autosnippet 2.8.2 → 2.9.0

package/lib/service/chat/AnalystAgent.js

@@ -19,20 +19,31 @@ import Logger from '../../infrastructure/logging/Logger.js';
 // System Prompt — Analyst 专用 (~100 tokens)
 // ──────────────────────────────────────────────────────────────────
 
-const ANALYST_SYSTEM_PROMPT = `你是一位高级软件架构师，正在深度分析一个真实项目。
+const ANALYST_SYSTEM_PROMPT = `你是一位高级软件架构师，正在深度分析一个真实项目的某个维度。
 
-## 工具使用优先级
-1. **结构化查询优先** — get_project_overview → get_class_hierarchy → get_class_info
-   这些工具返回精确的类继承、协议实现、方法签名信息，比文本搜索更高效。
-2. **文本搜索补充** — search_project_code 用于查找特定模式/关键字
-3. **文件阅读验证** — read_project_file 用于确认具体实现细节
+## 执行计划
+你有 **N 轮**工具调用机会（系统会告知具体数字）。请严格按以下节奏分配：
 
-> ⚠️ 避免反复调用 search_project_code 搜索不同关键词。
-> 如果需要了解类结构，直接用 get_class_info 查询。
+| 阶段 | 轮次占比 | 目标 |
+|------|---------|------|
+| 1. 全局扫描 | 第 1-3 轮 | get_project_overview + list_project_structure 了解项目结构 |
+| 2. 结构化探索 | 第 4-N×60% 轮 | get_class_hierarchy / get_class_info 理解核心类；search_project_code 批量搜索关键模式 |
+| 3. 深度验证 | 第 N×60%-N×80% 轮 | read_project_file 阅读关键实现，确认细节 |
+| 4. 输出总结 | 最后 20% | **停止调用工具**，直接输出你的分析文本 |
 
+## 关键规则
+- **到达 80% 轮次时必须开始写总结**，不要等系统提醒
+- 每一轮都必须调用工具获取新信息，不要花轮次在纯文本思考上
+- 不要重复搜索相同关键词或读取相同文件（系统会返回缓存并扣轮次）
+
+## 工具效率
+- **批量搜索**: search_project_code({ patterns: ["keywordA", "keywordB", "keywordC"] }) — 一次搜 3-5 个
+- **批量读文件**: read_project_file({ filePaths: ["a.m", "b.m", "c.m"] }) — 一次读 3-5 个
+- **结构化查询优先**: get_class_hierarchy / get_class_info 比文本搜索更精确高效
+
+## 输出要求
 输出你的分析发现，包括具体的文件路径和代码位置。
-不需要任何特定格式，用自然语言描述你的理解即可。
-尽可能多地使用工具来获取准确信息，不要猜测。`;
+用自然语言描述你的理解，不需要特定格式。`;
 
 // ──────────────────────────────────────────────────────────────────
 // Analyst 可用工具白名单 — 只做探索，不做提交
@@ -61,12 +72,12 @@ const ANALYST_TOOLS = [
 // ──────────────────────────────────────────────────────────────────
 
 const ANALYST_BUDGET = {
-  maxIterations: 12,      // was 20 — 多数维度 5-9 轮完成
-  searchBudget: 10,       // was 15 — 探索为主，精简预算
-  searchBudgetGrace: 6,   // was 10
+  maxIterations: 24,      // was 18 — 大项目维度需要充足探索轮次
+  searchBudget: 18,       // was 14 — 匹配更大探索空间
+  searchBudgetGrace: 10,  // was 8
   maxSubmits: 0,          // Analyst 不提交候选
   softSubmitLimit: 0,
-  idleRoundsToExit: 2,    // was 3 — 减少空转
+  idleRoundsToExit: 2,    // 减少空转
 };
 
 // ──────────────────────────────────────────────────────────────────

package/lib/service/chat/ChatAgent.js

@@ -253,6 +253,31 @@ export class ChatAgent {
     // 附加 token 用量统计
     result.tokenUsage = { ...this.#currentTokenUsage };
 
+    // 持久化 token 消耗到数据库（fire-and-forget）
+    try {
+      const tokenStore = this.#container?.get?.('tokenUsageStore');
+      if (tokenStore) {
+        const aiProvider = this.#aiProvider;
+        tokenStore.record({
+          source: source || 'unknown',
+          dimension: dimensionId || dimensionMeta?.id || null,
+          provider: aiProvider?.name || null,
+          model: aiProvider?.model || null,
+          inputTokens: this.#currentTokenUsage.input,
+          outputTokens: this.#currentTokenUsage.output,
+          durationMs: Date.now() - execStartTime,
+          toolCalls: result.toolCalls?.length || 0,
+          sessionId: conversationId || null,
+        });
+
+        // 通知前端 token 用量变化
+        try {
+          const realtime = this.#container?.get?.('realtimeService');
+          realtime?.broadcastTokenUsageUpdated?.();
+        } catch { /* optional */ }
+      }
+    } catch { /* token logging should never break execution */ }
+
     return { ...result, conversationId };
   }
 
@@ -306,7 +331,13 @@ export class ChatAgent {
     const phaseRouter = (isSystem && !disablePhaseRouter) ? new PhaseRouter(budget, isSkillOnly) : null;
 
     // ── 系统提示词 (支持外部覆盖) ──
-    const baseSystemPrompt = systemPromptOverride || this.#buildNativeToolSystemPrompt(budget);
+    let baseSystemPrompt = systemPromptOverride || this.#buildNativeToolSystemPrompt(budget);
+    // 统一注入轮次预算，确保 AI 始终知道具体数字和节奏
+    if (isSystem && !baseSystemPrompt.includes('轮次预算')) {
+      const exploreEnd = Math.floor(budget.maxIterations * 0.6);
+      const verifyEnd = Math.floor(budget.maxIterations * 0.8);
+      baseSystemPrompt += `\n\n## 轮次预算\n- 总轮次: **${budget.maxIterations} 轮**\n- 探索阶段: 第 1-${exploreEnd} 轮（搜索和结构化查询）\n- 验证阶段: 第 ${exploreEnd + 1}-${verifyEnd} 轮（读取关键文件确认细节）\n- 总结阶段: 第 ${verifyEnd + 1}-${budget.maxIterations} 轮（**停止工具调用，输出分析文本**）\n\n到达第 ${verifyEnd} 轮时你必须开始输出总结，不要继续搜索。`;
+    }
 
     // Bootstrap 场景限制可用工具集 (支持外部覆盖)
     const effectiveAllowedTools = allowedTools || (isSystem ? [
@@ -328,6 +359,20 @@ export class ChatAgent {
     const submittedTitles = new Set(this.#globalSubmittedTitles);
     const sharedState = {}; // P2.2: 跨工具调用共享状态（搜索计数器等）
 
+    // ── 进度感知收敛 (Analyst 专用: disablePhaseRouter=true) ──
+    // 追踪搜索/读取新信息的效率，当探索饱和时提前引导 AI 收敛
+    const explorationMetrics = {
+      uniqueFiles: new Set(),        // 已读取的唯一文件
+      uniquePatterns: new Set(),     // 已搜索的唯一 pattern
+      uniqueQueries: new Set(),      // 已查询的唯一类名/目录（AST + list_project_structure）
+      totalToolCalls: 0,             // 总工具调用数
+      newInfoRounds: 0,              // 最近 N 轮中获取到新信息的轮次
+      staleRounds: 0,                // 连续未获取新信息的轮次
+      convergenceNudged: false,      // 是否已注入收敛 nudge
+    };
+    const MIN_EXPLORE_ITERS = 16;    // 最少探索轮次（冷启动质量保障）
+    const STALE_THRESHOLD = 3;       // 连续无新信息轮次触发收敛
+
     // ── 主循环 ──
     while (true) {
       // PhaseRouter tick + 退出检查
@@ -337,9 +382,53 @@ export class ChatAgent {
           this.#logger.info(`[ChatAgent] PhaseRouter exit: phase=${phaseRouter.phase}, iter=${phaseRouter.totalIterations}, submits=${phaseRouter.totalSubmits}`);
           break;
         }
-      } else if (isSystem && iterationCount >= maxIter) {
-        // v3: system 模式无 PhaseRouter 时用独立迭代计数器硬限制
-        this.#logger.info(`[ChatAgent] Iteration hard cap reached: ${iterationCount}/${maxIter}`);
+        // PhaseRouter 因 maxIterations 强制转入 SUMMARIZE → 注入收尾 nudge
+        if (phaseRouter.consumeForcedSummarize()) {
+          const submitCount = toolCalls.filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check').length;
+          ctx.appendUserNudge(
+            `⚠️ 轮次即将耗尽 (${phaseRouter.totalIterations}/${budget.maxIterations})，**必须立即结束**。请在回复中直接输出 dimensionDigest JSON 总结（用 \`\`\`json 包裹），不要再调用任何工具。\n` +
+            `\`\`\`json\n{"dimensionDigest":{"summary":"分析总结","candidateCount":${submitCount},"keyFindings":["发现"],"crossRefs":{},"gaps":["缺口"],"remainingTasks":[{"signal":"未处理信号","reason":"轮次耗尽","priority":"high","searchHints":["搜索词"]}]}}\n\`\`\`\n> remainingTasks: 列出未来得及处理的信号。已覆盖则留空 \`[]\`。`
+          );
+          this.#logger.info('[ChatAgent] 📝 injected forced SUMMARIZE nudge (maxIterations reached)');
+        }
+      } else if (isSystem && !phaseRouter && !ctx.__gracefulExitInjected && !explorationMetrics.convergenceNudged
+                 && iterationCount >= MIN_EXPLORE_ITERS && explorationMetrics.staleRounds >= STALE_THRESHOLD) {
+        // ── 进度感知收敛：探索已饱和，提前引导 AI 总结 ──
+        this.#logger.info(
+          `[ChatAgent] 📊 Exploration saturated at iter ${iterationCount}/${maxIter} — ` +
+          `files=${explorationMetrics.uniqueFiles.size}, patterns=${explorationMetrics.uniquePatterns.size}, ` +
+          `queries=${explorationMetrics.uniqueQueries.size}, staleRounds=${explorationMetrics.staleRounds} — nudging convergence`
+        );
+        ctx.appendUserNudge(
+          `你已经充分探索了项目代码（${explorationMetrics.uniqueFiles.size} 个文件，${explorationMetrics.uniquePatterns.size} 次不同搜索，${explorationMetrics.uniqueQueries.size} 次结构化查询）。` +
+          `最近 ${explorationMetrics.staleRounds} 轮没有发现新信息，建议开始撰写分析总结。\n` +
+          `如果你确信还有重要方面未覆盖，可以继续探索（剩余 ${maxIter - iterationCount} 轮）；否则请直接输出你的分析发现。`
+        );
+        explorationMetrics.convergenceNudged = true;
+        // 不 break，不设 toolChoice=none — 这是软 nudge，AI 仍可继续探索
+      } else if (isSystem && !phaseRouter && !ctx.__budgetWarningInjected
+                 && iterationCount >= Math.floor(maxIter * 0.75)) {
+        // ── 预算感知提醒：75% 预算消耗时轻量提示 ──
+        ctx.appendUserNudge(
+          `📌 进度提醒：你已使用 ${iterationCount}/${maxIter} 轮次（${Math.round(iterationCount / maxIter * 100)}%）。` +
+          `请确保核心方面已覆盖，开始准备总结。剩余 ${maxIter - iterationCount} 轮，优先填补最重要的分析空白。`
+        );
+        ctx.__budgetWarningInjected = true;
+        this.#logger.info(`[ChatAgent] 📌 Budget warning at ${iterationCount}/${maxIter} (${Math.round(iterationCount / maxIter * 100)}%)`);
+      } else if (isSystem && iterationCount >= maxIter && !ctx.__gracefulExitInjected) {
+        // 达到上限 → 注入收尾消息让 AI 快速总结（而非硬中断）
+        this.#logger.info(`[ChatAgent] Iteration cap reached (${iterationCount}/${maxIter}) — injecting graceful exit nudge`);
+        const submitCount = toolCalls.filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check').length;
+        ctx.appendUserNudge(
+          `⚠️ 你已使用 ${iterationCount}/${maxIter} 轮次，**必须立即结束**。请在回复中直接输出 dimensionDigest JSON 总结（用 \`\`\`json 包裹），不要再调用任何工具。\n` +
+          `\`\`\`json\n{"dimensionDigest":{"summary":"分析总结","candidateCount":${submitCount},"keyFindings":["发现"],"crossRefs":{},"gaps":["缺口"],"remainingTasks":[{"signal":"未处理信号","reason":"轮次耗尽","priority":"high","searchHints":["搜索词"]}]}}\n\`\`\`\n> remainingTasks: 列出未来得及处理的信号。已覆盖则留空 \`[]\`。`
+        );
+        ctx.__gracefulExitInjected = true;
+        // 不 break，给 AI 2 轮 grace 来产出总结
+        // 继续 while 循环
+      } else if (isSystem && iterationCount >= maxIter + 2) {
+        // 硬上限兜底：grace 轮次也耗尽
+        this.#logger.info(`[ChatAgent] Hard cap reached: ${iterationCount}/${maxIter + 2}`);
         break;
       } else if (!isSystem && ctx.length > maxIter * 2 + 2) {
         // 用户对话模式: 简单的消息数限制
@@ -352,7 +441,10 @@ export class ChatAgent {
 
       // ── 动态 toolChoice (由 PhaseRouter 决定) ──
       let currentChoice;
-      if (phaseRouter) {
+      if (ctx.__gracefulExitInjected) {
+        // graceful exit: 禁止工具调用，强制 AI 输出文本总结
+        currentChoice = 'none';
+      } else if (phaseRouter) {
         currentChoice = phaseRouter.getToolChoice();
       } else {
         currentChoice = 'auto';
@@ -371,6 +463,19 @@ export class ChatAgent {
         if (hint) {
           systemPrompt += `\n\n## 当前状态\n${hint}`;
         }
+      } else if (isSystem) {
+        // 非 PhaseRouter 路径：注入实时轮次计数器，让 AI 始终感知进度
+        const verifyStart = Math.floor(maxIter * 0.8);
+        const remaining = maxIter - iterationCount;
+        let phaseLabel;
+        if (iterationCount <= Math.floor(maxIter * 0.6)) {
+          phaseLabel = '探索阶段';
+        } else if (iterationCount <= verifyStart) {
+          phaseLabel = '验证阶段';
+        } else {
+          phaseLabel = '⚠ 总结阶段 — 请停止工具调用，直接输出分析文本';
+        }
+        systemPrompt += `\n\n## 当前进度\n第 ${iterationCount}/${maxIter} 轮 | ${phaseLabel} | 剩余 ${remaining} 轮`;
       }
 
       // ── AI 调用 ──
@@ -438,6 +543,20 @@ export class ChatAgent {
 
       // ── 处理 functionCalls ──
       if (aiResult.functionCalls && aiResult.functionCalls.length > 0) {
+        // ── Graceful exit 保护: Gemini 有时会无视 toolChoice='none' 继续返回工具调用
+        //    强制忽略工具调用，将附带文本视为最终回复
+        if (ctx.__gracefulExitInjected) {
+          this.#logger.warn(`[ChatAgent] ⚠ AI returned ${aiResult.functionCalls.length} tool calls despite toolChoice=none (graceful exit) — ignoring tools, treating as text`);
+          if (aiResult.text) {
+            const reply = this.#cleanFinalAnswer(aiResult.text);
+            const totalDuration = Date.now() - execStartTime;
+            this.#logger.info(`[ChatAgent] ✅ final answer (graceful exit, forced) — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`);
+            return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+          }
+          // 无文本时继续循环，下一轮硬上限兜底
+          continue;
+        }
+
         // 限制单次工具调用数量（防上下文溢出）
         const MAX_TOOL_CALLS_PER_ITER = 8;
         let activeCalls = aiResult.functionCalls;
@@ -450,6 +569,7 @@ export class ChatAgent {
         ctx.appendAssistantWithToolCalls(aiResult.text || null, activeCalls);
 
         let roundSubmitCount = 0;
+        let roundHasNewInfo = false;  // 本轮是否获取到新信息
 
         for (const fc of activeCalls) {
           const toolStartTime = Date.now();
@@ -474,6 +594,99 @@ export class ChatAgent {
           const summarized = this.#summarizeResult(toolResult);
           toolCalls.push({ tool: fc.name, params: fc.args, result: summarized });
 
+          // ── 探索进度追踪 (非 PhaseRouter 路径) ──
+          if (!phaseRouter && isSystem) {
+            explorationMetrics.totalToolCalls++;
+            let foundNewInfo = false;
+
+            if (fc.name === 'search_project_code') {
+              const pattern = fc.args?.pattern || '';
+              const patterns = fc.args?.patterns || [];
+              // 单模式
+              if (pattern && !explorationMetrics.uniquePatterns.has(pattern)) {
+                explorationMetrics.uniquePatterns.add(pattern);
+                foundNewInfo = true;
+              }
+              // 批量模式
+              for (const p of patterns) {
+                if (!explorationMetrics.uniquePatterns.has(p)) {
+                  explorationMetrics.uniquePatterns.add(p);
+                  foundNewInfo = true;
+                }
+              }
+              // 检查搜索结果是否有新文件
+              if (toolResult && typeof toolResult === 'object') {
+                const matches = toolResult.matches || [];
+                const batchResults = toolResult.batchResults || {};
+                for (const m of matches) {
+                  if (m.file && !explorationMetrics.uniqueFiles.has(m.file)) {
+                    explorationMetrics.uniqueFiles.add(m.file);
+                    foundNewInfo = true;
+                  }
+                }
+                for (const sub of Object.values(batchResults)) {
+                  for (const m of (sub.matches || [])) {
+                    if (m.file && !explorationMetrics.uniqueFiles.has(m.file)) {
+                      explorationMetrics.uniqueFiles.add(m.file);
+                      foundNewInfo = true;
+                    }
+                  }
+                }
+              }
+            } else if (fc.name === 'read_project_file') {
+              const fp = fc.args?.filePath || '';
+              const fps = fc.args?.filePaths || [];
+              if (fp && !explorationMetrics.uniqueFiles.has(fp)) {
+                explorationMetrics.uniqueFiles.add(fp);
+                foundNewInfo = true;
+              }
+              for (const f of fps) {
+                if (!explorationMetrics.uniqueFiles.has(f)) {
+                  explorationMetrics.uniqueFiles.add(f);
+                  foundNewInfo = true;
+                }
+              }
+            } else if (fc.name === 'list_project_structure') {
+              // 目录结构：同一目录只算一次新信息
+              const dir = fc.args?.directory || '/';
+              const qKey = `list:${dir}`;
+              if (!explorationMetrics.uniqueQueries.has(qKey)) {
+                explorationMetrics.uniqueQueries.add(qKey);
+                foundNewInfo = true;
+              }
+            } else if (fc.name === 'get_class_info' || fc.name === 'get_class_hierarchy'
+                     || fc.name === 'get_protocol_info' || fc.name === 'get_method_overrides'
+                     || fc.name === 'get_category_map') {
+              // AST 结构化查询：同一类名/协议名只算一次新信息
+              const queryTarget = fc.args?.className || fc.args?.protocolName || fc.args?.name || '';
+              const qKey = `${fc.name}:${queryTarget}`;
+              if (!explorationMetrics.uniqueQueries.has(qKey)) {
+                explorationMetrics.uniqueQueries.add(qKey);
+                foundNewInfo = true;
+              }
+            } else if (fc.name === 'get_project_overview') {
+              // 项目概览只需调一次
+              const qKey = 'overview';
+              if (!explorationMetrics.uniqueQueries.has(qKey)) {
+                explorationMetrics.uniqueQueries.add(qKey);
+                foundNewInfo = true;
+              }
+            } else if (fc.name !== 'submit_candidate' && fc.name !== 'submit_with_check') {
+              // 其他未分类工具 — 首次算新信息，之后同工具名+同参数去重
+              const qKey = `${fc.name}:${JSON.stringify(fc.args || {}).substring(0, 80)}`;
+              if (!explorationMetrics.uniqueQueries.has(qKey)) {
+                explorationMetrics.uniqueQueries.add(qKey);
+                foundNewInfo = true;
+              }
+            }
+
+            if (foundNewInfo) {
+              explorationMetrics.staleRounds = 0;
+              explorationMetrics.newInfoRounds++;
+              roundHasNewInfo = true;
+            }
+          }
+
           // ── Layer 3: ToolResultLimiter — 动态配额压缩 ──
           const quota = ctx.getToolResultQuota();
           let resultStr = limitToolResult(fc.name, toolResult, quota);
@@ -503,6 +716,11 @@ export class ChatAgent {
           ctx.appendToolResult(fc.id, fc.name, resultStr);
         }
 
+        // ── 探索饱和度更新 (非 PhaseRouter 路径) ──
+        if (!phaseRouter && isSystem && !roundHasNewInfo) {
+          explorationMetrics.staleRounds++;
+        }
+
         // ── PhaseRouter 更新 ──
         if (phaseRouter) {
           const transition = phaseRouter.update({
@@ -602,7 +820,15 @@ export class ChatAgent {
         continue;
       }
 
-      // 用户对话: 文字回答即最终回答
+      // 用户对话 / graceful exit: 文字回答即最终回答
+      if (ctx.__gracefulExitInjected || !isSystem) {
+        const reply = this.#cleanFinalAnswer(aiResult.text || '');
+        const totalDuration = Date.now() - execStartTime;
+        this.#logger.info(`[ChatAgent] ✅ final answer (${ctx.__gracefulExitInjected ? 'graceful exit' : 'user'}) — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`);
+        return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+      }
+
+      // system 模式非 graceful exit 的文字回答（理论上不应到这里）
       const reply = this.#cleanFinalAnswer(aiResult.text || '');
       const totalDuration = Date.now() - execStartTime;
       this.#logger.info(`[ChatAgent] ✅ final answer — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`);
@@ -1392,6 +1618,11 @@ ${this.#projectBriefingCache}
 4. **语义发现** → semantic_search_code 在知识库查找相关知识
 5. **知识产出** → submit_candidate 提交有价值的发现
 
+## 高效使用工具（节省轮次）
+- **批量搜索**: search_project_code({ patterns: ["keywordA", "keywordB", "keywordC"] })
+- **批量读文件**: read_project_file({ filePaths: ["path/a.m", "path/b.m"] })
+- 合并同类请求为一次调用，避免逐个搜索/读取浪费轮次。
+
 ## 「项目特写」= 基本用法 + 项目特征融合
 submit_candidate 的 code 字段必须是「项目特写」— 将技术的基本用法与本项目的特征融合为一体:
 1. **项目选择了什么**: 采用了哪种写法/模式/约定

package/lib/service/chat/ContextWindow.js

@@ -399,13 +399,27 @@ export function limitToolResult(toolName, result, quota) {
     return raw.length > 500 ? raw.substring(0, 500) : raw;
   }
 
-  // search_project_code: 限制匹配数 + 截断上下文
+  // search_project_code: 限制匹配数 + 截断上下文（支持批量模式）
   if (toolName === 'search_project_code') {
+    if (result && typeof result === 'object' && result.batchResults) {
+      // 批量模式：对每个 pattern 的结果独立限制（直接操作对象，避免 stringify→parse 往返）
+      const limited = { ...result };
+      const perKeyChars = Math.floor(maxChars / Object.keys(limited.batchResults).length);
+      for (const [key, sub] of Object.entries(limited.batchResults)) {
+        limited.batchResults[key] = limitSearchResultObj(sub, Math.min(maxMatches, 3), perKeyChars);
+      }
+      const raw = JSON.stringify(limited);
+      return raw.length > maxChars ? raw.substring(0, maxChars) + '\n... [batch truncated]' : raw;
+    }
     return limitSearchResult(result, maxMatches, maxChars);
   }
 
-  // read_project_file: 限制字符数
+  // read_project_file: 限制字符数（支持批量模式）
   if (toolName === 'read_project_file') {
+    if (result && typeof result === 'object' && result.batchResults) {
+      const raw = JSON.stringify(result);
+      return raw.length > maxChars ? raw.substring(0, maxChars) + '\n... [batch truncated]' : raw;
+    }
     return limitFileContent(result, maxChars);
   }
 
@@ -465,6 +479,41 @@ function limitSearchResult(result, maxMatches, maxChars) {
   return str;
 }
 
+/**
+ * 限制搜索结果（返回对象） — 用于批量模式，避免 JSON.stringify → JSON.parse 往返
+ * 当源码含控制字符时，stringify→substring 截断会破坏 JSON 结构导致 parse 失败
+ */
+function limitSearchResultObj(result, maxMatches, maxChars) {
+  if (!result || typeof result !== 'object') return result || {};
+  if (typeof result === 'string') return { _raw: result.substring(0, maxChars) };
+
+  const limited = { ...result };
+  if (Array.isArray(limited.matches)) {
+    limited.matches = limited.matches.slice(0, maxMatches).map(m => {
+      const copy = { ...m };
+      if (copy.context && typeof copy.context === 'string') {
+        const contextLines = copy.context.split('\n');
+        if (contextLines.length > 7) {
+          copy.context = contextLines.slice(0, 7).join('\n') + '\n... [truncated]';
+        }
+        // 按字符上限截断 context（防止单个代码块过大）
+        if (copy.context.length > 500) {
+          copy.context = copy.context.substring(0, 500) + '\n... [truncated]';
+        }
+      }
+      if (Array.isArray(copy.lines) && copy.lines.length > 5) {
+        copy.lines = copy.lines.slice(0, 5);
+        copy._truncated = true;
+      }
+      return copy;
+    });
+    if (result.matches.length > maxMatches) {
+      limited._note = `Showing ${maxMatches} of ${result.matches.length} matches`;
+    }
+  }
+  return limited;
+}
+
 /**
  * 限制文件内容 — 截断 content 字段
  */
@@ -526,6 +575,9 @@ export class PhaseRouter {
   /** @type {Object} 日志器 */
   #logger;
 
+  /** @type {boolean} 是否因 maxIterations 强制进入 SUMMARIZE */
+  #forcedSummarize = false;
+
   /**
    * @param {Object} budget — 预算配置
    * @param {boolean} isSkillOnly — 是否为 skill-only 维度
@@ -561,6 +613,19 @@ export class PhaseRouter {
     return this.#totalSubmits;
   }
 
+  /**
+   * 是否因 maxIterations 触顶而强制进入 SUMMARIZE（一次性标记）
+   * 调用后自动复位
+   * @returns {boolean}
+   */
+  consumeForcedSummarize() {
+    if (this.#forcedSummarize) {
+      this.#forcedSummarize = false;
+      return true;
+    }
+    return false;
+  }
+
   /**
    * 获取当前阶段的 toolChoice
    * @returns {'required'|'auto'|'none'}
@@ -585,8 +650,21 @@ export class PhaseRouter {
    * @returns {boolean}
    */
   shouldExit() {
-    if (this.#totalIterations >= this.#budget.maxIterations) return true;
+    // 已在 SUMMARIZE 阶段 → 给 2 轮输出总结后退出
     if (this.#phase === 'SUMMARIZE' && this.#phaseRounds >= 2) return true;
+
+    // 达到 maxIterations → 不硬退出，而是强制转入 SUMMARIZE 让 AI 在完整上下文中收尾
+    if (this.#totalIterations >= this.#budget.maxIterations && this.#phase !== 'SUMMARIZE') {
+      this.#logger.info(`[PhaseRouter] maxIterations reached (${this.#totalIterations}/${this.#budget.maxIterations}), forcing → SUMMARIZE for graceful exit`);
+      this.#forcedSummarize = true;
+      this.#transitionTo('SUMMARIZE');
+      // 返回 false 让主循环继续运行 SUMMARIZE 阶段的 2 轮收尾
+      return false;
+    }
+
+    // SUMMARIZE 阶段超限兜底（maxIterations + 2 轮 grace）
+    if (this.#totalIterations >= this.#budget.maxIterations + 2) return true;
+
     return false;
   }
 
@@ -688,6 +766,12 @@ export class PhaseRouter {
    * @returns {string|null}
    */
   getPhaseHint() {
+    // 接近 maxIterations 上限时，无论处于哪个阶段都警告 AI
+    const remaining = this.#budget.maxIterations - this.#totalIterations;
+    if (remaining <= 2 && remaining > 0 && this.#phase !== 'SUMMARIZE') {
+      return `⚠️ 仅剩 ${remaining} 轮次即达上限，请尽快完成当前工作并准备输出总结。`;
+    }
+
     switch (this.#phase) {
       case 'EXPLORE':
         if (this.#phaseRounds >= this.#budget.searchBudget - 2) {

package/lib/service/chat/HandoffProtocol.js

@@ -13,6 +13,31 @@
 // AnalysisReport 构建
 // ──────────────────────────────────────────────────────────────────
 
+/**
+ * 清理 Analyst 分析文本中可能泄漏的系统 nudge / graceful exit 指令。
+ * 这些内容如果传给 Producer，会干扰其正常工作流。
+ */
+function sanitizeAnalysisText(text) {
+  if (!text) return '';
+  // 移除 graceful exit nudge 及 digest 模板指令
+  const patterns = [
+    /\*{0,2}⚠️?\s*(?:你已使用|轮次即将耗尽|仅剩|请立即停止|必须立即结束)[^\n]*\n?/gi,
+    /\*{0,2}请立即停止所有工具调用[^\n]*\*{0,2}\n?/gi,
+    /请在回复中直接输出\s*dimensionDigest\s*JSON[^\n]*\n?/gi,
+    /> ?(?:remainingTasks|如果所有信号都已覆盖)[^\n]*\n?/gi,
+    /> ?⚠️ 严禁输出任何非 JSON 内容[^\n]*\n?/gi,
+    // 移除 AI 回显的 dimensionDigest JSON 块（对 Producer 无价值且会干扰）
+    /```json\s*\n\s*\{\s*"dimensionDigest"\s*:[\s\S]*?\n```/g,
+  ];
+  let cleaned = text;
+  for (const pat of patterns) {
+    cleaned = cleaned.replace(pat, '');
+  }
+  // 移除可能残留的空行堆积
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n').trim();
+  return cleaned;
+}
+
 /**
  * 从 Analyst 的执行结果构建 AnalysisReport
  *
@@ -73,7 +98,7 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
   }
 
   // 从分析文本中提取文件路径
-  const text = analystResult.reply || '';
+  const text = sanitizeAnalysisText(analystResult.reply || '');
   const textFileRefs = text.match(/[\w/.-]+\.[mhswift]+/g);
   if (textFileRefs) {
     for (const f of textFileRefs) {

package/lib/service/chat/ProducerAgent.js

@@ -31,12 +31,14 @@ const PRODUCER_SYSTEM_PROMPT = `你是知识管理专家。你会收到一段代
 
 工作流程:
 1. 阅读分析文本，识别每个独立的知识点/发现
-2. 对每个知识点，用 read_project_file 获取关键代码片段（读取 30-80 行，不要只读 5 行头部）
+2. 用 read_project_file 批量获取关键代码片段:
+   read_project_file({ filePaths: ["FileA.m", "FileB.m"], maxLines: 80 })
 3. 立刻调用 submit_candidate 提交
 4. 重复直到分析中的所有知识点都已提交
 
 关键规则:
 - 分析中的每个要点/段落都应转化为至少一个候选
+- read_project_file 支持 filePaths 数组批量读取多个文件，一次调用完成
 - read_project_file 时读取足够多的行数（startLine + maxLines 至少 30 行）
 - reasoning.sources 必须是非空数组，填写相关文件路径如 ["FileName.m"]
 - 如果分析提到了 3 个模式，就应该提交 3 个候选，不要合并
@@ -63,7 +65,7 @@ const PRODUCER_TOOLS = [
 // ──────────────────────────────────────────────────────────────────
 
 const PRODUCER_BUDGET = {
-  maxIterations: 15,
+  maxIterations: 24,      // was 18 — 与 Analyst 统一
   searchBudget: 4,
   searchBudgetGrace: 3,
   maxSubmits: 10,