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 核心职责

构建 API 请求（消息、系统提示、工具定义）
处理流式响应（thinking、工具使用、文本）
Token 计数和预算管理
重试逻辑和错误处理
紧凑/压缩触发
副本记录 (transcript recording)

4. 状态管理

AppStateStore.ts (569 行)

使用自定义的 createStore() 实现（非 Redux，非 Zustand），类型安全。

核心状态字段：

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 接口：

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）

命令来源

内置命令 — commands.ts 中的 COMMANDS() (memoize)
技能命令 — skills/ 目录中的 .md 文件
插件命令 — 插件注册的命令
Bundled 技能 — skills/bundled/ 中的内置技能
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. 性能优化

启动优化

并行子进程：MDM 读取 + Keychain 预取 + 导入并行 (~135ms)
延迟加载：重型模块动态导入（OpenTelemetry, gRPC, print.ts）
Feature Flag DCE：未启用的功能在构建时完全裁剪
Memoize：getCommands(), getTools(), getSkills() 等结果缓存
预连接：API 预连接在用户输入前完成

运行时优化

Token 预算：上下文压缩触发管理
文件历史快照：高效的文件变更追踪
虚拟滚动：VirtualMessageList 支持大量消息
流式渲染：增量 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

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History