来了来了，Claude Code 全架构解析！！！

claude code 源码泄露这事儿大家应该知道了吧？不知道的我再说一次。 2026 年 3 月 31 日，@anthropic-ai/claude-code npm 包的 source map 意外暴露了 R2 存储桶中的未混淆 TypeScript 源码，由 Chaofan Shou (@Fried_rice) 率先发现。这次泄露让我们有机会一窥这个企业级产品的完整架构设计。

Chaofan Shou ，你可是真一个大聪明。

在聊之前先解决两个疑惑，很多读者朋友们不清楚一个 CLI 为什么还要 npm，以及不清楚 source map 是个啥，这里我先给你讲清楚。

Claude Code 是用 TypeScript/Node.js 写的 CLI 工具。在 Node.js 生态里，最主流的发布方式就是打成 npm 包，然后用户通过 npm install -g @anthropic-ai/claude-code 全局安装。

这和前端网页没关系，纯粹是 Node.js 工具的标准分发形式。像 Vue CLI、Create React App、TypeScript 本身，也都是通过 npm 包分发的 CLI 工具。

而Source map 不是给用户用的，是给开发者（Anthropic 自己）调试用的。

当 TypeScript 代码被编译成 JavaScript 之后，如果线上运行时报错，堆栈信息指向的是压缩/编译后的代码，几乎没法读。有了 source map，开发者可以把错误位置映射回原始的 TypeScript 源码，精准定位问题。

问题是------这个东西应该在发布前删掉。正常流程是：开发时生成 source map 方便调试，打包发布生产包时要么不生成，要么生成但单独存到内部监控系统，而不是一起塞进 npm 包里。

至于这是不是 claude 自己故意的就不得而知了，但我猜是故意的，我估计你们也信。

好了，废话不多扯，直接进入硬核环节。由于工程量太过巨大，这篇文章只是先大致的介绍一下整个大致框架，有意思的事情咱们后面再说。

产品关键指标：

代码规模：1,987 个文件，512,000+ 行 TypeScript 代码
运行时：Bun（现代 JavaScript 运行时）
UI 框架：React + Ink（终端 React 渲染器）
架构模式：模块化、插件化、多代理协作

整体架构

核心架构设计

Claude Code 采用了六层分层架构，每一层职责清晰，松耦合设计：

入口层 ：main.tsx 负责启动，setup.ts 初始化环境
展示层：React + Ink 构建的终端 UI，提供现代化用户体验
核心引擎：QueryEngine（46K 行代码）处理所有 LLM 对话逻辑
执行层：Tool System 和 Command System 负责实际操作执行
协作层：多 Agent 系统和远程桥接实现复杂协作
管理层：权限、配置、状态管理确保系统稳定可靠

启动流程架构

性能优化亮点

启动优化的艺术：前 19 行代码采用并行预取优化，减少启动时间约 135ms：

scss 复制代码

// main.tsx 第 1-19 行
const tasks = Promise.all([
  profileCheckpoint(),      // 性能分析
  startMdmRawRead(),        // MDM 配置读取
  startKeychainPrefetch()   // OAuth/API 钥匙串预取
])

这个设计非常聪明------三个任务同时执行，用 Promise.all 等待所有任务完成，大大减少了串行操作的时间消耗。这体现了企业级产品对用户体验的极致追求。

工具系统架构

功能多样性分析

功能的多样性体现得淋漓尽致：

类别	工具数	说明
核心工具	10+	BashTool、FileReadTool、FileEditTool、FileWriteTool、GlobTool、GrepTool 等
网络工具	2	WebFetchTool、WebSearchTool
代理与协作	5+	AgentTool、SkillTool、TaskTool、SendMessageTool、TeamTool 等
协议集成	3+	MCPTool、LSPTool、ListMcpResourcesTool、ReadMcpResourceTool 等
特殊工具	9+	NotebookEditTool、AskUserQuestionTool、ConfigTool、TodoWriteTool 等
功能标记工具	26+	SleepTool、TerminalCaptureTool、WebBrowserTool、SnipTool 等

每个工具都是自包含的模块，有 input 验证、权限检查、执行逻辑，这体现了良好的代码组织实践。

命令系统架构

用户体验设计

命令的威力：87 个斜杠命令按功能分类，提供优秀的用户体验：

类别	命令数	说明
版本控制	4	commit、review、diff、branch
会话管理	4	resume、session、share、compact
配置管理	4	config、theme、keybindings、permissions
工具与技能	4	skills、plugins、tasks、mcp
模式切换	4	plan、vim、fast、sandbox-toggle
分析与统计	4	cost、usage、stats、insights
功能标记命令	8+	buddy、proactive、assistant、brief、bridge、voice、ultraplan、fork 等
内部命令（仅 ant）	5+	teleport、bughunter、mock-limits、ctx_viz、ant-trace 等

QueryEngine 架构

AI 对话引擎分析

AI 对话的引擎：46K 行代码的 QueryEngine 是整个系统的大脑，处理所有 LLM 交互：

上下文管理：收集 git 状态、CLAUDE.md、环境信息
LLM 交互：处理 API 调用、流式响应
工具调度：执行工具调用、结果解析
权限检查：工具调用前的权限验证
重试逻辑：API 失败时的重试机制
费用追踪：Token 计数、成本计算

这是典型的"工具使用 Agent"架构，体现了 Anthropic 对 AI 代理设计的深刻理解。

权限系统架构

安全架构分析

安全的边界：三级门控系统确保安全：

工具级别：checkPermissions() 方法
全局规则：alwaysAllowRules / alwaysDenyRules / alwaysAskRules
自动分类：TRANSCRIPT_CLASSIFIER（Yolo 分类器）
用户确认：用户提示或自动决策

功能门控系统：

编译时开关：feature() 50 个，非活动代码完全从构建中移除
用户类型：ant（内部）或 external（外部），功能完全不同
GrowthBook A/B 测试：远程配置，支持实验性功能发布

这是企业级安全架构的典范------渐进式功能发布，三层门控确保安全。

BUDDY 系统架构

用户忠诚度策略

这可能是最有意思的模块了。

宠物经济学的奥妙：

确定性生成：每人只会得到一只固定的宠物，基于账号 UUID + 固定盐值 friend-2026-401 确定性生成
物种多样性：18 种物种，包括鸭子、鹅、果冻、猫、龙、章鱼、猫头鹰、企鹅、乌龟、蜗牛、幽灵、六角恐龙、水豚、仙人掌、机器人、兔子、蘑菇、胖猫
稀有度系统：

common：60%，★
uncommon：25%，★★
rare：10%，★★★
epic：4%，★★★★
legendary：1%，★★★★★

属性系统：5 项属性------DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK
闪光概率：1% 概率获得特殊颜色的宠物
交互命令：/buddy hatch 孵化、/buddy pet 抚摸、/buddy card 查看卡片

这是一个巧妙的用户粘性设计------确定性确保公平，稀有度带来惊喜，交互提升粘性。

KAIROS 系统架构

用户粘性策略

永不关机的 Claude：

跨会话持久运行：通过 .claude/settings.json 的 assistant: true 激活
每日日志：自动在 /logs/YYYY/MM/YYYY-MM-DD.md 记录工作日志
自动 Dream：记忆整合流程

触发条件：距上次整合 > 24 小时 + 有 5+ 新会话
四阶段：Orient → Gather → Consolidate → Prune

主动模式：没人说话时自己找活干，没活就 SleepTool 等着
后台任务：命令超 15 秒自动丢后台，支持持久 cron 任务

这是用户粘性设计的典范------持久运行、每日日志、自动记忆整合，让用户离不开。

ULTRAPLAN 系统架构

高级功能策略

云端的思考：

功能流程：/ultraplan 触发

创建远程 CCR 会话
Opus 模型独立研究（最长 30 分钟）
后台轮询等待（30 分钟超时）
浏览器查看/修改方案
批准执行或传送回本地

关键词触发：消息包含 "ultraplan" 自动触发，智能排除引号/路径/标识符中的误触发
传送功能：本地 ↔ 远程会话传输，支持 Git Bundle 打包代码上下文
限制条件：isEnabled: () => "external" === 'ant'，外部用户永远不可用

这是高级功能的典范------云端规划、本地控制，完美解决复杂任务。

Coordinator 系统架构

复杂任务策略

多代理协作：

角色分离：

Coordinator：只有三个工具------派活（Agent）、通信（SendMessage）、停工（Shutdown）
Worker：独立子进程，完整工具集

协作机制：基于文件的共享任务列表
系统提示：明确规定"禁止甩锅式委派"，不能把不清楚的需求直接丢给 Worker

这是多代理架构的典范------角色分离、职责明确、协作机制完善。

Bridge 系统架构

远程协作策略

远程协作的未来：

WebSocket 实时连接：本地 CLI 通过 WebSocket 与 claude.ai 双向通信
完整远程控制：远程端可以发送消息、批准权限、查看输出
进程间通信：跨 Claude 会话的消息传递机制
状态同步：bridgeStatusUtil.ts 实时同步运行状态
权限回调：bridgePermissionCallbacks.ts 远程权限审批

目录结构

代码组织策略

代码组织的智慧：

模块化设计：1,987 个文件分布在 20+ 个目录，每个模块独立且可测试
入口文件：main.tsx（803KB）是 CLI 主入口
核心引擎：QueryEngine.ts（46K 行）处理 LLM 对话
工具与命令：

tools/：53 个工具实现
commands/：87 个斜杠命令

用户界面：

components/：148 个 React 组件
hooks/：87 个自定义 Hooks

功能模块：agents/、assistant/、buddy/、bridge/、coordinator/、proactive/、voice/ 等
外部服务：services/ 包含 MCP 集成、LSP 管理、Analytics 等

这是企业级代码组织的典范------模块化、可测试、职责明确。

关键设计模式

架构设计策略

架构设计的智慧：

并行预取优化：启动时 3 任务同时执行
延迟加载：重模块按需导入，如 OpenTelemetry、gRPC、分析模块
死代码消除：Bun 编译时移除非活动代码，使用 feature() 编译开关
自包含工具模块：每个工具独立，有 input 验证、权限检查、执行逻辑
缓存友好设计：命令、工具、上下文 memoize 缓存

总结与启示

产品成功因素

架构清晰：模块化、插件化、多代理协作设计，易于维护和扩展
性能优化：启动优化、延迟加载、死代码消除，提供良好的用户体验
安全架构：三级权限系统、沙箱模式、审计日志，确保系统安全
用户体验：React + Ink 现代终端 UI、并行预取优化，启动时间短
功能完整性：53 个工具、87 个命令、18 种宠物、7 大隐藏功能，覆盖开发全流程
用户粘性：BUDDY 宠物系统、KAIROS 持久助手、每日日志，提升用户留存
高级功能：ULTRAPLAN 云端规划、Coordinator 多代理编排，满足复杂需求
远程协作：Bridge 系统支持远程控制，在手机上批准权限

对产品设计的启示

渐进式功能发布：使用 feature() 编译开关和 GrowthBook，实现功能渐进式发布
类型安全设计：严格 TypeScript + Zod 验证，减少错误
性能优化策略：并行预取、延迟加载、缓存友好，提升系统响应速度
安全架构设计：三级门控系统、权限检查、审计日志，确保系统安全
用户粘性策略：宠物系统、每日日志、持久助手，提升用户留存
高级功能设计：云端规划、多代理编排，满足复杂场景需求

声明

源码版权：归 Anthropic 所有
研究用途：本分析仅供技术研究与学习使用
非官方：本文档非 Anthropic 官方文档
删除请求：如有侵权，请联系删除

泄露事件时间线：

2026-03-31 - Chaofan Shou (@Fried_rice) 在 X (Twitter) 公开发现
2026-03-31 - GitHub 社区恢复版发布

来了来了，Claude Code 全架构解析 ！！！