《御舆：解码 Agent Harness》：一本把 Claude Code 拆成零件图的中文技术书
《御舆：解码 Agent Harness》42万字拆解 AI Agent 的Harness骨架与神经 —— Claude Code 架构深度剖析，15 章从对话循环到构建你自己的 Agent Harness。在线阅读网站：
秒懂
- 它是什么？
- 这是一部以 Claude Code 为解剖对象的 42 万字中文著作，逐层拆解 Agent 运行时的对话循环、工具协议与权限管线。它适合想从源码层面理解 Agent 架构的工程师，但阅读前需要先认清其独立分析而非官方文档的定位。
- 适合谁用？
- 适合两种人阅读：一是正在构建或维护 Agent 运行时，需要参考成熟产品内部设计的工程师，书中附录 A 的 16 个核心模块地图与附录 C 的 89 个功能标志速查表可以直接当索引用；二是想从 Copilot 式补全转向 Agent 编程范式，需要建立整体心智模型的团队负责人。不适合把 Claude Code 当黑盒使用、只关心命令行操作的普通用户，这类需求看官方文档更快。
- 能商用吗？
- 未经许可不能。GitHub 在这个仓库里没有找到许可证文件；没有许可证，默认即「保留所有权利」：你可以阅读代码，但不能复用。使用前请看看 README，或先征得作者同意。
- 还在维护吗？
- 在维护。仓库最近一次提交在 11 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
一本把闭源产品当标本的解剖书
多数技术书教你怎么用工具，这本书教你怎么拆工具。《御舆：解码 Agent Harness》把 Anthropic 的 Claude Code 当作一个静态标本，用 15 章正文加 4 篇附录，从对话循环一路拆到 MCP 协议桥接。仓库 README 开篇引《考工记》的句子，把 Agent 运行时比作车的承载结构，舆是车厢，辕辐軎辖是各子系统。这个比喻贯穿全书结构：对话循环是心跳，工具系统是双手，权限管线是护栏。书的定位在阅读说明里写得很清楚，它区分三类内容：源码可确认的行为、架构推演、教学示例。也就是说，书中有一部分是作者基于代码结构的推断，不是 Anthropic 的官方承诺。这一点对读者很重要，尤其当你打算照着书里的架构图去复刻一个 Harness 时。
从 Copilot 到 Agent 的范式转移，是全书的地基
第 01 章不急着讲代码，先讲范式转移。作者把 Claude Code 放在 Copilot 的延长线上，说明补全工具与 Agent 运行时的本质差异在于谁主导任务推进。这一章同时抛出 Agent Harness 的五大设计原则，并点名技术栈：Bun 运行时、React/Ink 做终端界面、Zod v4 做数据校验。这个组合本身就有信息量，它说明 Claude Code 的终端交互层不是简单的 printf 拼接，而是用组件化思路处理流式输出。对于想从零构建 Harness 的读者，这一章的价值在于先建立判断标准，再进入具体机制。书里给了一条推荐路径：初次阅读从前言开始，按 01、02、04、15 的顺序走，这条路绕开了工具细节和记忆系统，先把对话循环、权限管线和整体构建串起来。
对话循环不是 while(true)，是五种 yield 事件的异步生成器
第 02 章拆的是 Agent 的心脏。作者把主循环描述为一个 `while(true)` 异步生成器，这个表述容易让人误以为只是简单的轮询。关键在于五种 yield 事件和十种终止原因的组合，它们定义了循环的每一次让步：什么时候把控制权交还给调用方，交出去时携带什么信息。章节还提到 `QueryDeps` 依赖注入机制，这解释了 Claude Code 如何在循环内部管理外部依赖的生命周期。对读者来说，这一章的价值不只是理解 Claude Code，而是看到 Agent 循环设计的一个完整样本。多数自建 Agent 的循环只处理模型返回的文本，忽略了 yield 事件这种细粒度控制方式。读完这一章再去看自己的循环代码，会意识到缺少的往往不是模型能力，而是循环对外暴露的事件类型不够丰富。
工具协议的五要素与权限管线的四阶段
第 03 章和第 04 章可以连着读，它们分别讲 Agent 的双手和护栏。工具系统部分提出 `Tool<I,O,P>` 五要素协议，I 是输入类型，O 是输出类型，P 是权限描述。这个协议设计迫使每个工具在定义时就声明自己的输入输出边界和权限需求，而不是在运行时临时判断。章节还提到 45 个以上工具按 12 类划分，以及并发分区贪心算法，后者解决的是多个工具同时可调用时如何分配资源的问题。权限管线部分更值得细读，它描述了四阶段管线和五种权限模式谱系。作者特别提到 Bash 规则匹配和推测性分类器，后者用 2 秒的 `Promise.race` 做超时控制，这是一个具体的工程决策，不是抽象的原则。对于自己实现过工具调用的读者，这两章能直接对照出差距：你的工具是否声明了权限属性，你的权限检查是同步的还是带超时的推测式判断。
记忆与上下文管理，封闭式设计的两个极端
第 06 章和第 07 章处理 Agent 的两种记忆。长期记忆部分提出四种封闭式记忆类型，核心原则是只保存无法推导的信息，这个约束直接对抗的是无脑存日志的做法。MEMORY.md 索引和 Fork 记忆机制是具体的实现手段，后者把子进程的上下文继承做成字节级复制。上下文管理部分给出了有效窗口公式，以及四级渐进压缩策略：Snip 到 MicroCompact 到 Collapse 再到 AutoCompact。每一级压缩的粒度不同，触发条件也不同。章节还提到断路器模式，这是为了防止压缩本身消耗过多上下文而设计的保护机制。这两章对自建 Agent 的启发很直接：记忆不是越多越好，压缩不是越狠越好，两者都需要明确的边界条件。书里把这些边界条件拆成了可验证的公式和层级，而不是停留在经验之谈。
钩子、子智能体与 MCP，扩展机制的三种深度
第 08 章到第 12 章覆盖扩展机制。钩子系统定义了五种 Hook 类型和 26 个生命周期事件，JSON 响应协议让外部脚本能结构化地干预 Agent 行为，六层优先级决定多个钩子同时触发时谁先执行。子智能体与 Fork 模式部分解释了三种 Agent 来源和字节级上下文继承，递归 Fork 防护是一个容易被忽略但必要的设计。协调器模式给出 Coordinator-Worker 双重门控和只编排不执行的约束，这个约束防止协调器越权执行具体任务。MCP 集成部分覆盖八类连接配置和五态连接管理，三段式工具命名和 Bridge 双向通信系统是协议层面的具体设计。这三章适合按需查阅，不必顺序读。如果你只用 MCP 连接外部服务，直接看第 12 章即可；如果你在规划多 Agent 协作，第 10 章的协调器模式比第 09 章的子智能体更贴近你的场景。
附录比正文更值得先翻，这是本书的使用诀窍
四篇附录是这本书最被低估的部分。附录 A 是源码导航地图，列出 16 个核心模块、依赖树、六条数据流路径、四层架构和十种设计模式，相当于一张可以直接对照源码的索引表。附录 B 列出 50 多个工具按 12 类划分，并标注每个工具的 readOnly、destructive、concurrencySafe 属性，这个表对配置权限策略有直接参考价值。附录 C 整理了 89 个功能标志，按 13 类区分编译时与运行时类型，还画了依赖关系图。附录 D 是 100 条中英对照术语表，含交叉引用。建议先翻附录 A 建立地图，再回头读正文，效率会比顺序阅读高很多。仓库还提供了修订流程，提交前需要运行 `python3 scripts/check_book.py` 和 `python3 -m unittest discover -s tests`，Mermaid 图检查依赖 Node.js 22 以上版本。
独立分析的边界与 CC BY-NC-SA 的约束
这本书有一个明确的身份声明：Claude Code 是 Anthropic 的产品，本书是独立的技术分析，不是官方出版物。这意味着书中的架构描述可能随 Claude Code 版本更新而失准，仓库阅读说明也提示功能标志与工具可用性取决于构建和运行时配置。另一个实际约束是许可协议，全书文字采用 CC BY-NC-SA 4.0，要求署名、禁止商业使用、演绎作品必须以相同协议共享。对于想在企业内部培训中大规模引用本书内容的团队，这个许可需要先走法务确认。参与修订的门槛不低，要跑 Python 测试和 Node.js 的 Mermaid 检查，但这也保证了内容质量的下限。仓库首页还提到英文版 README 存在，涉及双语内容时需同步检查，这说明项目方把修订质量当作一个持续维护的过程。
编辑结论
适合两种人阅读：一是正在构建或维护 Agent 运行时，需要参考成熟产品内部设计的工程师，书中附录 A 的 16 个核心模块地图与附录 C 的 89 个功能标志速查表可以直接当索引用；二是想从 Copilot 式补全转向 Agent 编程范式，需要建立整体心智模型的团队负责人。不适合把 Claude Code 当黑盒使用、只关心命令行操作的普通用户，这类需求看官方文档更快。也不适合需要商业授权内容的团队，全书采用 CC BY-NC-SA 4.0，非商业使用是硬边界。动手实践前先核实两件事：其一，书中标注的源码行为是否与你使用的 Claude Code 版本一致，功能标志与工具可用性随构建配置变化，仓库阅读说明已明确提示；其二，附录 B 中 50 多个工具的 readOnly 与 destructive 属性分类，在你自己的权限配置里是否对应。最后确认你的 Node.js 版本能跑通 `npm run check:diagrams`，否则修订贡献流程会卡在 Mermaid 语法检查这一步。
社区笔记