Claude Code 源码解析Claude Code 源码解析Claude Code 源码解析

// 从源码提取的核心配置
总代码行数: 512,000+
源文件数量: 1,900+
命令数量: 101
工具数量: 52
npm 包名: @anthropic-ai/claude-code

┌─────────────────────────────────────────────────────────────────┐
│                        用户输入层                                │
│  (Terminal / SDK / Cowork / Desktop / Mobile)                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      命令解析层                                  │
│  src/commands/ (101 个子目录)                                   │
│  - /add-dir, /compact, /doctor, /resume, /status, ...          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     QueryEngine                                 │
│  src/QueryEngine.ts (核心会话引擎)                              │
│  - 管理对话状态与归因                                           │
│  - 处理消息持久化                                               │
│  - 控制压缩与边界                                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       query.ts                                  │
│  src/query.ts (流式对话循环, 1700+ 行)                          │
│  - 流式 API 调用                                                │
│  - 工具执行编排                                                 │
│  - 自动压缩触发                                                 │
│  - Token 预算控制                                               │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│   权限系统       │ │   工具系统       │ │   服务层         │
│ permissions/     │ │ tools/ (52个)    │ │ services/        │
│ - plan/auto/man  │ │ - BashTool       │ │ - api/           │
│ - YOLO Classifier│ │ - FileEditTool   │ │ - mcp/           │
│ - 路径验证       │ │ - AgentTool      │ │ - autoDream/     │
│                  │ │ - WebFetchTool   │ │ - compact/       │
└──────────────────┘ └──────────────────┘ └──────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    多模型 API 层                                 │
│  - Anthropic Direct (API Key + OAuth)                          │
│  - AWS Bedrock (凭据刷新, Bearer Token)                        │
│  - Google Vertex (GCP 凭据)                                    │
│  - Azure Foundry (API Key + Azure AD)                          │
└─────────────────────────────────────────────────────────────────┘

export class QueryEngine {
  private config: QueryEngineConfig
  private mutableMessages: Message[]
  private abortController: AbortController
  private permissionDenials: SDKPermissionDenial[]
  private totalUsage: NonNullableUsage
  private hasHandledOrphanedPermission = false
  private readFileState: FileStateCache
  
  // 核心方法：提交消息并处理流式响应
  async *submitMessage(
    prompt: string | ContentBlockParam[],
    options?: { uuid?: string; isMeta?: boolean },
  ): AsyncGenerator<SDKMessage, void, unknown> {
    // 1. 构建系统提示词
    const systemPrompt = asSystemPrompt([
      ...defaultSystemPrompt,
      ...memoryMechanicsPrompt,
      ...appendSystemPrompt,
    ])
    
    // 2. 处理用户输入
    const { messages, shouldQuery, allowedTools } = await processUserInput(...)
    
    // 3. 持久化用户消息（支持 resume）
    await recordTranscript(messages)
    
    // 4. 进入 query 循环
    for await (const message of query({
      messages,
      systemPrompt,
      canUseTool: wrappedCanUseTool,
      ...
    })) {
      yield message
    }
  }
}

async function* queryLoop(params: QueryParams) {
  let state: State = {
    messages: params.messages,
    toolUseContext: params.toolUseContext,
    autoCompactTracking: undefined,
    maxOutputTokensRecoveryCount: 0,
    ...
  }
  
  while (true) {
    // 1. 应用压缩策略（snip → microcompact → autocompact）
    messagesForQuery = await applyCompactionStrategies(messagesForQuery)
    
    // 2. 调用模型 API
    for await (const message of deps.callModel({
      messages: messagesForQuery,
      systemPrompt: fullSystemPrompt,
      tools: toolUseContext.options.tools,
      ...
    })) {
      yield message
      
      if (message.type === 'assistant') {
        // 收集 tool_use 块
        toolUseBlocks.push(...extractToolUseBlocks(message))
        needsFollowUp = true
      }
    }
    
    // 3. 执行工具调用
    if (needsFollowUp) {
      const toolResults = await executeTools(toolUseBlocks, ...)
      state.messages.push(...assistantMessages, ...toolResults)
      continue  // 递归继续对话
    }
    
    // 4. 检查停止条件
    if (!needsFollowUp) {
      // 处理 max_output_tokens 恢复
      // 处理 prompt-too-long 恢复
      // 执行 stop hooks
      return { reason: 'completed' }
    }
  }
}

// src/tools.ts
export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    // 嵌入式搜索工具检测
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    NotebookEditTool,
    WebFetchTool,
    TodoWriteTool,
    WebSearchTool,
    TaskStopTool,
    AskUserQuestionTool,
    SkillTool,
    EnterPlanModeTool,
    // Ant-only 工具
    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool, TungstenTool] : []),
    // Feature-gated 工具
    ...(SleepTool ? [SleepTool] : []),
    ...cronTools,
    ...(WorkflowTool ? [WorkflowTool] : []),
    ...(isAgentSwarmsEnabled() ? [TeamCreateTool, TeamDeleteTool] : []),
    ...
  ]
}

// 按权限过滤
export function getTools(permissionContext: ToolPermissionContext): Tools {
  const tools = getAllBaseTools()
  return filterToolsByDenyRules(tools, permissionContext)
    .filter(tool => tool.isEnabled())
}

/add-dir        /advisor        /agents         /ant-trace
/assistant      /autofix-pr     /backfill       /branch
/break-cache    /bridge         /brief          /btw
/buddy          /bughunter      /chrome         /clear
/color          /commit         /compact        /config
/context        /copy           /cost           /desktop
/diff           /doctor         /effort         /env
/exit           /export         /fast           /feedback
/files          /fork           /good-claude    /heapdump
/help           /hooks          /ide            /init
/insights       /install        /issue          /keybindings
/login          /logout         /mcp            /memory
/mobile         /model          /oauth-refresh  /onboarding
/output-style   /passes         /peers          /perf-issue
/permissions    /plan           /plugin         /pr-comments
/privacy        /rate-limit     /release-notes  /reload-plugins
/remote-env     /remote-setup   /rename         /reset-limits
/resume         /review         /rewind         /sandbox-toggle
/security       /session        /share          /skills
/stats          /status         /stickers       /summary
/tag            /tasks          /teleport       /terminalSetup
/theme          /thinkback       /ultraplan      /upgrade
/usage          /version        /vim            /voice
/workflows

// 使用 String.fromCharCode 混淆绕过关键词检测
const c = String.fromCharCode
export const duck = c(0x64,0x75,0x63,0x6b) as 'duck'
export const goose = c(0x67,0x6f,0x6f,0x73,0x65) as 'goose'
export const dragon = c(0x64,0x72,0x61,0x67,0x6f,0x6e) as 'dragon'
export const cat = c(0x63,0x61,0x74) as 'cat'
export const axolotl = c(0x61,0x78,0x6f,0x6c,0x6f,0x74,0x6c) as 'axolotl'
export const capybara = c(0x63,0x61,0x70,0x79,0x62,0x61,0x72,0x61) as 'capybara'
// ... 共 18 种
export const SPECIES = [
  duck, goose, blob, cat, dragon, octopus, owl, penguin,
  turtle, snail, ghost, axolotl, capybara, cactus, robot,
  rabbit, mushroom, chonk
] as const

export const RARITY_WEIGHTS = {
  common: 60,      // 60%
  uncommon: 25,    // 25%
  rare: 10,        // 10%
  epic: 4,         // 4%
  legendary: 1     // 1%
} as const

export const STAT_NAMES = [
  'DEBUGGING',   // 调试能力
  'PATIENCE',    // 耐心程度
  'CHAOS',       // 混沌倾向
  'WISDOM',      // 智慧等级
  'SNARK'        // 讽刺指数
] as const

// companion.ts
function mulberry32(seed: number): () => number {
  let a = seed >>> 0
  return function () {
    a |= 0
    a = (a + 0x6d2b79f5) | 0
    let t = Math.imul(a ^ (a >>> 15), 1 | a)
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
  }
}

const SALT = 'friend-2026-401'

export function roll(userId: string): Roll {
  const key = userId + SALT
  const value = rollFrom(mulberry32(hashString(key)))
  return value
}

// 1. 时间门：距上次做梦 > 24 小时
const hoursSince = (Date.now() - lastAt) / 3_600_000
if (hoursSince < cfg.minHours) return

// 2. 会话门：新会话数 >= 5
const sessionsTouched = await listSessionsTouchedSince(lastAt)
if (sessionsTouched.length < cfg.minSessions) return

// 3. 锁门：获取 consolidation 锁
if (!await tryAcquireConsolidationLock()) return

Research      → 并行启动多个 Worker 调研不同模块
Synthesis     → Coordinator 汇总 Worker 结果，生成执行方案
Implementation → Worker 并行执行代码修改
Verification  → Worker 独立验证修改结果

// coordinatorMode.ts
const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
    .filter(name => !INTERNAL_WORKER_TOOLS.has(name))

┌─────────────────────────────────────────────────────┐
│  Layer 1: feature() - 编译时 Gate                   │
│  - Bun bundle tree-shaking                          │
│  - 代码路径完全消除                                  │
│  - 适用于字符串敏感的功能                            │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Layer 2: Statsig Feature Gate - 运行时 Gate        │
│  - checkStatsigFeatureGate()                        │
│  - Growthbook A/B 测试集成                          │
│  - 用户级灰度发布                                    │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│  Layer 3: Beta Headers - API 级 Gate                │
│  - HTTP headers 传递给 Anthropic API                │
│  - 服务端功能启用                                    │
│  - 1M context / task-budgets 等                     │
└─────────────────────────────────────────────────────┘

// query.ts 核心流式循环
for await (const message of deps.callModel({
  messages: messagesForQuery,
  systemPrompt: fullSystemPrompt,
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: {
    model: currentModel,
    fastMode: appState.fastMode,
    mcpTools: appState.mcp.tools,
    taskBudget: { total, remaining },
    ...
  }
})) {
  yield message
  
  if (message.type === 'assistant') {
    // 收集 tool_use 块
    // 流式执行工具（StreamingToolExecutor）
  }
}

// QueryEngine.submitMessage 是 AsyncGenerator
async *submitMessage(prompt): AsyncGenerator<SDKMessage> {
  for await (const message of query(...)) {
    yield message
  }
}

type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number
  transition: Continue | undefined  // 上次迭代原因
}

// Continue 站点统一更新
state = {
  messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
  transition: { reason: 'next_turn' },
  ...
}

export type QueryDeps = {
  callModel: (params) => AsyncGenerator<Message>
  autocompact: (messages, ...) => Promise<CompactionResult>
  microcompact: (messages, ...) => Promise<MicrocompactResult>
  uuid: () => string
}

// 默认使用 productionDeps
const deps = params.deps ?? productionDeps()

// 条件导入，不满足条件时代码完全消除
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null

// 使用时检查 null
...(SleepTool ? [SleepTool] : [])

// 从 API 调用到工具执行，全链路 AsyncGenerator
async *submitMessage(): AsyncGenerator<SDKMessage> {
  for await (const message of query(...)) {
    yield message  // 流式返回，不阻塞
  }
}

type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  transition: Continue | undefined  // 记录上次迭代原因
}

// Continue 站点统一更新
state = { 
  messages, 
  transition: { reason: 'next_turn' } 
}

// 同一用户，永远同一只宠物
const key = userId + 'friend-2026-401'
return rollFrom(mulberry32(hashString(key)))

编译时 Gate → 运行时 Gate → API 级 Gate

1,900 个文件，512,000 行代码

// 101 个命令目录，52 个工具目录
// 每个都是独立的文件夹 + TS 文件
src/commands/add-dir/
src/commands/advisor.ts
src/commands/agents/
// ... 大量重复结构

// tools.ts 注释已经承认了问题
// Lazy require to break circular dependency
const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js')
const getSendMessageTool = () =>
  require('./tools/SendMessageTool/SendMessageTool.js')

// QueryEngine.ts - 8 个私有状态变量
private mutableMessages: Message[]
private abortController: AbortController
private permissionDenials: SDKPermissionDenial[]
private totalUsage: NonNullableUsage
private hasHandledOrphanedPermission = false
private readFileState: FileStateCache
private discoveredSkillNames = new Set<string>()
private loadedNestedMemoryPaths = new Set<string>()

20+ Feature Flags

// buddy/types.ts
const c = String.fromCharCode
export const duck = c(0x64,0x75,0x63,0x6b) as 'duck'  // "duck"

101 个命令

// 内部 Skills 不共享
src/skills/  // 只能 Anthropic 内部用