# learn_claude_code

**Repository Path**: xzitluyang/learn_claude_code

## Basic Information

- **Project Name**: learn_claude_code
- **Description**: claude code核心原理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Learn Claude Code - - 真正的 Agent Harness 工程

## Agency 来自模型，Agent 产品 = 模型 + Harness

在讨论代码之前，先把一件事说清楚。

**Agency - - 感知、推理、行动的能力 - - 来自模型训练，而不是外部代码的编排。** 但一个能干活的 Agent 产品，模型和 Harness 缺一不可：模型是驾驶者，Harness 是载具。本仓库教你造载具。

### Agency 从哪来

Agent 的核心是一个神经网络 - - Transformer、RNN，一个被训练出来的函数 - - 经过数十亿次梯度更新，在行动序列数据上学会了感知环境、推理目标、采取行动。Agency 从来不是外面那层代码赋予的，而是模型在训练中学到的。

人类就是最好的例子：一个由数百万年进化"训练"出来的生物神经网络，通过感官感知世界，通过大脑推理，通过身体行动。当 DeepMind、OpenAI 或 Anthropic 谈论 "Agent" 时，他们说的核心都是同一件事：**一个通过训练学会了行动的模型，加上让它能在特定环境中工作的基础设施。**

历史已经写下铁证：

- **2013 年，DeepMind DQN 玩 Atari。** 一个神经网络，只接收原始像素和游戏分数，就学会了 7 款 Atari 2600 游戏 - - 超越此前所有算法，并在其中 3 款上击败人类专家。到 2015 年，同一架构扩展到 [49 款游戏，达到职业人类测试员水平](https://www.nature.com/articles/nature14236)，论文发表于 *Nature*。没有游戏专属规则，没有决策树，只有一个从经验中学习的模型。那个模型就是 Agent。

- **2019 年，OpenAI Five 征服 Dota 2。** 五个神经网络，在 10 个月内与自己对战了 [45,000 年的 Dota 2](https://openai.com/index/openai-five-defeats-dota-2-world-champions/)，随后在旧金山直播赛上 2-0 击败 TI8 世界冠军 **OG**。在之后的公开竞技场中，AI 在 42,729 场比赛中取得 99.4% 的胜率。没有脚本化策略，没有人工编排的团队协调逻辑 - - 模型完全通过自我对弈学会了团队协作、战术与实时应变。

- **2019 年，DeepMind AlphaStar 制霸星际争霸 II。** AlphaStar 先在闭门赛中 [10-1 击败职业选手](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/)，随后在欧洲服务器打上[宗师段位](https://www.nature.com/articles/d41586-019-03298-6) - - 跻身 90,000 名玩家中的前 0.15%。这是一款信息不完全、需要实时决策、组合动作空间远超国际象棋和围棋的游戏。Agent 是什么？是模型，是训练出来的，不是编出来的。

- **2019 年，腾讯绝悟统治王者荣耀。** 腾讯 AI Lab 的"绝悟"在 2019 年 8 月 2 日的世冠杯半决赛上[以 5v5 击败 KPL 职业选手](https://www.jiemian.com/article/3371171.html)；在 1v1 模式下，职业选手 [15 场仅胜 1 场，最多坚持不到 8 分钟](https://developer.aliyun.com/article/851058)。其训练强度相当于人类一天打 440 年。到 2021 年，绝悟在全英雄池 BO5 中已全面超越 KPL 职业选手水准。没有手工编写的英雄克制表，没有脚本化的阵容编排，只有一个从零开始、通过自我对弈学会整个游戏的模型。

- **2024-2025 年，LLM Agent 重塑软件工程。** Claude、GPT、Gemini - - 这些在人类全部代码与推理成果上训练出来的大语言模型 - - 被部署为编程 Agent：阅读代码库、编写实现、调试故障、团队协作。架构与此前的每一个 Agent 完全相同：一个训练好的模型，放进一个环境，配上感知和行动的工具。唯一的区别，是它们所学内容的规模和所解任务的通用性。

每一个里程碑都指向同一个事实：**Agency - - 感知、推理、行动的能力 - - 是训练出来的，不是编出来的。** 但每个 Agent 同时也需要一个环境才能工作：Atari 模拟器、Dota 2 客户端、星际争霸 II 引擎、IDE 和终端。模型提供智能，环境提供行动空间，两者合在一起才是一个完整的 Agent。

### Agent 不是什么

"Agent" 这个词，已经被一整条"提示词水管"产业劫持了。

拖拽式工作流构建器、无代码 "AI Agent" 平台、提示词链编排库 - - 它们共享同一个幻觉：以为把 LLM API 调用用 if-else 分支、节点图、硬编码路由逻辑串在一起，就算是"构建 Agent"了。

不是的。它们做出来的是鲁布·戈德堡机械：一条过度工程化、脆弱不堪的过程式规则流水线，LLM 被楔在其中，充当一个美化过的文本补全节点。那不是 Agent，那是一个有着宏大妄想的 shell 脚本。

**提示词水管工式的 "Agent"，是不做模型的人对智能的一厢情愿。** 他们试图通过堆叠过程式逻辑来暴力模拟智能 - - 庞大的规则树、节点图、链式提示词瀑布 - - 然后祈祷足够多的胶水代码能涌现出自主行为。不会的。你不可能通过工程手段"编"出 Agency，因为 Agency 是学出来的，不是编出来的。

这类系统从诞生之日起就已注定失败：脆弱、无法扩展、根本不具备泛化能力。它们是 GOFAI（Good Old-Fashioned AI，经典符号 AI）的现代还魂 - - 几十年前就被学界抛弃的符号规则系统，如今喷上一层 LLM 的漆重新登场。换了个包装，仍是同一条死路。

### 心智转换：从"开发 Agent"到"开发 Harness"

当一个人说"我在开发 Agent"时，他只可能是以下两种意思之一：

**1. 训练模型。** 通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重；收集任务过程数据 - - 真实领域中感知、推理、行动的实际序列 - - 用它们塑造模型的行为。这是 DeepMind、OpenAI、腾讯 AI Lab、Anthropic 在做的事，也是最本义的 Agent 开发。

**2. 构建 Harness。** 编写代码，为模型提供一个可操作的环境。这是我们大多数人在做的事，也是本仓库的核心。

Harness 是 Agent 在特定领域工作所需要的一切：

```
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

    Tools: 文件读写、Shell、网络、数据库、浏览器
    Knowledge: 产品文档、领域资料、API 规范、风格指南
    Observation: git diff、错误日志、浏览器状态、传感器数据
    Action: CLI 命令、API 调用、UI 交互
    Permissions: 沙箱隔离、审批流程、信任边界
```

模型做决策，Harness 执行；模型做推理，Harness 提供上下文。模型是驾驶者，Harness 是载具。

**编程 Agent 的 Harness，是它的 IDE、终端和文件系统。** 农业 Agent 的 Harness，是传感器阵列、灌溉控制和气象数据。酒店 Agent 的 Harness，是预订系统、客户沟通渠道和设施管理 API。Agent - - 那个智能、那个决策者 - - 永远是模型。Harness 因领域而变，Agent 跨领域泛化。

这个仓库教你造载具 - - 编程用的载具。但其中的设计模式可以泛化到任何领域：庄园管理、农田运营、酒店运作、工厂制造、物流调度、医疗保健、教育培训、科学研究。只要有任务需要被感知、推理和执行，Agent 就需要一个 Harness。

### Harness 工程师到底在做什么

如果你在读这个仓库，你很可能就是一名 Harness 工程师 - - 这是一个值得自豪的身份。你真正的工作是：

- **实现工具 - - 给 Agent 一双手。** 文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 Agent 在环境中可以采取的一个行动，设计时要原子化、可组合、描述清晰。

- **策划知识 - - 给 Agent 领域专长。** 产品文档、架构决策记录、风格指南、合规要求。按需加载（s07），而不是一次性全塞进上下文。Agent 应该知道有什么可用，然后自己拉取所需。

- **管理上下文 - - 给 Agent 干净的记忆。** 子 Agent 隔离（s06）防止噪声泄露，上下文压缩（s08）防止历史淹没，任务系统（s12）让目标在单次对话之外持续存在。

- **控制权限 - - 给 Agent 边界。** 沙箱化文件访问，对破坏性操作要求审批，在 Agent 与外部系统之间设立信任边界。这是安全工程与 Harness 工程的交汇点。

- **收集任务过程数据。** Agent 在你的 Harness 中执行的每一条行动序列都是训练信号；真实部署中的"感知 - 推理 - 行动"轨迹，是微调下一代 Agent 模型的原材料。你的 Harness 不仅服务于 Agent，还能帮助 Agent 进化。

你不是在编写智能，而是在构建智能栖居的世界。这个世界的质量 - - Agent 能看得多清楚、行动得多精准、可用知识有多丰富 - - 直接决定了智能能在多大程度上发挥出来。

**造好 Harness，Agent 会完成剩下的。**

### 为什么是 Claude Code：Harness 工程的大师课

为什么这个仓库专门拆解 Claude Code？

因为 Claude Code 是我们所见过的最优雅、最完整的 Agent Harness 实现。原因不在于某个巧妙的技巧，而在于它*没做*的事：它没有试图成为 Agent 本身，没有强加僵化的工作流，没有用精心设计的决策树替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 - - 然后让开了。

把 Claude Code 剥到本质来看：

```
Claude Code = 一个 Agent 循环
            + 工具 (bash, read, write, edit, glob, grep, browser...)
            + 按需 Skill 加载
            + 上下文压缩
            + 子 Agent 派生
            + 带依赖图的任务系统
            + 异步邮箱的团队协调
            + worktree 隔离的并行执行
            + 权限治理
```

就这些，这就是全部架构。每个组件都是 Harness 机制，都是为 Agent 构建的栖居世界的一部分。那 Agent 本身呢？是 Claude - - 一个模型，由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 并没有让 Claude 变聪明，Claude 本来就聪明；Harness 只是给了 Claude 双手、双眼和一个工作空间。

这正是 Claude Code 作为教学标本的意义：**它展示了当你信任模型、把工程精力集中在 Harness 上时会发生什么。** 本仓库的课程（s01-s20）会逐步拆解并重组 Claude Code 架构中的 Harness 机制。学完之后，你理解的不只是 Claude Code 如何工作，而是适用于任何领域、任何 Agent 的 Harness 工程通用原则。

启示不是"复制 Claude Code"，而是：**最好的 Agent 产品，出自那些明白自己的工作是 Harness 而非智能本身的工程师之手。**

---

## 愿景：用真正的 Agent 铺满宇宙

这不只关乎编程 Agent。

每一个人类从事复杂、多步骤、需要判断力的工作的领域，都是 Agent 可以运作的领域 - - 只要有对的 Harness。本仓库中的模式是通用的：

```
庄园管理 Agent = 模型 + 物业传感器 + 维护工具 + 租户通信
农业 Agent = 模型 + 土壤/气象数据 + 灌溉控制 + 作物知识
酒店运营 Agent = 模型 + 预订系统 + 客户渠道 + 设施 API
医学研究 Agent = 模型 + 文献检索 + 实验仪器 + 协议文档
制造业 Agent = 模型 + 产线传感器 + 质量控制 + 物流系统
教育 Agent = 模型 + 课程知识 + 学生进度 + 评估工具
```

循环永远不变，工具在变，知识在变，权限在变。Agent = 模型（LLM）+ 泛化的操作环境（Harness）。

每一位读这个仓库的 Harness 工程师，学到的都远超软件工程本身 - - 你在学习为一个智能的、自动化的未来构建基础设施。每一个部署在真实领域的好 Harness，都是 Agent 能够感知、推理、行动的又一块阵地。

先铺满工作室，然后是农田、医院、工厂，然后是城市，然后是星球。

**Bash is all you need. Real agents are all the universe needs.**

---

```
                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           / \
                         yes no
                          | |
                    execute tools return text
                    append results
                    loop back -----------------> messages[]

    这是最小循环，每个 AI Agent 都需要它。
    模型决定何时调用工具、何时停止，
    代码只是执行模型的要求。
    本仓库教你构建围绕这个循环的一切 - -
    让 Agent 在特定领域高效工作的 Harness。
```

**20 个递进式课程，从简单循环到完整 Harness。**
**每个课程添加一个 Harness 机制，每个机制配一句格言。**

> **s01**   *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个 Agent
>
> **s02**   *"加一个工具，只加一个 handler"* — 循环不用动，新工具注册进 dispatch map 就行
>
> **s03**   *"先划边界，再给自由"* — 先判断操作能不能做、要不要问用户
>
> **s04**   *"挂在循环上，不写进循环里"* — 在工具前后留插口，不改主循环也能扩展
>
> **s05**   *"没有计划的 Agent 走哪算哪"* — 先列步骤再动手，完成率翻倍
>
> **s06**   *"大任务拆小，每个小任务一个干净的上下文"* — 子 Agent 自己干活，只把结果带回来
>
> **s07**   *"用到时再加载，别全塞进 prompt"* — 技能先列目录，用到时再展开
>
> **s08**   *"上下文总会满，要有办法腾地方"* — 四层压缩策略，便宜的先跑、贵的后跑
>
> **s09**   *"记住该记的，忘掉该忘的"* — 三个子系统：筛选、提取、整理
>
> **s10**   *"prompt 是组装出来的，不是写死的"* — 分段 + 按需拼接
>
> **s11**   *"错误不是终点，是重试的起点"* — 出错时会重试、腾空间、换路子
>
> **s12**   *"大目标拆成小任务，排好序，持久化"* — 文件持久化的任务图，多 Agent 协作的基础
>
> **s13**   *"慢操作丢后台，Agent 继续思考"* — 后台线程跑命令，完成后注入通知
>
> **s14**   *"定时触发，不需要人推"* — 按时间自动触发任务
>
> **s15**   *"一个搞不定，组队来"* — 持久化队友 + 异步邮箱
>
> **s16**   *"队友之间要有约定"* — 用固定的请求 - 回复格式沟通
>
> **s17**   *"队友自己看板，有活就认领"* — 不需要领导逐个分配，自组织
>
> **s18**   *"各干各的目录，互不干扰"* — 任务管目标，worktree 管目录，按 ID 绑定
>
> **s19**   *"能力不够？插上 MCP"* — 把外部工具接进同一个工具池
>
> **s20**   *"机制很多，循环一个"* — 前面所有机制回归一个完整 Harness

---

## 核心模式

```python
def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant",
                         "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})
```

每个课程都在这个循环之上叠加一个 Harness 机制 - - 循环本身始终不变。循环属于 Agent，机制属于 Harness。

## 范围说明（重要）

本仓库是一个从 0 到 1 的 Harness 工程学习项目 - - 目标是构建围绕 Agent 模型的工作环境。为了保证学习路径清晰，仓库有意简化或省略了部分生产级机制：

- 完整的事件 / Hook 总线（例如 PreToolUse、SessionStart/End、ConfigChange）。s12 仅提供教学用途的最小 append-only 生命周期事件流。
- 基于规则的权限治理与信任流程。
- 会话生命周期控制（resume/fork），以及更完整的 worktree 生命周期控制。
- 完整的 MCP 运行时细节（transport/OAuth/资源订阅/轮询）。

仓库中的团队 JSONL 邮箱协议是教学实现，不代表任何特定生产系统的内部实现。

## 快速开始

### 20 章主线

```sh
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

python s01_agent_loop/code.py # 起点：一个循环 + bash
……
python s08_context_compact/code.py # 上下文压缩（复杂章）
python s20_comprehensive/code.py # 终点章：全部机制归于一个循环
```

## 学习路径

主线：能动手 → 能做复杂任务 → 能记住和恢复 → 能长期运行 → 能协作 → 能扩展并合体

```mermaid
flowchart TD
    %% 统一定义卡片样式：加入 text-align:left 保证列表不会居中乱飘
    classDef stage1 fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1,rx:12,ry:12,text-align:left
    classDef stage2 fill:#E8F5E9,stroke:#388E3C,stroke-width:2px,color:#1B5E20,rx:12,ry:12,text-align:left
    classDef stage3 fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#E65100,rx:12,ry:12,text-align:left
    classDef stage4 fill:#FCE4EC,stroke:#C2185b,stroke-width:2px,color:#880E4F,rx:12,ry:12,text-align:left
    classDef stage5 fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C,rx:12,ry:12,text-align:left
    classDef stage6 fill:#E0F7FA,stroke:#0097A7,stroke-width:2px,color:#006064,rx:12,ry:12,text-align:left

    %% 背景框样式
    classDef groupBox fill:#F8F9FA,stroke:#CED4DA,stroke-width:2px,stroke-dasharray: 5 5,rx:15,ry:15,color:#495057

    %% 第一层：1-3阶段
    subgraph Phase1 ["🌱 阶段 1-3：基础能力构建（从简单到复杂）"]
        direction LR
        S1["<b>第一阶段：让 Agent 能动手</b><br/>━━━━━━━━━━━━━<br/><b>s01 Agent Loop</b><br/>└─ 一个循环 + bash<br/><br/><b>s02 Tool Use</b><br/>└─ 单个到多个工具<br/><br/><b>s03 Permission</b><br/>└─ 判断能不能做<br/><br/><b>s04 Hooks</b><br/>└─ 工具前后留扩展插口"]:::stage1

        S2["<b>第二阶段：做复杂任务</b><br/>━━━━━━━━━━━━━<br/><b>s05 TodoWrite</b><br/>└─ 先列计划，再执行<br/><br/><b>s06 Subagent</b><br/>└─ 子节点干活带回结果<br/><br/><b>s08 Context Compact</b><br/>└─ 长上下文腾空间"]:::stage2

        S3["<b>第三阶段：记住和恢复</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ 该记记，该忘忘<br/><br/><b>s10 System Prompt</b><br/>└─ 运行时组装<br/><br/><b>s11 Error Recovery</b><br/>└─ 重试换路子"]:::stage3

        S1 ==> S2 ==> S3
    end

    %% 第二层：4-6阶段
    subgraph Phase2 ["🚀 阶段 4-6：高阶能力进化（长期、协作与融合）"]
        direction LR
        S4["<b>第四阶段：让任务长期运行</b><br/>━━━━━━━━━━━━━<br/><b>s12 Task System</b><br/>└─ 任务落盘记依赖<br/><br/><b>s13 Background Tasks</b><br/>└─ 慢操作丢后台<br/><br/><b>s14 Cron Scheduler</b><br/>└─ 按时自动触发"]:::stage4

        S5["<b>第五阶段：让多个 Agent 协作</b><br/>━━━━━━━━━━━━━<br/><b>s15 Agent Teams</b><br/>└─ 队友 + 邮箱通信<br/><br/><b>s16 Team Protocols</b><br/>└─ 固定收发格式<br/><br/><b>s17 Autonomous Agents</b><br/>└─ 自己看板认领活<br/><br/><b>s18 Worktree Isolation</b><br/>└─ 隔离目录"]:::stage5

        S6["<b>第六阶段：接外部能力合体</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ 技能按需展开<br/><br/><b>s19 MCP Plugin</b><br/>└─ 外部接进工具池<br/><br/><b>s20 Comprehensive Agent</b><br/>└─ 全机制回单循环"]:::stage6

        S4 ==> S5 ==> S6
    end

    %% 将两个模块连接起来，形成 Z 字形阅读流
    Phase1 ===> Phase2

    %% 应用背景样式
    class Phase1,Phase2 groupBox
```

## 全部章节

| 章节 | 主题 | 关键概念 |
|---|---|---|
| [s01](./s01_agent_loop/) | Agent Loop | `messages` / `while True` / `stop_reason` |
| [s02](./s02_tool_use/) | Tool Use | `TOOL_HANDLERS` / dispatch map / 并发 |
| [s03](./s03_permission/) | Permission | `PermissionRule` / 审批管线 |
| [s04](./s04_hooks/) | Hooks | `PreToolUse` / `PostToolUse` / 扩展点 |
| [s05](./s05_todo_write/) | TodoWrite | `TodoItem` / 先计划后执行 |
| [s06](./s06_subagent/) | Subagent | `fresh messages[]` / 上下文隔离 |
| [s07](./s07_skill_loading/) | Skill Loading | `SkillManifest` / 按需注入 |
| [s08](./s08_context_compact/) | Context Compact | snip / micro / budget / auto 四层压缩 |
| [s09](./s09_memory/) | Memory | selection / extraction / consolidation |
| [s10](./s10_system_prompt/) | System Prompt | 运行时组装 / 分段拼接 |
| [s11](./s11_error_recovery/) | Error Recovery | token 升级 / fallback 模型 / 重试策略 |
| [s12](./s12_task_system/) | Task System | `TaskRecord` / `blockedBy` / 磁盘持久化 |
| [s13](./s13_background_tasks/) | Background Tasks | 线程执行 / 通知队列 |
| [s14](./s14_cron_scheduler/) | Cron Scheduler | 持久化调度 / 会话级触发 |
| [s15](./s15_agent_teams/) | Agent Teams | `MessageBus` / 收件箱 / 权限冒泡 |
| [s16](./s16_team_protocols/) | Team Protocols | 关机握手 / 计划审批 |
| [s17](./s17_autonomous_agents/) | Autonomous Agents | 空闲循环 / 自动认领 |
| [s18](./s18_worktree_isolation/) | Worktree Isolation | `WorktreeRecord` / 任务-目录绑定 |
| [s19](./s19_mcp_plugin/) | MCP Plugin | 多传输 / 通道路由 / 工具池组装 |
| [s20](./s20_comprehensive/) | Comprehensive Agent | 全部机制归到一个循环 |

## 项目结构

```
learn-claude-code/
  s01_agent_loop/ # 每章一个文件夹
    README.md # 中文源文档（完整叙事）
    README.en.md # 英文译本
    README.ja.md # 日文译本
    code.py # 独立可运行代码
    images/ # SVG 流程图
  s02_tool_use/
  ...
  s19_mcp_plugin/
  s20_comprehensive/ # 终点章
  agents/ # 旧 12 章可运行副本 + s_full.py
  skills/ # s07 使用的 skill 文件
  docs/ # 旧 12 章文档，过渡期保留
  web/ # 当前仍基于 docs/ 旧版内容生成
  tests/
```

## 许可证

MIT

---

**Agency 来自模型，Harness 让 Agency 落地。造好 Harness，模型会完成剩下的。**

**Bash is all you need. Real agents are all the universe needs.**