夜雨聆风⭐63,308 | Python | MIT
📌 一句话速览
learn-claude-code是一个教你从零开始构建AI Agent Harness（「车辆」）的开源教程项目。它的核心理念是：AI的自主能力来自模型训练本身，而Agent产品需要的是一套让模型在特定环境中运行的基础设施——就像司机（模型）需要一辆车（Harness）才能上路。
🔍 这是什么
如果你关注AI Agent领域，你可能会发现一个有趣的现象：所有人都在谈论Agent的未来，但很少有人能说清楚Agent到底是怎么从代码层面构建出来的。Cursor、Claude Code、Devin这些产品看起来像魔法，但拆开来看，它们的底层架构遵循着相同的设计模式。
learn-claude-code就是为了填补这个认知空白而诞生的。这个项目由shareAI-lab团队创建，从2025年6月开源至今已获得63,308颗星标和10,344个Fork。它不是一个可以直接用的产品，而是一份从零到一的「造车说明书」。
项目开篇就抛出了一个核心洞察：「Agency——感知、推理和行动的能力——来自模型训练，而不是外部代码编排。」这句话看似简单，却揭示了当前Agent领域的根本性误解。很多人以为写好编排逻辑（ReAct、CoT）就能创造Agent，但事实上，模型的自主行为能力是在训练阶段通过海量梯度下降学到的，外部代码只是让这个能力得以施展的载体。
项目通过历史案例论证这一点：DeepMind的DQN在2013年仅凭原始像素和游戏分数就学会了7款Atari游戏；OpenAI Five通过45,000年的自我对弈掌握了Dota 2，击败了世界冠军OG；AlphaStar在StarCraft II中达到了Grandmaster段位——所有这些都不需要外部规则或策略脚本，模型通过训练学会了自主决策。
🏗️ 架构设计
learn-claude-code的教学架构分为三个核心层次：
模型层（The Driver）： 这是预训练的大语言模型，拥有通过训练获得的感知、推理和行动能力。项目强调，这一层不需要你构建——你只需要理解它的能力边界。
工具层（The Dashboard）： 这是Agent与外部世界交互的接口集合，包括文件操作、代码执行、网络请求、Shell命令等。每个工具都需要明确的输入输出规范和错误处理机制。
编排层（The Steering Wheel）： 这是将模型决策转化为工具调用的调度系统，包括上下文管理、多轮对话状态追踪、错误恢复和任务分解。项目用Python从零实现了这套系统，不依赖LangChain或任何现成框架。
用户指令
↓
编排层（消息循环 + 工具调度）
├──→ 模型推理（感知 + 决策）
├──→ 工具执行（行动）
└──→ 上下文更新（记忆）
↓
结果返回整个实现只有几百行Python代码，但涵盖了Agent Harness的所有核心组件：消息格式定义、工具注册表、流式输出处理、安全沙箱执行。
⚡ 核心功能
1. 从零实现的消息循环
# learn-claude-code的核心循环（简化版）
while True:
# 1. 将消息历史发送给模型
response = model.chat(messages)
# 2. 解析模型输出，判断是文本回复还是工具调用
if response.has_tool_call():
# 3. 执行工具
result = execute_tool(response.tool_call)
# 4. 将结果加入消息历史
messages.append({"role": "tool", "content": result})
else:
# 5. 纯文本回复，展示给用户
print(response.content)
break2. 工具注册与执行框架
项目提供了一个简洁的工具注册机制，让你可以轻松扩展Agent的能力。每个工具只需要定义名称、描述、参数Schema和执行函数，系统会自动处理参数验证和错误捕获。
3. 上下文管理策略
这是Agent工程中最容易被忽视但最关键的部分。项目教你如何管理上下文窗口——包括消息截断策略、关键信息保留机制、以及长对话中的记忆压缩方法。
4. 安全沙箱
代码执行在隔离的沙箱环境中运行，防止Agent执行恶意命令。项目展示了如何用Docker或subprocess构建基本的执行隔离。
⚔️ 竞品对比
| 维度 | learn-claude-code | LangChain | AutoGPT | Claude Code |
|---|---|---|---|---|
| 定位 | 教学教程 | 生产框架 | 全自动Agent | 商业产品 |
| 代码量 | ~500行 | ~50,000行 | ~10,000行 | 闭源 |
| 学习曲线 | 低（逐行讲解） | 中（文档庞大） | 中 | N/A |
| 生产就绪 | ❌ 教学用途 | ✅ | ⚠️ 有限 | ✅ |
| 核心价值 | 理解Agent原理 | 快速构建应用 | 自动化任务 | 即用型编程助手 |
| 适合人群 | 开发者/研究者 | 应用开发者 | 终端用户 | 程序员 |
🔧 快速上手
# 克隆仓库
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
# 安装依赖
pip install -r requirements.txt
# 运行最基础的Agent示例
python examples/01_basic_agent.py
# 逐步学习
# 01 - 基础消息循环
# 02 - 添加工具支持
# 03 - 上下文管理
# 04 - 错误处理与恢复
# 05 - 安全沙箱
# 06 - 多轮对话💡 编辑点评
learn-claude-code的价值不在于它能做什么，而在于它能教你理解什么。在Agent框架层出不穷的今天，理解底层原理比掌握某个框架的API更重要。这个项目用最少的代码揭示了Agent工程的核心模式，是每个想深入AI Agent领域的开发者的必读教材。
| 维度 | 评分 |
|---|---|
| 创新性 | ★★★★☆ |
| 实用性 | ★★★★★ |
| 文档质量 | ★★★★★ |
| 社区活跃度 | ★★★★★ |
| 推荐指数 | ★★★★★ |
— END —
免责声明：本文由AI辅助生成，仅供参考。
