@zooique/memora 2.0.0 → 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）。
  *
@@ -26,34 +26,27 @@ 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 { recall, boostScores } from '../memory/recall.js';
 import { assembleComponents } from '../agent/assembler.js';
 import { matchPersonaByLlm } from '../agent/personaMatcher.js';
-import { chatBusyError, configError } from '../utils/errors.js';
-import { clearSafeInterval } from '../utils/safeTimer.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 键集保持一致（10 个事件）
-const AGENT_EVENT_NAMES = new Set([
-    'memoryAdded', 'personaSwitched', 'decayCompleted',
-    'memoryRecalled', 'sessionForked', 'insightExtracted',
-    'conflictDetected', 'projectSwitched', 'skillMatched',
-    'archiveFailed',
-]);
+// 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 不同，它们拥有完全隔离的记忆库和会话。
@@ -98,6 +91,23 @@ export class Agent extends TypedEventEmitter {
     insightExtractor = null;
     configManager = null;
     memoryInspector = 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;
@@ -107,8 +117,7 @@ export class Agent extends TypedEventEmitter {
     textPolisher = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     _sessionManager = null;
-    /** 当前激活的技能名（上一轮匹配，本轮注入） */
-    activeSkill = null;
+    // activeSkill 字段已移除：matchAndInjectSkill 改为当轮实时匹配注入，无需跨轮状态缓存
     _initialized = false;
     // 项目上下文（AgentContext 与 ProjectContext 等价，直接使用后者避免重复字段）
     pctx = null;
@@ -119,10 +128,19 @@ export class Agent extends TypedEventEmitter {
      * 详见 ChatLockManager 类注释。
      */
     chatLockManager = null;
-    /** 记忆衰减定时器（已迁移至 MemoryDecayScheduler，此字段保留用于 close 时引用判断） */
-    decayTimer = 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() 读取
@@ -134,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,
@@ -156,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) {
-            // 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,
@@ -184,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() 是否有未捕获的异常',
@@ -194,29 +230,28 @@ export class Agent extends TypedEventEmitter {
                 '确认 API Key 已配置（环境变量或配置文件）',
             ]);
         }
+    }
+    /**
+     * 创建 init() 后期组件（初始化完成后才需要的组件）
+     */
+    createPostInitComponents(pctx) {
         // chat() 并发锁管理器（生命周期与 Agent 实例一致）
         this.chatLockManager = new ChatLockManager();
-        this._initialized = true;
         // 归档操作委托给 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
-        // L2 时效性评估：注入 backgroundProvider + index（可选，未注入时 evaluateTimeliness 静默跳过）
         this.memoryDecayScheduler = new MemoryDecayScheduler({
             tracer: this.#config.tracer,
             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 回调语义一致：不阻塞衰减循环）
+                this.emit(AGENT_EVENTS.decayCompleted, payload);
+                // MIND2-D4：从 agent.evaluateTimeliness() 迁移到 governance.evaluateTimeliness()
+                void this._governance?.evaluateTimeliness().catch((err) => {
                     logger.warn({ err }, 'L2 时效性评估自动触发失败（已降级，不影响衰减循环）');
                 });
             },
@@ -224,38 +259,21 @@ export class Agent extends TypedEventEmitter {
             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.chatLockManager?.isBusy) {
-            throw chatBusyError('发起新对话');
-        }
-        // 获取锁 + 分配 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 cleanupExternalSignal = chatLock.attachExternalSignal(signal, internalAbort);
-        const combinedSignal = internalAbort.signal;
+        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 消息
-            const loop = 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',
@@ -263,72 +281,128 @@ export class Agent extends TypedEventEmitter {
                 };
                 return;
             }
-            // 注入上一轮匹配的技能 prompt
-            yield { type: 'thinking', phase: 'processing' };
-            this.injectActiveSkill();
-            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 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 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：失败不影响用户已收到的回答）
+            else {
+                yield { type: 'error', message: err instanceof Error ? err.message : String(err) };
+                return;
+            }
+        }
+        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 history.appendAssistant(assistantContent);
+                await this.reloadConfig(src);
+                this.emit(AGENT_EVENTS.configReloaded, { source: src });
             }
             catch (err) {
-                logger.warn({ err }, '助手消息历史写入失败');
+                logger.warn({ err, source: src }, '补执行配置重载失败');
             }
-            // 后处理阶段
-            yield { type: 'thinking', phase: 'archiving' };
-            await this.postProcess(input, assistantContent);
-        }
-        finally {
-            // 仅当本调用仍是当前锁持有者时才清理资源（token 校验）
-            // 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态
-            this.chatLockManager?.release(myToken);
-            cleanupExternalSignal();
         }
     }
     /**
@@ -378,8 +452,8 @@ export class Agent extends TypedEventEmitter {
         });
         let recalledMemories = [];
         try {
-            recalledMemories = await recall(this.pctx.index, input, {
-                limit: 5,
+            recalledMemories = await recall(this.requirePctx.index, input, {
+                limit: AGENT_CONSTANTS.DEFAULT_RECALL_LIMIT,
                 vectorStore: this.#config.vectorStore,
                 excludeSources: this.#config.recallExcludeSources,
             });
@@ -393,11 +467,18 @@ export class Agent extends TypedEventEmitter {
             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.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]';
@@ -413,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 }, '技能匹配失败');
         }
     }
     /**
@@ -445,7 +544,7 @@ export class Agent extends TypedEventEmitter {
             archiveMode: this.#config.archiveMode,
         });
         try {
-            await this.postProcessInner(input, assistantContent);
+            await this.doPostProcess(input, assistantContent);
         }
         finally {
             span.end();
@@ -456,95 +555,42 @@ export class Agent extends TypedEventEmitter {
      *
      * 原 postProcess 逻辑完整保留于此，由外层 postProcess 负责 span 生命周期管理。
      */
-    async postProcessInner(input, assistantContent) {
-        // 角色自动匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
-        // 两层匹配策略：关键词高置信度 → LLM 辅助（低置信度且 backgroundProvider 已注入时）
-        // LLM 辅助匹配在 agent 层执行，遵循 backend_layers_rules §分层职责（persona/ 不直接调 LLM）
-        if (this.personaManager) {
-            try {
-                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);
-                    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 }, '角色自动匹配失败');
-            }
-        }
-        // 技能关键词匹配（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 }, '技能匹配失败');
-            }
-        }
-        // ADR-015: manual 模式跳过所有自动归档（profile + insight），
-        // 需用户手动调用 archiveProfileFacts/archiveInsight 触发。
+    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 违反）
-        // ADR-015: full / insights-only 模式下 profile facts 自动归档
-        const history = this.history;
-        if (!skipAutoArchive) {
-            try {
-                // 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) });
-                });
-                history.registerPendingArchive(archiveFactsPromise);
-            }
-            catch (err) {
-                logger.warn({ err }, '用户画像归档初始化失败');
-            }
+        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);
+        }
+        catch (err) {
+            logger.warn({ err }, '用户画像归档初始化失败');
         }
         // 输入分类 → Insight 提取（委托 ArchiveCoordinator，与手动归档路径统一）
-        // ADR-015: full / insights-only 模式下 insight 自动归档
-        if (!skipAutoArchive) {
-            try {
-                // 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 提取初始化失败');
-            }
+        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) {
@@ -580,7 +626,7 @@ export class Agent extends TypedEventEmitter {
      */
     forkSession(targetSession) {
         this.assertInitialized('forkSession');
-        return this._sessionManager.forkSession(targetSession);
+        return this.requireSessionManager.forkSession(targetSession);
     }
     /**
      * 切换到指定项目
@@ -591,9 +637,7 @@ export class Agent extends TypedEventEmitter {
     async switchProject(nameOrPath) {
         this.assertInitialized('switchProject', ['projectManager', 'provider']);
         // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换项目');
-        }
+        this.assertNotBusy('切换项目');
         const pm = this.projectManager;
         const projects = pm.list;
         let target = projects.find((p) => p.name === nameOrPath || p.path === nameOrPath);
@@ -606,10 +650,21 @@ export class Agent extends TypedEventEmitter {
         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,
@@ -634,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;
@@ -644,6 +711,8 @@ export class Agent extends TypedEventEmitter {
         this.insightExtractor = result.insightExtractor;
         this.configManager = result.configManager;
         this.memoryInspector = result.memoryInspector;
+        this.dedupManager = result.dedupManager;
+        this.memoryAdvisor = result.memoryAdvisor;
         this.autoConfigRefiner = result.autoConfigRefiner;
         this.workProjection = result.workProjection;
         this.sessionArchiver = result.sessionArchiver;
@@ -651,7 +720,7 @@ export class Agent extends TypedEventEmitter {
         // 绑定冲突检测回调，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) {
@@ -683,7 +752,7 @@ 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);
             }
         };
@@ -695,9 +764,7 @@ export class Agent extends TypedEventEmitter {
     setProvider(provider) {
         // 对话进行中切换 Provider 会导致同一 processUserInput 循环内前后两次 LLM 调用命中不同 Provider
         // （模型上下文窗口假设不一致 → 可能导致上下文截断逻辑误判或 tool_call 格式不兼容）
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换 Provider');
-        }
+        this.assertNotBusy('切换 Provider');
         this.#provider = provider;
         if (this.loop) {
             this.loop.setProvider(provider);
@@ -706,9 +773,7 @@ export class Agent extends TypedEventEmitter {
     }
     setBackgroundProvider(provider) {
         // 与 setProvider 一致，对话进行中禁止切换后台 Provider
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换后台 Provider');
-        }
+        this.assertNotBusy('切换后台 Provider');
         this.#backgroundProvider = provider;
         // 同步更新 AutoConfigRefiner 的后台 Provider
         if (this.autoConfigRefiner) {
@@ -725,13 +790,12 @@ export class Agent extends TypedEventEmitter {
      * @param mode 目标模式
      */
     setArchiveMode(mode) {
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('切换归档模式');
-        }
+        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 }, '归档模式已切换');
     }
     /**
@@ -742,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 模式下使用）
@@ -763,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 类记忆）
@@ -779,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();
     }
     // ─── 配置重载（事件驱动） ───────────────────────
     /**
@@ -799,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）
      *
@@ -809,33 +1055,57 @@ export class Agent extends TypedEventEmitter {
     async reloadConfig(source) {
         this.assertInitialized('reloadConfig');
         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 失败');
+            }
+        }
+        if (errors.length > 0) {
+            logger.warn({ source, ...result, errorCount: errors.length }, '配置热重载部分失败');
+        }
+        else {
+            logger.info({ source, ...result }, '配置已热重载');
         }
-        logger.info({ source, ...result }, '配置已热重载');
         return result;
     }
     // ─── 组件访问 ─────────────────────────────────────────
@@ -847,9 +1117,7 @@ export class Agent extends TypedEventEmitter {
      */
     async rebuildComponents() {
         // 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
-        if (this.chatLockManager?.isBusy) {
-            throw chatBusyError('重建组件');
-        }
+        this.assertNotBusy('重建组件');
         await this.rebuildComponentsWithCurrentCtx();
     }
     // ─── 守卫方法 ───────────────────────────────────────────
@@ -879,6 +1147,57 @@ export class Agent extends TypedEventEmitter {
             }
         }
     }
+    /**
+     * 断言对话未进行中 — 统一守卫，避免在 chat() 进行中执行会破坏状态一致性的操作
+     *
+     * 提取原因：switchProject / setProvider / setBackgroundProvider / setArchiveMode /
+     * switchPersona / rebuildComponents 等 6 处方法均有相同的 `if (isBusy) throw chatBusyError('XXX')` 守卫，
+     * 违反 DRY 原则（v2 神木回天 REPEAT-4 闭环）。
+     *
+     * 注意：reloadConfig 不使用本方法——它在 isBusy 时需暂存 source 而非直接抛错。
+     *
+     * @param operation 操作名称（用于错误消息，如 "切换项目"）
+     */
+    assertNotBusy(operation) {
+        if (this.chatLockManager?.isBusy) {
+            throw chatBusyError(operation);
+        }
+    }
+    /**
+     * 断言 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 ─────
     // ─── 关闭 ─────────────────────────────────────────────
@@ -891,17 +1210,29 @@ export class Agent extends TypedEventEmitter {
         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;
-        }
         // 清理 PersonaManager 的角色切换防抖锁计时器，防止关闭后回调触发
         if (this.personaManager) {
             this.personaManager.close();
@@ -910,18 +1241,28 @@ export class Agent extends TypedEventEmitter {
         // 顺序敏感：若先 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.activeSkill = null;
         this._lastInteractionAt = null;
+        this.pendingConfigReload.clear();
     }
     /**
      * 统一 null 化所有组件字段（新增 Manager 时在此处追加一行）
@@ -943,6 +1284,9 @@ export class Agent extends TypedEventEmitter {
         this.insightExtractor = null;
         this.configManager = null;
         this.memoryInspector = null;
+        this.dedupManager = null;
+        this.memoryAdvisor = null;
+        this._governance = null;
         this.workProjection = null;
         this.autoConfigRefiner = null;
         this.sessionArchiver = null;
@@ -959,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）
      *
@@ -971,10 +1336,9 @@ 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;
@@ -985,6 +1349,20 @@ export class Agent extends TypedEventEmitter {
     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 运行时指标快照（可观测性增强）
@@ -1083,92 +1461,6 @@ 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
-    // 未注入时静默跳过"语义一致（向后兼容）。
-    /**
-     * L1 语义去重（委托 MemoryInspector.deduplicateMemories）
-     *
-     * 扫描名称相似的记忆对，调用 LLM 判断语义等价，降级低分记忆（score→0.1，不物理删除）。
-     * backgroundProvider 未注入或 Agent 未初始化时返回 skippedReason 报告，不抛错。
-     *
-     * @param signal 可选的 AbortSignal（取消进行中的 LLM 判断）
-     * @returns 去重报告（扫描数 / 降级 ID 列表 / 跳过原因）
-     */
-    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）
      *