Claude Code 源码还原版 (claude-code-sourcemap) 深度解析

背景

• 仓库地址：https://github.com/ChinaSiro/claude-code-sourcemap
• 版本：2.1.88
• 还原方式：通过 npm 发布的 @anthropic-ai/claude-code 包中遗留的 cli.js.map 文件，提取 sourcesContent 字段，100% 还原了未混淆的 TypeScript 源码。
• 文件规模：4756 个文件，其中 .ts/.tsx 源文件 1884 个，代码总量约 51 万行。
• 核心价值：这是一份官方真实商业级 Agent 的完整源码，而非教学 demo。它暴露了 Anthropic 在实际产品中如何处理多 Agent 协调、权限控制、上下文防撑爆、复杂工具链以及 API 代理回退等极具工程价值的细节。

⚡ TL;DR / 核心架构洞察

1. Agent 抽象层：不再是单一死循环，而是 Coordinator Mode（协调器模式）下的大脑+子工作节点模式（Swarm）。
2. Context Management (上下文极限拉扯)：用了极其复杂的策略（Micro-compact, Snip, AutoCompact, ContextCollapse），甚至专门给 prompt_too_long 写了重试。
3. Tools 生态：内置了 30+ 种工具，包括完整的 MCP（Model Context Protocol）生态接入，甚至支持从浏览器插件 (claudeInChrome) 获取上下文。
4. React Ink 终端 UI：整个 CLI 界面全是用 React + Ink 写的，不是纯命令行打字机。

详细过程：源码级拆解

1. 核心大循环 (Query Engine)

核心引擎在 src/QueryEngine.ts 和 src/query.ts。

• 与简单的 "发请求 -> 执行工具 -> 发请求" 不同，它的循环包含了 StreamEvent 状态机。
• Streaming 容错机制（在 services/api/claude.ts 2280行附近）：它专门处理了网络或代理引起的 SSE 流断裂。如果收到意外的 message_start（你在聊天里问的那个报错），说明流拼接错误，它有专门的 FallbackTriggeredError 尝试回退到非流式请求。
• Task 系统 (Task.ts)：一切执行都是 Task。包括 local_bash、local_agent、remote_agent 甚至 in_process_teammate（多代理通讯）。

2. Coordinator Mode (协调器/代理集群模式)

源码目录 src/coordinator/coordinatorMode.ts 暴露了一个高级特性。

• 当 COORDINATOR_MODE 激活时，当前 Claude 不是干活的，而是包工头（Coordinator）。
• 它的 System Prompt 会变成：“You are a coordinator. Your job is to direct workers to research, implement and verify... Do not trivially report file contents... Give them higher-level tasks.”
• 它可以调用 AgentTool 去 Spawn (孵化) 新的 Worker Agent，并且可以分配不同的 MCP 工具给特定 Worker。
• Worker 的输出会通过 <task-notification> 伪装成 user 消息传回给 Coordinator。

3. Context 防撑爆与截断策略 (Compact)

这是商业级 Agent 和玩具 Agent 差距最大的地方（src/services/compact/ 目录下有几十个文件）。

• AutoCompact：设定了软硬阈值（比如模型窗口是 200k，它会在 180k 时触发）。
• SnipCompact：历史片段剪裁。
• 触发 Compact 时，它会起一个旁路请求（甚至用另一个更便宜/快速的模型），让模型“Summarize the conversation so far in a concise paragraph, preserving key decisions, file paths...”，然后把长对话替换成一条带 [Previous conversation summary] 的压缩消息。

4. 权限与安全边界 (Permission & Sandbox)

在 src/utils/permissions/ 下有极细的分类。

• 不是简单的“一刀切”同意或拒绝，而是分为 read_only、destructive。
• Auto Mode 状态机：即便开了 auto-approve，遇到高危正则匹配（如 rm -rf，git push -f），依然会拦截。
• 如果配置了沙箱 (shouldUseSandbox.ts)，Bash 命令会在独立的容器或虚拟环境中执行。

5. 丰富的工具集 (Tools)

在 src/tools/ 下发现了 39 个核心工具，挑几个有意思的：

• FileEditTool：不仅能全量覆盖，还支持内部的 sedEditParser.ts 也就是正则/块级别替换，极大节省 token。
• LSPTool：竟然内嵌了 LSP 客户端，可以直接跟本地代码编辑器的 Language Server 交互，获取类型定义和 Symbol。
• MCPTool：标准化接入外部 Model Context Protocol 资源。
• SyntheticOutputTool：用于让子 Agent 生成“结构化/伪造”的中间输出。
• SleepTool：主动睡眠等待（常见于轮询任务）。

结论与启示

claude-code-sourcemap 是一座金矿。它告诉我们一个能卖钱的 Coding Agent 需要做多深：

1. 不要试图在一个 Prompt 里塞下整个世界：引入多 Agent 协调（Coordinator + Workers）。
2. Context 不是无限的：必须做实时的 Token 预算核算（Token Budget）和动态压缩。
3. 工程上的鲁棒性：处理 API 529 过载、流断开、正则表达式执行超时、死循环。

相比于你刚才看的 claude-code-from-scratch（1300 行的玩具模型），这个才是真实世界的工业级实现。建议重点阅读它的 coordinatorMode.ts 和 compact.ts，对你未来自己写 Agent 会有极大的架构启发。