Claude Code 源代码深度架构报告

目录

一、项目概览

二、技术栈

三、目录结构全景

src/
├── main.tsx # 主入口:Commander.js CLI 解析 + React/Ink 渲染初始化
├── QueryEngine.ts # 核心查询引擎(~46K 行)
├── query.ts # 查询管线(query loop 实现)
├── tools.ts # 工具注册表
├── Tool.ts # 工具类型定义(~29K 行)
├── commands.ts # 命令注册表(~25K 行)
│
├── entrypoints/ # 启动入口(cli.tsx 为最外层)
├── tools/ # 工具实现(~40 个)
│ ├── AgentTool/ # 子 Agent 工具
│ ├── BashTool/ # Shell 命令执行
│ ├── FileReadTool/ # 文件读取
│ ├── FileWriteTool/ # 文件创建/覆盖
│ ├── FileEditTool/ # 文件局部编辑
│ ├── GlobTool/ # 文件模式匹配
│ ├── GrepTool/ # ripgrep 内容搜索
│ ├── WebFetchTool/ # URL 内容获取
│ ├── WebSearchTool/ # 网络搜索
│ ├── MCPTool/ # MCP 工具模板
│ ├── NotebookEditTool/ # Jupyter Notebook 编辑
│ ├── AskUserQuestionTool/ # 用户交互问答
│ ├── TodoWriteTool/ # 待办列表管理
│ ├── SkillTool/ # 技能执行
│ ├── SendMessageTool/ # 多 Agent 消息发送
│ ├── ToolSearchTool/ # 延迟工具发现
│ └── ... # 更多工具
│
├── commands/ # 斜杠命令实现(~50 个)
├── components/ # Ink UI 组件(~140 个)
├── screens/ # 全屏 UI(REPL、Doctor、Resume)
├── hooks/ # React Hooks
├── services/ # 服务层
│ ├── api/ # Anthropic API 客户端
│ ├── mcp/ # MCP 连接管理
│ ├── compact/ # 上下文压缩
│ ├── tools/ # 工具执行编排
│ ├── analytics/ # 特性开关与分析
│ ├── lsp/ # LSP 客户端
│ ├── oauth/ # OAuth 认证
│ └── ...
│
├── state/ # 状态管理(自定义 Store)
├── context/ # React Context Providers
├── query/ # 查询管线辅助模块
├── schemas/ # 配置 Schema(Zod)
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
│
├── bridge/ # IDE 桥接(VS Code / JetBrains / claude.ai)
├── coordinator/ # 多 Agent 协调器
├── remote/ # 远程会话(CCR Sessions API)
├── server/ # 直连自建 Session 服务端
├── plugins/ # 插件系统
├── skills/ # 技能系统
├── tasks/ # 任务管理
├── ink/ # 自定义 Ink 渲染器
├── keybindings/ # 快捷键配置
├── vim/ # Vim 模式
├── voice/ # 语音输入
├── memdir/ # 持久化记忆目录
├── migrations/ # 配置迁移
├── buddy/ # 伴侣精灵(彩蛋)
├── outputStyles/ # 输出样式
└── upstreamproxy/ # 代理配置

四、核心架构:Agent 循环

4.1 启动流程

entrypoints/cli.tsx
 │ 最外层入口,处理 --version、MCP、daemon 等快速路径
 │ 默认路径动态 import main.tsx
 ▼
main.tsx (Commander.js)
 │ 创建完整 CLI 程序,解析参数
 │ 并行预取:MDM 设置、Keychain、GrowthBook
 ▼
replLauncher.tsx → App.tsx + REPL.tsx
 │ 启动 Ink 渲染器,展示交互界面
 ▼
用户输入
 │
 ▼
handlePromptSubmit.ts
 │ 校验空输入、解析引用、expandPastedTextRefs
 ▼
processUserInput.ts
 │ 解析斜杠命令 / 处理文本提示 / UserPromptSubmit hooks
 ▼
QueryEngine.submitMessage()
 │ 维护消息数组、构建系统提示
 ▼
query() → queryLoop()
 │ 核心 Agent 循环

4.2 queryLoop — Agent 循环的心脏

┌─────────────────────────────────────────────────────────────┐
│ queryLoop 每轮迭代 │
│ │
│ 1. 上下文裁剪 │
│ ├─ getMessagesAfterCompactBoundary() 从最近压缩边界开始 │
│ ├─ applyToolResultBudget() 大工具结果落盘 │
│ ├─ snipCompactIfNeeded() 历史截断 │
│ ├─ microcompactMessages() 微压缩 │
│ └─ autoCompactIfNeeded() 自动全量压缩 │
│ │
│ 2. 系统提示构建 │
│ └─ appendSystemContext(systemPrompt, systemContext) │
│ │
│ 3. 模型调用(流式) │
│ └─ deps.callModel() → queryModelWithStreaming() │
│ └─ anthropic.beta.messages.create({stream: true}) │
│ │
│ 4. 流式处理 │
│ ├─ 累积 assistantMessages │
│ ├─ 提取 toolUseBlocks │
│ └─ StreamingToolExecutor(可选:边收流边执行工具) │
│ │
│ 5. 分支判断 │
│ ├─ 无 tool_use → 处理错误恢复 / Stop hooks → return │
│ └─ 有 tool_use → 进入工具执行 │
│ │
│ 6. 工具执行 │
│ └─ runTools() / StreamingToolExecutor │
│ ├─ 权限检查 (canUseTool) │
│ ├─ Pre/Post Tool Hooks │
│ └─ tool.call(args, context, ...) │
│ │
│ 7. 组装下一轮消息 │
│ └─ messages = [...现有消息, ...助手消息, ...工具结果] │
│ │
│ 8. 继续 while(true) 下一轮 ──→ 回到步骤 1 │
└─────────────────────────────────────────────────────────────┘

4.3 依赖注入设计

export type QueryDeps = {
 callModel: typeof queryModelWithStreaming // 模型调用
 microcompact: typeof microcompactMessages // 微压缩
 autocompact: typeof autoCompactIfNeeded // 自动压缩
 uuid: () => string // UUID 生成
}

4.4 模型调用层

五、工具系统总体设计

5.1 Tool 接口完整定义

标识与元数据

Schema 字段

MCP 专属字段

延迟加载控制

行为判断方法

isEnabled(): boolean // 工具是否启用
isConcurrencySafe(input): boolean // 是否可并发安全执行
isReadOnly(input): boolean // 是否只读
isDestructive?(input): boolean // 是否不可逆(删除/覆盖/发送)
interruptBehavior?(): 'cancel' | 'block' // 用户新消息时:cancel 取消 / block 阻塞
isSearchOrReadCommand?(input): { isSearch; isRead; isList? } // UI 折叠判断
requiresUserInteraction?(): boolean // 需要用户交互
isTransparentWrapper?(): boolean // 委托渲染给内部工具(如 REPL)

核心执行方法

call(args, context: ToolUseContext, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>
description(input, options): Promise<string> // 面向模型的工具描述
prompt(options): Promise<string> // 面向模型的使用提示
validateInput?(input, context): Promise<ValidationResult> // 自定义输入验证

权限方法

checkPermissions(input, context): Promise<PermissionResult>
preparePermissionMatcher?(input): Promise<(pattern: string) => boolean> // Hook 条件匹配器

渲染方法(11 个)

userFacingName(input): string
renderToolUseMessage(input, options): React.ReactNode
renderToolResultMessage?(content, progressMessages, options): React.ReactNode
renderToolUseProgressMessage?(progressMessages, options): React.ReactNode
renderToolUseTag?(input): React.ReactNode // 标签元数据(超时、模型等)
renderGroupedToolUse?(toolUses, options): React.ReactNode | null // 批量渲染
getToolUseSummary?(input): string | null // 简要摘要
getActivityDescription?(input): string | null // 活动描述
renderToolUseQueuedMessage?(): React.ReactNode
renderToolUseRejectedMessage?(input, options): React.ReactNode
renderToolUseErrorMessage?(result, options): React.ReactNode

其他方法

inputsEquivalent?(a, b): boolean // 判断两个输入是否等价
toAutoClassifierInput(input): unknown // 安全分类器的紧凑输入表示
mapToolResultToToolResultBlockParam(content, toolUseID): ToolResultBlockParam // 转 API 格式
extractSearchText?(out): string // 转录搜索索引
getPath?(input): string // 文件路径相关工具

权限类型定义

// PermissionResult — 工具级权限返回
type PermissionResult<Input> =
 | { behavior: 'allow'; updatedInput?: Input }
 | { behavior: 'deny'; message: string; decisionReason: PermissionDecisionReason }
 | { behavior: 'ask'; message: string; suggestions?: PermissionUpdate[] }
 | { behavior: 'passthrough'; message: string } // 交给通用权限系统
// PermissionDecisionReason — 10 种决策原因
type PermissionDecisionReason =
 | 'rule' | 'mode' | 'subcommandResults' | 'permissionPromptTool'
 | 'hook' | 'asyncAgent' | 'sandboxOverride' | 'classifier'
 | 'workingDir' | 'safetyCheck' | 'other'
// PermissionMode — 7 种权限模式
type PermissionMode =
 | 'acceptEdits' | 'bypassPermissions' | 'default'
 | 'dontAsk' | 'plan' | 'auto' | 'bubble'

5.2 buildTool 工厂函数

const TOOL_DEFAULTS = {
 isEnabled: () => true, // 默认启用
 isConcurrencySafe: (_input?) => false, // 假设不安全(保守)
 isReadOnly: (_input?) => false, // 假设会写(保守)
 isDestructive: (_input?) => false, // 默认非破坏性
 checkPermissions: (input) => // 交给通用权限系统
 Promise.resolve({ behavior: 'allow', updatedInput: input }),
 toAutoClassifierInput: (_input?) => '', // 跳过分类器
 userFacingName: () => '', // 用 def.name 覆盖
}
function buildTool(def: ToolDef): Tool {
 return {
 ...TOOL_DEFAULTS,
 userFacingName: () => def.name,
 ...def, // 调用方的定义覆盖默认值
 }
}

5.3 ToolUseContext — 工具执行上下文

5.4 工具注册与合并

getAllBaseTools() ← 收集所有工具(按 feature flag 条件加载)
 │
 ▼
getTools(permissionContext) ← 过滤:deny 规则 → REPL 隐藏 → isEnabled
 │
 ▼
assembleToolPool(perms, mcp) ← 内置 + MCP 合并,内置优先,按名排序保 prompt cache

5.5 工具生命周期

1. 定义阶段
 ToolDef (可省略默认方法) → buildTool() → Tool (完整接口)
2. 注册阶段
 getAllBaseTools() — 收集所有工具(条件加载)
3. 过滤阶段
 getTools(permissionContext)
 → filterToolsByDenyRules() 移除被拒绝的工具
 → REPL 过滤 隐藏 REPL_ONLY_TOOLS
 → isEnabled() 过滤 移除禁用工具
4. 合并阶段
 assembleToolPool(permissionContext, mcpTools)
 → 内置 + MCP 工具按名去重合并
5. 延迟加载(可选)
 shouldDefer=true 的工具以 defer_loading:true 发送给 API
 模型通过 ToolSearchTool 按 searchHint 发现并加载
6. 执行阶段
 tool.validateInput(input, context)
 tool.checkPermissions(input, context)
 通用权限系统 + hooks + 分类器
 tool.call(args, context, canUseTool, parentMessage, onProgress)
 → 返回 ToolResult<Output>
7. 结果处理
 tool.mapToolResultToToolResultBlockParam() → 转 API 格式
 tool.renderToolResultMessage() → UI 渲染

六、工具执行管线

6.1 编排层 — 并发与串行调度

6.2 单个工具执行生命周期

┌──────────────────────────────────────────────────────────┐
│ 1. 工具查找 │
│ 在可见工具集查找 → 回退到全量列表(处理废弃别名) │
│ 找不到 → 返回 <tool_use_error> │
│ │
│ 2. 中止检查 │
│ abortController.signal.aborted → 返回取消消息 │
│ │
│ 3. 两阶段输入验证 │
│ Phase 1: Zod schema 验证 │
│ 失败 → formatZodValidationError │
│ 延迟加载工具 schema 未发送 → 提示调 ToolSearch │
│ Phase 2: tool.validateInput() │
│ 自定义逻辑(如"必须先读再写") │
│ │
│ 4. 输入预处理 │
│ 剥离内部注入字段 → backfillObservableInput │
│ │
│ 5. PreToolUse 钩子 │
│ 可能:修改输入 / 做权限决策 / 停止执行 │
│ 类型:message / hookPermissionResult / │
│ hookUpdatedInput / preventContinuation / │
│ additionalContext / stop │
│ │
│ 6. 权限检查 (resolveHookPermissionDecision) │
│ ┌─ hook allow + deny 规则 → deny 覆盖 │
│ ├─ hook allow + ask 规则 → 仍需用户交互 │
│ ├─ hook deny → 直接拒绝 │
│ └─ 无 hook → canUseTool 正常流程 │
│ 安全不变式:hook 的 allow 不能绕过 deny/ask 规则 │
│ │
│ 7. 实际执行 │
│ tool.call(callInput, context, canUseTool, │
│ assistantMessage, onProgress) │
│ │
│ 8. PostToolUse 钩子 │
│ MCP 工具:先跑 hook(可能修改输出),再 addToolResult │
│ 非 MCP:先 addToolResult,再跑 hook │
│ │
│ 9. 结果格式化 │
│ tool.mapToolResultToToolResultBlockParam() │
│ → ToolResultBlockParam → createUserMessage │
│ 附加 acceptFeedback / contentBlocks │
│ │
│ 10. 错误路径 │
│ → PostToolUseFailure 钩子 → formatError │
│ → MCP 认证错误 → 更新客户端状态为 needs-auth │
└──────────────────────────────────────────────────────────┘

6.3 流式工具执行

6.4 错误处理

七、所有工具详细设计

7.1 文件操作工具

FileReadTool — Read

FileWriteTool — Write

FileEditTool — Edit

NotebookEditTool — NotebookEdit

7.2 搜索工具

GlobTool — Glob

GrepTool — Grep

ToolSearchTool — ToolSearch

7.3 系统操作工具

BashTool — Bash

7.4 网络工具

WebFetchTool — WebFetch

WebSearchTool — WebSearch

7.5 Agent 与任务工具

AgentTool — Task (alias: Agent)

TaskOutputTool — TaskOutput

TaskStopTool — TaskStop (alias: KillShell)

TodoWriteTool — TodoWrite

Task v2 工具(与 TodoWriteTool 互斥)

SkillTool — Skill

7.6 协作工具

SendMessageTool — SendMessage

TeamCreateTool — TeamCreate

TeamDeleteTool — TeamDelete

AskUserQuestionTool — AskUserQuestion

BriefTool — SendUserMessage (alias: Brief)

7.7 模式切换工具

EnterPlanModeTool — EnterPlanMode

ExitPlanModeV2Tool — ExitPlanMode

EnterWorktreeTool — EnterWorktree

ExitWorktreeTool — ExitWorktree

7.8 MCP 工具

MCPTool — 模板工具

McpAuthTool — MCP 认证占位

ListMcpResourcesTool

ReadMcpResourceTool

7.9 特殊功能工具

SyntheticOutputTool — StructuredOutput

CronCreateTool / CronDeleteTool / CronListTool

RemoteTriggerTool — RemoteTrigger

LSPTool — LSP

7.10 Feature-gated 工具

工具分类常量(constants/tools.ts)

八、权限系统

权限检查流程

工具调用请求
 │
 ▼
hasPermissionsToUseTool() ← utils/permissions/permissions.ts
 │
 ├─ allow → 直接执行
 ├─ deny → 拒绝并返回错误
 └─ ask → 交互式确认
 ├─ coordinator handler
 ├─ interactive handler(终端提示)
 └─ swarm worker handler

权限模式

权限规则

ToolPermissionContext = {
 mode: PermissionMode
 alwaysAllowRules: ToolPermissionRulesBySource // 始终允许的规则
 alwaysDenyRules: ToolPermissionRulesBySource // 始终拒绝的规则
 alwaysAskRules: ToolPermissionRulesBySource // 始终询问的规则
 shouldAvoidPermissionPrompts?: boolean // 后台 Agent 自动拒绝
 awaitAutomatedChecksBeforeDialog?: boolean // 协调器等待自动检查
 prePlanMode?: PermissionMode // 进入 plan 模式前的模式
}

九、Hook 系统

Hook 事件类型

Hook 执行器类型

Hook 配置

HooksSchema = Partial<Record<HookEvent, HookMatcher[]>>
HookMatcher = {
 if?: string // 条件表达式(如工具名匹配)
 command?: string // shell 命令
 prompt?: string // 提示文本
 http?: HttpConfig // HTTP 配置
 agent?: AgentConfig // Agent 配置
}

十、上下文管理与压缩策略

压缩层级(从轻到重)

Level 0: Tool Result Budget(工具结果预算)
 │ 超大工具结果落盘,替换为预览摘要
 │ 由 maxResultSizeChars 和 PERSISTED_OUTPUT_TAG 控制
 ▼
Level 1: Microcompact(微压缩)
 │ 超时的旧 tool_result 内容清空为 [Old tool result content cleared]
 │ 保留最近 N 个,重置 microcompact 状态
 │ 支持 Cached Microcompact(登记 cache_edits,不本地改消息)
 ▼
Level 2: History Snip(历史截断)
 │ snipCompactIfNeeded — 截断较旧的历史消息
 ▼
Level 3: Context Collapse(上下文折叠)
 │ 细粒度折叠特定区段
 │ 在 autocompact 之前投影/提交 collapse
 ▼
Level 4: Auto Compact(自动全量压缩)
 │ trySessionMemoryCompaction → compactConversation
 │ 调模型生成摘要,替换全部历史

自动压缩触发条件

有效窗口 = 模型上下文窗口 - min(MAX_OUTPUT_TOKENS, MAX_OUTPUT_TOKENS_FOR_SUMMARY=20000)
 可被 CLAUDE_CODE_AUTO_COMPACT_WINDOW 进一步限制
触发阈值 = 有效窗口 - AUTOCOMPACT_BUFFER_TOKENS(13000)
 可被 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 百分比覆盖
当 tokenCountWithEstimation(messages) - snipTokensFreed > 触发阈值
 → 先尝试 trySessionMemoryCompaction
 → 失败再走 compactConversation
 → 连续失败 ≥3 次有 circuit breaker

全量压缩流程

boundary → summaryMessages → messagesToKeep → attachments → hookResults

Token 计数

十一、子 Agent 系统

AgentTool — 子 Agent 入口

runAgent — 子 Agent 运行时

多 Agent 协调

十二、UI 与渲染层

自定义 Ink 渲染器

Markdown 渲染

主要屏幕

十三、状态管理

架构

// state/store.ts — 极简 store
createStore(initialState) → { getState, setState, subscribe }
// setState 使用 Object.is 短路
// state/AppState.tsx — Provider
AppStateProvider → AppStoreContext → useSyncExternalStore(store.subscribe, selector)
// useAppState(selector) 按选择器切片更新
// useSetAppState() 只拿 setState
// 禁止嵌套 Provider

AppState 核心字段

副作用枢纽

十四、服务层

十五、远程与桥接

Bridge(桥接)

Remote(远程会话)

Server(直连服务端)

十六、扩展机制

MCP 集成

插件系统

技能系统 (Skills)

斜杠命令

十七、性能优化设计

启动优化 — 并行预取

// main.tsx — 在其他 import 之前作为副作用并行启动
startMdmRawRead() // MDM 设置预读
startKeychainPrefetch() // Keychain 预取
// API preconnect、GrowthBook 初始化同样并行

延迟加载

编译期特性消除

import { feature } from 'bun:bundle'
const voiceCommand = feature('VOICE_MODE')
 ? require('./commands/voice/index.js').default
 : null
// 未启用的代码在构建时完全剥离(dead code elimination)

流式工具执行

Prompt Cache 稳定性

十八、设计模式总结

1. buildTool 工厂模式

2. 读后写保护

3. 延迟加载(Tool Search)

4. 权限三层架构

5. 并发安全标记

6. 大输出持久化

7. 进度报告

8. 流式执行

9. 多级压缩

10. 统一 Agent 架构

附录:端到端消息流

用户输入
 │
 ▼
REPL.onSubmit() → handlePromptSubmit() → processUserInput()
 │ 解析斜杠命令 / 文本提示 / UserPromptSubmit hooks
 ▼
QueryEngine.submitMessage()
 │ 拼装 systemPrompt、userContext、systemContext
 ▼
query() → queryLoop() [while(true)]
 │
 ├─ 上下文裁剪(5 级压缩)
 ├─ appendSystemContext()
 │
 ├─ queryModelWithStreaming()
 │ └─ anthropic.beta.messages.create({stream: true})
 │
 ├─ 流式处理 + StreamingToolExecutor
 │
 ├─ 无 tool_use → Stop hooks → return
 │
 └─ 有 tool_use
 │
 ├─ partitionToolCalls()(并发 / 串行分区)
 │
 └─ runToolUse() ×ばつ N
 ├─ validateInput(Zod + 自定义)
 ├─ PreToolUse hooks
 ├─ resolveHookPermissionDecision
 │ └─ hook allow 不能绕过 deny/ask 规则
 ├─ tool.call()
 ├─ PostToolUse hooks(MCP 可修改输出)
 └─ createUserMessage(tool_result)
 │
 └─ 合并到 messages → 继续 while(true) 下一轮