502 lines
17 KiB
Markdown
502 lines
17 KiB
Markdown
# Claude Code v2.1.88 源码分析报告
|
||
|
||
> 分析日期：2026-03-31
|
||
> 源码版本：anthropic-ai-claude-code-2.1.88
|
||
> 总文件数：1,884 个源文件（.ts/.tsx）
|
||
> 总代码行数：约 512,664 行
|
||
|
||
---
|
||
|
||
## 一、项目概览
|
||
|
||
Claude Code 是 Anthropic 官方的 CLI 交互式编程助手。它基于 **Bun 运行时** 构建，使用 **React + Ink** 渲染终端 UI，通过 Anthropic API 与 Claude 模型交互，为用户提供代码编写、调试、文件操作等软件工程任务支持。
|
||
|
||
### 技术栈
|
||
|
||
| 类别 | 技术 |
|
||
|------|------|
|
||
| 运行时 | Bun |
|
||
| 语言 | TypeScript / TSX |
|
||
| CLI 框架 | Commander.js (`@commander-js/extra-typings`) |
|
||
| 终端 UI | React + Ink（自定义 fork） |
|
||
| AI SDK | `@anthropic-ai/sdk` (Beta Messages API) |
|
||
| 协议 | MCP (Model Context Protocol) |
|
||
| 构建 | Bun bundler（`bun:bundle` feature flags） |
|
||
|
||
---
|
||
|
||
## 二、整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ entrypoints/cli.tsx │ ← 入口
|
||
├─────────────────────────────────────────────────────┤
|
||
│ main.tsx │ ← CLI 参数解析 + 初始化
|
||
├─────────────────────────────────────────────────────┤
|
||
│ screens/REPL.tsx │ ← 主交互界面（React 组件）
|
||
├──────────┬──────────┬───────────┬───────────────────┤
|
||
│ query.ts │ tools.ts │commands.ts│ QueryEngine.ts │ ← 核心调度层
|
||
├──────────┴──────────┴───────────┴───────────────────┤
|
||
│ services/api/claude.ts │ services/mcp/client.ts │ ← API 通信层
|
||
├──────────────────────────┴──────────────────────────┤
|
||
│ tools/ │ skills/ │ hooks/ │ tasks/ │ ← 功能实现层
|
||
├─────────────────────────────────────────────────────┤
|
||
│ utils/ │ state/ │ constants/ │ types/ │ ← 基础设施层
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心模块详解
|
||
|
||
### 3.1 入口与启动流程
|
||
|
||
**文件**: `src/entrypoints/cli.tsx`
|
||
|
||
启动经过精心优化的多阶段引导：
|
||
|
||
1. **快速路径（Fast Path）**: `--version` 直接输出版本号，零模块加载
|
||
2. **特殊模式检查**: `--dump-system-prompt`, `--claude-in-chrome-mcp`, `--chrome-native-host` 等
|
||
3. **主路径**: 动态导入 `main.tsx`，进入完整 CLI 初始化
|
||
|
||
**文件**: `src/main.tsx`（4,683 行，最核心文件之一）
|
||
|
||
主函数负责：
|
||
- 并行预取：MDM 配置、Keychain 凭证、OAuth、GrowthBook 特性开关
|
||
- Commander.js 命令行参数解析
|
||
- 初始化分析（analytics）、策略限制（policy limits）、远程托管设置
|
||
- 加载 MCP 服务器、工具列表、技能系统、插件系统
|
||
- 启动 React/Ink 渲染 → `REPL` 组件
|
||
|
||
### 3.2 REPL 主界面
|
||
|
||
**文件**: `src/screens/REPL.tsx`（5,005 行）
|
||
|
||
核心交互组件，包含：
|
||
- 消息列表渲染（虚拟滚动）
|
||
- 用户输入处理（含 Vim 模式）
|
||
- 权限请求对话框
|
||
- 成本追踪与显示
|
||
- Agent/Teammate 管理
|
||
- 会话持久化与恢复
|
||
|
||
### 3.3 查询引擎（Query Loop）
|
||
|
||
**文件**: `src/query.ts` — 单次对话轮次的核心循环
|
||
**文件**: `src/QueryEngine.ts` — 高级查询引擎（SDK/非交互模式）
|
||
|
||
对话流程：
|
||
```
|
||
用户输入 → System Prompt 构建 → API 调用(streaming) → 解析响应
|
||
↓
|
||
tool_use → 权限检查 → 工具执行 → 结果返回 → 继续 API 调用
|
||
↓
|
||
end_turn → 展示结果给用户
|
||
```
|
||
|
||
关键机制：
|
||
- **Auto Compact**: 上下文接近限制时自动压缩对话历史
|
||
- **Reactive Compact**: 更智能的上下文折叠（feature flag 控制）
|
||
- **Token Budget**: 工具结果的 token 预算管理
|
||
- **Fingerprint**: 消息去重与缓存优化
|
||
|
||
### 3.4 API 通信层
|
||
|
||
**文件**: `src/services/api/claude.ts`（3,419 行）
|
||
|
||
- 使用 Anthropic SDK 的 **Beta Messages API**（支持 streaming）
|
||
- 支持多 provider：Anthropic 直连、AWS Bedrock、GCP Vertex
|
||
- 处理 Betas 特性（extended thinking、tool use 等）
|
||
- 请求指纹计算（用于 prompt cache）
|
||
- 重试与错误处理策略
|
||
|
||
---
|
||
|
||
## 四、工具系统（Tools）
|
||
|
||
### 4.1 工具接口
|
||
|
||
**文件**: `src/Tool.ts`
|
||
|
||
核心类型 `ToolUseContext` 定义了工具执行的完整上下文，包括：
|
||
- 可用工具列表、命令、MCP 客户端
|
||
- `AbortController` 中断控制
|
||
- `AppState` 读写
|
||
- 文件状态缓存、权限上下文
|
||
- Agent/子代理相关状态
|
||
|
||
### 4.2 工具注册
|
||
|
||
**文件**: `src/tools.ts`
|
||
|
||
所有工具在此文件中集中注册。支持条件加载（通过 `bun:bundle` feature flags）：
|
||
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| **BashTool** | 执行 shell 命令 |
|
||
| **FileReadTool** | 读取文件 |
|
||
| **FileEditTool** | 编辑文件（精确替换） |
|
||
| **FileWriteTool** | 写入文件 |
|
||
| **GlobTool** | 文件模式匹配搜索 |
|
||
| **GrepTool** | 内容正则搜索（基于 ripgrep） |
|
||
| **WebFetchTool** | 抓取网页内容 |
|
||
| **WebSearchTool** | 网页搜索 |
|
||
| **AgentTool** | 启动子代理 |
|
||
| **SendMessageTool** | 向子代理发送消息 |
|
||
| **NotebookEditTool** | 编辑 Jupyter Notebook |
|
||
| **AskUserQuestionTool** | 向用户提问 |
|
||
| **EnterPlanModeTool** | 进入计划模式 |
|
||
| **ExitPlanModeTool** | 退出计划模式 |
|
||
| **EnterWorktreeTool** | 创建 Git Worktree |
|
||
| **ExitWorktreeTool** | 退出 Git Worktree |
|
||
| **TaskCreateTool** | 创建任务 |
|
||
| **TaskUpdateTool** | 更新任务 |
|
||
| **TaskGetTool** | 获取任务详情 |
|
||
| **TaskListTool** | 列出任务 |
|
||
| **TaskOutputTool** | 获取任务输出 |
|
||
| **TaskStopTool** | 停止任务 |
|
||
| **SkillTool** | 执行技能 |
|
||
| **TodoWriteTool** | 写入待办事项 |
|
||
| **LSPTool** | Language Server Protocol 交互 |
|
||
| **MCPTool** | 调用 MCP 工具 |
|
||
| **ToolSearchTool** | 搜索可用工具 |
|
||
| **ConfigTool** | 配置管理 |
|
||
| **BriefTool** | 简洁模式 |
|
||
| **ScheduleCronTool** | 定时任务（CronCreate/Delete/List） |
|
||
| **ListMcpResourcesTool** | 列出 MCP 资源 |
|
||
| **ReadMcpResourceTool** | 读取 MCP 资源 |
|
||
|
||
**内部/实验性工具**（feature flag 控制）：
|
||
- `REPLTool` — 仅内部用户
|
||
- `SleepTool` — 主动等待
|
||
- `RemoteTriggerTool` — 远程触发
|
||
- `MonitorTool` — 监控工具
|
||
- `SendUserFileTool` — 发送文件给用户（KAIROS）
|
||
- `PushNotificationTool` — 推送通知
|
||
- `SubscribePRTool` — PR 订阅
|
||
- `TeamCreateTool` / `TeamDeleteTool` — 团队/多代理管理
|
||
- `TungstenTool` — 内部工具
|
||
|
||
### 4.3 Bash 工具安全系统
|
||
|
||
**文件**: `src/tools/BashTool/bashSecurity.ts`（2,592 行）
|
||
**文件**: `src/tools/BashTool/bashPermissions.ts`（2,621 行）
|
||
|
||
Bash 工具有最复杂的安全系统：
|
||
- 命令白名单/黑名单
|
||
- 破坏性命令检测（rm -rf, git push --force 等）
|
||
- 沙箱模式
|
||
- Bash AST 解析器（`bashParser.ts` 4,436 行）用于静态分析命令安全性
|
||
|
||
---
|
||
|
||
## 五、权限系统
|
||
|
||
### 5.1 权限模式
|
||
|
||
**文件**: `src/types/permissions.ts`
|
||
|
||
三种权限模式：
|
||
- **`default`**: 默认模式，危险操作需要用户确认
|
||
- **`plan`**: 计划模式，只读操作
|
||
- **`bypass`**: 跳过权限检查（需用户明确启用）
|
||
|
||
### 5.2 权限规则
|
||
|
||
```typescript
|
||
type ToolPermissionContext = {
|
||
mode: PermissionMode
|
||
alwaysAllowRules: ToolPermissionRulesBySource // 始终允许
|
||
alwaysDenyRules: ToolPermissionRulesBySource // 始终拒绝
|
||
alwaysAskRules: ToolPermissionRulesBySource // 始终询问
|
||
isBypassPermissionsModeAvailable: boolean
|
||
}
|
||
```
|
||
|
||
权限规则可在多个层级配置：
|
||
- 全局设置 (`~/.claude/settings.json`)
|
||
- 项目设置 (`.claude/settings.json`)
|
||
- 命令行参数
|
||
- 运行时用户选择
|
||
|
||
---
|
||
|
||
## 六、任务系统（Tasks）
|
||
|
||
**文件**: `src/Task.ts`
|
||
|
||
支持的任务类型：
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `local_bash` | 本地 Shell 后台命令 |
|
||
| `local_agent` | 本地子代理 |
|
||
| `remote_agent` | 远程代理 |
|
||
| `in_process_teammate` | 进程内协作者（多代理） |
|
||
| `local_workflow` | 本地工作流 |
|
||
| `monitor_mcp` | MCP 监控 |
|
||
| `dream` | Dream 任务（后台推理） |
|
||
|
||
任务状态机：`pending → running → completed/failed/killed`
|
||
|
||
---
|
||
|
||
## 七、MCP 集成
|
||
|
||
**文件**: `src/services/mcp/client.ts`（3,348 行）
|
||
**文件**: `src/services/mcp/auth.ts`（2,465 行）
|
||
|
||
MCP (Model Context Protocol) 深度集成：
|
||
- 支持 stdio 和 SSE 传输
|
||
- OAuth 2.0 认证流程
|
||
- 工具、资源、提示的完整支持
|
||
- 官方 MCP 服务器注册表（`officialRegistry.ts`）
|
||
- 连接生命周期管理（`MCPConnectionManager.tsx`）
|
||
- 通道权限控制（`channelPermissions.ts`）
|
||
|
||
---
|
||
|
||
## 八、技能系统（Skills）
|
||
|
||
**文件**: `src/skills/`
|
||
|
||
技能是更高级的命令抽象：
|
||
- `bundled/` — 内置技能
|
||
- `loadSkillsDir.ts` — 从目录加载自定义技能
|
||
- `mcpSkillBuilders.ts` — 从 MCP 构建技能
|
||
- 支持用户通过 `/skill-name` 快捷调用
|
||
|
||
---
|
||
|
||
## 九、UI 系统
|
||
|
||
### 9.1 Ink 终端渲染
|
||
|
||
**文件**: `src/ink/`（96 个文件）
|
||
|
||
自定义的 Ink (React for CLI) 框架：
|
||
- `layout/` — 布局引擎（基于 Yoga layout）
|
||
- `components/` — 基础 UI 组件
|
||
- `hooks/` — React hooks（终端尺寸、焦点、搜索等）
|
||
- `termio/` — 终端 I/O 和 DEC 控制序列
|
||
- `events/` — 事件系统
|
||
|
||
### 9.2 主要组件
|
||
|
||
**文件**: `src/components/`（389 个文件）
|
||
|
||
关键组件包括：
|
||
- `PromptInput/` — 用户输入框（支持多行、Vim 模式）
|
||
- `VirtualMessageList` — 虚拟滚动消息列表
|
||
- `Spinner` — 加载动画
|
||
- `permissions/` — 权限请求 UI
|
||
- `mcp/` — MCP 相关 UI
|
||
- `MessageSelector` — 消息选择器
|
||
- `CostThresholdDialog` — 成本阈值对话框
|
||
|
||
---
|
||
|
||
## 十、命令系统
|
||
|
||
**文件**: `src/commands/`（207 个文件）
|
||
|
||
Slash 命令系统（用户通过 `/command` 触发）：
|
||
|
||
| 分类 | 命令示例 |
|
||
|------|---------|
|
||
| **Git** | `/commit`, `/branch`, `/diff`, `/pr_comments`, `/review` |
|
||
| **会话** | `/resume`, `/session`, `/compact`, `/clear`, `/exit` |
|
||
| **配置** | `/config`, `/model`, `/theme`, `/permissions`, `/vim` |
|
||
| **工具** | `/mcp`, `/plugin`, `/skills`, `/hooks` |
|
||
| **调试** | `/doctor`, `/debug-tool-call`, `/cost`, `/stats`, `/perf-issue` |
|
||
| **AI 模式** | `/plan`, `/fast`, `/effort`, `/brief`, `/thinkback` |
|
||
| **协作** | `/agents`, `/tasks`, `/teleport`, `/remote-setup` |
|
||
| **其他** | `/memory`, `/export`, `/help`, `/feedback`, `/version` |
|
||
|
||
---
|
||
|
||
## 十一、服务层
|
||
|
||
**文件**: `src/services/`（130 个文件）
|
||
|
||
| 服务 | 说明 |
|
||
|------|------|
|
||
| `api/` | Anthropic API 通信（claude.ts, bootstrap.ts, filesApi.ts） |
|
||
| `mcp/` | MCP 协议客户端和服务器管理 |
|
||
| `oauth/` | OAuth 2.0 认证 |
|
||
| `analytics/` | 分析追踪（GrowthBook 特性开关） |
|
||
| `compact/` | 对话压缩（autoCompact, reactiveCompact） |
|
||
| `policyLimits/` | 策略限制管理 |
|
||
| `remoteManagedSettings/` | 远程托管设置 |
|
||
| `plugins/` | 插件加载与管理 |
|
||
| `SessionMemory/` | 会话记忆 |
|
||
| `tips/` | 使用提示 |
|
||
| `lsp/` | LSP 服务 |
|
||
| `tools/` | 工具相关服务 |
|
||
| `extractMemories/` | 自动记忆提取 |
|
||
| `voice/` | 语音交互 |
|
||
|
||
---
|
||
|
||
## 十二、状态管理
|
||
|
||
**文件**: `src/state/`
|
||
|
||
- `AppState.tsx` — 全局应用状态类型定义
|
||
- `AppStateStore.ts` — 状态存储实现
|
||
- `store.ts` — 状态存储工厂
|
||
- `selectors.ts` — 状态选择器
|
||
- `onChangeAppState.ts` — 状态变更监听
|
||
|
||
状态包含：消息列表、任务状态、权限上下文、MCP 连接、成本追踪等。
|
||
|
||
---
|
||
|
||
## 十三、辅助系统
|
||
|
||
### 13.1 记忆系统
|
||
**文件**: `src/memdir/`（8 个文件）
|
||
管理 `MEMORY.md` 和持久化记忆目录，跨会话保持上下文。
|
||
|
||
### 13.2 Vim 模式
|
||
**文件**: `src/vim/`（5 个文件）
|
||
终端输入框支持 Vim 键绑定。
|
||
|
||
### 13.3 语音交互
|
||
**文件**: `src/services/voice.ts`, `voiceStreamSTT.ts`
|
||
语音输入支持（STT）。
|
||
|
||
### 13.4 代理群集（Agent Swarms）
|
||
**文件**: `src/utils/swarm/`
|
||
支持多代理协作：leader/worker 权限同步、team 管理、沙箱权限请求。
|
||
|
||
### 13.5 插件系统
|
||
**文件**: `src/services/plugins/`, `src/utils/plugins/`
|
||
- `pluginLoader.ts`（3,302 行）— 插件加载器
|
||
- `marketplaceManager.ts`（2,643 行）— 插件市场管理
|
||
- 支持内置插件和第三方插件
|
||
|
||
---
|
||
|
||
## 十四、Feature Flags 系统
|
||
|
||
通过 `bun:bundle` 的 `feature()` 函数实现编译时特性开关：
|
||
|
||
| Flag | 功能 |
|
||
|------|------|
|
||
| `ABLATION_BASELINE` | A/B 测试基线 |
|
||
| `DUMP_SYSTEM_PROMPT` | 导出系统提示 |
|
||
| `PROACTIVE` | 主动模式 |
|
||
| `KAIROS` | Assistant 模式 |
|
||
| `AGENT_TRIGGERS` | 定时任务 |
|
||
| `AGENT_TRIGGERS_REMOTE` | 远程触发 |
|
||
| `MONITOR_TOOL` | 监控工具 |
|
||
| `COORDINATOR_MODE` | 协调器模式 |
|
||
| `REACTIVE_COMPACT` | 响应式压缩 |
|
||
| `CONTEXT_COLLAPSE` | 上下文折叠 |
|
||
| `KAIROS_GITHUB_WEBHOOKS` | GitHub Webhook |
|
||
| `KAIROS_PUSH_NOTIFICATION` | 推送通知 |
|
||
|
||
外部构建通过 DCE（Dead Code Elimination）移除内部功能。
|
||
|
||
---
|
||
|
||
## 十五、关键文件索引
|
||
|
||
| 文件 | 行数 | 功能 |
|
||
|------|------|------|
|
||
| `cli/print.ts` | 5,594 | 非交互式输出/打印模式 |
|
||
| `utils/messages.ts` | 5,512 | 消息创建与处理 |
|
||
| `utils/sessionStorage.ts` | 5,105 | 会话持久化存储 |
|
||
| `utils/hooks.ts` | 5,022 | Hooks 系统实现 |
|
||
| `screens/REPL.tsx` | 5,005 | 主 REPL 界面 |
|
||
| `main.tsx` | 4,683 | 主入口/初始化 |
|
||
| `utils/bash/bashParser.ts` | 4,436 | Bash 命令解析器 |
|
||
| `utils/attachments.ts` | 3,997 | 附件处理 |
|
||
| `services/api/claude.ts` | 3,419 | API 通信 |
|
||
| `services/mcp/client.ts` | 3,348 | MCP 客户端 |
|
||
| `utils/plugins/pluginLoader.ts` | 3,302 | 插件加载器 |
|
||
| `commands/insights.ts` | 3,200 | 洞察命令 |
|
||
| `bridge/bridgeMain.ts` | 2,999 | Bridge 主进程 |
|
||
| `utils/bash/ast.ts` | 2,679 | Bash AST |
|
||
| `tools/BashTool/bashPermissions.ts` | 2,621 | Bash 权限 |
|
||
| `tools/BashTool/bashSecurity.ts` | 2,592 | Bash 安全 |
|
||
|
||
---
|
||
|
||
## 十六、架构亮点
|
||
|
||
### 1. 启动性能优化
|
||
- 多阶段懒加载：快速路径零导入，主路径并行预取
|
||
- `startupProfiler.ts` 追踪每个启动阶段耗时
|
||
- MDM、Keychain、OAuth 凭证并行预取
|
||
|
||
### 2. 安全设计
|
||
- Bash 命令 AST 级静态分析
|
||
- 多层权限控制（白名单、黑名单、始终询问）
|
||
- 沙箱模式隔离
|
||
- 破坏性操作自动检测与拦截
|
||
|
||
### 3. 多代理架构
|
||
- 子代理（AgentTool）支持并发执行
|
||
- 团队协作（TeamCreate/TeamDelete）
|
||
- 进程内协作者（InProcessTeammate）
|
||
- 远程代理（RemoteAgent）
|
||
- Leader/Worker 权限同步
|
||
|
||
### 4. 上下文管理
|
||
- Auto Compact 自动压缩历史
|
||
- Reactive Compact 智能压缩
|
||
- Context Collapse 上下文折叠
|
||
- Token Budget 精细控制
|
||
- 文件状态缓存 LRU
|
||
|
||
### 5. 可扩展性
|
||
- 插件系统 + 插件市场
|
||
- MCP 协议集成
|
||
- 自定义技能
|
||
- Hooks 系统
|
||
- Feature Flags 编译时裁剪
|
||
|
||
---
|
||
|
||
## 十七、数据流图
|
||
|
||
```
|
||
User Input
|
||
│
|
||
▼
|
||
┌─────────────┐ ┌──────────────┐
|
||
│ PromptInput │────▶│ REPL.tsx │
|
||
└─────────────┘ └──────┬───────┘
|
||
│
|
||
┌──────▼───────┐
|
||
│ query.ts │ ◄── System Prompt (constants/prompts.ts)
|
||
│ (主循环) │ ◄── Memory (memdir/)
|
||
└──────┬───────┘ ◄── CLAUDE.md
|
||
│
|
||
┌──────▼───────┐
|
||
│ claude.ts │ ── Anthropic Beta Messages API (streaming)
|
||
│ (API 调用) │
|
||
└──────┬───────┘
|
||
│
|
||
┌────────────┼────────────┐
|
||
▼ ▼ ▼
|
||
text_delta tool_use end_turn
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
渲染文本 ┌─────────┐ 返回结果
|
||
│权限检查 │
|
||
└────┬────┘
|
||
│
|
||
┌────▼────┐
|
||
│工具执行 │ → BashTool / FileReadTool / AgentTool / ...
|
||
└────┬────┘
|
||
│
|
||
tool_result → 继续 API 调用（循环）
|
||
```
|
||
|
||
---
|
||
|
||
*报告生成完毕。源代码已还原至 `package/source/src/` 目录。*
|