claude-code/learn/LEARN.md

Claude Code 源码学习路线

基于反编译版 Claude Code CLI (v2.1.888) 的源码学习跟踪

各阶段详细笔记见同目录下的 phase-*.md 文件

第一阶段：启动流程（入口链路） ✅

详细笔记：phase-1-startup-flow.md

理解程序从命令行启动到用户看到交互界面的完整路径。

• src/entrypoints/cli.tsx — 真正入口，polyfill 注入 + 快速路径分发
  • 全局 polyfill：feature() 永远返回 false、MACRO 全局对象、BUILD_* 常量
  • 快速路径设计：按开销从低到高检查，能早返回就早返回
  • 动态 import 模式：await import() 延迟加载，减少启动时间
  • 最终出口：import("../main.jsx") → cliMain()
• src/main.tsx — Commander.js CLI 定义，重型初始化（4683 行）
  • 三段式结构：辅助函数(1-584) → main()(585-856) → run()(884-4683)
  • side-effect import：profileCheckpoint、startMdmRawRead、startKeychainPrefetch 并行预加载
  • preAction 钩子：MDM 等待、init()、迁移、远程设置
  • Commander 参数定义：40+ CLI 选项
  • action handler（2800 行）：参数解析 → 服务初始化 → showSetupScreens → launchRepl()
  • --print 分支走 print.ts；交互分支走 launchRepl()（7 个场景分支）
  • 子命令注册：mcp/auth/plugin/doctor/update/install 等
• src/replLauncher.tsx — 桥梁（22 行），组合 <App> + <REPL> 渲染到终端
• src/screens/REPL.tsx — 交互式 REPL 界面（5009 行）
  • Props：commands、tools、messages、systemPrompt、thinkingConfig 等
  • 50+ 状态：messages、inputValue、screen、streamingText、queryGuard 等
  • 核心数据流：onSubmit → handlePromptSubmit → onQuery → onQueryImpl → query() → onQueryEvent
  • QueryGuard 并发控制：idle → running → idle，防止重复查询
  • 渲染：Transcript 模式（只读历史）/ Prompt 模式（Messages + PermissionRequest + PromptInput）

数据流：bun run dev → package.json scripts.dev → bun run src/entrypoints/cli.tsx → 快速路径检查 → main.tsx:main() → launchRepl() → <App><REPL /></App>

---

第二阶段：核心对话循环 ✅

详细笔记：phase-2-conversation-loop.md

理解用户发一句话后，如何变成 API 请求、如何处理流式响应和工具调用。

• src/query.ts — 核心查询循环（1732 行）
  • query() AsyncGenerator 入口，委托给 queryLoop()
  • queryLoop() — while(true) 主循环，State 对象管理迭代状态
  • 消息预处理（autocompact、compact boundary）
  • deps.callModel() → 流式 API 调用
  • StreamingToolExecutor — API 流式返回时并行执行工具
  • 工具调用循环（tool use → 执行 → result → continue）
  • 错误恢复（prompt-too-long、max_output_tokens 升级+多轮恢复）
  • 模型降级（FallbackTriggeredError → 切换 fallbackModel）
  • Withheld 消息模式（暂扣可恢复错误）
• src/QueryEngine.ts — 高层编排器（1320 行）
  • QueryEngine 类 — 一个 conversation 一个实例
  • submitMessage() — 处理用户输入 → 调用 query() → 消费事件流
  • SDK/print 模式专用（REPL 直接调用 query()）
  • 会话持久化（recordTranscript）
  • Usage 跟踪、权限拒绝记录
  • ask() 便捷包装函数
• src/services/api/claude.ts — API 客户端（3420 行）
  • queryModelWithStreaming / queryModelWithoutStreaming — 两个公开入口
  • queryModel() — 核心私有函数（2400 行）
  • 请求参数组装（system prompt、betas、tools、cache control）
  • Anthropic SDK 流式调用（anthropic.beta.messages.stream()）
  • BetaRawMessageStreamEvent 事件处理（message_start/content_block_*/message_delta/stop）
  • withRetry 重试策略（429/500/529 + 模型降级）
  • Prompt Caching 策略（ephemeral/1h TTL/global scope）
  • 多 provider 支持（Anthropic / Bedrock / Vertex / Azure）

数据流：REPL.onSubmit → handlePromptSubmit → onQuery → onQueryImpl → query() AsyncGenerator → queryLoop() while(true) → deps.callModel() → claude.ts queryModel() → anthropic.beta.messages.stream() → 流式事件 → 收集 tool_use → 执行工具 → 结果追加到 messages → continue → 无工具调用时 return

---

第三阶段：工具系统

理解 Claude 如何定义、注册、调用工具。先读框架，再挑具体工具。

• src/Tool.ts — Tool 接口定义
  • Tool 类型结构（name、description、inputSchema、call）
  • findToolByName、toolMatchesName 工具函数
• src/tools.ts — 工具注册表
  • 工具列表组装逻辑
  • 条件加载（feature flag、USER_TYPE）
• 具体工具实现（挑选 2-3 个深入阅读）：
  • src/tools/BashTool/ — 执行 shell 命令，最常用的工具
  • src/tools/FileReadTool/ — 读取文件，简单直观，适合理解工具模式
  • src/tools/FileEditTool/ — 编辑文件，理解 diff/patch 机制
  • src/tools/AgentTool/ — 子 Agent 机制，较复杂但核心

---

第四阶段：上下文与系统提示

理解 Claude 如何"知道"项目信息、用户偏好等上下文。

• src/context.ts — 系统/用户上下文构建
  • git 状态注入
  • CLAUDE.md 内容加载
  • 内存文件（memory）注入
  • 日期、平台等环境信息
• src/utils/claudemd.ts — CLAUDE.md 发现与加载
  • 项目层级搜索逻辑
  • 多级 CLAUDE.md 合并

---

第五阶段：UI 层（按兴趣选读）

理解终端 UI 的渲染机制（React/Ink）。

• src/components/App.tsx — 根组件，Provider 注入
• src/state/AppState.tsx — 全局状态类型与 Context
• src/components/permissions/ — 工具权限审批 UI
• src/components/messages/ — 消息渲染组件

---

第六阶段：外围系统（按需探索）

• src/services/mcp/ — MCP 协议（Model Context Protocol）
• src/skills/ — 技能系统（/commit 等斜杠命令）
• src/commands/ — CLI 子命令
• src/tasks/ — 后台任务系统
• src/utils/model/providers.ts — 多 provider 选择逻辑

---

学习笔记

关键设计模式

模式	位置	说明
快速路径	cli.tsx	按开销从低到高逐级检查，减少不必要的模块加载
动态 import	cli.tsx / main.tsx	await import() 延迟加载，优化启动时间
feature flag	全局	feature() 永远返回 false，所有内部功能禁用
React/Ink	UI 层	用 React 组件模型渲染终端 UI
工具循环	query.ts	AI 返回工具调用 → 执行 → 结果回传 → 继续，直到无工具调用
AsyncGenerator 链	query.ts → claude.ts	yield* 透传事件流，形成管道
State 对象	query.ts queryLoop	循环间通过不可变 State + transition 字段传递状态
StreamingToolExecutor	query.ts	API 流式返回时并行执行工具
Withheld 消息	query.ts	暂扣可恢复错误，恢复成功则吞掉
withRetry	claude.ts	429/500/529 自动重试 + 模型降级
Prompt Caching	claude.ts	缓存系统提示和历史消息，减少 token 消耗

需要忽略的内容

• _c() 调用 — React Compiler 反编译产物
• feature('...') 后面的代码块 — 全部是死代码
• tsc 类型错误 — 反编译导致，不影响 Bun 运行
• packages/@ant/ — stub 包，无实际实现