Claude Code 源码学习手册¶

📚 完整版 —— 30+ 文档、500+ 练习、80+ 自动化测试，把 dvxiaofan/cc-claude-code 仓库（2026-03-31 Claude Code 源码泄露事件的一个完整快照，1902 src 文件 / 512,664 行 / 4 vendor 文件）"拆开揉碎了"地讲清楚。

⚠️ 仓库本身不包含 package.json / bun.lockb / node_modules，学习以纯读代码为主。本目录的练习任务和测试可在独立的练习工程里跑（见 practice-tests/）。

🚀 快速开始（30 秒选路径）¶

我只有 1 小时¶

读 00-index.md 的"技术栈速览"和"架构骨架图"
读 phase-01-entry.md 的"1.1 入口层级总览"和"1.2 第一层：bin 入口"
用 glossary.md 查不认识的术语

我有 3~5 天（速通）¶

按 00-index.md 的「A. 时间紧张」路径：阶段 1 → 2 → 3 → 5 → 6

我有 2~3 周（精通）¶

按 00-index.md 的「B. 时间充裕」路径：阶段 1 → 2 → 3 → 4 → 5 → 6 → 7

我有具体目标¶

想学 TUI 架构 → 阶段 2 + 阶段 4 + 阶段 7（Ink）
想学状态管理 → 阶段 3（60 行 store.ts）
想学 agent loop → 阶段 6（query.ts / QueryEngine）
想学扩展系统 → 阶段 7（MCP / plugins / skills）
想学 N-API 集成 → 阶段 7（vendor/）

📂 完整目录¶

learn_doc/
├── README.md                            ← 你正在看
├── 00-index.md                          ← 整体导读
├── glossary.md                          ← A~Z 完整术语表（~150 词条）
│
├── phase-01-entry.md                    ← 阶段 1：入口与启动链
├── phase-02-repl.md                     ← 阶段 2：REPL 主循环
├── phase-03-state.md                    ← 阶段 3：状态管理
├── phase-04-components.md               ← 阶段 4：组件库与设计系统
├── phase-05-tools.md                    ← 阶段 5：工具调用系统
├── phase-06-agent-loop.md               ← 阶段 6：Agent 循环
├── phase-07-advanced.md                 ← 阶段 7：高级系统
│
├── topics/                              ← 13 个跨阶段专题深挖
│   ├── async-generator-pattern.md           async function* 完整讲解
│   ├── dce-feature-flags.md                 95+ feature 旗标全景
│   ├── keybindings-system.md                键位系统全拆
│   ├── mcp-protocol-deep-dive.md            MCP 协议深入
│   ├── context-compaction.md                压缩 10 文件拆解
│   ├── bash-security-model.md               BashTool 16 文件安全模型
│   ├── ink-rendering-pipeline.md            Ink 渲染管线
│   ├── markdown-rendering-optimization.md   Markdown 优化
│   ├── structured-diff-perf-archaeology.md  性能考古
│   ├── coding-style-conventions.md          代码风格 + React Compiler
│   ├── big-files-untold-stories.md          5 大巨型文件揭秘
│   ├── directory-tree-walkthrough.md        完整目录树注释
│   └── native-napi-integration.md           N-API 集成模板
│
├── reference/                           ← 5 个速查手册
│   ├── file-index.md                        200+ 文件 1 句话索引
│   ├── feature-flags.md                     95+ 旗标清单
│   ├── env-vars.md                          400+ env vars 清单
│   ├── api-quickref.md                      导出符号速查
│   └── import-graph.md                      关键 import 关系
│
├── data/                                ← 4 个 mermaid 可视化
│   ├── architecture-diagrams.md             12 张架构图
│   ├── sequence-diagrams.md                 10 个时序图
│   ├── state-machines.md                    10 个状态机
│   └── call-graphs.md                       调用图
│
├── walkthrough/                         ← 4 个练习答案
│   ├── handwrite-store.md                   60 行 Store 答案
│   ├── mock-agent-loop.md                  5 行 agent 循环
│   ├── lru-cache.md                         LRU Cache 实现
│   └── build-a-tool.md                     GitCommitTool 设计
│
├── analysis/                            ← 2 个深度分析
│   ├── design-philosophy.md                10 条设计哲学
│   └── error-handling.md                   错误处理模式全拆
│
└── practice-tests/                      ← 7 阶段自动化测试
    ├── README.md
    ├── package.json
    ├── tsconfig.json
    └── src/
        ├── store.ts + store.test.ts        阶段 3：60 行 Store（13 测试）
        ├── tool.ts + tool.test.ts          阶段 5：findToolByName（10 测试）
        ├── phase-1-startup.ts + .test.ts   阶段 1：启动 prefetch（6 测试）
        ├── phase-2-repl.ts + .test.ts      阶段 2：REPL 编排（10 测试）
        ├── phase-4-lru.ts + .test.ts        阶段 4：LRU + Theme（19 测试）
        ├── phase-6-agent.ts + .test.ts     阶段 6：mock agent loop（11 测试）
        └── phase-7-vendor.ts + .test.ts    阶段 7：N-API + MCP（10 测试）

📊 数据统计¶

学习手册：
  - 30+ 文档
  - ~7000 行 markdown
  - 80+ 自动化测试（100% pass）
  - 0 typecheck 错误
  - 覆盖 src/ 50万行 / 1902 文件

🎯 每个阶段文档的固定结构¶

目标 + 时长 + 前端类比 —— 一眼看定位
核心代码片段 —— 直接引用 src/... 真实文件 + 行号
关键洞察 —— 项目里"为什么这样写"的设计哲学
阅读清单 —— 按优先级排序的具体文件
练习任务 —— 学完动手验证
下一步链接 —— 阶段间串接

💡 贯穿全文的几个反复强调的点¶

概念	出现位置	一句话总结
*`async function` + `yield`**	topics, phase-02, 05, 06, 07	Claude Code 整个流式架构的底座（query、tool.call、API client 都用）
Bun `feature('XXX')` DCE	topics, phase-01, 02, 05, 07	大量 Ant-only 分支是死代码，外部构建看不到
TypeScript 联合类型 + 类型守卫	phase-03, 05, 06	TaskState / message.type / permission decision 全用这套
"inlined X" 打破循环依赖	phase-03, 06, 07	注释里反复出现的纪律
注释即历史	phase-04, topics, 07	`StructuredDiff.tsx` 顶部引用 PR `#21439` / `#20378` 是实战经验标本
状态机两层	phase-06	QueryEngine（class）管单次对话 / TaskState（union）管多 agent

🧪 练习任务¶

每个阶段文档结尾都有"练习任务"小节。7 个阶段的练习已做成 vitest 自动化测试：

cd learn_doc/practice-tests
bun install    # 或 npm install
bun test       # 或 npx vitest
# 期望：79 pass / 0 fail / 0 typecheck 错

具体见 practice-tests/README.md。

🗺️ 推荐阅读顺序¶

Day 1（入门）¶

00-index.md → 技术栈速览 + 架构骨架图
phase-01-entry.md → 通读
看 src/entrypoints/cli.tsx 前 100 行 + src/main.tsx 前 50 行

Day 2~3（核心）¶

phase-02-repl.md → 重点看"2.2 顶层结构"和"2.4 三大数据流"
phase-03-state.md → 手抄 60 行 store.ts

Day 4~5（深水区）¶

phase-05-tools.md → 挑 FileEditTool/ 一个工具读完
phase-06-agent-loop.md → 理解 async function* 循环

Day 6+（按兴趣）¶

phase-04-components.md → TUI 组件库
phase-07-advanced.md → 选 MCP / Bridge / Ink / N-API 任一专题
topics/ → 13 个跨阶段专题

工具书（随时查）¶

glossary.md → 术语
reference/file-index.md → 文件功能
reference/feature-flags.md → 旗标
reference/env-vars.md → env vars
reference/api-quickref.md → 导出符号
reference/import-graph.md → 依赖关系
data/ → mermaid 架构图
walkthrough/ → 练习答案
analysis/ → 深度分析

🤝 反馈¶

觉得哪里写错了、哪里想展开、哪个阶段需要更详细的例子，直接说： - "阶段 X 讲得太粗" → 我会补充代码片段 - "术语 Y 没收录" → 我会加进 glossary.md - "练习任务 Z 不会做" → 我会写个 walkthrough

🎓 文档之间的交叉引用¶

00-index.md (导读)
  ├─ phase-01 ~ 07 (7 个阶段)
  │    ├─ → topics/* (专题深挖)
  │    └─ → walkthrough/* (练习答案)
  ├─ topics/* (13 个跨阶段专题)
  │    └─ → walkthrough/* (具体答案)
  ├─ reference/* (5 个速查)
  ├─ data/* (4 个可视化)
  ├─ analysis/* (2 个深度分析)
  ├─ glossary.md (150+ 术语)
  └─ practice-tests/* (7 阶段测试)

下一步： - 速通者 → 00-index.md - 想理解整体架构 → 00-index.md 「0.3 架构骨架」 - 想从入口读起 → phase-01-entry.md - 查术语 → glossary.md - 看架构图 → data/architecture-diagrams.md - 跑测试 → practice-tests/README.md