《Claude Code 源码解读》EP01:源码全景

导读

打开 Claude Code 源码，真正调 AI 的代码不到 1 万行。剩下 98.4% 是什么？这一集完整拆解。

1.6% vs 98.4%：打开源码的第一眼

Claude Code v2.1.88版本的代码，总共有 512,664 行 TypeScript，分布在 1,884 个文件中。直接调用 Anthropic API 的代码，只有约 8,200 行——占比 1.6%。

剩下的 98.4% 是什么？不是模型调优，不是 prompt 打磨——是让 AI 可靠工作的那套工程系统：权限、安全、压缩、工具、UI、Hooks、沙箱。

在调 AI，但真正决定产品质量的不是模型有多聪明，而是 Harness 有多可靠。

这 98.4% 的代码可以清晰地分成三大块，每一块有完全不同的使命：

超过一半的代码在做同一件事——防止模型做错事。

让 Agent 能做事。不是一句"能做事"就完了——tools 负责读写搜索执行（43+ 工具），services 管理 API、压缩、MCP，commands 提供 100+ 斜杠入口。

最容易被忽略的第三层——自研 Ink 渲染引擎（90 个文件）、bridge 负责 VS Code + JetBrains 双向通信、cli 负责入口和会话管理。没有这一层，Agent 有枪没路。

这 9 大模块最后汇入同一个 queryLoop，串成一次完整执行。

用户敲下回车之后发生了什么？四阶段：Hook 拦截 → QueryEngine 组装 → queryLoop 循环 → SessionEnd 终止。queryLoop 内部，模型返回后依次经过：解析 tool_use → tools 执行 → services 压缩 → hooks 更新 UI。

进入 queryLoop 内部，模型返回后依次经过 5 个步骤：

200K token 上下文窗口是所有设计的隐藏约束。系统准备了 4 级压缩：从最便宜的截断开始，逐级换代价换空间——直到最后一招 LLM 摘要。

queryLoop 不是简单的 while(true)——有 7 个恢复站点兜住错误，10 种终止条件控制退出，是一个隐式状态机。

用 30 行就能写出一个玩具 Agent 循环，但要覆盖权限、压缩、恢复、工具结果和 UI——同样的循环膨胀到 1,800 行。

这 60 倍差距，就是 Harness Engineering 的全部价值。

这些代码不是随便堆出来的。贯穿 Claude Code 的，是五条很强的工程原则，每条都能在代码中找到几十处证据：

① 工具即能力边界：Agent 能做什么完全由工具集决定。没有任何后门让模型绕过工具直接碰文件系统——只能生成 JSON 请求，由 Harness 检查、执行、记录。

② Fail-closed：遗忘不应该导致漏洞。isConcurrencySafe / isReadOnly / isDestructive 全部默认 false——忘记标记只会更保守，不会跳过安全检查。

③ Context Engineering > Prompt Engineering：不是写一段好的指令——是构建信息管理系统：分段缓存 System Prompt、动态注入 Git 与 CLAUDE.md、四级压缩管道、四种记忆。

④ 可组合性：核心机制是可复用积木——主 Agent、子 Agent、Fork、Team Worker 全部复用同一个 queryLoop()；修一个 bug 全员受益。

⑤ 编译时消除 > 运行时判断：feature('X') ? [Tool] : [] 在构建时被 tree-shake——未启用的代码不在 bundle 中，物理上不可能被触发。

Claude Code 能执行命令、读写文件，安全是前提。Fail-closed 落到安全上，就是六层纵深防御——从软约束开始，一层层往更硬的系统边界收紧。

外层有 CLAUDE.md 指导、Permission Rules 和 Hooks；中间有语义分类器（AI 辅助判定）；内层是 Sandbox 进程隔离和写死在代码里的 Hardcoded Denials。

关键不是每层都完美，而是任意一层失效时，下一层仍然能兜住风险。

Claude Code 内部流转的不是简单的用户说、模型答。它有 8 种消息类型：UserMessage、AssistantMessage、AttachmentMessage、SystemMessage、SystemLocalCommand、ProgressMessage——以及两个特别关键的：

ToolUseSummaryMessage：把老化的工具结果压成摘要——上下文不会被历史日志撑爆，但模型仍然保留必要线索。

TombstoneMessage：消息被删除后保留占位。内容没了，ID 还在，整个消息链的引用关系不会崩。

两个很小但很关键的消息——保持状态在压缩和删除中始终一致。

50 万行代码、1,884 个文件、43+ 工具、100+ 命令——这就是 Claude Code 的源码全景。

记住那句话：真正决定 Agent 质量的，不是模型多聪明，而是 Harness 多可靠。

下一集 EP02，我们进入 queryLoop 的心脏，看它怎样把一次请求跑完。

Claude Code Deep Dive · EP01 · 源码全景#ClaudeCode#源码解读#HarnessEngineering