@zooique/memora 1.0.1 → 2.0.3

package/dist/agent/agent.js

@@ -1,7 +1,7 @@
 /**
  * Agent 门面类 — Memora 宿主项目接入入口
  *
- * 设计文档（ADR-010 · Agent 门面类）要求宿主项目通过 `import { Agent } from '@memora/core'`
+ * 设计文档（ADR-010 · Agent 门面类）要求宿主项目通过 `import { Agent } from '@zooique/memora'`
  * 一行代码接入。本类负责组件组装和核心对话编排，
  * 领域专属操作委托给专职 Manager（PersonaManager / ToolExecutor / SkillManager / ConfigManager / InsightExtractor / MemoryInspector）。
  *
@@ -22,35 +22,31 @@
  *   - 记忆查看 → 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 { recall, boostScores } from '../memory/recall.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, isAbortError, toError } from '../utils/errors.js';
 import { SessionManager } from '../agent/managers/sessionManager.js';
+import { ChatLockManager } from '../agent/managers/chatLockManager.js';
 import { MemoryDecayScheduler } from '../agent/managers/memoryDecayScheduler.js';
+import { MemoryGovernance } from '../agent/managers/memoryGovernance.js';
 import { ArchiveCoordinator } from '../agent/managers/archiveCoordinator.js';
-import { TypedEventEmitter } from '../utils/eventEmitter.js';
+import { TypedEventEmitter, AGENT_EVENTS, AGENT_EVENT_SET } 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 个事件）
-const AGENT_EVENT_NAMES = new Set([
-    'memoryAdded', 'personaSwitched', 'decayCompleted',
-    'memoryRecalled', 'sessionForked', 'insightExtracted',
-    'conflictDetected', 'projectSwitched', 'skillMatched',
-]);
+// AGENT_EVENTS / AGENT_EVENT_SET 已迁移至 utils/eventEmitter.ts（与 AgentEventMap 同处，单一真理源）
 // ─── Agent 门面类 ───────────────────────────────────────
 /**
  * Memora Agent 门面类
  *
  * **设计哲学**：单 Agent，单配置，单记忆。每个 Agent 实例拥有独立的
  * 对话管线（AgentLoop）、独立的消息历史（MessageHistory）和独立的
- * 运行时状态（activeSkill、chatBusy）。
+ * 运行时状态（chatBusy）。activeSkill 已移除——技能匹配改为当轮实时注入，无需跨轮状态缓存。
  *
  * **多实例**：宿主可通过 new Agent({ dataDir: './agent2' }) 创建
  * 独立实例。只要 dataDir 不同，它们拥有完全隔离的记忆库和会话。
@@ -95,47 +91,56 @@ export class Agent extends TypedEventEmitter {
     insightExtractor = null;
     configManager = null;
     memoryInspector = null;
-    /** 记忆写入器（P1-2 拆分，与 MemoryInspector 严格分工：写操作代理；ES 私有字段避免与 getter 重名递归） */
-    #memoryMutator = null;
+    /**
+     * 语义去重管理器（L1 LLM 记忆治理）
+     *
+     * SPLIT-3 闭环（2026-07-21）：从 MemoryInspector 拆分出 deduplicateMemories 职责，
+     * 让 MemoryInspector 回归纯存储读写。Agent.deduplicateMemories() 委托本对象。
+     */
+    dedupManager = null;
+    /**
+     * 记忆顾问（L3 冲突检测 / sourceHealth / suggest）
+     *
+     * v2 PROXY-1 闭环：Agent.detectConflicts 直接调用 advisor，
+     * 不再经 MemoryInspector 转发，消除 3 层无意义代理。
+     * sourceHealth/suggest 仍由 inspector 转发以保持 agent.memory 统一入口语义。
+     */
+    memoryAdvisor = null;
+    /** 记忆治理统一门面（L0/L1/L2/L3 + 诊断） */
+    _governance = null;
     workProjection = null;
     /** AutoConfigRefiner（模式 3：Agent 智能总结） */
     autoConfigRefiner = null;
     /** SessionArchiver（会话内容归档器，content 类记忆） */
     sessionArchiver = null;
+    /** TextPolishManager（文本润色管理器，LLM 语法修正 + 表达优化） */
+    textPolisher = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     _sessionManager = null;
-    /** 当前激活的技能名（上一轮匹配，本轮注入） */
-    activeSkill = null;
+    // activeSkill 字段已移除：matchAndInjectSkill 改为当轮实时匹配注入，无需跨轮状态缓存
     _initialized = false;
     // 项目上下文（AgentContext 与 ProjectContext 等价，直接使用后者避免重复字段）
     pctx = null;
-    /** chat() 并发锁 */
-    _chatBusy = false;
     /**
-     * chat() 锁持有者 token（race condition 防护）
-     *
-     * 设计目的：
-     *   原锁是简单布尔值 `_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` 后才清理
-     *   - 不匹配时跳过清理，避免误清新调用者的资源
+     * chat() 并发锁管理器（init 时创建，close 时销毁）
      *
-     * 选择 number 而非 Symbol：递增计数器可序列化、零依赖、足够唯一（同一 Agent 实例内）
+     * 职责：chat() 并发锁 + token 校验（race condition 防护）+ 超时保护 + 外部 signal 合并。
+     * 详见 ChatLockManager 类注释。
      */
-    _chatLockToken = 0;
-    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
-    chatLockTimer = null;
-    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
-    chatAbortController = null;
-    /** 记忆衰减定时器（已迁移至 MemoryDecayScheduler，此字段保留用于 close 时引用判断） */
-    decayTimer = null;
+    chatLockManager = null;
     /** 最近一次 chat() 调用的时间戳 */
     _lastInteractionAt = null;
+    /**
+     * 对话进行中暂存的配置重载请求集合（chatLock 释放后补执行）
+     *
+     * 场景：用户在对话中通过 create_persona / create_skill 工具创建配置，
+     * reloadConfig 因 chatLock 冲突失败时，将 source 暂存于此。
+     * chat() 的 finally 块释放锁后遍历此集合逐个补执行 reloadConfig，
+     * 兑现"对话结束后自动加载"的承诺（见 tools.ts createConfigHandler 提示文案）。
+     *
+     * 用 Set 而非数组：同一 source 多次请求只需补执行一次（去重）。
+     */
+    pendingConfigReload = new Set();
     // ─── 衰减职责已拆分至 MemoryDecayScheduler ──────────
     // metricDecayRunCount / metricTotalDecayedCount / metricLastDecayAt 字段
     // 位于 MemoryDecayScheduler 内部，Agent 通过 memoryDecayScheduler.getMetrics() 读取
@@ -147,7 +152,7 @@ export class Agent extends TypedEventEmitter {
         super();
         this.#config = {
             projectPath: opts.projectPath,
-            dataDir: opts.dataDir ?? '~/.memora',
+            dataDir: opts.dataDir,
             registryDir: opts.registryDir,
             maxContextTokens: opts.maxContextTokens ?? AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS,
             personaName: opts.persona,
@@ -169,27 +174,42 @@ export class Agent extends TypedEventEmitter {
         };
         this.#provider = opts.provider;
         this.#backgroundProvider = opts.backgroundProvider ?? null;
-        // 如需自定义日志，请在创建 Agent 前调用 `import { setLogger } from '@memora/core'` 全局设置
+        // 如需自定义日志，请在创建 Agent 前调用 `import { setLogger } from '@zooique/memora'` 全局设置
     }
     // ─── 生命周期 ─────────────────────────────────────────
     /**
      * 初始化 Agent：加载索引、组装内部组件
      */
     async init(projectPathOverride) {
-        if (this._initialized) {
-            // 修复 #3：close() 失败不应阻塞 init() 重建
-            // 原 close() 异常（如 awaitPendingArchives 超时）会传播到 init() 调用方，
-            // 导致 Agent 处于不可用状态。此处捕获后继续重建。
-            try {
-                await this.close();
-            }
-            catch (err) {
-                logger.warn({ err }, 'init() 中 close() 旧实例失败，继续重建');
-            }
-        }
+        await this.disposePreviousInstance();
         if (projectPathOverride) {
             this.#config.projectPath = projectPathOverride;
         }
+        const pctx = await this.initializeProject();
+        await this.assembleComponents(pctx);
+        this.pctx = pctx;
+        this.validateCoreComponents();
+        this.createPostInitComponents(pctx);
+        this._initialized = true;
+        return pctx;
+    }
+    /**
+     * 关闭旧实例（如果已初始化），失败不阻塞重建
+     */
+    async disposePreviousInstance() {
+        if (!this._initialized)
+            return;
+        try {
+            await this.close();
+        }
+        catch (err) {
+            logger.warn({ err }, 'init() 中 close() 旧实例失败，继续重建');
+        }
+    }
+    /**
+     * 创建 ProjectManager 并初始化项目上下文
+     */
+    async initializeProject() {
         this.projectManager = new ProjectManager({
             dataDir: this.#config.dataDir,
             storage: this.#config.storage,
@@ -197,9 +217,12 @@ export class Agent extends TypedEventEmitter {
             // SecurityGuard 由 Agent 层创建，解除 memory→security 反向依赖
             createSecurityGuard: (projectPath, memoraDir, configDir, agentDataDir) => new SecurityGuard(projectPath, memoraDir, this.#config.allowedPaths, this.#config.confirmWrites, this.#config.permission, configDir ?? this.#config.configDir, agentDataDir ?? this.#config.dataDir),
         });
-        const pctx = await this.projectManager.initProject(this.#config.projectPath, undefined, this.#config.configDir);
-        await this.assembleComponents(pctx);
-        this.pctx = pctx;
+        return this.projectManager.initProject(this.#config.projectPath, undefined, this.#config.configDir);
+    }
+    /**
+     * 校验核心组件（loop / history）非空
+     */
+    validateCoreComponents() {
         if (!this.loop || !this.history) {
             throw configError('Agent 初始化失败', '组件组装后 loop 或 history 为空（可能 assembleComponents 抛异常被静默吞掉）', [
                 '检查 assembleComponents() 是否有未捕获的异常',
@@ -207,76 +230,50 @@ export class Agent extends TypedEventEmitter {
                 '确认 API Key 已配置（环境变量或配置文件）',
             ]);
         }
-        this._initialized = true;
+    }
+    /**
+     * 创建 init() 后期组件（初始化完成后才需要的组件）
+     */
+    createPostInitComponents(pctx) {
+        // chat() 并发锁管理器（生命周期与 Agent 实例一致）
+        this.chatLockManager = new ChatLockManager();
         // 归档操作委托给 ArchiveCoordinator
-        // 使用 getter 回调注入依赖，close 时 null 化字段后 getter 自然返回 null
         this.archiveCoordinator = new ArchiveCoordinator({
             getUserProfile: () => this.#userProfile,
             getInsightExtractor: () => this.insightExtractor,
             getSessionArchiver: () => this.sessionArchiver,
+            getArchiveMode: () => this.#config.archiveMode,
             emit: (event, payload) => this.emit(event, payload),
         });
         // 记忆衰减职责委托给 MemoryDecayScheduler
         this.memoryDecayScheduler = new MemoryDecayScheduler({
             tracer: this.#config.tracer,
-            onDecayCompleted: (payload) => this.emit('decayCompleted', payload),
+            onDecayCompleted: (payload) => {
+                this.emit(AGENT_EVENTS.decayCompleted, payload);
+                // MIND2-D4：从 agent.evaluateTimeliness() 迁移到 governance.evaluateTimeliness()
+                void this._governance?.evaluateTimeliness().catch((err) => {
+                    logger.warn({ err }, 'L2 时效性评估自动触发失败（已降级，不影响衰减循环）');
+                });
+            },
+            backgroundProvider: this.#backgroundProvider,
+            index: pctx.index,
         });
         this.memoryDecayScheduler.start(pctx.index, AGENT_CONSTANTS.DECAY_INTERVAL_MS);
-        // 保留 decayTimer 引用用于 close 时序兼容（实际定时器由 MemoryDecayScheduler 管理）
-        this.decayTimer = null;
-        return pctx;
+        // 记忆治理统一门面（L0/L1/L2/L3 + 诊断）
+        this._governance = new MemoryGovernance(this.dedupManager, this.memoryDecayScheduler, this.memoryAdvisor);
     }
     /**
      * 流式对话（核心 API）
      */
     async *chat(input, signal) {
         this.assertInitialized('chat');
-        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() 调用',
-            ]);
-        }
-        this._chatBusy = true;
-        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
-        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
-        const myToken = ++this._chatLockToken;
-        // 内部 AbortController，超时时中断 generator 而非仅释放锁
-        const internalAbort = new AbortController();
-        this.chatAbortController = internalAbort;
-        // 合并外部 signal：外部 abort 时也触发内部
-        const onExternalAbort = () => internalAbort.abort();
-        signal?.addEventListener('abort', onExternalAbort, { once: true });
-        // 修复 #4：addEventListener 对已 aborted 的 signal 不触发回调
-        // 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程
-        if (signal?.aborted) {
-            internalAbort.abort();
-        }
-        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);
+        this.validateChatInput(input);
+        const lockCtx = this.acquireChatLock(signal);
+        const { myToken, combinedSignal, cleanupExternalSignal } = lockCtx;
         try {
             this._lastInteractionAt = new Date();
-            // 清理上一轮注入的临时 system 消息（recentConversation/skill/recall/truncation）
-            // 防止多轮累积：每轮 chat() 开始前，只保留 messages[0] 和非 system 消息
-            this.requireNonNull(this.loop, 'loop').cleanTemporarySystemMessages();
-            // 基元驱动召回（双通道：语义 + 关键词）
-            yield { type: 'thinking', phase: 'recalling' };
-            const recalledMemories = await this.recallAndInject(input);
+            // 上下文准备：角色匹配 → 记忆召回 → 技能注入 → 历史追加
+            const recalledMemories = yield* this.prepareChatContext(input, combinedSignal);
             if (combinedSignal.aborted) {
                 yield {
                     type: 'aborted',
@@ -284,78 +281,128 @@ export class Agent extends TypedEventEmitter {
                 };
                 return;
             }
-            // 注入上一轮匹配的技能 prompt
-            yield { type: 'thinking', phase: 'processing' };
-            this.injectActiveSkill();
-            await this.requireNonNull(this.history, '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)) {
-                    yield chunk;
-                    if (chunk.type === 'text') {
-                        assistantContent += chunk.content;
-                    }
-                    else if (chunk.type === 'aborted') {
-                        wasAborted = true;
-                    }
-                }
-            }
-            catch (err) {
-                // aborted 已由 loop.ts 内部 yield chunk 处理，此处只捕获真正的异常
-                // （如 LLM 超时、连接断开、AbortError 未被 loop 拦截等）
-                // 转为 error chunk 通知宿主，避免裸 throw 导致 UI 卡死
-                if (err instanceof DOMException && err.name === 'AbortError') {
-                    // 必须 yield aborted chunk 让宿主能展示中断标记
-                    // （仅设置 wasAborted 会导致 chatHandlers catch 不触发，渲染层收不到 ABORTED）
-                    yield { type: 'aborted', reason: 'User cancelled the conversation' };
-                    return;
+            // LLM 流式调用 → 助手消息写历史 → 后处理
+            yield* this.executeChatLoop(input, recalledMemories, combinedSignal);
+        }
+        finally {
+            // 仅当本调用仍是当前锁持有者时才清理资源（token 校验）
+            this.chatLockManager?.release(myToken);
+            cleanupExternalSignal();
+            // 补执行对话期间暂存的配置重载请求
+            await this.flushPendingConfigReload();
+        }
+    }
+    /**
+     * 校验 chat 输入
+     */
+    validateChatInput(input) {
+        if (input.length > AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH) {
+            throw configError('输入过长', `输入超过最大长度限制（${AGENT_CONSTANTS.CHAT_INPUT_MAX_LENGTH / 1024}KB）`, ['缩短输入内容', '分多次对话发送']);
+        }
+    }
+    /**
+     * 获取对话锁 — 返回锁上下文
+     */
+    acquireChatLock(signal) {
+        const chatLock = this.chatLockManager;
+        if (!chatLock)
+            throw configError('ChatLockManager', 'ChatLockManager 未初始化', []);
+        if (chatLock.isBusy) {
+            throw chatBusyError('发起新对话');
+        }
+        const { token: myToken, internalAbort } = chatLock.acquire(AGENT_CONSTANTS.CHAT_LOCK_TIMEOUT_MS);
+        const cleanupExternalSignal = chatLock.attachExternalSignal(signal, internalAbort);
+        return { myToken, internalAbort, cleanupExternalSignal, combinedSignal: internalAbort.signal };
+    }
+    /**
+     * 准备对话上下文：角色匹配 → 记忆召回 → 技能注入 → 用户消息写历史
+     * @returns 召回的记忆列表（供 loop.processUserInput 注入为 system 消息）
+     */
+    async *prepareChatContext(input, combinedSignal) {
+        const loop = this.requireLoop;
+        loop.cleanTemporarySystemMessages();
+        // 角色自动匹配（回答前执行）
+        await this.tryAutoMatchPersona(input);
+        // 基元驱动召回（双通道：语义 + 关键词）
+        yield { type: 'thinking', phase: 'recalling' };
+        const recalledMemories = await this.recallAndInject(input);
+        if (combinedSignal.aborted)
+            return recalledMemories;
+        // 技能关键词/正则匹配（当轮立即注入生效）
+        yield { type: 'thinking', phase: 'processing' };
+        this.matchAndInjectSkill(input);
+        const history = this.requireHistory;
+        await history.appendUser(input);
+        return recalledMemories;
+    }
+    /**
+     * 执行 LLM 流式循环 → 追加助手消息 → 触发后处理
+     */
+    async *executeChatLoop(input, recalledMemories, combinedSignal) {
+        const loop = this.requireLoop;
+        const history = this.requireHistory;
+        let assistantContent = '';
+        let wasAborted = false;
+        try {
+            for await (const chunk of loop.processUserInput(input, recalledMemories, combinedSignal)) {
+                yield chunk;
+                if (chunk.type === 'text') {
+                    assistantContent += chunk.content;
                 }
-                else {
-                    yield { type: 'error', message: err instanceof Error ? err.message : String(err) };
-                    return;
+                else if (chunk.type === 'aborted') {
+                    wasAborted = true;
                 }
             }
-            if (wasAborted) {
-                // 流式中断时仍保留已生成的部分文本到历史，避免下一轮上下文丢失
-                // 追加 interrupted 标记让下一轮 LLM 和历史归档能识别这是中断响应（非完整回复）
-                // 与下方正常路径一致采用 best-effort 写入（失败不影响中断流程）
-                if (assistantContent.trim()) {
-                    const interruptedMark = this.#config.messages?.interrupted ?? '\n\n[已中断]';
-                    try {
-                        await this.requireNonNull(this.history, 'history').appendAssistant(assistantContent + interruptedMark);
-                    }
-                    catch (err) {
-                        logger.warn({ err }, '中断消息历史写入失败');
-                    }
-                }
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                yield { type: 'aborted', reason: 'User cancelled the conversation' };
                 return;
             }
-            // 追加助手消息到历史（best-effort：失败不影响用户已收到的回答）
-            try {
-                await this.requireNonNull(this.history, 'history').appendAssistant(assistantContent);
-            }
-            catch (err) {
-                logger.warn({ err }, '助手消息历史写入失败');
+            else {
+                yield { type: 'error', message: err instanceof Error ? err.message : String(err) };
+                return;
             }
-            // 后处理阶段
-            yield { type: 'thinking', phase: 'archiving' };
-            await this.postProcess(input, assistantContent);
         }
-        finally {
-            // 仅当本调用仍是当前锁持有者时才清理资源
-            // 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态
-            if (this._chatLockToken === myToken) {
-                this._chatBusy = false;
-                this.chatAbortController = null;
-                if (this.chatLockTimer) {
-                    clearSafeTimeout(this.chatLockTimer);
-                    this.chatLockTimer = null;
+        if (wasAborted) {
+            if (assistantContent.trim()) {
+                const interruptedMark = this.#config.messages?.interrupted ?? '\n\n[已中断]';
+                try {
+                    await history.appendAssistant(assistantContent + interruptedMark);
                 }
+                catch (err) {
+                    logger.warn({ err }, '中断消息历史写入失败');
+                }
+            }
+            return;
+        }
+        // 追加助手消息到历史（best-effort）
+        try {
+            await history.appendAssistant(assistantContent);
+        }
+        catch (err) {
+            logger.warn({ err }, '助手消息历史写入失败');
+        }
+        // 后处理阶段
+        yield { type: 'thinking', phase: 'archiving' };
+        await this.postProcess(input, assistantContent);
+    }
+    /**
+     * 补执行对话期间暂存的配置重载请求
+     */
+    async flushPendingConfigReload() {
+        if (this.pendingConfigReload.size === 0)
+            return;
+        const pending = Array.from(this.pendingConfigReload);
+        this.pendingConfigReload.clear();
+        for (const src of pending) {
+            try {
+                await this.reloadConfig(src);
+                this.emit(AGENT_EVENTS.configReloaded, { source: src });
+            }
+            catch (err) {
+                logger.warn({ err, source: src }, '补执行配置重载失败');
             }
-            signal?.removeEventListener('abort', onExternalAbort);
         }
     }
     /**
@@ -369,7 +416,7 @@ export class Agent extends TypedEventEmitter {
      *
      * 本方法让宿主在确认 generator 挂起后强制释放锁，让用户能立即发起新对话。
      *
-     * 安全机制：
+     * 安全机制（委托至 ChatLockManager.forceRelease）：
      *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
      *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
      *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
@@ -384,22 +431,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,17 +444,41 @@ 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.requirePctx.index, input, {
+                limit: AGENT_CONSTANTS.DEFAULT_RECALL_LIMIT,
+                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 });
+            this.emit(AGENT_EVENTS.memoryRecalled, { count: recalledMemories.length, query: input });
+            // FIX-P1-2：boost 持久化拆分为 fire-and-forget，不阻塞 chat 读路径
+            // boost 是软指标（每次 +0.05，上限 1.0），写入失败仅 log 不影响 chat 流程
+            const ids = recalledMemories.map((m) => m.id);
+            void boostScores(this.requirePctx.index, ids).catch((err) => {
+                logger.warn({ err }, 'boost 持久化失败（不影响 chat 流程）');
+                this.emit(AGENT_EVENTS.boostPersistFailed, { memoryId: ids.join(','), message: toError(err).message });
+            });
         }
         // Layer 5: 最近对话注入
-        const loop = this.requireNonNull(this.loop, 'loop');
-        const recentHistory = loop.getRecentHistory(3);
+        const loop = this.requireLoop;
+        const recentHistory = loop.getRecentHistory(AGENT_CONSTANTS.DEFAULT_RECENT_HISTORY_ROUNDS);
         if (recentHistory.length > 0) {
             const msgs = this.#config.messages;
             const label = msgs?.recentConversationLabel ?? '[Recent conversation]';
@@ -438,16 +494,34 @@ export class Agent extends TypedEventEmitter {
         return recalledMemories;
     }
     /**
-     * 注入上一轮匹配的技能 prompt
+     * 匹配技能并立即注入本轮对话（当轮生效，不延迟到下一轮）
+     *
+     * 与 persona 的 tryAutoMatchPersona 同模式：匹配 → 注入 → 本轮 LLM 即生效。
+     * 原设计为 injectActiveSkill（注入上一轮匹配结果），导致用户说"写代码"的第一轮
+     * 得不到技能增强，需再发一条消息才生效。已改为实时匹配注入。
+     *
+     * 匹配策略：regex trigger 优先（score=1.0），其次关键词匹配（阈值 0.3）。
+     * 清理机制：cleanTemporarySystemMessages() 每轮开头清除临时 system 消息，
+     * 技能 prompt 自然不会累积到下一轮。
+     *
+     * @param input 用户输入文本
      */
-    injectActiveSkill() {
-        if (this.activeSkill && this.skillManager && this.loop) {
-            const skillPrompt = this.skillManager.buildSystemPrompt(this.activeSkill);
-            if (skillPrompt) {
-                this.loop.injectSystemMessage(skillPrompt);
-                logger.debug({ skill: this.activeSkill }, '技能 prompt 已注入');
+    matchAndInjectSkill(input) {
+        if (!this.skillManager || !this.loop)
+            return;
+        try {
+            const match = this.skillManager.match(input);
+            if (match) {
+                const skillPrompt = this.skillManager.buildSystemPrompt(match.skill.name);
+                if (skillPrompt) {
+                    this.loop.injectSystemMessage(skillPrompt);
+                    logger.debug({ skill: match.skill.name, score: match.score }, '技能 prompt 已注入（当轮生效）');
+                }
+                this.emit(AGENT_EVENTS.skillMatched, { skill: match.skill.name, score: match.score });
             }
-            this.activeSkill = null;
+        }
+        catch (err) {
+            logger.warn({ err }, '技能匹配失败');
         }
     }
     /**
@@ -464,94 +538,59 @@ export class Agent extends TypedEventEmitter {
      *   （会话归档实现后，`insights-only` 将跳过对话原始内容自动归档）
      */
     async postProcess(input, assistantContent) {
-        // 角色自动匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
-        if (this.personaManager) {
-            try {
-                const matchedPersona = this.personaManager.autoMatch(input);
-                if (matchedPersona) {
-                    const prevName = this.personaManager.activeName;
-                    this.personaManager.switchPersona(matchedPersona);
-                    this.emit('personaSwitched', { from: prevName, to: matchedPersona });
-                    if (this.loop) {
-                        const profilePrompt = this.userProfile?.buildSystemPrompt() ?? '';
-                        const personaPrompt = this.personaManager.buildSystemPrompt();
-                        const newPrefix = [personaPrompt, profilePrompt].filter(Boolean).join('\n\n') +
-                            ([personaPrompt, profilePrompt].some(Boolean) ? '\n\n---\n\n' : '');
-                        this.loop.refreshPersonaPrefix(newPrefix);
-                    }
-                    logger.info({ persona: matchedPersona }, '角色自动切换');
-                }
-            }
-            catch (err) {
-                logger.warn({ err }, '角色自动匹配失败');
-            }
+        // 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.doPostProcess(input, assistantContent);
         }
-        // 技能关键词匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
-        if (this.skillManager) {
-            try {
-                const match = this.skillManager.match(input);
-                if (match) {
-                    this.activeSkill = match.skill.name;
-                    // 发射 skillMatched 事件：宿主 UI 可据此展示当前激活技能
-                    this.emit('skillMatched', { skill: match.skill.name, score: match.score });
-                    logger.debug({ skill: match.skill.name, score: match.score }, '技能匹配，下一轮注入');
-                }
-            }
-            catch (err) {
-                logger.warn({ err }, '技能匹配失败');
-            }
+        finally {
+            span.end();
         }
-        // ADR-015: manual 模式跳过所有自动归档（profile + insight），
-        // 需用户手动调用 archiveProfileFacts/archiveInsight 触发。
+    }
+    /**
+     * postProcess 内部实现（为 span 埋点提供 try/finally 包裹边界）
+     *
+     * 原 postProcess 逻辑完整保留于此，由外层 postProcess 负责 span 生命周期管理。
+     */
+    async doPostProcess(input, assistantContent) {
+        // 技能匹配已迁移到 chat() 开头的 matchAndInjectSkill()（当轮实时生效），
+        // 与 persona 的 tryAutoMatchPersona 同模式，消除"第一轮无技能"的一轮延迟问题。
+        // ADR-015 + FIX-P1-4: archiveMode 三态控制集中到 ArchiveCoordinator
+        // 此处统一传 { autoTriggered: true }，由 ArchiveCoordinator 内部按 archiveMode 判断是否跳过：
+        //   - manual 模式 → 跳过 profile/insight 自动归档（用户需手动调用）
+        //   - full / insights-only 模式 → 执行
         // 角色匹配/技能匹配/AutoConfigRefiner 属"配置学习"行为，非归档，每轮都执行。
-        const skipAutoArchive = this.#config.archiveMode === 'manual';
-        if (skipAutoArchive) {
-            logger.debug({ mode: 'manual' }, '归档模式为 manual，跳过自动归档');
+        const history = this.requireHistory;
+        // 用户画像实时归档（委托 ArchiveCoordinator，与手动归档路径统一，消除 DRY 违反）
+        try {
+            // fire-and-forget 包装：registerPendingArchive 确保 close() 时等待后台归档完成
+            // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
+            const archiveFactsPromise = this.requireArchiveCoordinator.archiveProfileFacts(input, { autoTriggered: true }).then(() => { }, (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn({ err, stage: 'profile' }, '归档失败');
+                this.emit(AGENT_EVENTS.archiveFailed, { stage: 'profile', message: message.slice(0, 200) });
+            });
+            history.registerPendingArchive(archiveFactsPromise);
         }
-        // 用户画像实时归档（语义解析在 agent/ 层，存储在 memory/ 层）
-        // ADR-015: full / insights-only 模式下 profile facts 自动归档
-        if (!skipAutoArchive && this.#userProfile) {
-            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 }, '用户画像实时归档失败');
-                });
-                this.requireNonNull(this.history, 'history').registerPendingArchive(archiveFactsPromise);
-            }
-            catch (err) {
-                logger.warn({ err }, '用户画像归档初始化失败');
-            }
+        catch (err) {
+            logger.warn({ err }, '用户画像归档初始化失败');
         }
-        // 输入分类 → Insight 提取（委托给 InsightExtractor）
-        // ADR-015: full / insights-only 模式下 insight 自动归档
-        if (!skipAutoArchive && this.insightExtractor) {
-            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);
-                }
-            }
-            catch (err) {
-                logger.warn({ err }, 'Insight 提取初始化失败');
-            }
+        // 输入分类 → Insight 提取（委托 ArchiveCoordinator，与手动归档路径统一）
+        try {
+            // fire-and-forget 包装：classify 判断由 ArchiveCoordinator 内部完成
+            // 失败时发射 archiveFailed 事件，让宿主 UI 可通知用户（而非静默吞没）
+            const archiveInsightPromise = this.requireArchiveCoordinator.archiveInsight(input, assistantContent, { autoTriggered: true }).then(() => { }, (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn({ err, stage: 'insight' }, '归档失败');
+                this.emit(AGENT_EVENTS.archiveFailed, { stage: 'insight', message: message.slice(0, 200) });
+            });
+            history.registerPendingArchive(archiveInsightPromise);
+        }
+        catch (err) {
+            logger.warn({ err }, 'Insight 提取初始化失败');
         }
         // AutoConfigRefiner（模式 3：Agent 智能总结）
         if (this.autoConfigRefiner) {
@@ -560,7 +599,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 +626,7 @@ export class Agent extends TypedEventEmitter {
      */
     forkSession(targetSession) {
         this.assertInitialized('forkSession');
-        return this.requireNonNull(this._sessionManager, 'sessionManager').forkSession(targetSession);
+        return this.requireSessionManager.forkSession(targetSession);
     }
     /**
      * 切换到指定项目
@@ -598,12 +637,8 @@ export class Agent extends TypedEventEmitter {
     async switchProject(nameOrPath) {
         this.assertInitialized('switchProject', ['projectManager', 'provider']);
         // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换项目', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
-        }
-        const pm = this.requireNonNull(this.projectManager, 'projectManager');
+        this.assertNotBusy('切换项目');
+        const pm = this.projectManager;
         const projects = pm.list;
         let target = projects.find((p) => p.name === nameOrPath || p.path === nameOrPath);
         if (!target) {
@@ -611,14 +646,25 @@ 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;
-        this.pctx = newPctx;
-        await this.rebuildComponentsWithCurrentCtx();
+        // 先尝试重建组件，失败时回滚 pctx 防止状态不一致
+        try {
+            this.pctx = newPctx;
+            await this.rebuildComponentsWithCurrentCtx();
+        }
+        catch (err) {
+            // 回滚：恢复旧 pctx（若存在）
+            if (fromProjectPath) {
+                logger.warn({ err: toError(err) }, 'switchProject: 组件重建失败，回滚项目上下文');
+                this.pctx = { projectPath: fromProjectPath };
+            }
+            throw err;
+        }
         // 发射项目切换事件（供宿主 UI 刷新项目相关界面）
-        this.emit('projectSwitched', {
+        this.emit(AGENT_EVENTS.projectSwitched, {
             from: fromProjectPath,
             to: projectPath,
             projectName,
@@ -643,6 +689,18 @@ export class Agent extends TypedEventEmitter {
             messages: this.#config.messages,
             enableContextSummary: this.#config.enableContextSummary,
             existingSkillManager: this.skillManager,
+            onWorkProjectionGenerated: (sourcePath, summary) => {
+                this.emit(AGENT_EVENTS.workProjectionGenerated, { sourcePath, summary });
+            },
+            onContextTruncated: (skippedCount, keptCount) => {
+                this.emit(AGENT_EVENTS.contextTruncated, { skippedCount, keptCount });
+            },
+            onDedupCompleted: (report) => {
+                this.emit(AGENT_EVENTS.dedupCompleted, { deduplicatedCount: report.deduplicatedCount, demotedIds: report.demotedIds });
+            },
+            onGuardrailError: (rule, message) => {
+                this.emit(AGENT_EVENTS.guardrailError, { rule, message });
+            },
         });
         this.history = result.history;
         this.loop = result.loop;
@@ -653,14 +711,16 @@ export class Agent extends TypedEventEmitter {
         this.insightExtractor = result.insightExtractor;
         this.configManager = result.configManager;
         this.memoryInspector = result.memoryInspector;
-        this.#memoryMutator = result.memoryMutator;
+        this.dedupManager = result.dedupManager;
+        this.memoryAdvisor = result.memoryAdvisor;
         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) => {
-            this.emit('conflictDetected', info);
+            this.emit(AGENT_EVENTS.conflictDetected, info);
         });
         // 注入 VectorStore 到 MemoryInspector，启用混合搜索
         if (this.memoryInspector && this.#config.vectorStore) {
@@ -692,21 +752,19 @@ export class Agent extends TypedEventEmitter {
      */
     createSessionManager() {
         const forwardEvent = (event, data) => {
-            if (AGENT_EVENT_NAMES.has(event)) {
+            if (AGENT_EVENT_SET.has(event)) {
                 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 耗尽',
-            ]);
-        }
+        this.assertNotBusy('切换 Provider');
         this.#provider = provider;
         if (this.loop) {
             this.loop.setProvider(provider);
@@ -715,11 +773,7 @@ export class Agent extends TypedEventEmitter {
     }
     setBackgroundProvider(provider) {
         // 与 setProvider 一致，对话进行中禁止切换后台 Provider
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换后台 Provider', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
-        }
+        this.assertNotBusy('切换后台 Provider');
         this.#backgroundProvider = provider;
         // 同步更新 AutoConfigRefiner 的后台 Provider
         if (this.autoConfigRefiner) {
@@ -736,15 +790,12 @@ export class Agent extends TypedEventEmitter {
      * @param mode 目标模式
      */
     setArchiveMode(mode) {
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换归档模式', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
-        }
+        this.assertNotBusy('切换归档模式');
         const prev = this.#config.archiveMode;
         if (prev === mode)
             return; // 幂等：无变更直接返回
         this.#config.archiveMode = mode;
+        this.emit(AGENT_EVENTS.archiveModeChanged, { from: prev, to: mode });
         logger.info({ from: prev, to: mode }, '归档模式已切换');
     }
     /**
@@ -755,20 +806,180 @@ export class Agent extends TypedEventEmitter {
     getArchiveMode() {
         return this.#config.archiveMode;
     }
+    /**
+     * 手动切换角色（宿主 UI 角色选择器入口）
+     *
+     * 与 doPostProcess 中的自动匹配走同一条事件链路，确保：
+     *   1. AgentLoop 的 systemPromptPrefix 立即刷新（下一次对话使用新角色 prompt）
+     *   2. 发射 personaSwitched 事件，触发 spriteLifecycleManager 的完整副作用：
+     *      - emit('personaChanged') 通知宿主 UI
+     *      - proactiveEngine.addNotice('persona', ...) 记录通知
+     *      - perceptionCoordinator.refreshBeforeChat() 基于新角色 traits 重新推导情感基调
+     *
+     * 对话进行中切换角色会破坏当前 system prompt，与项目切换一致拒绝。
+     *
+     * @param name 目标角色名
+     * @returns 切换成功返回新角色的 system prompt 段；角色不存在或切换失败返回 null
+     */
+    switchPersona(name) {
+        this.assertInitialized('switchPersona');
+        this.assertNotBusy('切换角色');
+        if (!this.personaManager)
+            return null;
+        // 同名切换幂等：直接返回当前 prompt，不触发事件链路
+        if (this.personaManager.activeName === name) {
+            return this.personaManager.buildSystemPrompt();
+        }
+        const prevName = this.personaManager.activeName;
+        try {
+            this.personaManager.switchPersona(name);
+        }
+        catch (err) {
+            // 角色不存在时 PersonaManager 抛 MemoraError，降级为 null 返回
+            logger.warn({ err: toError(err).message, name }, '手动切换角色失败');
+            return null;
+        }
+        // 同步刷新 AgentLoop 的角色前缀（关键：否则下一次对话仍用旧角色 prompt）
+        // 与 doPostProcess 自动匹配共用同一段逻辑，ADR-017 枝叶层 2 次提取
+        this.refreshPersonaPrefixOnLoop();
+        // 发射切换事件，触发宿主 UI 刷新 + 感知重推导 + 通知队列记录
+        this.emit(AGENT_EVENTS.personaSwitched, { from: prevName, to: name });
+        logger.info({ from: prevName, to: name }, '角色手动切换');
+        return this.personaManager.buildSystemPrompt();
+    }
+    /**
+     * 获取角色切换锁定状态（透传 PersonaManager，P0-2 用户体验打磨）
+     *
+     * 与 switchPersona 分离：switchPersona 仍返回 string | null 不变，
+     * 锁定原因查询走独立路径，避免破坏既有契约（cli.ts、sprite.test.ts 等消费者无感）。
+     *
+     * 宿主 IPC 层调用此方法前置判断锁定状态，区分"切换失败"原因
+     * （locked / busy / not_found / invalid），让用户知道为什么没反应。
+     *
+     * @returns locked 是否处于锁定状态；unlockAt 锁定自动恢复时间戳（ms epoch），未锁定时为 null
+     */
+    getPersonaSwitchLockStatus() {
+        this.assertInitialized('getPersonaSwitchLockStatus');
+        if (!this.personaManager)
+            return { locked: false, unlockAt: null };
+        return this.personaManager.getSwitchLockStatus();
+    }
+    /**
+     * 刷新 AgentLoop 的 systemPromptPrefix（角色 prompt + profile prompt）
+     *
+     * 提取自 doPostProcess 自动匹配 + switchPersona 手动切换两处共用逻辑（ADR-017 枝叶层 2 次提取）。
+     * 组装规则：[personaPrompt, profilePrompt].filter(Boolean).join('\n\n') + 末尾分隔符 '---'
+     *
+     * 调用时机：
+     * - tryAutoMatchPersona 中角色自动匹配成功后（chat() 回答前）
+     * - switchPersona 手动切换成功后
+     * - loop 为 null 时静默跳过（init 前或 close 后的边界场景）
+     */
+    refreshPersonaPrefixOnLoop() {
+        if (!this.loop)
+            return;
+        const profilePrompt = this.userProfile?.buildSystemPrompt() ?? '';
+        const personaPrompt = this.personaManager?.buildSystemPrompt() ?? '';
+        const newPrefix = [personaPrompt, profilePrompt].filter(Boolean).join('\n\n') +
+            ([personaPrompt, profilePrompt].some(Boolean) ? '\n\n---\n\n' : '');
+        this.loop.refreshPersonaPrefix(newPrefix);
+    }
+    /**
+     * 角色自动匹配（best-effort：失败不阻塞对话流程）
+     *
+     * 在 chat() 回答前执行，确保本轮 LLM 调用就用匹配到的角色 system prompt。
+     * 两层匹配策略：关键词高置信度 → LLM 辅助（低置信度且 backgroundProvider 已注入时）。
+     * LLM 辅助匹配在 agent 层执行，遵循 backend_layers_rules §分层职责（persona/ 不直接调 LLM）。
+     *
+     * 匹配成功时：切换角色 + 发射 personaSwitched 事件 + 刷新 AgentLoop 前缀。
+     * 匹配失败/异常时：静默降级，保持当前角色。
+     *
+     * @param input 用户输入文本
+     */
+    async tryAutoMatchPersona(input) {
+        if (!this.personaManager)
+            return;
+        try {
+            let matchedPersona = null;
+            if (this.personaManager.canAutoMatch()) {
+                matchedPersona = 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);
+                this.emit(AGENT_EVENTS.personaSwitched, { from: prevName, to: matchedPersona });
+                // 刷新 AgentLoop 的角色前缀（与 switchPersona 共用同一段逻辑，ADR-017 枝叶层 2 次提取）
+                this.refreshPersonaPrefixOnLoop();
+                logger.info({ persona: matchedPersona }, '角色自动切换');
+            }
+            else {
+                // 关键词 + LLM 均未命中，且当前角色不是列表首个角色 → 回退到首个角色
+                // "切过去回不来"：用户从默认切到散文作者后，输入无关话题应回到默认角色
+                // 使用 list[0] 而非硬编码 'default'：防止 default 角色被删除后 fallback 抛异常
+                const shouldFallback = this.shouldFallbackToDefault();
+                if (shouldFallback) {
+                    const fallbackTarget = this.personaManager.list[0]?.name ?? 'default';
+                    const prevName = this.personaManager.activeName;
+                    this.personaManager.switchPersona(fallbackTarget);
+                    this.emit(AGENT_EVENTS.personaSwitched, { from: prevName, to: fallbackTarget });
+                    this.refreshPersonaPrefixOnLoop();
+                    logger.info({ persona: fallbackTarget }, '角色回退默认');
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err }, '角色自动匹配失败');
+        }
+    }
+    /**
+     * 判断是否应回退到默认角色
+     *
+     * 回退条件（全部满足）：
+     *   1. 当前激活角色不是默认角色（已在默认角色则无需回退）
+     *   2. 角色管理器存在且非锁定状态（锁定时 switchPersona 也会被拦截，回退无意义）
+     *
+     * 注意：bgProvider 未配置时也会触发回退——因为关键词 + LLM 均未命中说明当前角色不匹配本轮对话，
+     * 回退默认角色比卡在错误角色上更合理。
+     *
+     * @returns 是否应回退到默认角色
+     */
+    shouldFallbackToDefault() {
+        if (!this.personaManager)
+            return false;
+        // manual 模式下不回退：用户明确固定了角色，回退会破坏其意图
+        if (this.personaManager.currentMode !== 'auto')
+            return false;
+        const status = this.personaManager.getSwitchLockStatus();
+        if (status.locked)
+            return false; // 锁定中不回退，避免无意义调用 switchPersona
+        // 当前角色已是���表首个角色（"默认"角色）→ 无需回退
+        const defaultName = this.personaManager.list[0]?.name;
+        return defaultName !== undefined && this.personaManager.activeName !== defaultName;
+    }
     /**
      * 手动触发 profile facts 归档（manual 模式下使用）
      *
      * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
      * full / insights-only 模式下也可调用（会重复归档，但不推荐）。
      *
+     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
+     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
+     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     *
      * 归档逻辑已委托给 ArchiveCoordinator
      *
      * @param input 本轮用户输入
+     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
      * @returns 写入/更新的 UserProfileEntry 列表
      */
-    async archiveProfileFacts(input) {
+    async archiveProfileFacts(input, options) {
         this.assertInitialized('archiveProfileFacts');
-        return this.archiveCoordinator.archiveProfileFacts(input);
+        return this.requireArchiveCoordinator.archiveProfileFacts(input, options);
     }
     /**
      * 手动触发 insight 提取（manual 模式下使用）
@@ -776,15 +987,20 @@ export class Agent extends TypedEventEmitter {
      * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
      * 内部仍走 classify 判断（避免无价值输入浪费 LLM 调用）。
      *
+     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
+     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
+     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     *
      * 归档逻辑已委托给 ArchiveCoordinator
      *
      * @param input 本轮用户输入
      * @param assistantContent 本轮助手回复内容
+     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
      * @returns 写入/更新的 Memory 列表
      */
-    async archiveInsight(input, assistantContent) {
+    async archiveInsight(input, assistantContent, options) {
         this.assertInitialized('archiveInsight');
-        return this.archiveCoordinator.archiveInsight(input, assistantContent);
+        return this.requireArchiveCoordinator.archiveInsight(input, assistantContent, options);
     }
     /**
      * 手动归档会话内容（content 类记忆）
@@ -792,15 +1008,32 @@ export class Agent extends TypedEventEmitter {
      * 适用于 `insights-only` / `manual` 模式下用户手动触发会话内容归档。
      * `full` 模式下由宿主在会话切换前自动调用，无需用户干预。
      *
+     * FIX-P1-4：新增 options 参数透传给 ArchiveCoordinator。
+     * 宿主自动触发时传 `{ autoTriggered: true }`，由 ArchiveCoordinator 内部按模式判断；
+     * 用户手动触发时无需传 options（默认 autoTriggered=false，无条件执行）。
+     *
      * 归档逻辑已委托给 ArchiveCoordinator
      *
      * @param date 会话日期 YYYY-MM-DD
      * @param session 会话标识（不含日期前缀）
+     * @param options 触发选项（autoTriggered 默认 false，即手动触发）
      * @returns 归档结果（memories 可能为空，表示无归档价值或 LLM 失败）
      */
-    async archiveSessionContent(date, session) {
+    async archiveSessionContent(date, session, options) {
         this.assertInitialized('archiveSessionContent');
-        return this.archiveCoordinator.archiveSessionContent(date, session);
+        return this.requireArchiveCoordinator.archiveSessionContent(date, session, options);
+    }
+    /**
+     * 获取 pending 归档队列长度（MIND2-C3）
+     *
+     * 返回待重试的失败归档数。归档失败时输入入队，下次同阶段归档调用时自动重试。
+     * 供宿主 UI 展示"N 条待补归档"提示，或判断是否需要手动触发重试。
+     *
+     * @returns pending 队列长度（0 表示无待补）
+     */
+    getPendingArchiveCount() {
+        this.assertInitialized('getPendingArchiveCount');
+        return this.requireArchiveCoordinator.getPendingArchiveCount();
     }
     // ─── 配置重载（事件驱动） ───────────────────────
     /**
@@ -812,7 +1045,7 @@ export class Agent extends TypedEventEmitter {
      * 支持的 source：
      * - 'skill' → SkillManager.reload() 清空缓存重新扫描 skills/ 目录
      * - 'persona' → PersonaManager.reload() 清空缓存重新扫描 personas/ 目录（保持激活角色）
-     * - 'rule' → 无操作（rule 类型已由 ConfigManager.addRule() 即时注入 system prompt）
+     * - 'rule' → 无操作（rule 类型由 ConfigManager CRUD 即时同步 bootstrap 段，详见 deleteRule/updateRule）
      * - 'guardrail' → 抛错（guardrail 是 AgentLoop 的 readonly 数组，需 rebuildComponents 才能重载）
      * - undefined → 重载 skill + persona（全量重载，不含 guardrail）
      *
@@ -821,36 +1054,58 @@ export class Agent extends TypedEventEmitter {
      */
     async reloadConfig(source) {
         this.assertInitialized('reloadConfig');
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重载配置', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
+        if (this.chatLockManager?.isBusy) {
+            // 对话进行中无法热重载：将 source 暂存，待 chat() finally 块释放锁后补执行
+            // source 为 undefined（全量重载）时不暂存——全量重载无具体来源，补执行语义不明
+            if (source) {
+                this.pendingConfigReload.add(source);
+                logger.info({ source }, '对话进行中，配置重载已暂存，将在对话结束后补执行');
+            }
+            throw chatBusyError('重载配置');
         }
         // guardrail 需重建 AgentLoop，不属于热重载范畴
         if (source === 'guardrail') {
             throw configError('guardrail 不支持热重载', 'guardrail 规则是 AgentLoop 的 readonly 数组，需调用 rebuildComponents() 重建', ['使用 rebuildComponents() 重建组件（代价较高）']);
         }
-        // rule 类型已由 ConfigManager.addRule() 即时注入，无需重载
+        // rule 类型由 ConfigManager.deleteRule/updateRule CRUD 即时同步 bootstrap 段（refreshBootstrapMemories 回调），无需 reloadConfig
         if (source === 'rule') {
-            logger.info('rule 类型已由 addRule() 即时注入，reloadConfig 跳过');
+            logger.info('rule 类型由 ConfigManager CRUD 即时同步 bootstrap 段，reloadConfig 跳过');
             return { skill: 0, persona: 0 };
         }
         const result = { skill: 0, persona: 0 };
+        const errors = [];
         // 按需重载：source 缺省时全量重载，否则只重载指定类型
         const shouldReloadSkill = !source || source === 'skill';
         const shouldReloadPersona = !source || source === 'persona';
         if (shouldReloadSkill && this.skillManager) {
-            result.skill = await this.skillManager.reload();
+            try {
+                result.skill = await this.skillManager.reload();
+            }
+            catch (err) {
+                errors.push(toError(err));
+                logger.warn({ err: toError(err) }, 'reloadConfig: skillManager.reload 失败');
+            }
         }
         if (shouldReloadPersona && this.personaManager) {
-            result.persona = await this.personaManager.reload();
-            // 角色重载后，刷新 AgentLoop 的角色前缀（使新角色内容立即注入 system prompt）
-            if (this.loop) {
-                const newPrefix = this.personaManager.buildSystemPrompt();
-                this.loop.refreshPersonaPrefix(newPrefix);
+            try {
+                result.persona = await this.personaManager.reload();
+                // 角色重载后，刷新 AgentLoop 的角色前缀（使新角色内容立即注入 system prompt）
+                if (this.loop) {
+                    const newPrefix = this.personaManager.buildSystemPrompt();
+                    this.loop.refreshPersonaPrefix(newPrefix);
+                }
+            }
+            catch (err) {
+                errors.push(toError(err));
+                logger.warn({ err: toError(err) }, 'reloadConfig: personaManager.reload 失败');
             }
         }
-        logger.info({ source, ...result }, '配置已热重载');
+        if (errors.length > 0) {
+            logger.warn({ source, ...result, errorCount: errors.length }, '配置热重载部分失败');
+        }
+        else {
+            logger.info({ source, ...result }, '配置已热重载');
+        }
         return result;
     }
     // ─── 组件访问 ─────────────────────────────────────────
@@ -862,11 +1117,7 @@ export class Agent extends TypedEventEmitter {
      */
     async rebuildComponents() {
         // 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this._chatBusy) {
-            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重建组件', [
-                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
-            ]);
-        }
+        this.assertNotBusy('重建组件');
         await this.rebuildComponentsWithCurrentCtx();
     }
     // ─── 守卫方法 ───────────────────────────────────────────
@@ -897,17 +1148,55 @@ export class Agent extends TypedEventEmitter {
         }
     }
     /**
-     * 非空断言守卫——对 null/undefined 值抛出清晰错误的运行时检查
+     * 断言对话未进行中 — 统一守卫，避免在 chat() 进行中执行会破坏状态一致性的操作
      *
-     * @param value 可能为 null/undefined 的值
-     * @param name 组件名称（用于错误消息）
-     * @throws MemoraError 如果 value 为 null/undefined
+     * 提取原因：switchProject / setProvider / setBackgroundProvider / setArchiveMode /
+     * switchPersona / rebuildComponents 等 6 处方法均有相同的 `if (isBusy) throw chatBusyError('XXX')` 守卫，
+     * 违反 DRY 原则（v2 神木回天 REPEAT-4 闭环）。
+     *
+     * 注意：reloadConfig 不使用本方法——它在 isBusy 时需暂存 source 而非直接抛错。
+     *
+     * @param operation 操作名称（用于错误消息，如 "切换项目"）
      */
-    requireNonNull(value, name) {
-        if (value === null || value === undefined) {
-            throw configError('Agent 未初始化', `${name} 组件不可用`, ['请先调用 await agent.init()']);
+    assertNotBusy(operation) {
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError(operation);
         }
-        return value;
+    }
+    /**
+     * 断言 getter：获取 loop，若 null 则抛出明确错误
+     * 替代 `this.loop!` 非空断言，提供更好的重构安全性
+     */
+    get requireLoop() {
+        if (!this.loop)
+            throw configError('AgentLoop 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this.loop;
+    }
+    /**
+     * 断言 getter：获取 history，若 null 则抛出明确错误
+     */
+    get requireHistory() {
+        if (!this.history)
+            throw configError('MessageHistory 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this.history;
+    }
+    /**
+     * 断言 getter：获取 pctx，若 null 则抛出明确错误
+     */
+    get requirePctx() {
+        if (!this.pctx)
+            throw configError('ProjectContext 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this.pctx;
+    }
+    get requireArchiveCoordinator() {
+        if (!this.archiveCoordinator)
+            throw configError('ArchiveCoordinator 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this.archiveCoordinator;
+    }
+    get requireSessionManager() {
+        if (!this._sessionManager)
+            throw configError('SessionManager 未初始化', undefined, ['在调用此方法前执行 await agent.init()']);
+        return this._sessionManager;
     }
     // ─── 记忆生命周期 ───────────────────────────────────────
     // ─── runMemoryDecay 已迁移至 MemoryDecayScheduler.runOnce ─────
@@ -916,65 +1205,96 @@ 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 引用）
+        // FIX-P0-1：先 stop() abort L2 评估的 LLM 调用，再 awaitInflight() 等待 Promise 完成，
+        // 防止 close 后 LLM 回调 upsert 已关闭的 storage
         if (this.memoryDecayScheduler) {
             this.memoryDecayScheduler.stop();
+            try {
+                await this.memoryDecayScheduler.awaitInflight();
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: memoryDecayScheduler.awaitInflight 失败');
+            }
             this.memoryDecayScheduler = null;
         }
+        // FIX-P0-1：等待 WorkProjection 的 inflight LLM 生成完成，防止 close 后 upsert 已关闭的 storage
+        if (this.workProjection) {
+            try {
+                await this.workProjection.awaitInflight();
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: workProjection.awaitInflight 失败');
+            }
+        }
         // 清理 ArchiveCoordinator（无定时器，只需释放引用）
         this.archiveCoordinator = null;
-        // 清理定时器
-        if (this.decayTimer) {
-            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);
+            try {
+                await this.history.awaitPendingArchives(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: awaitPendingArchives 失败');
+            }
         }
+        // pending archives 完成后再移除监听器，确保归档失败的 emit 能送达
+        this.removeAllListeners();
         if (this.projectManager) {
-            await this.projectManager.shutdown();
+            try {
+                await this.projectManager.shutdown();
+            }
+            catch (err) {
+                logger.warn({ err: toError(err) }, 'close: projectManager.shutdown 失败');
+            }
         }
         this._initialized = false;
+        this.nullifyAllComponents();
+        // 清理次要状态字段，防止 re-init 后残留上一会话状态
+        this._lastInteractionAt = null;
+        this.pendingConfigReload.clear();
+    }
+    /**
+     * 统一 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.dedupManager = null;
+        this.memoryAdvisor = null;
+        this._governance = 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() {
@@ -983,9 +1303,30 @@ export class Agent extends TypedEventEmitter {
     get context() {
         return this.pctx;
     }
+    /**
+     * @deprecated 直接暴露 AgentLoop 破坏封装，将在下一主版本移除。
+     * 使用 getMessages() / getMessageCount() 等有界接口替代。
+     */
     get agentLoop() {
         return this.loop;
     }
+    /**
+     * 获取当前消息列表（只读副本，不可绕过 Agent 编排链路直接修改）
+     */
+    getMessages() {
+        return this.loop?.getMessages() ?? [];
+    }
+    /** 获取当前消息数量 */
+    getMessageCount() {
+        return this.loop?.getMessages().length ?? 0;
+    }
+    /**
+     * @deprecated 直接暴露 MessageHistory 破坏封装，将在下一主版本移除。
+     * 使用 Agent 的对话管理方法（chat/chatSync/forkSession）替代直接操作。
+     */
+    get agentHistory() {
+        return this.history;
+    }
     /**
      * 注入情感基调到 system prompt（Phase 2.1：AffectController）
      *
@@ -995,20 +1336,33 @@ export class Agent extends TypedEventEmitter {
      * @param affectString 情感描述文本，传空字符串清除注入
      */
     injectAffect(affectString) {
-        this.loop?.injectAffect(affectString);
-    }
-    get agentHistory() {
-        return this.history;
+        if (!this.loop)
+            throw configError('AgentLoop', 'AgentLoop 未初始化，无法注入 affect', []);
+        this.loop.injectAffect(affectString);
     }
     get provider() {
         return this.#provider;
     }
     get isBusy() {
-        return this._chatBusy;
+        return this.chatLockManager?.isBusy ?? false;
     }
     get lastInteractionAt() {
         return this._lastInteractionAt;
     }
+    /**
+     * 记忆治理统一门面（L0 衰减 / L1 去重 / L2 时效性 / L3 冲突 / 诊断 / 推荐）
+     *
+     * 统一入口替代散落在 Agent 上的 6 个独立方法：
+     *   agent.governance.decay()           → 原 runMemoryDecayOnce()
+     *   agent.governance.deduplicate()     → 原 deduplicateMemories()
+     *   agent.governance.evaluateTimeliness() → 原 evaluateTimeliness()
+     *   agent.governance.detectConflicts() → 原 detectConflicts()
+     *   agent.governance.sourceHealth()    → 原 sourceHealth()
+     *   agent.governance.suggest()         → 原 suggest()
+     */
+    get governance() {
+        return this._governance;
+    }
     // ─── 运行时指标 ────────────────────────────────
     /**
      * 获取 Agent 运行时指标快照（可观测性增强）
@@ -1055,7 +1409,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,17 +1461,6 @@ export class Agent extends TypedEventEmitter {
     get memory() {
         return this.memoryInspector;
     }
-    /**
-     * 记忆写入器（可能为 null）—— upsert / delete / restore / purge / purgeExpired /
-     * addRelation / removeRelation
-     *
-     * P1-2 拆分：从 MemoryInspector 拆出写操作代理，与 MemoryInspector 严格分工。
-     * 返回 null 时表示 Agent 未初始化或存储层未就绪。
-     * 宿主项目常用模式：`const m = agent.memoryMutator; if (!m) return; m.upsert(...)`
-     */
-    get memoryMutator() {
-        return this.#memoryMutator;
-    }
     /**
      * 项目管理器（可能为 null）
      *
@@ -1166,5 +1509,9 @@ export class Agent extends TypedEventEmitter {
     get sessionManager() {
         return this._sessionManager;
     }
+    /** 文本润色管理器（宿主可通过此 getter 调用 polish 方法） */
+    get polish() {
+        return this.textPolisher;
+    }
 }
 //# sourceMappingURL=agent.js.map