在讨论代码之前，先把一件事说清楚。
Agency -- 感知、推理、行动的能力 -- 来自模型训练，不是来自外部代码的编排。 但一个能干活的 agent 产品，需要模型和 harness 缺一不可。模型是驾驶者，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 工程师 -- 这是一个强大的身份。以下是你真正的工作：
-
实现工具。 给 agent 一双手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 agent 在环境中可以采取的一个行动。设计它们时要原子化、可组合、描述清晰。
-
策划知识。 给 agent 领域专长。产品文档、架构决策记录、风格指南、合规要求。按需加载（s07），不要前置塞入。Agent 应该知道有什么可用，然后自己拉取所需。
-
管理上下文。 子 Agent 把明确的工作留在另一份消息列表中；上下文压缩（s08）缩短较早的历史；任务系统（s10）让目标持久化到单次对话之外。
-
控制权限。 给 agent 边界。沙箱化文件访问。对破坏性操作要求审批。在 agent 和外部系统之间实施信任边界。这是安全工程与 harness 工程的交汇点。
-
收集任务过程数据。 Agent 在你的 harness 中执行的每一条行动序列都是训练信号。真实部署中的感知-推理-行动轨迹是微调下一代 agent 模型的原材料。你的 harness 不仅服务于 agent -- 它还可以帮助进化 agent。
你不是在编写智能。你是在构建智能栖居的世界。这个世界的质量 -- agent 能看得多清楚、行动得多精准、可用知识有多丰富 -- 直接决定了智能能多有效地表达自己。
造好 Harness。Agent 会完成剩下的。
为什么这个仓库专门拆解 Claude Code？
因为 Claude Code 是我们所见过的最优雅、最完整的 agent harness 实现。不是因为某个巧妙的技巧，而是因为它 没做 的事：它没有试图成为 agent 本身。它没有强加僵化的工作流。它没有用精心设计的决策树去替模型做判断。它给模型提供了工具、知识、上下文管理和权限边界 -- 然后让开了。
把 Claude Code 剥到本质来看：
Claude Code = 一个 agent loop
+ 工具 (bash, read, write, edit, glob, grep, browser...)
+ 按需 skill 加载
+ 上下文压缩
+ 子 agent 派生
+ 带依赖图的任务系统
+ 异步邮箱的团队协调
+ 任务绑定的 worktree 并行执行
+ 权限治理
就这些。这就是全部架构。每一个组件都是 harness 机制 -- 为 agent 构建的栖居世界的一部分。Agent 本身呢？是 Claude。一个模型。由 Anthropic 在人类推理和代码的全部广度上训练而成。Harness 没有让 Claude 变聪明。Claude 本来就聪明。Harness 给了 Claude 双手、双眼和一个工作空间。
这就是 Claude Code 作为教学标本的意义：它展示了当你信任模型、把工程精力集中在 harness 上时会发生什么。 本仓库的课程（s01-s17）逐步拆解并重组 harness 机制。学完之后，你理解的不只是一个 coding agent 怎么工作，而是适用于不同领域的 harness 工程原则。
启示不是 "复制 Claude Code"。启示是：最好的 agent 产品，出自那些明白自己的工作是 harness 而非 intelligence 的工程师之手。
这不只关乎编程 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
|
包含 tool_use block?
/ \
yes no
| |
execute tools return text
append results
loop back -----------------> messages[]
这是最小循环。每个 AI Agent 都需要这个循环。
模型决定何时调用工具、何时停止。
代码只是执行模型的要求。
本仓库教你构建围绕这个循环的一切 --
让 agent 在特定领域高效工作的 harness。
17 个递进式课程, 从简单循环到目标闭环。 每个课程添加一个 harness 机制。每个机制有一句格言。
s01 "One loop & Bash is all you need" — 一个工具 + 一个循环 = 一个 Agent
s02 "加一个工具, 只加一个 handler" — 循环不用动, 新工具注册进 dispatch map 就行
s03 "先划边界, 再给自由" — 先判断操作能不能做，要不要问用户
s04 "挂在循环上, 不写进循环里" — 在工具前后留插口，不改主循环也能扩展
s05 "没有计划的 agent 走哪算哪" — 先列步骤再动手, 完成率翻倍
s06 给子任务全新的
messages[]，最终文本作为一条工具结果返回s07 "用到时再加载, 别全塞 prompt 里" — 技能先列目录，用到时再展开
s08 "上下文总会满, 要有办法腾地方" — 四步压缩，先整理工具结果，仍然超限时再生成历史摘要
s09 "记住该记的, 忘掉该忘的" — 三个子系统: 筛选、提取、整理
s10 "大目标拆成小任务, 排好序, 持久化" — 文件持久化的任务图, 多 agent 协作的基础
s11 "慢操作丢后台, agent 继续思考" — 后台线程跑命令, 完成后注入通知
s12 "定时触发, 不需要人推" — 按时间自动触发任务
s13 "一个 Agent 顾不过来，就让队友分工协作" — 持久队友协作、认领就绪任务，并使用任务绑定的工作目录
s14 "能力不够? 插上 MCP" — 把外部工具接进同一个工具池
s15 "多种机制，一个循环" — 集成示例用到的机制归到同一个 harness
s16 "编排形状固定时，就把它写进代码" — 保存好的 workflow 使用 journal 续跑
s17 "目标决定循环什么时候真正结束" — 每次准备停止时都由独立判断器审查；目标不可能、执行失败或超过续跑上限时把控制权交还用户
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})
tool_calls = [
block for block in response.content if block.type == "tool_use"
]
if not tool_calls:
return
results = []
for block in tool_calls:
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 机制。s15 把累积的运行时接回一起；s16 和 s17 再分别聚焦 workflow 编排与目标收口。循环属于 agent，机制属于 harness。
这是一个从 0 到 1 的 harness 工程课程。每章先单独展开一个机制，s15 再把累积的运行时接回完整的 Agent 循环。s16 在这个循环上加入 workflow 编排；s17 用更小的工具池单独讲目标控制的续跑，不是又一个累积式运行时。
- 打开项目 GitHub 页面，点右上角绿色
Code→Download ZIP，下载后解压。 - 进入解压后的文件夹，双击
启动.command。- 如果提示“无法打开/来自身份不明的开发者”：按住
Control点按启动.command，选“打开”，再点“打开”。
- 如果提示“无法打开/来自身份不明的开发者”：按住
- 保持联网等待。脚本会自动检查 Python；如果没有，会引导自动安装。弹出管理员密码框时，输入 Mac 开机密码。
- 第一次运行会自动安装依赖。看到
请输入你的 DeepSeek API Key时：- 打开 https://platform.deepseek.com/ 注册并登录；
- 在控制台创建 API Key 并复制；
- 回到终端窗口粘贴，然后按回车。
- 看到
run >>菜单后，输入章节编号开始上课：s01回车：第一课；- 之后依次输入
s02、s03…s17； - 课程里输入
q：退出当前章节，回到菜单； - 菜单里输入
q：退出整个程序。
- 第二次以后，仍然双击
启动.command，即可直接进入课程。
Windows 用户：目前自动安装脚本优先支持 Mac。Windows 请先到 https://www.python.org/downloads/ 安装 Python 3.11 或更高版本，安装时勾选 Add Python to PATH，然后在项目文件夹打开终端运行：
python run.py如果你习惯用终端，也可以这样做：
git clone https://github.com/huuuboo/learn-claude-code
cd learn-claude-code
# 自动装依赖 + 首次引导填 key + 菜单选择章节 s01–s17
python3 run.py
# 高级用法：
python run.py 3 # 直接运行指定章节（3 / s03 / agent_loop 均可）
python run.py s16 demo # s16 附带的 demo / resume 模式
python s01_agent_loop/code.py # 各章代码仍可独立运行主线：能动手 → 能做复杂任务 → 能记住和恢复 → 能长期运行 → 能协作 → 能扩展并合体
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/>└─ 保存并召回可复用知识"]:::stage3
S1 ==> S2 ==> S3
end
%% 第二层：4-6阶段
subgraph Phase2 ["🚀 阶段 4-6：高阶能力进化（长期、协作与融合）"]
direction LR
S4["<b>第四阶段：让任务长期运行</b><br/>━━━━━━━━━━━━━<br/><b>s10 Task System</b><br/>└─ 任务落盘记依赖<br/><br/><b>s11 Background Tasks</b><br/>└─ 慢操作丢后台<br/><br/><b>s12 Cron Scheduler</b><br/>└─ 按时自动触发"]:::stage4
S5["<b>第五阶段：让多个 Agent 协作</b><br/>━━━━━━━━━━━━━<br/><b>s13 Agent Teams</b><br/>└─ 队友 + 消息投递 + 协作协议<br/>└─ 原子认领就绪任务<br/>└─ 任务绑定的 Worktree"]:::stage5
S6["<b>第六阶段：接外部能力合体</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ 技能按需展开<br/><br/><b>s14 MCP Plugin</b><br/>└─ 外部接进工具池<br/><br/><b>s15 Agent Harness 集成</b><br/>└─ 课程机制回到同一循环"]:::stage6
S4 ==> S5 ==> S6
end
%% 第三层：编排与目标闭环
subgraph Phase3 ["🎯 第七阶段：编排与目标闭环"]
direction LR
S7["<b>第七阶段：编排并完成</b><br/>━━━━━━━━━━━━━<br/><b>s16 Workflow Runtime</b><br/>└─ 脚本拥有固定编排<br/><br/><b>s17 Goal Loop</b><br/>└─ 独立判断决定何时停止"]:::stage1
S6 ==> S7
end
%% 将三个模块连接起来，形成 Z 字形阅读流
Phase1 ===> Phase2 ===> Phase3
%% 应用背景样式
class Phase1,Phase2,Phase3 groupBox
| 章节 | 主题 | 关键概念 |
|---|---|---|
| s01 | Agent Loop | messages / while True / tool_use |
| s02 | Tool Use | TOOL_HANDLERS / dispatch map / 并发 |
| s03 | Permission | PermissionRule / 审批管线 |
| s04 | Hooks | PreToolUse / PostToolUse / 扩展点 |
| s05 | TodoWrite | TodoItem / 先计划后执行 |
| s06 | Subagent | fresh messages[] / 上下文隔离 |
| s07 | Skill Loading | SkillLoader / 技能目录 / 按需注入 |
| s08 | Context Compact | budget / snip / micro / summary 四步压缩 |
| s09 | Memory | selection / extraction / consolidation |
| s10 | Task System | TaskRecord / blockedBy / 磁盘持久化 |
| s11 | Background Tasks | 线程执行 / 通知队列 |
| s12 | Cron Scheduler | 持久化调度 / 会话级触发 |
| s13 | Agent Teams | 持久队友 / 原子认领 / 任务绑定的 Worktree / 类型协议 |
| s14 | MCP Plugin | 工具发现 / 命名空间 / 工具池组装 |
| s15 | Agent Harness 集成 | 工具、运行时上下文、任务、团队、调度和 MCP 归到一个循环 |
| s16 | Workflow Runtime | 脚本编排 / 生命周期事件 / journal 续跑 |
| s17 | Goal Loop | 目标闸门 / 对话判断 / 自动续轮 |
learn-claude-code/
s01_agent_loop/ # 每章一个文件夹
README.md # 默认英文文档（完整叙事）
README.zh.md # 中文译本
README.ja.md # 日文译本
code.py # 独立可运行代码
images/ # SVG 流程图
s02_tool_use/
...
s14_mcp_plugin/
s15_integrated_harness/
s16_workflow_runtime/
s17_goal_loop/ # 终点章
skills/ # s07 使用的 skill 文件
tests/
MIT
Agency 来自模型。Harness 让 agency 落地。造好 Harness，模型会完成剩下的。
Bash is all you need. Real agents are all the universe needs.