autosnippet 2.8.3 → 2.10.0

package/lib/service/chat/ChatAgent.js

@@ -36,7 +36,7 @@ const PROJECT_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
 const SOUL_PATH = path.resolve(PROJECT_ROOT, 'SOUL.md');
 const MAX_ITERATIONS = 6;
-/** 系统调用 (如 bootstrap) 允许更多迭代,因为每维度需要多次 submit_candidate */
+/** 系统调用 (如 bootstrap) 允许更多迭代,因为每维度需要多次 submit_knowledge */
 const MAX_ITERATIONS_SYSTEM = 30;
 /** 原生函数调用模式下，已提交 ≥ MIN_SUBMITS_FOR_EARLY_EXIT 个候选后，连续 N 轮无新提交则提前退出 */
 const MIN_SUBMITS_FOR_EARLY_EXIT = 1;
@@ -69,23 +69,23 @@ const SYSTEM_CONTINUATION_PROMPT = `你的分析计划很好。但你需要 **
 请现在开始执行:
 1. 用 \`search_project_code\` 搜索项目代码获取真实示例
 2. 用 \`read_project_file\` 查看完整文件内容
-3. 对每个值得保留的信号,用 \`submit_candidate\` 提交候选
+3. 对每个值得保留的信号,用 \`submit_knowledge\` 提交候选
 
 ⚡ 推荐使用 batch_actions 一次提交多条候选:
 \`\`\`batch_actions
 [
-  {"tool": "submit_candidate", "params": {"title": "[Bootstrap] xxx/子主题", "code": "# 标题 — 项目特写\\n\\n> 摘要...\\n\\n描述和代码交织...", "language": "objectivec", "category": "Service", "summary": "...", "tags": ["bootstrap"], "source": "bootstrap", "reasoning": {"whyStandard": "...", "sources": ["file1"], "confidence": 0.7}}},
-  {"tool": "submit_candidate", "params": {"title": "...", "code": "...", ...}}
+  {"tool": "submit_knowledge", "params": {"title": "[Bootstrap] xxx/子主题", "code": "# 标题 — 项目特写\\n\\n> 摘要...\\n\\n描述和代码交织...", "language": "objectivec", "category": "Service", "summary": "...", "tags": ["bootstrap"], "source": "bootstrap", "reasoning": {"whyStandard": "...", "sources": ["file1"], "confidence": 0.7}}},
+  {"tool": "submit_knowledge", "params": {"title": "...", "code": "...", ...}}
 ]
 \`\`\`
 
 请立即开始执行,不要再输出分析文字。`;
 
 /**
- * 系统调用提交提示 — 当 AI 做了工具调用(search/read)、写了分析文本,但没调 submit_candidate 时注入
- * 引导 AI 将已有分析转化为实际的 submit_candidate 调用
+ * 系统调用提交提示 — 当 AI 做了工具调用(search/read)、写了分析文本,但没调 submit_knowledge 时注入
+ * 引导 AI 将已有分析转化为实际的 submit_knowledge 调用
  */
-const SYSTEM_SUBMIT_PROMPT = `你的分析很好，已经获取了足够的项目信息。但你还没有调用 \`submit_candidate\` 提交任何候选。
+const SYSTEM_SUBMIT_PROMPT = `你的分析很好，已经获取了足够的项目信息。但你还没有调用 \`submit_knowledge\` 提交任何候选。
 
 **你的分析不能只停留在文字描述层面** — 必须通过工具调用将分析结果持久化。
 
@@ -93,7 +93,7 @@ const SYSTEM_SUBMIT_PROMPT = `你的分析很好，已经获取了足够的项
 
 \`\`\`batch_actions
 [
-  {"tool": "submit_candidate", "params": {
+  {"tool": "submit_knowledge", "params": {
     "title": "[Bootstrap] 维度/子主题",
     "code": "# 标题 — 项目特写\\n\\n> 本项目使用 XX 模式, N 个文件采用此写法\\n\\n描述...\\n\\n\`\`\`objc\\n// 真实代码示例\\n\`\`\`\\n\\n要点说明...",
     "language": "objectivec",
@@ -103,11 +103,11 @@ const SYSTEM_SUBMIT_PROMPT = `你的分析很好，已经获取了足够的项
     "source": "bootstrap",
     "reasoning": {"whyStandard": "为什么值得保留", "sources": ["真实文件名"], "confidence": 0.7}
   }},
-  {"tool": "submit_candidate", "params": {...}}
+  {"tool": "submit_knowledge", "params": {...}}
 ]
 \`\`\`
 
-将你上面分析出的每个有价值的发现都转化为一条 submit_candidate 调用。code 字段写「项目特写」风格: 描述和代码交织,用项目真实类名和代码。`;
+将你上面分析出的每个有价值的发现都转化为一条 submit_knowledge 调用。code 字段写「项目特写」风格: 描述和代码交织,用项目真实类名和代码。`;
 
 export class ChatAgent {
   #toolRegistry;
@@ -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,12 +331,18 @@ 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 ? [
       'search_project_code', 'read_project_file',
-      'submit_candidate', 'submit_with_check',
+      'submit_knowledge', 'submit_with_check',
       'list_project_structure', 'get_file_summary', 'semantic_search_code',
       // AST 结构化分析工具
       'get_project_overview', 'get_class_hierarchy', 'get_class_info',
@@ -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_knowledge' || 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_knowledge' || 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,12 +594,105 @@ 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_knowledge' && 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);
 
           // ── 重复提交 / 维度范围校验 ──
-          if (fc.name === 'submit_candidate' || fc.name === 'submit_with_check') {
+          if (fc.name === 'submit_knowledge' || fc.name === 'submit_with_check') {
             const title = fc.args?.title || fc.args?.category || '';
             const isRejected = typeof toolResult === 'object' && toolResult?.status === 'rejected';
             const isError = typeof toolResult === 'object' && (toolResult?.error || toolResult?.status === 'error');
@@ -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({
@@ -516,7 +734,7 @@ export class ChatAgent {
           // 需要一条 user 消息明确告知 AI 切换到提交模式
           if (transition.transitioned && transition.newPhase === 'PRODUCE') {
             ctx.appendUserNudge(
-              '你已充分探索了项目代码，现在请开始调用 submit_candidate 工具来提交你发现的知识候选。不要再搜索，直接提交。'
+              '你已充分探索了项目代码，现在请开始调用 submit_knowledge 工具来提交你发现的知识候选。不要再搜索，直接提交。'
             );
             this.#logger.info('[ChatAgent] 📝 injected PRODUCE transition nudge');
           }
@@ -525,7 +743,7 @@ export class ChatAgent {
           // skill-only 维度从 EXPLORE 直接进入 SUMMARIZE (跳过 PRODUCE)，
           // 需要明确告知 AI 输出 dimensionDigest JSON
           if (transition.transitioned && transition.newPhase === 'SUMMARIZE') {
-            const submitCount = toolCalls.filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check').length;
+            const submitCount = toolCalls.filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check').length;
             ctx.appendUserNudge(
               `你已完成分析探索。请在回复中直接输出 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 留空数组 \`[]\`。如果有未来得及处理的信号，请在此标记，系统会在下次运行时续传。`
             );
@@ -563,7 +781,7 @@ export class ChatAgent {
           // 注入 nudge 让 AI 再输出一次 digest JSON
           if (transition.transitioned) {
             ctx.appendAssistantText(aiResult.text || '');
-            const submitCount = toolCalls.filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check').length;
+            const submitCount = toolCalls.filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check').length;
             ctx.appendUserNudge(
               `请在回复中直接输出 dimensionDigest JSON 总结（用 \`\`\`json 包裹）：\n\`\`\`json\n{"dimensionDigest":{"summary":"分析总结","candidateCount":${submitCount},"keyFindings":["发现"],"crossRefs":{},"gaps":["缺口"],"remainingTasks":[{"signal":"未处理的信号","reason":"原因","priority":"high","searchHints":["搜索词"]}]}}\n\`\`\`\n> remainingTasks: 记录未来得及处理的信号。已全部覆盖则留空 \`[]\`。`
             );
@@ -584,7 +802,7 @@ export class ChatAgent {
             ctx.appendAssistantText(aiResult.text || '');
             if (phaseRouter.phase === 'PRODUCE') {
               ctx.appendUserNudge(
-                '你的分析很好。请继续调用 submit_candidate 提交你发现的知识候选，每个值得记录的模式/实践都应该提交。'
+                '你的分析很好。请继续调用 submit_knowledge 提交你发现的知识候选，每个值得记录的模式/实践都应该提交。'
               );
               this.#logger.info('[ChatAgent] 📝 injected submit nudge (text in PRODUCE, not transitioning)');
             }
@@ -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`);
@@ -624,7 +850,7 @@ export class ChatAgent {
     this.#logger.info(`[ChatAgent] ⚠ producing forced summary (${iterations} iters, ${toolCalls.length} calls)`);
 
     const candidateCount = toolCalls.filter(tc =>
-      tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check'
+      tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check'
     ).length;
 
     let finalReply;
@@ -639,7 +865,7 @@ export class ChatAgent {
       if (isCircuitOpen) throw new Error('circuit open — skip to synthetic digest');
 
       const submitSummary = toolCalls
-        .filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check')
+        .filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check')
         .map((tc, i) => `${i + 1}. ${tc.params?.title || tc.params?.category || 'untitled'}`)
         .join('\n');
 
@@ -686,7 +912,7 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
       this.#logger.warn(`[ChatAgent] forced summary AI call failed: ${err.message}`);
       // 合成 digest 兜底
       const titles = toolCalls
-        .filter(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check')
+        .filter(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check')
         .map(tc => tc.params?.title || 'untitled');
       finalReply = `\`\`\`json
 {
@@ -771,7 +997,7 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
 
       if (!actions) {
         // ── 系统调用自动续跑 ──
-        const hasSubmits = toolCalls.some(tc => tc.tool === 'submit_candidate' || tc.tool === 'submit_with_check');
+        const hasSubmits = toolCalls.some(tc => tc.tool === 'submit_knowledge' || tc.tool === 'submit_with_check');
         if (source === 'system' && iterations < maxIter && !hasSubmits) {
           if (this.#looksLikeIncompleteStep(response)) {
             this.#logger.info(`[ChatAgent] 🔄 detected planning-only response at iteration ${iterations}, injecting continuation prompt`);
@@ -1046,13 +1272,13 @@ ${highSim.map(s => `- ${s.title} (相似度: ${s.similarity})`).join('\n')}
    */
   async #taskDiscoverAllRelations({ batchSize = 20 } = {}) {
     const ctx = this.#getToolContext();
-    const recipeService = ctx.container.get('recipeService');
-    if (!recipeService) throw new Error('RecipeService 不可用');
+    const knowledgeService = ctx.container.get('knowledgeService');
+    if (!knowledgeService) throw new Error('KnowledgeService 不可用');
 
     if (!ctx.aiProvider) throw new Error('AI Provider 未配置，请先设置 API Key');
 
-    // 获取所有 recipe
-    const { items = [], data = [] } = await recipeService.listRecipes({}, { page: 1, pageSize: 500 });
+    // 获取所有活跃知识条目
+    const { items = [], data = [] } = await knowledgeService.list({ lifecycle: 'active' }, { page: 1, pageSize: 500 });
     const recipes = items.length > 0 ? items : data;
     if (recipes.length < 2) return { discovered: 0, totalPairs: 0, message: `只有 ${recipes.length} 条 Recipe，至少需要 2 条` };
 
@@ -1108,10 +1334,10 @@ ${highSim.map(s => `- ${s.title} (相似度: ${s.similarity})`).join('\n')}
    */
   async #taskFullEnrich({ status = 'pending', maxCount = 50 } = {}) {
     const ctx = this.#getToolContext();
-    const candidateService = ctx.container.get('candidateService');
+    const knowledgeService = ctx.container.get('knowledgeService');
 
-    const { items = [], data = [] } = await candidateService.listCandidates(
-      { status }, { page: 1, pageSize: maxCount }
+    const { items = [], data = [] } = await knowledgeService.list(
+      { lifecycle: status }, { page: 1, pageSize: maxCount }
     );
     const candidates = items.length > 0 ? items : data;
     if (candidates.length === 0) return { enriched: 0, message: 'No candidates to enrich' };
@@ -1137,10 +1363,10 @@ ${highSim.map(s => `- ${s.title} (相似度: ${s.similarity})`).join('\n')}
    */
   async #taskQualityAudit({ threshold = 0.6, maxCount = 100 } = {}) {
     const ctx = this.#getToolContext();
-    const recipeService = ctx.container.get('recipeService');
+    const knowledgeService = ctx.container.get('knowledgeService');
 
-    const { items = [], data = [] } = await recipeService.listRecipes(
-      { status: 'active' }, { page: 1, pageSize: maxCount }
+    const { items = [], data = [] } = await knowledgeService.list(
+      { lifecycle: 'active' }, { page: 1, pageSize: maxCount }
     );
     const recipes = items.length > 0 ? items : data;
     if (recipes.length === 0) return { total: 0, lowQuality: [], message: 'No active recipes' };
@@ -1267,7 +1493,7 @@ ${code.substring(0, 3000)}
     // 核心工具 — 使用最频繁，直接展示完整 schema
     const coreTools = new Set([
       'search_project_code', 'read_project_file',
-      'search_knowledge', 'submit_candidate', 'submit_with_check', 'analyze_code',
+      'search_knowledge', 'submit_knowledge', 'submit_with_check', 'analyze_code',
       'bootstrap_knowledge', 'load_skill', 'suggest_skills',
       'create_skill', 'knowledge_overview', 'get_tool_details',
       'plan_task', 'review_my_output',
@@ -1323,8 +1549,8 @@ ${skillSection}
 
 \`\`\`batch_actions
 [
-  {"tool": "submit_candidate", "params": {"title": "...", "code": "..."}},
-  {"tool": "submit_candidate", "params": {"title": "...", "code": "..."}}
+  {"tool": "submit_knowledge", "params": {"title": "...", "code": "..."}},
+  {"tool": "submit_knowledge", "params": {"title": "...", "code": "..."}}
 ]
 \`\`\`
 
@@ -1390,10 +1616,15 @@ ${this.#projectBriefingCache}
 2. **定向探索** → get_file_summary 快速了解文件角色
 3. **深入研读** → search_project_code / read_project_file 获取真实代码
 4. **语义发现** → semantic_search_code 在知识库查找相关知识
-5. **知识产出** → submit_candidate 提交有价值的发现
+5. **知识产出** → submit_knowledge 提交有价值的发现
+
+## 高效使用工具（节省轮次）
+- **批量搜索**: search_project_code({ patterns: ["keywordA", "keywordB", "keywordC"] })
+- **批量读文件**: read_project_file({ filePaths: ["path/a.m", "path/b.m"] })
+- 合并同类请求为一次调用，避免逐个搜索/读取浪费轮次。
 
 ## 「项目特写」= 基本用法 + 项目特征融合
-submit_candidate 的 code 字段必须是「项目特写」— 将技术的基本用法与本项目的特征融合为一体:
+submit_knowledge 的 code 字段必须是「项目特写」— 将技术的基本用法与本项目的特征融合为一体:
 1. **项目选择了什么**: 采用了哪种写法/模式/约定
 2. **为什么这样选**: 统计数据（N 个文件、占比 M%）
 3. **项目禁止什么**: 被放弃的写法、反模式、显式禁用标记
@@ -1771,15 +2002,16 @@ submit_candidate 的 code 字段必须是「项目特写」— 将技术的基
       //   rule: code-standard, code-style, best-practice, boundary-constraint
       //   pattern: code-pattern, architecture, solution
       //   fact: code-relation, inheritance, call-chain, data-flow, module-dependency
+      // V3: knowledge_entries 统一表（candidates 已合并，lifecycle 替代 status）
       const stats = db.prepare(`
         SELECT
-          (SELECT COUNT(*) FROM recipes) as recipeCount,
-          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-standard','code-style','best-practice','boundary-constraint')) as ruleCount,
-          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-pattern','architecture','solution')) as patternCount,
-          (SELECT COUNT(*) FROM recipes WHERE knowledge_type IN ('code-relation','inheritance','call-chain','data-flow','module-dependency')) as factCount,
-          (SELECT COUNT(*) FROM recipes WHERE knowledge_type = 'boundary-constraint') as guardRuleCount,
-          (SELECT COUNT(*) FROM candidates WHERE status='pending') as pendingCandidates,
-          (SELECT COUNT(*) FROM candidates) as totalCandidates
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active') as recipeCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledge_type IN ('code-standard','code-style','best-practice','boundary-constraint')) as ruleCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledge_type IN ('code-pattern','architecture','solution')) as patternCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledge_type IN ('code-relation','inheritance','call-chain','data-flow','module-dependency')) as factCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledge_type = 'boundary-constraint') as guardRuleCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'pending') as pendingCandidates,
+          (SELECT COUNT(*) FROM knowledge_entries) as totalCandidates
       `).get();
       if (!stats || stats.recipeCount === 0) {
         return '\n## 项目状态\n⚠️ 知识库为空。建议先执行冷启动（bootstrap_knowledge）。\n';