Dive into Claude Code它如何工作，以及为什么这样设计

七个组件连成一条从左到右的主干：用户 → 接口 → agent loop → 权限系统 → 工具 → 执行环境，状态与持久化在旁边记录一切。所有入口最终汇进同一个循环。

七个组件各自对应到具体源码：

1. 用户：提交 prompt、批准权限、审阅输出。
2. 接口层：交互式 CLI、无头 CLI（claude -p）、Agent SDK，以及 IDE／桌面／浏览器。所有界面喂进同一个循环。
3. agent loop：模型调用、工具分发、结果收集的迭代周期，实现为 query.ts 里的 queryLoop() 异步生成器。
4. 权限系统：拒绝优先的规则求值（permissions.ts）、auto-mode 机器学习分类器、基于 hook 的拦截（types/hooks.ts）。
5. 工具：最多 54 个内置工具（19 个无条件，35 个受功能开关与用户类型影响），由 assembleToolPool() 组装，再与 MCP 提供的工具合并。
6. 状态与持久化：以追加为主的 JSONL 会话记录（sessionStorage.ts）、全局 prompt 历史（history.ts）、subagent 的 sidechain 文件。
7. 执行环境：带可选 sandbox 的 shell 执行（shouldUseSandbox.ts）、文件系统操作、网络抓取、MCP 服务器连接、远程执行。

把这七个组件展开，会得到五层子系统。这张图是理解后续每一站的坐标系——每一站都落在其中某一层里。

用户在终端敲下「修好 auth.test.ts 里失败的测试」。这句话进入的是一个反应式循环——每一轮只承诺一次动作序列，不回溯，不搜索多条路径。

整个单轮流程如下图。请求经上下文装配进入模型，工具请求穿过权限网关，工具结果回灌循环，compaction 在上下文吃紧时介入。这张图是第一部分剩下九站的路线图。

这个循环遵循 ReAct 模式：模型生成推理与工具调用，harness 执行动作，结果喂给下一轮迭代。

Anthropic 自己的文档归纳了五种可组合的工作流模式——prompt 链接、路由、并行化、编排者－工作者、评估者－优化者。Claude Code 主要在 subagent 委派上用了编排者－工作者模式（见 09），核心循环则保持反应式。

模型看到什么，决定它能做什么。上下文窗口由九类来源拼装而成，有的在开始时一次装好，有的在这一轮进行中陆续注入——所以上下文不是静态的，它在一轮之内还会长。

九类来源

1. 系统提示：含 output style 的修改，以及 --append-system-prompt 的内容。
2. 环境信息：经 getSystemContext() 取得 git 状态（远程模式或禁用 git 指令时跳过）。每个会话记忆一次。
3. CLAUDE.md 层级：经 getUserContext() 载入四级指令文件，同样有记忆。
4. 路径域规则：条件规则与目录匹配规则，只有 agent 读到匹配目录里的文件时才懒加载。
5. auto memory：与情境相关的记忆条目，异步预取。
6. 工具元数据：skill 描述、MCP 工具名，以及经 ToolSearch 按需取得的延迟工具定义。
7. 对话历史：向前携带，受 compaction 影响。
8. 工具结果：文件读取、命令输出、subagent 摘要。
9. compact 摘要：替换掉更早的历史片段。

CLAUDE.md 的四级层级

记忆系统遵循一条设计原则：存下来的上下文应当能被用户检查和编辑。所以它是纯文本 Markdown，不是结构化配置，也不是数据库条目。

1. 受管记忆（如 Linux 上 /etc/claude-code/CLAUDE.md）：面向所有用户的系统级策略。
2. 用户记忆（~/.claude/CLAUDE.md）：私人全局指令。
3. 项目记忆（CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md）：随代码库进版本控制的指令。
4. 本地记忆（CLAUDE.local.md）：被 gitignore，用于私人的项目专属指令。

文件发现从当前目录一路向上遍历到根，越靠近当前目录的优先级越高——实现方式是后加载。文件按「优先级的反序」装入，因为后装入的能获得更多模型注意力。

这意味着模型的指令集可能在一次对话中演化：当 agent 探索到代码库的新区域，那里的规则才会加载进来。

记忆文件支持 @include 指令做模块化组合（processMemoryFile()），语法变体包括 @path、@./relative、@~/home、@/absolute。指令只在叶子文本节点生效，不进代码块。实现上被包含的文件追加在包含者之后，循环引用通过记录已处理路径来避免，不存在的文件静默忽略。

检索：没有用向量

系统不使用嵌入或向量相似度索引来检索记忆。它用一次 LLM 扫描记忆文件的头部，按需挑出最多五个相关文件，粒度是文件级而非条目级。基于嵌入的方案能更有选择性地取回单条记忆，代价是可审查性下降，以及需要维护一套索引基础设施。

模型这一轮能看到哪些工具，不是固定的。四种扩展机制在 agent loop 的不同位置挂载，它们的排序依据是一个很实际的量：各自要吃掉多少上下文。

while (true) {
  a ctx = assemble(history, memory, tools)
  b out = model(ctx)
    if (out.isTextOnly())
      stopped = run_stop_hooks(out)   # 可否决
  c res = execute(out.toolUse)
    history.push(res)
}

一轮开始时，模型看到的不只是 BashTool、FileReadTool 这类内置工具，还有来自 MCP 服务器的数据库查询工具、来自 .claude/skills/ 的自定义 lint skill，以及已安装 plugin 贡献的工具。它们通过四种机制在循环的不同点接入。

四种机制

MCP 服务器。Model Context Protocol 是主要的外部工具接入路径。MCP 服务器可从项目、用户、本地、企业多个作用域配置，运行时再并入 plugin 与 claude.ai 提供的服务器。客户端支持 stdio、SSE、HTTP、WebSocket、SDK，以及 IDE 专用变体。每个已连接服务器贡献一组 MCPTool 对象。

plugin。它同时是打包格式与分发机制。清单模式接受十类组件：命令、agent、skill、hook、MCP 服务器、LSP 服务器、output style、channel、settings、用户配置。加载器校验清单，再把每个组件路由到各自的注册表。一个 plugin 包因此能同时扩展多种组件类型，这使它成为第三方扩展的主要分发载体。

skill。每个 skill 由带 YAML frontmatter 的 SKILL.md 定义，解析 15 个以上字段，包括显示名、描述、附加工具授权、参数提示、模型覆盖、执行上下文（fork 表示隔离执行）、关联的 agent 定义、投入档位与 shell 配置。skill 可以定义自己的 hook，在被调用时动态注册。调用时 SkillTool 这个元工具把 skill 的指令注入上下文。

hook。源码定义了 27 个 hook 事件，覆盖工具授权、会话生命周期、用户交互、subagent 协调、上下文管理、工作区事件与通知。其中 15 个有事件专属的输出模式，支持权限决策、上下文注入、输入修改、MCP 结果变换与重试控制。持久化的 hook 命令有四种类型：shell 命令、LLM prompt、HTTP、agentic verifier。

为什么是四种而不是一种

每多一种机制，开发者要学的表面积就更大。答案在上下文开销上：

这条递进的开销序列（hook 零、skill 低、plugin 中、MCP 高）意味着便宜的扩展可以大规模铺开而不耗尽上下文窗口，昂贵的则留给真正需要新工具面的场合。单一机制无法在不迫使扩展作者做出无谓妥协的前提下，跨越从零开销事件处理器到 schema 密集的外部服务集成这整个跨度。

代价是学习曲线：面对一个具体的集成任务，开发者要先判断该用哪种机制。

工具池的五步组装

assembleToolPool() 在源码注释里被称为「合并内置工具与 MCP 工具的唯一事实来源」。

1. 枚举基础工具。getAllBaseTools() 返回最多 54 个工具的数组：19 个总是包含（如 BashTool、FileReadTool、AgentTool、SkillTool），另外 35 个依功能开关、环境变量与用户类型条件包含。
2. 模式过滤。getTools() 按模式过滤。在 CLAUDE_CODE_SIMPLE 模式下只有 Bash、Read 和 Edit 可用（REPL 分支则是 REPLTool），必要时另加 coordinator 工具。每个工具的 isEnabled() 方法会被调用做运行时可用性检查。
3. 拒绝规则预过滤。filterToolsByDenyRules() 在任何调用之前，就把整体被拒的工具从模型视野里剥掉。
4. MCP 工具并入。来自 appState.mcp.tools 的工具先经拒绝规则过滤，再与内置工具合并。
5. 去重。按名称去重，内置工具优先于 MCP 工具。

基于 agent 的扩展（.claude/agents/*.md 与 plugin 贡献的 agent）不在这四种机制里，因为它们的性质根本不同：它们创建新的、隔离的上下文窗口，而不是扩展当前这个。这部分见 09。

每一轮都走同一条九步固定序列。这一步是全文最反直觉的地方：模型只负责推理，绝不直接接触文件系统、shell 或网络——它对外界唯一的接口是结构化的 tool_use 协议。

九步查询流水线

1. 设置解析。queryLoop() 解构不可变参数，包括系统提示、权限回调、模型配置。
2. 可变状态初始化。单个 State 对象存放跨迭代的全部可变状态：消息、工具上下文、compaction 追踪、恢复计数器。循环的七个 continue 点各自以整对象赋值覆写它，而不是逐字段修改。
3. 上下文装配。getMessagesAfterCompactBoundary() 从最后一个 compact 边界向前取消息，确保被压缩的内容以摘要而非原始消息的形式呈现。
4. 五个前置 context shaper。顺序执行，见 08。
5. 模型调用。for await 循环流式接收 deps.callModel() 的响应，传入装配好的消息、完整系统提示、思考配置、可用工具集、中止信号、当前模型规格，以及快速模式设置、投入档位、后备模型等选项。
6. tool_use 分发。响应含 tool_use 块时流向工具编排层。
7. 权限网关。每个工具请求穿过权限系统（06）。
8. 工具执行与结果收集。结果作为 tool_result 消息加入对话，循环继续。
9. 停止条件。响应不含 tool_use（纯文本）时，这一轮结束。

queryLoop() 被定义为 AsyncGenerator，随进展产出 StreamEvent、RequestStartEvent、Message、TombstoneMessage、ToolUseSummaryMessage 等事件。这种基于生成器的设计使输出能流式送往 UI 层，同时在循环内部保持单一的同步控制流。

模型要求跑 npm test 复现失败。工具不必等模型说完就能开始跑——但结果的返回顺序必须与请求顺序一致，否则模型会对不上号。

响应里出现 tool_use 块时，系统在两条执行路径之间选择。主路径用 StreamingToolExecutor，在工具从模型响应中流式到达时就开始执行，降低多工具响应的延迟。后备路径用 toolOrchestration.ts 里的 runTools()，遍历 partitionToolCalls() 产出的分区。两条路径都把工具分类为并发安全或互斥：只读操作可以并行，修改状态的操作（如 shell 命令）串行化。

两个协调机制

• 兄弟中止控制器。任一 Bash 工具报错即触发，立刻终止其他在飞的子进程，而不是让它们跑完。
• 进度可用信号。有新输出就绪时唤醒 getRemainingResults() 的消费者。

工具结果收集阶段遍历来自流式执行器或批量 runTools() 生成器的更新。两者都是异步可迭代对象，由同一个 for await 循环消费；差别只在于工具执行是在模型流式输出完成前就开始（流式），还是在按并发安全分组分区后才开始（批量）。

每次更新可携带工具结果、附件或进度事件。有一个专门的检查探测 hook_stopped_continuation 附件：若 PostToolUse hook 发信号说这一轮不该继续，就设置 shouldPreventContinuation 标志。结果经 normalizeMessagesForAPI() 为 Anthropic API 规范化，只保留 user 类型消息。

跑 npm test 这个请求要穿过七道独立的层，任何一层都能单独拦下它。这套设计的直接动因是一个行为事实：用户会批准 93% 的提示，所以安全不能只靠人的警觉。

七道关卡

1. 工具预过滤（tools.ts）：整体被拒的工具在任何调用之前就从模型视野里移除，模型根本无法尝试调用。
2. 拒绝优先的规则求值（permissions.ts）：拒绝规则永远优先于放行规则，即使放行规则更具体。
3. permission mode 约束（types/permissions.ts）：当前模式决定了没有匹配到显式规则的请求如何处理。
4. auto-mode 分类器：一个机器学习分类器评估工具安全性，可能拒绝规则系统本会放行的请求。
5. shell sandbox（shouldUseSandbox.ts）：已获批准的 shell 命令仍可能在限制文件系统与网络访问的 sandbox 内执行。
6. 恢复时不还原权限（conversationRecovery.ts）：会话域的权限在 resume 或 fork 时不恢复。
7. hook 拦截（types/hooks.ts）：PreToolUse hook 可修改权限决策；PermissionRequest hook 可在用户对话框之外（协调者模式下则在其之前）异步解决决策。

七种 permission mode

类型定义里存在七种模式：五种外部可见，auto 条件加入，bubble 仅内部使用。

1. plan：模型必须先给出计划，用户批准后才执行。
2. default：标准交互式使用。多数操作需用户批准。
3. acceptEdits：工作目录内的编辑与部分文件系统 shell 命令（mkdir、rmdir、touch、rm、mv、cp、sed）自动批准，其他 shell 命令仍需批准。
4. auto：机器学习分类器评估未通过快速路径检查的请求（受 TRANSCRIPT_CLASSIFIER 开关控制）。
5. dontAsk：抑制提示，本会提示的动作自动拒绝；显式的放行与拒绝规则仍生效。
6. bypassPermissions：跳过多数权限提示，但安全关键检查与免绕过规则仍适用。
7. bubble：仅内部使用，用于 subagent 向父终端上升权限。

规则求值按拒绝优先顺序进行。toolMatchesRule() 先检查拒绝规则：宽泛的拒绝（「拒绝所有 shell 命令」）不能被狭窄的放行（「允许 npm test」）覆盖。规则系统支持工具级匹配（按工具名）与内容级匹配（匹配具体工具输入模式，如 Bash(prefix:npm)）。

授权流水线

预过滤。在任何工具请求到达运行时求值之前，filterToolsByDenyRules() 在工具池组装时就把整体被拒的工具从模型视野里彻底剥掉。文档写道：「使用与运行时权限检查相同的匹配器」，所以像 mcp__server 这样的服务器前缀规则会在模型看到之前剥掉该服务器的所有工具。

PreToolUse hook。已注册的 hook 作为权限流水线的一部分触发，可返回 permissionDecision（拒绝或询问）以及修改工具输入参数的 updatedInput。一个 hook 的放行不会绕过后续的规则拒绝或安全检查。在交互路径上用户对话框先排队，hook 异步运行；协调者与类似的后台 agent 路径则先等自动检查完成再显示对话框。

规则求值。MCP 工具按完全限定的 mcp__server__tool 名匹配，服务器级规则匹配该服务器的所有工具。

权限处理器。useCanUseTool.tsx 里的处理器按运行时上下文分四条支路：协调者（多 agent 协调模式，先尝试自动解决再回落到用户交互）、swarm worker（多 agent 集群里的工作者，有自己的解决逻辑）、推测式分类器（启用 BASH_CLASSIFIER 且工具为 BashTool 时，一个预启动的分类结果与超时赛跑，分类器高置信度返回则工具立即批准，无需用户交互）、交互式（后备路径，通过终端 UI 呈现标准批准对话框）。

auto-mode 分类器与 hook 生命周期

启用 TRANSCRIPT_CLASSIFIER 时，yoloClassifier.ts 加载三份 prompt 资源：一份基础系统提示、一份外部权限模板，以及给 Anthropic 内部用户的另一份内部模板。分类器把待执行的工具调用对照对话记录与权限模板评估，产出放行、拒绝或请求人工批准。isUsingExternalPermissions() 检查 USER_TYPE 与 forceExternalPermissions 配置来选模板。

源码定义的 27 个 hook 事件中，有五个直接参与权限流程，各有 Zod 校验的输出模式：

• PreToolUse：可返回 permissionDecision（拒绝或询问，但放行不绕过后续检查）、permissionDecisionReason、updatedInput。
• PostToolUse：可注入 additionalContext；对 MCP 工具可返回 updatedMCPToolOutput 以在结果进入上下文前修改它。
• PostToolUseFailure：可为特定错误注入指导。
• PermissionDenied：可在 auto-mode 拒绝后提供重试指导。
• PermissionRequest：可返回放行或拒绝的决定。

shell sandbox

sandbox 为 Bash 与 PowerShell 命令提供额外一层保护。shouldUseSandbox() 检查三件事：sandbox 是否全局启用、该次调用是否主动退出、命令是否匹配任何排除模式。

启用时，sandbox 提供的文件系统与网络隔离独立于应用层权限模型。一个命令可能被权限批准但仍被沙箱化，也可能被权限拒绝而根本到不了安全检查。两套系统作用在不同的轴上：授权与隔离。

测试跑起来了，输出回到循环。这一站的问题是：出错怎么办，以及循环什么时候停。设计倾向是静默恢复，把人的注意力留给真正无法恢复的情况。

五种恢复机制

• 输出 token 上限升级：响应撞上输出 token 上限时，系统可以用升高后的上限重试，受 GrowthBook 开关与「不存在既有覆盖或环境变量上限」的条件约束。每轮最多三次恢复尝试（MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3）。
• 反应式 compaction（受 REACTIVE_COMPACT 控制）：上下文接近容量时，反应式 compact 只压出刚够用的空间。hasAttemptedReactiveCompact 标志确保每轮最多触发一次。
• prompt-too-long 处理：API 返回该错误时，循环先尝试 context collapse 溢出恢复与反应式 compaction，只有这些都失败才以 reason: 'prompt_too_long' 终止。
• 流式后备：onStreamingFallback 回调处理流式 API 问题，让循环换一种策略重试。
• 后备模型：fallbackModel 参数允许在主模型失败时切换到备用模型。

五个停止条件

1. 没有工具调用：模型只产出文本内容——这是主要的停止条件。
2. 达到最大轮数：可配置的 maxTurns 上限。
3. 上下文溢出：API 返回 prompt_too_long。
4. hook 介入：PostToolUse hook 设置 hook_stopped_continuation。
5. 显式中止：abortController 信号触发。

修测试的过程读了几个文件、跑了几次命令，上下文开始吃紧。压缩不是一步到位，而是五层按代价递进——先用最不破坏信息的手段，只有便宜的不够时才升级。

五层，按代价从低到高

1. 预算削减（applyToolResultBudget()，总是启用）：对工具结果施加逐消息的尺寸上限，把超大输出替换成内容引用。豁免工具（maxResultSizeChars 非有限的）保留完整输出。内容替换会被持久化，以便 resume 时重建。
2. snip（snipCompactIfNeeded()，受 HISTORY_SNIP 控制）：轻量修剪，移除较旧的历史片段，返回 {messages, tokensFreed, boundaryMessage}。
3. microcompact（受 CACHED_MICROCOMPACT 控制）：细粒度压缩，总是走一条基于时间的路径，可选走一条缓存感知路径。启用缓存路径时，边界消息延后到 API 响应之后，以便使用实际的 cache_deleted_input_tokens 而非估算值。
4. context collapse（受 CONTEXT_COLLAPSE 控制）：对话历史上的读时投影。源码注释写道：「什么都不产出；折叠视图是 REPL 完整历史上的读时投影。摘要消息存在折叠存储里，不在 REPL 数组里。这正是折叠能跨轮持续的原因。」它不修改 REPL 存储的历史，只用 applyCollapsesIfNeeded() 替换 messagesForQuery 数组——模型看到折叠版本，完整历史仍可用于重建。
5. auto-compact（默认启用，可关闭）：第五个 shaper，经 compactConversation() 触发一次完整的模型生成摘要。该函数先执行 PreCompact hook，用 getCompactPrompt() 构造摘要请求，调模型产出压缩摘要，结果喂入 buildPostCompactMessages()。只有前四层都跑过、上下文仍超过压力阈值时才触发。

buildPostCompactMessages() 返回的压缩输出结构是 [boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]。边界标记由 annotateBoundaryWithPreservedSegment() 附上保留片段元数据，记录 headUuid、anchorUuid、tailUuid，以支持读时链修补。这种以追加为主的设计意味着 compaction 从不修改或删除已写入的记录行，只追加新的边界与摘要事件。

compaction 之外，还有几个子系统决策同样出于「上下文是瓶颈」这一约束：CLAUDE.md 懒加载（嵌套指令文件与条件规则只在 agent 读到相应目录的文件时才加载）、延迟工具 schema（启用 ToolSearch 时部分工具初期只留名字）、subagent 只回摘要（见 09）、逐工具结果预算（单个工具结果被限制在可配置尺寸内，防止一次冗长输出吃掉不成比例的上下文）。

修测试之前需要先摸清认证模块的结构。这活可以交给 subagent——它在独立的上下文窗口里跑，只把一份摘要交回来。完整历史写进单独的文件，永不进入父上下文。

Agent 工具与内置类型

委派机制是 Agent 工具（AgentTool.tsx），Task 保留为遗留别名。模型用结构化输入调用 Agent，包含委派 prompt、可选的 subagent 类型，以及隔离模式、权限覆盖、工作目录的配置。内置类型最多六种，实际有几种取决于功能开关与入口点。输入模式使用功能开关控制的字段：相应功能关闭时省略可选参数。isolation 字段给内部用户提供 ['worktree', 'remote']，给外部用户提供 ['worktree']，在构建时决定。

• Explore：以读取／搜索为主的调查，写入与编辑工具在它的拒绝列表里。
• Plan：产出结构化计划，执行仍走标准权限模型。
• General-purpose：通用能力，需显式请求。注意：省略类型可能路由到 fork-subagent 路径，那条路径复用父对话上下文而不隔离它。
• Claude Code Guide：上手与文档协助，有自己的 permissionMode 覆盖。
• Verification：跑校验检查（测试套件、lint）。
• Statusline-setup：终端状态行配置。

此外用户可用 .claude/agents/*.md 定义自定义 subagent，plugin 也可贡献 agent 定义。每个文件的 Markdown 正文充当该 agent 的系统提示，YAML frontmatter 指定 description、tools（放行清单）、disallowedTools、model、effort、permissionMode、mcpServers、hooks、skills、maxTurns、memory scope、background、isolation。

三种隔离模式

• worktree：创建临时 git worktree，给 subagent 一份自己的仓库副本，修改不影响父工作树。
• remote（仅内部）：在远程 Claude Code Remote 环境启动，总是后台运行。
• in-process（默认）：与父共享文件系统，但在隔离的对话上下文里运作。

权限覆盖逻辑（runAgent.ts）有几条具体规则：subagent 定义了 permissionMode 时，覆盖生效，除非父已处于 bypassPermissions、acceptEdits 或 auto 模式——因为这些模式代表用户对安全与自主性权衡的显式决定，优先级更高。对异步 agent，系统按级联判断是否避免提示：先看 canShowPermissionPrompts，再看 bubble 模式（总是显示，因为它上升到父终端），最后是默认值（同步 agent 显示提示，异步不显示）。能显示提示的后台 agent 会设置 awaitAutomatedChecksBeforeDialog: true，确保分类器在打断用户之前先出结果。

当 allowedTools 显式传给 runAgent() 时，两级权限作用域模型生效：SDK 级权限（来自 --allowedTools）保留，因为「来自 SDK 消费者的显式权限应当适用于所有 agent」；但会话级规则被 subagent 声明的 allowedTools 替换。未提供 allowedTools 时（常见的 AgentTool 路径），父的会话级规则被继承而不替换。

sidechain 记录

每个 subagent 把自己的记录写成独立的 .jsonl 文件，配一个 .meta.json 元数据文件。这种设计使 subagent 历史可供调试与审计，但不会膨胀父会话文件。只有 subagent 的最终响应文本与元数据返回父对话上下文，完整历史永不进入父上下文窗口。

agent team 的多实例协调用文件锁，不用消息代理或分布式协调服务。每个 teammate 有自己的收件箱 JSON 文件（utils/teammateMailbox.ts），任务分配与其他 agent 间消息推入收件人的收件箱，由逐收件箱的锁文件（utils/lockfile.ts）保护，文件存放在可预测的路径。这用吞吐量换来两个性质：零依赖部署（不需要外部基础设施）与完全可调试（读纯文本 JSON 就能检查任何 agent 的状态）。

测试修好了。这一轮的 prompt、工具调用与结果、compact 摘要、subagent 摘要全部已经落盘。但下次 resume 时，这一轮授予的权限不会回来。

三条独立的持久化通道

1. 会话记录：user、assistant、attachment、system 消息，加上 compaction 与其他元数据事件。项目域，每会话一个文件。
2. 全局 prompt 历史：只存用户 prompt，放在 Claude 配置主目录的 history.json。makeHistoryReader() 生成器经 readLinesReverse() 逆序产出条目，支持上箭头与 ctrl+r 导航。
3. subagent sidechain：每个 subagent 独立的 .jsonl 加 .meta.json。

会话记录存为项目专属路径下以追加为主的 JSONL 文件（显式的清理重写是例外）。getTranscriptPath() 把它算作 join(projectDir, ${getSessionId()}.jsonl)，其中 projectDir 先查 getSessionProjectDir()（由 resume／分支时的 switchSession() 设置），再回落到 getProjectDir(getOriginalCwd())。

记录里除了普通消息，还存 compaction 标记、文件历史快照、归属快照、内容替换记录。追加式 JSONL 是刻意选择：以查询能力为代价换取可审查性与简单性。每条日志事件都人类可读、可进版本控制，不需专门工具即可检视。数据库支撑的方案能对会话历史做更丰富的查询，但引入部署依赖并降低透明度。

resume、fork，以及权限不恢复

--resume 通过重放记录重建对话（conversationRecovery.ts）。fork 从既有会话创建新会话（commands/branch/branch.ts）。但两者都不恢复会话域权限，用户必须在新会话里重新授予。

compact_boundary 标记为配合持久化做了专门设计。annotateBoundaryWithPreservedSegment() 在边界事件中记录 headUuid、anchorUuid、tailUuid。这些 UUID 让会话加载器能在读时修补消息链：被保留的消息在磁盘上保持原来的 parentUuid，加载器用边界元数据正确连接它们。

另需澄清：Claude Code 里的「checkpoint」是给 --rewind-files 用的文件历史检查点，存在 ~/.claude/file-history/<sessionId>/。它们是文件级快照，用于回退文件系统改动，不是通用的状态检查点存储。

技术术语保留英文原词。下表按主题分组，正文中带虚线下划线的词都能在这里找到。

循环与执行

上下文与记忆

权限与安全

工具与扩展

委派与持久化

TypeScript 包到运行时职责的映射。左侧是源码目录，右侧是推断出的运行时角色——这部分属于重构分析，不是官方文档。C 级证据

tools/ 目录含约 42 个子目录实现具体工具，各带对应的 schema、描述、权限要求与执行逻辑。commands/ 目录含约 86 个斜杠命令子目录。

关键服务目录包括 services/tools/（StreamingToolExecutor、toolOrchestration、toolExecution）、services/compact/（compaction 引擎）、services/mcp/（MCP 客户端与配置）。权限基础设施横跨 utils/permissions/（规则求值、分类器）、hooks/useCanUseTool.tsx（权限处理器）、types/permissions.ts（模式定义）与 types/hooks.ts（事件模式）。

工具的条件可用性

getAllBaseTools() 依模式、构建、环境与功能开关构造不同的工具集。模型在极简模式下可能只看到 3 个工具（Bash、Read、Edit），在功能全开的内部构建里则达 54 个（19 个无条件加 35 个条件）。

跨文件依赖

导入图包含以下依赖结构：QueryEngine.ts 把单轮执行委派给 query.ts；query.ts 从 services/tools/（StreamingToolExecutor、runTools）与 services/compact/（autoCompact、buildPostCompactMessages）导入；QueryEngine.ts 从 memdir/ 导入记忆与 prompt 装配。代码显式避免循环导入：types/permissions.ts 被抽出以打破导入环，context.ts 里的 setCachedClaudeMdContent() 避开一条经权限／文件系统路径的环。

全文的论断分三个证据层级。正文中带 ABC 标记的地方，是原文明确标注了层级的论断。

三个证据层级

• A 级（产品文档）：取自 Anthropic 官方文档与工程发布。它们确立产品意图，但可能不反映内部实现。
• B 级（代码验证）：引用抽取出的 TypeScript 代码库（v2.1.88，从公开可得的 npm 包提取）中具体文件与函数的论断。这是最强的证据层级，也是全文的主体。
• C 级（重构推断）：源自社区分析、OpenClaw 或 Hermes Agent 的结构对比，或从代码模式推断。这类论断用带保留的措辞陈述。

源码语料约 1884 个文件、51.2 万行 TypeScript。OpenClaw 与 Hermes Agent 被用作比较参照点，而非事实标准。

设计空间的分析程序

设计问题的识别方式是：逐个考察子系统，寻找「其他生产 agent 存在替代设计」的反复出现的选择点。Claude Code 对每个问题的答案都被追溯到具体源码文件与函数实现（B 级证据）。五价值框架从官方文档与创造者陈述（A 级证据）中识别，再经十三条设计原则追到架构决策。

长期能力保全被单独当作横切问题处理，而非设计价值——因为它在架构中、也在 Anthropic 自陈的价值中，都没有作为设计驱动被显著体现。token 经济被当作同时约束五个价值的横切约束，用以揭示各子系统选择在共享资源压力下如何互相作用。

局限

• 静态快照。分析反映单一版本（v2.1.88）。功能开关（如 TRANSCRIPT_CLASSIFIER、CONTEXT_COLLAPSE）造成构建期变异，不同构建目标可能产出功能上不同的应用。
• 逆向工程的认识论限度。源码揭示已实现的结构、控制流、依赖与功能门控，但无法确认设计意图、生产环境实际启用的开关、运行时的普遍性，或未发布的行为。
• 单系统分析。结论描述 Claude Code 的设计空间，不是编码 agent 的全部设计空间。推广是有边界的。
• 对照系统的快照性。OpenClaw 与 Hermes Agent 的分析各自反映某个特定开发状态，可能不代表它们当前的能力。

另有两条分析层面的约束：getSystemContext() 与 getUserContext() 都用 lodash memoize，意味着 git 状态与 CLAUDE.md 内容是被缓存而非每轮重算的，对话中途的动态变化可能不会立即反映（compaction 能清缓存，懒加载的路径域规则提供部分反制）。功能开关造成构建期变异，受门控的模块用动态 require() 而非静态 import，因为 feature() 由于 bun 打包的树摇约束只在 if／三元条件里生效。

Claude Code 的 TypeScript 源码变为公开可读后，若干社区项目发布了独立重实现。每个都是可运行的 CLI agent，而非被动的源码转录或注释。

论文所属仓库另维护一组配套笔记，追踪新出现的 agent 系统进展；它们不作为 Claude Code 实现的证据。

这不是逐句翻译，而是按「如何工作 → 为什么这样设计 → 速查」重新组织的中文版。下面说明改动了什么，以便与原文对照。

• 结构重组。原文第 3 至 9 章按子系统分章；此版把它们重排成一条请求的十站旅程，使「它如何工作」可以线性读完。原文第 2、10 至 14 章合为第二部分「为什么这样设计」，附录与术语表合为第三部分「速查」。
• 章节对照。站 00 对应原文 3.2 至 3.4；站 01 对应 4.1 与 3.1；站 02 对应 7.1、7.2；站 03 对应第 6 章；站 04 对应 4.1、3.1；站 05 对应 4.2；站 06 对应第 5 章与 3.5；站 07 对应 4.4、4.5；站 08 对应 4.3、7.3、3.6；站 09 对应第 8 章；站 10 对应第 9 章。第二部分依次对应原文 2、12.1、10、12.2、12.3、12.4、12.7、13、11、14 节。
• 术语。技术术语保留英文原词，首次出现处给出中文解释。
• 图表。原文九张图与九张表按窄屏重新排布：流程图在窄屏转为纵向，宽表转为每行一卡。
• 文献引用。正文不逐条标注作者与年份，改用「有工作」「有观察」这类指代，完整文献表见末尾；需要溯源时请对照原文。原文以 ABC 三档标注证据强度，此版只在原文明确标注处保留该标记。
• 压缩取舍。第二部分的「它在文献里的位置」与「六个未解的方向」两节对原文第 11、13 章做了压缩，若干细节论点未保留：包括 §13.3 末段把各方向扩展映射回价值张力表的分析、§13.5 的训练数据来源约束与监管接口文献、§13.6 的过程监督讨论。需要完整论证请读原文。
• 依据版本。依 arXiv v2（2026 年 7 月 2 日）。该版新增 Hermes Agent 作为第三个对照系统、社区重实现附录，并调整了第 10 至 14 章的次序。

原文见 arxiv.org/abs/2604.14228，作者仓库见 github.com/VILA-Lab/Dive-into-Claude-Code。

原文完整文献表，默认收起。浏览器内搜索（Ctrl+F／⌘F）命中折叠内容时会自动展开。