autosnippet 2.9.0 → 2.11.0

package/lib/service/chat/ChatAgent.js

@@ -30,13 +30,14 @@ import { TaskPipeline } from './TaskPipeline.js';
 import { Memory } from './Memory.js';
 import { ConversationStore } from './ConversationStore.js';
 import { ContextWindow, PhaseRouter, limitToolResult } from './ContextWindow.js';
+import { ReasoningLayer } from './ReasoningLayer.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 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 +70,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 +94,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 +104,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;
@@ -342,7 +343,7 @@ export class ChatAgent {
     // 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',
@@ -373,6 +374,16 @@ export class ChatAgent {
     const MIN_EXPLORE_ITERS = 16;    // 最少探索轮次（冷启动质量保障）
     const STALE_THRESHOLD = 3;       // 连续无新信息轮次触发收敛
 
+    // ── Layer 4: ReasoningLayer — 推理链采集 + 结构化观察 + 反思 + 规划 ──
+    const reasoning = new ReasoningLayer({
+      enabled: true,
+      reflectionEnabled: isSystem,      // 仅 system 模式启用反思
+      reflectionInterval: isSystem ? 5 : 0,
+      planningEnabled: isSystem,        // 仅 system 模式启用规划
+      replanInterval: isSystem ? 8 : 0,
+      deviationThreshold: 0.6,
+    });
+
     // ── 主循环 ──
     while (true) {
       // PhaseRouter tick + 退出检查
@@ -384,7 +395,7 @@ export class ChatAgent {
         }
         // PhaseRouter 因 maxIterations 强制转入 SUMMARIZE → 注入收尾 nudge
         if (phaseRouter.consumeForcedSummarize()) {
-          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(
             `⚠️ 轮次即将耗尽 (${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: 列出未来得及处理的信号。已覆盖则留空 \`[]\`。`
@@ -418,7 +429,7 @@ export class ChatAgent {
       } 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;
+        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: 列出未来得及处理的信号。已覆盖则留空 \`[]\`。`
@@ -450,6 +461,15 @@ export class ChatAgent {
         currentChoice = 'auto';
       }
 
+      // ── ReasoningLayer Hook 1: beforeAICall — 开始新轮次 + 反思检查 ──
+      const reflectionNudge = reasoning.beforeAICall(iterationCount, {
+        explorationMetrics, budget, phase: phaseRouter?.phase,
+      });
+      if (reflectionNudge) {
+        ctx.appendUserNudge(reflectionNudge);
+        this.#logger.info(`[ChatAgent] 💭 injected reflection at iteration ${iterationCount}`);
+      }
+
       // ── 压缩检查 (每次 AI 调用前) ──
       const compactResult = ctx.compactIfNeeded();
       if (compactResult.level > 0) {
@@ -508,6 +528,9 @@ export class ChatAgent {
           this.#logger.info(`[ChatAgent] ✓ AI returned text in ${aiDuration}ms (${(aiResult.text || '').length} chars) — "${textPreview}…"`);
         }
         consecutiveAiErrors = 0;
+
+        // ── ReasoningLayer Hook 2: afterAICall — 提取 Thought ──
+        reasoning.afterAICall(aiResult, 'native');
       } catch (aiErr) {
         consecutiveAiErrors++;
         this.#logger.warn(`[ChatAgent] AI call failed (attempt ${consecutiveAiErrors}): ${aiErr.message}`);
@@ -518,10 +541,13 @@ export class ChatAgent {
             this.#logger.warn(`[ChatAgent] 🛑 circuit breaker is OPEN — skipping to summary`);
             break;
           }
+          reasoning.afterRound();
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
+            reasoningTrace: reasoning.trace,
+            reasoningQuality: reasoning.getQualityMetrics(),
           };
         }
 
@@ -531,10 +557,13 @@ export class ChatAgent {
             ctx.resetToPromptOnly();
             break;
           }
+          reasoning.afterRound();
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
+            reasoningTrace: reasoning.trace,
+            reasoningQuality: reasoning.getQualityMetrics(),
           };
         }
         await new Promise(r => setTimeout(r, 2000));
@@ -550,8 +579,9 @@ export class ChatAgent {
           if (aiResult.text) {
             const reply = this.#cleanFinalAnswer(aiResult.text);
             const totalDuration = Date.now() - execStartTime;
+            reasoning.afterRound();
             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 };
+            return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
           }
           // 无文本时继续循环，下一轮硬上限兜底
           continue;
@@ -594,6 +624,9 @@ export class ChatAgent {
           const summarized = this.#summarizeResult(toolResult);
           toolCalls.push({ tool: fc.name, params: fc.args, result: summarized });
 
+          // ── ReasoningLayer Hook 3: afterToolExec — 记录 Action + 构建 Observation ──
+          reasoning.afterToolExec(fc.name, fc.args, toolResult, explorationMetrics);
+
           // ── 探索进度追踪 (非 PhaseRouter 路径) ──
           if (!phaseRouter && isSystem) {
             explorationMetrics.totalToolCalls++;
@@ -671,7 +704,7 @@ export class ChatAgent {
                 explorationMetrics.uniqueQueries.add(qKey);
                 foundNewInfo = true;
               }
-            } else if (fc.name !== 'submit_candidate' && fc.name !== 'submit_with_check') {
+            } 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)) {
@@ -692,7 +725,7 @@ export class ChatAgent {
           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');
@@ -721,6 +754,14 @@ export class ChatAgent {
           explorationMetrics.staleRounds++;
         }
 
+        // ── ReasoningLayer Hook 4: afterRound — 关闭轮次 + 写入摘要 ──
+        reasoning.afterRound({
+          newInfoCount: roundHasNewInfo ? 1 : 0,
+          totalCalls: activeCalls.length,
+          submitCount: roundSubmitCount,
+          explorationMetrics,
+        });
+
         // ── PhaseRouter 更新 ──
         if (phaseRouter) {
           const transition = phaseRouter.update({
@@ -734,7 +775,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');
           }
@@ -743,7 +784,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 留空数组 \`[]\`。如果有未来得及处理的信号，请在此标记，系统会在下次运行时续传。`
             );
@@ -781,7 +822,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: 记录未来得及处理的信号。已全部覆盖则留空 \`[]\`。`
             );
@@ -791,8 +832,9 @@ export class ChatAgent {
           // 已在 SUMMARIZE 阶段 — 这就是最终回答
           const reply = this.#cleanFinalAnswer(aiResult.text || '');
           const totalDuration = Date.now() - execStartTime;
+          reasoning.afterRound();
           this.#logger.info(`[ChatAgent] ✅ final answer — ${reply.length} chars, ${phaseRouter.totalIterations} iters, ${toolCalls.length} tool calls, ${totalDuration}ms`);
-          return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+          return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
         }
 
         if (!transition.transitioned) {
@@ -802,7 +844,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)');
             }
@@ -811,8 +853,9 @@ export class ChatAgent {
           // 非生产阶段的未转换文本 = 最终回答
           const reply = this.#cleanFinalAnswer(aiResult.text || '');
           const totalDuration = Date.now() - execStartTime;
+          reasoning.afterRound();
           this.#logger.info(`[ChatAgent] ✅ final answer — ${reply.length} chars, ${phaseRouter.totalIterations} iters, ${toolCalls.length} tool calls, ${totalDuration}ms`);
-          return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+          return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
         }
 
         // 其他阶段的文字回答 → 继续循环（PhaseRouter 已自动转换阶段）
@@ -824,21 +867,27 @@ export class ChatAgent {
       if (ctx.__gracefulExitInjected || !isSystem) {
         const reply = this.#cleanFinalAnswer(aiResult.text || '');
         const totalDuration = Date.now() - execStartTime;
+        reasoning.afterRound();
         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 };
+        return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
       }
 
       // system 模式非 graceful exit 的文字回答（理论上不应到这里）
       const reply = this.#cleanFinalAnswer(aiResult.text || '');
       const totalDuration = Date.now() - execStartTime;
+      reasoning.afterRound();
       this.#logger.info(`[ChatAgent] ✅ final answer — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`);
-      return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+      return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
     }
 
     // ── 循环退出: 产出 dimensionDigest 总结 ──
-    return this.#produceForcedSummary({
+    reasoning.afterRound();
+    const forcedResult = await this.#produceForcedSummary({
       source, toolCalls, toolSchemas, ctx, phaseRouter, execStartTime,
     });
+    forcedResult.reasoningTrace = reasoning.trace;
+    forcedResult.reasoningQuality = reasoning.getQualityMetrics();
+    return forcedResult;
   }
 
   /**
@@ -850,7 +899,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;
@@ -865,7 +914,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');
 
@@ -912,7 +961,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
 {
@@ -954,10 +1003,19 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
     let consecutiveAiErrors = 0;
     const maxIter = source === 'system' ? MAX_ITERATIONS_SYSTEM : MAX_ITERATIONS;
 
+    // ── ReasoningLayer (文本解析模式) ──
+    const reasoning = new ReasoningLayer({
+      enabled: true,
+      reflectionEnabled: false,   // 文本模式暂不启用反思（避免复杂度）
+    });
+
     while (iterations < maxIter) {
       iterations++;
       const iterStartTime = Date.now();
 
+      // ── ReasoningLayer Hook 1: beforeAICall ──
+      reasoning.beforeAICall(iterations);
+
       let response;
       try {
         this.#logger.info(`[ChatAgent] 🔄 text iteration ${iterations}/${maxIter} — calling AI (${messages.length} messages)`);
@@ -969,24 +1027,33 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
         const responsePreview = (response || '').substring(0, 120).replace(/\n/g, '↵');
         this.#logger.info(`[ChatAgent] ✓ AI responded in ${aiDuration}ms (${(response || '').length} chars) — "${responsePreview}…"`);
         consecutiveAiErrors = 0;
+
+        // ── ReasoningLayer Hook 2: afterAICall ──
+        reasoning.afterAICall(response, 'text');
       } catch (aiErr) {
         consecutiveAiErrors++;
         this.#logger.warn(`[ChatAgent] AI call failed (attempt ${consecutiveAiErrors}): ${aiErr.message}`);
 
         // 熔断器已打开 → 立即返回
         if (aiErr.code === 'CIRCUIT_OPEN') {
+          reasoning.afterRound();
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
+            reasoningTrace: reasoning.trace,
+            reasoningQuality: reasoning.getQualityMetrics(),
           };
         }
 
         if (consecutiveAiErrors >= 2) {
+          reasoning.afterRound();
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
+            reasoningTrace: reasoning.trace,
+            reasoningQuality: reasoning.getQualityMetrics(),
           };
         }
         await new Promise(r => setTimeout(r, 2000));
@@ -997,7 +1064,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`);
@@ -1017,9 +1084,10 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
 
         const reply = this.#cleanFinalAnswer(response);
         const totalDuration = Date.now() - execStartTime;
+        reasoning.afterRound();
         this.#logger.info(`[ChatAgent] ✅ text final answer — ${reply.length} chars, ${iterations} iterations, ${toolCalls.length} tool calls, ${totalDuration}ms total`);
 
-        return { reply, toolCalls, hasContext: toolCalls.length > 0 };
+        return { reply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
       }
 
       // 执行工具
@@ -1058,8 +1126,17 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
           result: summarized,
         });
         batchResults.push({ tool: action.tool, result: toolResult });
+
+        // ── ReasoningLayer Hook 3: afterToolExec ──
+        reasoning.afterToolExec(action.tool, action.params, toolResult);
       }
 
+      // ── ReasoningLayer Hook 4: afterRound ──
+      reasoning.afterRound({
+        totalCalls: actions.length,
+        submitCount: 0,
+      });
+
       // 将工具结果注入为下一轮 prompt
       let observation;
       if (batchResults.length === 1) {
@@ -1098,7 +1175,7 @@ ${submitSummary ? `已提交候选:\n${submitSummary}\n` : ''}
     }
 
     const finalReply = this.#cleanFinalAnswer(finalResponse);
-    return { reply: finalReply, toolCalls, hasContext: toolCalls.length > 0 };
+    return { reply: finalReply, toolCalls, hasContext: toolCalls.length > 0, reasoningTrace: reasoning.trace, reasoningQuality: reasoning.getQualityMetrics() };
   }
 
   /**
@@ -1272,13 +1349,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 条` };
 
@@ -1334,10 +1411,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' };
@@ -1363,10 +1440,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' };
@@ -1493,7 +1570,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',
@@ -1549,8 +1626,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": "..."}}
 ]
 \`\`\`
 
@@ -1616,7 +1693,7 @@ ${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"] })
@@ -1624,7 +1701,7 @@ ${this.#projectBriefingCache}
 - 合并同类请求为一次调用，避免逐个搜索/读取浪费轮次。
 
 ## 「项目特写」= 基本用法 + 项目特征融合
-submit_candidate 的 code 字段必须是「项目特写」— 将技术的基本用法与本项目的特征融合为一体:
+submit_knowledge 的 code 字段必须是「项目特写」— 将技术的基本用法与本项目的特征融合为一体:
 1. **项目选择了什么**: 采用了哪种写法/模式/约定
 2. **为什么这样选**: 统计数据（N 个文件、占比 M%）
 3. **项目禁止什么**: 被放弃的写法、反模式、显式禁用标记
@@ -1998,19 +2075,20 @@ submit_candidate 的 code 字段必须是「项目特写」— 将技术的基
     try {
       const db = this.#container?.get('database');
       if (!db) return '';
-      // knowledge_type → kind 映射:
+      // knowledgeType → kind 映射:
       //   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 knowledgeType IN ('code-standard','code-style','best-practice','boundary-constraint')) as ruleCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledgeType IN ('code-pattern','architecture','solution')) as patternCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledgeType IN ('code-relation','inheritance','call-chain','data-flow','module-dependency')) as factCount,
+          (SELECT COUNT(*) FROM knowledge_entries WHERE lifecycle = 'active' AND knowledgeType = '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';

package/lib/service/chat/ContextWindow.js

@@ -218,7 +218,7 @@ export class ContextWindow {
     for (const m of removed) {
       if (m.role === 'assistant' && m.toolCalls) {
         for (const tc of m.toolCalls) {
-          if (tc.name === 'submit_candidate' || tc.name === 'submit_with_check') {
+          if (tc.name === 'submit_knowledge' || tc.name === 'submit_with_check') {
             this.#compactedSubmits.add(tc.args?.title || tc.args?.category || 'untitled');
           }
         }
@@ -339,7 +339,7 @@ export class ContextWindow {
         const m = this.#messages[i];
         if (m.role === 'assistant' && m.toolCalls) {
           for (const tc of m.toolCalls) {
-            if (tc.name === 'submit_candidate' || tc.name === 'submit_with_check') {
+            if (tc.name === 'submit_knowledge' || tc.name === 'submit_with_check') {
               this.#compactedSubmits.add(tc.args?.title || tc.args?.category || 'untitled');
             }
           }
@@ -393,8 +393,8 @@ export class ContextWindow {
 export function limitToolResult(toolName, result, quota) {
   const { maxChars = 4000, maxMatches = 10 } = quota;
 
-  // submit_candidate / submit_with_check 结果很短，不截断
-  if (toolName === 'submit_candidate' || toolName === 'submit_with_check') {
+  // submit_knowledge / submit_with_check 结果很短，不截断
+  if (toolName === 'submit_knowledge' || toolName === 'submit_with_check') {
     const raw = typeof result === 'string' ? result : JSON.stringify(result);
     return raw.length > 500 ? raw.substring(0, 500) : raw;
   }
@@ -783,7 +783,7 @@ export class PhaseRouter {
         if (this.#totalSubmits === 0 && this.#phaseRounds >= 1) {
           return this.#isSkillOnly
             ? '你已收集足够信息，请在回复中直接输出 dimensionDigest JSON。'
-            : '⚠️ 探索阶段已结束。你已收集了足够的项目信息，请 **立即** 调用 submit_candidate 提交候选。不要继续搜索，直接提交。';
+            : '⚠️ 探索阶段已结束。你已收集了足够的项目信息，请 **立即** 调用 submit_knowledge 提交候选。不要继续搜索，直接提交。';
         }
         if (this.#totalSubmits >= this.#budget.softSubmitLimit && this.#budget.softSubmitLimit > 0) {
           const remaining = this.#budget.maxSubmits - this.#totalSubmits;

package/lib/service/chat/HandoffProtocol.js

@@ -118,6 +118,7 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
       iterations: analystResult.toolCalls?.length || 0,
       toolCallCount: analystResult.toolCalls?.length || 0,
       tokenUsage: analystResult.tokenUsage || null,
+      reasoningQuality: analystResult.reasoningQuality || null,
     },
   };
 }