@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/managers/chatLockManager.d.ts

@@ -1,115 +1,47 @@
 /**
- * ChatLockManager — chat() 并发锁管理器
+ * ChatLockManager — chat() 并发锁管理器：并发锁 + token 校验 + 超时保护 + 外部 signal 合并。
  *
- * 职责：
- *   - chat() 并发锁（防止多轮 chat 同时执行）
- *   - token 校验（防止 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者资源）
- *   - 超时保护（LLM 卡死时中断 generator + 释放锁）
- *   - 外部 signal 合并（外部 abort 时触发内部 abort）
- *
- * 从 agent.ts 提取（AUDIT-1-1，ADR-017 架构层先行原则首次实践）
- *
- * 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 实例内）
+ * race condition 防护（token 机制）：原锁仅布尔 _chatBusy，超时回调与 finally 块无差别清理，
+ * 可能误清新调用者的资源（T=0 A 获取→超时释放→B 获取→A finally 误清 B）。
+ * 故获取锁时递增 token，超时回调/finally 均校验 token 是否仍是当前持有者，不匹配则跳过清理。
  */
 /**
- * chat() 并发锁管理器
- *
- * 使用方式：
- *   const mgr = new ChatLockManager();
- *   const { token, internalAbort } = mgr.acquire(180_000);
- *   const cleanup = mgr.attachExternalSignal(externalSignal, internalAbort);
- *   try {
- *     // ... 使用 internalAbort.signal 传递给 generator ...
- *   } finally {
- *     mgr.release(token);
- *     cleanup();
- *   }
- *
- * 强制释放（宿主兜底）：
- *   mgr.forceRelease();
- *
- * 销毁（Agent.close 时）：
- *   mgr.dispose();
+ * chat() 并发锁管理器。acquire 返回 token+internalAbort，finally 中 release(token)。
+ * forceRelease 供宿主无进展超时兜底；dispose 供 Agent.close。
  */
 export declare class ChatLockManager {
-    /** chat() 是否正在执行（并发锁） */
+    /** 并发锁标志 */
     private _chatBusy;
-    /**
-     * chat() 锁持有者 token（race condition 防护）
-     *
-     * 获取锁时递增，超时回调和 finally 块据此判断是否仍是当前持有者。
-     * 不匹配时跳过清理，避免误清新调用者的资源。
-     */
+    /** 锁持有者 token（race condition 防护，校验当前持有者避免误清新调用者资源） */
     private _chatLockToken;
-    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
+    /** 锁超时计时器（防 LLM 卡死时锁永久持有） */
     private chatLockTimer;
-    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
+    /** 内部 AbortController（超时时中断 generator） */
     private chatAbortController;
     /** 当前是否持有锁 */
     get isBusy(): boolean;
     /**
-     * 获取锁，返回 token + 内部 AbortController
-     *
-     * @param timeoutMs 锁超时时间（LLM 卡死保护）
-     * @param onTimeout 超时回调（用于日志记录等）
-     * @returns token（用于 finally 校验）+ internalAbort（用于传递给 loop.processUserInput）
+     * 获取锁，返回 token（finally 校验）+ internalAbort（传给 loop.processUserInput）。
+     * 超时保护：锁超时后自动释放锁（允许新对话进入），但不中断生成流——
+     * LLM 无进展由 provider 层请求级/事件停滞超时兜底，锁不对整次对话时长设硬上限。
      */
     acquire(timeoutMs: number, onTimeout?: () => void): {
         token: number;
         internalAbort: AbortController;
     };
-    /**
-     * 合并外部 signal：外部 abort 时触发内部 abort
-     *
-     * addEventListener 对已 aborted 的 signal 不触发回调，
-     * 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程。
-     *
-     * @returns 清理函数（finally 块中调用 removeEventListener）
-     */
+    /** 合并外部 signal：外部 abort 时触发内部 abort；返回 cleanup。addEventListener 对已 aborted 的 signal 不触发，需手动检查。 */
     attachExternalSignal(externalSignal: AbortSignal | undefined, internalAbort: AbortController): () => void;
-    /**
-     * finally 块清理（token 校验后）
-     *
-     * 仅当本调用仍是当前锁持有者时才清理资源。
-     * 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态。
-     */
+    /** finally 清理（token 校验）：仅当前持有者清理，token 已变则跳过避免误清新调用者状态 */
     release(token: number): void;
     /**
-     * 强制释放对话锁（宿主无进展超时兜底）
-     *
-     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
-     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
-     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
-     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
-     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
-     *
-     * 安全机制：
-     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
-     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
-     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
-     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
-     *     但其 finally 块的 token 校验会阻止它影响新调用
-     *
-     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
+     * 强制释放对话锁（宿主无进展超时兜底）。幂等：_chatBusy 已 false 时 no-op。
+     * generator 可能卡在不可响应的 await 点，递增 token 让原 finally 跳过清理；
+     * abort controller 让响应 signal 的 await 点退出。原 generator 后台残留也无法影响新调用。
      */
     forceRelease(): void;
     /**
-     * 销毁管理器（Agent.close 时调用）
-     *
-     * 与 forceRelease() 的区别：不记录 warn 日志（close 是正常生命周期，非异常场景）。
-     * 递增 token 使任何进行中的 chat() generator 的 finally 块检测到 token 变化后
-     * 跳过资源清理（close 已接管清理职责）。
+     * 销毁管理器（Agent.close 时调用）。与 forceRelease 同行为但不记 warn 日志
+     * （close 为正常生命周期）。递增 token 使进行中 generator 的 finally 跳过清理。
      */
     dispose(): void;
 }

package/dist/agent/managers/chatLockManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chatLockManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAe;IAC1B,yBAAyB;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAa;IACnC,gCAAgC;IAChC,OAAO,CAAC,aAAa,CAA8C;IACnE,sDAAsD;IACtD,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,cAAc;IACd,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;;OAMG;IACH,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,IAAI,GACrB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,eAAe,CAAA;KAAE;IA8BpD;;;;;;;OAOG;IACH,oBAAoB,CAClB,cAAc,EAAE,WAAW,GAAG,SAAS,EACvC,aAAa,EAAE,eAAe,GAC7B,MAAM,IAAI;IAYb;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,IAAI,IAAI;IAkBpB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAchB"}
+{"version":3,"file":"chatLockManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;GAGG;AACH,qBAAa,eAAe;IAC1B,YAAY;IACZ,OAAO,CAAC,SAAS,CAAS;IAC1B,sDAAsD;IACtD,OAAO,CAAC,cAAc,CAAa;IACnC,6BAA6B;IAC7B,OAAO,CAAC,aAAa,CAA8C;IACnE,0CAA0C;IAC1C,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,cAAc;IACd,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,IAAI,GACrB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,eAAe,CAAA;KAAE;IA2BpD,kGAAkG;IAClG,oBAAoB,CAClB,cAAc,EAAE,WAAW,GAAG,SAAS,EACvC,aAAa,EAAE,eAAe,GAC7B,MAAM,IAAI;IAWb,0DAA0D;IAC1D,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY5B;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAgBpB;;;OAGG;IACH,OAAO,IAAI,IAAI;CAahB"}

package/dist/agent/managers/chatLockManager.js

@@ -1,91 +1,51 @@
 /**
- * ChatLockManager — chat() 并发锁管理器
+ * ChatLockManager — chat() 并发锁管理器：并发锁 + token 校验 + 超时保护 + 外部 signal 合并。
  *
- * 职责：
- *   - chat() 并发锁（防止多轮 chat 同时执行）
- *   - token 校验（防止 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者资源）
- *   - 超时保护（LLM 卡死时中断 generator + 释放锁）
- *   - 外部 signal 合并（外部 abort 时触发内部 abort）
- *
- * 从 agent.ts 提取（AUDIT-1-1，ADR-017 架构层先行原则首次实践）
- *
- * 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 实例内）
+ * race condition 防护（token 机制）：原锁仅布尔 _chatBusy，超时回调与 finally 块无差别清理，
+ * 可能误清新调用者的资源（T=0 A 获取→超时释放→B 获取→A finally 误清 B）。
+ * 故获取锁时递增 token，超时回调/finally 均校验 token 是否仍是当前持有者，不匹配则跳过清理。
  */
 import { clearSafeTimeout, safeSetTimeout } from '../../utils/safeTimer.js';
 import { logger } from '../../logging/logger.js';
 /**
- * chat() 并发锁管理器
- *
- * 使用方式：
- *   const mgr = new ChatLockManager();
- *   const { token, internalAbort } = mgr.acquire(180_000);
- *   const cleanup = mgr.attachExternalSignal(externalSignal, internalAbort);
- *   try {
- *     // ... 使用 internalAbort.signal 传递给 generator ...
- *   } finally {
- *     mgr.release(token);
- *     cleanup();
- *   }
- *
- * 强制释放（宿主兜底）：
- *   mgr.forceRelease();
- *
- * 销毁（Agent.close 时）：
- *   mgr.dispose();
+ * chat() 并发锁管理器。acquire 返回 token+internalAbort，finally 中 release(token)。
+ * forceRelease 供宿主无进展超时兜底；dispose 供 Agent.close。
  */
 export class ChatLockManager {
-    /** chat() 是否正在执行（并发锁） */
+    /** 并发锁标志 */
     _chatBusy = false;
-    /**
-     * chat() 锁持有者 token（race condition 防护）
-     *
-     * 获取锁时递增，超时回调和 finally 块据此判断是否仍是当前持有者。
-     * 不匹配时跳过清理，避免误清新调用者的资源。
-     */
+    /** 锁持有者 token（race condition 防护，校验当前持有者避免误清新调用者资源） */
     _chatLockToken = 0;
-    /** 聊天锁超时计时器（防止 LLM 卡死时锁永久持有） */
+    /** 锁超时计时器（防 LLM 卡死时锁永久持有） */
     chatLockTimer = null;
-    /** chat() 内部 AbortController（超时时中断 generator，防止并发） */
+    /** 内部 AbortController（超时时中断 generator） */
     chatAbortController = null;
     /** 当前是否持有锁 */
     get isBusy() {
         return this._chatBusy;
     }
     /**
-     * 获取锁，返回 token + 内部 AbortController
-     *
-     * @param timeoutMs 锁超时时间（LLM 卡死保护）
-     * @param onTimeout 超时回调（用于日志记录等）
-     * @returns token（用于 finally 校验）+ internalAbort（用于传递给 loop.processUserInput）
+     * 获取锁，返回 token（finally 校验）+ internalAbort（传给 loop.processUserInput）。
+     * 超时保护：锁超时后自动释放锁（允许新对话进入），但不中断生成流——
+     * LLM 无进展由 provider 层请求级/事件停滞超时兜底，锁不对整次对话时长设硬上限。
      */
     acquire(timeoutMs, onTimeout) {
         this._chatBusy = true;
-        // 分配本调用的 token，超时回调和 finally 块据此判断是否仍是当前持有者
-        // 避免 race condition：超时释放后新调用获取锁，旧 finally 误清新调用者的资源
+        // 分配本调用 token，超时/finally 据此判断是否仍是持有者，避免误清新调用资源
         const token = ++this._chatLockToken;
-        // 内部 AbortController，超时时中断 generator 而非仅释放锁
+        // 中断信号（用户 stop / 插话 / 宿主 forceRelease 会 abort 它；锁自身超时不 abort）
         const internalAbort = new AbortController();
         this.chatAbortController = internalAbort;
-        // 超时保护：LLM 卡死时中断 generator + 释放锁，防止并发
-        // 超时回调校验 token 后才清理，避免误清新调用者的资源
         this.chatLockTimer = safeSetTimeout(() => {
-            // 令牌不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
+            // token 不匹配：锁已被新调用者获取（或本调用已正常退出），跳过清理
             if (this._chatLockToken !== token) {
                 return;
             }
-            logger.warn({ timeoutMs }, 'chat() 锁超时，中断 generator 并释放锁');
-            internalAbort.abort();
+            logger.warn({ timeoutMs }, 'chat() 锁超时，自动释放锁（不中断生成流）');
+            // 仅释放锁（自增 token 令旧 generator 的 finally release 跳过清理，避免误清新调用），
+            // 不 abort 生成流——LLM 无进展/停滞由 provider 层超时兜底（请求级 120s + SSE 事件停滞 120s），
+            // 锁不再对「整次对话时长」设硬上限，慢但正常的长时间对话不被误杀。
+            this._chatLockToken++;
             this._chatBusy = false;
             this.chatLockTimer = null;
             this.chatAbortController = null;
@@ -93,32 +53,19 @@ export class ChatLockManager {
         }, timeoutMs);
         return { token, internalAbort };
     }
-    /**
-     * 合并外部 signal：外部 abort 时触发内部 abort
-     *
-     * addEventListener 对已 aborted 的 signal 不触发回调，
-     * 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程。
-     *
-     * @returns 清理函数（finally 块中调用 removeEventListener）
-     */
+    /** 合并外部 signal：外部 abort 时触发内部 abort；返回 cleanup。addEventListener 对已 aborted 的 signal 不触发，需手动检查。 */
     attachExternalSignal(externalSignal, internalAbort) {
         if (!externalSignal)
             return () => { };
         const onExternalAbort = () => internalAbort.abort();
         externalSignal.addEventListener('abort', onExternalAbort, { once: true });
-        // addEventListener 对已 aborted 的 signal 不触发回调
-        // 需手动检查并触发 internalAbort，否则外部已取消的请求仍会进入主流程
+        // 外部 signal 已 aborted 时不触发回调，手动触发一次，避免外部已取消请求仍进入主流程
         if (externalSignal.aborted) {
             internalAbort.abort();
         }
         return () => externalSignal.removeEventListener('abort', onExternalAbort);
     }
-    /**
-     * finally 块清理（token 校验后）
-     *
-     * 仅当本调用仍是当前锁持有者时才清理资源。
-     * 若 token 已变（超时释放后被新调用者获取），跳过清理避免误清新调用者的状态。
-     */
+    /** finally 清理（token 校验）：仅当前持有者清理，token 已变则跳过避免误清新调用者状态 */
     release(token) {
         if (this._chatLockToken !== token) {
             return;
@@ -131,34 +78,19 @@ export class ChatLockManager {
         }
     }
     /**
-     * 强制释放对话锁（宿主无进展超时兜底）
-     *
-     * 场景：宿主主进程"无进展超时"兜底后，generator 可能仍卡在不可中断的 await 点
-     *   （executeToolCalls 和 generateContextSummary 已覆盖 signal 响应，但其他
-     *   第三方库或未来新增的 await 点仍可能不响应 signal）。
-     *   此时 _chatBusy 锁未释放，用户再发消息会被 chat() 的竞态保护拒绝，
-     *   表现为"UI 能操作但发不出消息"，需等到 3 分钟锁超时才能恢复。
-     *
-     * 安全机制：
-     *   - 递增 _chatLockToken，让原 chat() 的 finally 块检测到 token 不匹配后
-     *     跳过资源清理（避免误清新调用者的 _chatBusy/chatAbortController）
-     *   - abort chatAbortController，让响应 signal 的 await 点（如 fetch）退出
-     *   - 原 generator 仍可能在后台运行（无法真正中断不响应 signal 的 await），
-     *     但其 finally 块的 token 校验会阻止它影响新调用
-     *
-     * 幂等性：_chatBusy 已 false 时 no-op（多次调用安全）
+     * 强制释放对话锁（宿主无进展超时兜底）。幂等：_chatBusy 已 false 时 no-op。
+     * generator 可能卡在不可响应的 await 点，递增 token 让原 finally 跳过清理；
+     * abort controller 让响应 signal 的 await 点退出。原 generator 后台残留也无法影响新调用。
      */
     forceRelease() {
         if (!this._chatBusy)
             return;
-        // 递增 token 让原 chat() 的 finally 块跳过清理（避免误清新调用者的资源）
+        // 递增 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;
@@ -167,15 +99,11 @@ export class ChatLockManager {
         logger.warn('对话锁被强制释放（宿主无进展超时兜底）');
     }
     /**
-     * 销毁管理器（Agent.close 时调用）
-     *
-     * 与 forceRelease() 的区别：不记录 warn 日志（close 是正常生命周期，非异常场景）。
-     * 递增 token 使任何进行中的 chat() generator 的 finally 块检测到 token 变化后
-     * 跳过资源清理（close 已接管清理职责）。
+     * 销毁管理器（Agent.close 时调用）。与 forceRelease 同行为但不记 warn 日志
+     * （close 为正常生命周期）。递增 token 使进行中 generator 的 finally 跳过清理。
      */
     dispose() {
-        // 递增 token，使任何进行中的 chat() generator 的 finally 块
-        // 检测到 token 变化后跳过资源清理（close 已接管清理职责）
+        // 递增 token，让进行中 chat() finally 跳过资源清理（close 已接管清理职责）
         this._chatLockToken++;
         if (this.chatAbortController) {
             this.chatAbortController.abort();

package/dist/agent/managers/chatLockManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"chatLockManager.js","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chatLockManager.js","sourceRoot":"","sources":["../../../src/agent/managers/chatLockManager.ts"],"names":[],"mappings":"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"}

package/dist/agent/managers/dedupManager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 记忆治理管理者（从 MemoryInspector 拆分，专责异步 LLM 语义去重）。
+ * 职责分离：MemoryInspector 纯存储读写，DedupManager 异步 LLM 治理。
+ * 设计原则：未注入 provider 时静默降级返回报告不抛错；不物理删除仅软删重复方保留可恢复性；不阻塞主对话热路径。
+ */
+import type { Memory } from '../../memory/types.js';
+import type { IMemoryStorage } from '../../memory/storageInterface.js';
+import type { LlmProvider } from '../../llm/provider.js';
+/** 名称高度相似的候选记忆对（待 LLM 判断语义等价性） */
+export interface DedupPair {
+    /** 记忆 A（保留候选） */
+    a: Memory;
+    /** 记忆 B（重复方，软删候选） */
+    b: Memory;
+    /** 名称归一化相似度（0-1，越小越相似） */
+    nameSimilarity: number;
+}
+/** LLM 对单对记忆的语义等价判断结果 */
+export interface DedupVerdict {
+    /** 是否语义等价（true → 软删重复方） */
+    isDuplicate: boolean;
+    /** 合并后的内容（isDuplicate=true 时提供，保留更完整信息） */
+    mergedContent?: string;
+    /** LLM 判断理由（便于审计调试） */
+    reason: string;
+}
+/** 降级记忆审计详情（供 UI 展示"为什么降级" + 合并后内容） */
+export interface DedupVerdictSummary {
+    /** 被降级记忆 ID（与 demotedIds 一一对应） */
+    demotedId: string;
+    /** LLM 判断理由（便于审计降级是否合理） */
+    reason: string;
+    /** 合并后完整内容（便于验证合并质量；缺失时渲染器负责截断展示） */
+    mergedContent?: string;
+}
+/** 语义去重报告（deduplicateMemories 返回值） */
+export interface DedupReport {
+    /** 扫描的候选记忆总数 */
+    scannedCount: number;
+    /** 发现的名称相似对数 */
+    pairCount: number;
+    /** LLM 判定为语义等价并执行降级的对数 */
+    deduplicatedCount: number;
+    /** 被降级记忆 ID 列表（未物理删除） */
+    demotedIds: string[];
+    /** 降级审计详情（与 demotedIds 一一对应） */
+    verdicts?: DedupVerdictSummary[];
+    /** 跳过原因（LLM 不可用 / 无候选对） */
+    skippedReason?: string;
+}
+/** 语义去重管理器：扫描名称高度相似的记忆对，LLM 判断语义等价性，降级低分记忆。assembler 组合根创建，由 Agent 透传调用。 */
+export declare class DedupManager {
+    private readonly index;
+    /** 去重完成回调（宿主据此发射事件通知用户） */
+    private readonly onCompleted?;
+    /** 后台 LLM Provider（可选，未注入时降级跳过） */
+    private readonly backgroundProvider;
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时去重空转，测试可显式注入） */
+    private readonly sources;
+    constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null, 
+    /** 去重完成回调（宿主据此发射事件通知用户） */
+    onCompleted?: ((report: DedupReport) => void) | undefined, sources?: readonly string[]);
+    /**
+     * 语义去重：加载候选（上限 50）→ 名称相似度筛选对（上限 10）→ LLM 判断语义等价 → 等价则软删重复方。
+     * 安全设计：不物理删除仅软删（可恢复）；LLM 失败降级不阻塞；provider 未注入静默返回 skippedReason。
+     */
+    deduplicateMemories(signal?: AbortSignal): Promise<DedupReport>;
+    /**
+     * 筛选名称高度相似的候选记忆对。判定：归一化 Levenshtein ≤0.3 或一方包含另一方。
+     * 已配对的记忆不再参与后续配对（避免三元组产生多对）；按相似度升序（越相似越优先）取前 10 对。
+     */
+    private findNameOverlapPairs;
+    /** 名称归一化相似度（0-1，越小越相似）。规则：包含关系=0；否则 Levenshtein 距离 / max(len)。 */
+    private static computeNameSimilarity;
+    /**
+     * 调用 LLM 判断单对记忆语义等价：结构化 JSON 输出（isDuplicate+mergedContent+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
+     */
+    private judgeDuplicate;
+    /** 软删重复记忆（不物理删除保留可恢复；合并内容由 keepMerged 单独写回 a）。重复方以 delete 进入回收站。 */
+    private demoteMemory;
+    /** 将合并内容写回保留方 a：保持 id/source/name/createdAt 不变，仅刷新 content + accessedAt */
+    private keepMerged;
+}
+//# sourceMappingURL=dedupManager.d.ts.map

package/dist/agent/managers/dedupManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupManager.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/dedupManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAyB9D,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,qBAAqB;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,0BAA0B;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yBAAyB;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,4EAA4E;AAC5E,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAT/B,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,KAAK,EAAE,cAAc,EACtC,kBAAkB,GAAE,WAAW,GAAG,IAAW;IAC7C,2BAA2B;IACV,WAAW,CAAC,GAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,aAAA,EAC5D,OAAO,GAAE,SAAS,MAAM,EAAuB;IAMjD;;;OAGG;IACG,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAmFrE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAgC5B,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAkBpC;;;OAGG;YACW,cAAc;IAoB5B,oEAAoE;IACpE,OAAO,CAAC,YAAY;IAIpB,2EAA2E;IAC3E,OAAO,CAAC,UAAU;CASnB"}