来了来了，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：

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

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

工具系统架构

功能多样性分析

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

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

命令系统架构

用户体验设计

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

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 社区恢复版发布