Claude Code CLI 源码深度分析报告

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. 技术栈与依赖

运行时与语言

项目	选型
运行时	Bun ≥ 1.3.5（同时要求 Node.js ≥ 24）
语言	TypeScript（ESM、react-jsx）
模块系统	ESM（`"type": "module"`）
编译目标	ESNext

关键依赖

依赖	用途
`@anthropic-ai/sdk`	Claude API 客户端（流式消息、beta 特性）
`@modelcontextprotocol/sdk`	MCP 协议客户端/服务端
`react` + `ink`	终端 UI 框架（React 组件 → 终端渲染）
`@commander-js/extra-typings`	CLI 参数解析
`zod`	运行时 Schema 验证
`@growthbook/growthbook`	远程 A/B 测试与功能门控
OpenTelemetry 系列	可观测性（Metrics / Traces / Logs）
`axios` / `undici`	HTTP 客户端（OAuth、Bootstrap 数据）
`chalk` / `strip-ansi`	ANSI 终端着色
`lodash-es`	函数式工具函数
`ws`	WebSocket 客户端（Bridge 远程控制）
`chokidar`	文件系统监听
`yaml` / `jsonc-parser`	配置文件解析
`xss`	XSS 防护
`highlight.js` + `marked`	代码高亮与 Markdown 渲染

本地 Shim 包

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

ant-claude-for-chrome-mcp

ant-computer-use-input

ant-computer-use-mcp

ant-computer-use-swift

color-diff-napi

modifiers-napi

url-handler-napi

— URL 处理

3. 项目规模

指标	数据
TypeScript/TSX 文件数	~1,421 个
估算代码行数	200,000+ LOC
工具实现	50+
斜杠命令	40+ 公开 + 20+ 隐藏
React 组件	100+
React Hooks	60+
服务子目录	35+
工具函数文件	200+
编译时 Feature Flag	~50
GrowthBook 远程开关	10+
Schema 迁移文件	11

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 初始化           │
└─────────────────────────────────────────┘

启动优化要点：

bun:bundle

dynamic require()

5. 核心架构

5.1 工具系统 (Tool System)

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

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

工具分类

类别	工具
核心工具	BashTool, FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool
搜索与网络	WebFetchTool, WebSearchTool
Agent 工具	AgentTool, SkillTool
任务工具	TaskCreateTool, TaskUpdateTool, TaskListTool, TaskStopTool, TaskGetTool, TaskOutputTool
MCP 工具	ListMcpResourcesTool, ReadMcpResourceTool
交互工具	AskUserQuestionTool
高级工具	LSPTool, BriefTool
KAIROS 专属	SleepTool, SendUserFileTool, PushNotificationTool, SubscribePRTool
ANT-only	REPLTool, SuggestBackgroundPRTool
定时任务	CronCreateTool, CronDeleteTool, CronListTool

工具执行流程

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

5.2 任务系统 (Task System)

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

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

任务类型	说明
`local_bash`	本地 Shell 命令执行
`local_agent`	本地子进程中分叉 Agent
`remote_agent`	通过 Bridge 远程执行 Agent
`in_process_teammate`	Coordinator 模式下进程内 Worker
`local_workflow`	工作流脚本执行（Feature-gated）
`monitor_mcp`	MCP 资源监控（Feature-gated）
`dream`	KAIROS 记忆整合任务

生命周期：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

采用双层上下文注入：

层级	内容	注入方式
用户上下文	Git 分支/状态/提交、可用命令列表、记忆文件 `.claude/*.md`、项目/团队上下文、IDE 连接状态	`prependUserContext()`
系统上下文	日期/时间/时区、工作区尺寸/主题、版本信息、平台信息、API 提供商标识	`appendSystemContext()`

上下文进行了 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 目录下的模块：

类别	命令
认证	login, logout, init, onboarding
开发	diff, cost, status, doctor, config, memory
Git	commit, commit-push-pr, autofix-pr, pr-comments
工具	mcp, skills, help, ide
会话	resume, session, teleport, share
个性化	keybindings, theme, vim, tasks, review

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

6. UI 框架

终端 UI 架构

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

ThemeProvider

同步输出

主题切换

支持多种终端配色方案

组件库（100+ 组件）

领域	组件
消息	Message, MessageRow, MessageResponse, VirtualMessageList（虚拟滚动）
任务	TaskListV2, ResumeTask, TaskOutputTool
对话框	TrustDialog, ConsoleOAuthFlow, IdeAutoConnectDialog, ManagedSettingsSecurityDialog
输入	TextInput, SearchBox, ModelPicker, ThemePicker
状态	StatusLine, MemoryUsageIndicator, TokenWarning, Spinner
设置	Settings/ 文件夹（10+ 设置界面）

Hook 系统（60+ Hooks）

类别	Hook
输入	useTextInput, useVimInput, useCommandKeybindings, useArrowKeyHistory
状态	useMainLoopModel, useSettings, useSwarmInitialization, useSessionBackgrounding
集成	useIDEIntegration, useIdeSelection, useIdeConnectionStatus, useDirectConnect
工具	useCanUseTool（权限检查）, useMergedTools（本地 + MCP 工具合并）
搜索	useSearchInput, useHistorySearch
异步	useQueueProcessor, useMinDisplayTime, useNotifyAfterTimeout

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

适配器

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

growthbook.ts — Feature Gate 评估 + 本地缓存

datadog.ts — Datadog 事件导出

firstPartyEventLogger.ts — 第一方 BigQuery 导出（PII 标记列）循环依赖防护：Analytics 服务隔离，无外部依赖

其他服务

服务	用途
`SessionMemory/`	跨会话聊天历史持久化、消息恢复
`autoDream/`	KAIROS 记忆整合（Dream 机制）
`compact/`	消息压缩策略
`plugins/`	插件发现、加载、管理
`LangServer/`	LSP 服务管理

8. 七大隐藏子系统

8.1 BUDDY — AI 电子宠物

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

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

18 种物种：鸭子、鹅、猫、龙、章鱼、猫头鹰、企鹅、乌龟、蜗牛、幽灵、六角恐龙、水豚、仙人掌、机器人、兔子、蘑菇、果冻、胖猫

5 级稀有度：普通(60%) → 非凡(25%) → 稀有(10%) → 史诗(4%) → 传说(1%)

1% 闪光概率：独立于稀有度的闪光个体

确定性生成：账号 UUID + 盐值 'friend-2026-401'

外观：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 层激活链

每日日志：自动写入 <autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md

自动做梦（Dream）：触发条件：距上次超 24h + 5 条新会话 + 无并发锁4 阶段：Orient → Gather → Consolidate → Prune锁文件

.consolidate-lock

会话恢复：通过 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>

传送机制：src/utils/teleport.tsx

关键词触发：消息包含 "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 拥有完整工具集（排除内部工具）

核心纪律：系统提示要求"禁止甩锅式委派"——不能把不清楚的需求直接丢给 Worker4 阶段工作流：研究（并行）→ 综合 → 实现 → 验证任务共享：基于文件的共享任务列表 ~/.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 种会话模式

权限审计：远程端通过 bridgePermissionCallbacks.ts 审批权限请求

JWT 刷新：定时刷新认证 Token

状态同步：bridgeStatusUtil.ts

实时同步运行状态

可信设备：trustedDevice.ts

设备信任管理

8.6 Voice — 语音交互

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

tengu_cobalt_frost

8.7 Proactive — 主动自主模式

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

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

SleepTool

<tick>

提示检查任务与 KAIROS 深度集成

9. 三层功能门控体系

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

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

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

开关	功能
`BUDDY`	宠物伴侣系统
`KAIROS` / `KAIROS_BRIEF` / `KAIROS_CHANNELS`	持久助手与通道
`ULTRAPLAN`	云端深度规划
`COORDINATOR_MODE`	多 Agent 编排
`BRIDGE_MODE` / `DAEMON`	远程控制
`VOICE_MODE`	语音交互
`PROACTIVE`	主动自主模式
`FORK_SUBAGENT`	子代理分叉
`ANTI_DISTILLATION_CC`	反蒸馏保护
`CHICAGO_MCP`	Computer Use MCP
`TEAMMEM`	团队记忆同步
... 共计 ~50 个

第二层：用户类型 (`USER_TYPE`)

类型	特征
`ant`（Anthropic 内部）	全功能解锁、20 分钟 GrowthBook 刷新、调试工具、200+ 处专属检查
`external`（外部用户）	裁剪版、6 小时 GrowthBook 刷新

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

开关	功能
`tengu_kairos`	KAIROS 助手模式总开关
`tengu_onyx_plover`	自动做梦阈值
`tengu_cobalt_frost`	语音识别开关
`tengu_ultraplan_model`	Ultraplan 模型选择
`tengu_ant_model_override`	内部用户模型覆盖
`tengu_session_memory`	会话记忆功能
`tengu_max_version_config`	自动更新 Kill Switch
`tengu_ccr_bridge`	Bridge 远程控制开关

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/

插件类型

类型	说明
内置插件	`registerBuiltinPlugin()` 注册，Anthropic 维护（claudeApi, debug, verify, stuck 等）
市场插件	`plugin@marketplace` 格式发现与安装
会话插件	通过 CLI 参数 / SDK 选项注入
内联插件	`--plugin-dir` 指定目录

插件目录结构

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

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

技能系统

文件位置：src/skills/

内置技能：registerBundledSkill() 启动时注册

磁盘技能：.claude/skills/*.md 目录下的 Markdown 文件

技能提取：注入基础目录用于文件访问

每技能 Hook：HooksSettings

配置

12. 辅助模块一览

模块目录	用途
`src/native-ts/yoga-layout/`	纯 TypeScript 移植的 Flexbox 布局引擎（替代 C++ yoga）
`src/native-ts/color-diff/`	颜色差值计算
`src/native-ts/file-index/`	文件索引
`src/memdir/`	记忆目录管理：路径解析、相关记忆查找、记忆扫描、记忆老化
`src/migrations/`	Schema 迁移（11 个迁移文件）：Opus→Sonnet、设置合并等
`src/moreright/`	UI 布局组件
`src/ssh/`	SSH 会话管理：`createSSHSession.ts`、`SSHSessionManager.ts`
`src/upstreamproxy/`	上游代理中继：`relay.ts`、`upstreamproxy.ts`
`src/jobs/`	后台任务分类器
`src/remote/`	远程会话 WebSocket：`RemoteSessionManager`、`SessionsWebSocket`
`src/schemas/`	Zod Schema 验证
`src/server/`	直连会话管理：`DirectConnectSessionManager`
`src/vim/`	完整 Vim 模式引擎：motions / operators / textObjects / transitions
`src/keybindings/`	键位绑定系统：解析器、模板、用户自定义、Schema 验证
`src/outputStyles/`	自定义 ANSI 输出样式加载器
`src/ink/`	终端 UI 底层：70+ 文件（yoga-layout flexbox、ANSI 处理、事件处理）
`src/cli/`	CLI 参数定义与子命令注册
`src/bootstrap/`	启动状态管理

工具函数 (`src/utils/`)

200+ 文件，涵盖：

模块	职责
`git.ts`	异步 Git 操作（分支/状态/默认分支/无锁命令）
`claudemd.ts`	记忆文件发现、去重、过滤、上下文注入
`sessionStorage.ts`	转录记录、文件变更快照、跨项目恢复
`config.ts`	双级配置（全局 `~/.claude/` + 项目 `.claude/`）
`permissions/`	权限模式管理、Bash 分类器、危险模式检测
`plugins/`	插件加载器与管理
`model/`	模型选择与配置
`processUserInput/`	输入验证、文件 glob、附件去重
`hooks/`	SSRF Guard、Hook 注册
`mtls.ts`	双向 TLS

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

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

13. 开发与构建

命令

命令	用途
`bun install`	安装依赖 + 本地 shim 包
`bun run dev`	交互式启动 CLI
`bun run start`	同上（别名）
`bun run version`	验证 CLI 启动并打印版本

代码风格

react-jsx

编译模式省略分号、单引号PascalCase：组件/类，camelCase：函数/变量，kebab-case：命令目录

测试现状

无统一自动化测试套件

验证方式：

bun run dev

bun run version

代码中嵌入的验证：

14. 还原特殊说明

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

数据来源：从 npm 包 @anthropic-ai/claude-code 的 cli.js.map 中提取 sourcesContent

Shim 替代：/shims/ 中的包用 JS 回退替代了原生 NAPI 模块

Vendor 目录：vendor/ 包含音频/图像处理器的原始源码

版本标记：999.0.0-restored 表示还原而非正式版本

代码版权：归 Anthropic 所有，仅供研究学习

依赖版本：所有依赖使用 "*" 通配版本（还原限制）

构建差异：无法复现原始编译时的 Feature Gate 裁剪行为（所有代码均包含）

15. 架构评价与总结

架构亮点

方面	评价
启动性能	并行预取链、lazy-loading、编译时死代码消除，启动速度优化到位
可扩展性	插件 + 技能 + MCP + Hooks 四层扩展机制，生态开放
权限安全	工具级/会话级权限、Bash 语义分类器、SSRF 防护，安全层次分明
状态管理	不可变 AppState + 清理注册表，状态可控可追踪
可观测性	OpenTelemetry Span + Datadog + 1P 日志 + 性能检标点，全链路可观测
循环依赖防护	Analytics 服务隔离、延迟加载、依赖注入，工程纪律严谨
多模态支持	文本、语音、远程控制、IDE 集成四渠道交互

架构复杂度

1,421 个源文件 / 20 万行代码

50 个 Feature Flag

7 大隐藏子系统

总体结论

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