@zooique/memora 0.1.0 → 0.2.0

package/dist/agent/agent.js

@@ -27,20 +27,22 @@ 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/managers/userFactExtractor.js';
+import { extractUserFacts } from '../agent/userFactExtractor.js';
 import { assembleComponents } from '../agent/assembler.js';
-import { configError, toError } from '../utils/errors.js';
-import { safeSetTimeout, clearSafeTimeout, safeSetInterval, clearSafeInterval } from '../utils/safeTimer.js';
+import { configError } from '../utils/errors.js';
+import { safeSetTimeout, clearSafeTimeout, clearSafeInterval } from '../utils/safeTimer.js';
 import { SessionManager } from '../agent/managers/sessionManager.js';
+import { MemoryDecayScheduler } from '../agent/managers/memoryDecayScheduler.js';
+import { ArchiveCoordinator } from '../agent/managers/archiveCoordinator.js';
 import { TypedEventEmitter } from '../utils/eventEmitter.js';
-import { SOURCE_LABELS } from '../memory/types.js';
 import { logger } from '../logging/logger.js';
-import { NOOP_TRACER, TRACE_SPANS } 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 门面类 ───────────────────────────────────────
 /**
@@ -94,8 +96,10 @@ export class Agent extends TypedEventEmitter {
     configManager = null;
     memoryInspector = null;
     workProjection = null;
-    /** V-201: AutoConfigRefiner（模式 3：Agent 智能总结） */
+    /** AutoConfigRefiner（模式 3：Agent 智能总结） */
     autoConfigRefiner = null;
+    /** SessionArchiver（会话内容归档器，content 类记忆） */
+    sessionArchiver = null;
     /** 会话管理器（从 Agent 拆分出的会话管理职责） */
     _sessionManager = null;
     /** 当前激活的技能名（上一轮匹配，本轮注入） */
@@ -105,22 +109,38 @@ export class Agent extends TypedEventEmitter {
     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` 后才清理
+     *   - 不匹配时跳过清理，避免误清新调用者的资源
+     *
+     * 选择 number 而非 Symbol：递增计数器可序列化、零依赖、足够唯一（同一 Agent 实例内）
+     */
+    _chatLockToken = 0;
     /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
     chatLockTimer = null;
     /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
     chatAbortController = null;
-    /** 记忆衰减定时器 */
+    /** 记忆衰减定时器（已迁移至 MemoryDecayScheduler，此字段保留用于 close 时引用判断） */
     decayTimer = null;
     /** 最近一次 chat() 调用的时间戳 */
     _lastInteractionAt = null;
-    // ─── R-103 衰减指标统计字段 ──────────────────────────
-    // 累计值，从 Agent.init() 起累加，close() 后随实例销毁。
-    /** 衰减执行次数（每次 runMemoryDecay 实际执行 +1） */
-    metricDecayRunCount = 0;
-    /** 累计衰减记忆数（score 被调低的记忆条数总和） */
-    metricTotalDecayedCount = 0;
-    /** 上次衰减时间（ISO 8601，null 表示从未执行过） */
-    metricLastDecayAt = null;
+    // ─── 衰减职责已拆分至 MemoryDecayScheduler ──────────
+    // metricDecayRunCount / metricTotalDecayedCount / metricLastDecayAt 字段
+    // 位于 MemoryDecayScheduler 内部，Agent 通过 memoryDecayScheduler.getMetrics() 读取
+    /** 记忆衰减调度器（init 时创建，close 时销毁） */
+    memoryDecayScheduler = null;
+    /** 归档协调器（归档操作委托给 ArchiveCoordinator） */
+    archiveCoordinator = null;
     constructor(opts) {
         super();
         this.#config = {
@@ -143,6 +163,7 @@ export class Agent extends TypedEventEmitter {
             tracer: opts.tracer,
             messages: opts.messages,
             enableContextSummary: opts.enableContextSummary ?? true,
+            archiveMode: opts.archiveMode ?? 'full',
         };
         this.#provider = opts.provider;
         this.#backgroundProvider = opts.backgroundProvider ?? null;
@@ -171,7 +192,7 @@ export class Agent extends TypedEventEmitter {
             dataDir: this.#config.dataDir,
             storage: this.#config.storage,
             registryDir: this.#config.registryDir,
-            // A-004: SecurityGuard 由 Agent 层创建，解除 memory→security 反向依赖
+            // 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);
@@ -185,10 +206,22 @@ export class Agent extends TypedEventEmitter {
             ]);
         }
         this._initialized = true;
-        // 启动时记忆衰减（insight/archive 来源）
-        this.runMemoryDecay();
-        // 定期记忆衰减（每小时）
-        this.decayTimer = safeSetInterval(() => this.runMemoryDecay(), AGENT_CONSTANTS.DECAY_INTERVAL_MS);
+        // 归档操作委托给 ArchiveCoordinator
+        // 使用 getter 回调注入依赖，close 时 null 化字段后 getter 自然返回 null
+        this.archiveCoordinator = new ArchiveCoordinator({
+            getUserProfile: () => this.#userProfile,
+            getInsightExtractor: () => this.insightExtractor,
+            getSessionArchiver: () => this.sessionArchiver,
+            emit: (event, payload) => this.emit(event, payload),
+        });
+        // 记忆衰减职责委托给 MemoryDecayScheduler
+        this.memoryDecayScheduler = new MemoryDecayScheduler({
+            tracer: this.#config.tracer,
+            onDecayCompleted: (payload) => this.emit('decayCompleted', payload),
+        });
+        this.memoryDecayScheduler.start(pctx.index, AGENT_CONSTANTS.DECAY_INTERVAL_MS);
+        // 保留 decayTimer 引用用于 close 时序兼容（实际定时器由 MemoryDecayScheduler 管理）
+        this.decayTimer = null;
         return pctx;
     }
     /**
@@ -206,7 +239,10 @@ export class Agent extends TypedEventEmitter {
             ]);
         }
         this._chatBusy = true;
-        // SEC-02: 内部 AbortController，超时时中断 generator 而非仅释放锁
+        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
+        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
+        const myToken = ++this._chatLockToken;
+        // 内部 AbortController，超时时中断 generator 而非仅释放锁
         const internalAbort = new AbortController();
         this.chatAbortController = internalAbort;
         // 合并外部 signal：外部 abort 时也触发内部
@@ -219,7 +255,12 @@ export class Agent extends TypedEventEmitter {
         }
         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;
@@ -247,9 +288,8 @@ export class Agent extends TypedEventEmitter {
             await this.requireNonNull(this.history, 'history').appendUser(input);
             let assistantContent = '';
             let wasAborted = false;
-            // 修复 P1-D：原实现 generator 抛错直接传到宿主，宿主未 catch 会变未处理 rejection
-            // （表现为"几个字就卡住、无错误日志"——流式输出已开始但错误没机会展示）
-            // 改为 try/catch：把 provider 异常转为 yield error chunk，让宿主能优雅展示并清理 UI
+            // 把 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;
@@ -266,8 +306,8 @@ export class Agent extends TypedEventEmitter {
                 // （如 LLM 超时、连接断开、AbortError 未被 loop 拦截等）
                 // 转为 error chunk 通知宿主，避免裸 throw 导致 UI 卡死
                 if (err instanceof DOMException && err.name === 'AbortError') {
-                    // 翠幕天罗 P1 修复：必须 yield aborted chunk 让宿主能展示中断标记
-                    // （原仅设置 wasAborted 会导致 chatHandlers catch 不触发，渲染层收不到 ABORTED）
+                    // 必须 yield aborted chunk 让宿主能展示中断标记
+                    // （仅设置 wasAborted 会导致 chatHandlers catch 不触发，渲染层收不到 ABORTED）
                     yield { type: 'aborted', reason: 'User cancelled the conversation' };
                     return;
                 }
@@ -277,6 +317,18 @@ export class Agent extends TypedEventEmitter {
                 }
             }
             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 }, '中断消息历史写入失败');
+                    }
+                }
                 return;
             }
             // 追加助手消息到历史（best-effort：失败不影响用户已收到的回答）
@@ -291,15 +343,62 @@ export class Agent extends TypedEventEmitter {
             await this.postProcess(input, assistantContent);
         }
         finally {
-            this._chatBusy = false;
-            this.chatAbortController = null;
-            if (this.chatLockTimer) {
-                clearSafeTimeout(this.chatLockTimer);
-                this.chatLockTimer = null;
+            // 仅当本调用仍是当前锁持有者时才清理资源
+            // 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态
+            if (this._chatLockToken === myToken) {
+                this._chatBusy = false;
+                this.chatAbortController = null;
+                if (this.chatLockTimer) {
+                    clearSafeTimeout(this.chatLockTimer);
+                    this.chatLockTimer = null;
+                }
             }
             signal?.removeEventListener('abort', onExternalAbort);
         }
     }
+    /**
+     * 强制释放对话锁
+     *
+     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
+     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
+     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
+     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
+     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
+     *
+     * 本方法让宿主在确认 generator 挂起后强制释放锁，让用户能立即发起新对话。
+     *
+     * 安全机制：
+     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
+     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
+     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
+     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
+     *     但其 finally 块的 token 校验会阻止它影响新调用
+     *
+     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
+     *
+     * 使用约束：
+     *   - 仅在宿主确认 generator 挂起（如无进展超时）后调用
+     *   - 不应在常规 abort 路径调用（常规 abort 走 signal，generator 自然退出）
+     *   - 调用后不应再消费原 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('对话锁被强制释放（宿主无进展超时兜底）');
+    }
     /**
      * 召回记忆 + 注入最近对话上下文
      *
@@ -354,24 +453,16 @@ export class Agent extends TypedEventEmitter {
      *
      * 所有归档/匹配操作均为 best-effort：任何子步骤失败不应影响用户已收到的回答，
      * 失败仅记录日志，不向上抛出异常。
+     *
+     * ADR-015 归档模式控制：
+     * - 角色匹配 + 技能匹配不受 archiveMode 影响（每轮都执行，非归档行为）
+     * - `manual` 模式跳过所有自动归档（profile + insight），需用户手动调用
+     *   archiveProfileFacts() / archiveInsight() 触发
+     * - `full` / `insights-only` 模式下 profile + insight 都自动归档
+     *   （会话归档实现后，`insights-only` 将跳过对话原始内容自动归档）
      */
     async postProcess(input, assistantContent) {
-        // 用户画像实时归档（语义解析在 agent/ 层，存储在 memory/ 层）
-        if (this.#userProfile) {
-            try {
-                const turnIndex = `turn-${Date.now()}`;
-                const facts = extractUserFacts(input, turnIndex);
-                // FD-22: 注册到 pendingArchives，确保 close() 时等待后台归档完成，避免写入已关闭的存储
-                const archiveFactsPromise = this.#userProfile.archiveFacts(facts).catch((err) => {
-                    logger.warn({ err }, '用户画像实时归档失败');
-                });
-                this.requireNonNull(this.history, 'history').registerPendingArchive(archiveFactsPromise);
-            }
-            catch (err) {
-                logger.warn({ err }, '用户画像归档初始化失败');
-            }
-        }
-        // 角色自动匹配（best-effort：失败不阻塞对话结束）
+        // 角色自动匹配（best-effort：失败不阻塞对话结束，非归档行为不受 archiveMode 影响）
         if (this.personaManager) {
             try {
                 const matchedPersona = this.personaManager.autoMatch(input);
@@ -393,12 +484,14 @@ export class Agent extends TypedEventEmitter {
                 logger.warn({ err }, '角色自动匹配失败');
             }
         }
-        // 技能关键词匹配（best-effort：失败不阻塞对话结束）
+        // 技能关键词匹配（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 }, '技能匹配，下一轮注入');
                 }
             }
@@ -406,14 +499,50 @@ export class Agent extends TypedEventEmitter {
                 logger.warn({ err }, '技能匹配失败');
             }
         }
+        // ADR-015: manual 模式跳过所有自动归档（profile + insight），
+        // 需用户手动调用 archiveProfileFacts/archiveInsight 触发。
+        // 角色匹配/技能匹配/AutoConfigRefiner 属"配置学习"行为，非归档，每轮都执行。
+        const skipAutoArchive = this.#config.archiveMode === 'manual';
+        if (skipAutoArchive) {
+            logger.debug({ mode: 'manual' }, '归档模式为 manual，跳过自动归档');
+        }
+        // 用户画像实时归档（语义解析在 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 }, '用户画像归档初始化失败');
+            }
+        }
         // 输入分类 → Insight 提取（委托给 InsightExtractor）
-        if (this.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).catch((err) => {
+                    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 提取失败');
-                        return null;
                     });
                     this.requireNonNull(this.history, 'history').registerPendingArchive(p);
                 }
@@ -422,10 +551,10 @@ export class Agent extends TypedEventEmitter {
                 logger.warn({ err }, 'Insight 提取初始化失败');
             }
         }
-        // V-201: AutoConfigRefiner（模式 3：Agent 智能总结）
+        // AutoConfigRefiner（模式 3：Agent 智能总结）
         if (this.autoConfigRefiner) {
             try {
-                // FD-22: 注册到 pendingArchives，确保 close() 时等待后台分析完成，避免写入已关闭的存储
+                // 注册到 pendingArchives，确保 close() 时等待后台分析完成，避免写入已关闭的存储
                 const analyzePromise = this.autoConfigRefiner.analyze(input, assistantContent).catch((err) => {
                     logger.warn({ err }, 'AutoConfigRefiner 分析失败');
                 });
@@ -466,7 +595,7 @@ export class Agent extends TypedEventEmitter {
      */
     async switchProject(nameOrPath) {
         this.assertInitialized('switchProject', ['projectManager', 'provider']);
-        // FD-21: 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
+        // 对话进行中切换项目会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
         if (this._chatBusy) {
             throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换项目', [
                 '等待上一轮 chat() 的 AsyncGenerator 耗尽',
@@ -482,11 +611,11 @@ export class Agent extends TypedEventEmitter {
         const projectPath = target ? target.path : nameOrPath;
         const projectName = target ? target.name : basename(nameOrPath);
         const newPctx = await pm.initProject(projectPath, projectName, this.#config.configDir);
-        // A-003: 记录源项目路径（用于事件），切换前 pctx 可能不存在（首次初始化）
+        // 记录源项目路径（用于事件），切换前 pctx 可能不存在（首次初始化）
         const fromProjectPath = this.pctx?.projectPath ?? null;
         this.pctx = newPctx;
         await this.rebuildComponentsWithCurrentCtx();
-        // A-003: 发射项目切换事件（供宿主 UI 刷新项目相关界面）
+        // 发射项目切换事件（供宿主 UI 刷新项目相关界面）
         this.emit('projectSwitched', {
             from: fromProjectPath,
             to: projectPath,
@@ -524,20 +653,18 @@ export class Agent extends TypedEventEmitter {
         this.memoryInspector = result.memoryInspector;
         this.autoConfigRefiner = result.autoConfigRefiner;
         this.workProjection = result.workProjection;
-        // V-101：注入 VectorStore 到 MemoryInspector，启用混合搜索
+        this.sessionArchiver = result.sessionArchiver;
+        // 绑定冲突检测回调，InsightExtractor 检测到 contradicts 时 emit('conflictDetected')
+        // 与 bindGetRecentHistory 同模式：解决 Agent 晚于 InsightExtractor 创建的时序循环依赖
+        this.insightExtractor.bindOnConflict((info) => {
+            this.emit('conflictDetected', info);
+        });
+        // 注入 VectorStore 到 MemoryInspector，启用混合搜索
         if (this.memoryInspector && this.#config.vectorStore) {
             this.memoryInspector.setVectorStore(this.#config.vectorStore);
         }
-        // 创建会话管理器（通过回调访问当前组件，支持 rebuildComponents 后自动获取最新引用）
-        // 事件转发桥接：SessionManager 使用宽类型 (string, Record<string,unknown>)，
-        // Agent 内部桥接到 TypedEventEmitter 的强类型 emit
-        // 运行时校验事件名是否在 AgentEventMap 中，避免不安全的类型断言
-        const forwardEvent = (event, data) => {
-            if (AGENT_EVENT_NAMES.has(event)) {
-                this.emit(event, data);
-            }
-        };
-        this._sessionManager = new SessionManager(() => this.requireNonNull(this.history, 'history'), () => this.requireNonNull(this.loop, 'loop'), this.#config.sessionStore, () => this._chatBusy, forwardEvent);
+        // 创建会话管理器（提取 createSessionManager 辅助方法，消除重复）
+        this._sessionManager = this.createSessionManager();
     }
     /**
      * 用当前 pctx 重建 history / loop
@@ -546,17 +673,37 @@ export class Agent extends TypedEventEmitter {
         if (!this.pctx)
             return;
         await this.assembleComponents(this.pctx);
-        // 重建会话管理器：assembleComponents 创建了新的 history/loop 实例
-        // 事件转发桥接（同 assembleComponents 中的逻辑，含运行时校验）
+        // 重建会话管理器：assembleComponents 创建了新的 history/loop 实例（复用 createSessionManager）
+        this._sessionManager = this.createSessionManager();
+    }
+    /**
+     * 创建会话管理器（提取重复的 forwardEvent + SessionManager 构造逻辑）
+     *
+     * assembleComponents 和 rebuildComponentsWithCurrentCtx 共享同一套构造逻辑：
+     * - 通过回调访问当前组件（支持 rebuild 后自动获取最新引用）
+     * - 事件转发桥接：SessionManager 使用宽类型 (string, Record<string,unknown>)，
+     *   Agent 内部桥接到 TypedEventEmitter 的强类型 emit
+     * - 运行时校验事件名是否在 AgentEventMap 中，避免不安全的类型断言
+     *
+     * @returns 新的 SessionManager 实例
+     */
+    createSessionManager() {
         const forwardEvent = (event, data) => {
             if (AGENT_EVENT_NAMES.has(event)) {
                 this.emit(event, data);
             }
         };
-        this._sessionManager = new SessionManager(() => this.requireNonNull(this.history, 'history'), () => this.requireNonNull(this.loop, 'loop'), this.#config.sessionStore, () => this._chatBusy, forwardEvent);
+        return new SessionManager(() => this.requireNonNull(this.history, 'history'), () => this.requireNonNull(this.loop, 'loop'), this.#config.sessionStore, () => this._chatBusy, forwardEvent);
     }
     // ─── Provider 管理 ────────────────────────────────────
     setProvider(provider) {
+        // 对话进行中切换 Provider 会导致同一 processUserInput 循环内前后两次 LLM 调用命中不同 Provider
+        // （模型上下文窗口假设不一致 → 可能导致上下文截断逻辑误判或 tool_call 格式不兼容）
+        if (this._chatBusy) {
+            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换 Provider', [
+                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
+            ]);
+        }
         this.#provider = provider;
         if (this.loop) {
             this.loop.setProvider(provider);
@@ -564,13 +711,145 @@ export class Agent extends TypedEventEmitter {
         logger.info({ provider: this.#provider.name }, 'Provider 已切换');
     }
     setBackgroundProvider(provider) {
+        // 与 setProvider 一致，对话进行中禁止切换后台 Provider
+        if (this._chatBusy) {
+            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换后台 Provider', [
+                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
+            ]);
+        }
         this.#backgroundProvider = provider;
-        // V-201: 同步更新 AutoConfigRefiner 的后台 Provider
+        // 同步更新 AutoConfigRefiner 的后台 Provider
         if (this.autoConfigRefiner) {
             this.autoConfigRefiner.setBackgroundProvider(provider);
         }
         logger.info({ hasBackground: !!provider }, '后台 Provider 已切换');
     }
+    // ─── 归档模式管理（ADR-015） ───────────────────────────
+    /**
+     * 运行时切换归档模式
+     *
+     * 与 setProvider 一致，对话进行中禁止切换（避免本轮 postProcess 行为不一致）。
+     *
+     * @param mode 目标模式
+     */
+    setArchiveMode(mode) {
+        if (this._chatBusy) {
+            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再切换归档模式', [
+                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
+            ]);
+        }
+        const prev = this.#config.archiveMode;
+        if (prev === mode)
+            return; // 幂等：无变更直接返回
+        this.#config.archiveMode = mode;
+        logger.info({ from: prev, to: mode }, '归档模式已切换');
+    }
+    /**
+     * 查询当前归档模式
+     *
+     * 宿主 UI（如设置面板）可据此同步显示当前模式。
+     */
+    getArchiveMode() {
+        return this.#config.archiveMode;
+    }
+    /**
+     * 手动触发 profile facts 归档（manual 模式下使用）
+     *
+     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
+     * full / insights-only 模式下也可调用（会重复归档，但不推荐）。
+     *
+     * 归档逻辑已委托给 ArchiveCoordinator
+     *
+     * @param input 本轮用户输入
+     * @returns 写入/更新的 UserProfileEntry 列表
+     */
+    async archiveProfileFacts(input) {
+        this.assertInitialized('archiveProfileFacts');
+        return this.archiveCoordinator.archiveProfileFacts(input);
+    }
+    /**
+     * 手动触发 insight 提取（manual 模式下使用）
+     *
+     * manual 模式下 postProcess 跳过自动归档，用户需通过此 API 主动归档。
+     * 内部仍走 classify 判断（避免无价值输入浪费 LLM 调用）。
+     *
+     * 归档逻辑已委托给 ArchiveCoordinator
+     *
+     * @param input 本轮用户输入
+     * @param assistantContent 本轮助手回复内容
+     * @returns 写入/更新的 Memory 列表
+     */
+    async archiveInsight(input, assistantContent) {
+        this.assertInitialized('archiveInsight');
+        return this.archiveCoordinator.archiveInsight(input, assistantContent);
+    }
+    /**
+     * 手动归档会话内容（content 类记忆）
+     *
+     * 适用于 `insights-only` / `manual` 模式下用户手动触发会话内容归档。
+     * `full` 模式下由宿主在会话切换前自动调用，无需用户干预。
+     *
+     * 归档逻辑已委托给 ArchiveCoordinator
+     *
+     * @param date 会话日期 YYYY-MM-DD
+     * @param session 会话标识（不含日期前缀）
+     * @returns 归档结果（memories 可能为空，表示无归档价值或 LLM 失败）
+     */
+    async archiveSessionContent(date, session) {
+        this.assertInitialized('archiveSessionContent');
+        return this.archiveCoordinator.archiveSessionContent(date, session);
+    }
+    // ─── 配置重载（事件驱动） ───────────────────────
+    /**
+     * 重载配置类记忆：从 configDir 重新扫描指定 source 的配置文件并更新内存缓存 + SQLite 索引
+     *
+     * 解决方案：installSkill 写入文件后或 confirmConfigSuggestion 写入配置文件后，
+     * 调用此方法使当前会话立即生效，无需重启 Agent。
+     *
+     * 支持的 source：
+     * - 'skill' → SkillManager.reload() 清空缓存重新扫描 skills/ 目录
+     * - 'persona' → PersonaManager.reload() 清空缓存重新扫描 personas/ 目录（保持激活角色）
+     * - 'rule' → 无操作（rule 类型已由 ConfigManager.addRule() 即时注入 system prompt）
+     * - 'guardrail' → 抛错（guardrail 是 AgentLoop 的 readonly 数组，需 rebuildComponents 才能重载）
+     * - undefined → 重载 skill + persona（全量重载，不含 guardrail）
+     *
+     * @param source 配置类型，缺省时重载全部可热更新的配置
+     * @returns 重载结果统计
+     */
+    async reloadConfig(source) {
+        this.assertInitialized('reloadConfig');
+        if (this._chatBusy) {
+            throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重载配置', [
+                '等待上一轮 chat() 的 AsyncGenerator 耗尽',
+            ]);
+        }
+        // guardrail 需重建 AgentLoop，不属于热重载范畴
+        if (source === 'guardrail') {
+            throw configError('guardrail 不支持热重载', 'guardrail 规则是 AgentLoop 的 readonly 数组，需调用 rebuildComponents() 重建', ['使用 rebuildComponents() 重建组件（代价较高）']);
+        }
+        // rule 类型已由 ConfigManager.addRule() 即时注入，无需重载
+        if (source === 'rule') {
+            logger.info('rule 类型已由 addRule() 即时注入，reloadConfig 跳过');
+            return { skill: 0, persona: 0 };
+        }
+        const result = { skill: 0, persona: 0 };
+        // 按需重载：source 缺省时全量重载，否则只重载指定类型
+        const shouldReloadSkill = !source || source === 'skill';
+        const shouldReloadPersona = !source || source === 'persona';
+        if (shouldReloadSkill && this.skillManager) {
+            result.skill = await this.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);
+            }
+        }
+        logger.info({ source, ...result }, '配置已热重载');
+        return result;
+    }
     // ─── 组件访问 ─────────────────────────────────────────
     /**
      * 重建内部组件（history / loop / managers）
@@ -579,7 +858,7 @@ export class Agent extends TypedEventEmitter {
      * 仅在宿主项目需要强制刷新组件时使用（如热更新配置后）。
      */
     async rebuildComponents() {
-        // FD-21: 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
+        // 对话进行中重建组件会导致 loop/history 引用被替换，工作记忆与持久化状态不一致
         if (this._chatBusy) {
             throw configError('对话繁忙', '上一轮对话尚未完成，请等待其结束后再重建组件', [
                 '等待上一轮 chat() 的 AsyncGenerator 耗尽',
@@ -628,45 +907,22 @@ export class Agent extends TypedEventEmitter {
         return value;
     }
     // ─── 记忆生命周期 ───────────────────────────────────────
-    /**
-     * 对 insight/profile/work-projection 记忆执行 score 衰减
-     *
-     * 长期未访问的记忆 score 逐渐降低，体现"自然遗忘"
-     * 不影响 persona/rule/skill（这些是配置型记忆，不应衰减）
-     *
-     * 衰减逻辑委派给 IMemoryStorage.decayScores()，
-     * 宿主（SqliteStorage）可用一条 SQL UPDATE 批量完成，避免 O(n) 全量加载。
-     */
-    runMemoryDecay() {
-        if (!this.pctx)
-            return;
-        // R-103 衰减 Span：记录衰减执行过程，补全衰减可观测性缺口
-        const decaySpan = this.#config.tracer?.startSpan(TRACE_SPANS.DECAY) ?? NOOP_TRACER.startSpan(TRACE_SPANS.DECAY);
-        try {
-            const sources = [SOURCE_LABELS.INSIGHT, SOURCE_LABELS.PROFILE, SOURCE_LABELS.WORK_PROJECTION];
-            const decayedCount = this.pctx.index.decayScores(sources, new Date());
-            logger.debug({ decayedCount }, '记忆衰减完成');
-            // R-103 衰减指标统计：累计执行次数和衰减记忆数
-            this.metricDecayRunCount++;
-            this.metricTotalDecayedCount += decayedCount;
-            this.metricLastDecayAt = new Date().toISOString();
-            decaySpan.setAttribute('decayedCount', decayedCount);
-            decaySpan.setAttribute('totalRuns', this.metricDecayRunCount);
-            this.emit('decayCompleted', { decayedCount });
-        }
-        catch (err) {
-            logger.warn({ err }, '记忆衰减异常，跳过本轮');
-            decaySpan.recordException(toError(err));
-        }
-        finally {
-            decaySpan.end();
-        }
-    }
+    // ─── runMemoryDecay 已迁移至 MemoryDecayScheduler.runOnce ─────
     // ─── 关闭 ─────────────────────────────────────────────
     /**
      * 关闭 Agent，释放 SQLite 连接等资源
      */
     async close() {
+        // 递增 token，使任何进行中的 chat() generator 的 finally 块
+        // 检测到 token 变化后跳过资源清理（close 已接管清理职责）
+        this._chatLockToken++;
+        // 清理 MemoryDecayScheduler（含定时器和 storage 引用）
+        if (this.memoryDecayScheduler) {
+            this.memoryDecayScheduler.stop();
+            this.memoryDecayScheduler = null;
+        }
+        // 清理 ArchiveCoordinator（无定时器，只需释放引用）
+        this.archiveCoordinator = null;
         // 清理定时器
         if (this.decayTimer) {
             clearSafeInterval(this.decayTimer);
@@ -680,13 +936,13 @@ export class Agent extends TypedEventEmitter {
             this.chatAbortController.abort();
             this.chatAbortController = null;
         }
-        // P2-1 清理 PersonaManager 的角色切换防抖锁计时器，防止关闭后回调触发
+        // 清理 PersonaManager 的角色切换防抖锁计时器，防止关闭后回调触发
         if (this.personaManager) {
             this.personaManager.close();
         }
         this.removeAllListeners();
         if (this.history) {
-            await this.history.awaitPendingArchives(5000);
+            await this.history.awaitPendingArchives(AGENT_CONSTANTS.SHUTDOWN_ARCHIVE_TIMEOUT_MS);
         }
         if (this.projectManager) {
             await this.projectManager.shutdown();
@@ -702,7 +958,19 @@ export class Agent extends TypedEventEmitter {
         this.configManager = null;
         this.memoryInspector = null;
         this.autoConfigRefiner = null;
+        this.sessionArchiver = 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() {
@@ -737,9 +1005,9 @@ export class Agent extends TypedEventEmitter {
     get lastInteractionAt() {
         return this._lastInteractionAt;
     }
-    // ─── R-103 运行时指标 ────────────────────────────────
+    // ─── 运行时指标 ────────────────────────────────
     /**
-     * 获取 Agent 运行时指标快照（R-103 可观测性增强）
+     * 获取 Agent 运行时指标快照（可观测性增强）
      *
      * 聚合 AgentLoop 指标（LLM 调用、记忆召回、工具调用、上下文管理）
      * 与 Agent 层指标（记忆衰减），返回完整的 AgentMetrics 快照。
@@ -754,6 +1022,12 @@ export class Agent extends TypedEventEmitter {
      * @returns AgentMetrics 完整快照（含衰减指标）
      */
     getMetrics() {
+        // 衰减指标从 MemoryDecayScheduler 读取
+        const decayMetrics = this.memoryDecayScheduler?.getMetrics() ?? {
+            runCount: 0,
+            totalDecayedCount: 0,
+            lastRunAt: null,
+        };
         // 未初始化时返回全零指标，避免调用方需要判空
         if (!this.loop) {
             return {
@@ -761,22 +1035,14 @@ export class Agent extends TypedEventEmitter {
                 recall: { totalCount: 0, hitCount: 0, hitRate: 0 },
                 tools: { callCount: 0, failureCount: 0 },
                 context: { truncationCount: 0, messageCount: 0, estimatedTokens: 0 },
-                decay: {
-                    runCount: this.metricDecayRunCount,
-                    totalDecayedCount: this.metricTotalDecayedCount,
-                    lastRunAt: this.metricLastDecayAt,
-                },
+                decay: decayMetrics,
             };
         }
         // 获取 AgentLoop 指标快照，填充衰减字段
         const loopMetrics = this.loop.getMetrics();
         return {
             ...loopMetrics,
-            decay: {
-                runCount: this.metricDecayRunCount,
-                totalDecayedCount: this.metricTotalDecayedCount,
-                lastRunAt: this.metricLastDecayAt,
-            },
+            decay: decayMetrics,
         };
     }
     // ─── Manager 暴露（激进拆分：调用方直接操作 Manager）──
@@ -885,9 +1151,5 @@ export class Agent extends TypedEventEmitter {
     get sessionManager() {
         return this._sessionManager;
     }
-    /** 记忆存储（宿主可直接调用 CRUD，如 delete/upsert） */
-    get storage() {
-        return this.#config.storage ?? null;
-    }
 }
 //# sourceMappingURL=agent.js.map