mirror of
https://github.com/roger2ai/Claude-Code-Compiled.git
synced 2026-05-08 21:05:45 +08:00
e627a9388d
- Move all .md documentation into docs/ directory - Rewrite README.md with English documentation covering: - All 22 missing source stubs added - Source code fixes (useEffectEvent, version check, auth, sandbox-runtime) - Bun compatibility shims (macro, bun-bundle) - 28 missing npm dependencies - Build and run instructions - Remove dist/ from tracking (users compile themselves)
494 lines
17 KiB
Markdown
494 lines
17 KiB
Markdown
# Claude Code — 架构全景
|
||
|
||
> 项目规模：~1,900 源文件，512,000+ 行 TypeScript/TSX
|
||
> 运行时：Bun | 终端 UI：React + Ink (自定义渲染器) | CLI：Commander.js
|
||
|
||
---
|
||
|
||
## 1. 整体架构分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ CLI 入口 (main.tsx) │
|
||
│ Commander.js 参数解析 → 会话初始化 → 渲染上下文 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ REPL 屏幕 (REPL.tsx) │
|
||
│ 主交互循环：用户输入 → LLM 查询 → 工具执行 → UI 渲染 │
|
||
├──────────┬──────────┬──────────┬────────────────────────┤
|
||
│ Commands │ Tools │ Services │ Bridge/Remote │
|
||
│ (斜杠命令)│ (工具系统)│ (服务层) │ (IDE/远程集成) │
|
||
├──────────┴──────────┴──────────┴────────────────────────┤
|
||
│ State Management │
|
||
│ Zustand store + onChangeAppState + hooks │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Ink 渲染器 (ink/) │
|
||
│ 自定义 React 渲染器 → 终端 ANSI 输出 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 组件层 (components/) │
|
||
│ 346 个 React 组件：消息渲染、权限对话框、导航等 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Hooks 层 (hooks/) │
|
||
│ 104 个自定义 hooks：输入处理、权限、IDE集成、通知等 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 工具函数层 (utils/) │
|
||
│ ~300 个工具文件：git、shell、权限、插件、模型等 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 入口与初始化流程
|
||
|
||
### main.tsx (4,683 行)
|
||
|
||
程序的唯一入口。初始化顺序：
|
||
|
||
```
|
||
1. 启动优化：profileCheckpoint + MDM 子进程 + Keychain 预取 (并行)
|
||
2. 导入权重模块 (~135ms)
|
||
3. 检测调试模式 → 拦截调试器
|
||
4. main() 函数:
|
||
├─ 安全设置 (Windows PATH 安全)
|
||
├─ URL 处理 (cc://, deep link, SSH, assistant)
|
||
├─ 检测 -p/--print (非交互模式) vs 交互模式
|
||
├─ Commander.js 程序定义 (~100 个 CLI 选项)
|
||
├─ preAction hook:
|
||
│ ├─ init() - 配置、认证、特性开关初始化
|
||
│ ├─ 运行迁移 (11 个版本迁移)
|
||
│ ├─ 加载远程管理设置
|
||
│ └─ 加载策略限制
|
||
└─ 主命令 action:
|
||
├─ initializeToolPermissionContext()
|
||
├─ setup() - 工作目录、工作树
|
||
├─ getCommands() + getAgentDefinitions() (并行)
|
||
├─ showSetupScreens() - 信任对话框、OAuth、引导
|
||
├─ MCP 配置加载和连接
|
||
├─ 构建初始 AppState
|
||
└─ 分支:
|
||
├─ --continue → 加载最近对话 → launchRepl()
|
||
├─ --resume <id> → 恢复指定会话 → launchRepl()
|
||
├─ --teleport → 远程恢复 → launchRepl()
|
||
├─ --remote → 远程会话 → launchRepl()
|
||
├─ -p/--print → runHeadless() (非交互)
|
||
└─ 默认 → launchRepl() (新会话)
|
||
```
|
||
|
||
### 初始化优化策略
|
||
|
||
- **并行预取**：MDM 读取、Keychain 读取、API 预连接在导入前并行启动
|
||
- **延迟加载**：OpenTelemetry (~400KB)、gRPC (~700KB) 等通过 `import()` 延迟
|
||
- **Feature Flag 死码消除**：`bun:bundle` 的 `feature()` 在构建时裁剪未启用的功能
|
||
- **Memoize 缓存**：`getCommands()`、`getTools()` 等昂贵操作通过 lodash memoize 缓存
|
||
|
||
### Feature Flags (关键)
|
||
|
||
| Flag | 功能 |
|
||
|------|------|
|
||
| `PROACTIVE` / `KAIROS` | 主动模式 / 助手模式 |
|
||
| `BRIDGE_MODE` | 远程控制 (Remote Control) |
|
||
| `DIRECT_CONNECT` | cc:// URL 直连 |
|
||
| `SSH_REMOTE` | SSH 远程会话 |
|
||
| `COORDINATOR_MODE` | 多 Agent 协调模式 |
|
||
| `TRANSCRIPT_CLASSIFIER` | 自动模式 (auto-mode) |
|
||
| `VOICE_MODE` | 语音输入 |
|
||
| `AGENT_TRIGGERS` | Cron 定时触发 |
|
||
| `WORKFLOW_SCRIPTS` | 工作流脚本 |
|
||
| `TERMINAL_PANEL` | 终端面板捕获 |
|
||
| `WEB_BROWSER_TOOL` | 内嵌浏览器 |
|
||
|
||
---
|
||
|
||
## 3. REPL 交互循环 (REPL.tsx, 5,005 行)
|
||
|
||
核心交互界面。数据流：
|
||
|
||
```
|
||
用户输入 (PromptInput)
|
||
│
|
||
├─ /命令 → processSlashCommand() → 命令处理
|
||
│
|
||
└─ 普通文本 → processUserInput()
|
||
│
|
||
├─ fetchSystemPromptParts() → 系统提示
|
||
├─ loadMemoryPrompt() → 记忆
|
||
├─ buildEffectiveSystemPrompt() → 合成最终系统提示
|
||
│
|
||
└─ query() [QueryEngine.ts, 1,295 行]
|
||
│
|
||
├─ API 调用 (Anthropic SDK, 流式)
|
||
├─ 思考模式 (thinking config)
|
||
├─ Token 预算管理
|
||
│
|
||
└─ 工具调用循环:
|
||
│
|
||
├─ 工具使用块 → 权限检查
|
||
│ ├─ 通过 → 执行工具
|
||
│ └─ 拒绝 → 提示用户批准/拒绝
|
||
│
|
||
└─ 继续 API 调用直到完成
|
||
```
|
||
|
||
### QueryEngine.ts 核心职责
|
||
|
||
1. 构建 API 请求（消息、系统提示、工具定义）
|
||
2. 处理流式响应（thinking、工具使用、文本）
|
||
3. Token 计数和预算管理
|
||
4. 重试逻辑和错误处理
|
||
5. 紧凑/压缩触发
|
||
6. 副本记录 (transcript recording)
|
||
|
||
---
|
||
|
||
## 4. 状态管理
|
||
|
||
### AppStateStore.ts (569 行)
|
||
|
||
使用自定义的 `createStore()` 实现（非 Redux，非 Zustand），类型安全。
|
||
|
||
核心状态字段：
|
||
|
||
```typescript
|
||
AppState {
|
||
// 核心
|
||
verbose: boolean
|
||
mainLoopModel: ModelSetting
|
||
toolPermissionContext: ToolPermissionContext
|
||
isBriefOnly: boolean
|
||
|
||
// MCP
|
||
mcp: { clients, tools, commands, resources }
|
||
|
||
// 插件
|
||
plugins: { enabled, disabled, commands, errors }
|
||
|
||
// 远程控制
|
||
replBridgeEnabled: boolean
|
||
replBridgeConnected: boolean
|
||
|
||
// 任务
|
||
tasks: Record<string, TaskState>
|
||
todos: Record<string, TodoList>
|
||
|
||
// 团队
|
||
teamContext: TeamContext
|
||
|
||
// 通知
|
||
notifications: { current, queue }
|
||
|
||
// 会话
|
||
inbox: { messages }
|
||
speculation: SpeculationState
|
||
attribution: AttributionState
|
||
sessionHooks: Map
|
||
}
|
||
```
|
||
|
||
### onChangeAppState
|
||
|
||
状态变更时触发的副作用集合。`store.setState()` 后会执行 `onChangeAppState` 中注册的所有回调。
|
||
|
||
---
|
||
|
||
## 5. 工具系统 (tools/, 42 个工具)
|
||
|
||
### 工具接口 (Tool.ts, 792 行)
|
||
|
||
每个工具实现 `Tool` 接口：
|
||
|
||
```typescript
|
||
Tool {
|
||
name: string // 工具名称
|
||
description: string // 描述 (用于系统提示)
|
||
inputSchema: JSONSchema // 输入 JSON Schema
|
||
userFacingName(): string // 用户显示名
|
||
isEnabled(): boolean // 是否启用
|
||
needsPermissions(input): boolean // 是否需要权限
|
||
call(input, context): Result // 执行函数
|
||
renderToolUseMessage(input): UI // UI 渲染
|
||
renderToolResultMessage(): UI // 结果渲染
|
||
}
|
||
```
|
||
|
||
### 核心工具分类
|
||
|
||
**文件操作**: FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool
|
||
**执行**: BashTool, PowerShellTool (Windows)
|
||
**AI**: AgentTool (子 Agent), SkillTool (技能执行)
|
||
**外部**: WebFetchTool, WebSearchTool
|
||
**MCP**: MCPTool, ListMcpResourcesTool, ReadMcpResourceTool
|
||
**规划**: EnterPlanModeTool, ExitPlanModeV2Tool
|
||
**任务**: TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskStopTool
|
||
**团队**: TeamCreateTool, TeamDeleteTool, SendMessageTool
|
||
**其他**: TodoWriteTool, BriefTool, AskUserQuestionTool, ConfigTool
|
||
|
||
### 工具执行流程
|
||
|
||
```
|
||
1. QueryEngine 产出 ToolUseBlock
|
||
2. useCanUseTool hook → 权限检查
|
||
3. 工具 handler 执行
|
||
4. 结果 → ToolResultBlock → 回到 QueryEngine
|
||
```
|
||
|
||
### 权限系统
|
||
|
||
`ToolPermissionContext` 定义权限模式：
|
||
- `default` — 每次询问用户
|
||
- `plan` — 只读，编辑需批准
|
||
- `bypassPermissions` — 跳过所有检查（危险）
|
||
- `auto` — 基于分类器自动决策
|
||
|
||
权限规则通过 `PermissionRule` 配置，支持 allow/deny 规则匹配。
|
||
|
||
---
|
||
|
||
## 6. 命令系统 (commands/, 80+ 命令)
|
||
|
||
### 命令类型
|
||
|
||
- **`prompt` 型** — 扩展为文本发送给 LLM（如 `/commit`）
|
||
- **`local` 型** — 本地执行并显示结果（如 `/cost`）
|
||
- **`local-jsx` 型** — 渲染 JSX UI（如 `/config`）
|
||
|
||
### 命令来源
|
||
|
||
1. **内置命令** — `commands.ts` 中的 `COMMANDS()` (memoize)
|
||
2. **技能命令** — `skills/` 目录中的 `.md` 文件
|
||
3. **插件命令** — 插件注册的命令
|
||
4. **Bundled 技能** — `skills/bundled/` 中的内置技能
|
||
5. **MCP 命令** — MCP 服务器提供的 prompt 资源
|
||
|
||
### 加载优先级
|
||
|
||
```
|
||
Bundled Skills → Plugin Skills → Skill Dir → Workflows → Plugin Commands → Built-in
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 服务层 (services/)
|
||
|
||
### 核心服务
|
||
|
||
| 服务 | 职责 |
|
||
|------|------|
|
||
| `api/` | Anthropic API 客户端、使用量跟踪、bootstrap |
|
||
| `mcp/` | MCP 协议：服务器连接、工具发现、认证 |
|
||
| `oauth/` | OAuth 2.0 认证流程 |
|
||
| `lsp/` | LSP 语言服务器管理 |
|
||
| `analytics/` | GrowthBook 特性开关 + 遥测 |
|
||
| `compact/` | 上下文压缩（microcompact、auto-compact） |
|
||
| `plugins/` | 插件安装、加载、版本管理 |
|
||
| `extractMemories/` | 自动记忆提取 |
|
||
| `tokenEstimation.ts` | Token 计数估算 |
|
||
| `teamMemorySync/` | 团队记忆同步 |
|
||
| `tips/` | 提示系统 |
|
||
| `policyLimits/` | 组织策略限制 |
|
||
|
||
---
|
||
|
||
## 8. Bridge / 远程系统 (bridge/, remote/, server/)
|
||
|
||
### Bridge (IDE 集成)
|
||
|
||
双向通信层，连接 VS Code / JetBrains 扩展与 CLI。
|
||
|
||
```
|
||
IDE Extension ←── JSON-RPC ──→ Bridge Manager ←── Session ──→ REPL
|
||
(ws/stdio) (权限桥接)
|
||
```
|
||
|
||
关键组件：
|
||
- `bridgeMain.ts` — 桥接主循环
|
||
- `bridgeMessaging.ts` — 消息协议
|
||
- `bridgePermissionCallbacks.ts` — 权限回调代理
|
||
- `replBridge.ts` — REPL 会话桥接
|
||
- `sessionRunner.ts` — 会话执行管理
|
||
- `trustedDevice.ts` — 可信设备认证
|
||
|
||
### Remote Control
|
||
|
||
用户从 claude.ai/web/mobile 控制本地会话：
|
||
- `bridge/bridgeMain.ts` — 服务器连接
|
||
- `remote/RemoteSessionManager.ts` — 远程会话管理
|
||
- `remote/SessionsWebSocket.ts` — WebSocket 连接
|
||
|
||
### Server 模式
|
||
|
||
独立的 HTTP 服务器模式（`server/`），支持多会话并发。
|
||
|
||
---
|
||
|
||
## 9. Ink 渲染器 (ink/, 96 个文件)
|
||
|
||
**自定义的 React 终端渲染器**，不是直接使用 npm ink 包，而是 fork 并深度定制。
|
||
|
||
核心模块：
|
||
- `reconciler.ts` — React reconciler 实现
|
||
- `renderer.ts` — 终端 ANSI 输出渲染
|
||
- `layout/` — Yoga 布局引擎集成
|
||
- `events/` — 键盘/鼠标/终端事件系统
|
||
- `screen.ts` — 屏幕管理
|
||
- `selection.ts` — 文本选择
|
||
- `searchHighlight.ts` — 搜索高亮
|
||
- `termio/` — 终端 I/O 解析（ANSI/CSI/OSC/SGR）
|
||
|
||
---
|
||
|
||
## 10. 钩子系统 (hooks/)
|
||
|
||
### 工具权限钩子
|
||
|
||
```
|
||
toolPermission/
|
||
├── PermissionContext.ts — 权限上下文
|
||
├── handlers/
|
||
│ ├── interactiveHandler.ts — 交互模式处理器
|
||
│ ├── coordinatorHandler.ts — 协调器模式处理器
|
||
│ └── swarmWorkerHandler.ts — Swarm 工作器处理器
|
||
└── permissionLogging.ts — 权限日志
|
||
```
|
||
|
||
### 通知钩子
|
||
|
||
`hooks/notifs/` — 16 个通知钩子，处理各种状态通知（模型迁移、速率限制、IDE 状态等）。
|
||
|
||
### 关键 hooks
|
||
|
||
| Hook | 职责 |
|
||
|------|------|
|
||
| `useReplBridge.tsx` | 远程控制桥接 |
|
||
| `useCanUseTool.tsx` | 工具权限检查 |
|
||
| `useGlobalKeybindings.tsx` | 全局键盘快捷键 |
|
||
| `useVoice.ts` / `useVoiceIntegration.tsx` | 语音输入 |
|
||
| `useTasksV2.ts` | 任务管理 |
|
||
| `useSwarmInitialization.ts` | Swarm 团队初始化 |
|
||
| `useMergedTools.ts` | 工具池合并 (内置 + MCP) |
|
||
| `useMergedCommands.ts` | 命令池合并 |
|
||
| `useSettings.ts` | 设置管理 |
|
||
|
||
---
|
||
|
||
## 11. 插件系统 (plugins/)
|
||
|
||
### 架构
|
||
|
||
```
|
||
plugins/
|
||
├── builtinPlugins.ts — 内置插件列表
|
||
├── bundled/
|
||
│ └── index.ts — 捆绑插件初始化
|
||
utils/plugins/
|
||
├── pluginLoader.ts — 插件加载器
|
||
├── installedPluginsManager.ts — 已安装插件管理
|
||
├── marketplaceManager.ts — 市场管理
|
||
├── validatePlugin.ts — 插件验证
|
||
├── loadPluginCommands.ts — 加载插件命令
|
||
├── loadPluginHooks.ts — 加载插件钩子
|
||
├── loadPluginAgents.ts — 加载插件 Agent
|
||
└── loadPluginOutputStyles.ts — 加载输出样式
|
||
```
|
||
|
||
插件可以提供：命令、工具、钩子、Agent 定义、输出样式。
|
||
|
||
---
|
||
|
||
## 12. 配置系统
|
||
|
||
### 多层级配置
|
||
|
||
```
|
||
1. 远程管理设置 (enterprise MDM)
|
||
2. 策略设置 (organization policy)
|
||
3. 用户设置 (~/.claude/settings.json)
|
||
4. 项目设置 (.claude/settings.json)
|
||
5. 本地设置 (.claude/settings.local.json)
|
||
6. CLI 标志 (--model, --permission-mode 等)
|
||
7. 环境变量 (ANTHROPIC_API_KEY, CLAUDE_CODE_* 等)
|
||
```
|
||
|
||
### 设置验证
|
||
|
||
`utils/settings/validation.ts` — Zod schema 验证，支持类型检查和错误报告。
|
||
|
||
### 迁移系统
|
||
|
||
`migrations/` — 11 个版本迁移脚本，按序号执行（模型名称迁移、配置迁移等）。
|
||
|
||
---
|
||
|
||
## 13. 记忆系统 (memdir/)
|
||
|
||
```
|
||
memdir/
|
||
├── memdir.ts — 记忆目录操作
|
||
├── paths.ts — 路径解析
|
||
├── memoryScan.ts — 记忆扫描
|
||
├── memoryAge.ts — 记忆年龄管理
|
||
├── memoryTypes.ts — 类型定义
|
||
├── findRelevantMemories.ts — 相关记忆查找
|
||
├── teamMemPaths.ts — 团队记忆路径
|
||
└── teamMemPrompts.ts — 团队记忆提示
|
||
```
|
||
|
||
记忆存储在 `~/.claude/memory/` 目录，自动从对话中提取。
|
||
|
||
---
|
||
|
||
## 14. 性能优化
|
||
|
||
### 启动优化
|
||
|
||
1. **并行子进程**：MDM 读取 + Keychain 预取 + 导入并行 (~135ms)
|
||
2. **延迟加载**：重型模块动态导入（OpenTelemetry, gRPC, print.ts）
|
||
3. **Feature Flag DCE**：未启用的功能在构建时完全裁剪
|
||
4. **Memoize**：`getCommands()`, `getTools()`, `getSkills()` 等结果缓存
|
||
5. **预连接**：API 预连接在用户输入前完成
|
||
|
||
### 运行时优化
|
||
|
||
1. **Token 预算**：上下文压缩触发管理
|
||
2. **文件历史快照**：高效的文件变更追踪
|
||
3. **虚拟滚动**：`VirtualMessageList` 支持大量消息
|
||
4. **流式渲染**：增量 ANSI 输出
|
||
|
||
---
|
||
|
||
## 15. 关键数据流总结
|
||
|
||
```
|
||
用户输入
|
||
│
|
||
├→ /command → processSlashCommand → 命令执行 → 可能触发 query()
|
||
│
|
||
└→ 文本输入 → processUserInput
|
||
│
|
||
├→ processBashCommand (以 ! 开头)
|
||
└→ processTextPrompt
|
||
│
|
||
└→ QueryEngine.query()
|
||
│
|
||
├→ 构建 system prompt (fetchSystemPromptParts + buildEffectiveSystemPrompt)
|
||
├→ 构建 messages (对话历史)
|
||
├→ 构建 tools (getTools + MCP tools)
|
||
│
|
||
├→ API 调用 (Anthropic SDK, streaming)
|
||
│
|
||
└→ 循环处理响应:
|
||
│
|
||
├→ text block → 显示消息
|
||
├→ thinking block → 显示思考过程
|
||
└→ tool_use block → 权限检查 → 执行 → 结果回传 API
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：详细模块文档
|
||
|
||
- [Tools 详细分析](./ARCHITECTURE-TOOLS.md)
|
||
- [Services 详细分析](./ARCHITECTURE-SERVICES.md)
|
||
- [Components 详细分析](./ARCHITECTURE-COMPONENTS.md)
|
||
- [Bridge/Remote 详细分析](./ARCHITECTURE-BRIDGE-REMOTE.md)
|
||
- [Utils 详细分析](./ARCHITECTURE-UTILS.md)
|
||
- [Commands/Skills/Plugins 详细分析](./ARCHITECTURE-COMMANDS.md)
|