autosnippet 3.2.8 → 3.2.10

package/lib/service/{chat → agent/context}/ExplorationTracker.js

@@ -3,7 +3,7 @@
  *
  * 合并了三个原本各自为政的系统:
  *   1. PhaseRouter (ContextWindow.js) — 阶段状态机
- *   2. 探索进度追踪 (ChatAgent.js 内联) — 信息增量检测
+ *   2. 探索进度追踪 (原内联逻辑) — 信息增量检测
  *   3. ReasoningLayer 行为控制部分 — 反思/规划/停滞 nudge
  *
  * 职责:
@@ -21,7 +21,7 @@
  * @module ExplorationTracker
  */
 
-import Logger from '../../infrastructure/logging/Logger.js';
+import Logger from '../../../infrastructure/logging/Logger.js';
 
 // ─── 常量 ──────────────────────────────────────────────
 
@@ -39,11 +39,13 @@ 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 策略（原始 ChatAgent，有 submit 阶段）
+ * Bootstrap 策略（有 submit 阶段）
  * @param {boolean} isSkillOnly — skill-only 维度跳过 PRODUCE 阶段
  * @returns {object} 策略配置
  */
@@ -227,6 +229,8 @@ export class ExplorationTracker {
 
   /** @type {boolean} tick 是否已调用（用于 rollback） */
   #ticked = false;
+  /** @type {string} 提交工具名（用于 nudge 文本生成） */
+  #submitToolName = 'submit_knowledge';
 
   /**
    * @param {object} strategy — 策略配置对象
@@ -234,7 +238,20 @@ export class ExplorationTracker {
    */
   constructor(strategy, budget) {
     this.#strategy = strategy;
-    this.#budget = budget;
+    // 合并默认值: 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();
   }
@@ -243,7 +260,7 @@ export class ExplorationTracker {
 
   /**
    * 根据调用参数解析应使用的策略
-   * @param {object} opts — ChatAgent execute 的选项
+   * @param {object} opts — AgentRuntime execute 的选项
    * @param {object} budget — 预算配置
    * @returns {ExplorationTracker|null} — User 模式返回 null
    */
@@ -295,11 +312,20 @@ export class ExplorationTracker {
     }
   }
 
+  /** 提交工具名 (供外部判断是否为 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;
@@ -336,7 +362,7 @@ export class ExplorationTracker {
    *   4. reflection — 周期反思 / 停滞反思
    *   5. planning — 首轮规划 / 偏差重规划
    *
-   * @param {import('./memory/ActiveContext.js').ActiveContext} trace — 推理链（供反思用）
+   * @param {import('../memory/ActiveContext.js').ActiveContext} trace — 推理链（供反思用）
    * @returns {{ type: string, text: string }|null}
    */
   getNudge(trace) {
@@ -346,7 +372,7 @@ export class ExplorationTracker {
     // 1. 强制退出
     if (this.#gracefulExitRound != null && m.iteration === this.#gracefulExitRound) {
       const submitCount = m.submitCount;
-      // v5.1: Analyst 策略使用纯文本输出，其他策略使用 dimensionDigest JSON
+      // v5.1: Analyst 策略使用纯文本输出
       if (this.#strategy.name === 'analyst') {
         return {
           type: 'force_exit',
@@ -360,6 +386,17 @@ export class ExplorationTracker {
             `⛔ 严禁在回复中复制或引用本条指令的任何文字，只输出你自己的分析。`,
         };
       }
+      // 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` +
@@ -459,7 +496,7 @@ export class ExplorationTracker {
 
   /**
    * 记录一次工具调用结果，更新内部指标
-   * 替代 ChatAgent 中内联的 ~120 行 if-else 逻辑
+   * 替代原内联的 ~120 行 if-else 逻辑
    *
    * @param {string} toolName
    * @param {object} args
@@ -470,8 +507,8 @@ export class ExplorationTracker {
     this.#metrics.totalToolCalls++;
     const isNew = this.#detectNewInfo(toolName, args, result);
 
-    // Submit 追踪（只记成功提交）
-    if (toolName === 'submit_knowledge' || toolName === 'submit_with_check') {
+    // 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';
@@ -526,6 +563,13 @@ export class ExplorationTracker {
     // 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(),
@@ -557,8 +601,16 @@ export class ExplorationTracker {
     }
 
     if (isTerminal && transitioned) {
-      // 刚转入终结阶段 → 需要 digest nudge，不是最终回答
+      // 刚转入终结阶段
       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⚠️ 严禁在回复中复制本条指令文字，只输出你自己的分析。`
@@ -575,9 +627,10 @@ export class ExplorationTracker {
 
     // 非终结阶段收到文本
     if (this.#phase === 'PRODUCE' || this.#phase === 'EXPLORE') {
-      // PRODUCE 阶段中间文本 → 继续循环，注入提交引导
-      const nudge = this.#phase === 'PRODUCE'
-        ? '你的分析很好。请继续调用 submit_knowledge 提交你发现的知识候选，每个值得记录的模式/实践都应该提交。'
+      // 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 };
     }
@@ -641,6 +694,7 @@ export class ExplorationTracker {
     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,
@@ -650,6 +704,11 @@ export class ExplorationTracker {
     };
   }
 
+  /** 当前指标快照 (便捷 getter, 与 getMetrics() 相同) */
+  get metrics() {
+    return this.getMetrics();
+  }
+
   /**
    * 获取计划进度
    * @returns {object}
@@ -662,7 +721,7 @@ export class ExplorationTracker {
 
   /**
    * 检测工具调用是否产生了新信息
-   * 合并了 ChatAgent 内联的探索追踪 + ReasoningLayer.buildObservationMeta 的逻辑
+   * 合并了原内联的探索追踪 + ReasoningLayer.buildObservationMeta 的逻辑
    *
    * @param {string} toolName
    * @param {object} args
@@ -861,7 +920,7 @@ export class ExplorationTracker {
     const toPhase = this.#phase;
 
     if (toPhase === 'PRODUCE') {
-      return '你已充分探索了项目代码，现在请开始调用 submit_knowledge 工具来提交你发现的知识候选。不要再搜索，直接提交。';
+      return `你已充分探索了项目代码，现在请开始调用 ${this.#submitToolName} 工具来提交你发现的知识候选。不要再搜索，直接提交。`;
     }
 
     if (toPhase === 'SUMMARIZE') {
@@ -878,6 +937,13 @@ export class ExplorationTracker {
           `**现在开始输出你的分析报告。不要再调用任何工具。**\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。`;
@@ -912,10 +978,13 @@ export class ExplorationTracker {
 
       case 'PRODUCE':
         if (m.submitCount === 0 && m.phaseRounds >= 1) {
-          return '⚠️ 探索阶段已结束。你已收集了足够的项目信息，请 **立即** 调用 submit_knowledge 提交候选。不要继续搜索，直接提交。';
+          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;
@@ -961,7 +1030,7 @@ export class ExplorationTracker {
 
   /**
    * 检查是否需要触发反思 + 生成反思 nudge
-   * @param {import('./memory/ActiveContext.js').ActiveContext} trace
+   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
    * @returns {{ type: string, text: string }|null}
    * @private
    */
@@ -1039,7 +1108,7 @@ export class ExplorationTracker {
 
   /**
    * 检查是否需要触发规划 + 生成规划 nudge
-   * @param {import('./memory/ActiveContext.js').ActiveContext} trace
+   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
    * @returns {{ type: string, text: string }|null}
    * @private
    */
@@ -1049,6 +1118,7 @@ export class ExplorationTracker {
 
     // 第 1 轮: plan elicitation
     if (m.iteration === 1) {
+      trace?.expectPlan?.(); // 授权 ActiveContext 捕获计划
       return {
         type: 'planning',
         text: this.#buildPlanElicitationPrompt(),
@@ -1071,6 +1141,12 @@ export class ExplorationTracker {
 
     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) {
@@ -1102,6 +1178,7 @@ export class ExplorationTracker {
 
     progress.lastReplanIteration = m.iteration;
     this.#pendingReplan = true;
+    trace?.expectPlan?.(); // 授权 ActiveContext 捕获 replan
 
     this.#logger.info(
       `[ExplorationTracker] 📋 replan triggered at iteration ${m.iteration} (${deviationTrigger ? 'deviation' : 'periodic'})`
@@ -1140,7 +1217,7 @@ export class ExplorationTracker {
    * 更新计划进度（从 ReasoningLayer 迁入）
    * 将本轮工具调用与 plan 步骤进行模糊匹配
    *
-   * @param {import('./memory/ActiveContext.js').ActiveContext} trace
+   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
    */
   updatePlanProgress(trace) {
     if (!this.#strategy.enablePlanning) return;
@@ -1148,6 +1225,20 @@ export class ExplorationTracker {
     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;
 
@@ -1173,18 +1264,6 @@ export class ExplorationTracker {
     this.#planProgress.totalSteps = steps.length;
     this.#planProgress.deviationScore =
       steps.length > 0 ? 1 - this.#planProgress.coveredSteps / steps.length : 0;
-
-    // 处理 pending replan
-    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;
-      }
-    }
   }
 
   /**
@@ -1242,7 +1321,7 @@ export class ExplorationTracker {
 
   /**
    * 推理质量评分
-   * @param {import('./memory/ActiveContext.js').ActiveContext} trace
+   * @param {import('../memory/ActiveContext.js').ActiveContext} trace
    * @returns {{ score: number, breakdown: object }}
    */
   getQualityMetrics(trace) {

package/lib/service/{chat → agent/core}/ChatAgentPrompts.js

@@ -1,5 +1,5 @@
 /**
- * ChatAgentPrompts — ChatAgent 提示词构建和文本处理方法（从 ChatAgent.js 提取）
+ * ChatAgentPrompts — Agent 提示词构建和文本处理方法
  */
 
 import fs from 'node:fs';
@@ -152,8 +152,10 @@ export function cleanFinalAnswer(response) {
     .replace(/^\*{0,2}(?:请在|请直接|请确保|请务必|现在开始|输出你的|不要输出|不要再|不要包含|重要\s*[：:]).*(?:分析文本|分析总结|JSON|工具|输出|文本|报告)\*{0,2}[。.]?\s*$/gm, '')
     .replace(/^注意[：:]\s*到达第\s*\d+\s*轮时.*$/gm, '')
     .replace(/^第\s*\d+\/\d+\s*轮\s*\|[^\n]*$/gm, '')
-    // 清理 dimensionDigest JSON 块（Analyst 回显）
-    .replace(/```json\s*\n\s*\{\s*"dimensionDigest"\s*:[\s\S]*?\n```/g, '')
+    // v5.2: 移除 dimensionDigest JSON 剥离
+    // 之前会把 SUMMARIZE 阶段 LLM 按要求产出的 dimensionDigest JSON 全部删掉 → 0 chars
+    // dimensionDigest 是 SUMMARIZE 的预期输出，不应被 cleanFinalAnswer 清理
+    // Analyst 策略的 SUMMARIZE 使用自然语言 Markdown（不含 dimensionDigest），不受影响
     .replace(/\n{3,}/g, '\n\n')
     .trim();
 }

package/lib/service/agent/core/LoopContext.js

@@ -0,0 +1,170 @@
+/**
+ * LoopContext — reactLoop 单次执行的完整状态
+ *
+ * 封装原 reactLoop 内散落的 10+ 局部变量:
+ *   - 注入依赖 (messages, tracker, trace, memoryCoordinator, sharedState)
+ *   - 循环状态 (iteration, lastReply, toolCalls, tokenUsage)
+ *   - 错误恢复 (consecutiveAiErrors, consecutiveEmptyResponses)
+ *   - 配置 (source, budget, capabilities, baseSystemPrompt, toolSchemas, prompt)
+ *
+ * 使 reactLoop 的提取方法只需接收一个 ctx 参数。
+ *
+ * @module core/LoopContext
+ */
+
+/**
+ * @typedef {Object} LoopContextConfig
+ * @property {import('./MessageAdapter.js').MessageAdapter} messages — 统一消息适配器
+ * @property {Object|null} [tracker] — ExplorationTracker 实例
+ * @property {Object|null} [trace] — ActiveContext 实例
+ * @property {Object|null} [memoryCoordinator] — MemoryCoordinator 实例
+ * @property {Object|null} [sharedState] — 共享状态 { submittedTitles, submittedPatterns }
+ * @property {string} [source] — 'user' | 'system'
+ * @property {Object} budget — 预算配置
+ * @property {import('../capabilities.js').Capability[]} capabilities — 本轮使用的 capabilities
+ * @property {string} baseSystemPrompt — 基础系统提示词
+ * @property {Array} toolSchemas — 工具 schema 列表
+ * @property {string} prompt — 原始用户提示
+ * @property {Function|null} [onToolCall] — 本轮工具调用钩子
+ * @property {Object} [context] — 额外上下文
+ * @property {import('../context/ContextWindow.js').ContextWindow|null} [contextWindow] — 原始 ContextWindow (供 forced-summary 等外部逻辑)
+ */
+
+export class LoopContext {
+  // ─── 注入依赖 ───
+
+  /** @type {import('./MessageAdapter.js').MessageAdapter} 统一消息适配器 */
+  messages;
+
+  /** @type {Object|null} ExplorationTracker 实例 */
+  tracker;
+
+  /** @type {Object|null} ActiveContext 实例 */
+  trace;
+
+  /** @type {Object|null} MemoryCoordinator 实例 */
+  memoryCoordinator;
+
+  /** @type {Object|null} 共享状态 */
+  sharedState;
+
+  // ─── 循环状态 ───
+
+  /** @type {number} 当前迭代次数 */
+  iteration = 0;
+
+  /** @type {string} 最终回复文本 */
+  lastReply = '';
+
+  /** @type {Array} 本轮工具调用记录 */
+  toolCalls = [];
+
+  /** @type {{input: number, output: number}} 本轮 token 用量 */
+  tokenUsage = { input: 0, output: 0 };
+
+  /** @type {number} 循环开始时间戳 */
+  loopStartTime = 0;
+
+  // ─── 错误恢复 ───
+
+  /** @type {number} 连续 AI 错误计数 (2-strike 策略) */
+  consecutiveAiErrors = 0;
+
+  /** @type {number} 连续空响应计数 */
+  consecutiveEmptyResponses = 0;
+
+  // ─── 配置 (只读) ───
+
+  /** @type {string} 来源 'user' | 'system' */
+  source;
+
+  /** @type {Object} 预算配置 */
+  budget;
+
+  /** @type {import('../capabilities.js').Capability[]} */
+  capabilities;
+
+  /** @type {string} 基础系统提示词 */
+  baseSystemPrompt;
+
+  /** @type {Array} 工具 schemas */
+  toolSchemas;
+
+  /** @type {string} 原始用户提示 */
+  prompt;
+
+  /** @type {Function|null} 工具调用钩子 */
+  onToolCall;
+
+  /** @type {Object} 额外上下文 */
+  context;
+
+  /** @type {import('../../chat/ContextWindow.js').ContextWindow|null} 原始 ContextWindow 引用 */
+  contextWindow;
+
+  /** @type {string|null} 首轮 toolChoice 覆盖 ('required'/'auto'/'none') */
+  toolChoiceOverride;
+
+  /**
+   * @param {LoopContextConfig} config
+   */
+  constructor(config) {
+    this.messages = config.messages;
+    this.tracker = config.tracker || null;
+    this.trace = config.trace || null;
+    this.memoryCoordinator = config.memoryCoordinator || null;
+    this.sharedState = config.sharedState || null;
+    this.source = config.source || 'user';
+    this.budget = config.budget;
+    this.capabilities = config.capabilities;
+    this.baseSystemPrompt = config.baseSystemPrompt;
+    this.toolSchemas = config.toolSchemas;
+    this.prompt = config.prompt;
+    this.onToolCall = config.onToolCall || null;
+    this.context = config.context || {};
+    this.contextWindow = config.contextWindow || null;
+    this.toolChoiceOverride = config.toolChoiceOverride || null;
+    this.loopStartTime = Date.now();
+  }
+
+  // ─── 计算属性 ───
+
+  /** 是否为 system 场景 */
+  get isSystem() {
+    return this.source === 'system';
+  }
+
+  /** 最大迭代数 */
+  get maxIterations() {
+    return this.budget.maxIterations || 20;
+  }
+
+  // ─── Token 累计辅助 ───
+
+  /**
+   * 累加 token 用量到循环级统计
+   * @param {Object} usage — { inputTokens, outputTokens }
+   */
+  addTokenUsage(usage) {
+    if (!usage) return;
+    const inTok = usage.inputTokens || 0;
+    const outTok = usage.outputTokens || 0;
+    this.tokenUsage.input += inTok;
+    this.tokenUsage.output += outTok;
+  }
+
+  // ─── 结果构建 ───
+
+  /**
+   * 构建循环返回值
+   * @returns {{ reply: string, toolCalls: Array, tokenUsage: Object, iterations: number }}
+   */
+  buildResult() {
+    return {
+      reply: this.lastReply,
+      toolCalls: [...this.toolCalls],
+      tokenUsage: { ...this.tokenUsage },
+      iterations: this.iteration,
+    };
+  }
+}