Claude Code 源码分析手册
基于 Claude Code 开源快照
v2.1.88的深度源码分析。
唯一真相来源：claude-code-opensource/src/。
全书 12 章 89 篇文章，从核心运行时到隐藏内幕的完整覆盖。
阅读指南（序言） — 手册定位、目标读者、阅读路径与文章结构说明
第 01 章 — 核心运行时
会话从启动到终止的完整流程，Agentic Loop 的推理循环，以及上下文窗口的动态管理机制。
| # | 文章 | 主题 |
|---|---|---|
| 1 | Agentic Loop | 核心推理循环：反馈-决策-执行 |
| 2 | CLI 模式与参数 | 启动模式和关键参数 |
| 3 | 会话启动生命周期 | SessionStart 钩子与环境装配 |
| 4 | 会话收口生命周期 | Stop 钩子与后台异步治理 |
| 5 | 上下文窗口管理 | Prompt 装配、剪裁与压缩重组 |
| 6 | 回撤与检查点 | 文件级快照与对话记忆的协同回滚 |
| 7 | 会话恢复与选择器 | Resume / Fork 策略与 Session Picker |
| 8 | Bare 模式 | 零配置隔离态 |
| 9 | 远程 Web 会话 | 会话迁移与跨端执行协议 |
| 10 | Prompt 建议 | 首轮引导与停轮后预测 |
第 02 章 — 权限与安全
应用层审批与操作系统沙箱的双层防御体系，覆盖全部运行模式。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 权限与沙箱 | 双层防御架构总览 |
| 2 | 权限规则 | 细粒度 allow/ask/deny 匹配引擎 |
| 3 | Default 与 AcceptEdits 模式 | 默认模式与编辑接受模式的运行时行为 |
| 4 | Auto Mode | 基于分类器的自动化审批 |
| 5 | Bypass 模式 | 应用层审批绕过 |
| 6 | DontAsk 模式 | 非交互环境的静默拦截 |
| 7 | Plan Mode | 只读思考模式 |
| 8 | Bash 权限规则 | 基于 AST 的命令语义审计 |
| 9 | 认证优先级 | 多路径凭证的互斥裁决 |
第 03 章 — Hook 系统与扩展
事件驱动的扩展总线，贯穿会话全生命周期的 9 个可编程观测点。
| # | 文章 | 主题 |
|---|---|---|
| 1 | Hook 系统架构 | 事件分派、异步执行与指令协议 |
| 2 | Session Hooks | SessionStart / SessionStop 触发时机 |
| 3 | PreToolUse | 工具调用前的同步守卫 |
| 4 | PostToolUse | 工具调用后的结果审查与回填 |
| 5 | PermissionRequest | 审批劫持与远端旁路 |
| 6 | UserPromptSubmit | 输入预处理网关 |
| 7 | InstructionsLoaded | 系统 Prompt 动态注入 |
| 8 | CwdChanged / FileChanged | 环境变更的响应式补丁 |
| 9 | WorktreeCreate / Remove | Git Worktree 生命周期钩子 |
第 04 章 — 工具与 Agent 协作
从单个工具的执行逻辑到多 Agent 的协作模式。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 工具全景 | 超越 Bash 的精锐功能组 |
| 2 | Bash 工具行为 | 每次新进程 + snapshot 注入 + cwd 回写 |
| 3 | SubAgent 架构 | 侧链代理的派生与隔离 |
| 4 | Agent Teams | 共享账本与多后端编排 |
| 5 | 后台进程 | 托管任务运行时与 Ctrl+B 后台化 |
| 6 | 任务管理 | Task 列表、状态机与跨会话持久化 |
| 7 | 定时任务 | Cron 调度与云端远程触发 |
| 8 | Computer Use | 内嵌 MCP 与桌面控制协议 |
| 9 | 语音听写 | STT 录音、转写与光标回填 |
第 05 章 — MCP 协议
Model Context Protocol 的实现、认证与扩展生态。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 协议与客户端架构 | JSON-RPC 分发与传输层 |
| 2 | 注册表与服务发现 | 分层配置聚合与 Tool Search |
| 3 | OAuth 与认证 | OAuth 流程与 Headers Helper |
| 4 | 安全与信任模型 | 三层防御体系 |
| 5 | Elicitation 交互 | Server 发起的结构化问询 |
| 6 | 资源与 Prompt | 只读资源与动态命令适配 |
第 06 章 — 插件系统
插件的物化、缓存、版本控制、市场机制与 Skills 框架。
| # | 文章 | 主题 |
|---|---|---|
| 1 | Skills 系统 | 用户可扩展的能力框架 |
| 2 | 插件缓存与路径解析 | 物化模型与安装登记 |
| 3 | 版本解析 | 版本计算优先级与发布渠道 |
| 4 | 市场与发现 | 配置意图到物化的调和 |
| 5 | 本地插件测试 | --plugin-dir 旁路注入 |
第 07 章 — 配置与智能管理
多层配置的装配、合并、远程控制与动态特性管理。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 设置优先级 | 五层配置的 Deep-Merge 链 |
| 2 | 全局配置状态 | CLI 内部持久化数据库 |
| 3 | CLAUDE.md 与规则 | 指令分层装配与条件触发 |
| 4 | 环境变量 | 运行时行为的底层调谐 |
| 5 | Feature Flags | GrowthBook 远程配置 |
| 6 | 服务器托管设置 | Fail-open 策略同步 |
| 7 | 模型选择 | 白名单匹配、别名与 Provider 路由 |
| 8 | Prompt 缓存 | 服务端 KV 缓存与断点策略 |
| 9 | 输出样式 | System Prompt 身份层改写 |
| 10 | 发布渠道 | 版本轨道闸门 |
| 11 | Fast Mode | 请求层速度标记与冷却降级 |
第 08 章 — 界面与交互
终端渲染引擎、快捷键系统、Vim 模式与视觉定制。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 全屏渲染 | AlternateScreen 与虚拟滚动 |
| 2 | 快捷键 | 上下文感知的输入路由 |
| 3 | 状态栏 | 命令钩子驱动的状态显示 |
| 4 | 终端配置 | 宿主终端适配与按键补丁 |
| 5 | Vim 模式与主题 | Vim 键绑定与语义色彩定制 |
第 09 章 — 生态集成
IDE、浏览器、桌面/Web 平台、远程控制与事件通道。
| # | 文章 | 主题 |
|---|---|---|
| 1 | IDE 集成 | 实例探测与 LSP 语义分析 |
| 2 | Chrome 扩展 | Native Messaging 与动态 MCP |
| 3 | 桌面与 Web 平台 | CLI 引擎的云端化与多端协同 |
| 4 | 远程控制 | REPL Bridge 双向桥 |
| 5 | Channels | 外部事件异步注入协议 |
第 10 章 — 文件系统与工作流
工作目录管理、Git Worktree 协作、自动记忆与自主文档维护。
| # | 文章 | 主题 |
|---|---|---|
| 1 | /add-dir 命令 | 工作边界动态扩展 |
| 2 | Git Worktrees | 隔离会话与播种逻辑 |
| 3 | 自动记忆 | MEMORY.md 索引、memdir 结构化存储与团队共享 |
| 4 | AutoDream | 后台记忆整合与自我完善 |
| 5 | Magic Docs | 自主文档维护与同步 |
| 6 | 搜索与导航 | ripgrep + LSP 的导航流水线 |
| 7 | Skills 发现 | 路径回溯的按需加载 |
第 11 章 — 分析与遥测
事件管线、成本监控与错误分类的完整可观测性体系。
| # | 文章 | 主题 |
|---|---|---|
| 1 | 事件管线 | 双 Sink 分流与本地净化 |
| 2 | 监控与成本 | OTel 监控与 Token 追踪 |
| 3 | 错误分类 | 隐私隔离与网络归类 |
第 12 章 — 隐藏内幕
五十万行代码里那些不在官方文档中的秘密：未上线的彩蛋、内部员工专属工具、安全防线与底层移植。
| # | 文章 | 主题 |
|---|---|---|
| 1 | Buddy 伙伴系统 | 确定性哈希生成的终端电子宠物 |
| 2 | Undercover 模式 | 公开仓库中的身份保护机制 |
| 3 | 内部用户门控 | USER_TYPE=ant 的编译期分流架构 |
| 4 | Coordinator 模式 | 多 Worker 编排的军团作战模式 |
| 5 | Upstream 代理 | CCR 容器的 MITM TLS 中继 |
| 6 | Insights 命令与情绪检测 | 用 LLM 分析用户行为和情绪 |
| 7 | 调试子系统 | 分层日志、过滤器与启动性能分析 |
| 8 | 内部专属技能 | Ant 专属的调试与运维工具集 |
| 9 | 隐藏的运行时机制 | AutoDream、Advisor、Tips 与终端录制 |
| 10 | Native TypeScript 移植 | 消灭原生依赖的跨平台哲学 |
按主题横向索引
如果你是按问题找答案的读者，以下索引可以帮你快速定位跨章节的相关文章。
安全与权限
| 文章 | 章节 | 关注点 |
|---|---|---|
| 权限与沙箱 | Ch02 | 双层防御架构总览 |
| 权限规则 | Ch02 | allow/ask/deny 匹配引擎 |
| Bash 权限规则 | Ch02 | 命令语义审计与 AST 分析 |
| Auto / Bypass / DontAsk 模式 | Ch02 | 各运行模式的安全行为 |
| Hook 系统架构 | Ch03 | 安全审计扩展点 |
| PermissionRequest Hook | Ch03 | 审批劫持与旁路 |
| MCP 安全与信任模型 | Ch05 | 三层 MCP 防御 |
| 认证优先级 | Ch02 | 凭证裁决 |
| 内部用户门控 | Ch12 | 编译期分流与 DCE |
| Undercover 模式 | Ch12 | 身份保护机制 |
Agentic Loop 与会话生命周期
| 文章 | 章节 | 关注点 |
|---|---|---|
| Agentic Loop | Ch01 | 核心推理循环 |
| 上下文窗口管理 | Ch01 | Prompt 装配与压缩 |
| 会话启动生命周期 | Ch01 | 启动装配流程 |
| 会话收口生命周期 | Ch01 | 停止与清理 |
| 会话恢复与选择器 | Ch01 | Resume / Fork |
| 回撤与检查点 | Ch01 | 快照与回滚 |
| Session Hooks | Ch03 | 会话级钩子 |
工具系统与多 Agent 协作
| 文章 | 章节 | 关注点 |
|---|---|---|
| 工具全景 | Ch04 | 内置工具集总览 |
| Bash 工具行为 | Ch04 | 进程模型与 CWD 回写 |
| SubAgent 架构 | Ch04 | 子代理派生与隔离 |
| Agent Teams | Ch04 | 多 Agent 编排 |
| Coordinator 模式 | Ch12 | 军团作战模式 |
| PreToolUse | Ch03 | 工具执行前守卫 |
| PostToolUse | Ch03 | 工具执行后审查 |
配置与环境管理
| 文章 | 章节 | 关注点 |
|---|---|---|
| 设置优先级 | Ch07 | 五层 Deep-Merge |
| CLAUDE.md 与规则 | Ch07 | 指令分层装配 |
| 环境变量 | Ch07 | 运行时调谐 |
| Feature Flags | Ch07 | GrowthBook 远程开关 |
| 全局配置状态 | Ch07 | 持久化数据库 |
| 服务器托管设置 | Ch07 | Fail-open 策略 |
扩展与插件
| 文章 | 章节 | 关注点 |
|---|---|---|
| MCP 协议与客户端架构 | Ch05 | JSON-RPC 传输层 |
| MCP 注册表与服务发现 | Ch05 | 配置聚合 |
| Skills 系统 | Ch06 | 能力框架 |
| 插件缓存与路径解析 | Ch06 | 物化模型 |
| Skills 发现 | Ch10 | 路径回溯加载 |
| Hook 系统架构 | Ch03 | 可编程扩展点 |
调试与可观测性
| 文章 | 章节 | 关注点 |
|---|---|---|
| 事件管线 | Ch11 | 双 Sink 分流 |
| 监控与成本 | Ch11 | OTel 与 Token 追踪 |
| 错误分类 | Ch11 | 隐私隔离与归类 |
| 调试子系统 | Ch12 | 分层日志与性能分析 |
| 内部专属技能 | Ch12 | Ant 调试工具集 |
审计产物：
_audit/目录下存放有完整的审计报告（AUDIT-REPORT.md）、重组计划（REORG-PLAN.md）、
Gap 分析报告（GAP-ANALYSIS.md）及三份事实核查报告（factcheck-01-02.json、factcheck-03-04.json、factcheck-05-11.json）。