从零理解如何构建 AI Agent

Appearance

00 阅读指南 ​

适合谁读 ​

这套书面向“架构复刻向”的读者：你不满足于把 Claude Code 当作一个会聊天的终端 UI，而是想理解它如何把一次自然语言输入，变成可控的工程执行闭环（模型决策、工具编排、权限与预算、结果回填、会话与远程协同等）。

更具体地说，适合你如果你符合以下任意一条：

  • 你希望系统性阅读 restored-src/src/，并能把“看懂”转化为自己的架构抽象。
  • 你在做 AI Coding Agent / 工具编排系统，想借鉴它的分层、边界与治理机制。
  • 你想把“源码地图”当作长期笔记来维护：可顺读，也可快速回查。

不太适合你如果你期待：

  • 逐行讲解所有文件、所有分支（这会变成目录注释集，且维护成本极高）。
  • 完整复刻官方实现（本仓库是基于发布包与 source map 的研究还原，不代表内部仓库结构）。

推荐顺读路径 ​

现在这套书已经可以按一条完整主线顺读，不再只是“先读前三章等后续补齐”。推荐顺序如下：

  1. book/README.md：先确认全书范围、目录入口与附录用途。
  2. book/00-阅读指南.md（本章）：掌握阅读方式、练习方式和跳读策略。
  3. book/01-系统全景与学习路线.md：建立全局分层、关键入口与阅读坐标系。
  4. book/part-1-主业务流/01-CLI-启动与入口分流.md
  5. book/part-1-主业务流/02-初始化-配置-环境-遥测.md
  6. book/part-1-主业务流/03-会话上下文与消息模型.md
  7. book/part-1-主业务流/04-query-主循环如何驱动整个系统.md
  8. book/part-1-主业务流/05-tool-编排-执行-权限-结果回填.md
  9. book/part-1-主业务流/06-输出渲染-stop-hooks-任务摘要-请求收尾.md
  10. book/part-2-扩展能力流/07-MCP-如何把外部能力接进来.md
  11. book/part-2-扩展能力流/08-Skills-如何把方法论接进主流程.md
  12. book/part-2-扩展能力流/09-Plugins-Hooks-如何做能力扩展.md
  13. book/part-2-扩展能力流/10-权限-策略-安全边界.md
  14. book/part-3-远程协同流/11-Bridge-远程控制主链路.md
  15. book/part-3-远程协同流/12-Remote-Session-与连接管理.md
  16. book/part-3-远程协同流/13-后台会话与并发托管.md
  17. book/part-3-远程协同流/14-多代理-子任务-协同机制.md
  18. book/part-4-附录/90-源码地图-按目录反查系统能力.md
  19. book/part-4-附录/91-核心文件索引.md
  20. book/part-4-附录/92-关键类型与核心抽象.md
  21. book/part-4-附录/99-每章练习题与复刻建议.md

如果你不想一口气读完，可以先顺读到第 6 章，建立主循环闭环，再决定是先走 Part 2 还是 Part 3。

推荐跳读路径 ​

如果你带着明确问题来，可按主题跳读：

下面每条都直接给“现在就能读的最短路线”：

  • 你关心“它到底怎么跑起来的”：先读 book/01-系统全景与学习路线.md，再读 Part 1 的 01、02、04，最后回到 restored-src/src/entrypoints/cli.tsx 与 restored-src/src/entrypoints/init.ts 对照。
  • 你关心“为什么能做工具编排而不是闲聊”：先读 Part 1 的 03、04、05，再回看 restored-src/src/query.ts、restored-src/src/Tool.ts、restored-src/src/services/tools/*。
  • 你关心“如何接外部能力”：直接顺读 Part 2 的 07 到 10，然后配合 book/part-4-附录/92-关键类型与核心抽象.md 回看 MCP、Skill、Plugin 的抽象边界。
  • 你关心“远程协同与后台”：直接顺读 Part 3 的 11 到 14，再回看 restored-src/src/bridge/、restored-src/src/remote/、restored-src/src/tasks/、restored-src/src/coordinator/。
  • 你关心“按目录或文件反查更省力”：先看 book/part-4-附录/90-源码地图-按目录反查系统能力.md，再看 book/part-4-附录/91-核心文件索引.md。
  • 你关心“如何把看懂变成实践”：读完一卷后直接进入 book/part-4-附录/99-每章练习题与复刻建议.md，按练习路线去复述、画图和复刻。

如何把业务流与源码目录对应起来 ​

读这套书时，建议把“业务流”与“目录责任”绑定记忆：每当你在正文看到一个阶段，就立刻在 restored-src/src/ 里找到它的落点。

一个实用的对照方式是把系统拆成三类“可追踪对象”：

  • 入口与模式：读这一类时你要回答的问题是“系统有哪些运行形态？我现在走的是哪条入口路径？”从 entrypoints/ 看系统支持哪些启动形态与运行模式（交互式、后台、远程控制、模板作业等）。
  • 主循环与编排：读这一类时你要回答的问题是“一次请求如何推进成闭环？工具调用在哪个点发生并如何回填？”从 query.ts 看一次请求如何循环推进；从 services/tools/* 看工具如何被挑选、调度与执行；从 Tool.ts 看贯穿全程的上下文与约束。
  • 扩展与治理：读这一类时你要回答的问题是“能力如何接入而不破坏主链路？系统用什么机制把扩展纳入可控边界？”从 skills/、plugins/、services/mcp/* 等看能力如何接入；从权限/预算/压缩等机制看系统如何把扩展纳入可控边界。

实践上，你可以用这几个动作快速定位：

  • 以“入口文件”做锚点：优先打开 restored-src/src/entrypoints/cli.tsx、restored-src/src/query.ts、restored-src/src/Tool.ts，建立最小闭环的路径感。
  • 用 rg 追踪关键名词：例如在 restored-src/src/ 下搜索 tool_use、tool_result、runTools、ToolUseContext、bridge、remote，把名词的“出现位置”当作地图标注。
  • 先抓边界再读细节：每章先回答“它负责什么、不负责什么”，再进入局部实现。

如何使用每章的小练习 ​

每章的小练习不追求“写出一套 Claude Code”，而是帮助你把理解固化成可复用的抽象。建议按同一套路完成练习，并把产物收纳到自己的笔记仓库：

  • 复述练习：用 5 句话写清本章链路的业务步骤（输入、决策、执行、回填、收尾）。
  • 画图练习：把本章 Mermaid 图自己重画一遍，强迫自己补全关键分支与边界条件。
  • 复刻练习：用“最小可复刻闭环”描述你会保留哪些接口与约束（例如：消息模型、工具协议、权限裁决点、预算/压缩策略的占位）。

如果你时间有限，可以只做“复述 + 画图”；当你准备动手实现自己的系统时，再回头补“复刻练习”。