读 Claude Code，学习如何写一个 Agent

这是一套面向工程实践的源码阅读教程。它不是 Claude Code 的官方文档，也不是对还原源码逐行注释；它把 @anthropic-ai/claude-code 2.1.88 的 sourcemap 还原源码当作案例，提炼一个 Agent CLI 应该如何设计。

本教程的目标是让读者读完以后，可以自己搭出一个简化版 Agent：

• 能接收用户输入并维护会话消息。
• 能调用模型并处理 streaming 响应。
• 能注册和执行工具。
• 能把工具结果返回模型继续推理。
• 能加入权限、Hooks、会话恢复、上下文压缩和扩展机制。

阅读路径

建议按顺序阅读：

1. 项目定位
2. Agent 主循环
3. Tool 系统
4. 权限与 Hooks
5. 上下文、会话与记忆
6. 扩展机制与终端 UI
7. 实现一个简化版 Agent

核心主链路可以先看 Agent 主链路图。

教程开发工作流

每章都遵循同一个流程：

1. CONTRACT.md：定义章节目标、源码范围、必须回答的问题和验收标准。
2. RESEARCH.md：记录源码证据、调用链和架构提炼。
3. 正文小节：把研究笔记写成可学习的教程。
4. examples/：沉淀可迁移的简化实现。

重要边界

这个仓库里的 package/cli.js 是可运行的发布产物；restored-src/src 是从 sourcemap 还原出来的研究材料。学习时应把它当作架构样本，而不是当作可以直接二次开发和重新发布的官方源码工程。