Claude Code 源码深度解析：五层架构与核心设计模式

// src/tools.ts（节选）
import { feature } from 'bun:bundle'

const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null

const cronTools = feature('AGENT_TRIGGERS')
  ? [
      require('./tools/ScheduleCronTool/CronCreateTool.js').CronCreateTool,
      // ...
    ]
  : []

src/
├── main.tsx                  # CLI 入口（4,683 行）
├── QueryEngine.ts            # LLM 会话引擎（1,295 行）
├── query.ts                  # Agent Loop（1,729 行）
├── Tool.ts                   # Tool 类型定义（792 行）
├── tools.ts                  # 工具注册与池化（390 行）
├── commands.ts               # 命令注册与分发（754 行）
│
├── tools/          (184 文件, 3.2MB)   # 40+ 工具实现
├── commands/       (189 文件, 3.3MB)   # 50+ 斜杠命令
├── components/     (389 文件, 11MB)    # React/Ink UI 组件
├── utils/          (564 文件, 7.8MB)   # 工具函数、配置、权限
├── services/       (130 文件, 2.2MB)   # MCP、LSP、OAuth、Compact
├── hooks/          (104 文件, 1.5MB)   # React hooks
├── bridge/                             # IDE 桥接层（VS Code/JetBrains）
├── screens/                            # 全屏 UI（REPL、Doctor、Resume）
├── skills/                             # Skill 系统
├── tasks/                              # Task 管理 UI 层
├── coordinator/                        # 多 Agent 协调（369 行）
├── ink/                                # Ink 渲染器封装
├── cli/                                # CLI 工具函数
├── keybindings/                        # 快捷键配置（含 Vim 模式）
└── ...

// 并行预取（~40ms vs 串行 135ms+）
const mdmPrefetch    = startMdmRawRead()          // MDM 企业策略
const keychainPrefetch = startKeychainPrefetch()  // OAuth / API Key
// GrowthBook feature flags 也在此时异步拉取

main.tsx 入口
  ├─ profileCheckpoint('main_tsx_entry')   ← 启动计时打点
  ├─ 并行预取（MDM、Keychain、GrowthBook）
  ├─ Commander.js 解析 CLI 参数
  ├─ 按命令类型分发：
  │   ├─ 普通交互：React/Ink REPL 渲染
  │   ├─ --resume：恢复上次会话
  │   ├─ --bridge：IDE 桥接模式
  │   └─ 子命令：/mcp、/config、/doctor 等
  └─ Bootstrap：加载 MCP 配置、权限规则、OAuth 状态

用户输入
   ↓
[调用 LLM，流式获取响应]
   ↓
响应中有 tool_use？
   ├─ 是 → 执行工具 → 将结果追加到对话 → 回到"调用 LLM"
   └─ 否 → 结束，将最终文本响应展示给用户

// QueryEngine.ts:209
async *submitMessage(
  prompt: string | ContentBlockParam[],
  options?: { uuid?: string; isMeta?: boolean },
): AsyncGenerator<SDKMessage, void, unknown> {
  // 包装 canUseTool，追踪权限拒绝记录
  const wrappedCanUseTool: CanUseToolFn = async (...) => {
    const result = await canUseTool(...)
    if (result.behavior === 'deny') {
      this.permissionDenials.push(...)  // 记录拒绝历史
    }
    return result
  }
  // 进入 query() → queryLoop()
  yield* query({ messages, tools, canUseTool: wrappedCanUseTool, ... })
}

// query.ts:241
async function* queryLoop(
  params: QueryParams,
  consumedCommandUuids: string[],
): AsyncGenerator<StreamEvent | Message | ..., Terminal>

let state: State = {
  messages,                     // 完整对话历史
  toolUseContext,               // 工具上下文（工具列表、权限回调、agent ID 等）
  maxOutputTokensOverride,      // 恢复场景的 token 覆盖值
  autoCompactTracking,          // 自动压缩跟踪
  stopHookActive,               // stop hook 激活状态
  maxOutputTokensRecoveryCount, // 恢复重试计数
  hasAttemptedReactiveCompact,  // 是否已尝试响应式压缩
  turnCount,                    // 当前第几轮（从 1 开始）
  transition,                   // 本次迭代的来源描述
}

while (true) {
  // 1. 解构当前状态（只读）
  const { messages, toolUseContext, turnCount, ... } = state

  // 2. 预取：skill discovery（后台并发，不阻塞）
  const pendingSkillPrefetch = skillPrefetch?.startSkillDiscoveryPrefetch(...)

  yield { type: 'stream_request_start' }

  // 3. 只取 compact 边界之后的消息（节省 token）
  let messagesForQuery = [...getMessagesAfterCompactBoundary(messages)]

  // 4. 调用 LLM API（流式）
  const streamingToolExecutor = new StreamingToolExecutor(tools, canUseTool, toolUseContext)
  for await (const event of deps.callModel({ model, systemPrompt, messages: messagesForQuery, tools, ... })) {
    yield event  // 流式输出给 UI
    if (event.type === 'content_block_start' && event.content_block.type === 'tool_use') {
      streamingToolExecutor.addTool(event.content_block, assistantMessage)
    }
  }

  // 5. 等待所有工具执行完成，收集结果
  for await (const update of streamingToolExecutor.getRemainingResults()) {
    yield update.message
    toolUseContext = update.newContext
  }

  // 6. 判断退出 or 继续
  if (toolUseBlocks.length === 0) {
    return { type: 'no_tool_use' }  // 模型不再调用工具，结束
  }
  if (turnCount >= maxTurns) {
    return { type: 'max_turns' }    // 达到轮次上限，结束
  }

  // 7. 将工具结果追加到消息，进入下一轮
  state = { ...state, messages: [...messages, ...toolResultMessages], turnCount: turnCount + 1 }
}

type Tool<Input, Output, P> = {
  name: string
  aliases?: string[]               // 向后兼容别名

  // 核心执行函数
  call(
    args: Input,
    context: ToolUseContext,
    canUseTool: CanUseToolFn,
    parentMessage: AssistantMessage,
    onProgress: ProgressCallback,
  ): Promise<ToolResult<Output>>

  description(input: Input, options: DescriptionOptions): string
  inputSchema: ZodType<Input>      // 输入校验 schema

  isConcurrencySafe(input: Input): boolean  // 是否可与其他工具并发
  isReadOnly(input: Input): boolean          // 是否只读操作
  isDestructive?(input: Input): boolean      // 是否不可逆
  interruptBehavior?(): 'cancel' | 'block'   // 用户中断时的行为
  maxResultSizeChars: number                 // 结果大小上限
}

type ToolResult<T> = {
  data: T
  newMessages?: Message[]                             // 可附加额外消息
  contextModifier?: (ctx: ToolUseContext) => ToolUseContext  // 可修改上下文
}

runToolUse(block)
  ├─ 1. Zod schema 校验输入参数
  ├─ 2. tool.validateInput()（工具自定义校验，可选）
  ├─ 3. runPreToolUseHooks()     ← 前置 hooks
  ├─ 4. canUseTool() 权限决策
  │       ├─ deny 规则匹配 → 拒绝（记入 permissionDenials）
  │       ├─ ask 规则匹配  → 弹出用户确认对话框（阻塞）
  │       └─ allow         → 通过
  ├─ 5. tool.call(input, context, ...)  ← 实际执行
  ├─ 6. runPostToolUseHooks()    ← 后置 hooks
  └─ 7. 格式化为 tool_result 消息块，返回给 LLM

export class StreamingToolExecutor {
  private tools: TrackedTool[] = []   // 工具执行队列
  private toolUseContext: ToolUseContext
  private hasErrored = false
  private siblingAbortController: AbortController  // 兄弟工具出错时中止其他工具

  // 每个被追踪的工具状态
  // 'queued' → 'executing' → 'completed' → 'yielded'
}

type TrackedTool = {
  id: string
  block: ToolUseBlock
  status: ToolStatus
  isConcurrencySafe: boolean
  promise?: Promise<void>           // 执行 Promise
  results?: Message[]               // 执行结果（缓存）
  pendingProgress: Message[]        // 进度消息（立即推送）
  contextModifiers?: Array<(ctx: ToolUseContext) => ToolUseContext>
}

// StreamingToolExecutor.ts:76
addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {
  const isConcurrencySafe = toolDefinition.isConcurrencySafe(parsedInput)
  this.tools.push({ id, block, status: 'queued', isConcurrencySafe, ... })
  void this.processQueue()  // 立即尝试调度
}

// 并发条件判断（:129）
private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  )
}

type ThinkingConfig =
  | { type: 'adaptive' }                      // 自适应（模型自行决定是否思考）
  | { type: 'enabled'; budgetTokens: number } // 显式启用，指定思考 token 上限
  | { type: 'disabled' }                      // 关闭

// thinking.ts:29
export function hasUltrathinkKeyword(text: string): boolean {
  return /\bultrathink\b/i.test(text)
}

type Task = {
  id: string
  subject: string                           // 简短标题
  description: string                       // 详细描述
  activeForm?: string                       // 当前进行中的操作，如 "Running tests"
  owner?: string                            // 持有该任务的 agent ID
  status: 'pending' | 'in_progress' | 'completed'
  blocks: string[]                          // 本任务完成后才能开始的任务
  blockedBy: string[]                       // 必须先完成才能开始本任务的任务
  metadata?: Record<string, unknown>
}

// tasks.ts:541
async function claimTask(taskId, agentId, taskListId) {
  await lock(taskFilePath)
  try {
    const task = await readTask(taskId)
    if (task.owner && task.owner !== agentId) {
      return { success: false, reason: 'already_claimed' }
    }
    await writeTask({ ...task, owner: agentId, status: 'in_progress' })
    return { success: true }
  } finally {
    await unlock(taskFilePath)
  }
}

const COMPACT_MAX_OUTPUT_TOKENS = 20_000    // 摘要最大输出 token
const POST_COMPACT_TOKEN_BUDGET = 50_000    // 压缩后可用 token 预算

type Command = {
  type: 'prompt' | 'local'       // prompt = LLM 驱动；local = 本地函数
  name: string
  description: string
  whenToUse: string
  source: 'bundled' | 'skills' | 'commands' | 'plugin' | 'managed' | 'mcp'
  context: 'inline' | 'fork'    // 执行模式
  allowedTools: string[]         // 可用工具白名单
  model?: string                 // 可指定模型覆盖
  agent?: string                 // 可指定 agent 类型
}

PreToolUse / PostToolUse / PostToolUseFailure
SessionStart / SessionEnd / Setup / Stop / StopFailure
SubagentStart / SubagentStop
TaskCreated / TaskCompleted
PreCompact / PostCompact
UserPromptSubmit
PermissionDenied / PermissionRequest
InstructionsLoaded / CwdChanged / FileChanged
TeammateIdle