(1) 依赖与环境#

只需要 3 个第三方包：anthropic（调用 Claude API）、python-dotenv（加载 .env 里的 API key）、pyyaml（后续 session 用到）。

注意第 47 行的 os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)：当设置了 ANTHROPIC_BASE_URL（使用第三方兼容 API）时，删除从环境继承的 auth token，避免认证冲突。

这里需要补充一下 claude 请求格式与 oepnai 的不同。先看一下相同点吧，底层通信都是基于 HTTP 的RESTful API；数据交换格式都是 JSON；都抽象了基于 role（角色）和 content（内容）的对话历史数组模式（而不是文本补全）；都支持SSE协议来最大程度降低TTFB；原生支持函数调用（Function Calling / Tool Use）和多模态（视觉）输入。

关键区别就在一下几个点：

• O将system放在对话的第一个位置作为一个特殊角色，而C将system剥离数组，当成了一个顶级参数，与model、message同级。
• C严格遵循user和assistant交替出现的规则，O则相对宽容允许连续出现。
• 比较重要的一点，O在有工具调用的时候在 assistant 消息中返回 tool_calls 数组，提交工具执行结果时，需要新增一条角色为 tool 的消息，并通过 tool_call_id 与之前的调用关联；C调用工具时，内容（content）会变成一个数组，其中包含类型为 tool_use 的对象，提交工具结果时，需要新增一条角色为 user（注意是 user，而不是单独的 tool 角色）的消息，其内容为类型为 tool_result 的对象，并附带 tool_use_id。
• 鉴权模式，O是Bearer Token，C是自定义的，强制要求声明 API 版本。

来看一下标准带工具调用情况下两者的JSON差距，前面为O后面为C。首先是工具声明，前者嵌套更深严格区分function，后者结构更扁平，参数叫 input_schema：

1
"tools": [
2
  {
3
    "type": "function",
4
    "function": {
5
      "name": "get_weather",
6
      "description": "获取指定城市的天气",
7
      "parameters": {
8
        "type": "object",
9
        "properties": {
10
          "location": { "type": "string" }
11
        }
12
      }
13
    }
14
  }
15
]

1
"tools": [
2
  {
3
    "name": "get_weather",
4
    "description": "获取指定城市的天气",
5
    "input_schema": {
6
      "type": "object",
7
      "properties": {
8
        "location": { "type": "string" }
9
      }
10
    }
11
  }
12
]

然后是模型决定工具，这里有巨大差异，OpenAI 传回的是字符串格式的 JSON，需要你自己 json.loads()；而 Claude 直接传回了解析好的 JSON 对象：

1
{
2
  "role": "assistant",
3
  "content": null,
4
  "tool_calls": [
5
    {
6
      "id": "call_abc123",
7
      "type": "function",
8
      "function": {
9
        "name": "get_weather",
10
        "arguments": "{\"location\": \"Wuhan\"}"
11
      }
12
    }
13
  ]
14
}

1
{
2
  "role": "assistant",
3
  "content": [
4
    {
5
      "type": "text",
6
      "text": "好的，我来帮你查一下。"
7
    },
8
    {
9
      "type": "tool_use",
10
      "id": "toolu_xyz789",
11
      "name": "get_weather",
12
      "input": {
13
        "location": "Wuhan"
14
      }
15
    }
16
  ]
17
}

最终将工具执行结果返回模型的时候，前者必须新增一个专属的 role: "tool"，后者则是必须作为 role: "user" 消息发送，并在 content 数组里标记 tool_result（这也是两者要互相转化最麻烦的一点）：

如果要在底层打通两套接口，路由层需要重点处理：OpenAI 的 role: "tool" 必须被强制映射为 Claude 的 role: "user" + type: "tool_result" 结构。

(2) 系统提示词——赋予模型"身份"#

这行是整个 harness 的入口。os.getcwd() 被直接拼进字符串——模型收到的不是函数调用，而是当前目录的真实路径（如 /home/ubuntu/owen）。模型不知道自己在哪台机器上，它只知道 prompt 里写了这个路径，然后基于此"推理"应该执行什么命令。

权限从哪来？ 权限来自你运行 python agents/s01_agent_loop.py 时你自己的 shell。Python 进程继承了你的所有权限——能读写的文件、能执行的命令，和你在终端敲命令是一样的。

(3) 工具定义——模型唯一能"调用"的东西#

工具定义不是 Python 函数，只是一段 JSON Schema 描述。发给模型后，模型会输出类似这样的 JSON：

1
{
2
  "type": "tool_use",
3
  "name": "bash",
4
  "id": "toolu_01xxx",
5
  "input": {"command": "ls"}
6
}

模型只负责"说要做什么"。真正执行的是 harness。 模型产生意图，harness 赋予能力。

(4) 工具执行——run_bash#

关键点：

• subprocess.run(command, shell=True, cwd=os.getcwd()) — 模型输出的字符串被直接交给 shell 执行。这就是为什么 AI 可以操作文件：本质上和你自己在终端敲命令一样。
• 危险命令拦截 — 硬编码了 5 条关键词，在命令到达 subprocess 之前做简单过滤。这非常粗糙（比如 rm -rf ~/* 就绕过去了），真实的 Claude Code 有完整的权限系统和 hooks 机制。
• 输出截断 — out[:50000] 防止大量输出撑爆 token 预算（后面 s06 会专门处理上下文压缩）。
• 超时保护 — timeout=120，防止命令卡死。

(5) 核心循环——整个 s01 的灵魂#

流程图：

1
+--------+      +-------+      +---------+
2
|  User  | ---> |  LLM  | ---> |  Tool   |
3
| prompt |      |       |      | execute |
4
+--------+      +---+---+      +----+----+
5
                    ^                |
6
                    |   tool_result  |
7
                    +----------------+
8
                    (loop until stop_reason != "tool_use")

循环不变式：模型只要还在返回 stop_reason == "tool_use"，就把工具结果塞回 messages 再问一次；一旦返回 stop_reason == "end_turn"，循环终止。

一个设计细节：工具执行结果用 role: "user" 而不是 role: "tool" 返回。这是 Anthropic 消息协议的约定——工具结果被追加为 user role 的消息（因为它是"外部输入"，不是模型自己生成的）。

(6) 交互循环——REPL 外壳#

外层是一个简单的 while True REPL（Read-Eval-Print Loop）。history 在所有轮次中持续增长——上一次问题和模型的回答（含所有工具调用）都在里面，所以模型能"记住"上下文。

(7) macOS UTF-8 输入补丁#

macOS 默认用 libedit（而非 GNU readline），处理中文、日文等多字节字符时退格键可能只删半个字符导致乱码。这 6 行配置切换 libedit 的字符处理模式，让 UTF-8 输入正常。#143 引用对应的 GitHub issue/PR 编号。Linux 上 Python 自带 GNU readline，这段代码无害但不起作用。

(8) 运行#

1
cd learn-claude-code
2
python agents/s01_agent_loop.py

内置的测试 prompt：

• Create a file called hello.py that prints "Hello, World!"
• List all Python files in this directory
• What is the current git branch?
• Create a directory called test_output and write 3 files in it

(1) 路径沙箱——safe_path#

这是 s02 最重要的新增基础设施。s01 的 bash 对文件系统没有边界，cat ~/.ssh/id_rsa 也能执行。s02 给文件工具加了一道门：

三步检查：

1. WORKDIR / p — 把输入路径拼到工作目录下
2. .resolve() — 解析掉所有 .. 和符号链接，得到绝对路径
3. is_relative_to(WORKDIR) — 检查解析后的路径是否还在工作目录内

../../etc/passwd → resolve 后变成 /etc/passwd → 不在 /home/ubuntu/owen 下 → 抛异常。

但这个沙箱有一个大漏洞：它只保护了 read_file / write_file / edit_file，不保护 bash。 bash 工具直接走 subprocess.run(command, shell=True)，模型说 cat ~/.ssh/id_rsa.pub 就能读，说 cat /etc/passwd 也行。实际测试中，模型通过 bash 读到了 ~/.ssh/ 下的公钥——safe_path 在这里完全被绕过了。

这是故意留的设计张力：bash 给了模型最大灵活性，但也给了最大攻击面。后面 s06（权限系统）和 s12（worktree 隔离）会逐步解决这个问题。这里先记住一个原则：只要有不受限的 bash，任何文件级沙箱都有后门。

(2) 三个新工具的函数实现#

read_file — 读文件，支持行数限制：

比 cat 好在：可控行数、不会截断半个 UTF-8 字符、告知被截掉的行数。

write_file — 写文件，自动创建父目录：

mkdir(parents=True, exist_ok=True) 省去了先 mkdir -p 再写的两步操作。返回值直接给 LLM 看写入结果，形成闭环。

edit_file — 精确文本替换（这是 Claude Code 实际使用的方式，而非 sed/awk）：

注意 replace(old_text, new_text, 1) 中的 1——只替换第一次出现。因为如果 LLM 传了一个太短的 old_text（比如单个变量名），全量替换会改掉不该改的地方。真正的 Claude Code 的 Edit 工具也做单次替换，且要求 old_string 在文件中唯一，否则报错。

(3) 分发映射——Dispatch Map#

这是 s02 的架构亮点。工具名到处理函数的映射不用 if/elif 链，而用字典：

每个 lambda 做了同一件事：从模型返回的 kwargs 中提取自己需要的参数，传给具体函数。这是一种适配器模式——模型返回的是扁平的 {"path": "x", "content": "y"}，而每个函数要的参数名和数量不同。lambda 完成了"模型输出 → 函数签名"的映射。

后续 session 加新工具就是在这个字典里加一行，循环完全不用动。

一个容易忽略的点：TOOL_HANDLERS 和 TOOLS 是两个不同的东西。

s01 没有这个分离——只有一个 TOOLS，执行是硬编码的。s02 引入 dispatch map 时就把二者拆开了，s03 只是照惯例各加了一行。这个分离是 harness 设计的核心模式：给模型看的和本地执行的是两套东西，用名字做桥接。

(4) 循环中的分发调用#

对比 s01 和 s02 的循环体变化：

TOOL_HANDLERS.get(block.name) 一次查找替代了 s01 的硬编码。如果模型幻觉了一个不存在的工具名，返回 "Unknown tool" 让模型自行纠正。

(5) 工具定义——JSON Schema 数组#

每个工具都是自描述的——模型看 description 知道什么时候用它，看 input_schema 知道它需要什么参数。这个数组就是模型和真实世界的唯一接口。

(6) s01 → s02 变化总结#

(7) 运行#

1
python agents/s02_tool_use.py

推荐测试 prompt：

• Read the file requirements.txt
• Create a file called greet.py with a greet(name) function
• Edit greet.py to add a docstring to the function
• Read greet.py to verify the edit worked

(1) TodoManager——有状态的待办管理器#

这是 s03 的核心数据结构。之前的工具函数都是无状态的（读就是读、写就是写），而 TodoManager 是一个 Python 对象，在会话期间保持状态：

update() 做了严格的输入校验：

• 数量限制 — 最多 20 条，防止模型滥写
• 状态白名单 — 只能是 pending / in_progress / completed 三选一
• 唯一 in_progress — 同时只能有一个任务在做。这条规则很关键——它强制模型保持顺序聚焦，不能同时开三个坑
• 必填 text — 空任务没有意义

render() 把结构化数据转成模型能读懂的文本：

1
[ ] #1: Fix authentication bug
2
[>] #2: Add dark mode toggle        ← 当前正在做
3
[ ] #3: Write tests
4
[x] #4: Update README
5

6
(1/4 completed)

模型通过工具结果看到这段渲染文本，就跟自己写了一张便签一样。

(2) todo 工具——模型自己写、自己更新#

todo 工具的定义：

值得注意的是：这个工具 没有读能力。模型不能查询"我现在的 todos 是什么"，它只能写。那模型怎么知道当前状态？看上次 todo 工具返回的 render 结果。这引出了一个设计取舍——这里的 todo 状态在 harness（Python 内存），模型只能通过工具返回值"看到"它。真正的 Claude Code 会把状态持久化到文件（s07 会做）。

(3) Nag Reminder——harness 的催促机制#

模型有时会忘了更新 todo。s03 的解法很粗暴也很有效：数轮次，到阈值就催。

逻辑很清晰：

1
本轮调了 todo → rounds_since_todo = 0
2
本轮没调    → rounds_since_todo += 1
3
≥ 3         → 在 tool_results 中追加一条文本提醒

<reminder> 被作为 type: "text" 注入到 user 消息的 content 数组里。模型看到这条消息，就相当于 harness 拍了拍它的肩膀说"你该更新计划了"。

这和真实的 Claude Code 一致——你有时会看到系统注入的 <system-reminder> 标签，做的就是同样的事情。

(4) 为什么这个设计有效#

核心在于三点：

1. 状态在 harness，不在 prompt — 如果让模型"在脑子里记"，对话一长就忘。而 todo 列表是 Python 对象，render 结果每次作为工具返回值重新注入，模型相当于不停地看便签。
2. 唯一 in_progress — 物理上不可并行，模型一次只干一件事。
3. Nag 是压力，不是命令 — harness 不规定模型做哪一步、怎么做，它只提醒"你该更新计划了"。规划权还在模型手里。

这也是 harness 哲学的体现：harness 提供结构（todo 状态机），模型填充内容（具体做什么）。

(5) s02 → s03 变化总结#

(6) 运行#

1
python agents/s03_todo_write.py

推荐测试 prompt（故意给多步任务，观察它是否先列 todo 再动手）：

• Refactor the file hello.py: add type hints, docstrings, and a main guard
• Create a Python package with __init__.py, utils.py, and tests/test_utils.py
• Review all Python files and fix any style issues

(1) 两套工具、两套身份#

s04 首次出现了工具的分级——父和子看到的工具不同：

系统提示词也分开了：

父是"主管"——会派活；子是"执行者"——只干事，汇报。

(2) run_subagent——独立循环 + 上下文丢弃#

关键设计点：

• sub_messages 从空开始 — 子 Agent 看不到父对话历史，就像一个新开的 session。它不是 fork，是 fresh。
• for _ in range(30) — 安全兜底，防止子 Agent 陷入死循环。最多 30 个 API 轮次，必须产出结论。
• 函数返回时 sub_messages 直接丢掉 — 这是 Python 的 GC 行为：函数退出，局部变量销毁。子 Agent 可能读了 10 个文件、跑了 20 个 bash 命令，但这些上下文不会回到父级。父收到的就是一段摘要文本。
• 共享文件系统，不共享聊天记录 — 子 Agent 对工作目录的修改会持久化（因为文件系统是共享的），但对话上下文完全隔离。

(3) 父 loop 中的 task 调度#

注意这里是同步执行——父 Agent 派发 task 后会阻塞等待子 Agent 完成。它不是启动一个后台线程，也没有并发。run_subagent(prompt) 返回之前，父 loop 停在那。s08 会把这种模式升级为后台任务。

(4) 为什么不允许递归生成#

子 Agent 的 CHILD_TOOLS 里没有 task 工具。这是刻意的：

1
父 → task → 子 → task → 孙子 → task → ... 爆炸

没有 task 工具，子 Agent 就不知道"派子 Agent"这件事存在。它的 system prompt 只让它"完成给定的任务然后总结"，它的 JSON Schema 里没有 task。这就是工具层面的权限分级——不是你告诉子 Agent "别递归"，而是它物理上就没有这个能力。

(5) 这个模式的应用场景#

s04 的模式最适合两类子任务：

1. 探索/搜索类 — "找一下这个项目的测试框架是什么"、"列出所有用了 requests 库的文件"、"检查 auth 模块是怎么处理 token 的"。这类任务需要读很多文件但只需要一个简短结论。
2. 生成/创建类 — "创建一个 utils.py，包含 safe_filename() 和 hash_cache_key() 两个函数"、"写一个数据库迁移脚本"。子 Agent 写文件，父 Agent 看到结果。

不适合的场景：需要和用户持续交互的任务（子 Agent 没有 input，看不到外部对话）。

(6) s03 → s04 变化总结#

(7) 运行#

1
python agents/s04_subagent.py

推荐测试 prompt：

• Use a subtask to find what testing framework this project uses
• Delegate: read all .py files and summarize what each one does
• Use a task to create a new module, then verify it from here

启动后观察一个细节：父对话历史始终很短，而子 Agent 的内部循环你看不到（没有 print 它的每次工具调用）。你只收到子 Agent 的最终总结。

(1) Skill 的文件格式——YAML frontmatter + Markdown 正文#

每个 skill 是 skills/<name>/SKILL.md 目录结构：

1
skills/
2
  agent-builder/
3
    SKILL.md          # YAML 头部 + Markdown 指导内容
4
  code-review/
5
    SKILL.md
6
  mcp-builder/
7
    SKILL.md
8
  pdf/
9
    SKILL.md

SKILL.md 用前端常见的 frontmatter 格式分隔元数据和正文：

1
---
2
name: pdf
3
description: Process PDF files - extract text, merge, split, and convert
4
tags: [document]
5
---
6

7
# PDF Processing
8

9
## Reading PDFs
10
Use `pdftotext` (from poppler-utils) to extract text...
11

12
## Creating PDFs
13
...

前面的 YAML 块是元数据（便宜，塞进 system prompt），后面是操作指南（贵，仅在加载时取出）。

(2) SkillLoader——扫描、解析、两层供给#

rglob("SKILL.md") 递归扫描，你只需创建目录和文件，SkillLoader 自动发现。_parse_frontmatter 用正则 ^---\n(.*?)\n---\n(.*) 拆出 YAML 头和后边的 Markdown。

两层供给方法：

(3) system prompt 中只放名字#

最终生成的 system prompt 大概长这样：

1
You are a coding agent at /home/ubuntu/owen.
2
Use load_skill to access specialized knowledge before tackling unfamiliar topics.
3

4
Skills available:
5
  - agent-builder: Build custom AI agents using best practices [agent]
6
  - code-review: Review code for quality, security, and performance [code]
7
  - mcp-builder: Build MCP servers that integrate with Claude [mcp]
8
  - pdf: Process PDF files - extract text, merge, split, and convert

每个 skill 只占 ~100 token（名字 + 一句话描述），而不是完整 2000 token 的操作指南。

(4) load_skill 工具——模型需要时自己调#

模型收到任务后，如果觉得需要某个领域的知识，会先调 load_skill("code-review")，harness 把完整的代码审查指南作为 tool_result 注入当前轮次。然后模型基于刚加载的操作指南工作。

(5) 为什么走 tool_result 而不是 system prompt？#

这是 s05 最重要的设计选择。

如果走 system prompt：

1
模型需要 skill → 修改 system → 重新发请求，翻倍 API 调用

如果走 tool_result：

1
模型调 load_skill → skill 内容作为 tool_result 进入 messages → 下一轮模型已看到

走 tool_result 的好处：

• 不打断循环 — 就是一次普通工具调用，和其他工具行为一致
• 只在需要时出现 — pdf skill 的 2000 行内容不会出现在一个纯代码任务里
• 和对话上下文一起在 messages 里 — 模型能自然引用，不会像 system prompt 那样离对话历史太远
• 和其他工具结果一样被压缩/截断 — 后续 s06 的上下文压缩对 skill 内容一视同仁

(6) 和 prompt engineering 的区别#

这个模式不是"写更好的 prompt"，而是把知识变成可被 Agent 自己调用的资源。

skill 文件是数据不是代码——新增一个 skill 就是 mkdir + touch SKILL.md + 写 YAML，不用改 Python。

(6.5) 一个常见误解：pdf skill 能"处理 PDF"吗？#

初学者看到项目里有 skills/pdf/SKILL.md，直觉反应是"PDF 处理非常复杂（解析字体、渲染引擎、字符编码……），一个 skill 文件怎么可能搞定？"

实际上，看看 skills/pdf/SKILL.md 里写了什么：

1
## Reading PDFs
2
# 推荐用 pdftotext 或 pymupdf
3
pdftotext input.pdf -
4
# 或者
5
python3 -c "import fitz; doc = fitz.open('input.pdf'); ..."
6

7
## Creating PDFs
8
# 推荐用 pandoc (从 Markdown 生成)
9
pandoc input.md -o output.pdf
10
# 或者用 reportlab 编程生成
11

12
## Key Libraries
13
| Task | Library | Install |
14
|------|---------|---------|
15
| Read/Write/Merge | PyMuPDF | pip install pymupdf |
16
| Create from scratch | ReportLab | pip install reportlab |

skill 不是 PDF 处理引擎，它是一份操作指南/小抄。 里面写了三样东西：

1. bash 命令 — pdftotext、pandoc、wkhtmltopdf
2. Python 代码片段 — 标准库/三方库的调用模板
3. 推荐库对照表 — 什么场景用什么库、怎么安装

模型收到这个 skill 后，和之前做的事情完全一样：调 bash 工具去执行这些命令。 如果 pdftotext 没装，模型会先 pip install pymupdf 再试 Python 方案。如果 pandoc 没装，模型会切到 reportlab。

所以 pdf skill 的本质是领域知识注入——不是给 Agent 新能力，而是告诉它"处理 PDF 用这些工具就够了，别绕远路"。模型本身已经会写代码、会调 bash、会读报错后修正，skill 只是把 PDF 场景的最佳路径预先告诉它。

可以这样理解：skill 相当于一个资深同事给你留的便利贴，上面写着"用 pymupdf 别用 pdfplumber，后者太慢"。便利贴没有给你新能力，但它让你做决策更快更准。

这个机制的好处是：新增领域支持的成本极低。你不需要写"PDF 解析器"、"PDF 渲染器"——你把 Python 生态里已有的工具（pymupdf、pdftotext、pandoc）组织成一份指南，模型自己会按指南去调用它们。模型的通用能力 + skill 的领域路径 = 领域专家行为。

(7) s04 → s05 变化总结#

(8) 运行#

1
python agents/s05_skill_loading.py

推荐测试 prompt：

• What skills are available?
• Load the agent-builder skill and follow its instructions
• I need to do a code review -- load the relevant skill first

Layer 1：micro_compact——沉默的清扫工#

每次 API 调用前自动运行，安静无感。策略很简单——旧工具结果替换为占位符：

关键设计决策：

• 保留最近 3 个 — 当前在做的事需要完整上下文，不压缩
• read_file 永久保留 — 文件内容是参考材料，压缩后模型会忘了文件内容然后重读，反而不划算
• 替换而不是删除 — 结构保留（tool_result 对象还在），只是内容变成占位符。模型能看到"我之前调过 bash"，但看不到 bash 的完整输出。这种"知道发生了什么但忘了细节"的状态，和人类记忆很像
• 长度 >100 的才压缩 — 短结果（比如 "Wrote 50 bytes"）不值得替换

Layer 2：auto_compact——"我记不住了，帮我总结一下"#

当 token 估算超过阈值（50000），触发自动压缩。用 LLM 总结 LLM 的对话：

几个细节值得注意：

• transcript_{timestamp}.jsonl — 完整对话存盘到 .transcripts/，以便后续 debug 或审查。信息没有丢失，只是移出了活跃上下文。
• [-80000:] — 取对话尾部分给 LLM 做总结。因为最近的对话最重要，旧的对话可能在之前的压缩中已经被总结过了。
• 不带 tools 的 API 调用 — 这是 s06 中唯一一次不带 tools 参数的调用。总结这件事不需要工具，模型只输出一段纯文本。

Layer 3：compact 工具——模型主动请求压缩#

模型调用 compact 工具后，循环中检测到 manual_compact = True，同样调用 auto_compact()。focus 参数目前只是定义中的占位，实际只返回字符串 "Compressing..."——真正的压缩逻辑和 Layer 2 共享同一个 auto_compact 函数。

三层在循环中的位置#

三层金字塔的总结#

1
层 1: micro_compact  ─  每轮、轻量、自动    ─  旧 tool_result → 占位符
2
层 2: auto_compact   ─  超 50000 token 触发  ─  全量对话 → LLM 总结
3
层 3: compact 工具   ─  模型主动调用        ─  同层 2，手动触发

三层是递进关系：层 1 是日常清理，拖慢膨胀速度；层 2 是安全阀，防止越过 API 限制；层 3 是给模型的自主权，它可以在任务阶段切换时主动清空上下文。

s05 → s06 变化总结#

运行#

1
python agents/s06_context_compact.py

推荐测试 prompt（故意制造大量工具调用观察压缩）：

• Read every Python file in the agents/ directory one by one — 观察 micro-compact 逐步替换旧结果
• Keep reading files until compression triggers automatically — 触发 auto_compact
• Use the compact tool to manually compress the conversation — 手动触发

(1) 磁盘上的任务图#

1
.tasks/
2
  task_1.json  {"id":1, "subject":"Set up project", "status":"completed"}
3
  task_2.json  {"id":2, "subject":"Write code", "blockedBy":[1], "status":"pending"}
4
  task_3.json  {"id":3, "subject":"Write tests", "blockedBy":[1], "status":"pending"}
5
  task_4.json  {"id":4, "subject":"Run CI", "blockedBy":[2,3], "status":"pending"}

对应的有向图：

1
               +----------+
2
          +--> | task 2   | --+
3
          |    | pending  |   |
4
+----------+  +----------+    +--> +----------+
5
| task 1   |                         | task 4   |
6
| completed| --> +----------+   +--> | blocked  |
7
+----------+     | task 3   | --+    +----------+
8
                 | pending  |
9
                 +----------+
10

11
顺序:  task 1 必须先完成, 才能开始 2 和 3
12
并行:  task 2 和 3 可以同时执行
13
依赖:  task 4 要等 2 和 3 都完成

这个语义非常清晰：什么能做（pending 且 blockedBy 为空）、什么被卡住（blockedBy 里还有未完成的 ID）、什么做完了（completed）。

(2) TaskManager——CRUD + 依赖传播#

s07 是第二个用到文件系统持久化的 session（第一个是 s06 的 .transcripts/）。_next_id 从已有文件中读取最大值 +1——进程重启后 ID 不冲突。注意它不是靠全局计数器或者自增序列，而是 glob("task_*.json") 扫描磁盘，文件系统本身就是状态存储。

create 方法：

owner 字段现在是空字符串——这将来在 s09-s11 的 Agent 团队中会用到，标记任务属于哪个 Agent。

(3) 依赖传播——完成即解锁#

这是 s07 最精巧的机制。当任务完成时，自动从所有其他任务的 blockedBy 中移除已完成的任务 ID：

这里有一个重要的设计：_clear_dependency 扫描全部任务文件，而不是被完成的那个任务自己反查。这样可以安全处理"任务 A 被任务 B、C、D 共同依赖"的情况——A 完成那一刻，B、C、D 的 blockedBy 都被清理。

此外，add_blocked_by 用 list(set(...)) 去重，防止同一个依赖被加两次。

(4) 四个 task 工具#

四个工具的职责很明确：增、改、列、查。注意没有删除——任务完成了就是标记为 completed，留下痕迹。

(5) s03 TodoWrite vs s07 TaskManager 对比#

(6) 为什么是"第二个关键枢纽"#

s07 在整个 12 个 session 序列中处于中点位置（s01-s06 | s07-s12），文档特别用 | 分隔。这不是偶然的——s07 是一切合作的骨架：

• s08 的后台线程读取任务列表，自动认领 pending 任务
• s09-s10 的 Agent 团队通过 owner 字段协商任务分配
• s12 的 worktree 隔离用任务 ID 绑定工作目录

任务图是"被动的数据"，但它解耦了生产者和消费者——Agent A 创建任务，Agent B 执行任务，它们不需要直接通信，只需要读写同一个 .tasks/ 目录。

(7) s06 → s07 变化总结#

(8) 运行#

1
python agents/s07_task_system.py

推荐测试 prompt：

• Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.
• List all tasks and show the dependency graph
• Complete task 1 and then list tasks to see task 2 unblocked
• Create a task board for refactoring: parse → transform → emit → test, where transform and emit can run in parallel after parse

试试关掉进程再重开，调用 task_list——任务还在磁盘上。

(1) BackgroundManager——线程池的朴素版#

不是线程池——就是 threading.Thread 每次新建一个线程。daemon 线程，主进程退出时自动终止。

(2) run()——启动即返回#

关键：函数立即返回，模型看到一个 task_id，可以接着干别的事。和 s04 的 run_subagent 完全不同——那个是同步阻塞直到子 Agent 完成。

(3) _execute()——线程内的 subprocess#

和 run_bash 几乎一样——subprocess.run + 超时 + 截断。区别只有两个：

• timeout 从 120s 变成 300s — 后台任务预期是长任务，给了更长的超时
• 结果推入通知队列而不是直接返回 — 线程不能直接往 messages 里写，所以走队列

(4) drain_notifications()——循环中唯一的线程交汇点#

drain_notifications 是一次性操作——取走所有待通知，清空队列。这保证了每条通知只被注入一次。

(5) 循环注入——LLM 调用前的"收件箱检查"#

模型的核心循环是单线程的——只有 subprocess 在后台线程跑，agent loop 本身不并发。流程是：

1
Round N:   模型调 background_run("npm install") → 拿到 task_id
2
Round N+1: 模型干别的事（比如 background_run("pip install") 或 read_file）
3
Round N+2: drain_notifications() 发现 npm 跑完了 → 作为 <background-results> 注入
4
           模型看到结果，决定下一步

这不叫 agent 并发思考，这叫 I/O 并行 + Agent 顺序执行。Agent 本身还是单线程地一轮轮走，只是等待 I/O 的时间被利用了。

(6) 工具定义#

注意 check_background 的 task_id 不是 required——省略时列出所有任务。模型可以不知道自己 spawn 了哪些任务，调一次 check_background() 就能看到全局。

(7) s07 → s08 变化总结#

(8) 运行#

1
python agents/s08_background_tasks.py

推荐测试 prompt：

• Run "sleep 5 && echo done" in the background, then create a file while it runs
• Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.

(1) s04 Subagent vs s09 Teammate#

1
Subagent (s04):   spawn → execute → return summary → destroyed
2
Teammate (s09):   spawn → working → idle → working → ... → shutdown

s04 的子 Agent 像函数调用——传参、执行、返回、清理。s09 的队友像员工——有名字 "alice"，有角色 "coder"，有生命周期 working → idle → working → idle，可以反复复派任务。

(2) 目录结构#

1
.team/
2
  config.json              # 团队名册 + 各成员状态
3
  inbox/
4
    alice.jsonl            # alice 的收件箱（append-only）
5
    bob.jsonl              # bob 的收件箱
6
    lead.jsonl             # 领导的收件箱

(3) TeammateManager——队友生命周期#

config.json 每次更新都 _save_config() 写回磁盘。进程重启后队员名册还在。

spawn() 方法：

如果同名队友处于 idle 状态，就唤醒它并给新 prompt；如果是新名字，创建并启动线程。这实现了"队友复用"——不需要每次都创建新 Agent。

(4) MessageBus——文件级通信协议#

这是 s09 最核心的发明。JSONL 文件做邮箱：

关键设计：读即清空。read_inbox → 读所有行 → write_text("") 删文件。每条消息只被消费一次，不会重复处理。

5 种消息类型（定义了但 s09 只用到前 2 种，后 3 种留给 s10）：

还有 broadcast 方法，遍历所有队友逐个发：

(5) 队友的 agent loop——缩水但完整的版本#

每个队友在自己的线程里跑：

注意队友的 sys_prompt 和 Leader 不同——队友被告知自己的名字和角色，被要求"完成你的任务"，Leader 则被告知"你是团队领导，派发任务"。

(6) 领导（Lead）的循环——收件箱注入#

领导和队友的通信模式是对称的——都走 BUS.read_inbox，都通过 JSONL 文件交换消息。领导给 alice 发消息 → alice.jsonl 新增一行 → alice 下轮 read_inbox 读到 → 清空。

(7) 九工具全貌#

Leader 有 9 个工具：

Leader 有 bash/edit 等完整能力（它可以亲自干活），也有团队管理能力。队友只有 6 个工具——没有 spawn_teammate / list_teammates / broadcast（防止递归管理）。

(7.5) 什么时候用哪种模式？#

到 s09 为止，我们已经有了三种 Agent 协作模式。怎么选？代码没有显式写决策逻辑，但从设计意图可以看出一个判断框架：

决策逻辑模型（LLM 自己判断）：

模型看到任务后，会基于自己的判断决定调哪个工具：

• 需要自己查文件但不想污染对话 → 调 task 工具 spawn 一个子 Agent
• 任务可以分给不同角色并行 → 调 spawn_teammate 创建队友
• 简单的读/写/改 → 直接用 bash / read_file / write_file / edit_file

harness 不替模型做这个决策。它只是把三种工具都提供出来，让模型自己判断场景。这和之前的原则一致——模型拥有判断权，harness 拥有执行权。

值得一提的是：这些模式不是互斥的。Leader 可以 spawn 一个 teammate（alice），alice 在处理任务时也可以在自己的 loop 里用 bash/read/write——团队模式是单 Agent 模式的超集，团队里的每个成员本质上还是一个独立 Agent。

(8) s08 → s09 变化总结#

(9) 运行#

1
python agents/s09_agent_teams.py

内置命令（非 LLM 路径）：

• /team — 直接查看 .team/config.json 中的团队名册
• /inbox — 直接查看 lead 的收件箱

推荐测试 prompt：

• Spawn alice (coder) and bob (tester). Have alice send bob a message.
• Broadcast "status update: phase 1 complete" to all teammates

(1) 统一的 FSM——一个模式，两个场景#

1
Shutdown Protocol                  Plan Approval Protocol
2
==================                 ======================
3
Lead             Teammate           Teammate           Lead
4
  |                 |                 |                 |
5
  |--shutdown_req-->|                 |--plan_req------>|
6
  | {req_id:"abc"}  |                 | {req_id:"xyz"}  |
7
  |                 |                 |                 |
8
  |<--shutdown_resp-|                 |<--plan_resp-----|
9
  | {req_id:"abc",  |                 | {req_id:"xyz",  |
10
  |  approve:true}  |                 |  approve:true}  |
11

12
共享状态机:  [pending] ──approve──> [approved]
13
            [pending] ──reject───> [rejected]

两个场景方向不同但结构完全一样：一方发带唯一 ID 的请求，另一方引用同一 ID 响应。

(2) 请求追踪器——全局状态#

这两个全局 dict 在 s09 的基础上加了一层状态可观测性——s09 发完消息就完了，不知道对方处理了没有。s10 通过 request_id 可以查到每笔请求的状态。

(3) 关机协议——"请停下手里的活"#

Leader 发起：

队友收到后，在 _exec 中处理：

队友的 loop 中检测自己的 shutdown_response 是否被批准：

注意这里有一个微妙的设计：队友不是被 Leader 直接关掉的。 Leader 发请求 → 队友自己决定 approve/reject → 如果 approve，队友自己的 loop 检测到并退出。是"请求退出"不是"强制终止"。

(4) 计划审批——"干之前先让我看一眼"#

方向上和关机相反——是队友向 Leader 提审批：

Leader 审查：

这里的 feedback 参数允许 Leader 附加说明："计划可以，但别动数据库迁移部分"。

(5) 工具膨胀——12 个工具#

从 s09 的 9 个涨到 12 个。注意 shutdown_request 和 shutdown_response Leader 和队友都有，但用途不同——Leader 用 shutdown_request 发请求，用 shutdown_response 查状态；队友用 shutdown_request 收请求，用 shutdown_response 回响应。同名工具在不同角色的 context 里含义不同。

(6) s09 → s10 变化总结#

(7) 运行#

1
python agents/s10_team_protocols.py

推荐测试 prompt：

• Spawn alice as a coder. Then request her shutdown.
• List teammates to see alice's status after shutdown approval
• Spawn bob with a risky refactoring task. Review and reject his plan.

(1) WORK → IDLE → WORK 循环#

s11 把队友的 loop 从线性改成了状态机：

1
+-------+
2
| spawn |
3
+---+---+
4
    |
5
    v
6
+-------+   tool_use     +-------+
7
| WORK  | <------------- |  LLM  |
8
+---+---+                +-------+
9
    |
10
    | stop_reason != tool_use 或调用了 idle 工具
11
    v
12
+--------+
13
|  IDLE  |  每 5 秒轮询，最多 60 秒
14
+---+----+
15
    |
16
    +---> check inbox → 有新消息? → 回到 WORK
17
    |
18
    +---> scan .tasks/ → 有未认领? → claim → 回到 WORK
19
    |
20
    +---> 60s 超时 → SHUTDOWN

(2) 任务看板扫描——scan_unclaimed_tasks#

三个条件：pending 状态 + owner 为空 + blockedBy 为空。被阻塞的任务不会被认领——这保证了依赖顺序。

(3) 任务认领——claim_task#

_claim_lock 是关键——防止竞态条件。alice 和 bob 都在 IDLE 状态同时扫描，同时看到 task_3 未认领，同时尝试认领。_claim_lock 保证只有一个成功，另一个收到 "Error: already claimed"。

注意这里用的是锁 + 文件重读，而不是 compare-and-swap。这是安全的——因为 Python 线程虽然有 GIL，但文件 I/O 释放 GIL，_claim_lock 保证原子性。

(4) 身份重注入——压缩后不忘自己是谁#

s06 的 auto_compact 会把 messages 压缩成一条摘要。队友 loop 如果经历了一次压缩（messages 变得很短），就不知道自己是谁了——system prompt 被移到了 API 调用里，但压缩后的总结不会提及身份。

这是一个防御性设计：system prompt 可能膨胀（不能被压缩），但身份信息可以以 user message 的形式存在于可压缩的上下文里。 压缩后，harness 重新注入身份。

(5) idle 工具——模型主动说"我干完了"#

模型可以主动调 idle 表示当前任务完成，进入轮询等待新工作。Leader 的 handler：

(6) 新的斜杠命令#

/tasks 命令直接查看任务看板，显示每个任务的状态和认领人。

(7) s10 → s11 变化总结#

(8) 运行#

1
python agents/s11_autonomous_agents.py

推荐测试：

• Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.
• Spawn a coder teammate and let it find work from the task board itself
• /tasks 查看带 owner 的任务看板
• /team 监控谁在工作、谁在空闲

(1) 控制面 + 执行面#

1
Control plane (.tasks/)            Execution plane (.worktrees/)
2
+------------------+               +------------------------+
3
| task_1.json      |               | auth-refactor/         |
4
|   status: in_progress  <------>  |   branch: wt/auth-refactor
5
|   worktree: "auth-refactor" |    |   task_id: 1           |
6
+------------------+               +------------------------+
7
| task_2.json      |               | ui-login/              |
8
|   status: pending     <------>   |   branch: wt/ui-login
9
|   worktree: "ui-login"      |    |   task_id: 2           |
10
+------------------+               +------------------------+
11
                                   |
12
                         .worktrees/
13
                           index.json    (worktree registry)
14
                           events.jsonl  (lifecycle audit log)

每个 worktree 是一个完整的 git checkout，有自己的分支（wt/auth-refactor），自己的文件系统副本。alice 在 auth-refactor/ 里跑 pytest，bob 在 ui-login/ 里跑，互不影响。

(2) 仓库检测——s12 只在 git repo 里工作#

如果当前目录不在 git repo 里，REPO_ROOT 回退到 WORKDIR（git_available = False），worktree 工具会返回错误。

(3) WorktreeManager——目录隔离引擎#

WorktreeManager 管理 git worktree 的完整生命周期：

create——创建隔离副本：

bind_worktree 是双向操作——在 task JSON 里写上 worktree: "auth-refactor"，同时把任务状态从 pending 推进到 in_progress：

run——在隔离目录中执行命令：

这个 cwd=path 是 s12 区别于之前所有 session 的关键——命令运行在 isolatated 的目录副本中，改动不会污染主工作区。和 s01 cwd=WORKDIR 对照着看，能清楚看到隔离层级的一步步升级。

remove——拆除 worktree，同时可选完成绑定任务：

一个调用完成"删除目录 + 完成任务 + 发事件 + 更新索引"。force=True 时即使有未提交改动也会强制删除。

keep——保留 worktree 但不删除：

两个收尾选项对应两种场景：改完了提交到主分支 → remove；想保留这个分支日后继续 → keep。

(4) EventBus——生命周期可观测性#

8 种事件类型覆盖完整生命周期：

• worktree.create.before / .after / .failed
• worktree.remove.before / .after / .failed
• worktree.keep
• task.completed

每个事件的 JSON 行里都有 ts 时间戳、关联的 task 信息、worktree 状态。崩溃后可以用 worktree_events 工具查询事件流重建现场。

(5) 状态机：两层联动#

1
Task FSM:       pending  →  in_progress  →  completed
2
                     ↑          ↑               ↑
3
Worktree FSM:  absent   →   active     →  removed | kept
4
                     │          │               │
5
              bind_worktree  create      remove/keep

绑定的那一刻，任务从 pending 推进到 in_progress。拆除后，任务从 in_progress 推进到 completed（如果 complete_task=True）。

(6) 工具全景——16 个工具#

16 个工具，是整个序列中的最大值。和 s01 的 1 个工具（bash）对比——12 个 session，从 1 到 16，工具的数量增长就是 harness 能力的增长。

(7) s11 → s12 变化总结#

(8) 运行#

1
python agents/s12_worktree_task_isolation.py

（需要在一个 git repo 里运行）

推荐测试：

• Create tasks for backend auth and frontend login page, then list tasks.
• Create worktree "auth-refactor" for task 1, then bind task 2 to "ui-login".
• Run "git status" in worktree "auth-refactor".
• Remove worktree "auth-refactor" with complete_task=true.

12 个 session 的全景图#

1
Phase 1: The Loop           Phase 2: Planning & Knowledge
2
s01 ─ 核心循环              s03 ─ TodoWrite（内存规划）
3
s02 ─ 工具分发              s04 ─ Subagent（上下文隔离）
4
                            s05 ─ Skill 加载（按需知识）
5
                            s06 ─ 上下文压缩（策略遗忘）
6

7
Phase 3: Persistence        Phase 4: Teams
8
s07 ─ 任务系统（DAG+磁盘）   s09 ─ Agent 团队（收件箱通信）
9
s08 ─ 后台任务（线程异步）   s10 ─ 团队协议（请求-响应 FSM）
10
                            s11 ─ 自主 Agent（自组织认领）
11
                            s12 ─ Worktree 隔离（目录硬隔离）

三句贯穿始终的原则#

1. 模型看管判断，harness 看管执行 — 模型决定"做什么"，harness 决定"能做什么"和"做完了怎么办"。从 s01 的 run_bash 到 s12 的 worktree_remove，这个原则没变过。

2. 加能力不加代码，改循环不碰核心 — 所有能力增量都是 dispatch map 加一行 + TOOLS 数组加一个 schema。核心循环从 s02 之后就稳定了，12 个 session 只是不断往同一条循环上叠机制。

3. 状态在对话之外 — s03 的 todo 在内存里会丢 → s07 的 task 在磁盘上持久 → s12 的 worktree index 和 events 提供完整的崩溃恢复。每一步都在把状态往外拉，拉到模型和对话之外的文件系统里。

Command hook 示例#

在 .claude/settings.json 里配置：

1
{
2
  "hooks": {
3
    "PreToolUse": [
4
      {
5
        "matcher": "Bash(git push *)",
6
        "command": "node scripts/check-branch-protection.js",
7
        "timeout": 5000
8
      }
9
    ]
10
  }
11
}

Agent 要执行 git push origin main 时，CC 先启动 check-branch-protection.js，把工具调用的 JSON 通过 stdin 传给它：

1
{
2
  "hook_event_name": "PreToolUse",
3
  "tool_name": "Bash",
4
  "tool_input": {"command": "git push origin main"}
5
}

脚本 exit 0 → 放行。exit 2 → 阻止，stderr 给模型看原因。其他非零退出码 → 不阻止，stderr 只给用户看。

如果设置了 "async": true，进程启动后立即返回，不等待结果。适合发通知、写日志等不阻塞的场景。

Prompt hook 示例#

1
{
2
  "matcher": "Bash",
3
  "prompt": "Is this bash command safe to execute in a production environment? Command: $ARGUMENTS",
4
  "model": "claude-haiku-4-5",
5
  "timeout": 10000
6
}

$ARGUMENTS 会被替换为完整的工具调用 JSON。模型返回 {"ok": true} 或 {"ok": false, "reason": "会在生产环境重启服务"}。默认用 Haiku——便宜、快、对二元判断足够用。

Agent hook 示例（最强）#

1
{
2
  "matcher": "Write|Edit",
3
  "agent": "Review this file change for security issues, SQL injection, XSS vulnerabilities. The proposed change is: $ARGUMENTS",
4
  "timeout": 60000
5
}

Agent hook 有完整的工具访问权限——它能读文件、搜代码、跑 bash。一个合法的 50 轮 Agent 循环被启动，用 SyntheticOutputTool 强制输出结构化 JSON {ok: boolean, reason?: string}。