Claude Code CLI 源码深度分析报告

目录

• 1. 项目概述
• 2. 技术栈与依赖
• 3. 项目规模
• 4. 启动流程与入口点
• 5. 核心架构
• 5.1 工具系统 (Tool System)
• 5.2 任务系统 (Task System)
• 5.3 查询引擎 (Query Engine)
• 5.4 上下文管理 (Context)
• 5.5 状态管理 (State)
• 5.6 命令系统 (Commands)
• 6. UI 框架
• 7. 服务层架构
• 8. 七大隐藏子系统
• 8.1 BUDDY — AI 电子宠物
• 8.2 KAIROS — 持久助手模式
• 8.3 ULTRAPLAN — 云端深度规划
• 8.4 Coordinator — 多 Agent 编排
• 8.5 Bridge — 远程遥控终端
• 8.6 Voice — 语音交互
• 8.7 Proactive — 主动自主模式
• 9. 三层功能门控体系
• 10. 安全架构
• 11. 插件与技能生态
• 12. 辅助模块一览
• 13. 开发与构建
• 14. 还原特殊说明
• 15. 架构评价与总结

1. 项目概述

Claude Code 是 Anthropic 开发的命令行 AI 编程助手。用户在终端中与 Claude 模型交互，可以执行 shell 命令、读写文件、搜索代码、管理 MCP 资源等。本仓库是从官方 npm 包的 source map 中还原的完整 TypeScript 源代码，包含了大量在外部发布版中被编译时裁剪的内部功能。

核心定位：

• 终端内的 AI 编程伙伴（REPL 式交互）
• 支持多模型后端（Anthropic 直连 / AWS Bedrock / Google Vertex）
• 完整的工具链（文件操作、Shell 执行、Web 搜索、LSP、MCP）
• 多 Agent 协作能力（Coordinator / Worker 架构）
• 持久化助手模式（跨会话记忆与自主运行）

2. 技术栈与依赖

运行时与语言

关键依赖

本地 Shim 包

项目在 shims/ 目录下提供了 7 个本地包，用于替代无法直接使用的原生 NAPI 模块：

• ant-claude-for-chrome-mcp — Chrome 浏览器 MCP 适配
• ant-computer-use-input — 计算机使用输入模块
• ant-computer-use-mcp — 计算机使用 MCP 服务端
• ant-computer-use-swift — macOS Swift 计算机操作
• color-diff-napi — 颜色差值计算
• modifiers-napi — 修饰键检测
• url-handler-napi — URL 处理

3. 项目规模

4. 启动流程与入口点

CLI 采用多阶段初始化管线，重点优化启动速度：

bun run dev     │     ▼┌─────────────────────────────────────────┐│  src/dev-entry.ts                       ││  验证层：扫描 src/ 和 vendor/ 目录，    ││  检测缺失的相对导入                     │└────────────────┬────────────────────────┘                 │                 ▼┌─────────────────────────────────────────┐│  src/main.tsx  (~1600 行)               ││  主入口：                               ││  ① 并行预取: MDM/Keychain/API预连接     ││  ② profileCheckpoint() 性能标记         ││  ③ Feature Gate 条件加载               ││  ④ Commander.js CLI 参数解析            ││  ⑤ 根据模式选择入口 (REPL/Server/...)  │└────────────────┬────────────────────────┘                 │                 ▼┌─────────────────────────────────────────┐│  src/setup.ts                           ││  环境验证与初始化：                     ││  ① Node.js 版本检查                     ││  ② Git 检测与 Worktree 管理            ││  ③ 终端备份/恢复 (iTerm2/Terminal)      ││  ④ Tmux 会话创建                        ││  ⑤ Session ID 生成与持久化              │└────────────────┬────────────────────────┘                 │                 ▼┌─────────────────────────────────────────┐│  src/entrypoints/init.ts                ││  信任后初始化：                         ││  ① 遥测系统 (OpenTelemetry+Datadog)    ││  ② 策略限制与托管设置加载              ││  ③ Bootstrap 数据拉取                  ││  ④ LSP Server Manager 初始化           │└─────────────────────────────────────────┘

启动优化要点：

• 预取链（MDM 读取、Keychain 查找、API 预连接）并行执行
• bun:bundle 编译时死代码消除（Feature Gate 控制）
• 延迟加载：Coordinator、Assistant、Voice 等模块按需 dynamic require()

5. 核心架构

5.1 工具系统 (Tool System)

文件位置：src/Tool.ts（类型定义）、src/tools.ts（注册与路由）、src/tools/（50+ 工具实现）

工具是 Claude Code 最核心的抽象，每个工具代表 Claude 可以调用的一个能力：

工具分类

工具执行流程

用户/模型请求工具     │     ▼toolMatchesName() → findToolByName()  ← 名称匹配     │     ▼useCanUseTool() Hook                   ← 权限检查 (auto/ask/deny)     │     ▼ToolUseContext 构建                    ← 注入上下文（用户输入、工作目录、模型列表）     │     ▼Tool.execute()                         ← 执行     │     ▼结果返回 + 成本追踪

5.2 任务系统 (Task System)

文件位置：src/Task.ts、src/tasks.ts、src/tasks/

任务系统支持多种执行模式的后台运行：

生命周期：TaskHandle → AbortController → 磁盘输出文件 + 偏移量跟踪

5.3 查询引擎 (Query Engine)

文件位置：src/QueryEngine.ts、src/query.ts

多轮对话的中央编排器：

用户输入  → processUserInput()         // 输入预处理与归一化  → Message normalization       // 消息格式化  → Tool execution loop         // 工具执行循环  → Cost tracking / API calls   // 成本追踪与 API 调用  → State updates               // 状态更新  → UI rendering                // UI 渲染

关键特性：

• Token 预算控制：calculateTokenWarningState() 防止预算溢出
• 自动压缩：接近上下文限制时基于边界的消息压缩
• 响应式压缩（Feature-gated）：基于启发式的智能消息折叠
• 上下文折叠（Feature-gated）：大上下文场景的专用压缩策略

5.4 上下文管理 (Context)

文件位置：src/context.ts

采用双层上下文注入：

上下文进行了 Memoize 缓存，并支持注入覆盖（setSystemPromptInjection()）以用于调试。

5.5 状态管理 (State)

文件位置：src/state/AppState.tsx

采用类 Redux 的集中式状态管理：

AppState = {  messages: Message[]              // 对话消息  tasks: TaskStateBase[]           // 后台任务  permissions: OrphanedPermission[] // 权限状态  notifications: Notification[]     // 通知列表  conversation: ConversationState   // 对话状态// ...}

状态操作模式：

• getAppState() — 只读快照
• setAppState(f => newState) — 不可变更新
• onChangeAppState() — 订阅回调（副作用触发）

Reaction 系统：

• 消息变化 → 文件历史快照
• 任务状态跟踪更新
• 记忆文件同步
• 团队记忆操作

5.6 命令系统 (Commands)

文件位置：src/commands.ts（注册）、src/commands/（40+ 子目录）

每个斜杠命令对应一个 kebab-case 目录下的模块：

命令解析流程：用户输入 /commandName args → messageQueueManager.ts 解析 → 修改消息队列优先级 → 直接响应或排队处理。

6. UI 框架

终端 UI 架构

React 组件     │     ▼Ink 渲染器 (src/ink.ts)     │     ▼Yoga 布局引擎 (src/native-ts/yoga-layout/)  ← 纯 TS 移植的 Flexbox 引擎     │     ▼ANSI 终端输出

• ThemeProvider 包裹全局渲染
• 同步输出 支持并发渲染场景
• 主题切换 支持多种终端配色方案

组件库（100+ 组件）

Hook 系统（60+ Hooks）

7. 服务层架构

API 服务 (src/services/api/)

• bootstrap.ts — 客户端数据与模型选项拉取
• claude.ts — 流式 API 调用 + 用量追踪
• filesApi.ts — 文件上传/下载
• errors.ts — API 错误分类（可重试 vs 永久性错误）
• withRetry.ts — 指数退避重试逻辑

MCP 服务 (src/services/mcp/)

• client.ts — 缓存化 MCP 客户端连接、工具/资源发现
• officialRegistry.ts — 官方 MCP 服务端注册表预取
• 传输适配器：stdio / SSE / WebSocket / HTTP

分析服务 (src/services/analytics/)

• growthbook.ts — Feature Gate 评估 + 本地缓存
• datadog.ts — Datadog 事件导出
• firstPartyEventLogger.ts — 第一方 BigQuery 导出（PII 标记列）
• 循环依赖防护：Analytics 服务隔离，无外部依赖

其他服务

8. 七大隐藏子系统

8.1 BUDDY — AI 电子宠物

源码位置：src/buddy/编译开关：feature('BUDDY')

终端里的拓麻歌子——一个完整的虚拟宠物系统。

• 18 种物种：鸭子、鹅、猫、龙、章鱼、猫头鹰、企鹅、乌龟、蜗牛、幽灵、六角恐龙、水豚、仙人掌、机器人、兔子、蘑菇、果冻、胖猫
• 5 级稀有度：普通(60%) → 非凡(25%) → 稀有(10%) → 史诗(4%) → 传说(1%)
• 1% 闪光概率：独立于稀有度的闪光个体
• 确定性生成：账号 UUID + 盐值 'friend-2026-401' → FNV-1a 哈希 → Mulberry32 PRNG → 每人固定一只
• 外观：6 种眼睛样式 + 8 种帽子（皇冠、巫师帽、光环等）
• 命令：/buddy pet（抚摸 + 爱心动画）、/buddy hatch（孵化）、/buddy card（查看卡片）
• 动画：3 帧 ASCII 精灵，500ms 帧率，窄终端自动退化为表情文字脸 =·ω·=

8.2 KAIROS — 持久助手模式

源码位置：src/assistant/、src/proactive/、src/services/autoDream/编译开关：feature('KAIROS')、feature('KAIROS_BRIEF')、feature('KAIROS_CHANNELS')

关掉终端 Claude 还在运行的持久助手。

• 跨会话持久：.claude/settings.json 中 assistant: true 激活
• 5 层激活链：编译标志 → settings.assistant → 信任检查 → GrowthBook → 全局状态
• 每日日志：自动写入 <autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md
• 自动做梦（Dream）：
• 触发条件：距上次超 24h + 5 条新会话 + 无并发锁
• 4 阶段：Orient → Gather → Consolidate → Prune
• 锁文件 .consolidate-lock + PID 存活检查
• 会话恢复：通过 OAuth API v1/sessions/{sessionId}/events 恢复历史
• 后台任务：命令超 15s 自动后台化，支持持久 cron（permanent: true）

8.3 ULTRAPLAN — 云端深度规划

源码位置：src/commands/ultraplan.tsx、src/utils/ultraplan/编译开关：feature('ULTRAPLAN')

将复杂问题交给云端 Opus 独立研究最长 30 分钟。

• 流程：/ultraplan <prompt> → 创建远程 CCR 会话 → Opus 独立研究 → 浏览器查看/修改 → 批准执行
• 传送机制：src/utils/teleport.tsx 实现 local ↔ remote 会话传输，通过 Git Bundle 打包上下文
• 关键词触发：消息包含 “ultraplan” 自动唤起（排除引号/路径中的误触发）
• 完全内部限定：isEnabled: () => "external" === 'ant'，外部版永远不可用

8.4 Coordinator — 多 Agent 编排

源码位置：src/coordinator/编译开关：feature('COORDINATOR_MODE')环境变量：CLAUDE_CODE_COORDINATOR_MODE

主 Claude 变成纯指挥官，Worker 并行执行任务。

• 角色分离：
• Coordinator 只有 3 个工具：Agent（派活）、SendMessage（通信）、Shutdown（停工）
• Worker 拥有完整工具集（排除内部工具）
• 核心纪律：系统提示要求”禁止甩锅式委派”——不能把不清楚的需求直接丢给 Worker
• 4 阶段工作流：研究（并行）→ 综合 → 实现 → 验证
• 任务共享：基于文件的共享任务列表 ~/.claude/tasks/
• Scratchpad：Agent 间通过临时文件通信

8.5 Bridge — 远程遥控终端

源码位置：src/bridge/（33 个文件）编译开关：feature('BRIDGE_MODE')、feature('DAEMON')

从 claude.ai 或手机远程操控本地 CLI。

• 双模式：独立守护进程 claude remote-control 或 REPL 内嵌 /remote-control
• 混合传输：WebSocket 读取 + HTTP POST 写入
• 3 种会话模式：单会话、隔离 worktree、共享目录
• 权限审计：远程端通过 bridgePermissionCallbacks.ts 审批权限请求
• JWT 刷新：定时刷新认证 Token
• 状态同步：bridgeStatusUtil.ts 实时同步运行状态
• 可信设备：trustedDevice.ts 设备信任管理

8.6 Voice — 语音交互

源码位置：src/voice/编译开关：feature('VOICE_MODE')

• STT（语音转文字）集成
• TTS（文字转语音）输出
• 关键词追踪与上下文补充
• GrowthBook 开关：tengu_cobalt_frost

8.7 Proactive — 主动自主模式

源码位置：src/proactive/编译开关：feature('PROACTIVE') / feature('KAIROS')

无人值守时 Claude 自己找活干。

• 空闲时调用 SleepTool 等待
• 接收周期性 <tick> 提示检查任务
• 与 KAIROS 深度集成

9. 三层功能门控体系

Anthropic 通过三层门控系统控制功能可用性，外部发布版本实质上是阉割版：

第一层：编译时开关 (feature())

约 50 个编译时标志，通过 bun:bundle 实现死代码消除。外部版被裁剪的主要功能包括：

第二层：用户类型 (USER_TYPE)

第三层：GrowthBook 远程 A/B 测试

10. 安全架构

权限模型

                ┌─────────────┐                │  auto 模式   │ ← 自动批准所有工具调用                ├─────────────┤                │  ask  模式   │ ← 交互式确认对话框                ├─────────────┤                │  deny 模式   │ ← 阻止所有调用                └─────────────┘

• Bash 命令分类器 (bashClassifier.ts)：语义分析 Shell 命令安全性
• 危险模式检测 (dangerousPatterns.ts)：正则 + 启发式检测文件删除、秘密外泄等
• YOLO 分类器：高置信度场景自动通过
• 拒绝追踪：DenialTrackingState 防止重复弹窗
• Scratchpad 权限门控：敏感操作额外审查

认证与信任

• 目录信任状态检查：防止仓库劫持（KAIROS 激活前验证）
• OAuth Scope 验证：Bridge 需要 user:profile 权限
• 组织 UUID 校验：团队功能需验证组织身份
• MDM 托管设备管理：Windows/macOS 企业策略支持

网络安全

• mTLS：内部服务双向 TLS (src/utils/mtls.ts)
• SSRF 防护：Hook 系统 SSRF Guard (src/utils/hooks/ssrfGuard.ts)
• MCP 服务端审批：Elicitation Handler 工作流
• 通道白名单：MCP 资源访问控制
• XSS 清洗：xss 库集成

数据保护

• 安全存储：macOS Keychain / 加密本地存储
• 秘密扫描：团队记忆同步时扫描 (secretScanner.ts)
• 反蒸馏：编译标志 ANTI_DISTILLATION_CC 保护模型

11. 插件与技能生态

插件系统

文件位置：src/services/plugins/、src/plugins/

插件类型

插件目录结构

my-plugin/├── plugin.json          # 可选的清单文件├── commands/            # 斜杠命令├── agents/              # AI Agent└── hooks/               # Hook 配置

功能：清单验证、Hook 配置加载、变量解析、重复检测、启用/禁用状态持久化。

技能系统

文件位置：src/skills/

• 内置技能：registerBundledSkill() 启动时注册
• 磁盘技能：.claude/skills/*.md 目录下的 Markdown 文件
• 技能提取：注入基础目录用于文件访问
• 每技能 Hook：HooksSettings 配置

12. 辅助模块一览

工具函数 (src/utils/)

200+ 文件，涵盖：

成本追踪 (src/cost-tracker.ts)

• 按模型使用量累计
• 缓存 Token 记账（创建 vs 读取）
• 快速模式成本乘数
• Advisor 专属用量
• 可打印成本摘要

13. 开发与构建

命令

代码风格

• ESM 导入（无 CommonJS 混用，Feature-gated 动态 require 除外）
• TypeScript + react-jsx 编译模式
• 省略分号、单引号
• PascalCase：组件/类，camelCase：函数/变量，kebab-case：命令目录

测试现状

• 无统一自动化测试套件
• 验证方式：
• bun run dev 交互式冒烟测试
• bun run version 版本输出验证
• 特定模块手动测试
• 代码中嵌入的验证：
• Zod Schema 验证所有 API payload
• 权限决策 Hook 测试
• 解析器内嵌测试（Bash、frontmatter、cliArgs）

14. 还原特殊说明

本仓库是非官方还原版本，需注意：

1. 数据来源：从 npm 包 @anthropic-ai/claude-code 的 cli.js.map 中提取 sourcesContent
2. Shim 替代：/shims/ 中的包用 JS 回退替代了原生 NAPI 模块
3. Vendor 目录：vendor/ 包含音频/图像处理器的原始源码
4. 版本标记：999.0.0-restored 表示还原而非正式版本
5. 代码版权：归 Anthropic 所有，仅供研究学习
6. 依赖版本：所有依赖使用 "*" 通配版本（还原限制）
7. 构建差异：无法复现原始编译时的 Feature Gate 裁剪行为（所有代码均包含）

15. 架构评价与总结

架构亮点

架构复杂度

• 1,421 个源文件 / 20 万行代码 — 对一个 CLI 工具而言规模极大
• 50 个 Feature Flag — 门控系统复杂但有效支撑内外版本分治
• 7 大隐藏子系统 — 展现了 Anthropic 在 AI Agent 方向的深度布局：
• 宠物系统（用户粘性）
• 持久助手（7×24 运行）
• 多 Agent 编排（并行执行）
• 云端规划（深度推理）
• 远程控制（跨设备）
• 语音交互（多模态）
• 主动模式（自主运行）

总体结论

Claude Code 不仅仅是一个终端 AI 助手，它是 Anthropic AI Agent 平台的技术验证场。通过还原的源码可以看到，Anthropic 在 AI 自主运行（KAIROS）、多 Agent 协作（Coordinator）、持久化记忆（Dream）、远程编排（Bridge/Ultraplan）等方向已有深度实现。外部发布版本经过三层门控裁剪后，仅暴露了核心交互能力的冰山一角。