大多数关于 Claude Code 的讨论dou停留在“怎么写好 Prompt”或者“如何配置 MCP 服务器”这些表层应用上。这就像是在研究怎么把车开得geng快，却从未打开引擎盖kankan里面的活塞是如何运动的。但Ru果你真的想理解这个工具的边界，或者想自己构建一个类似的 AI 编程助手，你就必须潜入源码深处，去kankan当一个请求从终端发出后它在内部究竟经历了一场怎样的旅程。

这不仅仅是一次代码走查，geng是一场关于工程哲学的探讨。在 Anthropic 的工程师眼中，Claude Code 不是一个简单的聊天机器人，而是一个精密的状态机，一个在不可靠的网络环境与不可控的 LLM 输出之间寻找平衡的堡垒。今天我们就把那个约 53KB 的核心架构拆开，按下一个请求的生命周期，kankan它是流转的。

第一站：CLI 的极速响应与状态加载

一切始于你在终端敲下 `claude` 并按下回车的那一刻。代码的入口点在 `cli.tsx`，但这里有一个非常有趣的设计细节，体现了工程师对性Neng的极致追求。

你可Neng会觉得，启动一个复杂的 Node.js 应用总是需要几百毫秒的加载时间。但 Claude Code 偷了个懒——或者说Zuo了一个极其聪明的“Fast Path”设计。Ru果你只是输入 `--version` 查kan版本号，代码根本不会去加载那些沉重的依赖模块。它通过一个简单的 `if` 判断，直接在 12ms 内返回结果并退出。这种“零导入”的快速通道，保证了工具在日常使用中的轻快感。

当然当你真正进入交互模式时真正的重头戏才开始。这时候，`bootstrap/state.ts` 开始接管局面。这里定义了一个庞大的 `State` 类型，包含了上百个字段，从模型选择到会话 ID，从 CPU 占用到内存指标，无所不包。

这里有一个值得玩味的机制：Sticky-on Latch。

Anthropic 的 Prompt Cache 有个特性：请求参数必须完全一致才Neng命中缓存。这就带来了一个工程难题：用户在交互过程中可Neng会切换模式，这会改变请求头中的 Beta 参数。Ru果每次切换dou导致缓存 Key 变化，那么那高达 70K token 的系统缓存就会瞬间失效，成本和延迟dou会飙升。

Claude Code 的解决方案是借鉴了数字电路中的“锁存器”概念。一旦某个 Beta Header被激活过它就会被“锁住”，即使你后续切换了模式，它依然保持激活状态，直到你显式执行 `/clear` 或 `/compact` 命令。这是一种典型的工程权衡：牺牲一点“模式切换的即时响应反馈”，换取缓存命中率的极大提升。毕竟省下的 Token 和时间，远比那个 UI 状态的即时geng新geng有价值。

第二站：QueryEngine 的预处理艺术

状态就绪后命令会被移交给 `QueryEngine.ts`。这里是请求进入核心循环前的Zui后一道关卡，也是“把复杂度消化在启动层”哲学的体现。

`QueryEngine.submitMessage` 被设计为一个 `AsyncGenerator`。这和普通的 Promise 函数有本质区别：Promise 只Neng resolve 一次而 AsyncGenerator Ke以 yield 多次。这意味着 Claude Code Ke以在一个请求的生命周期中，多次向用户流式返回状态geng新，而不是等到Zui后才给一个结果。

在真正调用 LLM API 之前，QueryEngine 会Zuo几件不起眼但至关重要的事。

是 Transcript 的预写入。大多数开发者习惯的逻辑是“调 API -> 拿结果 -> 存数据库”。但 Claude Code 反其道而行之，它在 API 调用之前，就先把当前的上下文写入磁盘。这kan起来多此一举，实则是一招“未雨绸缪”。Ru果进程在 API 调用中途被杀掉，下次启动时系统Ke以从磁盘恢复上下文，而不是让用户对着空白的屏幕发呆。这种“先写后调”的策略，贯穿了整个系统的容错设计。

然后是 Skills 的延迟加载。Ru果你定义了 100 个自定义 Skill，启动时Ru果全部编译，那启动速度将不可接受。Claude Code 的Zuo法是：启动时只解析 YAML frontmatter，正文内容被闭包捕获，只有在真正调用到那个 Skill 时才进行编译。这种“按需编译”的策略，确保了主路径的轻量。

第三站：核心循环——不是递归，是状态机

预处理完成后请求进入了整个系统的心脏：`query.ts`。这段代码约 2000 行，是整个系统的中枢。

hen多人直觉上认为 AI 工具的交互是递归的：模型返回 tool_use -> 执行工具 -> 拿到结果 -> 递归调用自己 -> 再调模型。早期的 LangChain 就是这么干的。但 Claude Code 摒弃了这种Zuo法，转而使用了一个 `while` 循环配合 State 对象和 transition 字段。

为什么要这么Zuo？因为递归难以控制，容易陷入死循环，且状态管理混乱。而 `while` 本质上是一个状态机。每一轮循环，它douZuo几件事：准备上下文、检查阻塞限制、流式调用 API、执行工具、注入附加消息、打包状态继续。

这种设计让控制流变得极其清晰。无论模型是要调用工具，还是需要geng多上下文，亦或是任务完成，dou只是循环内部的一次状态转移。这也为后续的“多 Agent 递归”打下了基础——子 Agent 不过是同一个进程里压了一层栈的另一个 `query` 调用实例罢了。

第四站：流式执行与工具的并行哲学

在 `query.ts` 的循环中，Zui精彩的部分莫过于 API 调用与工具执行的重叠。

传统的Zuo法是串行的：等 API 完全返回，解析出 `tool_use` 块，然后去执行工具，拿到结果后再调下一轮 API。这就像是在等红灯，哪怕前面没车也得等。

Claude Code 采用了类似 CPU 流水线的思想。当 API 流式返回数据时每收到一个 `tool_use` block，它就立即注册并启动工具执行。它不会傻等 API 全部返回。等 API 跑完了工具可Neng也跑得差不多了再通过 `getRemainingResults` 拿到剩余结果。这种“API 和工具重叠执行”的策略，是 Claude Code 感觉极快的原因之一。

当然工具执行不是无脑并发的。这里有一个精细的并发控制机制。每个工具定义时dou有三个安全标记：`isConcurrencySafe`、`isReadOnly`、`isDestructive`。

像 `FileRead` 或 `Glob` 这种只读操作，被标记为并发安全，Ke以多个一起跑。但 `Bash` 或 `FileEdit` 这种写入操作，必须串行执行。geng绝的是Ru果一组并行工具中有一个 Bash 命令出错了系统会立即触发 `siblingAbortController.abort`，取消所有其他还在跑的兄弟工具。这避免了“一个工具失败了其他还在跑，Zui后拿到一个不一致状态”的尴尬局面。

第五站：多 Agent 的递归与隔离

当 Claude Code 判断一个任务太复杂，需要拆分时它会启动子 Agent。但这里的“子 Agent”和你想象的可Neng不太一样。

它不是开一个新的进程，也不是起一个新的线程，甚至不是一个新的网络连接。它本质上就是同一个进程里的一次递归调用。父 Agent 把自己的 `query` 调用栈往下压了一层，创建了一个新的 AsyncGenerator 实例来执行子任务。

这种设计带来了一个巨大的 UX 优势：用户只应该和一个“窗口”交互。子 Agent 不Neng直接向用户提问。Ru果子 Agent 需要权限确认，它必须把请求通过“Mailbox”上交给父 Agent，由父 Agent 统一弹窗询问用户。这保证了你永远不会kan到“第二个 Claude”突然跳出来问你问题，所有的交互dou在主界面上完成。

为了防止子 Agent 搞破坏，Claude Code 采用了 tmux 方案进行隔离。每个子 Agent 运行在独立的终端 pane 里环境隔离、信号隔离。这kan起来笨重，但在安全性面前，性Neng是Ke以妥协的。

第六站：权限系统的七层防御

安全性怎么强调dou不为过。Claude Code 没有采用简单的“弹窗确认”，而是构建了一套七层权限检查链。

Zui引人注目的是 Auto Mode 下的 YOLO Classifier。当你开启“离开键盘模式”让 Claude 自动干活时它不Neng每一步dou问你。这时候，一个专门的 LLM 分类器会介入。它接收完整的工具调用上下文——工具类型、命令内容、路径、环境变量等——然后进行一次独立的推理判断，决定这个操作是否安全。

这不是简单的正则匹配，而是真正的 LLM 推理。虽然这增加了一次额外的 API 调用成本，但换来了远比规则引擎灵活的安全判断。比如它Neng识别出 `rm -rf /tmp/foo && cat /etc/passwd` 这种用 `&&` 连接的隐蔽攻击链，这是普通正则hen难Zuo到的。

此外还有 `shadowedRuleDetection`来防止用户配置冲突，以及 `denialTracking`来避免用户被频繁弹窗骚扰。每一步dou有据可查，每一个决定dou有原因。

第七站：上下文压缩的五级阶梯

随着对话的深入，Token 一定会超限。这时候怎么办？直接报错？那是偷懒的Zuo法。Claude Code 设计了一套五级渐进式压缩策略。

这五级策略是严格顺序执行的，每一级的输出是下一级的输入，就像排好队的士兵：

L0 零成本： 大多数请求只经过这里什么dou不Zuo。

L1 Micro Compact： 移除一些不必要的空格或格式字符。

L2 Snip Compact： 利用 tree-sitter AST 解析，直接移除旧的 assistant 消息块。

L3 Auto Compact： 调用模型来对话历史，用摘要替换原始消息。

L4 Context Collapse： Zui重的一级，将超预算的内容持久化到磁盘，替换成路径引用。模型后续需要时Ke以通过 FileRead 再读回来。

这种“用Zui低成本解决问题，只在便宜的方法不够时才升级”的策略，体现了极高的工程素养。特别是 L4，它不是简单的丢弃数据，而是把数据存到磁盘。这保证了即使上下文被压缩了信息并没有丢失，只是被“换出”了内存。

第八站：可观测性与数据隔离

在整个生命周期中，每一步dou在被记录。Claude Code 内部维护了三层独立但互补的可观测体系。

这里有一个非常硬核的细节：`_PROTO_*` 机制。为了防止数据泄露，系统在记录日志时Zuo了严格的 PII隔离。文件路径、未脱敏数据等敏感信息，只有拥有特定权限的 privileged column Neng访问，像 Datadog 这样的第三方监控服务根本拿不到。这就像给数据加了一把只有自己Neng开的锁。

同时系统还使用了两个独立的 `AsyncLocalStorage` 来管理 Span 上下文：`interactionContext`和 `toolContext`。这种嵌套的 Span 设计，让开发者Ke以清晰地追踪到一个请求到底卡在了哪一步——是网络延迟了还是工具执行慢了还是模型推理久了。

工程是妥协的艺术

kan完这八个环节，你会发现 Claude Code 的源码里并没有什么黑魔法。它有的，只是无数个在“交互自由度”和“系统稳定性”之间Zuo的权衡。

它选择牺牲一点启动速度，换取geng安全的隔离；它选择牺牲一点模式切换的即时性，换取巨大的缓存收益；它选择牺牲一点实现的简洁性，换取geng强的可控性。

Ru果你要自己Zuo一个 LLM 驱动的工具，Neng从 Claude Code 里“偷”到什么？我想，Zui重要的不是某段具体的代码，而是这种“假设一切dou会失败，并为此Zuo好准备”的防御性编程思维。无论是先写 Transcript 的容错，还是五级压缩的兜底，亦或是多 Agent 的权限上收，每一行代码dou在为那个必然发生的错误时刻准备着退路。

这就是 Claude Code 的请求流转之路。它不是一条直线，而是一条充满了检查点、缓存层、熔断器和安全网的复杂管道。正是这些kan不见的工程细节，才造就了那个在终端里行云流水的 AI 助手。

---