# Claude Code 架构拆解：一个本地 agent 运行时

很多人把 Claude Code 当成一个终端里的 coding agent，但从这批源码材料看，它更接近一套分层完整的本地 agent 运行时。

事情的起点并不复杂。Anthropic 发布在 npm 上的 `@anthropic-ai/claude-code` 包里，附带了一份接近 60MB 的 `cli.js.map`。社区顺着 source map 里的 `sourcesContent`，还原出了大约 1884 个 TypeScript 源文件。它当然不是完整内部仓库，但已经够把主干结构看清楚。

![claude-code-source-title.jpg](https://developer.qcloudimg.com/http-save/yehe-7136204/915a6217f2a45a519b71da51772b7a02.jpg)

把这批材料放到一起看，能先确认两件事：

- Claude Code 的核心 agent loop 并不复杂
- 复杂度主要落在 loop 外面：终端 UI、工具运行时、权限系统、上下文治理、缓存和远端 transport

## npm 包里到底流出了什么

先看 npm 包本身。

![claude-code-source-npm.jpg](https://developer.qcloudimg.com/http-save/yehe-7136204/91da2b25a87576e498db49458ea44678.jpg)

这里最有信息量的不只是 `cli.js.map`，还包括包内其他内容：

- `README`
- `bun.lock`
- `sdk-tools.d.ts`
- `vendor/`

这说明发布到 npm 的不是一个很薄的 wrapper，而是一份本身就带着完整产品逻辑的分发包。社区拿到的也不只是压缩后的 CLI 二进制，而是一份足够把产品骨架拆开的 npm 包。

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

![claude-code-source-tree.jpg](https://developer.qcloudimg.com/http-save/yehe-7136204/595faa44ec2b1112e8be9233f8d3909e.jpg)

只看目录名，就能先把大致结构分出来：

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

只看这一层，Claude Code 就已经不是一个很薄的命令行包装器。它更像一套终端优先的本地应用，前面是一层 TUI，后面是一整套 agent 运行时。

## 终端 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 不是“一开始就把所有表面统一成同一套 engine”，而是先把 REPL 路径做稳，再把共享能力往外抽。

## Tool 在这里不是函数

这批源码里，`Tool` 抽象占的比重很大。

很多人自己写 agent 时，工具差不多就是：

- 一个 schema
- 一个 handler
- 一个返回值

Claude Code 里的工具不是这个尺度。`Tool.ts` 里一个工具对象除了 `name`、`inputSchema`、`call()`，还要带上不少别的东西：

- `prompt()`：怎么向模型描述自己
- `checkPermissions()`：权限怎么走
- `isReadOnly()`：是不是只读
- `isConcurrencySafe()`：能不能并发
- `isDestructive()`：有没有破坏性
- `renderToolUseMessage()`：调用时怎么显示
- `renderToolResultMessage()`：结果怎么显示
- `searchHint`：怎么被搜索到
- `interruptBehavior`：中断时怎么处理

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

`buildTool` 这层默认值也很直接。新工具如果没显式声明安全性，系统不会往乐观方向猜：

- `isConcurrencySafe` 默认是 `false`
- `isReadOnly` 默认是 `false`

也就是默认把它当成“不可并发、可能写文件”的工具来处理。权限这层同样往保守方向收，不会因为作者忘了补声明就自动变成安全工具。

## 工具调度分成两层

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

### `toolOrchestration.ts`

这一层先做工具编排，把同一轮模型返回里的工具调用拆成两类：

- 可以并发跑的
- 必须串行跑的

它不直接做权限判断，也不直接执行命令，主要负责“谁跟谁一起跑，谁要排队”。

### `toolExecution.ts`

真正把一次调用落地的是这里。它要处理的事情很多：

- 输入校验
- 工具级校验
- 权限检查
- hook 决策
- telemetry
- MCP 特殊处理
- 执行结果回写

这批泄露整理里还有一个很关键的细节：工具不是等整段模型回复结束以后才开始跑的，而是在流式输出期间就启动。

这样做有两个直接结果：

- 首个工具更早开跑
- 可并发工具能提早完成

但这也带来了恢复问题：如果模型在流式过程中 fallback 到另一个模型，已经启动的工具怎么办？

Claude Code 的处理方式是中途 fallback 时把已经跑起来的工具停掉，然后整轮重来。它牺牲了一部分实现简单度，换的是整轮状态的一致性。

## 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 behavior flags

### 2. `permissionSetup.ts`

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

### 3. `useCanUseTool.tsx`

这是 runtime 和 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/`

这是让本地客户端去 attach 和显示一个远端 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、工具、安全、缓存、权限、扩展和远端 transport 收成了一套完整产品。

如果这篇文章对你有帮助，欢迎点个赞、点个在看，也欢迎关注。  
后面还会继续写 Claude Code、Codex、OpenClaw 这些项目的源码分析和使用笔记。

很多人把 Claude Code 当成一个终端里的 coding agent，但从这批源码材料看，它更接近一套分层完整的本地 agent 运行时。

Claude Code 架构拆解：一个本地 agent 运行时

软件研发

其他

ClaudeCode架构深度解析：一个完整的本地agent运行时系统。从终端UI到工具调度、权限管理、上下文治理，揭秘Anthropic如何构建分层agent架构。包含Bash安全纵深防御、流式工具调用、prompt缓存优化等关键技术细节，展现从CLI到多agent系统的演进路径。

命令行工具

TypeScript

容器

2026采购季 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude Code 架构拆解：一个本地 agent 运行时-腾讯云开发者社区-腾讯云

Claude Code 架构拆解：一个本地 agent 运行时

Claude Code 架构拆解：一个本地 agent 运行时

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐