@zooique/memora 1.0.1 → 2.0.0

package/dist/agent/agent.js

@@ -22,27 +22,30 @@
  *   - 记忆查看 → MemoryInspector
  *   - 薄包装方法移除，调用方改为 agent.<manager>.xxx()
  */
-import { basename } from 'node:path';
+import { getBaseName } from '../utils/path.js';
 import { AGENT_CONSTANTS } from '../agent/constants.js';
 import { ProjectManager } from '../memory/projectManager.js';
 import { SecurityGuard } from '../security/pathGuard.js';
 import { recall } from '../memory/recall.js';
-import { extractUserFacts } from '../agent/userFactExtractor.js';
 import { assembleComponents } from '../agent/assembler.js';
-import { configError } from '../utils/errors.js';
-import { safeSetTimeout, clearSafeTimeout, clearSafeInterval } from '../utils/safeTimer.js';
+import { matchPersonaByLlm } from '../agent/personaMatcher.js';
+import { chatBusyError, configError } from '../utils/errors.js';
+import { clearSafeInterval } from '../utils/safeTimer.js';
 import { SessionManager } from '../agent/managers/sessionManager.js';
+import { ChatLockManager } from '../agent/managers/chatLockManager.js';
 import { MemoryDecayScheduler } from '../agent/managers/memoryDecayScheduler.js';
 import { ArchiveCoordinator } from '../agent/managers/archiveCoordinator.js';
 import { TypedEventEmitter } from '../utils/eventEmitter.js';
 import { logger } from '../logging/logger.js';
+import { TRACE_SPANS, NOOP_TRACER } from '../agent/tracer.js';
 // ─── 模块级常量 ─────────────────────────────────────────
 /** Agent 事件名白名单，用于运行时校验 SessionManager 转发的事件类型 */
-// 必须与 utils/eventEmitter.ts 的 AgentEventMap 键集保持一致（9 个事件）
+// 必须与 utils/eventEmitter.ts 的 AgentEventMap 键集保持一致（10 个事件）
 const AGENT_EVENT_NAMES = new Set([
     'memoryAdded', 'personaSwitched', 'decayCompleted',
     'memoryRecalled', 'sessionForked', 'insightExtracted',
     'conflictDetected', 'projectSwitched', 'skillMatched',
+    'archiveFailed',
 ]);
 // ─── Agent 门面类 ───────────────────────────────────────
 /**
@@ -95,13 +98,13 @@ export class Agent extends TypedEventEmitter {
     insightExtractor = null;
     configManager = null;
     memoryInspector = null;
-    /** 记忆写入器（P1-2 拆分，与 MemoryInspector 严格分工：写操作代理；ES 私有字段避免与 getter 重名递归） */
-    #memoryMutator = null;
     workProjection = null;
     /** AutoConfigRefiner（模式 3：Agent 智能总结） */
     autoConfigRefiner = null;
     /** SessionArchiver（会话内容归档器，content 类记忆） */
     sessionArchiver = null;
+    /** TextPolishManager（文本润色管理器，LLM 语法修正 + 表达优化） */
+    textPolisher = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     _sessionManager = null;
     /** 当前激活的技能名（上一轮匹配，本轮注入） */
@@ -109,29 +112,13 @@ export class Agent extends TypedEventEmitter {
     _initialized = false;
     // 项目上下文（AgentContext 与 ProjectContext 等价，直接使用后者避免重复字段）
     pctx = null;
-    /** chat() 并发锁 */
-    _chatBusy = false;
     /**
-     * chat() 锁持有者 token（race condition 防护）
+     * chat() 并发锁管理器（init 时创建，close 时销毁）
      *
-     * 设计目的：
-     *   原锁是简单布尔值 `_chatBusy`，无 owner 校验。超时回调与 finally 块无差别清理，
-     *   导致 race condition：T=0 A 获取锁 → T=180s 超时释放 → T=181s B 获取锁
-     *   → T=182s A 的 finally 误清 B 的锁/计时器/controller。
-     *
-     * 防护方案：
-     *   - 获取锁时 token 递增：`const myToken = ++this._chatLockToken`
-     *   - 超时回调校验 `this._chatLockToken === myToken` 后才释放
-     *   - finally 块校验 `this._chatLockToken === myToken` 后才清理
-     *   - 不匹配时跳过清理，避免误清新调用者的资源
-     *
-     * 选择 number 而非 Symbol：递增计数器可序列化、零依赖、足够唯一（同一 Agent 实例内）
+     * 职责：chat() 并发锁 + token 校验（race condition 防护）+ 超时保护 + 外部 signal 合并。
+     * 详见 ChatLockManager 类注释。
      */
-    _chatLockToken = 0;
-    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
-    chatLockTimer = null;
-    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
-    chatAbortController = null;
+    chatLockManager = null;
     /** 记忆衰减定时器（已迁移至 MemoryDecayScheduler，此字段保留用于 close 时引用判断） */
     decayTimer = null;
     /** 最近一次 chat() 调用的时间戳 */
@@ -177,7 +164,7 @@ export class Agent extends TypedEventEmitter {
      */
     async init(projectPathOverride) {
         if (this._initialized) {
-            // 修复 #3：close() 失败不应阻塞 init() 重建
+            // close() 失败不应阻塞 init() 重建
             // 原 close() 异常（如 awaitPendingArchives 超时）会传播到 init() 调用方，
             // 导致 Agent 处于不可用状态。此处捕获后继续重建。
             try {
@@ -207,6 +194,8 @@ export class Agent extends TypedEventEmitter {
                 '确认 API Key 已配置（环境变量或配置文件）',
             ]);
         }
+        // chat() 并发锁管理器（生命周期与 Agent 实例一致）
+        this.chatLockManager = new ChatLockManager();
         this._initialized = true;
         // 归档操作委托给 ArchiveCoordinator
         // 使用 getter 回调注入依赖，close 时 null 化字段后 getter 自然返回 null
@@ -217,9 +206,22 @@ export class Agent extends TypedEventEmitter {
             emit: (event, payload) => this.emit(event, payload),
         });
         // 记忆衰减职责委托给 MemoryDecayScheduler
+        // L2 时效性评估：注入 backgroundProvider + index（可选，未注入时 evaluateTimeliness 静默跳过）
         this.memoryDecayScheduler = new MemoryDecayScheduler({
             tracer: this.#config.tracer,
-            onDecayCompleted: (payload) => this.emit('decayCompleted', payload),
+            onDecayCompleted: (payload) => {
+                this.emit('decayCompleted', payload);
+                // G2 自动触发 L2 时效性评估：衰减完成后 fire-and-forget 调用 evaluateTimeliness。
+                // 不 await：衰减循环不应被 LLM 调用阻塞（LLM 可能 5-15 秒）。
+                // 失败静默降级：evaluateTimeliness 内部已捕获 LLM 异常并返回降级报告。
+                // 触发频次：每小时 1 次（DECAY_INTERVAL_MS=3_600_000），无频次压力。
+                void this.evaluateTimeliness().catch((err) => {
+                    // 仅记录日志，不抛错（与 onDecayCompleted 回调语义一致：不阻塞衰减循环）
+                    logger.warn({ err }, 'L2 时效性评估自动触发失败（已降级，不影响衰减循环）');
+                });
+            },
+            backgroundProvider: this.#backgroundProvider,
+            index: pctx.index,
         });
         this.memoryDecayScheduler.start(pctx.index, AGENT_CONSTANTS.DECAY_INTERVAL_MS);
         // 保留 decayTimer 引用用于 close 时序兼容（实际定时器由 MemoryDecayScheduler 管理）
@@ -234,46 +236,23 @@ export class Agent extends TypedEventEmitter {
         if (input.length > AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH) {
             throw configError('输入过长', `输入超过最大长度限制（${AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH / 1024}KB）`, ['缩短输入内容', '分多次对话发送']);
         }
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再发起新对话', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽（收到 done 事件）',
-                '宿主程序应确保同一时间只有一个 chat() 调用',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('发起新对话');
         }
-        this._chatBusy = true;
-        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
-        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
-        const myToken = ++this._chatLockToken;
-        // 内部 AbortController，超时时中断 generator 而非仅释放锁
-        const internalAbort = new AbortController();
-        this.chatAbortController = internalAbort;
+        // 获取锁 + 分配 token + 创建内部 AbortController + 启动超时定时器
+        // token 用于 finally 校验，避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
+        // assertInitialized 已保证 chatLockManager/loop/history 非 null，此处用 ! 窄化类型
+        const chatLock = this.chatLockManager;
+        const { token: myToken, internalAbort } = chatLock.acquire(AGENT_CONSTANTS.CHAT_LOCK_TIMEOUT_MS);
         // 合并外部 signal：外部 abort 时也触发内部
-        const onExternalAbort = () => internalAbort.abort();
-        signal?.addEventListener('abort', onExternalAbort, { once: true });
-        // 修复 #4：addEventListener 对已 aborted 的 signal 不触发回调
-        // 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程
-        if (signal?.aborted) {
-            internalAbort.abort();
-        }
+        const cleanupExternalSignal = chatLock.attachExternalSignal(signal, internalAbort);
         const combinedSignal = internalAbort.signal;
-        // 超时保护：LLM 卡死时中断 generator + 释放锁，防止并发
-        // 超时回调校验 token 后才清理，避免误清新调用者的资源
-        this.chatLockTimer = safeSetTimeout(() => {
-            // 令牌不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
-            if (this._chatLockToken !== myToken) {
-                return;
-            }
-            logger.warn({ timeoutMs: AGENT_CONSTANTS.CHAT_LOCK_TIMEOUT_MS }, 'chat() 锁超时，中断 generator 并释放锁');
-            internalAbort.abort();
-            this._chatBusy = false;
-            this.chatLockTimer = null;
-            this.chatAbortController = null;
-        }, AGENT_CONSTANTS.CHAT_LOCK_TIMEOUT_MS);
         try {
             this._lastInteractionAt = new Date();
             // 清理上一轮注入的临时 system 消息（recentConversation/skill/recall/truncation）
             // 防止多轮累积：每轮 chat() 开始前，只保留 messages[0] 和非 system 消息
-            this.requireNonNull(this.loop, 'loop').cleanTemporarySystemMessages();
+            const loop = this.loop;
+            loop.cleanTemporarySystemMessages();
             // 基元驱动召回（双通道：语义 + 关键词）
             yield { type: 'thinking', phase: 'recalling' };
             const recalledMemories = await this.recallAndInject(input);
@@ -287,13 +266,14 @@ export class Agent extends TypedEventEmitter {
             // 注入上一轮匹配的技能 prompt
             yield { type: 'thinking', phase: 'processing' };
             this.injectActiveSkill();
-            await this.requireNonNull(this.history, 'history').appendUser(input);
+            const history = this.history;
+            await history.appendUser(input);
             let assistantContent = '';
             let wasAborted = false;
             // 把 provider 异常转为 yield error chunk，让宿主能优雅展示并清理 UI
             // （裸 throw 会导致未处理 rejection，UI 收不到错误展示机会）
             try {
-                for await (const chunk of this.requireNonNull(this.loop, 'loop').processUserInput(input, recalledMemories, combinedSignal)) {
+                for await (const chunk of loop.processUserInput(input, recalledMemories, combinedSignal)) {
                     yield chunk;
                     if (chunk.type === 'text') {
                         assistantContent += chunk.content;
@@ -325,7 +305,7 @@ export class Agent extends TypedEventEmitter {
                 if (assistantContent.trim()) {
                     const interruptedMark = this.#config.messages?.interrupted ?? '\n\n[已中断]';
                     try {
-                        await this.requireNonNull(this.history, 'history').appendAssistant(assistantContent + interruptedMark);
+                        await history.appendAssistant(assistantContent + interruptedMark);
                     }
                     catch (err) {
                         logger.warn({ err }, '中断消息历史写入失败');
@@ -335,7 +315,7 @@ export class Agent extends TypedEventEmitter {
             }
             // 追加助手消息到历史（best-effort：失败不影响用户已收到的回答）
             try {
-                await this.requireNonNull(this.history, 'history').appendAssistant(assistantContent);
+                await history.appendAssistant(assistantContent);
             }
             catch (err) {
                 logger.warn({ err }, '助手消息历史写入失败');
@@ -345,17 +325,10 @@ export class Agent extends TypedEventEmitter {
             await this.postProcess(input, assistantContent);
         }
         finally {
-            // 仅当本调用仍是当前锁持有者时才清理资源
+            // 仅当本调用仍是当前锁持有者时才清理资源（token 校验）
             // 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态
-            if (this._chatLockToken === myToken) {
-                this._chatBusy = false;
-                this.chatAbortController = null;
-                if (this.chatLockTimer) {
-                    clearSafeTimeout(this.chatLockTimer);
-                    this.chatLockTimer = null;
-                }
-            }
-            signal?.removeEventListener('abort', onExternalAbort);
+            this.chatLockManager?.release(myToken);
+            cleanupExternalSignal();
         }
     }
     /**
@@ -369,7 +342,7 @@ export class Agent extends TypedEventEmitter {
      *
      * 本方法让宿主在确认 generator 挂起后强制释放锁，让用户能立即发起新对话。
      *
-     * 安全机制：
+     * 安全机制（委托至 ChatLockManager.forceRelease）：
      *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
      *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
      *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
@@ -384,22 +357,7 @@ export class Agent extends TypedEventEmitter {
      *   - 调用后不应再消费原 chat() generator 的后续 chunk（token 已变，chunk 无意义）
      */
     forceReleaseChatLock() {
-        if (!this._chatBusy)
-            return;
-        // 递增 token 让原 chat() 的 finally 块跳过清理（避免误清新调用者的资源）
-        this._chatLockToken++;
-        // abort 当前 generator（响应 signal 的 await 点会 throw AbortError 退出）
-        if (this.chatAbortController) {
-            this.chatAbortController.abort();
-            this.chatAbortController = null;
-        }
-        // 清理锁超时定时器（避免后续触发重复清理）
-        if (this.chatLockTimer) {
-            clearSafeTimeout(this.chatLockTimer);
-            this.chatLockTimer = null;
-        }
-        this._chatBusy = false;
-        logger.warn('对话锁被强制释放（宿主无进展超时兜底）');
+        this.chatLockManager?.forceRelease();
     }
     /**
      * 召回记忆 + 注入最近对话上下文
@@ -412,16 +370,33 @@ export class Agent extends TypedEventEmitter {
      * @returns 召回的记忆列表
      */
     async recallAndInject(input) {
-        const recalledMemories = await recall(this.requireNonNull(this.pctx, 'projectContext').index, input, {
-            limit: 5,
-            vectorStore: this.#config.vectorStore,
-            excludeSources: this.#config.recallExcludeSources,
+        // 实际 recall() 函数耗时 span（区别于 loop.ts 的 RECALL 注入 span）
+        const tracer = this.#config.tracer ?? NOOP_TRACER;
+        const recallSpan = tracer.startSpan(TRACE_SPANS.RECALL_ACTUAL, {
+            queryLength: input.length,
+            hasVectorStore: !!this.#config.vectorStore,
         });
+        let recalledMemories = [];
+        try {
+            recalledMemories = await recall(this.pctx.index, input, {
+                limit: 5,
+                vectorStore: this.#config.vectorStore,
+                excludeSources: this.#config.recallExcludeSources,
+            });
+        }
+        catch (err) {
+            recallSpan.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            recallSpan.setAttribute('resultCount', recalledMemories.length);
+            recallSpan.end();
+        }
         if (recalledMemories.length > 0) {
             this.emit('memoryRecalled', { count: recalledMemories.length, query: input });
         }
         // Layer 5: 最近对话注入
-        const loop = this.requireNonNull(this.loop, 'loop');
+        const loop = this.loop;
         const recentHistory = loop.getRecentHistory(3);
         if (recentHistory.length > 0) {
             const msgs = this.#config.messages;
@@ -464,10 +439,38 @@ export class Agent extends TypedEventEmitter {
      *   （会话归档实现后，`insights-only` 将跳过对话原始内容自动归档）
      */
     async postProcess(input, assistantContent) {
+        // postProcess 全流程 span（角色匹配 + 技能匹配 + 归档 + AutoConfigRefiner）
+        const tracer = this.#config.tracer ?? NOOP_TRACER;
+        const span = tracer.startSpan(TRACE_SPANS.POST_PROCESS, {
+            archiveMode: this.#config.archiveMode,
+        });
+        try {
+            await this.postProcessInner(input, assistantContent);
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * postProcess 内部实现（为 span 埋点提供 try/finally 包裹边界）
+     *
+     * 原 postProcess 逻辑完整保留于此，由外层 postProcess 负责 span 生命周期管理。
+     */
+    async postProcessInner(input, assistantContent) {
         // 角色自动匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
+        // 两层匹配策略：关键词高置信度 → LLM 辅助（低置信度且 backgroundProvider 已注入时）
+        // LLM 辅助匹配在 agent 层执行，遵循 backend_layers_rules §分层职责（persona/ 不直接调 LLM）
         if (this.personaManager) {
             try {
-                const matchedPersona = this.personaManager.autoMatch(input);
+                let matchedPersona = null;
+                if (this.personaManager.canAutoMatch()) {
+                    matchedPersona = await this.personaManager.autoMatch(input);
+                    // 关键词低置信度且 backgroundProvider 已注入 → LLM 辅助语义匹配
+                    const bgProvider = this.#backgroundProvider;
+                    if (!matchedPersona && bgProvider) {
+                        matchedPersona = await matchPersonaByLlm(bgProvider, this.personaManager.list, this.personaManager.activeName, input);
+                    }
+                }
                 if (matchedPersona) {
                     const prevName = this.personaManager.activeName;
                     this.personaManager.switchPersona(matchedPersona);
@@ -508,46 +511,36 @@ export class Agent extends TypedEventEmitter {
         if (skipAutoArchive) {
             logger.debug({ mode: 'manual' }, '归档模式为 manual，跳过自动归档');
         }
-        // 用户画像实时归档（语义解析在 agent/ 层，存储在 memory/ 层）
+        // 用户画像实时归档（委托 ArchiveCoordinator，与手动归档路径统一，消除 DRY 违反）
         // ADR-015: full / insights-only 模式下 profile facts 自动归档
-        if (!skipAutoArchive && this.#userProfile) {
+        const history = this.history;
+        if (!skipAutoArchive) {
             try {
-                const turnIndex = `turn-${Date.now()}`;
-                const facts = extractUserFacts(input, turnIndex);
-                // 注册到 pendingArchives，确保 close() 时等待后台归档完成，避免写入已关闭的存储
-                const archiveFactsPromise = this.#userProfile.archiveFacts(facts).then((entries) => {
-                    // 发射 memoryAdded 事件：仅对已确认且写入存储的条目（confirmed=true）
-                    for (const entry of entries) {
-                        if (entry.confirmed) {
-                            this.emit('memoryAdded', { id: entry.id, source: 'profile', name: entry.value });
-                        }
-                    }
-                }).catch((err) => {
-                    logger.warn({ err }, '用户画像实时归档失败');
+                // fire-and-forget 包装：registerPendingArchive 确保 close() 时等待后台归档完成
+                // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
+                const archiveFactsPromise = this.archiveCoordinator.archiveProfileFacts(input).then(() => { }, (err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    logger.warn({ err, stage: 'profile' }, '归档失败');
+                    this.emit('archiveFailed', { stage: 'profile', message: message.slice(0, 200) });
                 });
-                this.requireNonNull(this.history, 'history').registerPendingArchive(archiveFactsPromise);
+                history.registerPendingArchive(archiveFactsPromise);
             }
             catch (err) {
                 logger.warn({ err }, '用户画像归档初始化失败');
             }
         }
-        // 输入分类 → Insight 提取（委托给 InsightExtractor）
+        // 输入分类 → Insight 提取（委托 ArchiveCoordinator，与手动归档路径统一）
         // ADR-015: full / insights-only 模式下 insight 自动归档
-        if (!skipAutoArchive && this.insightExtractor) {
+        if (!skipAutoArchive) {
             try {
-                const shouldExtract = this.insightExtractor.classify(input);
-                if (shouldExtract === 'extract') {
-                    const p = this.insightExtractor.extract(input, assistantContent).then((memories) => {
-                        // 发射 memoryAdded + insightExtracted 事件：每条写入/更新的 insight 均通知宿主
-                        for (const memory of memories) {
-                            this.emit('memoryAdded', { id: memory.id, source: memory.source, name: memory.name });
-                            this.emit('insightExtracted', { source: memory.source, insight: memory.content });
-                        }
-                    }).catch((err) => {
-                        logger.warn({ err }, 'Insight 提取失败');
-                    });
-                    this.requireNonNull(this.history, 'history').registerPendingArchive(p);
-                }
+                // fire-and-forget 包装：classify 判断由 ArchiveCoordinator 内部完成
+                // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
+                const archiveInsightPromise = this.archiveCoordinator.archiveInsight(input, assistantContent).then(() => { }, (err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    logger.warn({ err, stage: 'insight' }, '归档失败');
+                    this.emit('archiveFailed', { stage: 'insight', message: message.slice(0, 200) });
+                });
+                history.registerPendingArchive(archiveInsightPromise);
             }
             catch (err) {
                 logger.warn({ err }, 'Insight 提取初始化失败');
@@ -560,7 +553,7 @@ export class Agent extends TypedEventEmitter {
                 const analyzePromise = this.autoConfigRefiner.analyze(input, assistantContent).catch((err) => {
                     logger.warn({ err }, 'AutoConfigRefiner 分析失败');
                 });
-                this.requireNonNull(this.history, 'history').registerPendingArchive(analyzePromise);
+                history.registerPendingArchive(analyzePromise);
             }
             catch (err) {
                 logger.warn({ err }, 'AutoConfigRefiner 初始化失败');
@@ -587,7 +580,7 @@ export class Agent extends TypedEventEmitter {
      */
     forkSession(targetSession) {
         this.assertInitialized('forkSession');
-        return this.requireNonNull(this._sessionManager, 'sessionManager').forkSession(targetSession);
+        return this._sessionManager.forkSession(targetSession);
     }
     /**
      * 切换到指定项目
@@ -598,12 +591,10 @@ export class Agent extends TypedEventEmitter {
     async switchProject(nameOrPath) {
         this.assertInitialized('switchProject', ['projectManager', 'provider']);
         // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换项目', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('切换项目');
         }
-        const pm = this.requireNonNull(this.projectManager, 'projectManager');
+        const pm = this.projectManager;
         const projects = pm.list;
         let target = projects.find((p) => p.name === nameOrPath || p.path === nameOrPath);
         if (!target) {
@@ -611,7 +602,7 @@ export class Agent extends TypedEventEmitter {
             target = projects.find((p) => p.name.toLowerCase() === nameOrPathLower || p.path.toLowerCase() === nameOrPathLower);
         }
         const projectPath = target ? target.path : nameOrPath;
-        const projectName = target ? target.name : basename(nameOrPath);
+        const projectName = target ? target.name : getBaseName(nameOrPath);
         const newPctx = await pm.initProject(projectPath, projectName, this.#config.configDir);
         // 记录源项目路径（用于事件），切换前 pctx 可能不存在（首次初始化）
         const fromProjectPath = this.pctx?.projectPath ?? null;
@@ -653,10 +644,10 @@ export class Agent extends TypedEventEmitter {
         this.insightExtractor = result.insightExtractor;
         this.configManager = result.configManager;
         this.memoryInspector = result.memoryInspector;
-        this.#memoryMutator = result.memoryMutator;
         this.autoConfigRefiner = result.autoConfigRefiner;
         this.workProjection = result.workProjection;
         this.sessionArchiver = result.sessionArchiver;
+        this.textPolisher = result.textPolisher;
         // 绑定冲突检测回调，InsightExtractor 检测到 contradicts 时 emit('conflictDetected')
         // 与 bindGetRecentHistory 同模式：解决 Agent 晚于 InsightExtractor 创建的时序循环依赖
         this.insightExtractor.bindOnConflict((info) => {
@@ -696,16 +687,16 @@ export class Agent extends TypedEventEmitter {
                 this.emit(event, data);
             }
         };
-        return new SessionManager(() => this.requireNonNull(this.history, 'history'), () => this.requireNonNull(this.loop, 'loop'), this.#config.sessionStore, () => this._chatBusy, forwardEvent);
+        return new SessionManager(
+        // 惰性 getter：SessionManager 内部调用时 Agent 已 init，用 ! 窄化
+        () => this.history, () => this.loop, this.#config.sessionStore, () => this.chatLockManager?.isBusy ?? false, forwardEvent);
     }
     // ─── Provider 管理 ────────────────────────────────────
     setProvider(provider) {
         // 对话进行中切换 Provider 会导致同一 processUserInput 循环内前后两次 LLM 调用命中不同 Provider
         // （模型上下文窗口假设不一致 → 可能导致上下文截断逻辑误判或 tool_call 格式不兼容）
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换 Provider', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('切换 Provider');
         }
         this.#provider = provider;
         if (this.loop) {
@@ -715,10 +706,8 @@ export class Agent extends TypedEventEmitter {
     }
     setBackgroundProvider(provider) {
         // 与 setProvider 一致，对话进行中禁止切换后台 Provider
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换后台 Provider', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('切换后台 Provider');
         }
         this.#backgroundProvider = provider;
         // 同步更新 AutoConfigRefiner 的后台 Provider
@@ -736,10 +725,8 @@ export class Agent extends TypedEventEmitter {
      * @param mode 目标模式
      */
     setArchiveMode(mode) {
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换归档模式', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('切换归档模式');
         }
         const prev = this.#config.archiveMode;
         if (prev === mode)
@@ -821,10 +808,8 @@ export class Agent extends TypedEventEmitter {
      */
     async reloadConfig(source) {
         this.assertInitialized('reloadConfig');
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重载配置', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('重载配置');
         }
         // guardrail 需重建 AgentLoop，不属于热重载范畴
         if (source === 'guardrail') {
@@ -862,10 +847,8 @@ export class Agent extends TypedEventEmitter {
      */
     async rebuildComponents() {
         // 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重建组件', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError('重建组件');
         }
         await this.rebuildComponentsWithCurrentCtx();
     }
@@ -896,19 +879,6 @@ export class Agent extends TypedEventEmitter {
             }
         }
     }
-    /**
-     * 非空断言守卫——对 null/undefined 值抛出清晰错误的运行时检查
-     *
-     * @param value 可能为 null/undefined 的值
-     * @param name 组件名称（用于错误消息）
-     * @throws MemoraError 如果 value 为 null/undefined
-     */
-    requireNonNull(value, name) {
-        if (value === null || value === undefined) {
-            throw configError('Agent 未初始化', `${name} 组件不可用`, ['请先调用 await agent.init()']);
-        }
-        return value;
-    }
     // ─── 记忆生命周期 ───────────────────────────────────────
     // ─── runMemoryDecay 已迁移至 MemoryDecayScheduler.runOnce ─────
     // ─── 关闭 ─────────────────────────────────────────────
@@ -916,9 +886,10 @@ export class Agent extends TypedEventEmitter {
      * 关闭 Agent，释放 SQLite 连接等资源
      */
     async close() {
-        // 递增 token，使任何进行中的 chat() generator 的 finally 块
-        // 检测到 token 变化后跳过资源清理（close 已接管清理职责）
-        this._chatLockToken++;
+        // 清理 chat 锁管理器（递增 token 使进行中的 chat() generator 的 finally 块
+        // 检测到 token 变化后跳过资源清理，close 已接管清理职责）
+        this.chatLockManager?.dispose();
+        this.chatLockManager = null;
         // 清理 MemoryDecayScheduler（含定时器和 storage 引用）
         if (this.memoryDecayScheduler) {
             this.memoryDecayScheduler.stop();
@@ -931,50 +902,55 @@ export class Agent extends TypedEventEmitter {
             clearSafeInterval(this.decayTimer);
             this.decayTimer = null;
         }
-        if (this.chatLockTimer) {
-            clearSafeTimeout(this.chatLockTimer);
-            this.chatLockTimer = null;
-        }
-        if (this.chatAbortController) {
-            this.chatAbortController.abort();
-            this.chatAbortController = null;
-        }
         // 清理 PersonaManager 的角色切换防抖锁计时器，防止关闭后回调触发
         if (this.personaManager) {
             this.personaManager.close();
         }
-        this.removeAllListeners();
+        // 先等待后台归档完成，再移除事件监听器
+        // 顺序敏感：若先 removeAllListeners，fire-and-forget 的归档 Promise 在 await 期间
+        // reject 时 emit 会变成 no-op（listeners 已清空），archiveFailed 事件丢失
         if (this.history) {
             await this.history.awaitPendingArchives(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
         }
+        // pending archives 完成后再移除监听器，确保归档失败的 emit 能送达
+        this.removeAllListeners();
         if (this.projectManager) {
             await this.projectManager.shutdown();
         }
         this._initialized = false;
+        this.nullifyAllComponents();
+        // 清理次要状态字段，防止 re-init 后残留上一会话状态
+        this.activeSkill = null;
+        this._lastInteractionAt = null;
+    }
+    /**
+     * 统一 null 化所有组件字段（新增 Manager 时在此处追加一行）
+     *
+     * 仅处理"纯 null 化"字段，带副作用的清理（dispose/stop/close/shutdown）
+     * 仍由 close() 显式调用，顺序敏感不可合并。
+     */
+    nullifyAllComponents() {
+        // Provider
         this.#backgroundProvider = null;
-        this._chatBusy = false;
+        // 核心组件
         this.history = null;
         this.loop = null;
-        this._sessionManager = null;
-        this.projectManager = null;
+        this.toolExec = null;
+        // 专职 Manager
+        this.personaManager = null;
+        this.#userProfile = null;
+        this.skillManager = null;
         this.insightExtractor = null;
         this.configManager = null;
         this.memoryInspector = null;
-        this.#memoryMutator = null;
+        this.workProjection = null;
         this.autoConfigRefiner = null;
         this.sessionArchiver = null;
+        this.textPolisher = null;
+        this._sessionManager = null;
+        // 项目管理
+        this.projectManager = null;
         this.pctx = null;
-        // 补全剩余 manager 字段 null 化，与上述字段处理方式一致
-        // （原实现仅 null 化部分 manager，toolExec/personaManager/#userProfile/skillManager/workProjection 遗漏）
-        this.toolExec = null;
-        this.personaManager = null;
-        this.#userProfile = null;
-        this.skillManager = null;
-        this.workProjection = null;
-        // 清理次要状态字段，防止 re-init 后残留上一会话状态
-        this.activeSkill = null;
-        this._lastInteractionAt = null;
-        // 衰减指标已迁移至 MemoryDecayScheduler，close 时通过 stop() 销毁实例
     }
     // ─── 只读访问器 ───────────────────────────────────────
     get initialized() {
@@ -1004,7 +980,7 @@ export class Agent extends TypedEventEmitter {
         return this.#provider;
     }
     get isBusy() {
-        return this._chatBusy;
+        return this.chatLockManager?.isBusy ?? false;
     }
     get lastInteractionAt() {
         return this._lastInteractionAt;
@@ -1055,7 +1031,7 @@ export class Agent extends TypedEventEmitter {
     // - 访问器（getter）：返回 Manager | null，供宿主项目链式调用和优雅降级
     //   （如 `agent.persona?.activeName`、`if (!agent.memory) return []`）
     // - 门面方法（snapshot/inspect/stats/searchMemories 等）：通过
-    //   assertInitialized + requireNonNull 抛 MemoraError，提供明确错误信息
+    //   assertInitialized 抛 MemoraError，提供明确错误信息
     // 宿主项目使用访问器时需自行判空，或使用门面方法获得自动错误处理。
     /**
      * 角色管理器（可能为 null）
@@ -1107,16 +1083,91 @@ export class Agent extends TypedEventEmitter {
     get memory() {
         return this.memoryInspector;
     }
+    // ─── LLM 记忆治理委托方法（G1：暴露能力但不暴露 manager 实例） ──
+    // 这三个方法是 sprite 层接入 L1~L3 治理能力的唯一入口。
+    // 委托内部 manager（memoryInspector / memoryDecayScheduler / memoryAdvisor），
+    // 不返回 manager 实例本身，保持封装（sprite 层不感知 manager 内部结构）。
+    // manager 未初始化时返回 skippedReason 报告，与 manager 内部"backgroundProvider
+    // 未注入时静默跳过"语义一致（向后兼容）。
     /**
-     * 记忆写入器（可能为 null）—— upsert / delete / restore / purge / purgeExpired /
-     * addRelation / removeRelation
+     * L1 语义去重（委托 MemoryInspector.deduplicateMemories）
      *
-     * P1-2 拆分：从 MemoryInspector 拆出写操作代理，与 MemoryInspector 严格分工。
-     * 返回 null 时表示 Agent 未初始化或存储层未就绪。
-     * 宿主项目常用模式：`const m = agent.memoryMutator; if (!m) return; m.upsert(...)`
+     * 扫描名称相似的记忆对，调用 LLM 判断语义等价，降级低分记忆（score→0.1，不物理删除）。
+     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
+     *
+     * @param signal 可选的 AbortSignal（取消进行中的 LLM 判断）
+     * @returns 去重报告（扫描数 / 降级 ID 列表 / 跳过原因）
      */
-    get memoryMutator() {
-        return this.#memoryMutator;
+    async deduplicateMemories(signal) {
+        const inspector = this.memoryInspector;
+        if (!inspector) {
+            return {
+                scannedCount: 0,
+                pairCount: 0,
+                deduplicatedCount: 0,
+                demotedIds: [],
+                skippedReason: 'Agent 未初始化',
+            };
+        }
+        return inspector.deduplicateMemories(signal);
+    }
+    /**
+     * L2 时效性评估（委托 MemoryDecayScheduler.evaluateTimeliness）
+     *
+     * 扫描低分记忆（score<0.3），调用 LLM 判断是否过时，降级过时记忆（score→0.05）。
+     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
+     *
+     * 使用场景：
+     *   - G2 自动触发：onDecayCompleted 钩子内 fire-and-forget 调用
+     *   - 手动触发：宿主 UI 健康度面板"时效性评估"按钮
+     *
+     * @param signal 可选的 AbortSignal
+     * @returns 评估报告（扫描数 / 过时数 / 降级 ID 列表 / 跳过原因）
+     */
+    async evaluateTimeliness(signal) {
+        const scheduler = this.memoryDecayScheduler;
+        if (!scheduler) {
+            return {
+                scannedCount: 0,
+                outdatedCount: 0,
+                demotedIds: [],
+                skippedReason: 'Agent 未初始化',
+            };
+        }
+        return scheduler.evaluateTimeliness(signal);
+    }
+    /**
+     * 手动触发一次 L0 记忆衰减（委托 MemoryDecayScheduler.runOnce）
+     *
+     * 执行纯 score 递减（无 LLM 调用），衰减完成后触发 decayCompleted 事件。
+     * 供宿主 UI 手动触发（如仪表盘"立即衰减"按钮），与定时器自动触发路径一致。
+     */
+    runMemoryDecayOnce() {
+        this.memoryDecayScheduler?.runOnce();
+    }
+    /**
+     * L3 冲突检测（委托 MemoryAdvisor.detectConflicts）
+     *
+     * 同 source 内配对，调用 LLM 判断语义冲突，仅检测不修复（需用户决策）。
+     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
+     *
+     * @param signal 可选的 AbortSignal
+     * @returns 冲突报告（扫描数 / 冲突数 / 冲突详情列表 / 跳过原因）
+     */
+    async detectConflicts(signal) {
+        // MemoryAdvisor 实例由 MemoryInspector 持有（组合根装配时注入），
+        // 通过 inspector.detectConflicts 转发，避免 agent 直接持有 advisor 引用
+        const inspector = this.memoryInspector;
+        if (!inspector) {
+            return {
+                scannedCount: 0,
+                pairCount: 0,
+                conflictCount: 0,
+                conflicts: [],
+                skippedReason: 'Agent 未初始化',
+            };
+        }
+        return inspector.detectConflicts(signal);
     }
     /**
      * 项目管理器（可能为 null）
@@ -1166,5 +1217,9 @@ export class Agent extends TypedEventEmitter {
     get sessionManager() {
         return this._sessionManager;
     }
+    /** 文本润色管理器（宿主可通过此 getter 调用 polish 方法） */
+    get polish() {
+        return this.textPolisher;
+    }
 }
 //# sourceMappingURL=agent.js.map