AI Agent 搭建说明书

从 Claude Code 源码出发,拆解生产级 AI Agent 的核心架构设计

基于 ~512,000 行 TypeScript 代码的逆向工程实践 · 2026

1. 前言:Claude Code 是什么

Claude Code 是 Anthropic 推出的终端原生 AI Agent。它不是简单的"对话封装",而是一个完整的终端 Agent 框架——核心是思考→行动→观察的循环(Reasoning → Acting → Observing),围绕这个循环构建了工具系统、权限模型、上下文管理、多 Agent 协调等完整基础设施。

claude-code/ ├── main.tsx # 入口 ├── Tool.ts # 工具类型定义(Schema、权限、渲染) ├── tools.ts # 工具注册表 ├── QueryEngine.ts # 核心 Agent Loop (~48KB / ~2000 行) ├── query.ts # 查询编排层 (~70KB) ├── commands.ts # 命令注册表 ├── context.ts # 上下文收集 ├── tools/ # ~40 个工具,每个独立模块 │ ├── BashTool/ # ├─ 定义 + prompt + UI + 安全 │ ├── FileEditTool/ # ├─ ... │ └── AgentTool/ # └─ 子 Agent 生成 ├── bridge/ # IDE 双向通信(VS Code / JetBrains) ├── services/ # API、MCP、压缩、认证、OAuth ├── hooks/ # 80+ React Hooks + 权限钩子 ├── components/ # 140+ Ink 终端 UI 组件 ├── state/ # 全局状态(类似 Redux) ├── coordinator/ # 多 Agent 协调器 ├── plugins/ # 插件系统 ├── skills/ # Skill 系统 ├── ink/ # Ink 渲染器封装 └── utils/ # 工具函数

本文档将逐一拆解每个核心子系统,说明它们存在的理由、内部设计、以及你如何在自己的 Agent 中复现这些模式。

2. 第一阶段:确定 Agent Loop(核心循环)

搭建 Agent 第一步不是写 UI,不是设计工具,而是确定循环。它是 Agent 的"操作系统",其他所有系统都挂在这个循环上。

2.1 什么是 Agent Loop

Agent Loop 是一个思考→行动→观察的迭代过程:

┌─────────────────────────────────────────────┐ │ Agent Loop │ │ │ │ 1. 构建系统提示 │ │ ├─ 系统角色定义 + 工具定义 (JSON Schema) │ │ ├─ 上下文(项目信息、记忆、Git 状态) │ │ └─ 对话历史 + 最近工具结果 │ │ │ │ 2. 调用 LLM │ │ ├─ 流式响应 → text / thinking / tool_use │ │ └─ 获取模型回复 │ │ │ │ 3. 处理响应 │ │ ├─ text 块 → 显示给用户 │ │ ├─ thinking 块 → 存储(Extended Thinking) │ │ └─ tool_use 块 → 进入工具执行 │ │ │ │ 4. 执行工具 │ │ ├─ 权限检查 → deny / allow / ask │ │ ├─ 执行 → 收集结果 │ │ └─ 结果裁剪(工具结果太大时压缩) │ │ │ │ 5. 循环判断 │ │ ├─ end_turn → 结束 │ │ ├─ max_tokens → 恢复继续 │ │ ├─ tool_use → 回到步骤 1 │ │ └─ 超时/中断 → 中止 │ │ │ │ 6. 后处理 │ │ ├─ 自动压缩(上下文快满时) │ │ ├─ 记忆提取 │ │ ├─ 存储 + 遥测上报 │ │ └─ 等待下一条用户消息 │ └─────────────────────────────────────────────┘

2.2 如何实现 Agent Loop

Claude Code 的实现分为两个层次:

你的最小实现应该包含以下核心结构:

// 最小 Agent Loop 骨架
class AgentLoop {
  // 单次查询:构建上下文 → 调用 LLM → 处理工具 → 返回结果
  async query(context: ToolUseContext): Promise<AgentResult> {
    // 1. 构建系统提示
    const systemPrompt = await this.buildSystemPrompt(context)

    // 2. 调用 LLM(流式)
    const response = await this.callLLM(systemPrompt, context.messages)

    // 3. 处理流式事件
    for await (const event of response) {
      if (event.type === 'text') this.handleText(event)
      if (event.type === 'tool_use') {
        // 4. 执行工具
        const result = await this.executeTool(event, context)
        context.messages.push(result)
        // 5. 循环 — 把结果送回 LLM
        return this.query(context)  // 递归继续
      }
      if (event.type === 'end_turn') break
    }
    return { messages: context.messages }
  }

  // 工具执行
  async executeTool(toolUse, context) {
    // 权限检查 → 执行 → 返回结果
    const tool = this.toolRegistry.get(toolUse.name)
    await this.permissionCheck(tool, toolUse.input)
    return await tool.execute(toolUse.input)
  }
}
🎯 关键设计决策:
  • 递归 vs 迭代 — Claude Code 使用递归方式(容易实现上下文隔离),但深度要有限制防栈溢出
  • 流式 vs 阻塞 — 必须支持流式 API,否则用户等不到反馈
  • 中止控制 — 每个循环必须有 AbortController,支持用户中断
  • Token 预算 — 为单轮输出设置上限,防止死循环

2.3 关键细节:Token 预算与恢复

Claude Code 有一个精巧的 token 预算系统:

// query/tokenBudget.ts
class TokenBudgetTracker {
  continuationCount: number  // 当前轮的恢复次数
  lastDeltaTokens: number    // 最后一块的 token 数
  lastGlobalTurnTokens: number // 全局累计
  startedAt: number          // 开始时间

  // 检查是否需要继续
  checkTokenBudget(
    agentId: string | undefined,
    budget: number | null,        // --max-turn-budget
    globalTurnTokens: number      // 当前已消耗的 token 数
  ): 'continue' | 'stop' {
    // 1. 收益递减检测:最后一块少于 500 tokens 时停止
    // 2. 预算检查:超过 max-turn-budget 时停止
    // 3. 完成度检查:达到 COMPLETION_THRESHOLD (90%) 时停止
  }
}
⚠️ 重要总结:Agent Loop 是先于一切设计的。不要先写工具再设计循环——循环决定了所有工具的交互方式。一个好的循环设计应该具备:
  • 可中断性 — 用户可以随时打断
  • 可恢复性 — token 用尽后可以继续
  • 可观测性 — 知道每个环节的耗时和 token 消耗
  • 错误隔离 — 单个工具失败不影响整个循环

2.5 重要补充:并发工具执行(StreamingToolExecutor)

Claude Code 返回的响应中可能包含多个 tool_use 块。如何高效执行这些工具是一个关键的性能优化点。

设计:并发安全 vs 独占执行

Claude Code 的 StreamingToolExecutor 将工具分为两类:

// 1. 并发安全工具 — 可同时执行
// Glob、Grep、FileRead、WebFetch、WebSearch 等只读操作
// 这些工具互不干扰,可以并行运行

// 2. 独占工具 — 一次只能执行一个
// Bash、FileEdit、FileWrite 等写操作
// 同时执行可能产生竞态

// 执行策略:
// ┌─────────┐  ┌─────────┐  ┌─────────┐
// │ Glob   │  │ Grep   │  │ Read   │  ← 并发安全,同时运行
// └─────────┘  └─────────┘  └─────────┘
//      ┌──────────┐
//      │  Bash    │  ← 独占,等前面的并发工具完成后再执行
//      └──────────┘
//      ┌──────────┐
//      │  Edit    │  ← 独占,串行执行
//      └──────────┘

核心实现

// StreamingToolExecutor
class StreamingToolExecutor {
  private tools: TrackedTool[] = []
  // 子 abortController — 当兄弟工具失败时杀死它
  private siblingAbortController: AbortController

  // 添加工具到队列
  addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {
    // 判断是否并发安全
    const isConcurrencySafe = toolHasTag(toolDefinition, 'concurrency-safe')

    // 如果可以立即执行,直接启动
    if (this.canStartExecution(tool)) {
      this.executeTool(tool)
    }
  }

  // 是否可以开始执行
  private canStartExecution(tool: TrackedTool): boolean {
    if (tool.isConcurrencySafe) {
      // 并发安全工具:只要没有正在执行的独占工具
      return !this.hasRunningExclusiveTool()
    } else {
      // 独占工具:没有正在执行的任何工具
      return this.tools.every(t => t.status !== 'executing')
    }
  }

  // 获取剩余结果(阻塞等待所有工具完成)
  async getRemainingResults(): Promise<MessageUpdate> {
    // 按工具原始顺序返回结果
    // 并发安全工具的结果可能乱序完成,但返回时保证顺序
  }

  // 放弃所有待处理和正在执行的工具(fallback 时调用)
  discard(): void {
    // 待启动的不会启动,正在执行的收到 synthetic error
  }
}

进度消息流

// 工具执行的每个阶段都发出进度事件
// 用户可以在终端看到实时状态

事件流:
  queued      → 工具加入队列等待执行
  executing   → 开始执行(显示 spinner)
  progress    → 执行中的增量输出(Bash 的 stdout)
  completed   → 执行完成
  yielded     → 被放弃(discard)

// 长时间运行的工具(Bash)
// 每行输出都作为 ProgressMessage 流式显示
// 用户可以实时看到命令的输出
💡 实现建议:
  • 并发安全分类 — 不是所有工具都是并发安全的。读操作可以并行,写操作要串行
  • 兄弟取消 — 一个 Bash 失败时,自动取消其他正在运行的 Bash,避免残留进程
  • 结果排序 — 虽然工具可能并行完成,但结果要按 LLM 返回的顺序排列
  • 进度反馈 — 长时间执行的工具(Bash、网络请求)一定要流式显示进度

3. 第二阶段:搭建工具系统(Tool System)

工具是 Agent 与外部世界交互的接口。Claude Code 的工具系统设计非常精巧,值得深入学习。

3.1 工具定义:一个工具 = 4 个文件

Claude Code 中每个工具是独立目录,包含 4 个标准文件:

tools/BashTool/               ← 实际有 18 个文件
├── BashTool.tsx              ← 工具定义 (Schema, isEnabled, 权限)
├── prompt.ts                 ← 系统提示词片段(告诉 LLM 怎么用)
├── UI.tsx                    ← Ink 终端渲染组件
├── bashSecurity.ts           ← 安全校验逻辑(tree-sitter 解析)
├── bashPermissions.ts        ← 权限规则匹配(通配符、前缀)
├── commandSemantics.ts       ← 命令语义分析(只读 vs 写入)
├── readOnlyValidation.ts     ← 只读模式验证
├── sedEditParser.ts          ← sed 命令解析(检测文件修改)
├── sedValidation.ts          ← sed 命令安全验证
├── shouldUseSandbox.ts       ← 是否启用沙箱执行
├── destructiveCommandWarning.ts ← 危险命令警告
├── pathValidation.ts         ← 路径穿越防护
├── modeValidation.ts         ← 权限模式验证
├── toolName.ts               ← 工具名常量
├── utils.ts                  ← 工具函数
├── bashCommandHelpers.ts     ← 命令辅助
├── commentLabel.ts           ← 注释标签
└── BashToolResultMessage.tsx ← 结果消息渲染

3.2 工具类型定义 (Tool.ts)

每个工具需要定义以下核心接口:

// Tool.ts — 工具完整类型定义(源码中有 30+ 个方法/属性)
interface Tool<TInput extends AnyObject, TOutput, TProgress extends ToolProgressData> {
  // ═══ 元数据 ═══
  name: string                        // 工具名(LLM 调用的 key)
  aliases?: string[]                  // 别名(重命名兼容,如 'KillShell' → 'TaskStop')
  searchHint?: string                 // ToolSearch 关键词(3-10 词)
  readonly inputSchema: TInput        // Zod Schema
  inputJSONSchema?: ToolInputJSONSchema // MCP 工具直接用 JSON Schema
  outputSchema?: z.ZodType            // 输出 Schema(可选)
  maxResultSizeChars: number          // 结果大小上限(超过则持久化到磁盘)
  readonly strict?: boolean           // 严格模式(API 更严格遵循 Schema)
  readonly shouldDefer?: boolean      // 延迟加载(ToolSearch 模式)
  readonly alwaysLoad?: boolean       // 始终加载(不被 defer)
  isMcp?: boolean                     // 是否 MCP 工具
  isLsp?: boolean                     // 是否 LSP 工具
  mcpInfo?: { serverName: string; toolName: string } // MCP 服务端信息

  // ═══ 生命周期 ═══
  isEnabled(): boolean                // 当前环境是否可用
  isConcurrencySafe(input): boolean   // 是否并发安全(只读=true)
  isReadOnly(input): boolean          // 是否只读操作
  isDestructive?(input): boolean      // 是否破坏性操作(删除、覆盖)

  // ═══ 权限 ═══
  checkPermissions(input, context): Promise<PermissionResult>
  preparePermissionMatcher?(input): Promise<(pattern: string) => boolean>

  // ═══ 输入处理 ═══
  validateInput?(input, context): Promise<ValidationResult>
  backfillObservableInput?(input: Record<string, unknown>): void // 给 hooks 回填字段
  inputsEquivalent?(a, b): boolean    // 输入等价判断

  // ═══ 执行 ═══
  call(input, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<TOutput>>
  interruptBehavior?(): 'cancel' | 'block'  // 用户中断时的行为

  // ═══ 提示词 ═══
  description(input, options): Promise<string>  // 动态描述
  prompt(options): Promise<string>               // 系统提示词片段

  // ═══ UI 渲染 ═══
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage?(content, progress, options): React.ReactNode
  renderToolUseProgressMessage?(progress, options): React.ReactNode
  renderToolUseRejectedMessage?(input, options): React.ReactNode
  renderToolUseErrorMessage?(result, options): React.ReactNode
  renderGroupedToolUse?(toolUses, options): React.ReactNode | null
  userFacingName(input): string
  userFacingNameBackgroundColor?(input): keyof Theme | undefined
  getToolUseSummary?(input): string | null
  getActivityDescription?(input): string | null
  renderToolUseTag?(input): React.ReactNode

  // ═══ 搜索与分类 ═══
  isSearchOrReadCommand?(input): { isSearch: boolean; isRead: boolean; isList?: boolean }
  isOpenWorld?(input): boolean
  isTransparentWrapper?(): boolean
  isResultTruncated?(output): boolean
  extractSearchText?(out): string
  toAutoClassifierInput(input): unknown  // Auto 模式分类器输入
  mapToolResultToToolResultBlockParam(content, toolUseID): ToolResultBlockParam
}

3.3 工具注册表 (tools.ts)

Claude Code 使用动态工具组装,不是硬编码列表:

// tools.ts — 工具注册表

// 1. 所有基础工具(构建时的完整列表)
function getAllBaseTools(): Tools {
  return [
    AgentTool,
    BashTool,
    FileEditTool,
    FileReadTool,
    FileWriteTool,
    GlobTool,
    GrepTool,
    WebFetchTool,
    WebSearchTool,
    // ... ~40 个工具
    // 条件性加入(Feature Flag 在构建时消除)
    ...(feature('PROACTIVE') ? [SleepTool] : []),
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
  ]
}

// 2. 按权限过滤
function getTools(permissionContext): Tools {
  const tools = getAllBaseTools()
  return filterToolsByDenyRules(tools, permissionContext)
}

// 3. 合并 MCP 外部工具
function assembleToolPool(permissionContext, mcpTools): Tools {
  const builtIn = getTools(permissionContext)
  const allowedMcp = filterToolsByDenyRules(mcpTools, permissionContext)
  // 内置工具优先,MCP 工具排序在后(prompt cache 稳定性)
  return uniqBy(
    [...builtIn].sort(byName).concat(allowedMcp.sort(byName)),
    'name'
  )
}

3.4 Schema 定义(Zod v4)

Claude Code 使用 Zod v4 定义工具输入 Schema,自动生成 JSON Schema 供 LLM 调用:

// 工具 Schema 示例 — BashTool
const BashInputSchema = z.object({
  command: z.string().describe('The command to execute'),
  description: z.string().optional()
    .describe('Brief description of what this command does'),
  is_background: z.boolean().optional()
    .default(false)
    .describe('Run in background'),
  wait: z.string().optional()
    .describe('Wait for a specific string in output'),
})

// 在工具定义中使用
class BashTool implements Tool<typeof BashInputSchema> {
  parameters = zodToJsonSchema(BashInputSchema)
}
🎯 Schema 设计原则:
  • 每个参数都要有 description — LLM 需要用描述来理解参数语义,类型名不足以表达
  • 可选参数给默认值 — 减少 LLM 的决策负担
  • 限制枚举值数量 — 超过 10 个枚举值的参数,LLM 选错概率大增
  • 用 describe 写场景提示 — "什么时候用这个参数、什么时候不用"

3.5 工具执行的完整链路

LLM 返回 tool_use 块
  │
  ├─ 1. 查找工具定义
  │     └─ toolRegistry.get(toolName)
  │
  ├─ 2. Schema 验证
  │     └─ Zod 校验输入参数
  │
  ├─ 3. 权限检查(见下一节)
  │
  ├─ 4. 执行
  │     └─ tool.execute(input) → 输出流式事件
  │
  ├─ 5. 结果显示
  │     └─ tool.renderToolResultUseMessage(input) → React Node
  │
  └─ 6. 结果裁剪(大结果时)
        └─ applyToolResultBudget() → 截断/压缩
💡 设计亮点 — 结果裁剪(Tool Result Budget):

当工具结果太大时,Claude Code 不会直接丢弃,而是按工具类型分策略处理:

  • 文件读取结果 — 只保留最近的 N 条,旧的结果替换为 "[Old tool result content cleared]"
  • Bash 输出 — 截断到最大行数,保留头尾
  • 搜索结果 — 只保留摘要,详细结果被压缩

这是 MicroCompact(微压缩)策略的一部分——在每次工具调用后检查。

2.5 重要补充:系统提示词工程(System Prompt Architecture)

系统提示词是 Agent 行为的"基因"——它决定了 Agent 的性格、能力边界和判断标准。Claude Code 的系统提示词非常复杂,由 10+ 个独立模块组装而成,每个模块负责不同的职责。

提示词分段架构

// Claude Code 的系统提示词组装流程
// 总共 ~15,000+ tokens,分为以下模块:

┌─────────────────────────────────────────────────────┐
│               系统提示词                           │
│                                                      │
│  1. 角色定义         (Intro)                         │
│     "You are an interactive agent that helps        │
│      users with software engineering tasks."
│                                                      │
│  2. 网络安全指令      (Cyber Risk)                   │
│     "Do not generate malicious code..."
│                                                      │
│  3. 系统行为说明      (System)                        │
│     "All text you output is displayed to the user..."
│     "Tools are executed in a user-selected           │
│      permission mode..."
│                                                      │
│  4. 执行行为指南      (Doing Tasks)                   │
│     "Don\'t add features beyond what was asked..."
│     "Be careful not to introduce security             │
│      vulnerabilities..."
│                                                      │
│  5. 行动谨慎指南      (Actions)                       │
│     "Carefully consider the reversibility..."
│     "Only take risky actions carefully..."
│                                                      │
│  6. 工具使用指南      (Tools)                         │
│     "Prefer dedicated tools over Bash..."
│     "If you need to edit a file..."
│                                                      │
│  7. 子 Agent 指南     (Agent)                         │
│     "Sub-agents inherit the same tools..."
│                                                      │
│  8. 记忆系统         (Memory)                        │
│     "Use CLAUDE.md for persistent state..."
│     "Autosave user preferences..."
│                                                      │
│  9. 动态上下文       (Dynamic)                       │
│     "Working directory: /home/user/project"
│     "Git status: 2 files modified"
│     "MCP servers: 3 connected"
│                                                      │
│  10. 工具 Schema     (Tool Definitions)               │
│     每个工具的 JSON Schema 描述                       │
│                                                      │
│  ┌──────────────────────────────────────────────┐    │
│  │     ⚡ 缓存分界线 (Cache Boundary)           │    │
│  └──────────────────────────────────────────────┘    │
│                                                      │
│  11. 用户上下文       (User Context)                  │
│     "Preferred language: Chinese"
│                                                      │
│  12. 系统上下文       (System Context)                 │
│     "MCP server instructions..."
│                                                      │
│  13. 输出风格         (Output Style)                  │
│     "Respond in a concise style..."
│                                                      │
└─────────────────────────────────────────────────────┘

缓存分界线设计

Claude Code 在提示词中间插入了一个 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记:

// 缓存分界线的作用:

__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__

// 分界线之前的内容:
//   → 跨组织缓存(scope: global)
//   → 角色定义、系统说明、工具指南
//   → 这些内容对所有用户都一样,可以复用缓存

// 分界线之后的内容:
//   → 用户/会话级缓存(scope: session)
//   → 用户上下文、MCP 指令、输出风格
//   → 这些内容因用户而异,不能跨用户缓存
// 提示词组装的代码结构
async function getSystemPrompt(
  tools: Tools,
  mainLoopModel: string,
  additionalWorkingDirectories: string[],
  mcpClients: MCPServerConnection[],
): Promise<string[]> {
  // 1. 获取静态部分(角色 + 行为指南)
  const intro = getSimpleIntroSection()
  const cyberRisk = getSimpleCyberRiskSection()
  const system = getSimpleSystemSection()
  const tasks = getSimpleDoingTasksSection()
  const actions = getActionsSection()
  const tools = getUsingYourToolsSection(enabledTools)

  // 2. 注入缓存分界线
  const boundary = SYSTEM_PROMPT_DYNAMIC_BOUNDARY

  // 3. 获取动态部分
  const memory = await loadMemoryPrompt()
  const gitStatus = await getGitStatus()
  const mcpInstructions = getMcpInstructions(mcpClients)

  // 4. 返回数组(系统消息 = 数组拼接)
  return [
    intro, cyberRisk, system, tasks, actions, tools,
    boundary,
    memory, gitStatus, mcpInstructions,
  ]
}

关键设计原则

🎯 提示词工程的 5 个原则:
  • 分段模块化 — 每个模块独立,职责单一。修改一个不影响其他
  • 缓存友好 — 静态部分放在前面(可缓存),动态部分放在后面(每次更新)
  • 工具驱动 — 告诉 LLM "用什么工具"比"怎么做"更有效
  • 行为约束 — 明确说"不要做什么"比"应该做什么"更有约束力
  • 上下文注入 — 动态注入 git 状态、项目结构、MCP 工具等实时信息
⚠️ 常见错误:
  • 把所有内容堆到一个 prompt 里 → 难维护、难调试
  • 不区分缓存级别 → 浪费缓存,增加延迟
  • 不注入动态上下文 → Agent 不知道当前项目状态
  • 过度详细 → 提示词太长,挤占有效工作空间

4. 第三阶段:设计权限模型(Permission Model)

权限系统是 Agent 安全性的基石。Claude Code 的权限设计是多层纵深防御的典范。

4.1 权限模式(6 种模式)

// 用户可设置的模式
type PermissionMode =
  | 'default'             // 默认:每次工具调用都询问用户
  | 'plan'                // 计划模式:只允许读操作(文件读取、搜索)
  | 'acceptEdits'         // 接受编辑:文件修改自动批准
  | 'bypassPermissions'   // 绕过全部:信任 Agent(危险!)
  | 'dontAsk'             // 不问:类似 bypass
  | 'auto'                // 自动审批:基于分类器判断

4.2 权限规则分层

规则可以来自多个层级,优先级从高到低:

// 权限规则来源(按优先级排序)
type PermissionRuleSource =
  | 'policySettings'      // 组织策略(最高优先级)
  | 'cliArg'              // CLI 命令行参数
  | 'userSettings'        // 用户设置
  | 'projectSettings'     // 项目设置 (.claude/settings.json)
  | 'localSettings'       // 本地设置
  | 'flagSettings'        // 功能开关

// 每条规则决定行为
type PermissionBehavior = 'allow' | 'deny' | 'ask'

4.3 权限检查流程

工具调用请求 │ ├─ 1. Deny Rules 检查 │ (配置级拒绝规则,按 source 分层) │ └─ 命中的 → 拒绝,不执行 │ ├─ 2. Permission Mode 分发 │ ├─ default → 显示确认对话框 │ ├─ plan → 只读检查(读操作允许,写操作弹窗) │ ├─ auto → 分类器 + Hook 自动判断 │ └─ bypass → 直接放行 │ ├─ 3. Hook 检查(pre-tool-use hooks) │ └─ 自定义脚本可以 approve / deny │ ├─ 4. 交互确认(如需要) │ ├─ 显示工具详情 + 参数预览 │ ├─ 用户按 y/n │ └─ 超时 → 拒绝 │ └─ 5. 执行 → 结果返回

4.4 实现你的权限系统

// 权限上下文 — 快照化以防止竞态
type ToolPermissionContext = {
  mode: PermissionMode
  alwaysAllowRules: ToolPermissionRules   // 按工具名 → 参数模式映射
  alwaysDenyRules: ToolPermissionRules
  alwaysAskRules: ToolPermissionRules
  isBypassPermissionsModeAvailable: boolean
  isAutoModeAvailable?: boolean

  // 后台 Agent 标记 — 无 UI 时自动拒绝
  shouldAvoidPermissionPrompts?: boolean
}

// 权限检查函数
async function canUseTool(
  tool: Tool,
  input: unknown,
  context: ToolPermissionContext
): Promise<PermissionResult> {
  // 1. 检查 deny rules
  const denyRule = findMatchingRule(tool.name, input, context.alwaysDenyRules)
  if (denyRule) return { result: false, reason: denyRule.message }

  // 2. 检查 allow rules
  if (isAlwaysAllowed(tool.name, input, context)) {
    return { result: true }
  }

  // 3. 根据 mode 处理
  switch (context.mode) {
    case 'plan':
      return handlePlanMode(tool, input)
    case 'auto':
      return handleAutoMode(tool, input)  // 调用分类器
    case 'default':
      return handleInteractivePrompt(tool, input)  // 显示对话框
    case 'bypassPermissions':
      return { result: true }
  }
}

// 拒绝追踪 — 连续拒绝时可自动拒绝同类操作
type DenialTrackingState = {
  // 按工具名追踪最近 N 次拒绝
  recentDenials: Map<string, Timestamp[]>
}
🔒 安全底线:
  • 永远不能绕过 Plan 模式的安全检查 — Plan 模式是只读的,写入操作必须被拦截
  • Auto 模式不是 bypass — 需要一个分类器(可以是小模型)来判断操作是否安全
  • 拒绝追踪 — 用户连续拒绝同类型操作后,Agent 应该自动停止尝试
  • 后台 Agent 无 UI — 设置 shouldAvoidPermissionPrompts=true,所有需确认的操作自动拒绝

3.5 重要补充:Plan 模式(只读探索 → 再修改)

Plan 模式是 Claude Code 最精巧的 UX 设计之一——它让 Agent 先以只读方式探索代码库,理解上下文后,再切换到修改模式。

为什么需要 Plan 模式

// 没有 Plan 模式的问题:

用户: "重构这个模块的错误处理"

Agent (直接修改):
  1. 读第一个文件... 还没理解全貌
  2. 就开始改了!
  3. 改到一半发现架构不兼容
  4. 改坏了,回滚...

// 结果:浪费时间,可能引入 bug

// 有了 Plan 模式:

用户: "重构这个模块的错误处理" (Plan 模式)

Agent (只读探索):
  1. 读所有相关文件
  2. grep 错误处理模式
  3. 理解依赖关系
  4. 输出一个详细计划
  5. 用户确认后,切换到修改模式
  6. 按计划精确执行

// 结果:更准确、更安全、更高效

Plan 模式的实现方式

// Plan 模式的核心:通过权限模型实现

// 1. 注册 Plan 模式的权限配置
const planPermissionMode: PermissionMode = {
  name: 'plan',
  // 允许的操作(只读)
  autoAllow: [
    'FileReadTool',    // 读文件
    'GlobTool',        // 查找文件
    'GrepTool',        // 搜索内容
    'BashTool[git:*]', // 只读 git 命令
    'WebSearchTool',   // 搜索
  ],
  // 禁止的操作(写入)
  autoDeny: [
    'FileEditTool',    // 编辑
    'FileWriteTool',   // 写入
    'BashTool[rm:*]',  // 删除
    'BashTool[mv:*]',  // 移动
  ],
}

// 2. 切换到 Plan 模式
// 用户可以通过 /plan 命令或 UI 按钮切换
// 切换后,Agent 的所有写入操作都会被拦截

// 3. Agent 自己也能切换
// 系统提示词告诉 Agent:
// "You are in plan mode. Read files, explore the codebase,
//  but DO NOT make any changes until the user approves."

// 4. 用户确认后,退出 Plan 模式
// /plan off 或点击按钮
// Agent 按计划执行修改
💡 Plan 模式的价值:
  • 降低风险 — 复杂任务先探索后执行,避免盲目修改
  • 节省 token — 不用反复试错,一次探索到位
  • 用户控制 — 用户看到计划后可以选择批准、修改或拒绝
  • Agent 学习 — 通过探索,Agent 对代码库建立更深理解

3.6 重要补充:Hooks 钩子系统

Hooks 是 Claude Code 的可扩展性设计——允许用户在工具执行的各个生命周期节点注入自定义逻辑。

Hook 类型

// Claude Code 的 Hook 系统有 4 个生命周期节点

┌─────────────────────────────────────────────────────┐
│                  Hook 生命周期                      │
│                                                      │
│   用户输入 ──→ PreToolUse ──→ 工具执行 ──→ PostToolUse │
│                                    │              │
│                                    ↓              ↓
│                              PostSampling   Notification
│                                                      │
│   SessionStart ──→ 会话初始化(加载记忆、检查环境)   │
└─────────────────────────────────────────────────────┘

// PreToolUse Hook
//   - 工具执行前触发
//   - 可以修改输入参数、阻止执行、或添加额外检查
//   - 例如:检查 Bash 命令是否包含危险操作

// PostToolUse Hook
//   - 工具执行后触发
//   - 可以处理结果、触发后续操作、记录日志
//   - 例如:Bash 执行完后,自动检查输出是否包含敏感信息

// PostSampling Hook
//   - LLM 返回响应后触发(在工具执行之前)
//   - 可以修改 LLM 响应、记录推理过程
//   - 例如:记录 LLM 的 token 使用情况

// SessionStart Hook
//   - 会话开始时触发
//   - 可以初始化环境、加载配置、检查依赖
//   - 例如:检查 git 状态、加载 CLAUDE.md

Hook 注册与执行

// Hook 注册
type HookContext = {
  toolName: string
  input: Record<string, unknown>
  result?: unknown
  messages: Message[]
  systemPrompt: SystemPrompt
}

type Hook = (ctx: HookContext) => Promise<void> | void

// 注册表
const hooks = {
  preToolUse: new Map<string, Hook[]>(),
  postToolUse: new Map<string, Hook[]>(),
  postSampling: new Map<string, Hook[]>(),
  sessionStart: new Map<string, Hook[]>(),
}

// 注册 hook
hooks.preToolUse.set('BashTool', [
  async (ctx) => {
    if (ctx.input.command.includes('rm -rf')) {
      throw new Error('危险命令被阻止')
    }
  }
])

// 执行 hook
async function executeHooks(phase: string, toolName: string, ctx) {
  const phaseHooks = hooks[phase].get(toolName) || []
  for (const hook of phaseHooks) {
    await hook(ctx)
  }
}
🎯 Hook 使用场景:
  • 安全审计 — PreToolUse 拦截危险命令,PostToolUse 记录所有操作
  • 代码规范 — PostToolUse 检查编辑后的代码是否符合规范
  • 自动测试 — FileEditTool 执行后自动运行相关测试
  • 环境检查 — SessionStart 检查依赖是否安装
  • 通知集成 — 长时间任务完成后发送通知

5. 第四阶段:构建状态管理(State Management)

Agent 的状态管理比前端应用复杂——不仅管理 UI 状态,还要管理消息流、工具执行、MCP 连接等并发状态。

5.1 Claude Code 的状态模型

// AppStateStore.ts — 全局不可变状态
type AppState = DeepImmutable<{
  // 消息系统
  messages: Message[]                      // 对话消息(用户 + 助手 + 工具)

  // 工具系统
  tools: Tool[]                            // 可用内置工具
  mcpClients: MCPServerConnection[]        // MCP 连接
  mcpTools: Tool[]                         // MCP 提供的工具
  mcpResources: Record<string, Resource[]> // MCP 资源

  // 权限系统
  permissionContext: ToolPermissionContext  // 权限上下文(快照)

  // 会话
  conversationId: UUID                     // 会话 ID
  agentDefinitions: AgentDefinitionsResult // Agent 定义
  agentType?: string                       // 当前 Agent 类型

  // 生命周期
  settings: SettingsJson                   // 用户设置
  plugins: LoadedPlugin[]                  // 已加载插件
  taskStates: Map<string, TaskState>       // 后台任务

  // ... 更多 ~100+ 字段
}>

5.2 不可变状态 Store

// store.ts — 自定义响应式 Store
type Store<T> = {
  getState: () => T              // 读取快照
  setState: (f: (prev: T) => T) => void  // 不可变更新
  subscribe: (f: () => void) => () => void  // 订阅变更
}
🎯 为什么用不可变状态(DeepImmutable):
  • 引用稳定 — 函数组件可以安全地用引用比较检测变化
  • 无竞态 — 取消/后台任务不会在"已过时的状态"上执行操作
  • 时间旅行调试 — 可以保存和恢复状态快照
  • 类型安全 — TypeScript 的 DeepImmutable 防止意外修改

5.3 消息类型体系

Claude Code 的消息类型不仅仅是"用户"和"助手"——它有精细的分类:

// types/message.ts — 消息类型体系
type Message =
  | UserMessage                    // 用户输入
  | AssistantMessage               // 助手回复(含 tool_use 块)
  | AssistantRedactedThinkingMessage  // 被隐藏的思考过程
  | AssistantThinkingMessage       // Extended Thinking 内容
  | ToolResultMessage              // 工具执行结果
  | ProgressMessage                // 进度更新(如 Bash 正在执行)
  | SystemMessage                  // 系统级消息(压缩边界等)
  | TombstoneMessage               // 被压缩或删除的旧消息
  | ToolUseSummaryMessage          // 工具调用汇总
  | AttachmentMessage              // 附件(文件、图片)

( ˘ ³˘)♥ 好的消息类型设计让调试变简单

5.4 你的状态管理实现方案

根据项目复杂度选择:

方案 适合场景 参考
Zustand 中小型 Agent,快速启动 轻量、TypeScript 友好
自定义 Store + DeepImmutable 大型 Agent,需要精细控制 Claude Code 的方式
Redux Toolkit 团队项目,需要 DevTools 生态成熟,学习曲线高
Signal (Preact/Solid) 性能敏感的 UI 细粒度响应式更新

4.5 重要补充:会话持久化与恢复

Agent 每次会话都是一段连续对话。会话结束后如何保存状态、如何恢复上下文、如何处理崩溃恢复,是生产级 Agent 必须解决的问题。

文件状态缓存(FileStateCache)

// Claude Code 使用 LRU 缓存来跟踪文件状态
// 避免重复读取同一文件,也用于检测文件是否被修改

class FileStateCache {
  private cache = new Map<string, CachedFile>()
  private maxSize = 1000  // 最多缓存 1000 个文件

  async getFileState(path: string): Promise<FileState> {
    const cached = this.cache.get(path)
    if (cached) {
      const stat = await fs.stat(path)
      if (stat.mtimeMs === cached.mtime) {
        return cached.state  // 缓存有效
      }
      this.cache.delete(path)  // 文件被修改,清除缓存
    }
    const content = await fs.readFile(path, 'utf-8')
    const state = { content, lines: content.split('\n') }
    this.cache.set(path, { mtime: stat.mtimeMs, state })
    // LRU 淘汰
    if (this.cache.size > this.maxSize) {
      const oldest = this.cache.keys().next().value
      this.cache.delete(oldest)
    }
    return state
  }

  // 工具修改文件后主动更新缓存
  updateFileState(path: string, content: string): void {
    this.cache.set(path, {
      mtime: Date.now(),
      state: { content, lines: content.split('\n') },
    })
  }
}

会话存储与恢复

// 会话生命周期

Session {
  id: string                    // 唯一标识
  messages: Message[]           // 完整对话历史
  toolResults: Map<string, ToolResult>  // 工具结果(可能很大)
  createdAt: number
  lastActiveAt: number
  metadata: {
    totalTokens: number         // 累计 token 使用
    model: string               // 使用的模型
  }
}

// 存储策略
// 1. 内存存储(热会话)→ 当前活跃会话,快速访问
// 2. 磁盘存储(冷会话)→ 历史会话持久化到 ~/.claude/sessions/
// 3. 崩溃恢复→ 每次 LLM 调用前保存 checkpoint,崩溃后从最近的 checkpoint 恢复

CLAUDE.md 记忆文件

// 记忆系统:不是数据库,而是项目根目录下的 markdown 文件

// ~/.claude/CLAUDE.md  → 用户级记忆(全局)
// .claude/CLAUDE.md    → 项目级记忆(仅当前项目)
// .claude/CLAUDE.local.md → 本地记忆(不提交到 git)

// 记忆格式是 markdown,用户可以直接编辑
// 也可以让 Agent 自动写入

// Agent 读取时机:会话开始时自动加载,注入系统提示词
// Agent 写入时机:用户说 "remember this" 或 /memory 命令触发
💡 会话持久化的设计原则:
  • 分层存储 — 热会话在内存,冷会话在磁盘,记忆在文件
  • 增量更新 — 不要每次保存整个会话,只保存变化的部分
  • 压缩优先 — 存储前先压缩,减少磁盘占用
  • 用户可控 — 用户可以查看、编辑、删除任何会话
  • 隐私保护 — 敏感信息(API key、密码)不存储到会话中

6. 第五阶段:上下文管理(Context Management)

LLM 上下文窗口有限(通常 200K tokens),会话一长就会溢出。上下文管理是生产级 Agent 必须解决的难题。

6.1 三级压缩策略

Claude Code 使用三级压缩,每层解决不同粒度的问题:

三级上下文压缩策略 L1: MicroCompact(每次工具调用后) 触发: 每次 tool_result 返回后 策略: 清理旧的工具结果(只保留最近 N 条) 目标: 工具结果太多 → 压缩历史结果 保留: 最近 20 条完整工具结果 替换: 旧结果 → "[Old tool result content cleared]" // 只压缩特定工具的结果(文件读取、Shell、搜索) COMPACTABLE_TOOLS = new Set([ 'FileRead', 'Bash', 'Grep', 'Glob', 'WebSearch', 'WebFetch', 'FileEdit', 'FileWrite' ]) L2: AutoCompact(上下文快满时) 触发: tokens 达到 contextWindow - 20K 策略: 调用 LLM 生成对话摘要 目标: 保留关键信息,丢弃冗余 熔断: 连续 3 次失败后停止 保护: 最近的 N 条消息不压缩 // 关键常量 AUTOCOMPACT_BUFFER_TOKENS = 13_000 WARNING_THRESHOLD_BUFFER_TOKENS = 20_000 MAX_CONSECUTIVE_FAILURES = 3 L3: SessionMemoryCompact(会话级) 触发: 会话结束或跨会话 策略: 提取关键信息到持久化记忆 目标: 跨会话知识保持 存储: memdir/ 目录下的 markdown 文件

6.2 上下文构建

// context.ts — 系统提示构建
async function getSystemContext(): Promise<string> {
  // 并行收集各类上下文
  const [gitStatus, osInfo, claudeMds] = await Promise.all([
    getGitStatus(),        // Git 状态
    getPlatformInfo(),     // OS 信息、Shell 类型
    getClaudeMds(),        // CLAUDE.md 文件
  ])

  return [
    `<SystemInfo>${osInfo}</SystemInfo>`,
    gitStatus ? `<GitStatus>${gitStatus}</GitStatus>` : '',
    // 工具定义由 QueryEngine 自动注入
  ].filter(Boolean).join('\n')
}

// 工具定义的 XML 化
// 每个工具的定义被转换成 LLM 可读的 XML 格式
//
// <tool_description>
// <tool_name>Bash</tool_name>
// <description>Execute shell commands</description>
// <parameter>
//   <name>command</name>
//   <type>string</type>
//   <required>true</required>
//   <description>The command to execute</description>
// </parameter>
// ...

// 全局缓存断裂点 — 工具定义在系统提示中的位置
// claude_code_system_cache_policy 确保改动后不产生大范围缓存失效

6.3 记忆系统(memdir)

Claude Code 使用目录化记忆:

// memdir/ — 持久化记忆目录
memdir/
├── paths.ts        ← 记忆文件路径管理
├── memdir.ts       ← 加载 / 存储记忆
├── item.ts         ← 记忆项类型
└── ...

// 记忆自动提取
services/
└── extractMemories/
    └── ...  ← 在会话结束后自动提取关键信息并写入记忆

// 记忆加载
async function loadMemoryPrompt(): Promise<string> {
  // 读取 memdir/ 下的所有记忆文件
  // 去重 + 排序
  // 拼接到系统提示中
}

// CLAUDE.md 文件
// 项目级别的记忆,位于项目根目录
// 用户手动维护或 Agent 自动更新
⚠️ 关键工程决策:
  • 熔断机制 — AutoCompact 连续 3 次失败后停止,防止无限重试浪费 API
  • 缓存断裂点 — 工具定义在系统提示中放在固定位置,利用 prompt caching 减少重复传输
  • 懒加载上下文 — Git 状态、CLAUDE.md 等在用到时才获取(通过 memoize 缓存)
  • 分级压缩 — 微压缩不调用 LLM(只做文本替换),自动压缩才消耗 API

7. 第六阶段:UI 与交互设计(REPL & UI)

终端 UI 不等于简陋。Claude Code 证明了 React + Ink 可以在终端中构建复杂的交互式界面。

7.1 架构:React 组件树 → 终端输出

React 组件树 (Virtual DOM)
  │
  ├─ Ink Reconciler (自定义)
  │     └─ 将 React Fiber 映射到终端节点
  │
  ├─ Yoga 布局引擎
  │     └─ Flexbox 在终端中的布局计算
  │
  └─ Ink Renderer
        └─ 输出 ANSI 转义序列到终端

层级:
  App.tsx (根)
    └─ REPL.tsx (交互主屏)
          ├─ VirtualMessageList.tsx (虚拟滚动)
          ├─ TextInput.tsx (输入框)
          ├─ VimTextInput.tsx (Vim 模式)
          ├─ PermissionDialog
          ├─ HelpV2.tsx (帮助面板)
          └─ ... 140+ 组件

7.2 关键 UI 组件

你的 Agent 至少需要这些 UI 能力:

// 1. 消息列表 — 支持虚拟滚动
// 架构: 只渲染可见区域的消息,其他只保留占位符
// 参考: VirtualMessageList.tsx

// 2. 消息渲染 — 按类型分组件
type MessageRenderer =
  | AssistantTextMessage   ← 纯文本回复
  | AssistantThinking      ← LLM 思考过程(可折叠)
  | ToolUseMessage        ← 工具调用(显示工具名 + 参数)
  | ToolResultMessage     ← 工具结果(截断显示)
  | ProgressMessage       ← 进度(Bash 执行中、文件上传中)

// 3. 权限对话框
// 显示工具名、参数预览、允许/拒绝按钮
// 超时后自动拒绝

// 4. 模糊搜索选择器 (FuzzyPicker)
// 用于 /mcp、/agents、/resume 等选择场景
// ⌕ 实时过滤 + 键盘导航

// 5. Diff 视图
// 文件变更的前后对比

7.3 终端优化的关键考量

🎯 终端 UI 设计原则:
  • 永远异步不阻塞 — 终端 I/O 是同步的(ANSI 转义序列),必须用 async/await 包装
  • 增量渲染 — LLM 流式输出时是逐个 token 显示的,不是一大段
  • 光标管理 — 仔细控制光标位置,显示 Spinner 时不影响内容输出
  • 色彩主题 — 支持 light/dark 主题,支持 256 色和 true color
  • 布局 — 使用 Yoga 或 similar 的 flexbox 布局引擎

7.4 最小 REPL 实现

// 最小 REPL 循环
async function replLoop() {
  while (true) {
    // 1. 获取用户输入
    const userInput = await readLine()

    // 2. 检查 Slash 命令
    if (userInput.startsWith('/')) {
      await executeCommand(userInput)
      continue
    }

    // 3. 构建上下文
    const messages = buildContext()
    messages.push({ role: 'user', content: userInput })

    // 4. 运行 Agent Loop
    const result = await agentLoop.query({ messages })

    // 5. 显示结果(流式)
    for (const event of result.events) {
      renderEvent(event)
    }
  }
}

7.5 对话历史可视化(Context View)

Claude Code 的 /context 命令非常实用——它展示当前上下文的组成:

/context
────────────────────────────────
📋 Token 使用:
  ● 系统提示:    24,531 tokens
  ● 对话历史:    78,243 tokens
  ● 工具结果:    15,879 tokens
  ● 总计:      118,653 / 200,000 (59%)

📎 附件:
  ● CLAUDE.md            (2,341 tokens)
  ● memory/default.md    (1,028 tokens)

📌 注意:
  ● 缓存命中: 7,834 tokens 节约
  ● 自动压缩: 已就绪 (约 20K tokens 后触发)

8. 第七阶段:多 Agent 协作(Agent Swarms)

当单个 Agent 不足以高效完成任务时,需要多 Agent 协作。Claude Code 设计了一套优雅的机制。

8.1 三层 Agent 架构

多 Agent 协作架构 Coordinator(协调者) ├─ 持有: Agent | TaskStop | SendMessage ├─ 职责: 拆分任务、分配 Worker、汇总结果 └─ 不执行: Bash / FileEdit / FileRead Worker 1 Worker 2 Worker 3 ├─ Bash ├─ Bash ├─ Bash ├─ FileEdit ├─ FileRead ├─ Glob └─ FileWrite └─ Grep └─ WebFetch 通信: SendMessageTool ←→ Agent 间消息传递 团队: TeamCreateTool / TeamDeleteTool

8.2 核心实现机制

// AgentTool — 子 Agent 生成
// 当 LLM 调用 AgentTool 时,创建一个新的 Agent 会话

// forkSubagent.ts — 子 Agent 创建
async function createSubagent(params: {
  prompt: string       // 给子 Agent 的任务描述
  tools?: string[]     // 允许的工具列表
  parentContext: ToolUseContext
}): Promise<AgentResult> {

  // 1. 创建隔离上下文
  const childContext = createSubagentContext({
    ...parentContext,
    // 独立的中止控制器
    abortController: new AbortController(),
    // 共享基础设施状态(任务注册等)
    setAppStateForTasks: parentContext.setAppStateForTasks,
    // 独立的文件缓存
    fileStateCache: cloneFileStateCache(parentContext, MAX_SIZE),
  })

  // 2. 过滤工具(子 Agent 只能使用部分工具)
  childContext.options.tools = filterToolsForAgent(
    childContext.options.tools,
    params.tools  // 允许的工具列表
  )

  // 3. 执行
  return await queryEngine.query(childContext)
}

// coordinatorMode.ts — 协调者模式
function isCoordinatorMode(): boolean {
  // 环境变量控制
  return process.env.CLAUDE_CODE_COORDINATOR_MODE === 'true'
}

function filterToolsForCoordinator(tools: Tools): Tools {
  // 协调者只持有:
  // - AgentTool(生成 Worker)
  // - TaskStopTool(停止任务)
  // - SendMessageTool(通信)
  // - SyntheticOutputTool(结构化输出)
  return tools.filter(t => COORDINATOR_ALLOWED_TOOLS.has(t.name))
}

function filterToolsForWorker(tools: Tools): Tools {
  // Worker 不能使用 AgentTool(不能继续分裂)
  return tools.filter(t => WORKER_ALLOWED_TOOLS.has(t.name))
}

8.3 Agent 间通信

// SendMessageTool — Agent 间消息传递
// 一个 Agent 可以向另一个 Agent 或所有 Agent 广播消息

// 消息类型
type AgentMessage = {
  target: 'coordinator' | 'worker:id' | 'broadcast'
  content: string
  attachments?: Attachment[]
}

// 通信流程
// Worker 1 ──[SendMessage("找到了 bug 在 file.ts:42 行")]──→ Coordinator
// Coordinator ──[AgentTool("修复这个 bug")]──→ Worker 2
// Worker 2 ──[SendMessage("已修复")]──→ Coordinator

8.4 团队管理

// TeamCreateTool — 创建 Agent 团队
// TeamDeleteTool — 销毁 Agent 团队

// 团队 = 一组 Worker + 一个 Coordinator
// 团队支持并行执行和汇总结果

// 后端支持:
// - tmux:每个 Agent 在独立的 tmux 窗格中运行
// - InProcess:在主进程内运行(适合轻量任务)
// - iTerm:在 iTerm 分屏中运行
💡 实现建议:
  • 不要过早引入多 Agent — 单 Agent 能解决的问题,引入多 Agent 只会增加复杂度
  • 工具隔离是关键 — 子 Agent 必须有独立且受限制的工具集
  • 通信是瓶颈 — Agent 间消息传递的带宽远小于单 Agent 内的上下文
  • 降级策略 — 多 Agent 失败时,优雅降级到单 Agent 模式

8.5 重要补充:MCP 扩展协议(Model Context Protocol)

MCP 是 Anthropic 提出的开放协议,定义了 AI Agent 如何动态发现和调用外部工具。它是 Claude Code 可扩展性的核心。

协议设计

// MCP 的核心思想:Agent 不需要预先知道所有工具
// 外部工具可以作为 MCP Server 注册到 Agent

// 架构:
┌──────────────┐    MCP Protocol    ┌──────────────┐
│              │  ←──────────────→  │  MCP Server  │
│  Agent (主)  │                    │  (外部工具)   │
│              │  ←──────────────→  │              │
│              │    MCP Protocol    │  MCP Server  │
│              │                    │  (数据库)     │
│              │  ←──────────────→  │              │
│              │    MCP Protocol    │  MCP Server  │
│              │                    │  (Slack)     │
└──────────────┘                    └──────────────┘

// MCP 协议定义了 3 种能力:
// 1. Tools — 可调用的工具(函数)
// 2. Resources — 可读取的资源(文件、数据)
// 3. Prompts — 可使用的提示词模板

工具发现与调用

// MCP 工具发现流程

// 1. 连接到 MCP Server
const connection = await mcpClient.connect(serverUrl)

// 2. 获取工具列表
const tools = await connection.listTools()
// 返回:
// [
//   {
//     name: "slack_send_message",
//     description: "Send a message to a Slack channel",
//     inputSchema: {
//       type: "object",
//       properties: {
//         channel: { type: "string" },
//         message: { type: "string" }
//       }
//     }
//   },
//   ...
// ]

// 3. 工具注册到 Agent 的工具池
// assembleToolPool() 会合并内置工具和 MCP 工具
// MCP 工具排序在内置工具之后(prompt cache 稳定性)

// 4. LLM 调用时,工具 Schema 自动注入到系统提示词
// Agent 不需要特殊处理,MCP 工具和内置工具一视同仁

// 5. 调用 MCP 工具
const result = await mcpClient.callTool('slack_send_message', {
  channel: '#general',
  message: 'Hello from Agent!'
})

资源访问

// MCP Resources — 读取外部数据

// 示例:数据库 MCP Server
const resources = await mcpClient.listResources()
// [
//   { uri: "db://users", name: "Users Table" },
//   { uri: "db://orders", name: "Orders Table" }
// ]

// 读取资源
const data = await mcpClient.readResource('db://users')
// 返回:JSON 格式的用户数据

// Agent 可以在系统提示词中描述这些资源
// LLM 就知道可以从哪里获取数据
🎯 MCP 设计原则:
  • 协议标准化 — 工具描述、调用、结果都有统一格式,Agent 不需要为每个工具写适配代码
  • 动态发现 — 工具可以在运行时注册,不需要预先配置
  • 权限隔离 — MCP Server 可以有自己的权限系统,Agent 只能调用被授权的工具
  • 缓存友好 — MCP 工具的 Schema 在系统提示词中位置固定,利于 prompt caching
⚠️ MCP 注意事项:
  • 工具数量控制 — MCP 工具太多会挤占系统提示词空间,建议限制在 20 个以内
  • Schema 质量 — MCP 工具的 description 必须清晰,否则 LLM 会误用
  • 错误处理 — MCP Server 可能不可用,需要超时和降级策略
  • 安全审计 — MCP 工具来自外部,调用前需要额外的安全检查

核心模块五:Bridge/IDE 集成系统(Bridge / IDE Integration)

前面所有模块讨论的都是 Claude Code 作为终端原生 Agent 的内部设计。但在真实开发场景中,开发者大部分时间在 IDE 里工作——VS Code、JetBrains、甚至远程开发环境。Bridge 系统就是 Claude Code 与 IDE 之间的双向通信桥梁,它让 CLI Agent 的全部能力可以无缝嵌入到 IDE 的图形界面中。

架构总览:CLI 与 IDE 的通信模型

Claude Code 的 Bridge 设计遵循一个核心原则:CLI 是大脑,IDE 是皮肤。CLI 进程持有完整的 Agent Loop、工具系统、权限模型;IDE 插件只负责 UI 渲染和用户交互。两者通过 JSON-RPC 协议经由 stdin/stdout 双向通信。

Bridge/IDE 集成架构 ┌─────────────────────────────────────────────────────────────────┐ │ IDE (VS Code / JetBrains) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ Chat Panel │ │ Inline Edit │ │ Permission Dialog │ │ │ │ 对话面板 │ │ 代码内联编辑 │ │ IDE 内权限确认弹窗 │ │ │ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │ │ │ │ │ │ │ └────────────┬────┴──────────────────────┘ │ │ │ │ │ ┌───────▼────────┐ │ │ │ Bridge Client │ │ │ │ (JSON-RPC) │ │ │ │ stdin/stdout │ │ │ └───────┬────────┘ │ └──────────────────────┼──────────────────────────────────────────┘ │ stdin (IDE → CLI) │ stdout (CLI → IDE) │ ┌──────────────────────┼──────────────────────────────────────────┐ │ │ CLI Process (Claude Code) │ │ ┌───────▼────────┐ │ │ │ Bridge Server │ │ │ │ bridgeMain.ts │ │ │ └───────┬────────┘ │ │ │ │ │ ┌────────────┼─────────────┐ │ │ │ │ │ │ │ ┌──────▼──────┐ ┌───▼────┐ ┌─────▼───────┐ │ │ │ Agent Loop │ │ Perms │ │ Session Mgr │ │ │ │ QueryEngine │ │ Model │ │ SessionRun │ │ │ └─────────────┘ └────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘

关键文件清单

Bridge 系统由以下核心文件组成,每个文件负责通信链路中的一个关键环节:

bridge/
├── bridgeMain.ts                 ← Bridge 服务端入口(CLI 侧)
│   启动 JSON-RPC 服务器,监听 stdin/stdout
│   注册所有 RPC 方法(消息发送、权限确认、会话管理)
│   管理 Bridge 生命周期(连接 → 认证 → 通信 → 断开)
│
├── bridgeMessaging.ts            ← 消息传输层
│   实现 JSON-RPC 2.0 协议的序列化/反序列化
│   处理消息分帧(每条消息以换行符分隔)
│   消息路由:按 method 字段分发到对应 handler
│
├── bridgePermissionCallbacks.ts  ← IDE 内权限确认
│   将权限确认请求转发到 IDE 侧(而非终端)
│   IDE 弹出图形化确认对话框
│   支持 "允许一次" / "始终允许" / "拒绝"
│   超时自动拒绝(与终端行为一致)
│
├── replBridge.ts                 ← REPL 与 Bridge 的衔接
│   将 CLI 的 REPL 循环桥接到 IDE
│   消息格式转换:CLI Message ↔ Bridge Message
│   流式事件转发:将 Agent Loop 的 yield 事件实时推送到 IDE
│
├── jwtUtils.ts                   ← JWT 认证工具
│   生成和验证 JWT Token
│   确保只有授权的 IDE 实例可以连接
│   防止恶意进程冒充 IDE 发送指令
│
├── sessionRunner.ts              ← 会话运行器
│   管理 Bridge 会话的完整生命周期
│   创建 → 运行 → 暂停 → 恢复 → 销毁
│   会话隔离:每个 IDE 窗口独立会话
│
├── remoteBridgeCore.ts           ← 远程开发桥接
│   支持 VS Code Remote SSH / JetBrains Gateway
│   处理网络延迟和断线重连
│   转发本地 stdin/stdout 到远程 IDE
│
└── trustedDevice.ts              ← 可信设备管理
    首次连接时的信任确认
    已信任设备列表持久化
    设备指纹识别(防止重放攻击)

JSON-RPC 通信协议

Bridge 使用标准的 JSON-RPC 2.0 协议,通过 stdin/stdout 传输。每条消息是一行 JSON,以换行符 \n 分隔:

// JSON-RPC 2.0 消息格式

// ═══ 请求(IDE → CLI)═══
{
  "jsonrpc": "2.0",
  "method": "sendMessage",        // RPC 方法名
  "params": {
    "content": "帮我重构这个函数",
    "attachments": [
      { "type": "file", "path": "/src/utils.ts" },
      { "type": "selection", "path": "/src/main.ts", "range": [42, 58] }
    ]
  },
  "id": 1                         // 请求 ID(用于匹配响应)
}

// ═══ 响应(CLI → IDE)═══
{
  "jsonrpc": "2.0",
  "result": { "status": "ok", "messageId": "msg_abc123" },
  "id": 1
}

// ═══ 通知(双向,无 id)═══
// CLI → IDE:流式事件推送
{
  "jsonrpc": "2.0",
  "method": "streamEvent",
  "params": {
    "type": "assistant_text",
    "delta": "我来分析一下这个函数的结构..."
  }
}

// CLI → IDE:权限确认请求
{
  "jsonrpc": "2.0",
  "method": "requestPermission",
  "params": {
    "tool": "Bash",
    "input": { "command": "npm install lodash" },
    "description": "安装 lodash 依赖",
    "timeout": 30000
  }
}

权限确认从终端迁移到 IDE

在纯终端模式下,权限确认通过 stdin/stdout 的交互式提示完成(用户按 y/n)。但在 IDE 中,这种交互式提示是不可用的——IDE 的终端面板不支持逐字符读取。Bridge 系统通过 bridgePermissionCallbacks.ts 解决了这个问题:

权限确认:终端 vs IDE 对比 终端模式(直接交互): Agent 执行 BashTool │ ├─ 权限检查 → 需要用户确认 │ ├─ 在终端打印: "允许执行 npm install? (y/n)" │ ├─ 用户按 y → 允许 │ └─ 继续执行 IDE 模式(Bridge 转发): Agent 执行 BashTool │ ├─ 权限检查 → 需要用户确认 │ ├─ Bridge 发送 JSON-RPC 通知: │ { │ "method": "requestPermission", │ "params": { │ "requestId": "perm_7x9k2", │ "tool": "Bash", │ "input": { "command": "npm install lodash" }, │ "description": "安装 npm 依赖", │ "timeout": 30000 │ } │ } │ ├─ IDE 弹出图形化确认框: │ ┌─────────────────────────────────────────┐ │ │ Claude Code 请求执行命令 │ │ │ │ │ │ 工具: Bash │ │ │ 命令: npm install lodash │ │ │ 描述: 安装 npm 依赖 │ │ │ │ │ │ [允许一次] [始终允许] [拒绝] │ │ └─────────────────────────────────────────┘ │ ├─ 用户点击 [允许一次] │ └─ IDE 返回: { "method": "respondPermission", "params": { "requestId": "perm_7x9k2", "allowed": true, "always": false } }
// bridgePermissionCallbacks.ts — 权限桥接实现

class PermissionBridge {
  // 待处理的权限请求队列
  private pendingRequests = new Map<string, {
    resolve: (allowed: boolean) => void
    timeout: NodeJS.Timeout
  }>()

  // 工具系统调用此方法,而非直接读 stdin
  async requestPermission(params: {
    tool: string
    input: unknown
    description: string
    timeout?: number
  }): Promise<boolean> {
    const requestId = `perm_${randomId()}`
    const timeoutMs = params.timeout ?? 30_000

    return new Promise((resolve) => {
      // 设置超时自动拒绝
      const timeout = setTimeout(() => {
        this.pendingRequests.delete(requestId)
        resolve(false)  // 超时 = 拒绝(安全默认)
      }, timeoutMs)

      // 注册到队列
      this.pendingRequests.set(requestId, { resolve, timeout })

      // 通过 Bridge 发送请求到 IDE
      bridgeMessaging.notify('requestPermission', {
        requestId,
        tool: params.tool,
        input: params.input,
        description: params.description,
        timeout: timeoutMs,
      })
    })
  }

  // IDE 返回确认结果时调用
  resolve(requestId: string, allowed: boolean): void {
    const pending = this.pendingRequests.get(requestId)
    if (!pending) return  // 已超时或已处理

    clearTimeout(pending.timeout)
    this.pendingRequests.delete(requestId)
    pending.resolve(allowed)
  }
}
权限桥接的设计要点:
  • 超时安全 — 30 秒无响应自动拒绝,与终端行为一致,防止 Agent 无限等待
  • 三种操作 — "允许一次"(单次)、"始终允许"(同工具+同参数模式免确认)、"拒绝"
  • 请求 ID — 每个权限请求有唯一 ID,支持并发请求(多个工具同时执行时)
  • 透明替换 — 权限检查逻辑不变,只是确认方式从 stdin 变成 IDE 弹窗
  • 降级兼容 — Bridge 断开时自动降级回终端模式

双向消息协议

Bridge 的消息协议是双向的——IDE 和 CLI 都可以主动发送消息,而不只是请求-响应模式:

// 双向消息流全景

═══ IDE → CLI 方向 ═══

sendMessage          → 用户发送对话消息(含附件)
cancelRequest        → 取消当前请求
respondPermission    → 返回权限确认结果
updateContext        → 上下文变更通知(打开新文件、选中代码等)
changeMode           → 切换模式(plan / default / auto)
executeCommand       → 执行斜杠命令(/help, /clear, /compact 等)
updateSettings       → 更新配置(模型、温度、最大 token 等)
resizeTerminal       → 终端面板大小变更(影响换行计算)

═══ CLI → IDE 方向 ═══

streamEvent          → Agent Loop 流式事件(text / thinking / tool_use / tool_result)
requestPermission    → 请求权限确认
stateChanged         → 状态变更(idle / running / waiting_permission)
costUpdate           → 成本更新(token 使用量、费用)
errorOccurred        → 错误通知(API 错误、工具错误等)
sessionCreated       → 新会话创建通知
contextChanged       → 上下文变更通知(文件被修改、CLAUDE.md 更新等)
backgroundTask       → 后台任务通知(任务完成、失败等)
memorySaved          → 记忆保存通知

JWT 认证与安全

Bridge 连接需要经过 JWT(JSON Web Token) 认证,防止恶意进程冒充 IDE 连接到 CLI 进程:

// jwtUtils.ts — JWT 认证流程

// ── 连接建立流程 ──

// Step 1: IDE 插件启动时生成 JWT
// JWT Payload:
// {
//   iss: 'claude-code-vscode',        // 发行者(IDE 标识)
//   sub: 'bridge-connection',          // 主题
//   iat: timestamp,                    // 签发时间
//   exp: timestamp + 5min,             // 过期时间(5 分钟)
//   ide: { name: 'vscode', version: '1.88.0' },
//   machine: { machineId: 'abc123...', pid: 12345 },
//   session: { nonce: 'random-uuid' }  // 防重放随机数
// }

// Step 2: IDE 将 JWT 附加到连接请求
// 通过 CLI 的 --bridge-token 参数或环境变量传递

// Step 3: CLI 验证 JWT
class JWTVerifier {
  private secret: string  // 从系统 Keychain 获取

  verify(token: string): boolean {
    const payload = jwt.decode(token)
    if (!jwt.verify(token, this.secret)) return false
    if (payload.exp < Date.now() / 1000) return false
    const validIssuers = ['claude-code-vscode', 'claude-code-jetbrains']
    if (!validIssuers.includes(payload.iss)) return false
    if (payload.machine.machineId !== getLocalMachineId()) return false
    return true
  }
}

// Step 4: 连接建立后
// - 每条 RPC 消息不需要单独签名(stdin/stdout 是本地管道)
// - 会话过期后需要重新认证
// - IDE 进程退出时连接自动断开
安全注意事项:
  • stdin/stdout 是本地管道 — 只有同一台机器上的进程可以连接,天然有网络隔离
  • JWT 防冒充 — 恶意进程即使知道协议格式,没有正确的签名也无法通过验证
  • 5 分钟过期 — 连接请求必须在 5 分钟内完成验证,防止 token 泄露后的重放
  • 机器指纹绑定 — JWT 绑定到特定机器,不能在不同机器间复用
  • 进程级隔离 — IDE 进程退出后,Bridge 连接立即断开,CLI 回到终端模式

会话管理(sessionRunner.ts)

每个 IDE 窗口(或标签页)对应一个独立的 Bridge 会话。SessionRunner 管理会话的完整生命周期:

// sessionRunner.ts — 会话运行器

class SessionRunner {
  private sessionId: string
  private queryEngine: QueryEngine
  private abortController: AbortController | null = null
  private state: 'idle' | 'running' | 'paused' | 'destroyed' = 'idle'

  constructor(params: {
    model: string
    permissionContext: ToolPermissionContext
    cwd: string
  }) {
    this.sessionId = generateSessionId()
    // 创建独立的 QueryEngine 实例
    // 每个 Bridge 会话有独立的消息历史、权限上下文、文件缓存、Token 预算
    this.queryEngine = new QueryEngine({
      model: params.model,
      permissionContext: params.permissionContext,
      cwd: params.cwd,
      sessionId: this.sessionId,
    })
  }

  // 执行查询(IDE 发送消息时调用)
  async query(content: string, attachments: Attachment[]): Promise<QueryResult> {
    this.state = 'running'
    this.abortController = new AbortController()
    try {
      const userMessage = buildUserMessage(content, attachments)
      return await this.queryEngine.submitMessage(userMessage, {
        abortController: this.abortController,
      })
    } finally {
      this.state = 'idle'
      this.abortController = null
    }
  }

  abort(): void { this.abortController?.abort() }
  pause(): void { if (this.state === 'running') this.state = 'paused' }
  resume(): void { if (this.state === 'paused') this.state = 'running' }
  destroy(): void {
    this.state = 'destroyed'
    this.abort()
    this.queryEngine.cleanup()
  }
}

远程开发桥接

现代 IDE 支持远程开发——VS Code Remote SSH、JetBrains Gateway、GitHub Codespaces。在这些场景中,IDE 前端在本地,但代码和终端运行在远程服务器上:

远程开发场景的 Bridge 架构 本地机器: ┌──────────────────────────────────┐ │ VS Code 前端 (Electron) │ │ ├─ Chat Panel │ │ ├─ Editor │ │ └─ Extension Host │ │ └─ Bridge Client │ │ │ │ │ │ WebSocket / SSH 隧道 └────────────┼─────────────────────┘ │ │ 网络传输(加密) │ ┌────────────┼─────────────────────┐ │ 远程服务器 │ │ │ ▼ │ │ VS Code Server (Node.js) │ │ └─ Bridge Proxy │ │ │ │ │ │ stdin/stdout (本地管道) │ ▼ │ │ Claude Code CLI 进程 │ │ └─ Bridge Server (bridgeMain) │ │ └─ Agent Loop │ └──────────────────────────────────┘
远程桥接的工程挑战:
  • 网络延迟 — 每次 RPC 调用都有网络往返延迟(10-200ms),批量操作时需要合并请求
  • 断线重连 — SSH 连接可能因网络波动断开,需要自动重连且不丢失会话状态
  • 认证链 — 本地 IDE → SSH 认证 → 远程 CLI JWT 认证,多层认证不能互相干扰
  • 终端差异 — 远程终端的 ANSI 支持可能与本地不同,需要适配

完整通信时序图

一次完整对话的 Bridge 通信时序 IDE 侧 CLI 侧 │ │ │ 1. 连接建立 │ │─── connect({ token: JWT }) ─────────→ │ │ │ verify JWT ✓ │ │ check trust ✓ │←── connected({ sessionId }) ─────────│ │ │ │ 2. 用户发送消息 │ │─── sendMessage({ │ │ content: "重构 auth 模块", │ │ attachments: [选中代码, 诊断] │ │ }) ──────────────────────────────→ │ │ │ Agent Loop 开始 │ │ 构建上下文 → 调用 LLM │ │ │ 3. 流式响应 │ │←── streamEvent({ type: "text", │ │ delta: "我来分析..." }) │ (逐 token 推送) │ │ │ 4. 工具调用 │ │←── streamEvent({ type: "tool_use", │ │ tool: "Glob", │ │ input: { pattern: "src/auth/**" }│ │ }) ──────────────────────────────→ │ 执行 Glob │←── streamEvent({ type: "tool_result", │ │ result: ["auth.ts", "types.ts"] │ │ }) ──────────────────────────────→ │ │ │ │ 5. 权限确认(IDE 内弹窗) │ │←── requestPermission({ │ │ tool: "FileEdit", │ │ description: "编辑 auth.ts" │ │ }) ──────────────────────────────→ │ │ [用户点击 "允许一次"] │ │─── respondPermission({ allowed: true })→│ │ │ 执行编辑 │ │ │ 6. 最终回复 │ │←── streamEvent({ type: "text", │ │ delta: "重构完成。主要改动..." │ │ }) ──────────────────────────────→ │ │←── stateChanged({ state: "idle" }) ──│ │ │ │ 7. 成本报告 │ │←── costUpdate({ │ │ inputTokens: 24531, │ │ outputTokens: 1872, │ │ costUSD: 0.12 │ │ }) ──────────────────────────────→ │

你的 Bridge 实现方案

// 最小可行 Bridge 系统

// 1. 协议层:JSON-RPC over stdin/stdout
class SimpleBridge {
  private handlers = new Map<string, Function>()

  constructor() {
    process.stdin.on('data', (chunk) => {
      const lines = chunk.toString().split('\n').filter(Boolean)
      for (const line of lines) {
        const msg = JSON.parse(line)
        this.handleMessage(msg)
      }
    })
  }

  send(method: string, params: unknown) {
    process.stdout.write(
      JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'
    )
  }

  register(method: string, handler: Function) {
    this.handlers.set(method, handler)
  }

  private async handleMessage(msg: JsonRpcMessage) {
    const handler = this.handlers.get(msg.method)
    if (handler) {
      const result = await handler(msg.params)
      if (msg.id !== undefined) {
        process.stdout.write(JSON.stringify({
          jsonrpc: '2.0', result, id: msg.id
        }) + '\n')
      }
    }
  }
}

// 2. 权限桥接:最简实现
class SimplePermissionBridge {
  private bridge: SimpleBridge
  private pending = new Map<string, Function>()

  async confirm(tool: string, input: unknown): Promise<boolean> {
    return new Promise((resolve) => {
      const id = `perm_${Date.now()}`
      this.pending.set(id, resolve)
      this.bridge.send('requestPermission', {
        requestId: id, tool, input, timeout: 30000,
      })
      setTimeout(() => {
        if (this.pending.has(id)) {
          this.pending.delete(id)
          resolve(false)  // 超时拒绝
        }
      }, 30000)
    })
  }

  onResponse(requestId: string, allowed: boolean) {
    const resolve = this.pending.get(requestId)
    if (resolve) { this.pending.delete(requestId); resolve(allowed) }
  }
}

// 3. 会话管理:最简实现
// 每个 IDE 连接 = 一个独立的 AgentLoop 实例
// 消息直接转发到 AgentLoop.query()
// 流式事件通过 bridge.send('streamEvent', ...) 推送
Bridge 系统的核心设计原则:
  • CLI 是大脑,IDE 是皮肤 — 所有逻辑在 CLI 侧,IDE 只做 UI 渲染
  • 协议标准化 — JSON-RPC 2.0 是成熟协议,调试工具丰富,学习成本低
  • stdin/stdout 即管道 — 不需要端口、不需要网络配置、天然进程隔离
  • 权限透明迁移 — 权限检查逻辑不变,只是确认方式从终端交互变成 IDE 弹窗
  • 上下文无损传递 — IDE 的选中代码、诊断信息、工作区状态完整传递给 Agent
  • 优雅降级 — Bridge 断开时自动回退到终端模式,不丢失会话状态
实现 Bridge 系统的常见陷阱:
  • 不要把 Agent Loop 移到 IDE 侧 — IDE 插件的运行环境受限(沙箱、API 限制),CLI 进程更灵活
  • 不要忽略消息分帧 — stdin 是流式的,必须按换行符分割消息,否则 JSON 解析失败
  • 不要忽略超时 — 权限确认必须有超时机制,否则 Agent 可能永远阻塞
  • 不要信任 IDE 的所有输入 — JWT 认证后仍需校验消息格式和参数合法性
  • 不要同步阻塞 stdin — 读取 stdin 必须用异步方式,否则会阻塞 Agent Loop

Bridge 系统清单

核心模块七:Worktree 隔离执行(Worktree Isolation)

当子 Agent 需要执行可能有破坏性的操作(如重构、大规模编辑)时,直接在主工作目录操作有风险——如果 Agent 出错,用户的代码可能被损坏。Claude Code 使用 Git Worktree 为子 Agent 创建隔离的工作副本,所有修改在独立分支上进行,不影响主目录。

Worktree 隔离原理

Worktree 隔离架构 主工作目录(用户正在工作的目录) /home/user/project/ ← master 分支,用户正在编辑 ├── src/ ├── package.json └── ... Worktree 副本(子 Agent 的隔离环境) /home/user/project/.claude/worktrees/feature-x/ ← 新分支 feature-x ├── src/ ← 完整的文件副本(共享 .git) ├── package.json └── ... Git 关系: 主目录 (master) ←── 共享 .git 对象数据库 ──→ worktree (feature-x) 用户修改 ←── 互不影响 ──→ Agent 修改
// EnterWorktreeTool — 创建并进入 worktree

export const EnterWorktreeTool = buildTool({
  name: 'EnterWorktree',
  shouldDefer: true,  // 延迟加载(不常用)
  searchHint: 'create an isolated git worktree and switch into it',

  async call(input) {
    // 1. 检查是否已在 worktree 中
    if (getCurrentWorktreeSession()) {
      throw new Error('Already in a worktree session')
    }

    // 2. 创建 worktree
    //    git worktree add .claude/worktrees/feature-x -b feature-x
    const worktree = await createWorktreeForSession({
      name: input.name,       // 可选名称
      slug: getPlanSlug(),    // 自动生成
    })

    // 3. 切换 CWD 到 worktree
    setCwd(worktree.path)
    setOriginalCwd(getCwd())

    // 4. 清除缓存(文件状态已变)
    clearSystemPromptSections()
    clearMemoryFileCaches()

    // 5. 保存 worktree 状态(用于恢复)
    saveWorktreeState({
      path: worktree.path,
      branch: worktree.branch,
      sessionId: getSessionId(),
    })

    return {
      worktreePath: worktree.path,
      worktreeBranch: worktree.branch,
      message: `Switched to worktree: ${worktree.path}`,
    }
  },
})

// ExitWorktreeTool — 退出并清理 worktree
export const ExitWorktreeTool = buildTool({
  name: 'ExitWorktree',

  async call(input) {
    const session = getCurrentWorktreeSession()
    if (!session) throw new Error('Not in a worktree session')

    if (input.action === 'keep') {
      // 保留 worktree(用户可能稍后回来)
      setCwd(session.originalCwd)
      return { message: 'Worktree kept, returned to original directory' }
    }

    if (input.action === 'remove') {
      // 检查是否有未提交的更改
      if (!input.discard_changes && hasUncommittedChanges(session.path)) {
        throw new Error('Worktree has uncommitted changes. Use discard_changes: true to force.')
      }
      // git worktree remove .claude/worktrees/feature-x
      await removeAgentWorktree(session.path)
      setCwd(session.originalCwd)
      return { message: 'Worktree removed' }
    }
  },
})

AgentTool 的 Worktree 集成

// AgentTool.ts — 子 Agent 的 worktree 隔离

// 当调用 AgentTool 时指定 isolation: "worktree"
await AgentTool.call({
  prompt: "重构 auth 模块,将所有函数重命名",
  subagent_type: "general-purpose",
  isolation: "worktree",  // ← 自动创建 worktree
})

// AgentTool 内部流程:
// 1. 检测 isolation = "worktree"
// 2. 调用 createWorktreeForSession() 创建隔离目录
// 3. 子 Agent 在 worktree 中工作
// 4. 子 Agent 完成后:
//    ├─ 无更改 → 自动清理 worktree
//    └─ 有更改 → 保留 worktree,返回分支名供用户审查
// 5. 用户可以 git merge feature-x 合并更改
Worktree 隔离的使用场景:
  • 大规模重构 — 重命名函数、移动文件、修改目录结构
  • 实验性修改 — "试试这个方案",失败了直接丢弃
  • 并行开发 — 多个子 Agent 各自在独立 worktree 中工作
  • 安全探索 — 子 Agent 可以自由执行 rm/mv,不影响主目录
Worktree 的限制:
  • 仅 Git 仓库 — 非 Git 项目无法使用 worktree
  • 磁盘空间 — 每个 worktree 是完整的工作副本(虽然共享 .git 对象)
  • 需要清理 — 长期不清理会积累大量 worktree
  • 不适用于小修改 — 创建 worktree 的开销对单行编辑来说太大

核心模块八:Fork Subagent 模式(Fork Subagent)

创建子 Agent 时,最大的成本之一是系统提示词的 token 消耗。每次创建新 Agent,都需要重新发送完整的系统提示词(工具定义、上下文、CLAUDE.md 等),这可能消耗数千 token。Claude Code 的 Fork Subagent 模式通过共享父级的已渲染系统提示词,实现了零额外 cache 成本的子 Agent 创建。

传统 Agent vs Fork Agent

传统子 Agent vs Fork 子 Agent 传统子 Agent: 父 Agent │ ├─ 创建子 Agent │ ├─ 重新构建系统提示词(getSystemPrompt()) │ ├─ 重新注入工具 Schema │ ├─ 重新注入上下文(CLAUDE.md、Git 状态等) │ └─ 消耗 ~3000-5000 token(全部是新内容) │ └─ API 调用: [新系统提示词 + 子 Agent 消息] Prompt cache 命中率: 低(系统提示词是新的) Fork 子 Agent: 父 Agent │ ├─ Fork 子 Agent │ ├─ 直接复用父级的 renderedSystemPrompt(已渲染的字节) │ ├─ 工具定义完全相同(tools: ['*']) │ ├─ 消耗 0 额外 token(系统提示词部分完全复用) │ └─ 只需发送子 Agent 的新消息 │ └─ API 调用: [父级系统提示词(cache 命中)+ 子 Agent 消息] Prompt cache 命中率: 高(系统提示词字节完全相同)

Fork Agent 定义

// forkSubagent.ts — Fork Agent 定义

export const FORK_AGENT = {
  agentType: 'fork',
  whenToUse: 'Implicit fork — inherits full conversation context',
  tools: ['*'],           // ← 继承父级的完整工具池
  maxTurns: 200,
  model: 'inherit',       // ← 继承父级的模型
  permissionMode: 'bubble', // ← 权限请求冒泡到父级终端
  source: 'built-in',
  getSystemPrompt: () => '',  // ← 不使用!实际用 renderedSystemPrompt
} satisfies BuiltInAgentDefinition

// 关键:tools: ['*'] + useExactTools
// 子 Agent 拥有和父级完全相同的工具池
// → 系统提示词中的工具定义部分字节完全一致
// → API 的 prompt cache 直接命中

Fork 消息构建

// forkSubagent.ts — 构建 Fork 子 Agent 的消息

function buildForkedMessages(
  parentMessages: Message[],
  forkDirective: string,
): Message[] {
  // 1. 过滤掉 thinking 块(不传给子 Agent)
  // 2. 过滤掉失败的工具调用(只保留成功的)
  // 3. 过滤掉中断消息
  const cleanMessages = parentMessages
    .filter(m => m.type !== 'thinking')
    .filter(m => !isInterruptedToolUse(m))
    .filter(m => !isFailedToolResult(m))

  // 4. 添加 fork 指令(用户消息)
  //    包裹在 FORK_BOILERPLATE_TAG 中
  const forkMessage = createUserMessage(
    `${FORK_DIRECTIVE_PREFIX}\n${forkDirective}\n${FORK_BOILERPLATE_TAG}`
  )

  // 5. 返回:父级消息 + fork 指令
  //    子 Agent 看到的是父级的完整上下文 + 新指令
  return [...cleanMessages, forkMessage]
}

// 效果:
// - 子 Agent 看到父级的完整对话历史(上下文不丢失)
// - 系统提示词完全相同(cache 命中)
// - 只增加了 fork 指令的消息(几百 token)

递归 Fork 保护

// 防止无限递归 fork

export function isInForkChild(messages: Message[]): boolean {
  return messages.some(m => {
    if (m.type !== 'user') return false
    // 检查消息中是否包含 FORK_BOILERPLATE_TAG
    // 如果有,说明当前 Agent 本身就是 fork 出来的
    return m.message.content.includes(FORK_BOILERPLATE_TAG)
  })
}

// Fork Agent 调用时的检查:
// if (isInForkChild(parentMessages)) {
//   // 当前 Agent 已经是 fork 子 Agent
//   // 不允许再次 fork(防止无限递归)
//   throw new Error('Cannot fork from a fork child')
// }

权限冒泡

// Fork Agent 的权限处理:bubble 模式

// permissionMode: 'bubble' 意味着:
// - 子 Agent 不自行处理权限确认
// - 权限请求"冒泡"到父级终端
// - 用户在父级终端看到确认提示
// - 确认结果传回子 Agent

// 流程:
// 1. Fork 子 Agent 调用 BashTool("rm -rf temp/")
// 2. 权限检查 → 需要用户确认
// 3. 子 Agent 发送权限请求到父级
// 4. 父级终端显示: "子 Agent 请求执行: rm -rf temp/ (y/n)"
// 5. 用户确认 → 结果传回子 Agent
// 6. 子 Agent 继续执行
Fork Subagent 的核心优势:
  • 零 cache 成本 — 系统提示词字节完全复用,prompt cache 直接命中
  • 上下文继承 — 子 Agent 看到父级的完整对话历史
  • 工具池一致 — tools: ['*'] 确保工具定义完全相同
  • 权限透明 — bubble 模式让用户在统一终端处理权限
  • 递归保护 — 防止 fork 嵌套导致无限递归
Fork vs 传统 Agent 选择指南:
  • 用 Fork — 需要父级上下文、工具相同、短期任务
  • 用传统 Agent — 需要不同工具集、不同模型、独立上下文
  • 用 Worktree + Agent — 需要隔离的文件系统修改
  • 不要 fork fork — 递归 fork 被显式禁止

核心模块一:记忆管理系统(Memory System)

记忆系统是 Agent 实现跨会话知识保持的核心。Claude Code 设计了一套五层记忆架构,从用户手动管理的指令文件,到系统自动提取的持久化记忆,每一层解决不同的问题。

五层记忆架构

五层记忆架构 L1: CLAUDE.md 指令文件(用户手动管理) ├─ ~/.claude/CLAUDE.md → 用户级全局指令 ├─ .claude/CLAUDE.md → 项目级指令(提交到 git) ├─ .claude/CLAUDE.local.md → 本地指令(不提交 git) └─ .claude/rules/*.md → 条件规则(按文件 glob 匹配) L2: Auto Memory(自动记忆)(系统自动管理) ├─ MEMORY.md → 索引文件(最多 200 行 / 25KB) ├─ user_preferences.md → 用户偏好 ├─ feedback_testing.md → 行为反馈 ├─ project_auth_rewrite.md → 项目动态 └─ reference_linear.md → 外部资源指针 L3: Team Memory(团队记忆)(共享知识库) ├─ team/MEMORY.md → 团队索引 └─ team/*.md → 团队共享记忆文件 L4: Session Memory(会话记忆)(当前会话) ├─ session-memory/ → 会话级笔记文件 └─ 自动提取 + 压缩时注入 L5: Agent Memory(Agent 记忆)(按 Agent 类型隔离) ├─ user scope: ~/.claude/agent-memory/{type}/ ├─ project scope: .claude/agent-memory/{type}/ └─ local scope: .claude/agent-memory-local/{type}/

L1: CLAUDE.md 指令文件

CLAUDE.md 是用户直接控制的"行为基因"。加载优先级从低到高:

// 加载顺序(低 → 高优先级)
1. Managed   /etc/claude-code/CLAUDE.md     ← 组织级全局(所有用户)
2. User      ~/.claude/CLAUDE.md             ← 用户级全局
3. Project   .claude/CLAUDE.md               ← 项目级(提交到 git)
             .claude/rules/*.md              ← 条件规则(按 glob 匹配文件)
4. Local     .claude/CLAUDE.local.md         ← 本地(不提交 git)

// 支持 @include 指令(递归最大 5 层)
// CLAUDE.md 中写:
//   @./rules/typescript.md
//   @~/global-rules/security.md
//   @/absolute/path/to/rules.md

// 条件规则 — 仅对匹配 glob 的文件生效
// .claude/rules/no-console-log.md
// ---
// paths: ["src/**/*.ts", "!src/debug/**"]
// ---
// Do not use console.log, use the logger utility instead.
🎯 设计要点:
  • 分层优先级 — 项目级 > 用户级 > 组织级。项目规则最具体,优先级最高
  • git 友好 — CLAUDE.md 提交到仓库,团队共享;CLAUDE.local.md 不提交,个人定制
  • 条件规则 — 用 glob 匹配文件路径,只对相关文件注入规则,减少噪音
  • 最大字符数 — 所有 CLAUDE.md 合计不超过 40,000 字符

L2: Auto Memory(自动记忆)

这是 Claude Code 最精巧的记忆层——系统自动从对话中提取持久化知识,存储为带 frontmatter 的 markdown 文件。

记忆类型分类(4 种)

// 每个记忆文件都有 frontmatter 元数据
---
name: user-role-data-scientist
description: 用户是数据科学家,当前关注可观测性/日志
type: user                          ← 4 种类型之一
---

用户是数据科学家,当前专注于调查我们的日志基础设施。
对 Python 和 SQL 很熟悉,但第一次接触 TypeScript。
解释前端概念时用后端类比会更有效。

// ─────────────────────────────────────

// 4 种记忆类型:

type MemoryType = 'user' | 'feedback' | 'project' | 'reference'

// user — 用户画像
//   何时保存:了解到用户的角色、偏好、知识水平
//   用途:调整交互风格(资深工程师 vs 初学者)

// feedback — 行为反馈
//   何时保存:用户纠正或确认了某个非显而易见的做法
//   包含:规则本身 + Why(原因) + How to apply(适用场景)
//   示例:
//     规则:集成测试必须连接真实数据库,不要 mock
//     Why:上季度 mock 测试通过但生产迁移失败
//     How to apply:所有涉及数据库的测试

// project — 项目动态
//   何时保存:了解到正在进行的工作、目标、截止日期
//   时效性:变化较快,需要保持更新
//   示例:周四之后冻结所有非关键合并——移动端在切 release 分支

// reference — 外部资源指针
//   何时保存:了解到外部系统中的资源位置
//   示例:pipeline bug 在 Linear 的 INGEST 项目里追踪

MEMORY.md 索引文件

// MEMORY.md 是自动记忆的入口点
// 限制:最多 200 行,25KB
// 格式:每行一条,指向一个记忆文件

// 示例内容:
- [用户偏好 - 名人思维模拟技能](user_preferences.md) — 用户希望安装模拟名人思维模式的技能
- [反馈 - 测试策略](feedback_testing.md) — 集成测试必须用真实数据库
- [项目 - 合并冻结](project_merge_freeze.md) — 周四后冻结非关键合并
- [参考 - Linear 追踪](reference_linear.md) — pipeline bug 在 Linear INGEST 项目

// 超出限制时自动截断,并在末尾添加 WARNING 标记

记忆保存流程(两步法)

// 保存记忆的标准流程:

// Step 1: 写入记忆文件
// 路径: ~/.claude/projects/{sanitized-path}/memory/{filename}.md

// 文件内容 = frontmatter + 正文
---
name: feedback-testing-strategy
description: 集成测试必须连接真实数据库
type: feedback
---

集成测试必须连接真实数据库,不要使用 mock。
**Why:** 上季度 mock 测试全部通过,但生产环境迁移失败。
**How to apply:** 所有涉及数据库操作的测试用例。

// Step 2: 更新 MEMORY.md 索引
// 在 MEMORY.md 中添加一行指向新文件的链接
- [反馈 - 测试策略](feedback_testing.md) — 集成测试必须用真实数据库

// 路径解析:
// autoMemPath = ~/.claude/projects/{sanitized-git-root}/memory/
// 使用 findCanonicalGitRoot() 确保同一仓库的所有 worktree 共享记忆目录

自动记忆提取(extractMemories)

Claude Code 在每次对话结束时自动运行一个后台 Agent 来提取记忆。这个设计非常精巧:

// 自动记忆提取流程

┌─────────────────────────────────────────────────────┐
│              自动记忆提取流程                       │
│                                                      │
│  1. 对话结束(handleStopHooks 触发)                  │
│     └─ 检查是否应该提取(互斥检查)                    │
│                                                      │
│  2. 互斥检查                                         │
│     ├─ 如果主 Agent 已经手动写了记忆文件 → 跳过       │
│     └─ 否则 → 继续                                   │
│                                                      │
│  3. 节流检查                                         │
│     └─ 每 N 轮对话才运行一次(默认每轮)              │
│                                                      │
│  4. 预注入记忆目录清单                                │
│     └─ 提取 Agent 不需要花一轮 ls 才知道有哪些文件    │
│                                                      │
│  5. 运行提取 Agent(forked agent 模式)               │
│     ├─ 共享主对话的 prompt cache(零额外缓存成本)    │
│     ├─ 最多 5 轮                                     │
│     ├─ 权限:只能在 memory/ 目录内写入                │
│     └─ 工具:Read/Grep/Glob + 只读 Bash + Edit/Write │
│                                                      │
│  6. 提取策略(高效 2 轮)                             │
│     ├─ 第 1 轮:并行读取现有记忆文件 + 对话历史       │
│     └─ 第 2 轮:并行写入新/更新的记忆文件             │
│                                                      │
│  7. 完成                                             │
│     ├─ 推进游标(lastMemoryMessageUuid)              │
│     ├─ 记录分析指标(token 数、文件数、耗时)         │
│     └─ 在主对话中注入 memorySavedMessage              │
└─────────────────────────────────────────────────────┘

// 关键设计:Forked Agent 模式
// - 提取 Agent 是主对话的完美分叉,共享 prompt cache
// - 不需要重新发送完整对话历史给 LLM
// - 成本极低(只需处理新增的几轮对话)

// 权限隔离:
function createAutoMemCanUseTool(memoryDir) {
  return (tool, input) => {
    if (['FileRead', 'Grep', 'Glob'].includes(tool)) return 'allow'
    if (tool === 'Bash' && isReadOnlyCommand(input)) return 'allow'
    if (['FileEdit', 'FileWrite'].includes(tool)) {
      return isPathWithinDir(input.path, memoryDir) ? 'allow' : 'deny'
    }
    return 'deny'
  }
}

记忆检索(findRelevantMemories)

不是把所有记忆都塞进系统提示词——而是用一个轻量级 LLM 侧查询来选择最相关的记忆:

// 记忆检索流程

用户发送消息
  │
  ├─ 1. 异步预取(startRelevantMemoryPrefetch)
  │     └─ 在用户输入处理期间就开始搜索,不阻塞主流程
  │
  ├─ 2. 扫描记忆目录(scanMemoryFiles)
  │     ├─ 递归读取所有 .md 文件(排除 MEMORY.md)
  │     ├─ 解析 frontmatter 的前 30 行
  │     ├─ 按修改时间降序排列
  │     └─ 最多 200 个文件
  │
  ├─ 3. Sonnet 侧查询(selectRelevantMemories)
  │     ├─ 输入:用户消息 + 记忆文件清单
  │     ├─ 模型:轻量级 Sonnet(成本低)
  │     ├─ 输出:最多 5 个最相关文件名
  │     └─ 策略:不要选最近已用工具的文档,但要选包含警告/陷阱的记忆
  │
  ├─ 4. 读取选中文件(readMemoriesForSurfacing)
  │     ├─ 每文件最多 200 行 / 4KB
  │     ├─ 超出时截断(不丢弃)
  │     └─ 会话累计限制 60KB
  │
  └─ 5. 注入为附件(relevant_memories attachment)
        ├─ 去重:已在上下文中的不重复注入
        ├─ 追踪:标记 readFileState 防止重复
        └─ 缓存友好:header 预计算,利于 prompt cache
💡 记忆检索的设计亮点:
  • 异步预取 — 用户输入处理期间就开始搜索,不增加延迟
  • 侧查询选择 — 用小模型选择相关记忆,成本低效果好
  • 去重防抖 — 已在上下文中的记忆不重复注入,节省 token
  • 截断不丢弃 — 大文件截断显示,而不是完全丢弃
  • 会话累计限制 — 整个会话最多注入 60KB 记忆,防止溢出

记忆整合(autoDream)

// autoDream — 定期记忆整合
// 当多个会话积累后,自动运行一个整合 Agent

触发条件(按成本从低到高检查):
  1. 时间门控:距上次整合 ≥ 24 小时
  2. 会话门控:自上次整合后有 ≥ 5 个新会话
  3. 锁门控:没有其他整合正在运行

整合流程:
  1. 获取整合锁(防止并发)
  2. 列出自上次整合后触碰过的会话
  3. 构建整合提示(附带会话列表)
  4. 运行 forked agent(共享 prompt cache)
  5. Agent 读取会话日志,提炼主题,更新/合并记忆文件
  6. 成功:完成 dream 任务,记录分析
  7. 失败:回滚锁,记录错误(不通知用户,best-effort)

Session Memory(会话记忆)

// 会话记忆 — 当前会话的结构化笔记
// 自动维护,不跨会话持久化

// 默认模板:
# Session Title
# Current State          ← 当前正在做什么
# Task specification     ← 任务描述
# Files and Functions    ← 涉及的文件和函数
# Workflow               ← 工作流程
# Errors & Corrections   ← 遇到的错误和修正
# Codebase and System Documentation  ← 代码库文档
# Learnings              ← 学到的知识
# Key results            ← 关键结果
# Worklog                ← 工作日志

// 触发条件(三个条件满足任一):
//   (当前 token 数 ≥ 10,000) AND (工具调用 ≥ 3 次)
//   OR
//   (距上次提取增长 ≥ 5,000 tokens) AND (上一轮没有工具调用)

// 提取方式:forked agent,只允许编辑会话记忆文件
// 每个 section 最多 2000 tokens,总计最多 12000 tokens

// 用途:
//   1. 压缩时注入 — AutoCompact 时作为上下文注入摘要
//   2. /summary 命令 — 用户手动查看当前会话笔记
⚠️ 记忆系统的工程决策:
  • 不要存什么 — 代码模式/架构(读代码就行)、git 历史(git log 就行)、调试方案(commit message 里有)、CLAUDE.md 已有内容
  • 记忆会过时 — 使用前必须验证。如果记忆说"文件 X 存在",先检查是否真的存在
  • 互斥机制 — 主 Agent 手动写了记忆 → 后台提取跳过,避免重复
  • 安全隔离 — 提取 Agent 只能写入 memory/ 目录,不能修改其他文件
  • Forked Agent — 共享 prompt cache,成本极低,不重新发送完整对话

你的记忆系统实现方案

// 最小可行记忆系统

// 1. CLAUDE.md 文件(L1)— 用户手动维护
//    最简单:读取项目根目录的 CLAUDE.md,注入系统提示词

// 2. MEMORY.md + 记忆文件(L2)— 两步法
class MemorySystem {
  memoryDir: string       // ~/.agent/projects/{project}/memory/
  indexPath: string       // memoryDir + '/MEMORY.md'

  // 保存记忆
  async save(name, content, type) {
    // Step 1: 写文件
    await writeFile(`${this.memoryDir}/${name}.md`, `---
name: ${name}
type: ${type}
---
${content}`)
    // Step 2: 更新索引
    await appendLine(this(indexPath, `- [${name}](${name}.md)`)
  }

  // 检索记忆(简化版:关键词匹配,不用 LLM)
  async findRelevant(query) {
    const files = await scanDir(this.memoryDir)
    return files
      .filter(f => f.name !== 'MEMORY.md')
      .sort((a, b) => b.mtime - a.mtime)
      .slice(0, 5)  // 最近 5 个
  }

  // 自动提取(会话结束时)
  async extractFromConversation(messages) {
    // 用 forked agent 或直接用小模型提取
    // 检查互斥:如果用户已手动写过,跳过
  }
}

核心模块二:工具调用全链路(Tool Calling Pipeline)

工具调用是 Agent 与外部世界交互的唯一通道。从 LLM 返回 tool_use 块到 tool_result 送回 LLM,中间经过 11 个阶段,每一步都有精心设计的逻辑。

完整调用链路图

工具调用全链路(11 个阶段) LLM 返回 tool_use 块 │ ├─ 阶段 1: 工具查找 │ └─ findToolByName() → 精确匹配 → 降级到别名映射 │ ├─ 阶段 2: 输入验证 │ ├─ Zod Schema 验证 (safeParse) │ └─ 工具自定义验证 (tool.validateInput) │ ├─ 阶段 3: 推测性分类器(仅 Bash) │ └─ 并行启动 bash 安全分类器(不等权限检查) │ ├─ 阶段 4: 输入回填 │ └─ backfillObservableInput() — 添加遗留字段给 hooks │ ├─ 阶段 5: PreToolUse Hooks │ ├─ 执行所有注册的前置钩子 │ ├─ 可以:修改输入、阻止执行、添加上下文 │ └─ 返回:allow / deny / ask / stop │ ├─ 阶段 6: 权限解析 │ ├─ Hook 返回 allow → 检查规则覆盖 │ ├─ Hook 返回 deny → 直接拒绝 │ └─ Hook 返回 ask → 进入权限检查链 │ ├─ 阶段 7: 权限检查链(canUseTool) │ ├─ Step 1a: Deny 规则检查 │ ├─ Step 1b: Ask 规则检查 │ ├─ Step 1c: 工具自定义权限 (checkPermissions) │ ├─ Step 1g: 安全检查(bypass-immune) │ ├─ Step 2a: Bypass 模式 → 直接放行 │ ├─ Step 2b: Always-allow 规则 │ └─ Step 3: 交互式确认 / Auto 模式分类器 │ ├─ 阶段 8: 工具执行 │ └─ tool.call(input, context, onProgress) → ToolResult │ ├─ 阶段 9: 结果处理 │ ├─ mapToolResultToToolResultBlockParam() │ ├─ 大结果持久化到磁盘 → 替换为预览 │ └─ 空结果占位符 │ ├─ 阶段 10: PostToolUse Hooks │ ├─ 可以修改 MCP 输出 │ ├─ 可以阻止继续 │ └─ 可以添加额外上下文 │ └─ 阶段 11: 结果返回 LLM └─ tool_result 消息加入对话历史 → 下一轮循环

阶段 1-2: 工具查找与输入验证

// 工具查找 — 两步降级
function findToolByName(name, tools) {
  // Step 1: 精确匹配
  let tool = tools.find(t => t.name === name)

  // Step 2: 别名映射(兼容旧名)
  if (!tool) {
    const alias = TOOL_ALIASES[name]  // e.g., 'KillShell' → 'TaskStop'
    if (alias) tool = tools.find(t => t.name === alias)
  }

  // Step 3: 兜底到 getAllBaseTools()(可能在延迟工具集中)
  if (!tool) tool = getAllBaseTools().find(t => t.name === name)

  return tool
}

// 输入验证 — 两层
// Layer 1: Zod Schema 验证
const parsed = tool.inputSchema.safeParse(input)
if (!parsed.success) {
  return { is_error: true, content: buildValidationError(parsed.error) }
}

// Layer 2: 工具自定义验证
const customError = await tool.validateInput(parsed.data, context)
if (customError) {
  return { is_error: true, content: customError }
}

阶段 5-6: PreToolUse Hooks 与权限解析

// PreToolUse Hook 的 7 种输出
type PreToolUseHookResult = {
  message?: Message                    // 附加消息
  hookPermissionResult?: 'allow' | 'deny' | 'ask'  // 权限决定
  hookUpdatedInput?: Record  // 修改后的输入
  preventContinuation?: boolean        // 阻止整个轮次继续
  stopReason?: string                  // 停止原因
  additionalContext?: Message[]        // 额外上下文
  stop?: boolean                       // 硬停止,中止工具执行
}

// 权限解析 — Hook 决定与规则系统的交互
function resolveHookPermissionDecision(hookResult, tool, input, context) {
  if (hookResult.hookPermissionResult === 'allow') {
    // Hook 说允许,但规则可能覆盖
    const ruleResult = checkRuleBasedPermissions(tool, input, context)
    if (ruleResult === 'deny' || ruleResult === 'ask') {
      return ruleResult  // 规则优先级高于 Hook
    }
    return 'allow'  // 没有规则反对,接受 Hook 的决定
  }
  if (hookResult.hookPermissionResult === 'deny') {
    return 'deny'  // 直接拒绝
  }
  // Hook 没有决定或返回 ask → 进入标准权限检查
  return canUseTool(tool, input, context)
}

阶段 7: 权限检查链(核心)

// 权限检查的完整决策树
function hasPermissionsToUseToolInner(tool, input, context) {
  // ── Step 1: 规则检查 ──
  // 1a. 整个工具在 deny 列表 → deny
  if (isToolInDenyList(tool.name, context)) return 'deny'

  // 1b. 整个工具在 ask 列表 → ask(除非沙箱 bash)
  if (isToolInAskList(tool.name, context)) return 'ask'

  // 1c. 工具自定义权限检查
  //     例如 BashTool 检查子命令规则
  //     例如 FileTool 检查路径安全性
  const toolResult = tool.checkPermissions(input, context)

  // 1d. 工具返回 deny → deny
  if (toolResult === 'deny') return 'deny'

  // 1e. 需要用户交互 + 工具返回 ask → ask
  if (tool.requiresInteraction && toolResult === 'ask') return 'ask'

  // 1f. 内容级 ask 规则(按参数模式匹配)
  if (hasContentAskRule(tool, input, context)) return 'ask'

  // 1g. 安全检查(bypass 也不能跳过)
  if (isSafetyCheck(tool, input)) return 'ask'

  // ── Step 2: 模式检查 ──
  // 2a. Bypass 模式 → allow
  if (context.mode === 'bypassPermissions') return 'allow'

  // 2b. 整个工具在 allow 列表 → allow
  if (isToolInAllowList(tool.name, context)) return 'allow'

  // ── Step 3: 默认行为 ──
  return 'ask'  // 没有匹配任何规则 → 询问用户
}

// ── Auto 模式分类器 ──
// 当 mode === 'auto' 且结果为 ask 时:
function handleAutoMode(tool, input) {
  // 1. 安全检查可跳过分类器
  if (isClassifierApprovable(tool)) return 'allow'

  // 2. acceptEdits 快速路径
  if (wouldBeAllowedInAcceptEditsMode(tool, input)) return 'allow'

  // 3. 安全工具白名单
  if (isSafeTool(tool)) return 'allow'

  // 4. 运行 AI 分类器(classifyYoloAction)
  const classification = await classifyYoloAction(tool, input)
  if (classification === 'allow') return 'allow'

  // 5. 分类器拒绝 → 追踪拒绝次数
  trackDenial(tool.name)
  if (denialCount >= MAX_DENIALS) return 'deny'  // 连续拒绝自动停止

  // 6. 降级到交互式确认
  return promptUser(tool, input)
}

// ── 交互式确认的 5 路竞争 ──
// 当需要用户确认时,同时启动多个竞争者:
async function handleInteractivePermission(tool, input) {
  const results = await Promise.race([
    waitForUserInteraction(),         // 用户在终端按 y/n
    waitForPermissionRequestHooks(),  // 自定义 hook 脚本
    waitForBashClassifier(),          // Bash 安全分类器(2秒超时)
    waitForBridgePermission(),        // 远程 IDE 权限
    waitForChannelPermission(),       // Telegram/iMessage 等渠道
  ])
  // 第一个返回的结果生效(claim() 原子操作)
}

阶段 8: 工具执行

// 工具执行 — 权限通过后
async function executeTool(tool, input, context, onProgress) {
  // 调用工具的 call 方法
  const result = await tool.call(input, context, canUseTool, assistantMessage, onProgress)

  // ToolResult 结构:
  return {
    data: string | ContentBlock[],    // 工具输出
    newMessages?: Message[],          // 附加消息
    contextModifier?: ContextModifier,// 修改后续上下文
    mcpMeta?: MCPMeta,                // MCP 元数据
  }
}

// 进度回调 — 长时间运行的工具(如 Bash)
// 每行输出都通过 onProgress 流式显示
// 用户可以实时看到命令输出

阶段 9: 结果处理与预算管理

// 两级结果大小管理

// ── Level 1: 单工具持久化(即时)──
// 每个工具声明 maxResultSizeChars(如 50,000)
function processToolResultBlock(result, toolUseId, tool) {
  if (result.length > tool.maxResultSizeChars) {
    // 大结果持久化到磁盘
    const path = `${projectDir}/${sessionId}/tool-results/${toolUseId}.txt`
    writeFile(path, result)
    // 返回预览
    return `
Output too large (${result.length} chars). Full output saved to: ${path}
Preview (first 2KB):
${result.slice(0, 2048)}...
`
  }
  return result
}

// ── Level 2: 每消息聚合预算(API 调用前)──
// applyToolResultBudget() 在每次 API 调用前运行
function applyToolResultBudget(messages) {
  for (const group of groupToolResultsByMessage(messages)) {
    if (group.totalSize > MAX_TOOL_RESULTS_PER_MESSAGE_CHARS) {
      // 按优先级替换:
      // mustReapply(之前已替换的)→ 保持
      // frozen(之前见过但保留的)→ 保持
      // fresh(新的)→ 按大小降序替换,直到低于预算
      const toReplace = selectLargestFreshResults(group, budget)
      for (const result of toReplace) {
        persistAndReplace(result)  // 持久化 + 替换为预览
      }
    }
  }
}

// 空结果占位符
if (result.length === 0) {
  return `(${toolName} completed with no output)`
}

中断/中止系统

// 分层 AbortController 树

toolUseContext.abortController          ← 顶层(主查询控制器)
  └─ siblingAbortController             ← 兄弟工具控制器
       └─ toolAbortController           ← 单工具控制器

// 中止级联规则:
// 1. Bash 工具错误 → siblingAbortController.abort('sibling_error')
//    → 杀死所有并发的兄弟 Bash 进程

// 2. 用户按 ESC → 主控制器中止
//    → interruptBehavior === 'cancel' 的工具收到合成错误
//    → interruptBehavior === 'block' 的工具继续运行

// 3. 权限对话框拒绝 → toolAbortController 中止
//    → 向上冒泡到主控制器

// 4. Streaming 回退 → streamingToolExecutor.discard()
//    → 所有待处理工具收到合成错误

// 每个工具声明中断行为:
interface Tool {
  interruptBehavior(): 'cancel' | 'block'
  // cancel: 用户中断时停止工具,返回错误结果
  // block: 用户中断时工具继续运行,新消息等待
}
🔒 工具调用的安全底线:
  • 永远不要相信 LLM 的输入 — 所有输入必须经过 Zod Schema 验证
  • 权限规则覆盖 Hook — Hook 说 allow,但 deny 规则仍然生效
  • 安全检查 bypass-immune — 即使在 bypass 模式下,安全检查也不能跳过
  • 结果大小限制 — 大结果必须持久化到磁盘,不能全部塞进上下文
  • 兄弟取消 — 一个 Bash 失败时,自动取消所有并发 Bash

核心模块三:后台任务与持久化(Background Tasks)

后台任务系统让 Agent 可以在不阻塞用户交互的情况下执行长时间运行的操作。Claude Code 设计了 7 种任务类型,每种有不同的执行模型和生命周期。

任务类型全景

// 7 种任务类型
type TaskType =
  | 'local_bash'             // 后台 Shell 命令
  | 'local_agent'            // 本地子 Agent
  | 'remote_agent'           // 远程 Agent(云端执行)
  | 'in_process_teammate'    // 进程内队友(集群模式)
  | 'local_workflow'         // 后台工作流
  | 'monitor_mcp'            // MCP 监控器
  | 'dream'                  // 记忆整合(autoDream)

// 任务状态机
type TaskStatus =
  | 'pending'    → 'running'  → 'completed'
                →             → 'failed'
                →             → 'killed'

// 任务 ID 格式:类型前缀 + 8 位随机 base-36
// 例如: b7x9k2m4p (bash), a3f8n1q5r (agent)

后台任务框架

// 框架层核心函数

// 1. 注册任务
function registerTask(task, setAppState) {
  // 插入 AppState.tasks
  // 如果是恢复(resume),携带保留的状态
  // 发出 task_started SDK 事件

  // 状态结构:
  {
    id: string,
    type: TaskType,
    status: TaskStatus,
    description: string,
    startTime: number,
    outputFile: string,     // 输出文件路径
    outputOffset: number,   // 已读取的输出偏移
    notified: boolean,      // 防止重复通知
  }
}

// 2. 轮询任务(每 1 秒)
function pollTasks(getAppState, setAppState) {
  for (const task of getAllTasks()) {
    if (task.status === 'running') {
      // 从磁盘读取新的输出增量
      const delta = getTaskOutputDelta(task.outputFile, task.outputOffset)
      if (delta) {
        // 更新偏移,生成附件
        updateTaskOffset(task.id, newOffset)
        generateAttachment(task, delta)
      }
    }
    if (isTerminal(task) && task.notified) {
      // 已完成且已通知 → 标记为可驱逐
      evictTerminalTask(task.id)
    }
  }
}

// 3. 停止任务
async function stopTask(taskId, context) {
  const task = getTask(taskId)
  if (task.status !== 'running') return { error: 'not running' }

  // 根据类型分发到对应的 kill 方法
  const impl = getTaskByType(task.type)
  await impl.kill(taskId, setAppState)

  // 更新状态为 killed
  updateTaskStatus(taskId, 'killed')
  emitTaskTerminatedSdk(taskId)
}

Local Shell Task(后台 Shell)

// 后台 Shell 命令的完整生命周期

// 创建方式 1:BashTool 参数
// { command: "npm test", run_in_background: true }

// 创建方式 2:用户按 Ctrl+B(后台化当前前台命令)

// 生命周期:
// ┌──────────┐    ┌──────────┐    ┌──────────┐
// │ register │───→│ background│───→│ running  │
// │ (前台)    │    │ (转后台)  │    │ (输出中) │
// └──────────┘    └──────────┘    └──────────┘
//                                      │
//                              ┌───────┼───────┐
//                              ↓       ↓       ↓
//                         completed  failed  killed

// 停滞看门狗(Stall Watchdog)
// 每 5 秒检查输出文件,如果 45 秒没有增长
// 且尾部看起来像交互式提示((y/n), Continue?)
// → 发送通知建议用户 kill 并用管道输入重跑

// 孤儿清理
// 当 Agent 退出时,自动 kill 它创建的所有后台 Shell
// 并清除该 Agent 的排队通知

Local Agent Task(后台 Agent)

// 后台 Agent 的生命周期

// 创建方式:AgentTool 参数
// { prompt: "重构这个模块", run_in_background: true }

// 状态结构(比 Shell 丰富得多):
{
  agentId: string,
  prompt: string,
  model?: string,
  abortController?: AbortController,
  progress?: AgentProgress,         // 进度追踪
  messages?: Message[],             // 对话历史
  pendingMessages: string[],        // 排队的中途消息
  retain: boolean,                  // UI 正在显示,阻止驱逐
}

// 进度追踪(ProgressTracker)
// 追踪:工具调用次数、输入/输出 token 数、最近活动
// 活动描述:自动解析工具操作为人类可读描述
// 例如:BashTool("npm test") → "运行 npm test"

// 前台/后台切换
// - registerAsyncAgent() → 直接后台
// - registerAgentForeground() → 前台,可选自动后台超时
// - backgroundAgentTask() → 切到后台(通过 background signal)
// - Ctrl+B → 后台化所有前台任务

// 中途消息
// 用户可以在 Agent 运行时发送消息
// 消息加入 pendingMessages 队列
// Agent 当前轮次结束后处理排队消息

Cron 定时任务

// Cron 任务 — 定时触发 Agent 操作

// 创建:
// CronCreateTool({ cron: "*/5 * * * *", prompt: "检查部署状态" })
// → 写入 .claude/scheduled_tasks.json

// 类型:
type CronTask = {
  id: string
  cron: string               // 5 字段标准 cron
  prompt: string             // 触发时执行的提示词
  createdAt: number
  lastFiredAt?: number
  recurring?: boolean        // 默认 true(重复执行)
  durable?: boolean          // 默认 false(仅会话内)
  permanent?: boolean        // 系统逃逸标记(不过期)
  agentId?: string           // 创建者 Agent ID
}

// 持久化策略:
// durable: false → 仅内存,会话结束即消失
// durable: true  → 写入 .claude/scheduled_tasks.json,重启后恢复

// 自动过期:
// recurring 任务在可配置的最大时长后自动删除
// permanent 标记豁免于自动过期

// 限制:
// - 最多 50 个 cron 任务
// - 队友不能创建 durable cron
// - CLAUDE_CODE_DISABLE_CRON 环境变量可禁用整个系统

结构化任务列表(Todo V2)

// 结构化任务列表 — 与后台任务不同的系统
// 用于追踪"要做什么",而非"正在运行什么"

// 4 个工具:
TaskCreateTool  → 创建任务(subject, description, activeForm)
TaskUpdateTool  → 更新任务(status, owner, blocks/blockedBy)
TaskGetTool     → 获取任务详情
TaskListTool    → 列出所有任务

// 状态工作流:
// pending → in_progress → completed
// deleted → 永久移除

// 依赖关系:
// addBlocks: ["2"]    → 任务 1 完成后,任务 2 才能开始
// addBlockedBy: ["1"] → 任务 2 被任务 1 阻塞

// 团队协作:
// - 自动分配 owner
// - 所有权变更时通知新 owner
// - 3+ 任务关闭未验证 → 建议生成验证 Agent

// 持久化:
// 存储在 .claude/ 目录下的 JSON 文件
// 支持文件锁(并发集群 Agent 安全)
// 信号通知(状态变更时通知订阅者)
💡 后台任务的设计亮点:
  • 输出持久化到磁盘 — 最大 5GB,进程崩溃不丢失
  • 增量读取 — 通过 outputOffset 追踪已读位置,只读新内容
  • XML 通知 — 标准格式,包含任务 ID、状态、摘要、输出路径
  • 孤儿清理 — Agent 退出时自动 kill 其创建的所有子任务
  • 停滞看门狗 — 检测交互式提示,主动通知用户
  • 去重通知 — notified 标记防止同一任务多次通知

你的后台任务实现方案

// 最小后台任务系统
class TaskManager {
  tasks = new Map<string, TaskState>()

  // 注册
  register(task: TaskState) {
    this.tasks.set(task.id, task)
    this.startPolling(task)
  }

  // 轮询(1秒间隔)
  private startPolling(task) {
    setInterval(async () => {
      if (task.status !== 'running') return

      const delta = await readOutputDelta(task.outputFile, task.outputOffset)
      if (delta) {
        task.outputOffset += delta.bytes
        this.notify(task, delta)  // 流式通知主对话
      }

      const exitCode = await checkExit(task)
      if (exitCode !== null) {
        task.status = exitCode === 0 ? 'completed' : 'failed'
        task.endTime = Date.now()
        this.notify(task, { summary: `Exit code: ${exitCode}` })
      }
    }, 1000)
  }

  // 停止
  async kill(taskId: string) {
    const task = this.tasks.get(taskId)
    await task.kill()
    task.status = 'killed'
  }

  // 生成通知(XML 格式)
  private notify(task, data) {
    const xml = `
  ${task.id}
  ${task.type}
  ${task.status}
  ${data.summary}
  ${task.outputFile}
`
    enqueueNotification(xml)
  }
}

核心模块四:Agent Loop 深度剖析(完整生命周期)

前面介绍了 Agent Loop 的概念。这里深入到每一行代码的执行流程——从用户输入到最终返回,中间的每一步决策、错误恢复、上下文管理。

完整生命周期:submitMessage() → 完成

QueryEngine.submitMessage() 完整流程 1. 初始化 ├─ 清除技能发现追踪 ├─ 设置 CWD ├─ 包装 canUseTool(拦截拒绝用于 SDK 报告) ├─ 解析模型(用户指定或默认) └─ 解析 Thinking 配置(adaptive / enabled / disabled) 2. 获取系统提示词(并行) ├─ Promise.all([ │ getSystemPrompt(), ← 角色定义 + 行为指南 + 工具 Schema │ getUserContext(), ← CLAUDE.md + 当前日期 │ getSystemContext(), ← Git 状态 + OS 信息 │ ]) 3. 组装系统提示词 ├─ 默认/自定义提示词 ├─ 记忆机制提示词 └─ 附加提示词 4. 处理用户输入 ├─ processUserInput() │ ├─ Slash 命令 → 本地执行,不进入循环 │ ├─ 附件处理(文件、图片) │ └─ 确定 shouldQuery └─ 如果 shouldQuery=false → yield 结果,返回 5. 持久化对话记录 └─ 写入用户消息到磁盘(崩溃恢复用) 6. 进入查询循环(核心) └─ for await (const message of query({...})) { ... } 7. 消息处理(switch on type) ├─ assistant → 更新最后回复 ├─ tool_result → 更新工具结果 ├─ progress → 更新进度显示 ├─ stream_event → 追踪 usage └─ tombstone → 标记已压缩消息

queryLoop() 每次迭代的完整流程

// queryLoop() — while(true) 循环的每次迭代

// ═══════════════════════════════════════════
// Phase 1: Pre-API 设置
// ═══════════════════════════════════════════

// 1.1 工具结果预算(防止一次对话中工具结果太多)
applyToolResultBudget(messages)

// 1.2 快照压缩(feature-gated HISTORY_SNIP)
snipCompactIfNeeded(messages)

// 1.3 微压缩(清理旧工具结果)
microcompact(messages)
// 策略:时间间隔超过阈值 → 清理旧结果为 "[Old tool result content cleared]"

// 1.4 上下文折叠(feature-gated CONTEXT_COLLAPSE)
contextCollapse(messages)

// 1.5 构建完整系统提示词
systemPrompt = appendSystemContext(systemPrompt, systemContext)

// 1.6 自动压缩检查
const threshold = effectiveContextWindow - 13_000  // AUTOCOMPACT_BUFFER_TOKENS
if (tokenCount(messages) > threshold) {
  // 先尝试 Session Memory 压缩(不调用 LLM)
  if (trySessionMemoryCompaction(messages)) {
    // 成功:直接替换消息,不消耗 API
  } else {
    // 回退到完整压缩(调用 LLM 生成摘要)
    compactConversation(messages)
  }
}

// 1.7 阻塞限制检查(auto-compact 关闭时的硬限制)
if (!autoCompactEnabled && tokens > effectiveContextWindow - 3000) {
  yield error("Context window exceeded")
  return { reason: 'blocked' }
}

// ═══════════════════════════════════════════
// Phase 2: API 调用与流式处理
// ═══════════════════════════════════════════

// 2.1 调用 LLM(流式)
for await (const message of callModel(systemPrompt, messages, tools)) {
  // 2.2 yield 每条消息给 UI
  yield message

  // 2.3 处理 assistant 消息
  if (message.type === 'assistant') {
    assistantMessages.push(message)
    // 提取 tool_use 块
    for (const block of message.tool_use_blocks) {
      toolUseBlocks.push(block)
      // 2.4 Streaming 模式:立即开始执行工具
      streamingToolExecutor?.addTool(block, message)
    }
  }

  // 2.5 处理 stream_event(usage 追踪)
  if (message.type === 'stream_event') {
    if (message.event.type === 'message_start') trackUsage(message)
    if (message.event.type === 'message_delta') trackDelta(message)
  }

  // 2.6 错误扣留(不 yield,稍后尝试恢复)
  if (isWithholdableError(message)) {
    withheldErrors.push(message)  // prompt-too-long, max-output-tokens
    continue  // 不 yield 给 UI
  }
}

// ═══════════════════════════════════════════
// Phase 3: 后流式决策树
// ═══════════════════════════════════════════

if (!needsFollowUp) {
  // ── 无工具调用路径 ──

  // 3.1 Prompt-too-long 恢复
  if (hasWithheldError('prompt_too_long')) {
    // 尝试 1: 上下文折叠排水
    if (recoverFromOverflow(messages)) continue
    // 尝试 2: 响应式压缩
    if (tryReactiveCompact(messages)) continue
    // 都失败 → surface 错误
    yield withheldError
  }

  // 3.2 Max-output-tokens 恢复
  if (hasWithheldError('max_output_tokens')) {
    // 尝试 1: 从 8k 升级到 64k
    if (canEscalate) { maxTokens = 64_000; continue }
    // 尝试 2: 多轮恢复(最多 3 次)
    if (recoveryAttempts < 3) {
      messages.push({ role: 'user', content: 'Resume directly...' })
      recoveryAttempts++
      continue
    }
    // 都失败 → surface 错误
    yield withheldError
  }

  // 3.3 Stop hooks
  handleStopHooks(messages)  // 触发记忆提取、autoDream

  // 3.4 Token 预算续接
  if (outputTokens < budget && canContinue) {
    messages.push({ role: 'user', content: 'Continue...' })
    continue
  }

  return { reason: 'completed' }

} else {
  // ── 有工具调用路径 ──

  // 3.5 执行工具
  const results = streamingToolExecutor
    ? streamingToolExecutor.getRemainingResults()
    : runTools(toolUseBlocks, context)

  for (const result of results) {
    yield result
    toolResults.push(result)
  }

  // 3.6 中止检查
  if (abortController.signal.aborted) {
    yield interruptionMessage
    return { reason: 'aborted' }
  }

  // 3.7 获取附件消息(记忆、文件变更通知)
  const attachments = await getAttachmentMessages(messages, context)

  // 3.8 最大轮次检查
  if (turnCount > maxTurns) {
    yield maxTurnsReachedMessage
    return { reason: 'max_turns' }
  }

  // 3.9 继续循环
  state = {
    messages: [...messages, ...assistantMessages, ...toolResults, ...attachments],
    transition: { reason: 'next_turn' }
  }
  continue  // → 回到 Phase 1
}

AsyncGenerator 链式模式

// 整个系统建立在嵌套的 AsyncGenerator 上
// 每个 yield 向上传播,实现流式处理

QueryEngine.submitMessage()    ← async * SDKMessage
  └─ query()                   ← async * StreamEvent | Message
       └─ queryLoop()          ← async * StreamEvent | Message
            └─ callModel()     ← async * StreamEvent | AssistantMessage
                 └─ queryModelWithStreaming()  ← async * StreamEvent
                      └─ withRetry()          ← async * ErrorMessage

// 消费方式:
for await (const message of queryEngine.submitMessage(input)) {
  switch (message.type) {
    case 'assistant': renderAssistant(message); break
    case 'tool_result': renderToolResult(message); break
    case 'progress': renderProgress(message); break
    case 'stream_event': updateUsage(message); break
  }
}

// 优势:
// 1. 流式处理 — 消息产生即消费,不等全部完成
// 2. 内存友好 — 不需要缓存所有消息
// 3. 可取消 — 随时 break 退出循环
// 4. 组合性 — yield* 委托实现层级传播

错误恢复与重试策略

// 重试引擎(withRetry)
const DEFAULT_MAX_RETRIES = 10
const BASE_DELAY_MS = 500

async function* withRetry(apiCall) {
  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    try {
      return yield* apiCall()
    } catch (error) {
      // ── 按错误类型分策略 ──

      // 429 速率限制
      if (error.status === 429) {
        const retryAfter = error.headers['retry-after']
        const delay = retryAfter
          ? parseInt(retryAfter) * 1000
          : BASE_DELAY_MS * Math.pow(2, attempt - 1)  // 指数退避
        const jitter = delay * 0.25 * Math.random()    // 25% 抖动
        await sleep(delay + jitter)
        continue
      }

      // 529 过载
      if (error.status === 529) {
        consecutive529Count++
        if (consecutive529Count >= 3) {
          // 切换到 fallback 模型
          throw new FallbackTriggeredError()
        }
        await sleep(BASE_DELAY_MS * Math.pow(2, attempt))
        continue
      }

      // 401/403 认证错误
      if (error.status === 401 || error.status === 403) {
        await refreshOAuthToken()     // 刷新 OAuth
        clearAWSCredentials()          // 清除云凭证缓存
        recreateClient()               // 重建 API 客户端
        continue
      }

      // ECONNRESET/EPIPE 连接错误
      if (isConnectionError(error)) {
        disableKeepAlive()             // 禁用 keep-alive
        continue
      }

      // 400 上下文溢出
      if (error.status === 400 && isContextOverflow(error)) {
        adjustMaxTokens(error)         // 调整 token 限制
        continue
      }

      // 不可重试错误 → 直接抛出
      throw error
    }
  }
}

// Streaming 回退
// 如果流式 API 失败(超时、代理问题)
// → 回退到非流式 executeNonStreamingRequest()
// → 非流式超时 300s,最多 64K tokens
// → 流式空闲看门狗:90s 无数据 → 中止

上下文窗口管理全景

// 8 种上下文管理机制协同工作

┌─────────────────────────────────────────────────────┐
│              上下文窗口管理                         │
│                                                      │
│  Pre-API(每次循环迭代前)                          │
│  ├─ 1. 工具结果预算    限制每消息工具结果总量        │
│  ├─ 2. 快照压缩        移除旧消息,保留尾部          │
│  ├─ 3. 微压缩          清理旧工具结果为占位符        │
│  ├─ 4. 上下文折叠      投影折叠视图                  │
│  ├─ 5. 自动压缩        LLM 生成对话摘要              │
│  ├─ 6. Session Memory  用提取的笔记替换旧消息        │
│  └─ 7. 阻塞限制        硬停止(auto-compact 关闭时) │
│                                                      │
│  Post-API(API 调用后)                             │
│  └─ 8. 响应式压缩      413 错误时触发摘要重试        │
│                                                      │
│  压缩后恢复                                         │
│  └─ 重新注入最近读取的 5 个文件(50K token 预算)    │
│     确保压缩后 Agent 仍保有工作上下文                │
└─────────────────────────────────────────────────────┘

// 关键常量:
AUTOCOMPACT_BUFFER_TOKENS = 13_000     // 距窗口顶部的缓冲
WARNING_THRESHOLD_BUFFER_TOKENS = 20_000  // 警告阈值
MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3  // 熔断次数
MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3     // max_tokens 恢复次数
ESCALATED_MAX_TOKENS = 64_000            // 升级后的 token 上限
🎯 Agent Loop 的核心设计原则:
  • while(true) 循环 + 状态传递 — 每次迭代携带完整的 mutable State
  • AsyncGenerator 链 — 流式处理,消息产生即消费
  • 错误扣留 — prompt-too-long 等错误不立即暴露,先尝试恢复
  • 熔断机制 — 自动压缩连续 3 次失败后停止,防止无限重试
  • Fallback 模型 — 529 过载时自动切换到备用模型
  • 压缩后恢复 — 压缩后重新注入最近文件,保持工作上下文
  • 每轮持久化 — 每次 API 调用前保存 checkpoint,支持崩溃恢复

核心模块七:设置分层合并系统(Settings Layering)

一个生产级 Agent 需要从多个来源读取配置——用户全局设置、项目级设置、企业策略、CLI 参数等。Claude Code 设计了一套5 层设置合并机制,使用 lodash 的 mergeWith 进行深度合并,并遵循deny 覆盖 allow的安全语义。

5 层设置来源

设置分层合并(从低到高优先级) Layer 1: userSettings ← ~/.claude/settings.json(用户全局) │ ▼ mergeWith 深度合并 Layer 2: projectSettings ← .claude/settings.json(项目级,可提交到 Git) │ ▼ mergeWith 深度合并 Layer 3: localSettings ← .claude/settings.local.json(本地,gitignore) │ ▼ mergeWith 深度合并 Layer 4: flagSettings ← --settings CLI 参数(命令行覆盖) │ ▼ mergeWith 深度合并 Layer 5: policySettings ← managed-settings.json / 远程 API(企业策略,最高优先级) │ ▼ 最终生效设置
// settings.ts — 5 层设置来源定义

export const SETTING_SOURCES = [
  'userSettings',      // 用户全局 (~/.claude/settings.json)
  'projectSettings',   // 项目共享 (.claude/settings.json)
  'localSettings',     // 本地覆盖 (.claude/settings.local.json, gitignore)
  'flagSettings',      // CLI --settings 参数
  'policySettings',    // 企业策略 (managed-settings.json 或远程 API)
] as const

// 合并逻辑:按顺序逐层 mergeWith
function mergeAllSettings(): SettingsJson {
  let merged: SettingsJson = {}

  for (const source of SETTING_SOURCES) {
    const settings = loadSettingsForSource(source)
    if (settings) {
      merged = mergeWith(merged, settings, settingsMergeCustomizer)
    }
  }

  return merged
}

深度合并与自定义规则

设置合并使用 lodash 的 mergeWith,但加了自定义合并器 settingsMergeCustomizer:

// settingsMergeCustomizer — 自定义合并规则

function settingsMergeCustomizer(objValue: unknown, srcValue: unknown,
  key: string, object: unknown, source: unknown, stack: unknown
): unknown {
  // 1. 数组:直接替换(不合并)
  //    例: permissions.allow = ["Bash"] 覆盖 ["Bash", "Read"]
  if (Array.isArray(srcValue)) {
    return srcValue
  }

  // 2. 普通对象:递归合并(默认行为)
  //    例: env 变量逐层合并
  if (isPlainObject(srcValue) && isPlainObject(objValue)) {
    return undefined  // 让 lodash 默认递归合并
  }

  // 3. 基本类型:直接覆盖
  //    例: model = "claude-sonnet-4-6" 覆盖 "claude-haiku-4-5"
  return srcValue
}

// 特殊处理:policySettings(企业策略)
// 企业策略使用 "first source wins" 语义
// 即策略中定义的值不可被更低层覆盖
function mergePolicySettings(policy: SettingsJson, lower: SettingsJson): SettingsJson {
  return mergeWith({}, lower, policy, (objValue, srcValue, key) => {
    // 策略值优先,不被覆盖
    if (srcValue !== undefined) return srcValue
    return objValue
  })
}
数组替换 vs 对象合并的设计选择:
  • 数组直接替换 — 权限规则列表(allow/deny)不能跨层合并,否则会出现"项目允许 Bash + 用户允许 Read = 两个都允许"的意外行为
  • 对象递归合并 — 环境变量(env)等配置需要逐层叠加,每层只覆盖自己关心的键
  • 基本类型覆盖 — model、temperature 等标量值,高层直接覆盖低层

deny-override-allow 安全语义

权限规则的合并遵循一个关键安全原则:deny 永远优先于 allow。无论 allow 在哪一层定义,只要任何一层有 deny 规则匹配,就拒绝执行。

// 权限规则合并后的评估逻辑

function evaluatePermission(
  mergedSettings: SettingsJson,
  tool: string,
  input: unknown
): 'allow' | 'deny' | 'ask' {

  const rules = mergedSettings.permissions ?? {}
  const allowRules = rules.allow ?? []
  const denyRules = rules.deny ?? []

  // 1. 先检查 deny — 任何一层的 deny 都生效
  for (const rule of denyRules) {
    if (matchesRule(rule, tool, input)) {
      return 'deny'  // 一票否决
    }
  }

  // 2. 再检查 allow
  for (const rule of allowRules) {
    if (matchesRule(rule, tool, input)) {
      return 'allow'
    }
  }

  // 3. 都不匹配 → 询问用户
  return 'ask'
}

// 示例:
// userSettings:    { permissions: { allow: ["Bash(npm *)"] } }
// projectSettings: { permissions: { deny:  ["Bash(rm *)"] } }
// 合并后:
//   allow: ["Bash(npm *)"]  +  deny: ["Bash(rm *)"]
//   → npm install 允许, rm -rf 拒绝, git status 询问用户
安全关键:deny 是跨层传播的。

企业策略(policySettings)中的 deny 规则不可被项目或用户设置覆盖。即使用户在自己的 settings.json 中 allow 了某个操作,如果企业策略 deny 了它,仍然会被拒绝。这是"纵深防御"的体现。

Zod Schema 验证

每个设置源加载后都会经过 Zod Schema 验证,确保类型安全:

// types.ts — Settings Schema 定义(简化版)

const PermissionRuleSchema = z.object({
  tool: z.string(),
  pattern: z.string().optional(),      // Bash 命令模式
  action: z.enum(['allow', 'deny']),
  scope: z.enum(['user', 'project', 'policy']).optional(),
})

const SettingsSchema = z.object({
  // 模型配置
  model: z.string().optional(),
  temperature: z.number().min(0).max(1).optional(),
  maxTokens: z.number().positive().optional(),

  // 权限配置
  permissions: z.object({
    allow: z.array(z.union([z.string(), PermissionRuleSchema])).optional(),
    deny: z.array(z.union([z.string(), PermissionRuleSchema])).optional(),
  }).optional(),

  // 环境变量
  env: z.record(z.string(), z.string()).optional(),

  // Hooks
  hooks: z.record(z.string(), z.array(HookSchema)).optional(),

  // Feature flags
  features: z.record(z.string(), z.boolean()).optional(),
})

// 验证失败时:
// - 记录错误但不阻止启动(graceful degradation)
// - 忽略无效字段,保留有效字段
// - 在 /doctor 命令中显示验证错误
设置系统设计要点:
  • 分层合并 — 5 层来源,逐层 mergeWith,高层覆盖低层
  • 数组替换 — 权限规则不跨层合并,防止意外叠加
  • deny 优先 — 任何层的 deny 都否决所有层的 allow
  • Schema 验证 — Zod 确保类型安全,无效配置 graceful degradation
  • 缓存 — 设置加载后缓存,避免重复磁盘 I/O
  • 热更新 — 文件变更时自动重载(通过 fs.watch)

核心模块八:推测性执行(Speculation)

当 Agent 需要执行一个写入操作(如编辑文件)并等待用户确认时,通常会阻塞等待。Claude Code 的推测性执行引擎在等待确认期间,预先执行只读工具(如 Glob、Grep、Read),将结果缓存起来。如果用户批准,结果立即可用;如果拒绝,结果被丢弃。这大幅减少了用户感知的延迟。

推测性执行流程

推测性执行时序 正常流程(无推测): Agent 调用 FileEdit → 等待用户确认 (10s) → 执行 → 调用 Glob → 执行 → 调用 Read → 执行 总耗时: 10s + 0.1s + 0.1s + 0.1s = 10.3s 推测性流程: Agent 调用 FileEdit → 发送确认请求给用户 │ │ 同时(推测性执行): ├─ 推测: LLM 可能接下来调用 Glob → 预执行 Glob ✓ ├─ 推测: LLM 可能接下来调用 Read → 预执行 Read ✓ │ 用户确认 (10s 后) ──┘ → FileEdit 执行 → Glob 结果直接从缓存返回 (0ms) → Read 结果直接从缓存返回 (0ms) 总耗时: 10s + 0.1s + 0ms + 0ms = 10.1s 用户感知延迟从 10.3s 降到 10.1s

工具安全分类

推测性执行只允许安全的只读工具,绝不允许写入操作:

// speculation.ts — 工具安全分类

// 安全的只读工具 — 可以推测性执行
const SAFE_READ_ONLY_TOOLS = new Set([
  'Read',        // 文件读取(不修改文件)
  'Glob',        // 文件模式匹配(只遍历目录)
  'Grep',        // 内容搜索(只读)
  'ToolSearch',  // 工具搜索(不执行工具)
  'LSP',         // 语言服务查询(只读)
  'TaskGet',     // 任务查询
  'TaskList',    // 任务列表
])

// 写入工具 — 绝不推测性执行
const WRITE_TOOLS = new Set([
  'Edit',         // 文件编辑
  'Write',        // 文件写入
  'NotebookEdit', // Notebook 编辑
])

// Bash — 特殊处理
// 检查命令是否为只读(readOnlyValidation.ts)
// 只读命令如 ls、cat、git status → 可推测
// 写入命令如 rm、mv、npm install → 不可推测

Copy-on-Write 隔离文件系统

推测性执行的工具可能读取文件,而这些文件可能在用户确认后被主 Agent 修改。为避免脏读,Claude Code 使用了Copy-on-Write (COW) 隔离:

// 推测性执行使用隔离的 overlay 文件系统

// 1. 创建 overlay 目录
const overlayPath = join(getClaudeTempDir(), 'speculation', String(process.pid), speculationId)
await mkdir(overlayPath, { recursive: true })

// 2. 文件读取时,先检查 overlay
async function readWithOverlay(path: string): Promise<string> {
  // 如果 overlay 中有这个文件(之前推测性写入的),读 overlay
  const overlayFile = join(overlayPath, relative(cwd, path))
  if (existsSync(overlayFile)) {
    return readFile(overlayFile, 'utf-8')
  }
  // 否则读真实文件
  return readFile(path, 'utf-8')
}

// 3. 推测性写入时,写到 overlay
async function writeWithOverlay(path: string, content: string): Promise<void> {
  const overlayFile = join(overlayPath, relative(cwd, path))
  await mkdir(dirname(overlayFile), { recursive: true })
  await writeFile(overlayFile, content)
  writtenPaths.add(relative(cwd, path))
}

// 4. 用户批准后,将 overlay 复制到真实目录
async function commitOverlay(overlayPath: string, writtenPaths: Set<string>) {
  for (const rel of writtenPaths) {
    const src = join(overlayPath, rel)
    const dest = join(cwd, rel)
    await mkdir(dirname(dest), { recursive: true })
    await copyFile(src, dest)
  }
}

// 5. 用户拒绝后,删除 overlay
function discardOverlay(overlayPath: string) {
  rm(overlayPath, { recursive: true, force: true })
}

完成边界(Completion Boundary)

推测性执行不能无限进行——需要知道什么时候"足够了"。Claude Code 使用完成边界来决定何时停止推测:

// 完成边界类型
type CompletionBoundary =
  | { type: 'bash'; command: string }      // 遇到 Bash 命令 → 停止
  | { type: 'edit'; filePath: string }      // 遇到文件编辑 → 停止
  | { type: 'denied_tool'; toolName: string; detail: string }  // 遇到拒绝的工具 → 停止
  | { type: 'complete' }                    // 自然完成

// 边界检测逻辑
function detectBoundary(messages: Message[]): CompletionBoundary | null {
  for (const msg of messages) {
    if (msg.type === 'assistant') {
      for (const block of msg.message.content) {
        if (block.type === 'tool_use') {
          // 遇到写入工具 → 停止推测
          if (WRITE_TOOLS.has(block.name)) {
            return { type: 'edit', filePath: block.input.file_path }
          }
          // 遇到 Bash → 检查是否只读
          if (block.name === 'Bash') {
            if (!checkReadOnlyConstraints(block.input.command).isReadOnly) {
              return { type: 'bash', command: block.input.command }
            }
          }
        }
      }
    }
  }
  return null  // 没有边界,继续推测
}
推测性执行的价值:
  • 减少感知延迟 — 用户确认期间"免费"执行后续只读操作
  • 安全隔离 — COW overlay 确保推测性读取不会看到脏数据
  • 边界控制 — 遇到写入操作立即停止,绝不越界
  • 结果丢弃 — 用户拒绝时,overlay 直接删除,无副作用
  • 自动启用 — 只读工具自动进入推测模式,无需用户配置
推测性执行的限制:
  • 仅限只读 — 写入工具绝不推测执行(安全第一)
  • Bash 特殊处理 — 需要命令级只读检查(ls/cat/git status 可以,rm/mv 不行)
  • 资源消耗 — 推测性执行消耗 API token(用于 LLM 推测下一步)
  • 缓存大小 — overlay 文件系统有大小限制(防止磁盘占满)

9. 第八阶段:启动优化与插件系统

9.1 并行预取

Claude Code 最惊艳的优化之一——在模块加载阶段就开始并行 I/O:

// main.tsx — 在所有其他 import 之前
import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';

// 作为模块副作用执行
startMdmRawRead();   // 启动 MDM 子进程(plutil/reg query)
startKeychainPrefetch();  // 启动 Keychain 读取

// ... ~135ms 的模块加载 ...

// 当需要时,结果已经准备好了
await ensureKeychainPrefetchCompleted()
// "零等待"——I/O 在后台已经完成了

设计要点:

9.2 Feature Flag 死代码消除

// Bun 专有:构建时消除死代码
import { feature } from 'bun:bundle'

// 当 feature('PROACTIVE') 为 false 时:
// 整段代码在编译输出中完全不存在
const SleepTool = feature('PROACTIVE')
  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null

// 条件模块加载
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null

// 实际使用的 flag 列表:
// PROACTIVE          — 主动模式
// KAIROS             — 助手模式
// BRIDGE_MODE        — IDE 桥接
// DAEMON             — 守护进程
// VOICE_MODE         — 语音输入
// AGENT_TRIGGERS     — 定时触发器
// COORDINATOR_MODE   — 多 Agent 协调
// WEB_BROWSER_TOOL   — 浏览器控制
// TERMINAL_PANEL     — 终端面板
// MONITOR_TOOL       — 监控工具
🎯 注意:如果你的运行时不支持构建时 feature flag,可以用 动态 import() + 懒加载 替代:
// 运行时懒加载(替代方案)
const SleepTool = await (async () => {
  if (config.isProactiveEnabled) {
    const mod = await import('./tools/SleepTool/SleepTool.js')
    return mod.SleepTool
  }
  return null
})()
但代价是:未使用的代码仍在最终构建产物中。

9.3 懒加载(Lazy Loading)

重型模块通过 require() 或 import() 延迟加载:

// 1. 循环依赖打破
const getTeammateUtils = () =>
  require('./utils/teammate.js') as typeof import('./utils/teammate.js')

// 2. 重型模块延迟加载
const { App } = await import('./components/App.js')
const { REPL } = await import('./screens/REPL.js')

// 3. 功能门控加载
const analytics = await import('./services/analytics/index.js')

9.4 插件系统架构

plugins/
├── bundled/              ← 内置插件
│   └── index.js
├── loader.ts             ← 插件加载器
├── pluginCliCommands.ts  ← 插件 CLI 命令
└── ...

// 插件可以:
// 1. 注册新工具(MCPTool 的实现)
// 2. 注册新命令(Slash 命令扩展)
// 3. 注入钩子(pre-tool-use hooks)
// 4. 修改主题

// 插件生命周期:
// 安装 → 加载 → 激活 → 执行 → 卸载

// 安装来源:
// - npm 包 (openclaw-plugin-xxx)
// - MCP 配置 (.mcp.json)
// - 本地路径

9.5 Skill 系统

skills/
├── bundled/              ← 内置 Skill
│   └── index.js
├── SkillTool.tsx         ← Skill 执行工具
└── ...

// Skill = 可复用工作流
// 通过 SkillTool 执行
// 可以被 LLM 发现和使用(ToolSearchTool)

// Skill 定义方式:
// 1. 在 skills/ 目录下创建 .md 文件
// 2. 描述执行步骤和工具调用
// 3. LLM 读取后按指示执行

10. 第九阶段:安全、隐私与成本控制

10.1 Bash 安全沙箱

Claude Code 的 Bash 安全系统是行业标杆级别的实现:

// bashSecurity.ts — 多层安全防御

// Layer 1: 命令解析
// 使用 tree-sitter 解析命令结构
// 识别管道、子 shell、重定向、后台执行

// Layer 2: 危险模式检测
const COMMAND_SUBSTITUTION_PATTERNS = [
  /\$\(/,     // $() 命令替换 — 常见的 bypass 手法
  /\$\{/,     // ${} 参数替换
  /<\(/,     // <() 进程替换
  />\(/,     // >() 进程替换
  ...

  // 防患于未然
  /<#/,       // PowerShell 注释语法(即使当前不用 PowerShell)
]

// Layer 3: Zsh 特定危险命令黑名单
const ZSH_DANGEROUS_COMMANDS = new Set([
  'zmodload',   // 模块加载 → sysopen/ztcp 等攻击向量
  'emulate',    // -c flag = eval 等价
  'sysopen',    // zsh/system 文件操作绕过
  'ztcp',       // zsh/net/tcp 网络外传
  'zf_rm',      // zsh/files 内置 rm(绕过二进制检查)
  ...
])

// Layer 4: 路径验证(目录穿越防护)
// Layer 5: 命令语义(只读 vs 写操作)
// Layer 6: 沙箱执行(高危命令隔离环境)

// 权限级别:
// 0: 完全允许(只读命令)
// 1: 询问(常规文件操作)
// 2: 危险(破坏性操作)
// 3: 禁止(永远不会允许的操作)

10.2 隐私保护设计

// 遥测安全设计
type AnalyticsMetadata = {
  // 类型表示:显式声明"这不是代码或文件路径"
  // 强制开发者确认不包含敏感信息
}

// 日志过滤
// - 不记录命令参数中的敏感内容
// - 不记录文件路径(仅记录操作类型计数)
// - 不上传代码内容(仅代码统计:行数、类型)

// 会话安全
// - 会话文件仅本地存储
// - OAuth Token 存储在系统 Keychain
// - 远程连接需要用户显式确认

10.3 成本控制体系

// cost-tracker.ts — 全链路成本追踪
type StoredCostState = {
  totalCostUSD: number           // 总费用
  totalAPIDuration: number       // API 耗时
  totalAPIDurationWithoutRetries: number
  totalToolDuration: number      // 工具执行耗时
  totalLinesAdded: number        // 新增行数
  totalLinesRemoved: number      // 删除行数
  modelUsage: Record<string, ModelUsage>  // 按模型统计
}

// 预算控制
// 启动时可设置 --max-budget-usd
// 达到预算上限时,Agent 停止执行新查询

// 按模型成本计算
// 不同模型有不同的输入/输出单价
// Cache 命中/创建也有不同价格

// /cost 命令显示:
// Total: $1.42 | Duration: 3m 42s
// Model: claude-sonnet-4 (42% of cost)
// ├─ Input:    124,832 tokens  ($0.52)
// ├─ Output:    24,183 tokens  ($0.88)
// └─ Cache:     12,340 tokens  ($0.02)
// Lines changed: +312 / -45
🔒 安全是一票否决制:
  • 权限系统不是你写完了再添加的 — 是和工具系统同时设计的
  • Shell 安全是最重要的 — 能执行命令的 Agent 就等于给了攻击者一把钥匙
  • 不要相信 LLM 的参数 — LLM 可能被注入或出现幻觉,所有参数都要校验
  • 成本透明 — 用户永远可以查看当前会话的成本

核心模块九:测试策略(Testing Strategy)

AI Agent 系统的测试比传统软件更复杂——你需要测试确定性逻辑(工具执行、权限检查)和非确定性行为(LLM 响应)。Claude Code 的测试策略分为四层:单元测试 → 集成测试 → 回归测试 → 混沌测试。

测试金字塔

Agent 测试金字塔 ┌─────────────┐ │ 混沌测试 │ ← 少量,验证容错能力 │ API 超时 │ │ 429 限流 │ │ 畸形响应 │ └──────┬──────┘ ┌────────┴────────┐ │ 回归测试 │ ← 中量,Golden Prompts │ 固定输入→预期 │ │ 工具调用序列 │ └───────┬────────┘ ┌───────────┴───────────┐ │ 集成测试 │ ← 较多,真实 API 调用 │ Agent Loop 端到端 │ │ 工具系统集成 │ └───────────┬───────────┘ ┌────────────────┴────────────────┐ │ 单元测试 │ ← 大量,快速反馈 │ 工具逻辑、权限规则、Schema 验证 │ │ 合并逻辑、安全检查、格式化 │ └─────────────────────────────────┘

第一层:单元测试

// 工具单元测试示例

// 1. 测试 BashTool 的只读验证
describe('BashTool readOnlyValidation', () => {
  it('应允许只读命令', () => {
    expect(checkReadOnlyConstraints('ls -la').isReadOnly).toBe(true)
    expect(checkReadOnlyConstraints('cat file.txt').isReadOnly).toBe(true)
    expect(checkReadOnlyConstraints('git status').isReadOnly).toBe(true)
    expect(checkReadOnlyConstraints('grep -r "foo" .').isReadOnly).toBe(true)
  })

  it('应拒绝写入命令', () => {
    expect(checkReadOnlyConstraints('rm -rf /').isReadOnly).toBe(false)
    expect(checkReadOnlyConstraints('mv a b').isReadOnly).toBe(false)
    expect(checkReadOnlyConstraints('npm install').isReadOnly).toBe(false)
    expect(checkReadOnlyConstraints('echo "hi" > file').isReadOnly).toBe(false)
  })

  it('应检测管道中的写入操作', () => {
    expect(checkReadOnlyConstraints('cat file | sort > output').isReadOnly).toBe(false)
    expect(checkReadOnlyConstraints('ls | grep foo').isReadOnly).toBe(true)
  })
})

// 2. 测试设置合并逻辑
describe('Settings merge', () => {
  it('应按层级合并', () => {
    const user = { model: 'claude-haiku-4-5', env: { A: '1' } }
    const project = { model: 'claude-sonnet-4-6' }
    const result = mergeAllSettings([user, project])
    expect(result.model).toBe('claude-sonnet-4-6')  // 项目覆盖用户
    expect(result.env.A).toBe('1')  // 用户的 env 保留
  })

  it('数组应替换而非合并', () => {
    const user = { permissions: { allow: ['Bash'] } }
    const project = { permissions: { allow: ['Read'] } }
    const result = mergeAllSettings([user, project])
    expect(result.permissions.allow).toEqual(['Read'])  // 替换,不是合并
  })

  it('deny 应覆盖 allow', () => {
    const settings = {
      permissions: {
        allow: ['Bash(npm *)'],
        deny: ['Bash(rm *)'],
      }
    }
    expect(evaluatePermission(settings, 'Bash', { command: 'npm install' })).toBe('allow')
    expect(evaluatePermission(settings, 'Bash', { command: 'rm -rf /' })).toBe('deny')
  })
})

// 3. 测试 Zod Schema 验证
describe('Settings validation', () => {
  it('应接受有效配置', () => {
    const result = SettingsSchema.safeParse({ model: 'claude-sonnet-4-6' })
    expect(result.success).toBe(true)
  })

  it('应拒绝无效配置', () => {
    const result = SettingsSchema.safeParse({ temperature: 5.0 })  // 超出范围
    expect(result.success).toBe(false)
  })
})

第二层:集成测试

// Agent Loop 集成测试(需要真实 API)

describe('Agent Loop integration', () => {
  // 使用小模型(Haiku)降低测试成本
  const TEST_MODEL = 'claude-haiku-4-5'

  it('应完成简单的文件读取任务', async () => {
    const agent = new AgentLoop({ model: TEST_MODEL })
    const result = await agent.query({
      messages: [createUserMessage('读取 package.json 的内容')],
      tools: [ReadTool, GlobTool],
    })

    // 验证:Agent 应该调用 Read 或 Glob 工具
    const toolCalls = extractToolCalls(result.messages)
    expect(toolCalls.length).toBeGreaterThan(0)
    expect(['Read', 'Glob']).toContain(toolCalls[0].name)
  }, 30_000)  // 30 秒超时

  it('应在权限拒绝后停止', async () => {
    const agent = new AgentLoop({
      model: TEST_MODEL,
      permissionContext: {
        mode: 'default',
        alwaysDenyRules: { Bash: ['rm *'] },
      },
    })

    const result = await agent.query({
      messages: [createUserMessage('删除 temp 目录')],
      tools: [BashTool],
    })

    // 验证:Agent 尝试了 rm,被拒绝后应告知用户
    const deniedCalls = result.messages.filter(m =>
      m.type === 'user' && m.message.content.includes('denied')
    )
    expect(deniedCalls.length).toBeGreaterThan(0)
  }, 30_000)
})

第三层:回归测试(Golden Prompts)

// Golden Prompt 回归测试
// 固定输入 → 验证预期的工具调用序列

describe('Golden Prompts', () => {
  const GOLDEN_CASES = [
    {
      name: '查找 TODO 注释',
      prompt: '列出所有 TODO 注释',
      expectedTools: ['Grep'],
      expectedPattern: /TODO/,
    },
    {
      name: '创建新文件',
      prompt: '创建一个 hello.js 文件,内容是 console.log("hello")',
      expectedTools: ['Write'],
      expectedFile: 'hello.js',
    },
    {
      name: '运行测试',
      prompt: '运行 npm test',
      expectedTools: ['Bash'],
      expectedCommand: /npm test/,
    },
  ]

  for (const tc of GOLDEN_CASES) {
    it(`Golden: ${tc.name}`, async () => {
      const agent = new AgentLoop({ model: TEST_MODEL })
      const result = await agent.query({
        messages: [createUserMessage(tc.prompt)],
        tools: getAllTools(),
      })

      const toolCalls = extractToolCalls(result.messages)
      expect(toolCalls.map(t => t.name)).toEqual(
        expect.arrayContaining(tc.expectedTools)
      )
    }, 30_000)
  }
})

第四层:混沌测试

// 混沌测试 — 模拟各种故障场景

describe('Chaos Testing', () => {
  it('应处理 API 超时', async () => {
    const agent = new AgentLoop({
      model: TEST_MODEL,
      // Mock: 第一次调用超时,第二次成功
      apiClient: createMockClient({
        responses: [
          { error: new TimeoutError('Request timed out') },
          { content: [{ type: 'text', text: 'Done' }] },
        ],
      }),
    })

    const result = await agent.query({
      messages: [createUserMessage('Hello')],
    })

    // 验证:Agent 重试后成功
    expect(result.messages[result.messages.length - 1].message.content)
      .toContain('Done')
  })

  it('应处理 429 限流', async () => {
    const agent = new AgentLoop({
      apiClient: createMockClient({
        responses: [
          { error: { status: 429, headers: { 'retry-after': '1' } } },
          { content: [{ type: 'text', text: 'OK' }] },
        ],
      }),
    })

    const startTime = Date.now()
    await agent.query({ messages: [createUserMessage('Hello')] })

    // 验证:等待了 retry-after 时间
    expect(Date.now() - startTime).toBeGreaterThanOrEqual(1000)
  })

  it('应处理畸形 API 响应', async () => {
    const agent = new AgentLoop({
      apiClient: createMockClient({
        responses: [
          // 返回没有 content 的响应
          { content: null },
        ],
      }),
    })

    // 验证:不崩溃,返回错误信息
    const result = await agent.query({
      messages: [createUserMessage('Hello')],
    })
    expect(result.error).toBeDefined()
  })

  it('应处理工具执行超时', async () => {
    const agent = new AgentLoop({
      tools: [{
        ...BashTool,
        execute: async () => {
          await sleep(60_000)  // 模拟超时
          return 'done'
        },
      }],
    })

    const result = await agent.query({
      messages: [createUserMessage('运行一个很慢的命令')],
      timeout: 5_000,  // 5 秒超时
    })

    // 验证:超时后 Agent 不崩溃
    expect(result.error).toContain('timeout')
  })
})

权限测试矩阵

// 权限系统测试矩阵

describe('Permission Matrix', () => {
  const MODES = ['default', 'plan', 'bypassPermissions', 'auto']
  const TOOLS = ['Bash', 'Read', 'Edit', 'Write']
  const INPUTS = [
    { tool: 'Bash', input: { command: 'ls' } },       // 只读
    { tool: 'Bash', input: { command: 'rm -rf /' } },  // 危险
    { tool: 'Edit', input: { file_path: '/src/a.ts' } }, // 写入
    { tool: 'Read', input: { file_path: '/src/a.ts' } }, // 只读
  ]

  for (const mode of MODES) {
    for (const { tool, input } of INPUTS) {
      it(`mode=${mode}, tool=${tool}, input=${JSON.stringify(input)}`, () => {
        const result = evaluatePermission(mode, tool, input)

        // plan 模式:写入工具应被拦截
        if (mode === 'plan' && ['Edit', 'Write'].includes(tool)) {
          expect(result).toBe('deny')
        }

        // bypass 模式:所有工具应被允许
        if (mode === 'bypassPermissions') {
          expect(result).toBe('allow')
        }

        // 只读工具在所有模式下都应允许
        if (tool === 'Read') {
          expect(result).toBe('allow')
        }
      })
    }
  }
})
测试策略总结:
  • 单元测试 — 快速、大量、无外部依赖,验证确定性逻辑
  • 集成测试 — 使用小模型(Haiku),验证 Agent Loop 端到端
  • 回归测试 — Golden Prompts 确保行为不退化
  • 混沌测试 — 注入故障(超时、限流、畸形响应),验证容错
  • 权限矩阵 — 4 种模式 × N 种工具 × N 种输入 = 完整覆盖
降低测试成本的技巧:
  • 用小模型 — 集成测试用 Haiku,成本是 Sonnet 的 1/20
  • Mock 外部服务 — MCP Server、LSP 等用 mock 替代
  • 缓存 API 响应 — 相同 prompt 的 API 响应缓存到磁盘
  • 并行执行 — 单元测试完全并行,集成测试按需并行
  • Golden Prompt 回放 — 录制一次 API 调用,后续回放

附录:分阶段搭建清单

这是一个逐阶段的检查清单,你可以按顺序参考:

Phase 1 — 核心循环

Phase 1.5 — 并发工具执行

Phase 2 — 工具系统

Phase 2.5 — 系统提示词工程

Phase 3 — 权限系统

Phase 3.5 — Plan 模式 + Hooks

Phase 4 — 状态管理

Phase 4.5 — 会话持久化

Phase 5 — 上下文管理

Phase 5.5 — 记忆系统(核心模块)

Phase 5.6 — 工具调用全链路(核心模块)

Phase 5.7 — 后台任务与持久化(核心模块)

Phase 5.8 — Agent Loop 深度实现(核心模块)

Phase 6 — UI 与交互

Phase 7 — 多 Agent(可选)

Phase 8 — 优化与扩展

Phase 9 — 安全与成本

扩展层 — MCP 协议集成

扩展层 — Bridge/IDE 集成

扩展层 — 高级工具加载

扩展层 — 设置与推测执行

扩展层 — 测试策略

🤖 愿你的 Agent 稳定运行,永不爆 token

基于 Claude Code 源码 (2026-03-31) 架构逆向分析
仅供学习与参考