autosnippet 3.2.4 → 3.2.6

package/lib/service/chat/ChatAgent.js

@@ -38,10 +38,11 @@ import {
   taskGuardFullScan,
   taskQualityAudit,
 } from './ChatAgentTasks.js';
-import { ContextWindow, limitToolResult, PhaseRouter } from './ContextWindow.js';
+import { ContextWindow, limitToolResult } from './ContextWindow.js';
 import { ConversationStore } from './ConversationStore.js';
-import { Memory } from './Memory.js';
-import { ReasoningLayer } from './ReasoningLayer.js';
+import { ExplorationTracker } from './ExplorationTracker.js';
+import { MemoryCoordinator } from './memory/MemoryCoordinator.js';
+import { ActiveContext } from './memory/ActiveContext.js';
 import { TaskPipeline } from './TaskPipeline.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -82,8 +83,6 @@ export class ChatAgent {
   #pipelines = new Map();
   /** @type {string} 缓存的项目概况（每次 execute 刷新一次） */
   #projectBriefingCache = '';
-  /** @type {Memory|null} 跨对话轻量记忆 */
-  #memory = null;
   /** @type {ConversationStore|null} 对话持久化 */
   #conversations = null;
   /** @type {string|null} 当前 execute 调用的 source — 'user' | 'system' */
@@ -102,6 +101,8 @@ export class ChatAgent {
   #currentTokenUsage = { input: 0, output: 0 };
   /** @type {import('./ProjectSemanticMemory.js').ProjectSemanticMemory|null} Tier 3 语义记忆 */
   #semanticMemory = null;
+  /** @type {MemoryCoordinator|null} v5.0 统一记忆协调器 */
+  #memoryCoordinator = null;
 
   /**
    * @param {object} opts
@@ -127,18 +128,27 @@ export class ChatAgent {
     /** AI Provider 引用（只读）— 用于外部模块直接调用 structuredOutput / extractJSON */
     this.aiProvider = aiProvider || null;
 
-    // 初始化跨对话记忆 + 对话持久化
+    // 初始化对话持久化
     try {
       const projectRoot = container?.singletons?._projectRoot || process.cwd();
-      this.#memory = new Memory(projectRoot);
       this.#conversations = new ConversationStore(projectRoot);
     } catch {
-      /* Memory/ConversationStore init failed, degrade silently */
+      /* ConversationStore init failed, degrade silently */
     }
 
     // v4.1: 尝试初始化 ProjectSemanticMemory (Tier 3)
     this.#initSemanticMemory(container);
 
+    // v5.0: 初始化 MemoryCoordinator (User Chat 模式)
+    try {
+      this.#memoryCoordinator = new MemoryCoordinator({
+        conversationLog: this.#conversations,
+        mode: 'user',
+      });
+    } catch {
+      /* MemoryCoordinator init failed, degrade silently */
+    }
+
     // 注册内置 DAG 管线
     this.#registerBuiltinPipelines();
 
@@ -168,6 +178,19 @@ export class ChatAgent {
    */
   setSemanticMemory(sm) {
     this.#semanticMemory = sm;
+    // v5.0: 同步更新 MemoryCoordinator 的 persistentMemory
+    if (this.#memoryCoordinator && sm) {
+      // 直接重建 coordinator 以包含语义记忆
+      try {
+        this.#memoryCoordinator = new MemoryCoordinator({
+          persistentMemory: sm,
+          conversationLog: this.#conversations,
+          mode: 'user',
+        });
+      } catch {
+        /* non-critical */
+      }
+    }
   }
 
   /**
@@ -220,14 +243,12 @@ export class ChatAgent {
       // v3.0: Agent 分离选项
       systemPromptOverride, // 覆盖默认 system prompt (Analyst/Producer 各自使用)
       allowedTools, // 覆盖默认工具白名单 (string[])
-      disablePhaseRouter = false, // 禁用 PhaseRouter (Analyst 不需要阶段控制)
+      strategy, // v4.2: 策略名称 ('bootstrap'|'analyst'|'producer')
       temperature: temperatureOverride, // 覆盖默认温度
       projectLanguage, // 项目主语言，注入到 submit tool 的 ctx._projectLanguage
       lang, // UI 语言偏好 ('zh'|'en')，控制回复语言
-      // v4.0: Agent Memory 集成
-      workingMemory, // WorkingMemory 实例 (由 orchestrator 注入)
-      episodicMemory, // EpisodicMemory 实例 (跨维度情景记忆)
-      toolResultCache, // ToolResultCache 实例 (跨维度工具结果缓存)
+      // v5.0: 统一记忆协调器
+      memoryCoordinator, // MemoryCoordinator 实例
       // v5.1: SSE 流式进度回调
       onProgress, // (event: {type, ...}) => void — 实时推送思考/工具/回答事件
     } = {}
@@ -265,6 +286,11 @@ export class ChatAgent {
     // 返回 { text, functionCalls: null }，被 native 循环视为最终回答。
     this.#logger.info(`[ChatAgent] ✨ using NATIVE tool calling mode (${this.#aiProvider.name})`);
     let result;
+
+    // v5.0: 确定有效的 MemoryCoordinator
+    // 优先使用外部传入的 (bootstrap 模式)，否则使用实例级的 (user chat 模式)
+    const effectiveCoordinator = memoryCoordinator || this.#memoryCoordinator || null;
+
     result = await this.#executeWithNativeTools(prompt, {
       effectiveHistory,
       conversationId,
@@ -274,12 +300,10 @@ export class ChatAgent {
       dimensionMeta,
       systemPromptOverride,
       allowedTools,
-      disablePhaseRouter,
+      strategy,
       temperatureOverride,
       projectLanguage,
-      workingMemory,
-      episodicMemory,
-      toolResultCache,
+      memoryCoordinator: effectiveCoordinator,
       onProgress,
     });
 
@@ -307,7 +331,10 @@ export class ChatAgent {
       });
     }
 
-    this.#extractMemory(prompt, result.reply);
+    // v5.0: 通过 coordinator 提取记忆
+    if (effectiveCoordinator) {
+      effectiveCoordinator.extractFromConversation(prompt, result.reply, source);
+    }
 
     // 附加 token 用量统计
     result.tokenUsage = { ...this.#currentTokenUsage };
@@ -349,10 +376,10 @@ export class ChatAgent {
   /**
    * 原生结构化函数调用 ReAct 循环
    *
-   * 三层架构:
-   *   1. ContextWindow — 消息生命周期 + 三级递进压缩
-   *   2. PhaseRouter — 阶段状态机 (EXPLORE→PRODUCE→SUMMARIZE)
-   *   3. ToolResultLimiter — 工具结果入口压缩 (动态配额)
+   * v4.2 重写: 用 ExplorationTracker 统一管理生命周期
+   *   - ExplorationTracker: 信号收集 + 阶段路由 + Nudge 生成 + Graceful exit
+   *   - ReasoningTrace: 纯数据收集（推理链记录）
+   *   - ContextWindow: 消息管理 + 三级压缩
    *
    * @param {string} prompt
    * @param {object} opts
@@ -367,27 +394,19 @@ export class ChatAgent {
       execStartTime,
       budget = DEFAULT_BUDGET,
       dimensionMeta,
-      // v3.0: Agent 分离新增选项
       systemPromptOverride,
       allowedTools,
-      disablePhaseRouter = false,
+      strategy,
       temperatureOverride,
       projectLanguage,
-      // v4.0: Agent Memory 集成
-      workingMemory,
-      episodicMemory,
-      toolResultCache,
-      // v5.1: SSE 流式进度回调
+      memoryCoordinator,
       onProgress,
     }
   ) {
     const isSystem = source === 'system';
-    const isSkillOnly = dimensionMeta?.outputType === 'skill';
     const temperature = temperatureOverride ?? (isSystem ? 0.3 : 0.7);
 
     // ── Layer 1: ContextWindow ──
-    // messages[0] = prompt（不可压缩），历史消息在前面
-    // token 预算按模型动态适配：大窗口模型(Gemini/Claude)给更多预算，小窗口(Ollama)限制预算
     const tokenBudget = ContextWindow.resolveTokenBudget(this.#aiProvider?.model, { isSystem });
     const ctx = new ContextWindow(tokenBudget);
     for (const h of effectiveHistory) {
@@ -397,41 +416,49 @@ export class ChatAgent {
         ctx.appendUserMessage(h.content);
       }
     }
-    // prompt 作为最终 user message（Anthropic 最佳实践: 查询放在所有上下文之后）
     ctx.appendUserMessage(prompt);
 
-    // ── P5: Pre-check — 首条 prompt 过大时预警 ──
+    // ── Pre-check: 首条 prompt 过大时预警 ──
     const initialUsage = ctx.getTokenUsageRatio();
     if (initialUsage > 0.7) {
       this.#logger.warn(
         `[ChatAgent] ⚠ initial prompt already at ${(initialUsage * 100).toFixed(0)}% of token budget (${ctx.estimateTokens()}/${ctx.tokenBudget})`
       );
-      if (initialUsage > 0.9 && isSystem) {
-        // 仅 1 条消息时 compactIfNeeded 无法压缩（需 >4 条），
-        // 依赖 P0/P1 信号限制来控制 prompt 大小
-        this.#logger.warn(
-          `[ChatAgent] ⚠ prompt exceeds 90% budget — P0/P1 signal limiting should have prevented this. Check PROMPT_LIMITS config.`
-        );
-      }
     }
 
-    // ── Layer 2: PhaseRouter (仅 system 源且未禁用时使用) ──
-    const phaseRouter =
-      isSystem && !disablePhaseRouter ? new PhaseRouter(budget, isSkillOnly) : null;
+    // ── Layer 2: ExplorationTracker (替代 PhaseRouter + 内联探索追踪 + ReasoningLayer 行为控制) ──
+    const tracker = ExplorationTracker.resolve(
+      { source, strategy, dimensionMeta, allowedTools },
+      budget
+    );
 
-    // ── 系统提示词 (支持外部覆盖) ──
+    // ── 并行安全: 从 dimensionMeta + strategy 推导确定性 scopeId ──
+    // orchestrator 约定 scopeId = `${dimId}:${strategy}` (e.g. "api-patterns:analyst")
+    const dimensionScopeId = (dimensionMeta?.id && strategy)
+      ? `${dimensionMeta.id}:${strategy}`
+      : null;
+
+    // ── Layer 3: ActiveContext (合并 ReasoningTrace + WorkingMemory, Phase 3) ──
+    // 优先使用 coordinator 管理的 AC (由 orchestrator 通过 createDimensionScope 创建)，
+    // 避免两个独立 AC 实例导致数据断裂。
+    // User Chat 模式: coordinator 无 AC → 创建 lightweight 本地实例。
+    const trace = memoryCoordinator?.getActiveContext(dimensionScopeId) || new ActiveContext({
+      lightweight: !isSystem, // User 模式: 轻量 (仅 RT 功能, D5)
+      maxRecentRounds: isSystem ? 3 : 2,
+    });
+
+    // ── 系统提示词 ──
     let baseSystemPrompt =
       systemPromptOverride ||
       buildNativeToolSystemPrompt({
         currentSource: this.#currentSource,
         projectBriefingCache: this.#projectBriefingCache,
-        memory: this.#memory,
-        semanticMemory: this.#semanticMemory,
+        memoryCoordinator,
         budget,
         soulPath: SOUL_PATH,
       });
 
-    // ── 统一注入语言指令（对所有来源生效: user 对话 / system bootstrap / analyst / producer）──
+    // ── 语言指令 ──
     const effectiveLang = this.#currentLang;
     if (effectiveLang === 'en') {
       baseSystemPrompt +=
@@ -441,14 +468,14 @@ export class ChatAgent {
         '\n\n## 语言\n你必须使用中文回复。所有输出文本、分析、标题和描述都必须是中文。';
     }
 
-    // 统一注入轮次预算，确保 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
@@ -460,7 +487,6 @@ export class ChatAgent {
             'list_project_structure',
             'get_file_summary',
             'semantic_search_code',
-            // AST 结构化分析工具
             'get_project_overview',
             'get_class_hierarchy',
             'get_class_info',
@@ -468,7 +494,6 @@ export class ChatAgent {
             'get_method_overrides',
             'get_category_map',
             'get_previous_analysis',
-            // Agent Memory 工具 (v4.0)
             'note_finding',
             'get_previous_evidence',
           ]
@@ -479,145 +504,49 @@ export class ChatAgent {
     const maxIter = isSystem ? budget.maxIterations : MAX_ITERATIONS;
     let consecutiveAiErrors = 0;
     let consecutiveEmptyResponses = 0;
-    let iterationCount = 0; // v3: 独立迭代计数器
     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; // 连续无新信息轮次触发收敛
-
-    // ── 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,
-    });
+    const sharedState = {};
 
     // ── 主循环 ──
     while (true) {
-      // PhaseRouter tick + 退出检查
-      if (phaseRouter) {
-        phaseRouter.tick();
-        if (phaseRouter.shouldExit()) {
+      // ── ExplorationTracker: tick + 退出检查 ──
+      if (tracker) {
+        tracker.tick();
+        if (tracker.shouldExit()) {
           this.#logger.info(
-            `[ChatAgent] PhaseRouter exit: phase=${phaseRouter.phase}, iter=${phaseRouter.totalIterations}, submits=${phaseRouter.totalSubmits}`
+            `[ChatAgent] tracker exit: phase=${tracker.phase}, iter=${tracker.iteration}, submits=${tracker.totalSubmits}`
           );
           break;
         }
-        // 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) {
-        // 用户对话模式: 简单的消息数限制
+        // User 模式: 简单消息数限制
         break;
       }
-      iterationCount++;
 
+      const currentIter = tracker?.iteration || (ctx.length - 1);
       const iterStartTime = Date.now();
-      const currentIter = phaseRouter?.totalIterations || iterationCount;
 
-      // ── 动态 toolChoice (由 PhaseRouter 决定) ──
+      // ── 动态 toolChoice ──
       let currentChoice;
-      if (ctx.__gracefulExitInjected) {
-        // graceful exit: 禁止工具调用，强制 AI 输出文本总结
-        currentChoice = 'none';
-      } else if (phaseRouter) {
-        currentChoice = phaseRouter.getToolChoice();
+      if (tracker) {
+        currentChoice = tracker.getToolChoice();
       } else {
         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}`);
+      // ── Nudge 注入（每轮最多一条） ──
+      if (tracker) {
+        const nudge = tracker.getNudge(trace);
+        if (nudge) {
+          ctx.appendUserNudge(nudge.text);
+          this.#logger.info(`[ChatAgent] 💬 injected ${nudge.type} nudge at iter ${currentIter}`);
+        }
       }
 
-      // ── 压缩检查 (每次 AI 调用前) ──
+      // ── ReasoningTrace: 开始新轮次 ──
+      trace.startRound(currentIter);
+
+      // ── 压缩检查 ──
       const compactResult = ctx.compactIfNeeded();
       if (compactResult.level > 0) {
         this.#logger.info(
@@ -625,32 +554,23 @@ export class ChatAgent {
         );
       }
 
-      // ── 构建 systemPrompt (含阶段提示) ──
+      // ── 构建 systemPrompt (含阶段上下文) ──
       let systemPrompt = baseSystemPrompt;
-      if (phaseRouter) {
-        const hint = phaseRouter.getPhaseHint();
-        if (hint) {
-          systemPrompt += `\n\n## 当前状态\n${hint}`;
-        }
+      if (tracker) {
+        systemPrompt += tracker.getPhaseContext();
       } 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} 轮`;
+        // fallback: 非 tracker 路径注入进度
+        const remaining = maxIter - currentIter;
+        systemPrompt += `\n\n## 当前进度\n第 ${currentIter}/${maxIter} 轮 | 剩余 ${remaining} 轮`;
       }
 
-      // ── v4.0: WorkingMemory 上下文注入 ──
-      // 当有压缩后的旧观察或 scratchpad 发现时，注入到 system prompt
-      if (workingMemory && isSystem) {
-        const wmContext = workingMemory.buildContext();
+      // ── WorkingMemory 上下文注入 ──
+      // v5.0: 通过 coordinator 获取动态记忆上下文
+      if (isSystem && memoryCoordinator) {
+        const wmContext = memoryCoordinator.buildDynamicMemoryPrompt({
+          mode: strategy || 'analyst',
+          scopeId: dimensionScopeId,
+        });
         if (wmContext) {
           systemPrompt += `\n\n${wmContext}`;
         }
@@ -660,12 +580,11 @@ export class ChatAgent {
       let aiResult;
       try {
         const messages = ctx.toMessages();
-        const currentPhase = phaseRouter?.phase || 'user';
+        const currentPhase = tracker?.phase || 'user';
         this.#logger.info(
           `[ChatAgent] 🔄 iteration ${currentIter}/${maxIter} — phase=${currentPhase}, ${messages.length} msgs, toolChoice=${currentChoice}, tokens~${ctx.estimateTokens()}`
         );
 
-        // SSE: 推送步骤开始
         onProgress?.({
           type: 'step:start',
           step: currentIter,
@@ -684,7 +603,6 @@ export class ChatAgent {
 
         const aiDuration = Date.now() - iterStartTime;
 
-        // 累计 token 用量
         if (aiResult.usage) {
           this.#currentTokenUsage.input += aiResult.usage.inputTokens || 0;
           this.#currentTokenUsage.output += aiResult.usage.outputTokens || 0;
@@ -702,27 +620,32 @@ export class ChatAgent {
         }
         consecutiveAiErrors = 0;
 
-        // ── ReasoningLayer Hook 2: afterAICall — 提取 Thought ──
-        reasoning.afterAICall(aiResult);
+        // ── ReasoningTrace: 提取 Thought + Plan ──
+        if (aiResult.text) {
+          trace.setThought(aiResult.text);
+          trace.extractAndSetPlan(aiResult.text, currentIter);
+        }
       } catch (aiErr) {
         consecutiveAiErrors++;
         this.#logger.warn(
           `[ChatAgent] AI call failed (attempt ${consecutiveAiErrors}): ${aiErr.message}`
         );
 
-        // 熔断器已打开时立即跳出 — 不要继续浪费重试、也避免失败计数加速累积
+        // 回退 tick（AI 失败不计入迭代）
+        tracker?.rollbackTick();
+
         if (aiErr.code === 'CIRCUIT_OPEN') {
           if (isSystem) {
             this.#logger.warn(`[ChatAgent] 🛑 circuit breaker is OPEN — skipping to summary`);
             break;
           }
-          reasoning.afterRound();
+          trace.endRound();
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
-            reasoningTrace: reasoning.trace,
-            reasoningQuality: reasoning.getQualityMetrics(),
+            reasoningTrace: trace,
+            reasoningQuality: tracker?.getQualityMetrics(trace) || null,
           };
         }
 
@@ -734,14 +657,14 @@ export class ChatAgent {
             ctx.resetToPromptOnly();
             break;
           }
-          reasoning.afterRound();
+          trace.endRound();
           onProgress?.({ type: 'step:end', step: currentIter });
           return {
             reply: `抱歉，AI 服务暂时不可用（${aiErr.message}）。请稍后重试，或检查 API 配置。`,
             toolCalls,
             hasContext: toolCalls.length > 0,
-            reasoningTrace: reasoning.trace,
-            reasoningQuality: reasoning.getQualityMetrics(),
+            reasoningTrace: trace,
+            reasoningQuality: tracker?.getQualityMetrics(trace) || null,
           };
         }
         await new Promise((r) => setTimeout(r, 2000));
@@ -750,16 +673,15 @@ export class ChatAgent {
 
       // ── 处理 functionCalls ──
       if (aiResult.functionCalls && aiResult.functionCalls.length > 0) {
-        // ── Graceful exit 保护: Gemini 有时会无视 toolChoice='none' 继续返回工具调用
-        //    强制忽略工具调用，将附带文本视为最终回复
-        if (ctx.__gracefulExitInjected) {
+        // Graceful exit 保护: 忽略 toolChoice='none' 下的工具调用 (Gemini 偶发)
+        if (tracker?.isGracefulExit) {
           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 = cleanFinalAnswer(aiResult.text);
             const totalDuration = Date.now() - execStartTime;
-            reasoning.afterRound();
+            trace.endRound();
             this.#logger.info(
               `[ChatAgent] ✅ final answer (graceful exit, forced) — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`
             );
@@ -767,29 +689,29 @@ export class ChatAgent {
               reply,
               toolCalls,
               hasContext: toolCalls.length > 0,
-              reasoningTrace: reasoning.trace,
-              reasoningQuality: reasoning.getQualityMetrics(),
+              reasoningTrace: trace,
+              reasoningQuality: tracker?.getQualityMetrics(trace) || null,
             };
           }
-          // 无文本时继续循环，下一轮硬上限兜底
           continue;
         }
 
-        // 限制单次工具调用数量（防上下文溢出）
+        // 限制单次工具调用数量
         const MAX_TOOL_CALLS_PER_ITER = 8;
         let activeCalls = aiResult.functionCalls;
         if (activeCalls.length > MAX_TOOL_CALLS_PER_ITER) {
           this.#logger.warn(
             `[ChatAgent] ⚠ ${activeCalls.length} tool calls, capping to ${MAX_TOOL_CALLS_PER_ITER}`
           );
+          tracker?.recordTruncatedCalls(activeCalls.length - MAX_TOOL_CALLS_PER_ITER);
           activeCalls = activeCalls.slice(0, MAX_TOOL_CALLS_PER_ITER);
         }
 
-        // ContextWindow: 原子追加 assistant + tool results
         ctx.appendAssistantWithToolCalls(aiResult.text || null, activeCalls);
 
         let roundSubmitCount = 0;
-        let roundHasNewInfo = false; // 本轮是否获取到新信息
+        let roundHasNewInfo = false;
+        const roundToolNames = [];
 
         for (const fc of activeCalls) {
           const toolStartTime = Date.now();
@@ -797,7 +719,6 @@ export class ChatAgent {
             `[ChatAgent] 🔧 ${fc.name}(${JSON.stringify(fc.args).substring(0, 100)})`
           );
 
-          // SSE: 推送工具调用开始
           onProgress?.({
             type: 'tool:start',
             id: `tc_${fc.name}_${Date.now()}`,
@@ -808,9 +729,9 @@ export class ChatAgent {
           let toolResult;
           let cacheHit = false;
 
-          // v4.0: ToolResultCache — 先检查缓存，命中则跳过实际执行
-          if (toolResultCache) {
-            const cached = toolResultCache.get(fc.name, fc.args);
+          // v5.0: 缓存检查通过 coordinator
+          if (memoryCoordinator) {
+            const cached = memoryCoordinator.getCachedResult(fc.name, fc.args);
             if (cached !== null) {
               toolResult = cached;
               cacheHit = true;
@@ -830,11 +751,9 @@ export class ChatAgent {
                   _submittedPatterns: this.#globalSubmittedPatterns,
                   _sharedState: sharedState,
                   _projectLanguage: projectLanguage,
-                  // v4.0: Agent Memory
-                  _workingMemory: workingMemory || null,
-                  _episodicMemory: episodicMemory || null,
-                  _toolResultCache: toolResultCache || null,
-                  _currentRound: iterationCount,
+                  _memoryCoordinator: memoryCoordinator || null,
+                  _dimensionScopeId: dimensionScopeId,
+                  _currentRound: currentIter,
                 })
               );
               const toolDuration = Date.now() - toolStartTime;
@@ -846,7 +765,6 @@ export class ChatAgent {
                 `[ChatAgent] 🔧 done: ${fc.name} → ${resultSize} chars in ${toolDuration}ms`
               );
 
-              // SSE: 推送工具调用完成
               onProgress?.({
                 type: 'tool:end',
                 tool: fc.name,
@@ -858,7 +776,6 @@ export class ChatAgent {
               this.#logger.warn(`[ChatAgent] 🔧 FAILED: ${fc.name} — ${toolErr.message}`);
               toolResult = { error: `tool "${fc.name}" failed: ${toolErr.message}` };
 
-              // SSE: 推送工具调用失败
               onProgress?.({
                 type: 'tool:end',
                 tool: fc.name,
@@ -869,122 +786,29 @@ export class ChatAgent {
             }
           }
 
-          // v4.0: WorkingMemory — 记录工具观察
-          if (workingMemory && fc.name !== 'note_finding') {
-            workingMemory.observe(fc.name, toolResult, iterationCount);
-          }
-
-          // v4.0: ToolResultCache — 缓存搜索/读文件结果 (仅非缓存命中时写入)
-          if (toolResultCache && !cacheHit) {
-            toolResultCache.set(fc.name, fc.args, toolResult);
+          // v5.0: 统一记录观察 (缓存写入)
+          if (memoryCoordinator) {
+            memoryCoordinator.recordObservation(fc.name, fc.args, toolResult, currentIter, cacheHit);
           }
 
           // 记录到全局 toolCalls
           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++;
-            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;
-            }
+          // ── ExplorationTracker: 记录工具调用 (替代内联 ~120 行 if-else) ──
+          let isNew = false;
+          if (tracker) {
+            const trackResult = tracker.recordToolCall(fc.name, fc.args, toolResult);
+            isNew = trackResult.isNew;
+            if (isNew) roundHasNewInfo = true;
           }
 
-          // ── Layer 3: ToolResultLimiter — 动态配额压缩 ──
+          // ── ActiveContext: 统一记录 Action + Observation + WM 压缩 (Phase 3) ──
+          trace.recordToolCall(fc.name, fc.args, toolResult, isNew);
+
+          roundToolNames.push(fc.name);
+
+          // ── ToolResultLimiter: 动态配额压缩 ──
           const quota = ctx.getToolResultQuota();
           let resultStr = limitToolResult(fc.name, toolResult, quota);
 
@@ -999,7 +823,6 @@ export class ChatAgent {
             if (isRejected) {
               this.#logger.info(`[ChatAgent] 🚫 off-topic rejected: "${title}"`);
             } else if (isError) {
-              // 候选创建失败（如 validation error）— 不加入 submittedTitles，允许 AI 重试
               this.#logger.info(
                 `[ChatAgent] ⚠ submit error: "${title}" — ${toolResult.error || 'unknown'}`
               );
@@ -1009,7 +832,6 @@ export class ChatAgent {
             } else {
               submittedTitles.add(title.toLowerCase().trim());
               this.#globalSubmittedTitles.add(title.toLowerCase().trim());
-              // 记录代码模式指纹用于跨维度去重
               const pattern = fc.args?.content?.pattern || '';
               if (pattern.length >= 30) {
                 const fp = pattern
@@ -1026,175 +848,102 @@ export class ChatAgent {
             }
           }
 
-          // ContextWindow: 追加 tool result（与 assistant 保持原子性）
           ctx.appendToolResult(fc.id, fc.name, resultStr);
         }
 
-        // ── 探索饱和度更新 (非 PhaseRouter 路径) ──
-        if (!phaseRouter && isSystem && !roundHasNewInfo) {
-          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({
-            functionCalls: activeCalls,
+        // ── ExplorationTracker: endRound → 检查阶段转换 ──
+        if (tracker) {
+          tracker.updatePlanProgress(trace);
+          const transitionNudge = tracker.endRound({
+            hasNewInfo: roundHasNewInfo,
             submitCount: roundSubmitCount,
-            isTextOnly: false,
+            toolNames: roundToolNames,
           });
 
-          // ── EXPLORE→PRODUCE 阶段过渡: 注入提交引导消息 ──
-          // 原生工具调用模式下，仅靠 systemPrompt 附加 hint 不够显著，
-          // 需要一条 user 消息明确告知 AI 切换到提交模式
-          if (transition.transitioned && transition.newPhase === 'PRODUCE') {
-            ctx.appendUserNudge(
-              '你已充分探索了项目代码，现在请开始调用 submit_knowledge 工具来提交你发现的知识候选。不要再搜索，直接提交。'
-            );
-            this.#logger.info('[ChatAgent] 📝 injected PRODUCE transition nudge');
-          }
-
-          // ── EXPLORE→SUMMARIZE / PRODUCE→SUMMARIZE 阶段过渡: 注入 digest 引导 ──
-          // skill-only 维度从 EXPLORE 直接进入 SUMMARIZE (跳过 PRODUCE)，
-          // 需要明确告知 AI 输出 dimensionDigest JSON
-          if (transition.transitioned && transition.newPhase === 'SUMMARIZE') {
-            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 留空数组 \`[]\`。如果有未来得及处理的信号，请在此标记，系统会在下次运行时续传。`
+          if (transitionNudge) {
+            ctx.appendUserNudge(transitionNudge.text);
+            this.#logger.info(
+              `[ChatAgent] 📝 injected ${transitionNudge.type} nudge (${tracker.phase})`
             );
-            this.#logger.info('[ChatAgent] 📝 injected SUMMARIZE transition nudge');
           }
         }
 
-        // SSE: 步骤结束
+        // ── ReasoningTrace: 关闭轮次 ──
+        trace.setRoundSummary({
+          newInfoCount: roundHasNewInfo ? 1 : 0,
+          totalCalls: activeCalls.length,
+          submits: roundSubmitCount,
+          cumulativeFiles: tracker?.getMetrics().uniqueFiles || 0,
+          cumulativePatterns: tracker?.getMetrics().uniquePatterns || 0,
+        });
+        trace.endRound();
+
         onProgress?.({ type: 'step:end', step: currentIter });
         continue;
       }
 
       // ── 文字回答 ──
-      // SSE: 文字回答意味着步骤结束
       onProgress?.({ type: 'step:end', step: currentIter });
-      // 空响应重试（Gemini 偶发）
+
+      // 空响应重试 (Gemini 偶发)
       if (!aiResult.text && isSystem && consecutiveEmptyResponses < 2) {
         consecutiveEmptyResponses++;
         this.#logger.warn(
           `[ChatAgent] ⚠ empty response from system source — retrying (${consecutiveEmptyResponses}/2)`
         );
+        tracker?.rollbackTick();
         await new Promise((r) => setTimeout(r, 1500));
         continue;
       }
-      // 收到非空响应时重置空响应计数器
       if (aiResult.text) {
         consecutiveEmptyResponses = 0;
       }
 
-      // PhaseRouter: 文字回答触发阶段转换
-      if (phaseRouter) {
-        const transition = phaseRouter.update({
-          functionCalls: null,
-          submitCount: 0,
-          isTextOnly: true,
-        });
+      // ── ExplorationTracker: 处理文本响应 ──
+      if (tracker) {
+        const textResult = tracker.onTextResponse();
 
-        // SUMMARIZE 阶段的文字回答 = 最终回答
-        if (phaseRouter.phase === 'SUMMARIZE') {
-          // 刚从 EXPLORE/PRODUCE 转入 SUMMARIZE 的文字回答可能不含 digest，
-          // 注入 nudge 让 AI 再输出一次 digest JSON
-          if (transition.transitioned) {
-            ctx.appendAssistantText(aiResult.text || '');
-            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: 记录未来得及处理的信号。已全部覆盖则留空 \`[]\`。`
-            );
-            this.#logger.info(
-              '[ChatAgent] 📝 injected SUMMARIZE nudge (text-triggered transition)'
-            );
-            continue;
-          }
-          // 已在 SUMMARIZE 阶段 — 这就是最终回答
+        if (textResult.isFinalAnswer) {
+          // 已在终结阶段且非刚转入 → 最终回答
           const reply = cleanFinalAnswer(aiResult.text || '');
           const totalDuration = Date.now() - execStartTime;
-          reasoning.afterRound();
+          trace.endRound();
           this.#logger.info(
-            `[ChatAgent] ✅ final answer — ${reply.length} chars, ${phaseRouter.totalIterations} iters, ${toolCalls.length} tool calls, ${totalDuration}ms`
+            `[ChatAgent] ✅ final answer — ${reply.length} chars, ${tracker.iteration} iters, ${toolCalls.length} tool calls, ${totalDuration}ms`
           );
           return {
             reply,
             toolCalls,
             hasContext: toolCalls.length > 0,
-            reasoningTrace: reasoning.trace,
-            reasoningQuality: reasoning.getQualityMetrics(),
+            reasoningTrace: trace,
+            reasoningQuality: tracker.getQualityMetrics(trace),
           };
         }
 
-        if (!transition.transitioned) {
-          // 在 EXPLORE/PRODUCE 阶段收到文本但未转阶段 — 可能是 AI 的中间分析
-          // 注入提交引导并继续循环，而非立即返回
-          if (phaseRouter.phase === 'EXPLORE' || phaseRouter.phase === 'PRODUCE') {
-            ctx.appendAssistantText(aiResult.text || '');
-            if (phaseRouter.phase === 'PRODUCE') {
-              ctx.appendUserNudge(
-                '你的分析很好。请继续调用 submit_knowledge 提交你发现的知识候选，每个值得记录的模式/实践都应该提交。'
-              );
-              this.#logger.info(
-                '[ChatAgent] 📝 injected submit nudge (text in PRODUCE, not transitioning)'
-              );
-            }
-            continue;
-          }
-          // 非生产阶段的未转换文本 = 最终回答
-          const reply = 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,
-            reasoningTrace: reasoning.trace,
-            reasoningQuality: reasoning.getQualityMetrics(),
-          };
+        if (textResult.needsDigestNudge) {
+          // 刚转入终结阶段 → 注入 digest nudge，继续循环
+          ctx.appendAssistantText(aiResult.text || '');
+          ctx.appendUserNudge(textResult.nudge);
+          this.#logger.info('[ChatAgent] 📝 injected SUMMARIZE nudge (text-triggered transition)');
+          trace.endRound();
+          continue;
         }
 
-        // 其他阶段的文字回答 → 继续循环（PhaseRouter 已自动转换阶段）
-        ctx.appendAssistantText(aiResult.text || '');
-        continue;
-      }
-
-      // 用户对话 / graceful exit: 文字回答即最终回答
-      if (ctx.__gracefulExitInjected || !isSystem) {
-        const reply = 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,
-          reasoningTrace: reasoning.trace,
-          reasoningQuality: reasoning.getQualityMetrics(),
-        };
+        if (textResult.shouldContinue) {
+          // 非终结阶段的中间文本 → 注入可选 nudge，继续循环
+          ctx.appendAssistantText(aiResult.text || '');
+          if (textResult.nudge) {
+            ctx.appendUserNudge(textResult.nudge);
+          }
+          trace.endRound();
+          continue;
+        }
       }
 
-      // system 模式非 graceful exit 的文字回答（理论上不应到这里）
+      // User 模式 / 非 tracker: 文字回答即最终回答
       const reply = cleanFinalAnswer(aiResult.text || '');
       const totalDuration = Date.now() - execStartTime;
-      reasoning.afterRound();
+      trace.endRound();
       this.#logger.info(
         `[ChatAgent] ✅ final answer — ${reply.length} chars, ${toolCalls.length} tool calls, ${totalDuration}ms`
       );
@@ -1202,24 +951,24 @@ export class ChatAgent {
         reply,
         toolCalls,
         hasContext: toolCalls.length > 0,
-        reasoningTrace: reasoning.trace,
-        reasoningQuality: reasoning.getQualityMetrics(),
+        reasoningTrace: trace,
+        reasoningQuality: tracker?.getQualityMetrics(trace) || null,
       };
     }
 
     // ── 循环退出: 产出 dimensionDigest 总结 ──
-    reasoning.afterRound();
+    trace.endRound();
     const forcedResult = await this.#produceForcedSummary({
       source,
       toolCalls,
       toolSchemas,
       ctx,
-      phaseRouter,
+      tracker,
       execStartTime,
       prompt,
     });
-    forcedResult.reasoningTrace = reasoning.trace;
-    forcedResult.reasoningQuality = reasoning.getQualityMetrics();
+    forcedResult.reasoningTrace = trace;
+    forcedResult.reasoningQuality = tracker?.getQualityMetrics(trace) || null;
     return forcedResult;
   }
 
@@ -1232,11 +981,11 @@ export class ChatAgent {
     toolCalls,
     toolSchemas,
     ctx,
-    phaseRouter,
+    tracker,
     execStartTime,
     prompt,
   }) {
-    const iterations = phaseRouter?.totalIterations || 0;
+    const iterations = tracker?.iteration || 0;
     const isSystem = source === 'system';
     this.#logger.info(
       `[ChatAgent] ⚠ producing forced summary (${iterations} iters, ${toolCalls.length} calls, source=${source})`
@@ -1740,6 +1489,18 @@ ${toolContextSummary}
         import('./ProjectSemanticMemory.js')
           .then(({ ProjectSemanticMemory }) => {
             this.#semanticMemory = new ProjectSemanticMemory(db, { logger: this.#logger });
+            // v5.0: 更新 MemoryCoordinator 的 persistentMemory
+            if (this.#memoryCoordinator) {
+              try {
+                this.#memoryCoordinator = new MemoryCoordinator({
+                  persistentMemory: this.#semanticMemory,
+                  conversationLog: this.#conversations,
+                  mode: 'user',
+                });
+              } catch {
+                /* non-critical */
+              }
+            }
           })
           .catch(() => {
             /* Semantic Memory not available */
@@ -1750,85 +1511,6 @@ ${toolContextSummary}
     }
   }
 
-  /**
-   * 从对话中提取值得记忆的信息写入 Memory
-   *
-   * 双层策略:
-   *   1. 规则快速匹配（零延迟，覆盖明确的中英文模式）
-   *   2. AI 驱动提取（异步后台，从 reply 中提取 [MEMORY] 标签）
-   *
-   * source 隔离: 标记 memory 来源，避免系统分析污染用户记忆
-   */
-  #extractMemory(prompt, reply) {
-    if (!this.#memory && !this.#semanticMemory) {
-      return;
-    }
-    const source = this.#currentSource || 'user';
-
-    try {
-      // ── 层 1: 规则快速匹配（中文 + 英文） ──
-      const prefPatterns = [
-        /我们(项目|团队)?(不用|不使用|禁止|避免|偏好|习惯|规范是)/,
-        /以后(都|请|要)/,
-        /记住/,
-        /we\s+(don'?t|never|always|prefer|avoid)\s+use/i,
-        /remember\s+(to|that)/i,
-        /our\s+(convention|standard|rule)\s+is/i,
-      ];
-      if (prefPatterns.some((p) => p.test(prompt))) {
-        const entry = {
-          type: 'preference',
-          content: prompt.substring(0, 200),
-          source,
-          ttl: 30,
-        };
-        this.#memory?.append(entry);
-        this.#semanticMemory?.append({ ...entry, ttl: undefined });
-      }
-
-      const decisionPatterns = [
-        /决定(了|用|采用|使用)/,
-        /(确认|同意|通过)(了|这个方案|审核)/,
-        /就(这样|这么)(做|定|办)/,
-        /let'?s\s+(go\s+with|use|adopt)/i,
-        /approved|confirmed|decided/i,
-      ];
-      if (decisionPatterns.some((p) => p.test(prompt))) {
-        const entry = {
-          type: 'decision',
-          content: prompt.substring(0, 200),
-          source,
-          ttl: 60,
-        };
-        this.#memory?.append(entry);
-        this.#semanticMemory?.append({ ...entry, ttl: undefined });
-      }
-
-      // ── 层 2: 从 AI reply 中提取 [MEMORY] 标签 ──
-      // AI 可在回复中嵌入: [MEMORY:preference] 内容 [/MEMORY]
-      if (reply) {
-        const memoryTagRegex = /\[MEMORY:(\w+)\]\s*([\s\S]*?)\s*\[\/MEMORY\]/g;
-        let match;
-        while ((match = memoryTagRegex.exec(reply)) !== null) {
-          const type = match[1]; // preference | decision | context
-          const content = match[2].trim();
-          if (content && ['preference', 'decision', 'context'].includes(type)) {
-            const entry = {
-              type,
-              content: content.substring(0, 200),
-              source,
-              ttl: type === 'context' ? 90 : type === 'decision' ? 60 : 30,
-            };
-            this.#memory?.append(entry);
-            this.#semanticMemory?.append({ ...entry, ttl: undefined });
-          }
-        }
-      }
-    } catch {
-      /* memory write failure is non-critical */
-    }
-  }
-
   /**
    * 自动压缩过长的对话（异步后台执行）
    * 当对话消息数超过 12 条时触发 AI 摘要压缩