@zooique/memora 2.0.3 → 3.0.0

package/dist/agent/managers/llmJudgeHelper.js

@@ -1,41 +1,24 @@
 /**
- * LLM Judge 高阶辅助函数
- *
- * 抽象"流式累积 → parseLlmJson → 判 null → 抛 configError"三件套模式。
- * 用于 memoryInspector / memoryDecayScheduler / memoryAdvisor 三个 Manager 的 LLM 判断流程，
- * 消除 3 处重复模式（ADR-017 枝叶层 2 次提取原则）。
- *
- * 设计要点：
- *   - 流式累积：与 TextPolishManager / SessionArchiver 同模式
- *   - 统一异常：parseLlmJson 返回 null 时抛 configError（统一 MemoraError 体系，避免裸 throw Error）
- *   - 类型参数化：调用方传入期望的返回类型 T
+ * LLM Judge 高阶辅助函数：封装"流式累积 → parseLlmJson → 判 null → 抛 configError"三件套。
+ * 由 memoryInspector / memoryAdvisor 复用，消除重复。
+ * 统一异常：解析失败抛 configError（MemoraError 体系）；类型参数化，调用方指定返回类型 T。
  */
 import { parseLlmJson } from '../../utils/json.js';
 import { configError } from '../../utils/errors.js';
 import { accumulateStream } from '../../agent/managers/streamAccumulator.js';
 /**
- * 调用 LLM 流式累积响应并解析为 JSON 对象
- *
- * 三件套模式封装：
- *   1. 流式累积 LLM 响应（chunk.content 拼接）
- *   2. parseLlmJson 解析为对象 T（容错：剥离代码块、修复常见错误、正则兜底）
- *   3. 解析失败抛 configError（统一 MemoraError 体系，附带排查建议）
- *
- * @param provider LLM Provider 实例（通常为 backgroundProvider）
- * @param messages LLM 消息数组（system + user）
- * @param options 调用选项（maxTokens / timeoutMs / signal）
- * @param errorTitle 解析失败时抛出 configError 的标题（中文简短）
- * @returns 解析后的对象（类型由调用方指定）
+ * 调用 LLM 流式累积响应并解析为 JSON 对象 T。
+ * 流式累积 → parseLlmJson（容错剥离代码块/修复错误/正则兜底）→ 解析失败抛 configError。
  */
 export async function judgeWithLlm(provider, messages, options, errorTitle) {
-    // 流式累积（复用 accumulateStream 工具函数，消除重复模式）
+    // 流式累积 LLM 响应（复用 accumulateStream，消除重复）
     const llmResponse = await accumulateStream(provider, messages, {
         maxTokens: options.maxTokens,
         temperature: 0,
         timeoutMs: options.timeoutMs,
         signal: options.signal,
     });
-    // 解析 LLM 响应（JSON 格式），失败则抛 configError（统一 MemoraError 体系）
+    // 解析 JSON，失败抛 configError（统一 MemoraError 体系）
     const parsed = parseLlmJson(llmResponse.trim());
     if (!parsed) {
         throw configError(errorTitle, 'LLM 返回内容不是有效的 JSON（parseLlmJson 解析失败）', [

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

@@ -1 +1 @@
-{"version":3,"file":"llmJudgeHelper.js","sourceRoot":"","sources":["../../../src/agent/managers/llmJudgeHelper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAYzE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAqB,EACrB,QAAmB,EACnB,OAAwB,EACxB,UAAkB;IAElB,wCAAwC;IACxC,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE;QAC7D,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,WAAW,EAAE,CAAC;QACd,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,yDAAyD;IACzD,MAAM,MAAM,GAAG,YAAY,CAAI,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,WAAW,CACf,UAAU,EACV,uCAAuC,EACvC;YACE,+BAA+B;YAC/B,0BAA0B;YAC1B,yBAAyB;SAC1B,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"llmJudgeHelper.js","sourceRoot":"","sources":["../../../src/agent/managers/llmJudgeHelper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAYzE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAqB,EACrB,QAAmB,EACnB,OAAwB,EACxB,UAAkB;IAElB,wCAAwC;IACxC,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE;QAC7D,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,WAAW,EAAE,CAAC;QACd,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,6CAA6C;IAC7C,MAAM,MAAM,GAAG,YAAY,CAAI,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,WAAW,CAAC,UAAU,EAAE,uCAAuC,EAAE;YACrE,+BAA+B;YAC/B,0BAA0B;YAC1B,yBAAyB;SAC1B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,58 @@
+/**
+ * AgentLoop 运行时指标纯状态容器
+ *
+ * 零 AgentLoop 依赖的自包含值对象：9 个计数字段 + 3 个派生 getter。
+ * 置入 `managers/` 而非 loop.ts 的理由：度量「定义」与度量「消费」应分离——
+ * loop 只负责 `this.metrics.xxx++`，指标结构本身不属于编排逻辑。
+ *
+ * 注：不设召回计数指标——记忆检索唯一入口 = search_memories 工具，耗时可看 TOOL_EXEC span。
+ */
+export declare class LoopMetrics {
+    llmCallCount: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    actualInputTokens: number;
+    actualOutputTokens: number;
+    toolCallCount: number;
+    toolFailureCount: number;
+    /** 空响应兜底次数（LLM 200 但 0 token）。为真说明用户看到英文兜底文案、
+     *  任务零产出却被 success 盖章——宿主据此识别「瞬态抽风」vs「模型拒绝」，不再被静默掩盖 */
+    emptyResponseCount: number;
+    /** 截断救回次数（截断型空响应换策略重试后成功产出）。与 emptyResponseCount 互补：
+     *  后者 = 最终仍空（救回失败），本计数 = 曾截断但被 T2 双轨救回（正文是真实模型产出，
+     *  不影响成功收尾）。「救回成功」的轮落盘无其它痕迹，无本计数则换策略重试的真机效力不可验。 */
+    truncationRecoveryCount: number;
+    /**
+     * 疑似工具调用但无原生 toolCalls 的文本意图数。
+     * 文本出口不再宣告可调用通道后，模型仍可能吐出 <tool_call>/<function=> 骨架——
+     * 本计数让「想干活却一步没干成」不再被静默盖章「完成」（宿主据此不显示 success）。
+     */
+    unparsedToolIntentCount: number;
+    /** 任务总执行次数（每次 processUserInput 算一次） */
+    taskTotalCount: number;
+    /** 任务成功次数 */
+    taskSuccessCount: number;
+    /** 任务失败次数（abort/超时/迭代耗尽） */
+    taskFailureCount: number;
+    /** 任务累计耗时（毫秒，用于计算平均耗时） */
+    taskTotalDurationMs: number;
+    /** 任务成功率（0-1） */
+    get taskSuccessRate(): number;
+    /** 平均任务耗时（毫秒） */
+    get taskAvgDurationMs(): number;
+    /** 累计调用 task_table_write 次数（= 任务表建表/重建次数） */
+    planTaskTableWriteCount: number;
+    /** 累计产出 plan_item_boundary 次数（= 思考折叠分块的边界数） */
+    planItemBoundaryCount: number;
+    /** 发送边界守卫命中次数（tool_call 批次成形违规被拒发）。健康态应恒 0——
+     *  命中 = 构造期散点回归（内核 bug 信号），见 toolCallHelpers.auditToolCallPairing */
+    llmPairingGuardFires: number;
+    /** read_file 覆盖度台账回显（分支② formatLedgerStub 命中）累计次数。
+     *  仅作观测基线：与「规避行为红旗」交叉判定防重是否过度顶替合法重读（见 AgentMetrics 该字段 JSDoc）。 */
+    ledgerStubEchoCount: number;
+    /** read_dedup 护栏硬拦命中（同主体重复获取且结果仍在上下文）累计次数。
+     *  与 ledgerStubEchoCount 互补：本计数 = L2 精确判重（模型乒乓信号，撞墙升级文案的量化基线），
+     *  后者 = L3 变体顶替；健康态应接近 0，持续增长 = 模型在同主体上反复重读。 */
+    readDedupBlockCount: number;
+}
+//# sourceMappingURL=loopMetrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loopMetrics.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/loopMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,YAAY,SAAK;IACjB,gBAAgB,SAAK;IACrB,iBAAiB,SAAK;IACtB,iBAAiB,SAAK;IACtB,kBAAkB,SAAK;IACvB,aAAa,SAAK;IAClB,gBAAgB,SAAK;IAErB;2DACuD;IACvD,kBAAkB,SAAK;IAEvB;;uDAEmD;IACnD,uBAAuB,SAAK;IAG5B;;;;OAIG;IACH,uBAAuB,SAAK;IAG5B,uCAAuC;IACvC,cAAc,SAAK;IACnB,aAAa;IACb,gBAAgB,SAAK;IACrB,4BAA4B;IAC5B,gBAAgB,SAAK;IACrB,0BAA0B;IAC1B,mBAAmB,SAAK;IAExB,iBAAiB;IACjB,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,iBAAiB;IACjB,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAGD,6CAA6C;IAC7C,uBAAuB,SAAK;IAC5B,+CAA+C;IAC/C,qBAAqB,SAAK;IAG1B;yEACqE;IACrE,oBAAoB,SAAK;IAGzB;sEACkE;IAClE,mBAAmB,SAAK;IAGxB;;oDAEgD;IAChD,mBAAmB,SAAK;CACzB"}

package/dist/agent/managers/loopMetrics.js

@@ -0,0 +1,68 @@
+/**
+ * AgentLoop 运行时指标纯状态容器
+ *
+ * 零 AgentLoop 依赖的自包含值对象：9 个计数字段 + 3 个派生 getter。
+ * 置入 `managers/` 而非 loop.ts 的理由：度量「定义」与度量「消费」应分离——
+ * loop 只负责 `this.metrics.xxx++`，指标结构本身不属于编排逻辑。
+ *
+ * 注：不设召回计数指标——记忆检索唯一入口 = search_memories 工具，耗时可看 TOOL_EXEC span。
+ */
+export class LoopMetrics {
+    llmCallCount = 0;
+    totalInputTokens = 0;
+    totalOutputTokens = 0;
+    actualInputTokens = 0;
+    actualOutputTokens = 0;
+    toolCallCount = 0;
+    toolFailureCount = 0;
+    /** 空响应兜底次数（LLM 200 但 0 token）。为真说明用户看到英文兜底文案、
+     *  任务零产出却被 success 盖章——宿主据此识别「瞬态抽风」vs「模型拒绝」，不再被静默掩盖 */
+    emptyResponseCount = 0;
+    /** 截断救回次数（截断型空响应换策略重试后成功产出）。与 emptyResponseCount 互补：
+     *  后者 = 最终仍空（救回失败），本计数 = 曾截断但被 T2 双轨救回（正文是真实模型产出，
+     *  不影响成功收尾）。「救回成功」的轮落盘无其它痕迹，无本计数则换策略重试的真机效力不可验。 */
+    truncationRecoveryCount = 0;
+    // ─── 未解析工具意图 ──────────────────────
+    /**
+     * 疑似工具调用但无原生 toolCalls 的文本意图数。
+     * 文本出口不再宣告可调用通道后，模型仍可能吐出 <tool_call>/<function=> 骨架——
+     * 本计数让「想干活却一步没干成」不再被静默盖章「完成」（宿主据此不显示 success）。
+     */
+    unparsedToolIntentCount = 0;
+    // ─── 任务级 SLO 度量 ──────────────────────
+    /** 任务总执行次数（每次 processUserInput 算一次） */
+    taskTotalCount = 0;
+    /** 任务成功次数 */
+    taskSuccessCount = 0;
+    /** 任务失败次数（abort/超时/迭代耗尽） */
+    taskFailureCount = 0;
+    /** 任务累计耗时（毫秒，用于计算平均耗时） */
+    taskTotalDurationMs = 0;
+    /** 任务成功率（0-1） */
+    get taskSuccessRate() {
+        return this.taskTotalCount > 0 ? this.taskSuccessCount / this.taskTotalCount : 0;
+    }
+    /** 平均任务耗时（毫秒） */
+    get taskAvgDurationMs() {
+        return this.taskTotalCount > 0 ? Math.round(this.taskTotalDurationMs / this.taskTotalCount) : 0;
+    }
+    // ─── 任务表触发观测量（先实证触发率，再决定修复是否起效）──
+    /** 累计调用 task_table_write 次数（= 任务表建表/重建次数） */
+    planTaskTableWriteCount = 0;
+    /** 累计产出 plan_item_boundary 次数（= 思考折叠分块的边界数） */
+    planItemBoundaryCount = 0;
+    // ─── 发送边界守卫 ───────────────────
+    /** 发送边界守卫命中次数（tool_call 批次成形违规被拒发）。健康态应恒 0——
+     *  命中 = 构造期散点回归（内核 bug 信号），见 toolCallHelpers.auditToolCallPairing */
+    llmPairingGuardFires = 0;
+    // ─── 读取防重的台账替身回显观测（观测防重是否过度拦截合法重读）──
+    /** read_file 覆盖度台账回显（分支② formatLedgerStub 命中）累计次数。
+     *  仅作观测基线：与「规避行为红旗」交叉判定防重是否过度顶替合法重读（见 AgentMetrics 该字段 JSDoc）。 */
+    ledgerStubEchoCount = 0;
+    // ─── 读取防重的 L2 硬拦观测 ──
+    /** read_dedup 护栏硬拦命中（同主体重复获取且结果仍在上下文）累计次数。
+     *  与 ledgerStubEchoCount 互补：本计数 = L2 精确判重（模型乒乓信号，撞墙升级文案的量化基线），
+     *  后者 = L3 变体顶替；健康态应接近 0，持续增长 = 模型在同主体上反复重读。 */
+    readDedupBlockCount = 0;
+}
+//# sourceMappingURL=loopMetrics.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loopMetrics.js","sourceRoot":"","sources":["../../../src/agent/managers/loopMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAW;IACtB,YAAY,GAAG,CAAC,CAAC;IACjB,gBAAgB,GAAG,CAAC,CAAC;IACrB,iBAAiB,GAAG,CAAC,CAAC;IACtB,iBAAiB,GAAG,CAAC,CAAC;IACtB,kBAAkB,GAAG,CAAC,CAAC;IACvB,aAAa,GAAG,CAAC,CAAC;IAClB,gBAAgB,GAAG,CAAC,CAAC;IAErB;2DACuD;IACvD,kBAAkB,GAAG,CAAC,CAAC;IAEvB;;uDAEmD;IACnD,uBAAuB,GAAG,CAAC,CAAC;IAE5B,qCAAqC;IACrC;;;;OAIG;IACH,uBAAuB,GAAG,CAAC,CAAC;IAE5B,wCAAwC;IACxC,uCAAuC;IACvC,cAAc,GAAG,CAAC,CAAC;IACnB,aAAa;IACb,gBAAgB,GAAG,CAAC,CAAC;IACrB,4BAA4B;IAC5B,gBAAgB,GAAG,CAAC,CAAC;IACrB,0BAA0B;IAC1B,mBAAmB,GAAG,CAAC,CAAC;IAExB,iBAAiB;IACjB,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,iBAAiB;IACjB,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,CAAC;IAED,mCAAmC;IACnC,6CAA6C;IAC7C,uBAAuB,GAAG,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,qBAAqB,GAAG,CAAC,CAAC;IAE1B,iCAAiC;IACjC;yEACqE;IACrE,oBAAoB,GAAG,CAAC,CAAC;IAEzB,sCAAsC;IACtC;sEACkE;IAClE,mBAAmB,GAAG,CAAC,CAAC;IAExB,uBAAuB;IACvB;;oDAEgD;IAChD,mBAAmB,GAAG,CAAC,CAAC;CACzB"}

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

@@ -1,43 +1,23 @@
 /**
- * 记忆顾问 — 健康诊断 + 关联推荐 + 冲突检测
- *
- * 从 MemoryInspector 提取 sourceHealth() + suggest() 为独立模块。
- * 两者均为纯只读分析计算，仅依赖 IMemoryStorage，不修改任何状态。
- *
- * 设计原则（延续 MemoryInspector）：
- *   - 纯只读——只读 IMemoryStorage，不修改任何状态
- *   - 同步返回——不调 LLM、不调 SQLite 写入
- *   - 无状态——所有数据从 IMemoryStorage 实时读取
- *
- * L3 冲突检测（可选增强）：
- *   - detectConflicts() 是异步方法，调用 LLM 判断记忆间语义冲突
- *   - backgroundProvider 未注入时静默跳过（向后兼容）
- *   - 仅检测不修复——冲突需要用户决策（降级哪条由用户选择）
+ * 记忆顾问 — sourceHealth()（源健康诊断）+ suggest()（关联推荐）+ detectConflicts()（L3 冲突检测）。
+ * 纯只读分析计算，仅依赖 IMemoryStorage 不修改状态；同步返回不调 LLM。
+ * L3 冲突检测：异步调 LLM 判断记忆间语义冲突，仅检测不修复（降级哪条由用户决策）。
  */
 import type { Memory } from '../../memory/types.js';
 import type { IMemoryStorage } from '../../memory/storageInterface.js';
 import type { LlmProvider } from '../../llm/provider.js';
-/** 记忆源健康状态 */
-export type SourceHealthStatus = 'healthy' | 'warning' | 'critical';
-/** 单个 source 的健康指标 */
+/** 单个 source 的事实观测指标（纯事实，不做健康等级判定） */
 export interface SourceHealthEntry {
-    /** 来源标签 */
     source: string;
     /** 记忆数量 */
     count: number;
-    /** 平均 score（0-1） */
-    avgScore: number;
-    /** 距上次访问的天数（取该 source 中最近访问的记忆） */
+    /** 距上次访问的天数（取该 source 中最近访问的记忆，冷记忆观测） */
     daysSinceLastAccess: number;
-    /** 健康状态：healthy（score≥0.5 且 7 天内有访问）/ warning（score<0.5 或 7-30 天未访问）/ critical（score<0.2 或 30 天以上未访问） */
-    status: SourceHealthStatus;
 }
-/** 记忆源健康诊断报告 */
+/** 记忆源诊断报告（纯事实观测，不设健康等级——记忆健康由 supersede/命中体现） */
 export interface SourceHealthReport {
-    /** 各 source 健康指标 */
+    /** 各 source 事实观测 */
     sources: SourceHealthEntry[];
-    /** 整体健康状态（取最差 source 的状态） */
-    overallStatus: SourceHealthStatus;
     /** 诊断时间（ISO 8601） */
     diagnosedAt: string;
 }
@@ -45,20 +25,17 @@ export interface SourceHealthReport {
 export interface SuggestOptions {
     /** 返回数量上限（默认 5） */
     limit?: number;
-    /** 排除的 source 标签（默认排除 persona、rule、skill） */
+    /** 排除的 source 标签（默认空数组——设定记忆已归角色包，不再参与召回排除） */
     excludeSources?: string[];
-    /** 时效性权重（0-1，默认 0.3）：越高越偏好最近访问的记忆 */
-    recencyWeight?: number;
 }
 /** 关联推荐结果 */
 export interface SuggestHit {
     /** 记忆唯一标识（source:name 格式） */
     id: string;
-    /** 记忆名称 */
     name: string;
     /** 来源标签 */
     source: string;
-    /** 推荐分数（0-1，由 score + recency 综合计算） */
+    /** 推荐分数（0-1，score 退役后为纯时效 recency） */
     relevance: number;
     /** 内容预览（截断到 120 字符） */
     contentPreview: string;
@@ -67,13 +44,11 @@ export interface SuggestHit {
 }
 /** 单对记忆的冲突判断结果 */
 export interface ConflictVerdict {
-    /** 记忆 A */
     memoryA: Memory;
-    /** 记忆 B */
     memoryB: Memory;
     /** 是否存在语义冲突（true → 需用户决策降级哪条） */
     hasConflict: boolean;
-    /** 冲突描述（hasConflict=true 时提供，说明冲突点） */
+    /** 冲突描述（hasConflict=true 时提供冲突点） */
     conflictDescription?: string;
     /** LLM 建议保留的记忆（'a' / 'b' / 'both'，仅供参考） */
     recommendation?: 'a' | 'b' | 'both';
@@ -90,108 +65,40 @@ export interface ConflictReport {
     conflictCount: number;
     /** 冲突详情列表（供宿主 UI 展示和用户决策） */
     conflicts: ConflictVerdict[];
-    /** 跳过原因（LLM 不可用 / 无候选对 / LLM 失败降级） */
+    /** 跳过原因（LLM 不可用 / 无候选对） */
     skippedReason?: string;
 }
-/**
- * 记忆顾问
- *
- * 从 MemoryInspector 拆分，负责基于记忆数据的分析计算：
- *   - sourceHealth()：记忆源健康诊断（数量、score、新鲜度）
- *   - suggest()：关联推荐（基于 score + 时效性 + 多样性）
- *   - detectConflicts()：语义冲突检测（L3，可选，backgroundProvider 注入后启用）
- *
- * 与 MemoryInspector 的分工：
- *   - MemoryInspector：直接数据查询（snapshot/search/stats/relations + 写操作代理）
- *   - MemoryAdvisor：分析计算（健康诊断 + 推荐排序 + 冲突检测）
- */
+/** 记忆顾问：与 MemoryInspector 分工（Inspector 直接数据查询，Advisor 分析计算：健康诊断 + 推荐排序 + 冲突检测） */
 export declare class MemoryAdvisor {
     private readonly index;
     /** 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过） */
     private readonly backgroundProvider;
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时推荐/冲突检测空转，测试可显式注入） */
+    private readonly sources;
+    constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null, sources?: readonly string[]);
     /**
-     * @param index - 记忆存储（只读访问，用于健康诊断和推荐计算）
-     * @param backgroundProvider - 后台 LLM Provider（可选，用于 L3 冲突检测，未注入时跳过）
-     */
-    constructor(index: IMemoryStorage, backgroundProvider?: LlmProvider | null);
-    /**
-     * 记忆源健康诊断
-     *
-     * 为每个 source 计算健康指标（数量、平均 score、新鲜度、状态），
-     * 帮助宿主项目判断是否需要触发衰减、清理或补充。
-     *
-     * 健康状态判定：
-     * - healthy：avgScore ≥ 0.5 且 7 天内有访问
-     * - warning：avgScore < 0.5 或 7-30 天未访问
-     * - critical：avgScore < 0.2 或 30 天以上未访问
-     *
-     * 纯只读、同步、不调 LLM，与 stats() 互补（stats 只有数量，本方法有质量指标）。
-     * 使用 getAllSources() 发现所有 source 标签，替代全量 search。
+     * 记忆源健康诊断：逐 source 计算记忆数量 / 最近访问天数（纯事实观测）。
+     * 不设健康等级：记忆健康由 supersede（写时取代）/ 命中体现，
+     * 无需榜单级 status 判定（daysSinceLastAccess 作冷记忆观测）。
+     * 纯只读同步不调 LLM，用 getAllSources() 发现所有 source 标签（替代全量 search）。
      */
     sourceHealth(): SourceHealthReport;
     /**
-     * 关联推荐：基于已有记忆数据，推荐你可能感兴趣的记忆
-     *
-     * 不调 LLM，纯计算。综合 score（权重）+ accessedAt（时效性）+ source 多样性，
-     * 返回"与你当前关注点相关但尚未直接搜索到"的记忆。
-     *
-     * 适用场景：
-     * - 用户搜索后，展示"你可能还想看"
-     * - 对话开始时，展示"最近你可能关心的记忆"
-     * - 宿主程序构建个性化推荐面板
-     *
-     * @param query - 可选的搜索关键词（提供时结合搜索结果推荐，省略时基于全局热度推荐）
-     * @param options - 推荐选项
+     * 关联推荐：不调 LLM 纯计算，综合 accessedAt（时效）+ source 多样性，
+     * 返回"相关但尚未直接搜索到"的记忆。query 提供时结合搜索命中推荐，省略时基于最近使用。
+     * relevance 为纯时效（recency）
      */
     suggest(query?: string, options?: SuggestOptions): SuggestHit[];
     /**
-     * 语义冲突检测：扫描同 source 的记忆对，调用 LLM 判断是否存在语义冲突
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载候选记忆（每个 source 取 top 10 条）
-     *   2. 同 source 内两两配对，取前 10 对
-     *   3. 对每对调用 LLM 判断是否存在语义冲突
-     *   4. 返回冲突报告（仅检测，不修复——冲突需要用户决策）
-     *
-     * 安全设计：
-     *   - 仅检测不修复——不自动降级任何记忆，返回冲突详情供用户决策
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 单对 LLM 失败不阻塞后续检测
-     *   - backgroundProvider 未注入时静默跳过（向后兼容）
-     *
-     * 使用场景：
-     *   - 宿主定时任务定期检测（如每天一次）
-     *   - 用户手动触发（记忆管理面板的"检测冲突"按钮）
-     *   - 健康诊断报告的补充（sourceHealth 显示数量，本方法显示质量冲突）
-     *
-     * @param signal 可选的 AbortSignal（取消正在进行的 LLM 判断）
-     * @returns 冲突检测报告
+     * 语义冲突检测：加载候选（每 source top 10）→ 同 source 两两配对（前 10 对）→ LLM 判断冲突。
+     * 仅检测不修复（不自动降级，冲突需用户决策）；LLM 失败不阻塞；provider 未注入静默跳过。
      */
     detectConflicts(signal?: AbortSignal): Promise<ConflictReport>;
-    /**
-     * 筛选同 source 内的候选冲突对
-     *
-     * 策略：
-     *   - 按 source 分组，同 source 内两两配对
-     *   - 限制每个 source 的配对数，避免 O(n²) 爆炸
-     *   - 总候选对数上限 10 对
-     *
-     * @param candidates 候选记忆列表（已按 source 分组混合）
-     * @returns 同 source 候选对列表
-     */
+    /** 筛选同 source 内候选冲突对：按 source 分组两两配对，限制每 source 配对数避免 O(n²) 爆炸，总上限 10 对 */
     private findConflictCandidates;
     /**
-     * 调用 LLM 判断两条记忆是否存在语义冲突
-     *
-     * 使用结构化 JSON 输出（hasConflict + conflictDescription + recommendation + reason），
-     * 流式累积 + parseLlmJson + 异常封装委托给 llmJudgeHelper.judgeWithLlm。
-     *
-     * LLM 失败时抛出 MemoraError（由 detectConflicts 捕获并降级跳过此对）。
-     *
-     * @param memoryA 记忆 A
-     * @param memoryB 记忆 B
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
+     * 调用 LLM 判断两条记忆是否冲突：结构化 JSON 输出（hasConflict+conflictDescription+recommendation+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
      */
     private judgeConflict;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"memoryAdvisor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryAdvisor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memoryAdvisor.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/memoryAdvisor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,mBAAmB,CAAC;AA6B9D,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,qBAAqB;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,kBAAkB;AAClB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,cAAc,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;IACpC,eAAe;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,kFAAkF;AAClF,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,KAAK,EAAE,cAAc,EACtC,kBAAkB,GAAE,WAAW,GAAG,IAAW,EAC7C,OAAO,GAAE,SAAS,MAAM,EAAuB;IAQjD;;;;;OAKG;IACH,YAAY,IAAI,kBAAkB;IAsClC;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,UAAU,EAAE;IA6EnE;;;OAGG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IAwEpE,2EAA2E;IAC3E,OAAO,CAAC,sBAAsB;IA+B9B;;;OAGG;YACW,aAAa;CAiC5B"}