English | 中文 | 日本語

学习 Claude 代码

这是一个面向希望从零开始构建高完成度编码助手的开发者的教学仓库。

本仓库并不试图完全复刻生产环境中的每一个细节，而是专注于那些真正决定一个代理能否高效运作的核心机制：

• 循环
• 工具
• 计划
• 委派
• 上下文控制
• 权限
• 钩子
• 内存
• 提示词组装
• 任务
• 团队
• 隔离执行通道
• 外部能力路由

目标很简单：

深入理解真正的设计核心，以便能够自行重建它。

本仓库真正教授的内容

先用一句话概括：

模型负责推理，而框架则为模型提供一个可工作的环境。

这个工作环境由几个相互协作的部分组成：

• Agent Loop：向模型提问、运行工具、追加结果并继续
• Tools：代理的“双手”
• Planning：一个小结构，用于防止多步任务偏离方向
• Context Management：保持活跃上下文的小巧与连贯
• Permissions：防止模型意图直接转化为不安全的操作
• Hooks：在不重写循环的情况下扩展其行为
• Memory：仅保留应跨会话持久化的事实
• Prompt Construction：根据稳定规则和运行时状态组装模型输入
• Tasks / Teams / Worktree / MCP：将单代理核心扩展为更大的工作平台

这是本仓库的教学承诺：

• 按照清晰的顺序讲解主线内容
• 在依赖某个概念之前先解释清楚它
• 紧贴实际系统结构
• 避免让学习者被无关的产品细节淹没

本仓库刻意不教授的内容

本仓库并不试图保留真实生产系统中可能存在的每一个细节。

如果某个细节并非代理核心运行模式的关键部分，则不应成为教学的重点。这包括：

• 打包与发布机制
• 跨平台兼容性层
• 企业策略集成
• 数据监控与账户配置
• 历史兼容分支
• 产品特有的命名问题

这些细节在生产环境中可能很重要，但它们并不属于从零开始学习路径的核心内容。

适合人群

假设读者具备以下基础：

• 掌握基本的 Python 知识
• 理解函数、类、列表和字典
• 可能对代理系统完全陌生

因此，仓库遵循几条明确的教学原则：

• 在使用某个概念之前先进行解释
• 将每个概念的完整说明集中在一处
• 从“是什么”开始，再到“为什么存在”，最后是“如何实现”
• 避免强迫初学者从零散的片段中拼凑整个系统

推荐阅读顺序

英文文档旨在独立成篇。章节顺序、桥接文档和机制图在不同语言版本中保持一致，因此你可以选择一种语言来跟随主要的学习路径。

• 概述：docs/en/s00-architecture-overview.md
• 代码阅读顺序：docs/en/s00f-code-reading-order.md
• 术语表：docs/en/glossary.md
• 教学范围：docs/en/teaching-scope.md
• 数据结构：docs/en/data-structures.md

如果你是第一次访问，从这里开始

请勿随意打开任意章节。

最安全的路径是：

1. 阅读 docs/en/s00-architecture-overview.md，了解整个系统的架构。
2. 阅读 docs/en/s00d-chapter-order-rationale.md，以便在深入机制细节之前理解章节顺序的意义。
3. 阅读 docs/en/s00f-code-reading-order.md，知道应该先打开哪些文件。
4. 按照四个阶段依次学习：s01-s06 -> s07-s11 -> s12-s14 -> s15-s19。
5. 每完成一个阶段后，停下来自己重建最小版本，然后再继续。

如果中间和后期的章节开始变得模糊不清，可以按以下顺序重新梳理：

1. docs/en/data-structures.md
2. docs/en/entity-map.md
3. 最接近你卡住章节的桥接文档
4. 然后再回到该章节的内容

Web 学习界面

如果你想以更直观的方式理解章节顺序、阶段边界以及章节之间的递进关系，可以运行内置的教学网站：

cd web
npm install
npm run dev

然后使用以下路由：

• /en：英语入口页面，用于选择阅读路径
• /en/timeline：最清晰的主线视图
• /en/layers：四阶段边界地图
• /en/compare：相邻步骤对比及跳转诊断

初次浏览时，建议从 timeline 开始。如果你已经进入中间阶段，且章节边界变得模糊，可以在深入源码之前先使用 layers 和 compare。

桥接文档

这些并非额外的主章节，而是帮助理解系统中间和后期部分的桥梁文档：

• 章节顺序 rationale：docs/en/s00d-chapter-order-rationale.md
• 代码阅读顺序：docs/en/s00f-code-reading-order.md
• 引用模块地图：docs/en/s00e-reference-module-map.md
• 查询控制平面：docs/en/s00a-query-control-plane.md
• 单次请求生命周期：docs/en/s00b-one-request-lifecycle.md
• 查询转换模型：docs/en/s00c-query-transition-model.md
• 工具控制平面：docs/en/s02a-tool-control-plane.md
• 工具执行运行时：docs/en/s02b-tool-execution-runtime.md
• 消息与提示词管道：docs/en/s10a-message-prompt-pipeline.md
• 运行时任务模型：docs/en/s13a-runtime-task-model.md
• MCP 能力层：docs/en/s19a-mcp-capability-layers.md
• 团队-任务-通道模型：docs/en/team-task-lane-model.md
• 实体映射：docs/en/entity-map.md

四个阶段

1. s01-s06：构建一个实用的单代理核心
2. s07-s11：添加安全性、扩展点、记忆、提示词组装和恢复功能
3. s12-s14：将临时会话计划转化为持久的运行时工作
4. s15-s19：转向团队、协议、自治、隔离执行以及外部能力路由

主要章节

章节	主题	你将学到什么
s00	架构概览	全局架构图、关键术语及学习顺序
s01	代理循环	最小可用的代理循环
s02	工具使用	稳定的工具调度层
s03	待办事项/规划	可视化的会话计划
s04	子代理	每个委派子任务拥有独立的上下文
s05	技能	仅在需要时加载专业知识
s06	上下文精简	保持活跃窗口的大小最小化
s07	权限系统	执行前的安全闸门
s08	钩子系统	循环周围的扩展点
s09	记忆系统	跨会话的持久化知识
s10	系统提示	基于章节的提示组装
s11	错误恢复	继续执行与重试分支
s12	任务系统	持久化的任务图
s13	后台任务	非阻塞式执行
s14	定时调度器	基于时间的触发机制
s15	代理团队	持久化的队友
s16	团队协议	共享的协调规则
s17	自主代理	自我申领与自我恢复
s18	工作树隔离	隔离的执行通道
s19	MCP & 插件	外部能力路由

快速开始

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env

然后在 .env 文件中配置 ANTHROPIC_API_KEY 或兼容的 API 端点，并运行：

python agents/s01_agent_loop.py
python agents/s18_worktree_task_isolation.py
python agents/s19_mcp_plugin.py
python agents/s_full.py

建议的学习顺序：

1. 先运行 s01，确保最小循环能够正常工作。
2. 阅读 s00，然后按 s01 -> s11 的顺序逐步学习。
3. 只有当单代理核心及其控制平面运行稳定后，再继续学习 s12 -> s19。
4. 最后阅读 s_full.py，此时各个机制已经单独理解清楚。

如何阅读每一章

为了更好地吸收内容，建议按照以下节奏进行阅读：

1. 如果没有该机制，会出现什么问题？
2. 新概念的具体含义是什么？
3. 最小且正确的实现是什么样子？
4. 状态实际存储在哪里？
5. 如何将其重新接入整个循环？
6. 哪些部分可以先完成，哪些可以稍后再处理？

在阅读过程中，不断问自己：

• “这是核心主线，还是只是次要细节？”
• “这个状态到底存储在哪里？”

如果仍有疑问，可以返回查阅：

• docs/en/teaching-scope.md
• docs/en/data-structures.md
• docs/en/entity-map.md

仓库结构

learn-claude-code/
├── agents/              # 每章对应的可运行 Python 参考实现
├── docs/zh/             # 中文主文档
├── docs/en/             # 英文文档
├── docs/ja/             # 日文文档
├── skills/              # `s05` 中使用的技能文件
├── web/                 # Web 教学平台
└── requirements.txt

语言版本情况

目前中文仍然是最权威的教学版本，也是进展最快的版本。

• zh: 审核最多、内容最完整。
• en: 主要章节及关键桥梁文档已发布。
• ja: 主要章节及关键桥梁文档已发布。

如果你想获得最全面、更新最频繁的讲解路径，请优先使用中文文档。

最终目标

完成本仓库的学习后，你应该能够清晰回答以下问题：

• 编程代理所需的最小状态是什么？
• 为什么 tool_result 是循环的核心？
• 何时应该使用子代理，而不是将更多内容塞入同一个上下文中？
• 权限、钩子、记忆、提示组装和任务分别解决了什么问题？
• 何时应将单代理系统扩展为任务、团队、工作树和 MCP？

如果你能够清晰回答这些问题，并自行构建类似的系统，那么本仓库就达到了它的目的。

learn-claude-code 快速上手指南

learn-claude-code 是一个教学型开源项目，旨在帮助开发者从零开始构建一个高完成度的代码智能体（Coding Agent）框架。它不追求复刻生产环境的所有细节，而是专注于讲解决定智能体能否高效工作的核心机制（如循环、工具、规划、上下文控制等）。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：Python 3.8+
• 包管理工具：pip
• API Key：你需要一个有效的 ANTHROPIC_API_KEY 或其他兼容的 LLM API 端点。

安装步骤

1. 克隆仓库 将项目代码下载到本地：

   git clone https://github.com/shareAI-lab/learn-claude-code
   cd learn-claude-code
   

2. 安装依赖 使用 pip 安装所需的 Python 库。 注：国内用户若遇到下载缓慢，可临时指定清华源加速：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

3. 配置环境变量 复制示例配置文件并填入你的 API Key：

   cp .env.example .env
   

   编辑 .env 文件，设置 ANTHROPIC_API_KEY：

   ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxx
   # 如果使用其他兼容端点，也可在此配置
   

基本使用

本项目通过一系列按顺序排列的 Python 脚本（s01 到 s19）来演示智能体的演进过程。建议按照以下顺序进行学习和运行：

1. 运行最小化智能体循环 (Hello World)

首先运行最基础的单智能体循环，验证环境配置是否正确：

python agents/s01_agent_loop.py

观察终端输出，确认模型能够接收指令并返回结果。

2. 按阶段深入学习

项目分为四个主要阶段，请依次阅读 docs/zh/ 下的中文文档并运行对应脚本：

• 阶段一 (核心构建): 构建可用的单智能体核心

  # 依次运行 s01 到 s06
  python agents/s02_tool_use.py
  python agents/s03_todo_planning.py
  # ... 直至 s06
  

• 阶段二 (安全与扩展): 添加权限、钩子、记忆和提示词组装

  # 依次运行 s07 到 s11
  python agents/s07_permission_system.py
  

• 阶段三 (任务持久化): 将会话规划转化为持久的运行时工作

  # 依次运行 s12 到 s14
  python agents/s12_task_system.py
  

• 阶段四 (团队协作与隔离): 引入团队、协议、自主性及隔离执行

  # 体验高级特性
  python agents/s18_worktree_task_isolation.py
  python agents/s19_mcp_plugin.py
  

3. 运行完整示例

当你理解了各个独立机制后，可以运行整合了所有功能的完整版本：

python agents/s_full.py

💡 学习建议

• 不要跳跃阅读：请先阅读 docs/zh/s00-architecture-overview.md 了解全局架构，再按照 s01 -> s19 的顺序逐个击破。
• 动手重构：每完成一个阶段，尝试自己手动重写该阶段的核心逻辑，以确保真正理解其设计原理。
• 可视化辅助：如果需要更直观的学习路径，可以启动内置的 Web 教学界面：

  cd web
  npm install
  npm run dev
  

  然后在浏览器访问 http://localhost:3000/zh (如果支持中文路由) 或 /en/timeline 查看章节演进图。