Claude Code架构深度拆解：本地智能体运行时工作原理与性能详细对比

许多人习惯将 Claude Code 视为终端中的编码代理，但这次泄露的源码材料清晰显示，它更接近一套完整的分层本地代理运行时。

事件的起点并不复杂。Anthropic 发布在 npm 上的 @anthropic-ai/claude-code 包，附带了一个接近 60MB 的 cli.js.map 文件。社区利用 source map 中的 sourcesContent，还原出大约 1884 个 TypeScript 源文件。虽然不是完整的内部仓库，但已足够勾勒出主干结构。

Claude Code 标题图

综合这批材料，可以先确认两件事：

• Claude Code 的核心 agent loop 并不复杂
• 复杂度主要分布在 loop 外围：终端 UI、工具运行时、权限系统、上下文治理、缓存和远程传输层

npm 包究竟泄露了什么

先看 npm 包本身。

Claude Code npm 包与 source map 截图

最有信息量的不只是 cli.js.map，还包括包内其他内容：README、bun.lock、sdk-tools.d.ts、vendor/。这表明发布到 npm 的不是一个轻量包装器，而是一份包含完整产品逻辑的分发包。社区拿到的也不仅仅是压缩后的 CLI 二进制，而是足以拆解产品骨架的 npm 包。

再看还原后的 src/ 顶层目录。

Claude Code src 目录截图

仅看目录名，就能划分出大致结构：

• entrypoints/：不同启动入口
• main.tsx：主运行时入口
• screens/、components/、context/：终端 UI 层
• services/：工具、MCP、分析和各类运行时服务
• skills/、plugins/、commands/：扩展面
• bridge/、remote/：远程控制和远程会话
• assistant/、coordinator/：自主代理和多代理相关逻辑
• buddy/、voice/、vim/：功能分支和实验特性

仅此一层，Claude Code 就已远非一个轻量命令行包装器。它更像一套终端优先的本地应用，前端是 TUI，后端是完整的代理运行时。

终端 UI 为何采用 React + Ink

首次打开这些文件时，一个常见疑问是：为什么入口文件叫 main.tsx，目录中为何有 context/，一个命令行工具为何遍布 React 组件？

答案在于其终端 UI 使用了 Ink，即 React 的终端渲染器。

一旦理解这一点，许多代码便清晰了：

• 权限确认框是组件
• 工具调用展示是组件
• Markdown 渲染是组件
• REPL 本身也是一个前端界面，只是运行在终端里

因此 main.tsx 并非命名习惯，而是产品的前端入口之一。代码中还能看到与滚动性能相关的处理：用户滚动时，后台工作会短暂暂停，定时器还会调用 unref() 以避免阻止进程退出。这类处理更像桌面前端，而非普通 CLI。

换句话说，在 Anthropic 的实现中，终端不是“文本输出设备”，而是另一个前端容器。

主执行链路的结构

将主路径压缩后，大致如下：

1. entrypoints/cli.tsx 先处理 fast path
2. main.tsx 执行完整初始化
3. replLauncher.tsx 挂起 App 和 REPL
4. REPL.tsx 组装消息状态、工具池、权限状态、MCP 状态
5. 输入被送至 query(...)
6. query.ts 运行 turn loop，处理流式输出、工具调用、上下文整理
7. toolOrchestration.ts 负责编排
8. toolExecution.ts 负责实际执行

这里有一个容易误判的点：仓库中已有 QueryEngine.ts，但 REPL 当前主路径仍使用 query()。QueryEngine 更倾向于为 SDK/headless 场景和后续抽象做准备。

也就是说，Claude Code 并非一开始就将所有表面统一成同一套引擎，而是先稳定 REPL 路径，再将共享能力向外抽取。

Tool 在此处不是函数

这批源码中，Tool 抽象占据很大比重。

许多人在编写 agent 时，工具通常只是：一个 schema、一个 handler、一个返回值。Claude Code 中的工具尺度不同。Tool.ts 中一个工具对象除了 name、inputSchema、call()，还需携带许多其他内容：

• prompt()：如何向模型描述自身
• checkPermissions()：权限如何流转
• isReadOnly()：是否只读
• isConcurrencySafe()：能否并发
• isDestructive()：是否具有破坏性
• renderToolUseMessage()：调用时如何显示
• renderToolResultMessage()：结果如何显示
• searchHint：如何被搜索到
• interruptBeha vior：中断时如何处理

在 Claude Code 中，工具不是单纯的函数，而是同时覆盖提示词层、执行层、权限层和 UI 层的运行时对象。

buildTool 提供的默认值也很直接。新工具若未显式声明安全性，系统不会乐观假设：isConcurrencySafe 默认是 false，isReadOnly 默认是 false。即默认将其视为“不可并发、可能写文件”的工具。权限层同样趋于保守，不会因作者遗漏声明就自动变为安全工具。

工具调度分为两层

从执行链来看，Claude Code 的工具部分至少拆分为两层。

toolOrchestration.ts

这一层先进行工具编排，将同一轮模型返回中的工具调用分为两类：可并发执行的与必须串行执行的。它不直接处理权限判断，也不直接执行命令，主要负责“谁与谁一起运行，谁需要排队”。

toolExecution.ts

真正将一次调用落实的位置在此。它需处理的事项繁多：输入校验、工具级校验、权限检查、hook 决策、遥测、MCP 特殊处理、执行结果回写。

此次泄露整理中还有一个关键细节：工具并非等到整个模型回复结束后才开始运行，而是在流式输出期间就已启动。

这样做有两个直接结果：首个工具更早开始运行，可并发工具能提前完成。

但这也带来了恢复问题：若模型在流式过程中回退到另一个模型，已启动的工具应如何处理？Claude Code 的处理方式是，中途回退时停止已运行的工具，然后整轮重来。它牺牲了一部分实现简单性，换取了整轮状态的一致性。

Bash 安全是一条纵深防线

这套源码中最像“线上事故沉淀”的部分，是 Bash 工具相关代码。

由于“让模型执行终端命令”是整个系统中风险最高的能力之一，其设计并非一条简单的黑名单，而是一条纵深校验链。

bashSecurity.ts 这类逻辑中包含许多独立检查器，分别针对不同攻击面：空命令、heredoc 与命令替换、shell 元字符、危险变量、重定向、Unicode 空白字符、回车注入、$IFS 注入、/proc/*/environ 访问、大括号展开、注释和引号不同步。

其中有两类问题很典型。

1. Unicode 空白字符

有些字符看起来像空格，但 shell 并不将其视为普通分隔符。人眼看到的是正常命令，解析器看到的却是另一回事。

2. 回车注入

\r 可使终端后面的内容覆盖前面的显示。屏幕上看似安全命令，实际执行的可能是另一条。

再往下看，还有一层 Zsh 专项治理。由于 macOS 默认 shell 是 Zsh，而 Zsh 包含许多 Bash 没有的内建能力，可绕过普通二进制检查。Claude Code 对这些路径单独做了限制，防范的不是一般误操作，而是带有意图的绕过。

权限系统横跨四层

Claude Code 的权限并非一个弹窗函数，而是一套公共层。

从代码分布来看，至少有 4 层：

1. Tool.ts

此处定义的是权限上下文，其中不仅包含 allow / deny / ask，还包括：mode、additional working directories、bypass / auto mode、prompt beha vior flags。

2. permissionSetup.ts

这一层决定初始权限包络。CLI 传入的 allow/deny 规则、基础工具规则、当前模式，首先在此整理。

3. useCanUseTool.tsx

这是运行时与 UI 的接口层。它需决定的不仅是“能否使用”，还包括：直接放行、直接拒绝、弹出权限框、转给协调器、转给 worker、在某些路径中自动分类或自动拒绝。

4. toolExecution.ts

实际执行前，还会再次读取当前 app state、hook 决策和权限状态。

这套分布看似较重，但逻辑上是连贯的：权限不是某个工具自身的事，而是所有工具、本地模式、远程模式、后台 worker 和 UI 都要共享的一套语义。

泄露整理中有一句话将后台 agent 的约束说得很清楚：不能向用户弹框确认的后台 agent，遇到需要审批的能力就直接拒绝。拿不到确认，就不做。这与整套权限系统的取向一致。

上下文窗口治理不是单次摘要

Claude Code 在上下文窗口上的做法，与许多人编写 agent 时的第一反应不同。

许多自制 agent 的做法是：快超限时，执行一次压缩整理（compaction）或 summarize。

Claude Code 更像一条固定的降级链：

1. 先截断工具结果
2. 再裁掉旧消息
3. 再按消息组做摘要
4. 若还不够，再单独发起一次模型调用，对整段会话做更重的压缩

这 4 步处理的并非同一问题：工具输出过长、普通对话历史过长、历史结构尚在但体积太大、整体上下文已必须压缩。

这也是为何许多简单 agent 在短任务中能运行，长任务就开始偏移。它们做了“摘要”，但未采用分层降级。

prompt cache 和成本控制直接融入架构

此次泄露中还有一处很实在，即 prompt cache 相关逻辑。

Claude Code 的系统提示很长。若每轮都原样重发，成本会很高，因此代码中专门有一条动态边界，将系统提示切成两段：前半段是稳定内容，后半段是工作目录、模型名、MCP 配置等动态内容。这样 stable prefix 更容易命中缓存。

更细致的地方在于，一些与请求头有关的状态会被做成“锁存器”。一旦某个模式打开，对应 header 便不再来回切换，因为这种切换会破坏 prompt cache。

会话在 API 调用前就持久化到 transcript，也是同一类思路。表面上这是为了 --resume 恢复，实际也减少了进程意外中断后整段对话重发的成本。

skills、plugins、MCP 最终都被收进同一张命令面

仅看 README，许多人会将 skills、plugins、MCP 理解为三种并列功能。

从 commands.ts 和 loadSkillsDir.ts 来看，它们最终都被收进同一张命令注册表：

• filesystem skills
• plugin skills
• bundled skills
• built-in plugin skills
• plugin commands
• workflow commands

也就是说，Claude Code 并非在主程序旁边挂几个扩展点，而是将这些来源统一为一个命令面。

loadSkillsDir.ts 还说明 skills 的来源多样：managed policy 目录、用户设置目录、项目目录、--add-dir、legacy commands-as-skills。而且技能还可按文件路径动态激活。MCP 这边也并非 sidecar 式接入，客户端会直接将 MCP server 暴露的工具和资源收入运行时。

这一层设计决定了 Claude Code 后续的可扩展能力为何能继续增长。因为底座并非一次性写死。

bridge/ 和 remote/ 表明它已不局限于本地 REPL

源码中至少能看出两套不同的远程栈：

bridge/

这是将本地机器变为远程控制 worker 的层级。其中包含：feature gating、entitlement / OAuth / policy 检查、env-based / env-less 路径选择、v1 / v2 transport 适配、worker 生命周期管理。

remote/

这是让本地客户端附加并显示远程 session 的层级。其中可见：websocket 订阅、HTTP message send、permission request / response handling、远程权限请求到本地 UI 的桥接。

因此这两套栈并非一回事：bridge/ 是“本地机器被远程控制”，remote/ 是“本地客户端连接远程 session”。而它们最终都要回到同一套工具语义和权限语义上。这也是为什么 Claude Code 的产品边界已不再是单一本地 REPL。

多 agent 和未发布能力，揭示同一条产品延长线

此次泄露中最容易被传播的，还是这些名称：KAIROS、Auto-Dream、ULTRAPLAN、SPECULATION、BUDDY。

其中确实有很轻松的内容，比如 BUDDY。源码中能看到一整套 ASCII 宠物系统，物种、帽子、眼睛、稀有度、名字、性格都已完成，连随机方式都是按用户 ID 做确定性生成。

但这些名称更重要的地方，并非“Claude Code 里藏了什么彩蛋”，而是它们几乎都长在现有底座上：KAIROS 指向跨 session 常驻 agent，Auto-Dream 指向空闲时自动整理记忆，SPECULATION 指向预测下一步输入并提前执行，ULTRAPLAN 指向更重的远程规划和多 agent 探索。

而多 agent 这一层，在泄露整理中说得直白：sub-agent 本质上就是同一个 turn engine，换一组参数再跑一遍：换模型、换工具集合、换权限上下文、必要时换 git worktree。

这说明“多 agent”未必意味着重造一套全新系统。很多时候，先将 turn engine、权限语义、工具语义和工作区隔离做稳，后续的 worker / coordinator 只是同一个系统的参数化复用。

这批源码中可直接看到的工程取向

将此次泄露的源码材料从头到尾梳理一遍，最终留下的并非某个神秘 loop，而是这些工程取向：

• 终端 UI 被当作前端来编写
• 工具被当作完整运行时对象来设计
• 工具调度支持流式期间启动和整轮重启
• Bash 风险采用纵深防御处理
• 权限系统横跨 setup、runtime、UI、remote
• 上下文窗口治理是一条分层降级链
• prompt cache 和成本控制直接写进架构
• skills、plugins、MCP 被收进统一扩展平面
• bridge 和 remote 说明它早已不是单表面产品

Claude Code 这次最值得看的，不是“它会不会调工具”，而是它已将终端 UI、工具、安全、缓存、权限、扩展和远程传输收成了一套完整产品。

来源：互联网