Claude Code 源码架构
核心价值提炼

Claude Code 是 Claude 官方 CLI 的开源可读源码（约 1900 文件 / 51 万行，Bun + TypeScript，终端 UI 用 React + Ink）。整套架构围绕三个核心抽象展开：异步生成器做脊柱、消息数组做历史、工具契约做能力边界。

三层同心圆

每一层都是一个 AsyncGenerator<Message>，外层用 yield* 把内层的消息流「接」出来。没有回调地狱，天然背压，模型输出 / 工具执行 / 对外 SDK 消息全部从同一根管子流过。

flowchart TB
    subgraph L1
        direction TB
        title1["会话/回合编排
QueryEngine.submitMessage()"]
        desc1["跨回合状态 · 组装 system prompt + 上下文
翻译成对外 SDK 消息"]
        subgraph L2
            direction TB
            title2["Agent 主循环 · query.ts queryLoop()
—— 脊柱"]
            desc2["一次 while 迭代 = 一次模型调用
+ 它请求的整批工具"]
            subgraph L3
                direction TB
                title3["模型 + 工具
callModel / StreamingToolExecutor"]
                desc3["流式 API 调用 · 工具的调度/权限/执行"]
            end
        end
    end
    desc1 -.->|"依赖注入接缝：callModel / autocompact / uuid 全可注入"| desc2
      

万物皆消息

整个系统几乎不区分「对话历史」和「状态」——绝大多数跨回合要记住的东西，都被编码成历史里的一条消息。历史始终是一维的 Message[]，可随意切片、压缩、持久化。

八条贯穿全局的设计决策

把 18 个子系统摊开看，同样的几条原则一遍遍出现——它们才是「为什么好用」的真正答案。

主循环是整个系统的地基：组装上下文 → 调模型 → 收 tool_use → 跑工具 → 拼历史 → 再来一轮。它用一个 while(true) 而非递归，跨迭代状态放进单个 State 对象。

单回合控制流

flowchart TD
    A["① 准备消息窗口
tool-result 预算 / micro-compact / autocompact"] --> B["② 流式调用模型
deps.callModel · for await 消费"]
    B --> C["③ 边流边收 tool_use block
只要有一个 → needsFollowUp = true"]
    C --> D{needsFollowUp?}
    D -->|否：模型不再要工具| E["return completed
循环终止"]
    D -->|是| F["④ 执行工具
产出 tool_result（本质是 user 消息）"]
    F --> G["⑤ 拼下一回合历史
[...本轮消息, ...assistant, ...toolResults]"]
    G -->|turnCount++| A
      

恢复机制家族：可恢复错误一律先「扣住」

主循环把「重试 / 恢复」实现为若干种特殊的 continue（写进 State.transition），把「终止」收敛成十来种带 reason 的 return。三套恢复与两套重试是本章主线：

跨回合状态的分层

一个 agentic 系统的「记忆」分成两层：进程内跨回合状态（QueryEngine 实例字段），和磁盘上的持久转录（~/.claude/projects/<cwd>/<sessionId>.jsonl）。resume 的唯一真相来源是 JSONL。

一个工具在 Claude Code 里不是一个函数，而是一份契约：要能把自己序列化成发给模型的 schema、能自证输入合法、能自证权限、能声明并发语义、能执行并产出结果、能把结果映射成 API 的 tool_result。新增一个工具 = 实现一份契约，编排 / 权限 / 持久化 / UI 全部是面向接口的通用代码。

buildTool：fail-closed 的默认值

buildTool(def) 把 7 个默认方法补齐成完整契约，默认值刻意保守：

工具池：为 prompt 缓存偏执

从「一堆 Tool 对象」到「发给 API 的 tools 数组」有一条流水线，隐藏主轴是 prompt 缓存——工具块渲染在服务端 position 2，任何一个字节抖动都会击穿约 11K token 的工具块及其后全部缓存。三条互相纠缠的不变量：

执行与并发：边流边跑

新版 StreamingToolExecutor 不等一轮 block 收齐：模型每 stream 出一个 block 就 addTool，满足并发条件立即开跑。三条不变量：并发安全工具可并行、非并发工具独占、结果按接收顺序回吐。Read 恒并发安全、Write 恒独占、Bash 视命令是否只读而定（ls 安全，git commit 独占）。

stateDiagram-v2
    [*] --> queued: addTool
    queued --> executing: canExecuteTool 通过
    queued --> queued: canExecuteTool 不通过
    executing --> completed: collectResults 结束
    completed --> yielded: getCompletedResults 吐出
    yielded --> [*]
      

权限决策引擎回答一个问题：模型请求调用某个工具、带着一组具体入参，允许吗？答案只有 allow / ask / deny 三种终态。安全语义的全部真相，编码在步骤编号的顺序里。

确定性流水线 + 模式后处理

引擎分两层：hasPermissionsToUseToolInner 是纯确定性的规则流水线（1a→3），不发网络、不弹窗、不跑分类器；外层 hasPermissionsToUseTool 再对 ask 结果施加非确定性模式变换（dontAsk / auto 分类器 / headless 兜底）。

flowchart TD
    A["inner: 1a 整工具 deny?"] --> B{"deny?"}
    B -- yes --> D["return deny (最高优先级)"]
    B -- no --> C["1b 整工具 ask → 1c tool.checkPermissions()"]
    C --> E{"1d-1g 工具 deny / 交互 ask / content-ask / safetyCheck?"}
    E -- yes --> F["return deny / ask（bypass 也拦）"]
    E -- no --> G["2a bypassPermissions? → allow"]
    G --> H["2b 整工具 allow 规则 → allow"]
    H --> I["3 兜底 passthrough → ask"]
      

三条必须牢记的不变式

auto 模式：分级探针 + 分类器 + 熔断

auto 模式的核心矛盾是「既要无人值守自动放行、又不能对危险操作放水」。成本从低到高倒排：先零成本的规则/白名单 → 本地 acceptEdits 复算 → 最后才付分类器 API 调用。分类器结果默认 fail-closed（挂了就拦），并带「连续 3 次或累计 20 次拒绝 → 强制回落到人工」的熔断。

Claude Code 的多 Agent 建立在一个惊人简单的递归之上：AgentTool.call() 是一个工具，它的实现体又调用了一遍主循环 query()。复杂度集中在「隔离边界」与「结果如何回来」两个问题。

递归与上下文隔离：默认隔离、显式共享

每次递归都换一份隔离的 ToolUseContext，全部集中在 createSubagentContext() 一个函数：可变状态克隆或置空、queryTracking.depth 递增、agentId 全新。外部构建把 Agent 工具剔除出子池，递归被硬限制在深度 1。

结果回注：不是 await，而是通知队列

子 agent 跑完后，父 agent 不是「await 子 agent」，而是：子 agent 把结果写成一段 <task-notification> XML，塞进一个进程级全局队列；父 agent 在自己的 query loop 每轮工具调用结束时主动领取属于自己的通知，把它当成一条新到达的 user 消息注入下一次推理。

sequenceDiagram
    participant W as worker
    participant Q as commandQueue
    participant P as 父 query loop
    participant M as 模型
    W->>W: 收完最后一条 assistant
    W->>W: finalizeAgentTool
    W->>Q: enqueueAgentNotification
    Note right of Q: priority: later
    Note over P: 父 agent 下一轮工具调用结束
    P->>Q: 按 agentId 过滤领取通知
    Q-->>P: task-notification 消息
    P->>M: yield 成 user 消息
      

三个不变量：先转终态、后润色（completeAsyncAgent 永远早于 handoff 分类与 worktree 清理，防挂起拖住状态机）；notified 是唯一去重闩兼逐出前置（只通知一次、通知后才回收内存）；agentId scoping（主线程领 undefined，子 agent 领本 id 的通知，用户 prompt 永不外泄给子 agent）。

协调者模式 vs 团队：被一个 SendMessage 缝合的两套模型

这一章是整套架构「真正值钱」的地方。功能逻辑往往几十行就写完，真正的工程量在「如何让缓存前缀稳定」和「如何在不丢关键信息的前提下把 token 压下去」。

系统提示三段 × 物理四块

构建 API cache-key 前缀的三块内容是 systemPrompt / userContext / systemContext（每会话稳定）。而 systemPrompt 本身在发往 API 前又被切成 attribution header / CLI prefix / static / dynamic 四块，由 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 哨兵一分为二，只有静态块打 scope:'global' 跨 org 共享缓存。

上下文压缩：四路径，侵入性从轻到重

持久记忆：唯一跨会话存活的状态

持久记忆不是一个数据库，而是一个文件系统目录（memdir），围绕它有两条原则值得记住：记忆只存「无法从当前工程状态推导」的东西（代码模式、偏好、教训——grep/git/CLAUDE.md 就能查到的都不该存）；「共享落盘、独立控制」——写入按 UUID 游标推进（回合末后台 forked agent）、读取按会话字节封顶（回合首 Sonnet 选择器召回 ≤5 条）、索引注入按 GB flag 二选一，互不阻塞。

Token、成本与落盘：同一个工程律

三件咬合的事共享同一个约束——任何改变发给模型字节的决策都必须可确定性重放。Token 锚点（最后一次真实 usage + 之后 char/4 粗估）、成本的 sessionId 守卫、落盘的 wx 幂等、预算的 seenIds/replacements 冻结、resume 的逐字节重建——都是为了让「同一段历史无论跑几次进程，产出的 wire prefix 完全相同」，从而把 prompt 缓存命中率（= 省钱 + 省上下文）钉死。

可扩展性由三条正交通道构成，粒度、加载时机、谁定义各不相同。它们共享同一个不变式：能力可以无限扩展，而常驻上下文只按「发现清单」线性增长。

Skill 的三层渐进披露

Skill 通道把「渐进披露」做到了极致——三层披露逐层压榨常驻成本：frontmatter 常驻（只有 name / description / whenToUse 三字段计 token）→ paths 条件延迟（带 paths frontmatter 的条件 skill 连清单都不进，直到相关文件被触碰）→ 正文 invoke 时才加载。

插件：把三条通道打成可开关的分发包

插件是「一次打包多种组件（skills / hooks / MCP servers / commands / agents）」的容器。内置插件（@builtin）随二进制分发但可开关；marketplace 插件从 git 拉取、解析 plugin.json、以 sha 钉版本。插件提供的 skill 故意标 source:'bundled' 而非 'builtin'，以继续享受清单不截断、analytics 记名等 bundled 待遇。

把 19 篇文档蒸馏到最后，真正可以带走的是下面这些——它们不绑定 Claude Code 的特定实现，而是一个成熟 agentic 系统的共性答案。