Agent 教程

外观

如何阅读这个项目 ​

不要从文件数量最多的目录开始读。Claude Code 的还原源码有上千个 TypeScript 文件，第一遍阅读应该沿着 Agent 的主链路走。

第一遍：读主链路 ​

推荐顺序：

text
README.md
  -> restored-src/src/main.tsx
  -> restored-src/src/QueryEngine.ts
  -> restored-src/src/query.ts
  -> restored-src/src/Tool.ts
  -> restored-src/src/tools.ts

这个顺序能回答最重要的问题：

  • CLI 怎么启动？
  • 用户输入怎么进入会话？
  • 模型在哪里调用？
  • 模型如何请求工具？
  • 工具怎么注册和执行？
  • 工具结果怎么回到模型？

先把 main.tsx 当作启动编排层 ​

阅读 restored-src/src/main.tsx 时，不要期待看到一个简单的：

text
main()
  -> runAgent()

它更像产品启动编排层。第一遍可以重点找这些锚点：

  • run()：Commander 入口和整体启动流程。
  • getTools()：根据权限上下文和功能开关得到工具池。
  • getCommands()：加载 slash commands、skills 和 plugin commands。
  • getMcpToolsCommandsAndResources()：接入 MCP tools、commands 和 resources。
  • getDefaultAppState()：构造交互式运行状态。

这些逻辑说明：Claude Code 在进入 Agent 主循环前，已经完成了 CLI 参数解析、配置加载、权限上下文、工具池、命令池、MCP 和 AppState 装配。真正适合学习 AgentLoop 的文件是后面的 QueryEngine.ts 和 query.ts。

第二遍：读关键子系统 ​

主链路清楚后，再按子系统读：

text
services/api/claude.ts        # 模型 API 层
services/tools/               # 工具执行管线
utils/permissions/            # 权限系统
services/compact/             # 上下文压缩
commands.ts                   # slash commands 与 skills 加载
services/mcp/                 # MCP 接入
state/AppStateStore.ts        # 交互式状态
screens/REPL.tsx              # 终端交互入口

第三遍：抽象成自己的 Agent ​

源码阅读不应该停在“Claude Code 是怎么写的”。每看完一个模块，都要问：

  • 这个模块解决了什么通用问题？
  • 如果我做一个小 Agent，需要这个模块吗？
  • 可以怎么简化？
  • 哪些复杂度来自 Claude Code 的产品规模，而不是 Agent 的本质？

例如，query.ts 里有很多上下文压缩和恢复策略。自己实现第一版 Agent 时，不需要复刻这些细节，但需要理解它们解决的是同一个问题：长会话不能无限增长。

阅读时的判断标准 ​

值得优先学习的设计：

  • QueryEngine 这种会话封装。
  • Tool 接口和工具注册表。
  • 工具调用前的权限网关。
  • AsyncGenerator 驱动的 streaming 主循环。
  • JSONL 会话日志。

可以暂时跳过的复杂度：

  • 大量 feature flag。
  • 内部 dogfooding 命令。
  • 完整终端 renderer。
  • 插件市场和自动更新。
  • 多种 MCP transport 的完整兼容。

本教程后续章节会按这个原则展开。