autosnippet 3.2.7 → 3.2.9

package/lib/service/agent/AgentRuntime.js

@@ -0,0 +1,1016 @@
+/**
+ * AgentRuntime — 统一 Agent 执行引擎 (The Brain)
+ *
+ * 核心思想: 不存在类型分野，只有 ONE Runtime。
+ * 只有 ONE Runtime，由 Capability + Strategy + Policy 配置驱动。
+ *
+ * AgentRuntime 是:
+ *   - ReAct 循环的宿主 (Thought → Action → Observation)
+ *   - Capability 的组合容器 (加载哪些技能)
+ *   - Policy 的执行者 (遵守哪些约束)
+ *   - Strategy 的被委托者 (Strategy 调用 runtime.reactLoop())
+ *
+ * 认知架构 (CoALA):
+ *   Perception → Working Memory → Reasoning → Action → Reflection
+ *   │             │                │           │         │
+ *   AgentMessage   history+memory   LLM call    Tools    Policy.validateAfter
+ *
+ * 引擎级能力:
+ *   - ContextWindow: 三级递进压缩，动态 token 预算 (可选注入)
+ *   - ExplorationTracker: 阶段状态机 + 信号收集 + Nudge + Graceful exit (可选注入)
+ *   - AI 错误恢复: consecutiveAiErrors 2-strike → context reset → forced summary
+ *   - 空响应重试: consecutiveEmptyResponses + rollback (system 场景)
+ *   - 熔断器感知: _circuitState === 'OPEN' → 直接合成摘要
+ *   - 工具调用数量限制: MAX_TOOL_CALLS_PER_ITER = 8
+ *   - 提交去重: submittedTitles / submittedPatterns
+ *   - cleanFinalAnswer: 去除 nudge 噪声
+ *
+ * @module AgentRuntime
+ */
+
+import { randomUUID } from 'node:crypto';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { AgentState, AgentPhase } from './AgentState.js';
+import { AgentEventBus, AgentEvents } from './AgentEventBus.js';
+import { PolicyEngine, BudgetPolicy, SafetyPolicy } from './policies.js';
+import { CapabilityRegistry, Capability } from './capabilities.js';
+import { limitToolResult } from './context/ContextWindow.js';
+import { cleanFinalAnswer } from './core/ChatAgentPrompts.js';
+import { produceForcedSummary } from './forced-summary.js';
+import { createMessageAdapter } from './core/MessageAdapter.js';
+import { LoopContext } from './core/LoopContext.js';
+import { createToolPipeline } from './core/ToolExecutionPipeline.js';
+
+/** 单次迭代允许的最大工具调用数 */
+const MAX_TOOL_CALLS_PER_ITER = 8;
+
+/**
+ * @typedef {Object} RuntimeConfig
+ * @property {string} [id] — 运行时唯一 ID
+ * @property {string} [presetName] — 使用的 Preset 名称 (仅标识)
+ * @property {import('../../external/ai/AiProvider.js').AiProvider} aiProvider — LLM 提供商
+ * @property {import('./tools/ToolRegistry.js').ToolRegistry} toolRegistry — 工具注册表
+ * @property {Object} [container] — DI 容器
+ * @property {Capability[]} capabilities — 已实例化的 Capability 列表
+ * @property {import('./strategies.js').Strategy} strategy — 执行策略
+ * @property {PolicyEngine} policies — 策略引擎
+ * @property {Object} [persona] — 人格配置
+ * @property {Object} [memory] — 记忆配置
+ * @property {Function} [onProgress] — 进度回调
+ * @property {Function} [onToolCall] — 工具调用通知钩子 (name, args, result, iteration)
+ * @property {string} [lang] — 语言偏好
+ * @property {string} [projectRoot] — 项目根目录 (传入工具上下文)
+ */
+
+export class AgentRuntime {
+  /** @type {string} */
+  id;
+  /** @type {string} */
+  presetName;
+  /** @type {AgentState} */
+  state;
+  /** @type {AgentEventBus} */
+  bus;
+  /** @type {import('../../external/ai/AiProvider.js').AiProvider} */
+  aiProvider;
+  /** @type {import('./tools/ToolRegistry.js').ToolRegistry} */
+  toolRegistry;
+  /** @type {Object} */
+  container;
+  /** @type {Capability[]} */
+  capabilities;
+  /** @type {import('./strategies.js').Strategy} */
+  strategy;
+  /** @type {PolicyEngine} */
+  policies;
+  /** @type {Object} */
+  persona;
+  /** @type {Object} */
+  memoryConfig;
+  /** @type {Function|null} */
+  onProgress;
+  /** @type {string|null} */
+  lang;
+  /** @type {Logger} */
+  logger;
+  /** @type {string} */
+  #projectRoot;
+  /** @type {Array|null} 文件缓存 (bootstrap 场景注入) */
+  #fileCache = null;
+  /** @type {string[]} 额外工具白名单 (调用方按需注入，不经 Capability) */
+  #additionalTools = [];
+  /** @type {import('./core/ToolExecutionPipeline.js').ToolExecutionPipeline} */
+  #toolPipeline;
+
+  // ── 执行统计 ──
+  iterationCount = 0;
+  toolCallHistory = [];
+  tokenUsage = { input: 0, output: 0 };
+  startTime = 0;
+
+  /**
+   * @param {RuntimeConfig} config
+   */
+  constructor(config) {
+    this.id = config.id || `runtime_${randomUUID().slice(0, 8)}`;
+    this.presetName = config.presetName || 'custom';
+    this.aiProvider = config.aiProvider;
+    this.toolRegistry = config.toolRegistry;
+    this.container = config.container || null;
+    this.capabilities = config.capabilities || [];
+    this.strategy = config.strategy;
+    this.policies = config.policies || new PolicyEngine([]);
+    this.persona = config.persona || {};
+    this.memoryConfig = config.memory || {};
+    this.onProgress = config.onProgress || null;
+    this.onToolCall = config.onToolCall || null;
+    this.lang = config.lang || null;
+    this.logger = Logger.getInstance();
+    this.bus = AgentEventBus.getInstance();
+    this.#projectRoot = config.projectRoot || process.cwd();
+    this.#additionalTools = config.additionalTools || [];
+    this.#toolPipeline = createToolPipeline();
+
+    this.state = new AgentState({
+      initialData: { runtimeId: this.id, preset: this.presetName },
+    });
+
+    this.bus.publish(AgentEvents.AGENT_CREATED, {
+      agentId: this.id,
+      preset: this.presetName,
+      capabilities: this.capabilities.map(c => c.name),
+      strategy: this.strategy?.name,
+    }, { source: this.id });
+  }
+
+  // ─── 公共 API ─────────────────────────────────
+
+  /**
+   * 执行 Agent — 入口
+   *
+   * @param {import('./AgentMessage.js').AgentMessage} message — 统一消息
+   * @param {Object} [opts] — 策略特定选项 (如 FanOut 的 items)
+   * @returns {Promise<AgentResult>}
+   *
+   * @typedef {Object} AgentResult
+   * @property {string} reply — 最终文本回复
+   * @property {Array} toolCalls — 工具调用记录
+   * @property {Object} tokenUsage — Token 用量
+   * @property {number} iterations — 循环次数
+   * @property {number} durationMs — 执行耗时
+   * @property {Object} [phases] — Pipeline/FanOut 阶段详情
+   * @property {Object} state — 状态快照
+   */
+  async execute(message, opts = {}) {
+    this.startTime = Date.now();
+    this.iterationCount = 0;
+    this.toolCallHistory = [];
+    this.tokenUsage = { input: 0, output: 0 };
+
+    // ── Policy: 执行前校验 ──
+    const beforeCheck = this.policies.validateBefore({ message, capabilities: this.capabilities });
+    if (!beforeCheck.ok) {
+      this.logger.warn(`[AgentRuntime] Policy rejected: ${beforeCheck.reason}`);
+      return {
+        reply: `⚠️ ${beforeCheck.reason}`,
+        toolCalls: [],
+        tokenUsage: { input: 0, output: 0 },
+        iterations: 0,
+        durationMs: 0,
+        state: this.state.toJSON(),
+      };
+    }
+
+    // ── 超时保护 ──
+    const budget = this.policies.getBudget();
+    const timeoutMs = budget?.timeoutMs || 300_000;
+
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error(`Agent timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+
+    try {
+      // ── 委托给 Strategy ──
+      const resultPromise = this.strategy.execute(this, message, opts);
+      const result = await Promise.race([resultPromise, timeoutPromise]);
+      clearTimeout(timeoutId);
+
+      // ── Policy: 执行后校验 ──
+      const afterCheck = this.policies.validateAfter(result);
+      if (!afterCheck.ok) {
+        this.logger.warn(`[AgentRuntime] Quality check: ${afterCheck.reason}`);
+        result.qualityWarning = afterCheck.reason;
+      }
+
+      // 状态完成
+      this.#safeTransition('finish', { reply: result.reply?.slice(0, 100) });
+
+      // 回复给原始渠道
+      if (message.replyFn && result.reply) {
+        await message.reply(result.reply);
+      }
+
+      result.state = this.state.toJSON();
+      result.durationMs = Date.now() - this.startTime;
+
+      this.bus.publish(AgentEvents.AGENT_COMPLETED, {
+        agentId: this.id,
+        preset: this.presetName,
+        iterations: result.iterations,
+        durationMs: result.durationMs,
+      }, { source: this.id });
+
+      return result;
+
+    } catch (err) {
+      clearTimeout(timeoutId);
+      this.state.send('error', { error: err.message });
+      this.bus.publish(AgentEvents.AGENT_FAILED, {
+        agentId: this.id,
+        error: err.message,
+      }, { source: this.id });
+      throw err;
+    }
+  }
+
+  // ─── ReAct Loop — 供 Strategy 调用 ──────────
+
+  /**
+   * 核心 ReAct 循环。Strategy 调用此方法执行实际的 LLM + Tool 交互。
+   *
+   * 引擎级能力通过可选参数注入:
+   *   - contextWindow → 三级递进压缩 + 动态工具结果限额
+   *   - tracker → ExplorationTracker 阶段管理 + Nudge + Graceful exit
+   *   - trace → ActiveContext 推理链记录
+   *   - memoryCoordinator → 缓存/动态提示/观察记录
+   *   - sharedState → 提交去重 { submittedTitles, submittedPatterns }
+   *   - source → 'user' | 'system' (影响错误恢复 + 强制摘要行为)
+   *
+   * 向后兼容: 以上参数均为可选。不提供时退化为原始裸循环。
+   *
+   * @param {string} prompt — 用户/系统提示
+   * @param {Object} [opts]
+   * @param {Array} [opts.history] — 对话历史
+   * @param {Object} [opts.context] — 额外上下文
+   * @param {string[]} [opts.capabilityOverride] — 临时覆盖 capability (Pipeline 阶段用)
+   * @param {Object} [opts.budgetOverride] — 临时覆盖 budget
+   * @param {string} [opts.systemPromptOverride] — 完全覆盖系统提示词 (Bootstrap 阶段专用)
+   * @param {Function} [opts.onToolCall] — 本轮独立的工具调用钩子，优先于 runtime 级
+   * @param {import('./context/ContextWindow.js').ContextWindow} [opts.contextWindow] — 上下文窗口管理器
+   * @param {Object} [opts.tracker] — ExplorationTracker 实例
+   * @param {Object} [opts.trace] — ActiveContext 实例
+   * @param {Object} [opts.memoryCoordinator] — MemoryCoordinator 实例
+   * @param {Object} [opts.sharedState] — 共享状态 { submittedTitles, submittedPatterns }
+   * @param {string} [opts.source] — 'user' | 'system'
+   * @param {string} [opts.toolChoiceOverride] — 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
+   *   首轮强制 LLM 生成 tool call（LLM 自行决定调哪个工具、传什么参数）。
+   *   这不是替 LLM 做决定，而是告诉 LLM "你必须调用某个工具"。
+   *   仅在第一轮生效，后续轮次恢复正常 toolChoice 逻辑。
+   * @returns {Promise<AgentResult>}
+   */
+  async reactLoop(prompt, opts = {}) {
+    const ctx = this.#initLoop(prompt, opts);
+
+    // ─── ReAct 主循环 (编排骨架) ─────
+    while (true) {
+      ctx.iteration++;
+      this.iterationCount++;
+
+      // ActiveContext: 开始新轮次 (必须在 #shouldExit 前, 保证 endRound 有配对)
+      ctx.trace?.startRound(ctx.iteration);
+
+      // 退出判定 (tracker + policy)
+      if (this.#shouldExit(ctx)) break;
+
+      // 迭代准备 (hooks + nudge + compact + toolChoice + prompt)
+      const { toolChoice, effectiveSystemPrompt, effectivePrompt } =
+        this.#prepareIteration(ctx);
+
+      // LLM 调用 (含错误恢复 + 空响应重试)
+      const llmResult = await this.#callLLM(ctx, toolChoice, effectiveSystemPrompt, effectivePrompt);
+      if (!llmResult) break;
+      if (llmResult.__continue) continue;
+
+      // ActiveContext: 记录 AI 的推理文本 + 提取/更新计划
+      if (ctx.trace && llmResult.text) {
+        ctx.trace.setThought(llmResult.text);
+        ctx.trace.extractAndSetPlan?.(llmResult.text, ctx.iteration);
+      }
+
+      // 分支: 有 Tool Call
+      if (llmResult.functionCalls?.length > 0) {
+        const exitAfterTools = await this.#processToolCalls(ctx, llmResult, effectiveSystemPrompt);
+        if (exitAfterTools) break;
+        continue;
+      }
+
+      // 分支: 纯文本回复
+      if (this.#processTextResponse(ctx, llmResult)) break;
+    }
+
+    return this.#finalize(ctx);
+  }
+
+  // ─── 提取方法: reactLoop 内部阶段 ────────────
+
+  /**
+   * 初始化循环上下文 — 封装 reactLoop 前 ~60 行初始化逻辑
+   * @param {string} prompt
+   * @param {Object} opts
+   * @returns {LoopContext}
+   */
+  #initLoop(prompt, opts) {
+    const {
+      history = [], context = {}, capabilityOverride, budgetOverride,
+      systemPromptOverride, onToolCall,
+      contextWindow, tracker, trace, memoryCoordinator, sharedState, source,
+      toolChoiceOverride,
+    } = opts;
+
+    // 解析 capabilities
+    const caps = capabilityOverride
+      ? this.#resolveCapabilities(capabilityOverride)
+      : this.capabilities;
+
+    // 构建基础系统提示词
+    const baseSystemPrompt = systemPromptOverride || this.#buildSystemPrompt(caps, context);
+
+    // 收集工具 (caps 为空数组时 = 明确无工具)
+    const allowedTools = this.#collectTools(caps);
+    const noToolsExplicit = Array.isArray(capabilityOverride) && capabilityOverride.length === 0;
+    const toolSchemas = noToolsExplicit
+      ? []
+      : this.toolRegistry.getToolSchemas(allowedTools.length > 0 ? allowedTools : null);
+
+    // 创建统一消息适配器 (消除 useCtxWin 双模式)
+    const messages = createMessageAdapter(contextWindow);
+
+    // 加载历史 + 用户 prompt
+    for (const h of history) {
+      if (h.role === 'assistant') {
+        messages.appendAssistantText(h.content);
+      } else {
+        messages.appendUserMessage(h.content);
+      }
+    }
+    messages.appendUserMessage(prompt);
+
+    // 预算
+    const budget = budgetOverride || this.policies.getBudget() || {
+      maxIterations: 20, maxTokens: 4096, temperature: 0.7,
+    };
+
+    // 状态转移
+    this.#safeTransition('start', { prompt: prompt.slice(0, 100) });
+    this.#safeTransition('plan_ready');
+
+    this.bus.publish(AgentEvents.AGENT_STARTED, {
+      agentId: this.id,
+      prompt: prompt.slice(0, 100),
+      capabilities: caps.map(c => c.name),
+    }, { source: this.id });
+
+    return new LoopContext({
+      messages,
+      tracker: tracker || null,
+      trace: trace || null,
+      memoryCoordinator: memoryCoordinator || null,
+      sharedState: sharedState || null,
+      source: source || 'user',
+      budget,
+      capabilities: caps,
+      baseSystemPrompt,
+      toolSchemas,
+      prompt,
+      onToolCall: onToolCall || null,
+      context: context || {},
+      contextWindow: contextWindow || null,
+      toolChoiceOverride: toolChoiceOverride || null,
+    });
+  }
+
+  /**
+   * 退出判定 — 合并 tracker/policy 退出检查
+   * @param {LoopContext} ctx
+   * @returns {boolean} true = 应退出循环
+   */
+  #shouldExit(ctx) {
+    // ExplorationTracker: tick + 退出检查
+    if (ctx.tracker) {
+      ctx.tracker.tick();
+      if (ctx.tracker.shouldExit()) {
+        this.logger.info(
+          `[AgentRuntime] tracker exit: phase=${ctx.tracker.phase}, iter=${ctx.tracker.iteration}, submits=${ctx.tracker.totalSubmits}`
+        );
+        return true;
+      }
+    }
+
+    // Capability 前置钩子
+    for (const cap of ctx.capabilities) {
+      cap.onBeforeStep({
+        iteration: ctx.iteration,
+        messages: ctx.messages.toMessages(),
+        prompt: ctx.prompt,
+      });
+    }
+
+    // ── Per-stage budget timeout (从 budgetOverride 注入) ──
+    // 与 BudgetPolicy 的全局 timeoutMs (600s) 不同，此处使用阶段级 budget.timeoutMs
+    // 保证 Analyst/Producer 各自有独立的超时边界，避免一个阶段消耗完所有时长
+    if (ctx.budget?.timeoutMs && Date.now() - ctx.loopStartTime > ctx.budget.timeoutMs) {
+      this.logger.info(
+        `[AgentRuntime] ⏰ Stage budget timeout: ${ctx.budget.timeoutMs}ms exceeded (elapsed: ${Date.now() - ctx.loopStartTime}ms)`,
+      );
+      return true;
+    }
+
+    // Policy 实时校验
+    // 当 ExplorationTracker 存在时，由 tracker 自己管理 maxIterations + grace 轮次，
+    // 跳过 BudgetPolicy 的 iteration 限制，避免竞争（tracker 给了 grace 但 policy 立即杀掉循环）。
+    // tracker 内部有硬上限 (maxIterations + 2) 保证不会无限循环。
+    const skipPolicyIterCheck = !!ctx.tracker;
+    const duringCheck = this.policies.validateDuring({
+      iteration: skipPolicyIterCheck ? 0 : ctx.iteration, // tracker 模式下用 0 绕过 iteration 检查
+      toolCalls: this.toolCallHistory,
+      tokenUsage: this.tokenUsage,
+      startTime: ctx.loopStartTime,
+    });
+    if (!duringCheck.ok) {
+      this.logger.info(`[AgentRuntime] Policy stop: ${duringCheck.reason}`);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * 迭代准备 — 合并 nudge/压缩/提示词增强/toolChoice
+   * @param {LoopContext} ctx
+   * @returns {{ toolChoice: string, effectiveSystemPrompt: string, effectivePrompt: string }}
+   */
+  #prepareIteration(ctx) {
+    const { tracker, trace, capabilities, messages, prompt } = ctx;
+    const maxIterations = ctx.maxIterations;
+
+    this.#emitProgress('thinking', { iteration: ctx.iteration, maxIterations });
+
+    // Nudge 注入 (ExplorationTracker)
+    if (tracker) {
+      const nudge = tracker.getNudge(trace);
+      if (nudge) {
+        messages.appendUserNudge(nudge.text);
+        this.logger.info(
+          `[AgentRuntime] 💬 injected ${nudge.type} nudge at iter ${ctx.iteration}`
+        );
+        const _dim = ctx.sharedState?._dimensionMeta?.id || '';
+        console.log(`\n\x1b[36m━━━ Nudge [${nudge.type}] iter=${ctx.iteration}${_dim ? ` dim=${_dim}` : ''} ━━━\x1b[0m`);
+        console.log(`\x1b[33m${nudge.text}\x1b[0m\n`);
+      }
+    }
+
+    // 压缩检查
+    const compactResult = messages.compactIfNeeded();
+    if (compactResult.level > 0) {
+      this.logger.info(
+        `[AgentRuntime] context compacted: L${compactResult.level}, removed ${compactResult.removed} items`
+      );
+    }
+
+    // 动态 toolChoice
+    const forceSummaryAt = Math.max(2, Math.ceil(maxIterations * 0.8));
+    const forceSummary = !tracker && ctx.iteration >= forceSummaryAt;
+    let toolChoice;
+    if (ctx.toolChoiceOverride && ctx.iteration === 1) {
+      // 首轮 toolChoice 覆盖: 强制 LLM 生成 tool call (LLM 自行决定调哪个、传什么)
+      toolChoice = ctx.toolChoiceOverride;
+    } else if (tracker) {
+      toolChoice = tracker.getToolChoice();
+    } else {
+      toolChoice = ctx.toolSchemas.length > 0
+        ? (forceSummary ? 'none' : 'auto')
+        : 'none';
+    }
+
+    // 系统提示词增强 (阶段上下文 + 动态记忆)
+    let effectiveSystemPrompt = ctx.baseSystemPrompt;
+    if (tracker) {
+      effectiveSystemPrompt += tracker.getPhaseContext();
+    } else if (ctx.isSystem && !tracker) {
+      const remaining = maxIterations - ctx.iteration;
+      effectiveSystemPrompt += `\n\n## 当前进度\n第 ${ctx.iteration}/${maxIterations} 轮 | 剩余 ${remaining} 轮`;
+    }
+    if (ctx.isSystem && ctx.memoryCoordinator) {
+      const wmContext = ctx.memoryCoordinator.buildDynamicMemoryPrompt?.({
+        mode: ctx.source || 'analyst',
+        scopeId: ctx.context?.dimensionScopeId || null,
+      });
+      if (wmContext) effectiveSystemPrompt += `\n\n${wmContext}`;
+    }
+
+    // 非 tracker 模式的强制摘要提示注入
+    const effectivePrompt = forceSummary
+      ? `${prompt}\n\n[系统提示] 已进入最后阶段，请停止调用工具，基于已有信息输出总结。`
+      : prompt;
+
+    return { toolChoice, effectiveSystemPrompt, effectivePrompt };
+  }
+
+  /**
+   * LLM 调用 — 含错误恢复 + 空响应重试
+   *
+   * @param {LoopContext} ctx
+   * @param {string} toolChoice
+   * @param {string} effectiveSystemPrompt
+   * @param {string} effectivePrompt
+   * @returns {Promise<Object|null>} llmResult 或 null (表示应退出)
+   */
+  async #callLLM(ctx, toolChoice, effectiveSystemPrompt, effectivePrompt) {
+    this.bus.publish(AgentEvents.LLM_CALL_START, {
+      agentId: this.id,
+      iteration: ctx.iteration,
+    }, { source: this.id });
+
+    let llmResult;
+    try {
+      llmResult = await this.aiProvider.chatWithTools(effectivePrompt, {
+        messages: ctx.messages.toMessages(),
+        toolSchemas: ctx.toolSchemas.length > 0 ? ctx.toolSchemas : undefined,
+        toolChoice,
+        systemPrompt: effectiveSystemPrompt,
+        temperature: ctx.budget.temperature ?? (ctx.isSystem ? 0.3 : 0.7),
+        maxTokens: ctx.budget.maxTokens ?? (ctx.isSystem ? 8192 : 4096),
+      });
+      ctx.consecutiveAiErrors = 0;
+    } catch (aiErr) {
+      return this.#handleAiError(ctx, aiErr);
+    }
+
+    // 累计 Token (runtime 级 + loop 级)
+    if (llmResult.usage) {
+      this.tokenUsage.input += (llmResult.usage.inputTokens || 0);
+      this.tokenUsage.output += (llmResult.usage.outputTokens || 0);
+      ctx.addTokenUsage(llmResult.usage);
+    }
+
+    this.bus.publish(AgentEvents.LLM_CALL_END, {
+      agentId: this.id,
+      hasToolCalls: !!llmResult.functionCalls?.length,
+      hasText: !!llmResult.text,
+      usage: llmResult.usage,
+    }, { source: this.id });
+
+    // 空响应重试
+    if (!llmResult.text && !llmResult.functionCalls?.length) {
+      if (ctx.isSystem && ctx.consecutiveEmptyResponses < 2) {
+        ctx.consecutiveEmptyResponses++;
+        this.logger.warn(
+          `[AgentRuntime] ⚠ empty response — retrying (${ctx.consecutiveEmptyResponses}/2)`
+        );
+        ctx.tracker?.rollbackTick?.();
+        await new Promise(r => setTimeout(r, 1500));
+        // 返回 'continue' 信号 — 调用方需重走循环
+        return { __continue: true };
+      }
+      return null; // 退出
+    }
+    if (llmResult.text || llmResult.functionCalls?.length) {
+      ctx.consecutiveEmptyResponses = 0;
+    }
+
+    // Graceful exit 保护
+    if (ctx.tracker?.isGracefulExit && llmResult.functionCalls?.length > 0) {
+      this.logger.warn(
+        `[AgentRuntime] ⚠ AI returned ${llmResult.functionCalls.length} tool calls despite toolChoice=none (graceful exit) — ignoring`
+      );
+      if (llmResult.text) {
+        ctx.lastReply = cleanFinalAnswer(llmResult.text);
+        return null; // 退出
+      }
+      return { __continue: true };
+    }
+
+    return llmResult;
+  }
+
+  /**
+   * AI 错误处理 — 熔断器感知 + 2-strike 策略
+   * @returns {Object|null} — { __continue: true } 或 null (退出)
+   */
+  async #handleAiError(ctx, aiErr) {
+    ctx.consecutiveAiErrors++;
+    this.logger.warn(
+      `[AgentRuntime] AI call failed (attempt ${ctx.consecutiveAiErrors}): ${aiErr.message}`
+    );
+
+    ctx.tracker?.rollbackTick?.();
+
+    // 熔断器感知
+    if (aiErr.code === 'CIRCUIT_OPEN') {
+      this.logger.warn('[AgentRuntime] 🛑 circuit breaker OPEN — breaking to summary');
+      if (!ctx.isSystem) {
+        ctx.lastReply = `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`;
+      }
+      return null;
+    }
+
+    // 2-strike 策略
+    if (ctx.consecutiveAiErrors >= 2) {
+      this.logger.warn('[AgentRuntime] 🛑 2 consecutive AI errors — breaking to summary');
+      ctx.messages.resetToPromptOnly();
+      if (!ctx.isSystem) {
+        ctx.lastReply = `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`;
+      }
+      return null;
+    }
+
+    await new Promise(r => setTimeout(r, 2000));
+    return { __continue: true };
+  }
+
+  /**
+   * 工具调用处理 — 执行 + 记录 + 去重 + 阶段转换
+   *
+   * @param {LoopContext} ctx
+   * @param {Object} llmResult
+   * @param {string} effectiveSystemPrompt — 用于 budget 耗尽时的摘要调用
+   * @returns {Promise<boolean>} true = 应退出循环
+   */
+  async #processToolCalls(ctx, llmResult, effectiveSystemPrompt) {
+    const { tracker, trace, messages } = ctx;
+
+    // 工具调用数量限制
+    let activeCalls = llmResult.functionCalls;
+    if (activeCalls.length > MAX_TOOL_CALLS_PER_ITER) {
+      this.logger.warn(
+        `[AgentRuntime] ⚠ ${activeCalls.length} tool calls, capping to ${MAX_TOOL_CALLS_PER_ITER}`
+      );
+      tracker?.recordTruncatedCalls?.(activeCalls.length - MAX_TOOL_CALLS_PER_ITER);
+      activeCalls = activeCalls.slice(0, MAX_TOOL_CALLS_PER_ITER);
+    }
+
+    // 追加 assistant 消息
+    messages.appendAssistantWithToolCalls(llmResult.text || null, activeCalls);
+
+    let roundSubmitCount = 0;
+    let roundHasNewInfo = false;
+    const roundToolNames = [];
+
+    // 执行每个工具
+    for (const fc of activeCalls) {
+      this.#emitProgress('tool_call', { tool: fc.name, args: fc.args });
+
+      this.bus.publish(AgentEvents.TOOL_CALL_START, {
+        agentId: this.id,
+        tool: fc.name,
+      }, { source: this.id });
+
+      // 通过 Pipeline 执行 (safety → cache → execute → observe → track → trace → dedup)
+      const { result: toolResult, metadata } = await this.#toolPipeline.execute(fc, {
+        runtime: this,
+        loopCtx: ctx,
+        iteration: ctx.iteration,
+      });
+
+      const durationMs = metadata.durationMs;
+      const toolEntry = { tool: fc.name, args: fc.args, result: toolResult, durationMs };
+      ctx.toolCalls.push(toolEntry);
+      this.toolCallHistory.push(toolEntry);
+
+      if (metadata.isNew) roundHasNewInfo = true;
+      roundToolNames.push(fc.name);
+
+      // onToolCall 通知
+      const effectiveHook = ctx.onToolCall || this.onToolCall;
+      if (effectiveHook) {
+        try { effectiveHook(fc.name, fc.args, toolResult, ctx.iteration); } catch { /* 观察者错误不中断 */ }
+      }
+
+      this.bus.publish(AgentEvents.TOOL_CALL_END, {
+        agentId: this.id,
+        tool: fc.name,
+        durationMs,
+        success: !toolResult?.error,
+      }, { source: this.id });
+
+      // 工具结果格式化 (统一通过 MessageAdapter)
+      let resultStr = messages.formatToolResult(fc.name, toolResult);
+
+      // 提交去重: pipeline 中间件已标记 metadata
+      if (metadata.dedupMessage) {
+        resultStr = metadata.dedupMessage;
+      } else if (metadata.isSubmit) {
+        roundSubmitCount++;
+      }
+
+      // 进度回调 (tool_end 需要 resultStr.length)
+      this.#emitProgress('tool_end', {
+        tool: fc.name,
+        duration: durationMs,
+        status: toolResult?.error ? 'error' : 'ok',
+        error: toolResult?.error || undefined,
+        resultSize: resultStr.length,
+      });
+
+      // 追加 tool result
+      messages.appendToolResult(fc.id, fc.name, resultStr);
+    }
+
+    // ExplorationTracker: endRound → 检查阶段转换
+    if (tracker) {
+      tracker.updatePlanProgress?.(trace);
+      const transitionNudge = tracker.endRound({
+        hasNewInfo: roundHasNewInfo,
+        submitCount: roundSubmitCount,
+        toolNames: roundToolNames,
+      });
+      if (transitionNudge) {
+        messages.appendUserNudge(transitionNudge.text);
+        this.logger.info(
+          `[AgentRuntime] 📝 injected ${transitionNudge.type} nudge (${tracker.phase})`
+        );
+        const _dimT = ctx.sharedState?._dimensionMeta?.id || '';
+        console.log(`\n\x1b[35m━━━ Transition Nudge [${transitionNudge.type}] phase=${tracker.phase}${_dimT ? ` dim=${_dimT}` : ''} ━━━\x1b[0m`);
+        console.log(`\x1b[33m${transitionNudge.text}\x1b[0m\n`);
+      }
+    }
+
+    // ActiveContext: 关闭轮次
+    if (trace) {
+      trace.setRoundSummary?.({
+        newInfoCount: roundHasNewInfo ? 1 : 0,
+        totalCalls: activeCalls.length,
+        submits: roundSubmitCount,
+        cumulativeFiles: tracker?.getMetrics?.()?.uniqueFiles || 0,
+        cumulativePatterns: tracker?.getMetrics?.()?.uniquePatterns || 0,
+      });
+      trace.endRound?.();
+    }
+
+    // Capability 后置钩子
+    const stepToolEntries = ctx.toolCalls.slice(-activeCalls.length);
+    const stepResult = {
+      type: 'tool_calls',
+      toolCalls: stepToolEntries,
+      iteration: ctx.iteration,
+    };
+    for (const cap of ctx.capabilities) {
+      cap.onAfterStep(stepResult);
+    }
+
+    this.#safeTransition('step_done', stepResult);
+
+    // 检查预算 (非 tracker 模式)
+    if (!tracker && ctx.iteration >= ctx.maxIterations) {
+      const summary = await this.aiProvider.chatWithTools(ctx.prompt, {
+        messages: messages.toMessages(),
+        systemPrompt: effectiveSystemPrompt,
+        toolChoice: 'none',
+        temperature: ctx.budget.temperature ?? 0.7,
+        maxTokens: ctx.budget.maxTokens ?? 4096,
+      });
+      if (summary.usage) {
+        this.tokenUsage.input += (summary.usage.inputTokens || 0);
+        this.tokenUsage.output += (summary.usage.outputTokens || 0);
+        ctx.addTokenUsage(summary.usage);
+      }
+      ctx.lastReply = cleanFinalAnswer(summary.text || '');
+      return true; // 退出
+    }
+
+    this.#safeTransition('continue');
+    return false; // 继续循环
+  }
+
+  /**
+   * 文本响应处理 — tracker 阶段路由 + 非 tracker 直接终止
+   *
+   * @param {LoopContext} ctx
+   * @param {Object} llmResult
+   * @returns {boolean} true = 应退出循环
+   */
+  #processTextResponse(ctx, llmResult) {
+    const { tracker, trace, messages } = ctx;
+
+    if (tracker) {
+      // (setThought + extractAndSetPlan 已在主循环中统一处理)
+
+      const textResult = tracker.onTextResponse();
+
+      if (textResult.isFinalAnswer) {
+        ctx.lastReply = cleanFinalAnswer(llmResult.text || '');
+        this.logger.info(
+          `[AgentRuntime] ✅ final answer — ${ctx.lastReply.length} chars, ${tracker.iteration} iters, ${ctx.toolCalls.length} tool calls`
+        );
+        trace?.endRound?.();
+        return true;
+      }
+
+      if (textResult.needsDigestNudge) {
+        messages.appendAssistantText(llmResult.text || '');
+        messages.appendUserNudge(textResult.nudge);
+        this.logger.info('[AgentRuntime] 📝 injected SUMMARIZE nudge (text-triggered transition)');
+        const _dimD = ctx.sharedState?._dimensionMeta?.id || '';
+        console.log(`\n\x1b[34m━━━ Digest Nudge [SUMMARIZE]${_dimD ? ` dim=${_dimD}` : ''} ━━━\x1b[0m`);
+        console.log(`\x1b[33m${textResult.nudge}\x1b[0m\n`);
+        trace?.endRound?.();
+        return false; // continue
+      }
+
+      if (textResult.shouldContinue) {
+        messages.appendAssistantText(llmResult.text || '');
+        if (textResult.nudge) {
+          messages.appendUserNudge(textResult.nudge);
+          const _dimC = ctx.sharedState?._dimensionMeta?.id || '';
+          console.log(`\n\x1b[32m━━━ Continue Nudge${_dimC ? ` dim=${_dimC}` : ''} ━━━\x1b[0m`);
+          console.log(`\x1b[33m${textResult.nudge}\x1b[0m\n`);
+        }
+        trace?.endRound?.();
+        return false; // continue
+      }
+    }
+
+    // 非 tracker 模式: 文字回答即最终回答
+    ctx.lastReply = cleanFinalAnswer(llmResult.text || '');
+    trace?.endRound?.();
+    return true;
+  }
+
+  /**
+   * 循环退出后处理 — 强制摘要 + 构建返回值
+   * @param {LoopContext} ctx
+   * @returns {Promise<Object>}
+   */
+  async #finalize(ctx) {
+    // 强制摘要 (系统场景或 tracker 场景)
+    if (!ctx.lastReply && (ctx.tracker || ctx.isSystem)) {
+      const forcedResult = await produceForcedSummary({
+        aiProvider: this.aiProvider,
+        source: ctx.source,
+        toolCalls: ctx.toolCalls,
+        tracker: ctx.tracker,
+        contextWindow: ctx.contextWindow,
+        prompt: ctx.prompt,
+        tokenUsage: this.tokenUsage,
+      });
+      ctx.lastReply = forcedResult.reply;
+      if (forcedResult.tokenUsage) {
+        this.tokenUsage.input += (forcedResult.tokenUsage.input || 0);
+        this.tokenUsage.output += (forcedResult.tokenUsage.output || 0);
+        ctx.addTokenUsage({
+          inputTokens: forcedResult.tokenUsage.input || 0,
+          outputTokens: forcedResult.tokenUsage.output || 0,
+        });
+      }
+    }
+
+    return ctx.buildResult();
+  }
+
+  // ─── 公共工具方法 ────────────────────────────
+
+  /**
+   * 中止执行
+   */
+  abort(reason = 'User aborted') {
+    this.#safeTransition('abort', { reason });
+    this.bus.publish(AgentEvents.AGENT_ABORTED, {
+      agentId: this.id,
+      reason,
+    }, { source: this.id });
+  }
+
+  /**
+   * 注入内存文件缓存（bootstrap 场景: allFiles 已在内存中，避免重复磁盘读取）
+   * @param {Array|null} files — [{ relativePath, content, name }]
+   */
+  setFileCache(files) {
+    this.#fileCache = files;
+  }
+
+  /** 项目根目录 (供 ToolExecutionPipeline 等访问) */
+  get projectRoot() {
+    return this.#projectRoot;
+  }
+
+  /** 文件缓存 (供 ToolExecutionPipeline 等访问) */
+  get fileCache() {
+    return this.#fileCache;
+  }
+
+  /**
+   * 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用)
+   */
+  emitProgress(type, data = {}) {
+    this.#emitProgress(type, data);
+  }
+
+  // ─── 私有方法 ────────────────────────────────
+
+  /**
+   * 安全状态转移 — 忽略不合法转移而不是抛异常。
+   *
+   * Pipeline/FanOut 场景下 reactLoop() 被多次调用,
+   * 第 2+ 次调用时状态已不在 IDLE，直接 send('start') 会抛错。
+   * 此方法在转移不合法时静默跳过，保证多阶段执行不中断。
+   */
+  #safeTransition(event, payload = {}) {
+    try {
+      this.state.send(event, payload);
+    } catch {
+      // 转移不合法 — 在多阶段场景中这是预期行为，静默跳过
+    }
+  }
+
+  /**
+   * 构建系统提示词 — 从 Persona + Capabilities 组装
+   */
+  #buildSystemPrompt(caps, context) {
+    const parts = [];
+
+    // Persona (角色定义)
+    if (this.persona?.description) {
+      parts.push(`# 角色\n${this.persona.description}`);
+    }
+
+    // fileCache 文件清单 — 让 LLM 知道有哪些文件可用于工具调用
+    if (this.#fileCache && this.#fileCache.length > 0) {
+      const fileList = this.#fileCache.map(f => {
+        const lines = f.content ? f.content.split('\n').length : 0;
+        const name = f.name || f.relativePath || 'unknown';
+        return `- ${name} (${lines} 行${f.language ? ', ' + f.language : ''})`;
+      }).join('\n');
+      parts.push(`## 预加载文件\n以下文件已加载到缓存中，工具可通过 filePath 参数引用：\n${fileList}`);
+    }
+
+    // Capability prompt fragments
+    for (const cap of caps) {
+      parts.push(cap.promptFragment);
+
+      // Capability 动态上下文 (记忆、项目概况等)
+      const dynamicCtx = cap.buildContext({
+        ...context,
+        lang: this.lang,
+        memoryMode: this.memoryConfig?.mode,
+      });
+      if (dynamicCtx) parts.push(dynamicCtx);
+    }
+
+    // 语言要求
+    if (this.lang === 'en') {
+      parts.push('\n## Language\nRespond in English.');
+    } else if (this.lang === 'zh') {
+      parts.push('\n## 语言\n用中文回复。代码/字段名保持英文。');
+    }
+
+    return parts.join('\n\n');
+  }
+
+  /**
+   * 收集所有 Capability 的工具白名单
+   * 如果任一 Capability tools 为空数组, 返回空 (使用全部工具)
+   */
+  #collectTools(caps) {
+    const toolSet = new Set();
+    let hasUnlimited = false;
+    for (const cap of caps) {
+      const tools = cap.tools;
+      if (!tools || tools.length === 0) {
+        hasUnlimited = true;
+        break;
+      }
+      for (const t of tools) toolSet.add(t);
+    }
+    // 合并调用方按需注入的额外工具 (不经 Capability，避免污染共享能力)
+    for (const t of this.#additionalTools) toolSet.add(t);
+    return hasUnlimited ? [] : [...toolSet];
+  }
+
+  /**
+   * 解析 capability 名称为实例 (Pipeline 阶段覆盖时调用)
+   */
+  #resolveCapabilities(capNames) {
+    if (capNames == null) return this.capabilities;
+    if (capNames.length === 0) return [];  // explicit empty = no tools
+    return capNames.map(name => {
+      if (typeof name === 'object' && name instanceof Capability) return name;
+      // 先在已加载的 capabilities 中查找
+      const existing = this.capabilities.find(c => c.name === name);
+      if (existing) return existing;
+      // 否则从注册表创建
+      return CapabilityRegistry.create(name);
+    });
+  }
+
+  /**
+   * 发送进度事件
+   */
+  #emitProgress(type, data = {}) {
+    const event = { type, agentId: this.id, preset: this.presetName, ...data, timestamp: Date.now() };
+    if (this.onProgress) this.onProgress(event);
+    this.bus.publish(AgentEvents.PROGRESS, event, { source: this.id });
+  }
+}
+
+export default AgentRuntime;