autosnippet 3.2.10 → 3.2.11

package/lib/service/agent/context/ExplorationTracker.js

@@ -1,1385 +0,0 @@
-/**
- * ExplorationTracker — 统一的 AI 探索生命周期控制器
- *
- * 合并了三个原本各自为政的系统:
- *   1. PhaseRouter (ContextWindow.js) — 阶段状态机
- *   2. 探索进度追踪 (原内联逻辑) — 信息增量检测
- *   3. ReasoningLayer 行为控制部分 — 反思/规划/停滞 nudge
- *
- * 职责:
- *   - 信号收集: 统一的 recordToolCall() 替代 ~120 行内联 if-else
- *   - 阶段路由: 策略模式，不同角色使用不同阶段策略
- *   - Nudge 生成: 优先级队列，每轮最多注入一条 nudge
- *   - Graceful exit: 管理轮次耗尽后的优雅退出流程
- *
- * 不拥有的职责:
- *   - 推理链数据收集 → ReasoningTrace (纯数据，不影响行为)
- *   - 上下文压缩 → ContextWindow
- *   - 工具注册与执行 → ToolRegistry
- *   - 跨对话记忆 → Memory / WorkingMemory
- *
- * @module ExplorationTracker
- */
-
-import Logger from '../../../infrastructure/logging/Logger.js';
-
-// ─── 常量 ──────────────────────────────────────────────
-
-/** 反思间隔（每 N 轮触发一次） */
-const DEFAULT_REFLECTION_INTERVAL = 5;
-/** 连续无新信息 N 轮触发停滞反思 */
-const DEFAULT_STALE_THRESHOLD = 2;
-/** 最少经过 N 轮后才允许触发停滞反思 */
-const MIN_ITERS_FOR_STALE_REFLECTION = 4;
-/** 默认重规划间隔 */
-const DEFAULT_REPLAN_INTERVAL = 8;
-/** 默认偏差阈值 */
-const DEFAULT_DEVIATION_THRESHOLD = 0.6;
-/** 默认最少探索轮次（冷启动质量保障） */
-const DEFAULT_MIN_EXPLORE_ITERS = 10;
-/** 默认停滞收敛阈值 */
-const DEFAULT_CONVERGENCE_STALE_THRESHOLD = 3;
-/** 最少经过 N 轮后才允许再次触发 replan（防止 replan 风暴） */
-const MIN_REPLAN_GAP = 3;
-
-// ─── 内置策略 ────────────────────────────────────────────
-
-/**
- * Bootstrap 策略（有 submit 阶段）
- * @param {boolean} isSkillOnly — skill-only 维度跳过 PRODUCE 阶段
- * @returns {object} 策略配置
- */
-function createBootstrapStrategy(isSkillOnly = false) {
-  return {
-    name: 'bootstrap',
-    phases: isSkillOnly
-      ? ['EXPLORE', 'SUMMARIZE']
-      : ['EXPLORE', 'PRODUCE', 'SUMMARIZE'],
-    transitions: {
-      ...(isSkillOnly
-        ? {
-            'EXPLORE→SUMMARIZE': {
-              onMetrics: (m, b) =>
-                m.submitCount > 0 ||
-                m.searchRoundsInPhase >= b.searchBudget,
-              onTextResponse: true,
-            },
-          }
-        : {
-            'EXPLORE→PRODUCE': {
-              onMetrics: (m, b) =>
-                m.submitCount > 0 ||
-                m.searchRoundsInPhase >= b.searchBudget,
-              onTextResponse: true,
-            },
-            'PRODUCE→SUMMARIZE': {
-              onMetrics: (m, b) =>
-                m.submitCount >= b.maxSubmits ||
-                (m.submitCount > 0 && m.roundsSinceSubmit >= b.idleRoundsToExit) ||
-                (m.phaseRounds >= b.searchBudgetGrace && m.submitCount === 0),
-              onTextResponse: (m, b) =>
-                m.submitCount >= b.softSubmitLimit,
-            },
-          }),
-    },
-    getToolChoice: (phase, m, b) => {
-      if (phase === 'SUMMARIZE') return 'none';
-      if (phase === 'EXPLORE') {
-        return m.searchRoundsInPhase >= b.searchBudget - 1 ? 'auto' : 'required';
-      }
-      return 'auto'; // PRODUCE
-    },
-    enableReflection: true,
-    reflectionInterval: DEFAULT_REFLECTION_INTERVAL,
-    enablePlanning: true,
-    replanInterval: DEFAULT_REPLAN_INTERVAL,
-  };
-}
-
-/**
- * Analyst 策略（纯探索，无 submit 阶段）
- * 4 阶段: SCAN → EXPLORE → VERIFY → SUMMARIZE
- */
-const STRATEGY_ANALYST = {
-  name: 'analyst',
-  phases: ['SCAN', 'EXPLORE', 'VERIFY', 'SUMMARIZE'],
-  transitions: {
-    'SCAN→EXPLORE': {
-      onMetrics: (m) => m.iteration >= 3,
-      onTextResponse: false, // SCAN 阶段文本回复不触发转换
-    },
-    'EXPLORE→VERIFY': {
-      onMetrics: (m, b) =>
-        m.searchRoundsInPhase >= Math.floor(b.maxIterations * 0.6) ||
-        m.roundsSinceNewInfo >= 3,
-      onTextResponse: false, // 允许中间分析文本
-    },
-    'VERIFY→SUMMARIZE': {
-      onMetrics: (m, b) =>
-        m.iteration >= Math.floor(b.maxIterations * 0.8) ||
-        m.roundsSinceNewInfo >= 2,
-      onTextResponse: true,
-    },
-  },
-  getToolChoice: (phase) => {
-    if (phase === 'SUMMARIZE') return 'none';
-    if (phase === 'SCAN') return 'required';
-    if (phase === 'EXPLORE') return 'required';
-    return 'auto'; // VERIFY
-  },
-  enableReflection: true,
-  reflectionInterval: DEFAULT_REFLECTION_INTERVAL,
-  enablePlanning: true,
-  replanInterval: DEFAULT_REPLAN_INTERVAL,
-};
-
-/**
- * Producer 策略（格式化+提交，不搜索）
- * 2 阶段: PRODUCE → SUMMARIZE
- */
-const STRATEGY_PRODUCER = {
-  name: 'producer',
-  phases: ['PRODUCE', 'SUMMARIZE'],
-  transitions: {
-    'PRODUCE→SUMMARIZE': {
-      onMetrics: (m, b) =>
-        m.submitCount >= b.maxSubmits ||
-        (m.submitCount > 0 && m.roundsSinceSubmit >= b.idleRoundsToExit) ||
-        (m.phaseRounds >= b.searchBudgetGrace && m.submitCount === 0),
-      onTextResponse: (m, b) =>
-        m.submitCount >= b.softSubmitLimit,
-    },
-  },
-  getToolChoice: (phase) => (phase === 'SUMMARIZE' ? 'none' : 'auto'),
-  enableReflection: false,
-  reflectionInterval: 0,
-  enablePlanning: false,
-  replanInterval: 0,
-};
-
-// ─── 搜索工具白名单（用于判断"搜索轮次"）───────────────
-
-const SEARCH_TOOLS = new Set([
-  'search_project_code',
-  'semantic_search_code',
-  'get_class_info',
-  'get_class_hierarchy',
-  'get_protocol_info',
-  'get_method_overrides',
-  'get_category_map',
-  'list_project_structure',
-  'get_project_overview',
-  'get_file_summary',
-  'query_code_graph',
-  'query_call_graph',
-]);
-
-// ─── ExplorationTracker 主类 ─────────────────────────────
-
-export class ExplorationTracker {
-  /** @type {object} 策略配置 */
-  #strategy;
-  /** @type {object} 预算配置 */
-  #budget;
-  /** @type {string} 当前阶段 */
-  #phase;
-  /** @type {object} 日志器 */
-  #logger;
-
-  // ── 信号指标 ──
-  #metrics = {
-    uniqueFiles: new Set(),
-    uniquePatterns: new Set(),
-    uniqueQueries: new Set(),
-    totalToolCalls: 0,
-    submitCount: 0,
-    roundsSinceNewInfo: 0,
-    roundsSinceSubmit: 0,
-    iteration: 0,
-    searchRoundsInPhase: 0,
-    phaseRounds: 0,
-  };
-
-  // ── 阶段控制 ──
-  /** @type {boolean} 是否刚完成阶段转换（用于 pending nudge） */
-  #justTransitioned = false;
-  /** @type {string|null} 转换前的旧阶段 */
-  #transitionFromPhase = null;
-  /** @type {boolean} 是否已注入收敛 nudge（防止重复触发） */
-  #convergenceNudged = false;
-  /** @type {boolean} 是否已注入预算警告（防止重复触发） */
-  #budgetWarningInjected = false;
-
-  // ── Graceful exit 控制 ──
-  /** @type {number|null} 进入 graceful exit 的轮次 */
-  #gracefulExitRound = null;
-
-  // ── Planning 跟踪 ──
-  /** @type {boolean} 等待 AI 输出 replan */
-  #pendingReplan = false;
-  /** @type {object} 计划进度 */
-  #planProgress = {
-    coveredSteps: 0,
-    totalSteps: 0,
-    deviationScore: 0,
-    unplannedActions: 0,
-    lastReplanIteration: null,
-    consecutiveOffPlan: 0,
-  };
-
-  /** @type {boolean} tick 是否已调用（用于 rollback） */
-  #ticked = false;
-  /** @type {string} 提交工具名（用于 nudge 文本生成） */
-  #submitToolName = 'submit_knowledge';
-
-  /**
-   * @param {object} strategy — 策略配置对象
-   * @param {object} budget — 预算配置 { maxIterations, searchBudget, ... }
-   */
-  constructor(strategy, budget) {
-    this.#strategy = strategy;
-    // 合并默认值: PipelineStrategy 创建 per-stage tracker 时,
-    // budget 可能仅含 maxIterations/temperature (来自 stage.budget),
-    // 需要补全 tracker 所需的 searchBudget、maxSubmits 等字段。
-    this.#budget = {
-      maxIterations: 24,
-      searchBudget: 18,
-      searchBudgetGrace: 10,
-      maxSubmits: 10,
-      softSubmitLimit: 8,
-      idleRoundsToExit: 3,
-      ...budget,
-    };
-    /** @type {string} 提交工具名 — bootstrap 用 submit_knowledge，scan 用 collect_scan_recipe */
-    this.#submitToolName = budget.submitToolName || 'submit_knowledge';
-    this.#phase = strategy.phases[0];
-    this.#logger = Logger.getInstance();
-  }
-
-  // ─── 静态工厂 ─────────────────────────────────────────
-
-  /**
-   * 根据调用参数解析应使用的策略
-   * @param {object} opts — AgentRuntime execute 的选项
-   * @param {object} budget — 预算配置
-   * @returns {ExplorationTracker|null} — User 模式返回 null
-   */
-  static resolve(opts, budget) {
-    const { source = 'user', strategy: strategyName, dimensionMeta } = opts;
-    const isSystem = source === 'system';
-
-    if (!isSystem) {
-      return null; // User 模式不需要 ExplorationTracker
-    }
-
-    let resolvedStrategy;
-
-    if (strategyName === 'analyst') {
-      resolvedStrategy = STRATEGY_ANALYST;
-    } else if (strategyName === 'producer') {
-      resolvedStrategy = STRATEGY_PRODUCER;
-    } else {
-      // 默认 bootstrap（strategyName === 'bootstrap' 或未指定）
-      const isSkillOnly = dimensionMeta?.outputType === 'skill';
-      resolvedStrategy = createBootstrapStrategy(isSkillOnly);
-    }
-
-    return new ExplorationTracker(resolvedStrategy, budget);
-  }
-
-  // ─── 核心 API：主循环调用点 ────────────────────────────
-
-  /**
-   * 每轮迭代开始时调用 — 递增计数
-   * 可通过 rollbackTick() 撤销（AI 失败/空响应时）
-   */
-  tick() {
-    this.#metrics.iteration++;
-    this.#metrics.phaseRounds++;
-    this.#ticked = true;
-    // 安全: 清除上一轮可能遗留的 justTransitioned (文本路径不调 endRound)
-    this.#justTransitioned = false;
-  }
-
-  /**
-   * 撤销 tick（AI 调用失败或空响应时，不计入迭代）
-   */
-  rollbackTick() {
-    if (this.#ticked) {
-      this.#metrics.iteration--;
-      this.#metrics.phaseRounds--;
-      this.#ticked = false;
-    }
-  }
-
-  /** 提交工具名 (供外部判断是否为 scan / bootstrap pipeline) */
-  get submitToolName() {
-    return this.#submitToolName;
-  }
-
-  /**
-   * 是否应退出主循环
-   * @returns {boolean}
-   */
-  shouldExit() {
-    // Scan pipeline: SUMMARIZE 无消费方，recipes 已通过工具调用收集，直接退出
-    if (this.#isTerminalPhase() && this.#submitToolName === 'collect_scan_recipe') {
-      return true;
-    }
-    // 终结阶段 + 已给了 2 轮 grace → 退出
-    if (this.#isTerminalPhase() && this.#metrics.phaseRounds >= 2) {
-      return true;
-    }
-
-    // 硬上限兜底（maxIterations + 2 grace 都耗尽）
-    if (this.#metrics.iteration >= this.#budget.maxIterations + 2) {
-      return true;
-    }
-
-    // 达到 maxIterations 但未在终结阶段 → 强制转入终结阶段
-    if (this.#metrics.iteration >= this.#budget.maxIterations && !this.#isTerminalPhase()) {
-      this.#logger.info(
-        `[ExplorationTracker] maxIterations reached (${this.#metrics.iteration}/${this.#budget.maxIterations}), forcing → ${this.#getTerminalPhase()}`
-      );
-      this.#transitionTo(this.#getTerminalPhase());
-      this.#justTransitioned = false; // shouldExit 的转换由 force_exit nudge 覆盖，不重复
-      this.#gracefulExitRound = this.#metrics.iteration;
-      // 返回 false，让主循环运行终结阶段的 grace 轮次
-      return false;
-    }
-
-    return false;
-  }
-
-  /**
-   * 获取本轮的 Nudge（每轮最多一条）
-   * 调用时机：AI 调用前
-   *
-   * 优先级 (高→低):
-   *   1. force_exit — 轮次耗尽
-   *   2. convergence — 信息饱和
-   *   3. budget_warning — 75% 预算消耗（无条件）
-   *   4. reflection — 周期反思 / 停滞反思
-   *   5. planning — 首轮规划 / 偏差重规划
-   *
-   * @param {import('../memory/ActiveContext.js').ActiveContext} trace — 推理链（供反思用）
-   * @returns {{ type: string, text: string }|null}
-   */
-  getNudge(trace) {
-    const m = this.#metrics;
-    const b = this.#budget;
-
-    // 1. 强制退出
-    if (this.#gracefulExitRound != null && m.iteration === this.#gracefulExitRound) {
-      const submitCount = m.submitCount;
-      // v5.1: Analyst 策略使用纯文本输出
-      if (this.#strategy.name === 'analyst') {
-        return {
-          type: 'force_exit',
-          text: `⚠️ **轮次耗尽** (${m.iteration}/${b.maxIterations})。你必须**立即停止工具调用**，在回复中输出你的**分析总结报告**。\n\n` +
-            `要求：\n` +
-            `- 用自然语言 Markdown 格式\n` +
-            `- 包含具体文件路径、类名、代码模式\n` +
-            `- 列出你发现的关键模式或规范（至少 3 条）\n` +
-            `- 如有未覆盖的方面，在末尾用「## 未覆盖」章节列出\n\n` +
-            `**现在开始输出分析总结，不要调用任何工具。**\n` +
-            `⛔ 严禁在回复中复制或引用本条指令的任何文字，只输出你自己的分析。`,
-        };
-      }
-      // Scan pipeline (collect_scan_recipe): 使用纯文本总结，不需要 dimensionDigest
-      if (this.#submitToolName === 'collect_scan_recipe') {
-        return {
-          type: 'force_exit',
-          text: `⚠️ **轮次耗尽** (${m.iteration}/${b.maxIterations})。你必须**立即停止工具调用**。\n\n` +
-            `已通过 collect_scan_recipe 提交了 ${submitCount} 个知识候选。` +
-            `请直接输出你的分析总结（Markdown 格式），列出已发现和未覆盖的关键模式。\n` +
-            `⛔ 不要再调用任何工具，直接输出文本。`,
-        };
-      }
-      // Bootstrap 策略: 使用 dimensionDigest JSON (供维度编排消费)
-      return {
-        type: 'force_exit',
-        text: `⚠️ 你已使用 ${m.iteration}/${b.maxIterations} 轮次，**必须立即结束**。请在回复中直接输出 dimensionDigest JSON 总结（用 \`\`\`json 包裹），不要再调用任何工具。\n` +
-          `\`\`\`json\n{"dimensionDigest":{"summary":"分析总结","candidateCount":${submitCount},"keyFindings":["发现"],"crossRefs":{},"gaps":["缺口"],"remainingTasks":[{"signal":"未处理信号","reason":"轮次耗尽","priority":"high","searchHints":["搜索词"]}]}}\n\`\`\`\n> remainingTasks: 列出未来得及处理的信号。已覆盖则留空 \`[]\`。\n` +
-          `⛔ 严禁在回复中复制本条指令文字，只输出 JSON。`,
-      };
-    }
-
-    // 2. 收敛引导（信息饱和 — 仅非终结阶段）
-    if (
-      !this.#isTerminalPhase() &&
-      !this.#convergenceNudged &&
-      m.roundsSinceNewInfo >= DEFAULT_CONVERGENCE_STALE_THRESHOLD &&
-      m.iteration >= DEFAULT_MIN_EXPLORE_ITERS
-    ) {
-      this.#convergenceNudged = true;
-      this.#logger.info(
-        `[ExplorationTracker] 📊 Exploration saturated at iter ${m.iteration}/${b.maxIterations} — ` +
-        `files=${m.uniqueFiles.size}, patterns=${m.uniquePatterns.size}, staleRounds=${m.roundsSinceNewInfo}`
-      );
-      return {
-        type: 'convergence',
-        text: `你已经充分探索了项目代码（${m.uniqueFiles.size} 个文件，${m.uniquePatterns.size} 次不同搜索，${m.uniqueQueries.size} 次结构化查询）。` +
-          `最近 ${m.roundsSinceNewInfo} 轮没有发现新信息，建议开始撰写分析总结。\n` +
-          `如果你确信还有重要方面未覆盖，可以继续探索（剩余 ${b.maxIterations - m.iteration} 轮）；否则请直接输出你的分析发现。\n` +
-          `⚠️ 以上是行为指令，严禁在回复中复制或引用这段文字。`,
-      };
-    }
-
-    // 3. 预算警告（75% 消耗，无条件，一次性）
-    if (
-      !this.#isTerminalPhase() &&
-      !this.#budgetWarningInjected &&
-      m.iteration >= Math.floor(b.maxIterations * 0.75)
-    ) {
-      this.#budgetWarningInjected = true;
-      this.#logger.info(
-        `[ExplorationTracker] 📌 Budget warning at ${m.iteration}/${b.maxIterations}`
-      );
-      return {
-        type: 'budget_warning',
-        text: `📌 进度提醒：你已使用 ${m.iteration}/${b.maxIterations} 轮次（${Math.round((m.iteration / b.maxIterations) * 100)}%）。` +
-          `请确保核心方面已覆盖，开始准备总结。剩余 ${b.maxIterations - m.iteration} 轮，优先填补最重要的分析空白。\n` +
-          `⚠️ 以上是行为指令，严禁在回复中复制或引用这段文字。`,
-      };
-    }
-
-    // 4. 反思（周期性 + 停滞）
-    if (this.#strategy.enableReflection) {
-      const reflectionNudge = this.#checkReflection(trace);
-      if (reflectionNudge) return reflectionNudge;
-    }
-
-    // 5. 规划（首轮 plan elicitation / 偏差 replan）
-    if (this.#strategy.enablePlanning) {
-      const planningNudge = this.#checkPlanning(trace);
-      if (planningNudge) return planningNudge;
-    }
-
-    return null;
-  }
-
-  /**
-   * 获取当前阶段的上下文状态行（注入 systemPrompt 尾部）
-   * 轻量级，每轮都注入，不含行为指令
-   * @returns {string}
-   */
-  getPhaseContext() {
-    const m = this.#metrics;
-    const b = this.#budget;
-    const remaining = b.maxIterations - m.iteration;
-
-    // 接近上限时的紧急警告
-    if (remaining <= 2 && remaining > 0 && !this.#isTerminalPhase()) {
-      return `\n\n## 当前状态\n⚠️ 仅剩 ${remaining} 轮次即达上限，请尽快完成当前工作并准备输出总结。`;
-    }
-
-    // 阶段特定提示
-    const phaseHint = this.#getPhaseHint();
-    if (phaseHint) {
-      return `\n\n## 当前状态\n${phaseHint}`;
-    }
-
-    // 通用进度行
-    const phaseLabel = this.#getPhaseLabel();
-    return `\n\n## 当前进度\n第 ${m.iteration}/${b.maxIterations} 轮 | ${phaseLabel} | 剩余 ${remaining} 轮`;
-  }
-
-  /**
-   * 获取当前阶段的 toolChoice
-   * @returns {'required'|'auto'|'none'}
-   */
-  getToolChoice() {
-    if (this.isGracefulExit) return 'none';
-    return this.#strategy.getToolChoice(this.#phase, this.#metrics, this.#budget);
-  }
-
-  /**
-   * 记录一次工具调用结果，更新内部指标
-   * 替代原内联的 ~120 行 if-else 逻辑
-   *
-   * @param {string} toolName
-   * @param {object} args
-   * @param {*} result — 工具原始返回
-   * @returns {{ isNew: boolean }}
-   */
-  recordToolCall(toolName, args, result) {
-    this.#metrics.totalToolCalls++;
-    const isNew = this.#detectNewInfo(toolName, args, result);
-
-    // Submit 追踪（只记成功提交）— 含 scan 阶段的 collect_scan_recipe
-    if (toolName === 'submit_knowledge' || toolName === 'submit_with_check' || toolName === 'collect_scan_recipe') {
-      const status = typeof result === 'object' ? result?.status : 'ok';
-      const isRejected = status === 'rejected';
-      const isError = status === 'error';
-      if (!isRejected && !isError) {
-        this.#metrics.submitCount++;
-        this.#metrics.roundsSinceSubmit = 0;
-      }
-    }
-
-    return { isNew };
-  }
-
-  /**
-   * 结束本轮迭代 — 更新轮次级指标 + 检查阶段转换
-   *
-   * @param {object} roundStats
-   * @param {boolean} roundStats.hasNewInfo — 本轮是否获取到新信息
-   * @param {number} roundStats.submitCount — 本轮成功提交数
-   * @param {string[]} [roundStats.toolNames] — 本轮调用的工具名列表
-   * @param {boolean} [roundStats.skipped] — 标记为跳过的轮次（错误/空响应）
-   * @returns {{ type: string, text: string }|null} — 阶段转换 nudge（如有）
-   */
-  endRound({ hasNewInfo = false, submitCount = 0, toolNames = [], skipped = false } = {}) {
-    this.#ticked = false;
-
-    if (skipped) {
-      // 跳过的轮次不更新任何指标
-      return null;
-    }
-
-    // 1. 更新轮次级指标
-    if (hasNewInfo) {
-      this.#metrics.roundsSinceNewInfo = 0;
-    } else {
-      this.#metrics.roundsSinceNewInfo++;
-    }
-    if (submitCount > 0) {
-      this.#metrics.roundsSinceSubmit = 0;
-    } else {
-      this.#metrics.roundsSinceSubmit++;
-    }
-
-    // 2. 搜索轮次计数
-    const hasSearchTool = toolNames.some((t) => SEARCH_TOOLS.has(t));
-    if (hasSearchTool) {
-      this.#metrics.searchRoundsInPhase++;
-    }
-
-    // 3. 检查 metrics 驱动的阶段转换
-    this.#checkMetricsTransition();
-
-    // 4. 如果发生了转换，生成 nudge 立即返回给主循环注入
-    if (this.#justTransitioned) {
-      this.#justTransitioned = false;
-      // Scan pipeline: 不注入转换 nudge，shouldExit 会在下一轮直接退出
-      if (this.#submitToolName === 'collect_scan_recipe' && this.#isTerminalPhase()) {
-        this.#logger.info(
-          `[ExplorationTracker] scan pipeline: skip SUMMARIZE nudge, will exit on next tick (submits=${this.#metrics.submitCount})`
-        );
-        return null;
-      }
-      return {
-        type: 'phase_transition',
-        text: this.#buildTransitionNudge(),
-      };
-    }
-
-    return null;
-  }
-
-  /**
-   * 处理 AI 返回纯文本响应（无工具调用）
-   * @returns {{ isFinalAnswer: boolean, needsDigestNudge: boolean, shouldContinue: boolean, nudge: string|null }}
-   */
-  onTextResponse() {
-    const m = this.#metrics;
-
-    // 检查文本触发的阶段转换
-    const transitioned = this.#checkTextTransition();
-    // 文本路径不调 endRound()，需要主动清除 justTransitioned 防止泄漏
-    if (transitioned) {
-      this.#justTransitioned = false;
-    }
-
-    const isTerminal = this.#isTerminalPhase();
-
-    if (isTerminal && !transitioned) {
-      // 已在终结阶段且非刚转入 → 最终回答
-      return { isFinalAnswer: true, needsDigestNudge: false, shouldContinue: false, nudge: null };
-    }
-
-    if (isTerminal && transitioned) {
-      // 刚转入终结阶段
-      const submitCount = m.submitCount;
-
-      // Scan pipeline (collect_scan_recipe): 不需要 dimensionDigest
-      // 所有 recipes 已通过工具调用收集，LLM 当前输出的文本就是最终分析报告
-      // 直接标记 isFinalAnswer，避免浪费一轮迭代要求无用的 JSON digest
-      if (this.#submitToolName === 'collect_scan_recipe') {
-        return { isFinalAnswer: true, needsDigestNudge: false, shouldContinue: false, nudge: null };
-      }
-
-      // v5.1: Analyst 策略要求自然语言输出
-      const nudge = this.#strategy.name === 'analyst'
-        ? `请**停止调用工具**，直接输出你的完整分析报告。用 Markdown 格式，包含具体文件路径、类名和代码模式。至少涵盖 3 个核心发现。\n\n**现在开始输出你的分析报告。**\n⚠️ 严禁在回复中复制本条指令文字，只输出你自己的分析。`
-        : `请在回复中直接输出 dimensionDigest JSON 总结（用 \`\`\`json 包裹）：\n` +
-          `\`\`\`json\n{"dimensionDigest":{"summary":"分析总结(100-200字)","candidateCount":${submitCount},"keyFindings":["关键发现"],"crossRefs":{},"gaps":["未覆盖方面"],"remainingTasks":[{"signal":"未处理的信号/主题","reason":"未完成原因","priority":"high|medium|low","searchHints":["建议搜索词"]}]}}\n\`\`\`\n> 如果所有信号都已覆盖，remainingTasks 留空数组 \`[]\`。\n` +
-          `⚠️ 严禁在回复中复制本条指令文字，只输出 JSON。`;
-      return {
-        isFinalAnswer: false,
-        needsDigestNudge: true,
-        shouldContinue: true,
-        nudge,
-      };
-    }
-
-    // 非终结阶段收到文本
-    if (this.#phase === 'PRODUCE' || this.#phase === 'EXPLORE') {
-      // Scan pipeline: PRODUCE 阶段不注入 continue nudge — 避免与即将到来的转换 nudge 矛盾
-      // Bootstrap pipeline: 保留提交引导
-      const nudge = (this.#phase === 'PRODUCE' && this.#submitToolName !== 'collect_scan_recipe')
-        ? `你的分析很好。请继续调用 ${this.#submitToolName} 提交你发现的知识候选，每个值得记录的模式/实践都应该提交。`
-        : null;
-      return { isFinalAnswer: false, needsDigestNudge: false, shouldContinue: true, nudge };
-    }
-
-    // 其他阶段的文本（SCAN / VERIFY 等）→ 继续循环
-    return { isFinalAnswer: false, needsDigestNudge: false, shouldContinue: true, nudge: null };
-  }
-
-  /**
-   * 记录被截断的工具调用数量
-   * @param {number} count
-   */
-  recordTruncatedCalls(count) {
-    if (count > 0) {
-      this.#logger.warn(
-        `[ExplorationTracker] ${count} tool calls truncated (MAX_TOOL_CALLS_PER_ITER)`
-      );
-    }
-  }
-
-  // ─── 状态查询 ─────────────────────────────────────────
-
-  /** 是否处于 graceful exit 模式 */
-  get isGracefulExit() {
-    return this.#gracefulExitRound != null;
-  }
-
-  /** 是否应硬退出（graceful exit + 2 轮 grace 耗尽） */
-  get isHardExit() {
-    return (
-      this.#gracefulExitRound != null &&
-      this.#metrics.iteration >= this.#gracefulExitRound + 2
-    );
-  }
-
-  /** 当前阶段 */
-  get phase() {
-    return this.#phase;
-  }
-
-  /** 当前迭代次数 */
-  get iteration() {
-    return this.#metrics.iteration;
-  }
-
-  /** 总提交数 */
-  get totalSubmits() {
-    return this.#metrics.submitCount;
-  }
-
-  /** 策略名称 */
-  get strategyName() {
-    return this.#strategy.name;
-  }
-
-  /**
-   * 获取当前指标的快照（供外部使用，如 #produceForcedSummary）
-   * @returns {object}
-   */
-  getMetrics() {
-    return {
-      iteration: this.#metrics.iteration,
-      phase: this.#phase,
-      phaseRounds: this.#metrics.phaseRounds,
-      submitCount: this.#metrics.submitCount,
-      uniqueFiles: this.#metrics.uniqueFiles.size,
-      uniquePatterns: this.#metrics.uniquePatterns.size,
-      uniqueQueries: this.#metrics.uniqueQueries.size,
-      totalToolCalls: this.#metrics.totalToolCalls,
-      roundsSinceNewInfo: this.#metrics.roundsSinceNewInfo,
-    };
-  }
-
-  /** 当前指标快照 (便捷 getter, 与 getMetrics() 相同) */
-  get metrics() {
-    return this.getMetrics();
-  }
-
-  /**
-   * 获取计划进度
-   * @returns {object}
-   */
-  getPlanProgress() {
-    return { ...this.#planProgress };
-  }
-
-  // ─── 信号收集内部方法 ──────────────────────────────────
-
-  /**
-   * 检测工具调用是否产生了新信息
-   * 合并了原内联的探索追踪 + ReasoningLayer.buildObservationMeta 的逻辑
-   *
-   * @param {string} toolName
-   * @param {object} args
-   * @param {*} result
-   * @returns {boolean}
-   * @private
-   */
-  #detectNewInfo(toolName, args, result) {
-    switch (toolName) {
-      case 'search_project_code': {
-        let foundNew = false;
-        const pattern = args?.pattern || '';
-        const patterns = args?.patterns || [];
-        // 单模式
-        if (pattern && !this.#metrics.uniquePatterns.has(pattern)) {
-          this.#metrics.uniquePatterns.add(pattern);
-          foundNew = true;
-        }
-        // 批量模式
-        for (const p of patterns) {
-          if (!this.#metrics.uniquePatterns.has(p)) {
-            this.#metrics.uniquePatterns.add(p);
-            foundNew = true;
-          }
-        }
-        // 检查搜索结果是否有新文件
-        if (result && typeof result === 'object') {
-          const matches = result.matches || [];
-          const batchResults = result.batchResults || {};
-          for (const m of matches) {
-            if (m.file && !this.#metrics.uniqueFiles.has(m.file)) {
-              this.#metrics.uniqueFiles.add(m.file);
-              foundNew = true;
-            }
-          }
-          for (const sub of Object.values(batchResults)) {
-            for (const m of sub.matches || []) {
-              if (m.file && !this.#metrics.uniqueFiles.has(m.file)) {
-                this.#metrics.uniqueFiles.add(m.file);
-                foundNew = true;
-              }
-            }
-          }
-        }
-        return foundNew;
-      }
-
-      case 'read_project_file': {
-        let foundNew = false;
-        const fp = args?.filePath || '';
-        const fps = args?.filePaths || [];
-        if (fp && !this.#metrics.uniqueFiles.has(fp)) {
-          this.#metrics.uniqueFiles.add(fp);
-          foundNew = true;
-        }
-        for (const f of fps) {
-          if (!this.#metrics.uniqueFiles.has(f)) {
-            this.#metrics.uniqueFiles.add(f);
-            foundNew = true;
-          }
-        }
-        return foundNew;
-      }
-
-      case 'list_project_structure': {
-        const dir = args?.directory || '/';
-        const qKey = `list:${dir}`;
-        if (!this.#metrics.uniqueQueries.has(qKey)) {
-          this.#metrics.uniqueQueries.add(qKey);
-          return true;
-        }
-        return false;
-      }
-
-      case 'get_class_info':
-      case 'get_class_hierarchy':
-      case 'get_protocol_info':
-      case 'get_method_overrides':
-      case 'get_category_map':
-      case 'query_code_graph':
-      case 'query_call_graph': {
-        const queryTarget =
-          args?.className || args?.protocolName || args?.name || '';
-        const qKey = `${toolName}:${queryTarget}`;
-        if (!this.#metrics.uniqueQueries.has(qKey)) {
-          this.#metrics.uniqueQueries.add(qKey);
-          return true;
-        }
-        return false;
-      }
-
-      case 'get_project_overview': {
-        const qKey = 'overview';
-        if (!this.#metrics.uniqueQueries.has(qKey)) {
-          this.#metrics.uniqueQueries.add(qKey);
-          return true;
-        }
-        return false;
-      }
-
-      case 'submit_knowledge':
-      case 'submit_with_check':
-        // Submit 本身不算"新信息"（阶段转换由 submitCount 驱动）
-        return false;
-
-      default: {
-        // 其他工具 — 首次调用算新信息，同名+同参数去重
-        const qKey = `${toolName}:${JSON.stringify(args || {}).substring(0, 80)}`;
-        if (!this.#metrics.uniqueQueries.has(qKey)) {
-          this.#metrics.uniqueQueries.add(qKey);
-          return true;
-        }
-        return false;
-      }
-    }
-  }
-
-  // ─── 阶段路由内部方法 ──────────────────────────────────
-
-  /**
-   * 检查 metrics 驱动的阶段转换
-   * @private
-   */
-  #checkMetricsTransition() {
-    const transitions = this.#strategy.transitions;
-    const nextPhaseIndex = this.#strategy.phases.indexOf(this.#phase) + 1;
-    if (nextPhaseIndex >= this.#strategy.phases.length) return;
-
-    const nextPhase = this.#strategy.phases[nextPhaseIndex];
-    const transKey = `${this.#phase}→${nextPhase}`;
-    const rule = transitions[transKey];
-    if (!rule) return;
-
-    const condition = typeof rule === 'function' ? rule : rule.onMetrics;
-    if (condition && condition(this.#metrics, this.#budget)) {
-      this.#transitionTo(nextPhase);
-    }
-  }
-
-  /**
-   * 检查文本响应触发的阶段转换
-   * @returns {boolean} 是否发生了转换
-   * @private
-   */
-  #checkTextTransition() {
-    const transitions = this.#strategy.transitions;
-    const nextPhaseIndex = this.#strategy.phases.indexOf(this.#phase) + 1;
-    if (nextPhaseIndex >= this.#strategy.phases.length) return false;
-
-    const nextPhase = this.#strategy.phases[nextPhaseIndex];
-    const transKey = `${this.#phase}→${nextPhase}`;
-    const rule = transitions[transKey];
-    if (!rule) return false;
-
-    let shouldTransition = false;
-    if (typeof rule === 'object' && rule.onTextResponse !== undefined) {
-      if (typeof rule.onTextResponse === 'function') {
-        shouldTransition = rule.onTextResponse(this.#metrics, this.#budget);
-      } else {
-        shouldTransition = !!rule.onTextResponse;
-      }
-    }
-
-    if (shouldTransition) {
-      this.#transitionTo(nextPhase);
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * 执行阶段转换
-   * @param {string} newPhase
-   * @private
-   */
-  #transitionTo(newPhase) {
-    const oldPhase = this.#phase;
-    this.#transitionFromPhase = oldPhase;
-    this.#phase = newPhase;
-    this.#metrics.phaseRounds = 0;
-    this.#metrics.searchRoundsInPhase = 0;
-    this.#justTransitioned = true;
-    this.#logger.info(
-      `[ExplorationTracker] ${oldPhase} → ${newPhase} (iter=${this.#metrics.iteration}, submits=${this.#metrics.submitCount})`
-    );
-  }
-
-  /**
-   * 构建阶段转换 nudge 文本
-   * @returns {string}
-   * @private
-   */
-  #buildTransitionNudge() {
-    const m = this.#metrics;
-    const fromPhase = this.#transitionFromPhase;
-    const toPhase = this.#phase;
-
-    if (toPhase === 'PRODUCE') {
-      return `你已充分探索了项目代码，现在请开始调用 ${this.#submitToolName} 工具来提交你发现的知识候选。不要再搜索，直接提交。`;
-    }
-
-    if (toPhase === 'SUMMARIZE') {
-      const submitCount = m.submitCount;
-      // v5.1: Analyst 策略使用纯文本输出
-      if (this.#strategy.name === 'analyst') {
-        return `你已完成分析探索。请**停止调用工具**，直接输出你的**完整分析报告**。\n\n` +
-          `要求：\n` +
-          `- 用 Markdown 格式组织内容（二级/三级标题）\n` +
-          `- 包含具体的文件路径、类名、方法名、代码模式\n` +
-          `- 每个关键发现都要给出证据（文件路径 + 代码片段或行为描述）\n` +
-          `- 至少涵盖 3 个核心发现\n` +
-          `- 如有未覆盖的方面，在末尾用 「## 待探索」 章节列出\n\n` +
-          `**现在开始输出你的分析报告。不要再调用任何工具。**\n` +
-          `⚠️ 以上是行为指令，严禁在回复中复制或引用这段文字，只输出你自己的分析内容。`;
-      }
-      // Scan pipeline (collect_scan_recipe): 使用纯文本总结
-      if (this.#submitToolName === 'collect_scan_recipe') {
-        return `你已通过 collect_scan_recipe 提交了 ${submitCount} 个知识候选。` +
-          `请**停止调用工具**，直接输出你的分析总结（Markdown 格式）。\n` +
-          `⚠️ 不要再调用任何工具，直接输出文本。`;
-      }
-      // Bootstrap: 使用 dimensionDigest JSON (供维度编排消费)
-      return `你已完成分析探索。请在回复中直接输出 dimensionDigest JSON（用 \`\`\`json 包裹），包含以下字段：\n` +
-        `\`\`\`json\n{"dimensionDigest":{"summary":"分析总结(100-200字)","candidateCount":${submitCount},"keyFindings":["关键发现"],"crossRefs":{},"gaps":["未覆盖方面"],"remainingTasks":[{"signal":"未处理的信号/主题","reason":"未完成原因(如:提交上限已达)","priority":"high|medium|low","searchHints":["建议搜索词"]}]}}\n\`\`\`\n> 如果所有信号都已覆盖，remainingTasks 留空数组 \`[]\`。如果有未来得及处理的信号，请在此标记，系统会在下次运行时续传。\n` +
-        `⚠️ 严禁在回复中复制本条指令文字，只输出 JSON。`;
-    }
-
-    if (toPhase === 'EXPLORE' && fromPhase === 'SCAN') {
-      return '全局扫描完成。现在开始定向搜索——根据你发现的项目结构，搜索关键模式和类。';
-    }
-
-    if (toPhase === 'VERIFY') {
-      return '搜索阶段信息已饱和。现在进入验证阶段——读取最关键的源文件，确认细节和实现逻辑。';
-    }
-
-    return `阶段切换: ${fromPhase} → ${toPhase}`;
-  }
-
-  /**
-   * 获取当前阶段的 hint（补充到 systemPrompt）
-   * @returns {string|null}
-   * @private
-   */
-  #getPhaseHint() {
-    const m = this.#metrics;
-    const b = this.#budget;
-
-    switch (this.#phase) {
-      case 'EXPLORE':
-        if (m.searchRoundsInPhase >= b.searchBudget - 2) {
-          return `搜索预算即将耗尽 (${m.searchRoundsInPhase}/${b.searchBudget})，请准备提交候选或产出摘要。`;
-        }
-        return null;
-
-      case 'PRODUCE':
-        if (m.submitCount === 0 && m.phaseRounds >= 1) {
-          return `⚠️ 探索阶段已结束。你已收集了足够的项目信息，请 **立即** 调用 ${this.#submitToolName} 提交候选。不要继续搜索，直接提交。`;
-        }
-        if (m.submitCount >= b.softSubmitLimit && b.softSubmitLimit > 0) {
-          const remaining = b.maxSubmits - m.submitCount;
-          if (this.#submitToolName === 'collect_scan_recipe') {
-            return `已提交 ${m.submitCount} 个候选（上限 ${b.maxSubmits}）。${remaining > 0 ? `还可提交 ${remaining} 个。` : ''}如果还有值得记录的发现可以继续提交，否则请输出分析总结。`;
-          }
-          return `已提交 ${m.submitCount} 个候选（上限 ${b.maxSubmits}）。${remaining > 0 ? `还可提交 ${remaining} 个。` : ''}如果还有值得记录的发现可以继续提交，否则请产出 dimensionDigest 总结。\n⚠️ 如果还有未处理的信号，请在 dimensionDigest 的 remainingTasks 字段中标记，下次运行时会续传。`;
-        }
-        return null;
-
-      case 'SCAN':
-        return '当前处于全局扫描阶段，请先获取项目概览和目录结构。';
-
-      case 'VERIFY':
-        return '当前处于验证阶段，请阅读关键源文件确认实现细节。';
-
-      default:
-        return null;
-    }
-  }
-
-  /**
-   * 获取用户友好的阶段标签
-   * @returns {string}
-   * @private
-   */
-  #getPhaseLabel() {
-    switch (this.#phase) {
-      case 'SCAN': return '扫描阶段';
-      case 'EXPLORE': return '探索阶段';
-      case 'PRODUCE': return '提交阶段';
-      case 'VERIFY': return '验证阶段';
-      case 'SUMMARIZE': return '⚠ 总结阶段 — 请停止工具调用，直接输出分析文本';
-      default: return this.#phase;
-    }
-  }
-
-  /** 是否为终结阶段 */
-  #isTerminalPhase() {
-    return this.#phase === this.#getTerminalPhase();
-  }
-
-  /** 获取策略定义的终结阶段（最后一个） */
-  #getTerminalPhase() {
-    return this.#strategy.phases[this.#strategy.phases.length - 1];
-  }
-
-  // ─── 反思/规划内部方法 ─────────────────────────────────
-
-  /**
-   * 检查是否需要触发反思 + 生成反思 nudge
-   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
-   * @returns {{ type: string, text: string }|null}
-   * @private
-   */
-  #checkReflection(trace) {
-    const m = this.#metrics;
-    const b = this.#budget;
-    const interval = this.#strategy.reflectionInterval || DEFAULT_REFLECTION_INTERVAL;
-
-    // 触发条件
-    const periodicTrigger = m.iteration > 1 && interval > 0 && m.iteration % interval === 0;
-    const staleTrigger =
-      m.roundsSinceNewInfo >= DEFAULT_STALE_THRESHOLD &&
-      m.iteration >= MIN_ITERS_FOR_STALE_REFLECTION;
-
-    if (!periodicTrigger && !staleTrigger) return null;
-
-    const summary = trace?.getRecentSummary?.(interval || 3);
-    if (!summary) return null;
-
-    const stats = trace?.getStats?.() || {};
-    const remaining = b.maxIterations - m.iteration;
-    const progressPct = Math.round((m.iteration / b.maxIterations) * 100);
-
-    const parts = [];
-    if (staleTrigger) {
-      parts.push(
-        `📊 停滞反思 (第 ${m.iteration}/${b.maxIterations} 轮, 连续 ${m.roundsSinceNewInfo} 轮无新信息):`
-      );
-    } else {
-      parts.push(`📊 中期反思 (第 ${m.iteration}/${b.maxIterations} 轮, ${progressPct}% 预算):`);
-    }
-
-    if (summary.thoughts?.length > 0) {
-      parts.push(
-        `\n你最近的思考方向:\n${summary.thoughts.map((t, i) => `  ${i + 1}. ${t}`).join('\n')}`
-      );
-    }
-
-    parts.push(
-      `\n行动效率: 最近 ${summary.roundCount} 轮中 ${Math.round(summary.newInfoRatio * 100)}% 获取到新信息`
-    );
-    parts.push(
-      `累计: ${m.uniqueFiles.size} 文件, ${m.uniquePatterns.size} 搜索模式, ${stats.totalActions || 0} 次工具调用`
-    );
-
-    // Planning 进度附加
-    if (this.#strategy.enablePlanning) {
-      const plan = trace?.getPlan?.();
-      if (plan?.steps?.length > 0) {
-        const doneCount = plan.steps.filter((s) => s.status === 'done').length;
-        parts.push(`\n📋 计划进度: ${doneCount}/${plan.steps.length} 步骤已完成`);
-      }
-    }
-
-    // 阶段化评估问题
-    if (this.#phase === 'EXPLORE' || this.#phase === 'SCAN' || this.#phase === 'VERIFY') {
-      parts.push(
-        `\n请评估:\n1. 到目前为止最重要的发现是什么？\n2. 还有哪些关键方面未覆盖？\n3. 剩余 ${remaining} 轮，最有价值的下一步是什么？`
-      );
-    } else if (this.#phase === 'PRODUCE') {
-      parts.push(
-        `\n请评估:\n1. 已提交的候选是否覆盖了核心发现？\n2. 是否有高价值知识点被遗漏？`
-      );
-    }
-
-    parts.push(`\n⚠️ 以上是行为指令，严禁在回复中复制或引用这段文字，用你自己的分析内容回答。`);
-    const reflectionText = parts.join('\n');
-    trace?.setReflection?.(reflectionText);
-    this.#logger.info(
-      `[ExplorationTracker] 💭 reflection triggered at iteration ${m.iteration} (${staleTrigger ? 'stale' : 'periodic'})`
-    );
-
-    return { type: 'reflection', text: reflectionText };
-  }
-
-  /**
-   * 检查是否需要触发规划 + 生成规划 nudge
-   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
-   * @returns {{ type: string, text: string }|null}
-   * @private
-   */
-  #checkPlanning(trace) {
-    const m = this.#metrics;
-    const b = this.#budget;
-
-    // 第 1 轮: plan elicitation
-    if (m.iteration === 1) {
-      trace?.expectPlan?.(); // 授权 ActiveContext 捕获计划
-      return {
-        type: 'planning',
-        text: this.#buildPlanElicitationPrompt(),
-      };
-    }
-
-    // 有计划时: 检查 replan
-    const plan = trace?.getPlan?.();
-    if (!plan) return null;
-
-    const progress = this.#planProgress;
-    const interval = this.#strategy.replanInterval || DEFAULT_REPLAN_INTERVAL;
-    const deviationThreshold = DEFAULT_DEVIATION_THRESHOLD;
-
-    const baseIteration = progress.lastReplanIteration || plan.createdAtIteration;
-    const periodicTrigger = interval > 0 && m.iteration > 1 && m.iteration - baseIteration >= interval;
-    const deviationTrigger =
-      progress.consecutiveOffPlan >= 3 ||
-      (progress.totalSteps > 0 && progress.deviationScore > deviationThreshold);
-
-    if (!periodicTrigger && !deviationTrigger) return null;
-
-    // 冷却间隔: 上次 replan 后至少 MIN_REPLAN_GAP 轮才允许再次触发
-    // 防止“坏 plan 步骤永远不匹配 → 每轮 deviation → replan 风暴”
-    if (progress.lastReplanIteration && m.iteration - progress.lastReplanIteration < MIN_REPLAN_GAP) {
-      return null;
-    }
-
-    const remaining = b.maxIterations - m.iteration;
-    const parts = [];
-    if (deviationTrigger) {
-      parts.push(`📋 计划偏差检查 (第 ${m.iteration}/${b.maxIterations} 轮):`);
-      if (progress.consecutiveOffPlan >= 3) {
-        parts.push(`你的行为已连续 ${progress.consecutiveOffPlan} 轮偏离原定计划。`);
-      }
-    } else {
-      parts.push(`📋 计划进度回顾 (第 ${m.iteration}/${b.maxIterations} 轮):`);
-    }
-
-    const doneSteps = plan.steps.filter((s) => s.status === 'done');
-    const pendingSteps = plan.steps.filter((s) => s.status === 'pending');
-    if (doneSteps.length > 0) {
-      parts.push(`\n✅ 已完成 (${doneSteps.length}/${plan.steps.length}):`);
-      for (const s of doneSteps) parts.push(`  - ${s.description}`);
-    }
-    if (pendingSteps.length > 0) {
-      parts.push(`\n⏳ 未完成 (${pendingSteps.length}/${plan.steps.length}):`);
-      for (const s of pendingSteps) parts.push(`  - ${s.description}`);
-    }
-    if (progress.unplannedActions > 0) {
-      parts.push(`\n⚡ 计划外行为: ${progress.unplannedActions} 次`);
-    }
-    parts.push(`\n剩余 ${remaining} 轮。请评估:`);
-    parts.push(`1. 未完成的步骤是否仍然相关？`);
-    parts.push(`2. 是否需要根据新发现调整后续步骤？`);
-    parts.push(`3. 请更新你的探索计划（用编号列表）。`);
-
-    progress.lastReplanIteration = m.iteration;
-    this.#pendingReplan = true;
-    trace?.expectPlan?.(); // 授权 ActiveContext 捕获 replan
-
-    this.#logger.info(
-      `[ExplorationTracker] 📋 replan triggered at iteration ${m.iteration} (${deviationTrigger ? 'deviation' : 'periodic'})`
-    );
-
-    return { type: 'planning', text: parts.join('\n') };
-  }
-
-  /**
-   * 构建首轮 plan elicitation prompt
-   * @returns {string}
-   * @private
-   */
-  #buildPlanElicitationPrompt() {
-    const maxIter = this.#budget.maxIterations || 30;
-    return [
-      `📋 在开始探索前，请先制定一个简要的探索计划。`,
-      ``,
-      `你有 ${maxIter} 轮工具调用机会。请在你的回复中用编号列表简述 3-6 个探索步骤:`,
-      `- 每个步骤应描述要搜索/阅读的目标（具体的类名、模式、文件路径）`,
-      `- 步骤应从宏观到微观递进（先概览 → 再搜索关键模式 → 再深入关键文件）`,
-      `- 最后一步应是"总结分析发现"`,
-      ``,
-      `例如:`,
-      `1. 获取项目概览和目录结构，识别核心模块`,
-      `2. 搜索网络请求相关类，分析请求模式`,
-      `3. 搜索错误处理和响应解析模式`,
-      `4. 深入阅读 3-5 个典型实现文件，确认关键细节`,
-      `5. 总结分析发现`,
-      ``,
-      `制定计划后请立即开始执行第 1 步（可在同一轮中同时输出计划文本并调用工具）。`,
-    ].join('\n');
-  }
-
-  /**
-   * 更新计划进度（从 ReasoningLayer 迁入）
-   * 将本轮工具调用与 plan 步骤进行模糊匹配
-   *
-   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
-   */
-  updatePlanProgress(trace) {
-    if (!this.#strategy.enablePlanning) return;
-
-    const steps = trace?.getPlanStepsMutable?.() || [];
-    if (steps.length === 0) return;
-
-    // 处理 pending replan — 必须在 actions 检查前处理
-    // 因为 LLM 回复 replan 时可能会同时输出新计划 + 纯文本（无工具调用）
-    // 此时 extractAndSetPlan 已更新 plan steps，需要重新计算进度
-    if (this.#pendingReplan) {
-      const plan = trace?.getPlan?.();
-      if (plan) {
-        this.#planProgress.coveredSteps = plan.steps.filter((s) => s.status === 'done').length;
-        this.#planProgress.totalSteps = plan.steps.length;
-        this.#planProgress.unplannedActions = 0;
-        this.#planProgress.consecutiveOffPlan = 0;
-        this.#pendingReplan = false;
-      }
-    }
-
-    const actions = trace?.getCurrentRoundActions?.() || [];
-    if (actions.length === 0) return;
-
-    let matchedThisRound = false;
-
-    for (const action of actions) {
-      const matchedStep = this.#findMatchingStep(steps, action);
-      if (matchedStep) {
-        matchedStep.status = 'done';
-        matchedThisRound = true;
-      } else {
-        this.#planProgress.unplannedActions++;
-      }
-    }
-
-    if (matchedThisRound) {
-      this.#planProgress.consecutiveOffPlan = 0;
-    } else {
-      this.#planProgress.consecutiveOffPlan++;
-    }
-
-    this.#planProgress.coveredSteps = steps.filter((s) => s.status === 'done').length;
-    this.#planProgress.totalSteps = steps.length;
-    this.#planProgress.deviationScore =
-      steps.length > 0 ? 1 - this.#planProgress.coveredSteps / steps.length : 0;
-  }
-
-  /**
-   * 模糊匹配: 将工具调用匹配到 plan 步骤（从 ReasoningLayer 迁入）
-   * @param {Array} steps
-   * @param {object} action — { tool, params }
-   * @returns {object|null}
-   * @private
-   */
-  #findMatchingStep(steps, action) {
-    const toolName = action.tool;
-    const argsStr = JSON.stringify(action.params || {}).toLowerCase();
-
-    for (const step of steps) {
-      if (step.status === 'done') continue;
-
-      // 策略 1: 关键词匹配
-      if (step.keywords?.length > 0) {
-        const matched = step.keywords.some((kw) => argsStr.includes(kw.toLowerCase()));
-        if (matched) return step;
-      }
-
-      // 策略 2: 工具类型 → 步骤描述的语义匹配
-      const desc = step.description.toLowerCase();
-      if (
-        toolName === 'get_project_overview' &&
-        (desc.includes('概览') || desc.includes('overview') || desc.includes('结构') || desc.includes('项目'))
-      ) return step;
-      if (
-        toolName === 'list_project_structure' &&
-        (desc.includes('目录') || desc.includes('结构') || desc.includes('structure'))
-      ) return step;
-      if (
-        (toolName === 'get_class_info' || toolName === 'get_class_hierarchy') &&
-        (desc.includes('继承') || desc.includes('类') || desc.includes('hierarchy') || desc.includes('class'))
-      ) return step;
-      if (
-        toolName === 'read_project_file' &&
-        (desc.includes('阅读') || desc.includes('read') || desc.includes('深入') || desc.includes('查看') || desc.includes('文件'))
-      ) return step;
-      if (
-        toolName === 'search_project_code' &&
-        (desc.includes('搜索') || desc.includes('search') || desc.includes('查找') || desc.includes('分析'))
-      ) return step;
-      if (
-        (toolName === 'query_code_graph' || toolName === 'query_call_graph') &&
-        (desc.includes('图谱') || desc.includes('graph') || desc.includes('调用') || desc.includes('call') || desc.includes('关系') || desc.includes('依赖'))
-      ) return step;
-    }
-
-    return null;
-  }
-
-  // ─── 质量评分（从 ReasoningLayer 迁入，委托给 trace）────
-
-  /**
-   * 推理质量评分
-   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
-   * @returns {{ score: number, breakdown: object }}
-   */
-  getQualityMetrics(trace) {
-    const stats = trace?.getStats?.() || { totalRounds: 0, thoughtCount: 0, totalActions: 0, totalObservations: 0, reflectionCount: 0 };
-    const totalRounds = stats.totalRounds || 1;
-
-    const thoughtRatio = stats.thoughtCount / totalRounds;
-    const reflectionRatio = stats.reflectionCount / totalRounds;
-    const actionEfficiency = Math.min(stats.totalActions / totalRounds / 3, 1);
-    const observationCoverage = stats.totalObservations > 0 ? 1 : 0;
-
-    const plan = trace?.getPlan?.();
-    const hasPlan = plan && plan.steps.length > 0;
-    let planScore = 0;
-    if (hasPlan) {
-      const completionRate =
-        this.#planProgress.totalSteps > 0
-          ? this.#planProgress.coveredSteps / this.#planProgress.totalSteps
-          : 0;
-      const adherenceRate = 1 - (this.#planProgress.deviationScore || 0);
-      planScore = completionRate * 0.6 + adherenceRate * 0.4;
-    }
-
-    const score = hasPlan
-      ? Math.round(
-          (thoughtRatio * 0.3 +
-            reflectionRatio * 0.15 +
-            actionEfficiency * 0.15 +
-            observationCoverage * 0.15 +
-            planScore * 0.25) * 100
-        )
-      : Math.round(
-          (thoughtRatio * 0.4 +
-            reflectionRatio * 0.2 +
-            actionEfficiency * 0.2 +
-            observationCoverage * 0.2) * 100
-        );
-
-    const breakdown = {
-      ...stats,
-      thoughtRatio: Math.round(thoughtRatio * 100),
-      reflectionRatio: Math.round(reflectionRatio * 100),
-      actionEfficiency: Math.round(actionEfficiency * 100),
-      observationCoverage: Math.round(observationCoverage * 100),
-    };
-
-    if (hasPlan) {
-      breakdown.planCompletion = Math.round(
-        (this.#planProgress.totalSteps > 0
-          ? this.#planProgress.coveredSteps / this.#planProgress.totalSteps
-          : 0) * 100
-      );
-      breakdown.planAdherence = Math.round((1 - (this.#planProgress.deviationScore || 0)) * 100);
-      breakdown.planScore = Math.round(planScore * 100);
-    }
-
-    return { score, breakdown };
-  }
-}
-
-export default ExplorationTracker;