@zooique/memora 2.0.3 → 3.0.1

package/dist/agent/managers/memoryDecayScheduler.js

@@ -1,413 +0,0 @@
-/**
- * 记忆衰减调度器（从 agent.ts 拆分）
- *
- * 职责：
- *   1. 定期执行记忆 score 衰减（体现"自然遗忘"）
- *   2. 衰减指标统计（执行次数 / 累计衰减记忆数 / 上次衰减时间）
- *   3. 衰减可观测性（Tracer Span 埋点）
- *   4. 衰减完成事件发射（decayCompleted）
- *   5. L2 时效性评估（可选，backgroundProvider + index 注入后启用）
- *
- * 设计理由：
- *   agent.ts 原承担 15+ 职责，记忆衰减是独立的生命周期职责，
- *   拆分后 Agent 聚焦对话编排，MemoryDecayScheduler 聚焦记忆自然遗忘。
- *
- * 衰减范围：
- *   - insight（洞察记忆）
- *   - profile（用户画像记忆）
- *   - work-projection（作品投影）
- *   不衰减 persona/rule/skill（配置型记忆不应衰减）
- *
- * L2 时效性评估（可选增强）：
- *   - 衰减后扫描低分记忆（score < TIMELINESS_LOW_SCORE_THRESHOLD）
- *   - 调用 LLM 判断是否"已过时"（如过时的技术栈、已变更的偏好）
- *   - 过时则进一步降级（score → TIMELINESS_OUTDATED_SCORE）
- *   - backgroundProvider / index 未注入时静默跳过（向后兼容）
- *
- * 自然生长原则：
- *   - 不持有 storage 引用（start 时注入，stop 时释放）
- *   - 通过回调发射事件（不继承 TypedEventEmitter，避免与 Agent 事件系统耦合）
- *   - 指标统计内聚（getMetrics 返回快照，Agent.getMetrics 直接合并）
- */
-import { safeSetInterval, clearSafeInterval } from '../../utils/safeTimer.js';
-import { logger } from '../../logging/logger.js';
-import { toError } from '../../utils/errors.js';
-import { nowIso } from '../../utils/time.js';
-import { NOOP_TRACER, TRACE_SPANS } from '../../agent/tracer.js';
-// LLM judge 三件套高阶函数（流式累积 + parseLlmJson + configError 异常封装）
-import { judgeWithLlm } from '../../agent/managers/llmJudgeHelper.js';
-import { truncate } from '../../utils/strings.js';
-// LLM 治理源列表（v2 REPEAT-1 闭环，消除 5 处独立维护的 [INSIGHT, PROFILE, WORK_PROJECTION] 列表）
-import { GOVERNANCE_SOURCES } from '../../memory/governance.js';
-// ─── L2 时效性评估常量 ────────────────────────────────────
-// 注：TIMELINESS_SOURCES 已统一为 GOVERNANCE_SOURCES（governance.ts），消除 5 处独立维护
-/** 低分记忆阈值（score 低于此值的记忆进入 LLM 时效性评估） */
-const TIMELINESS_LOW_SCORE_THRESHOLD = 0.3;
-/** 单次时效性评估的记忆条数上限（控制 LLM 调用量） */
-const TIMELINESS_EVALUATE_LIMIT = 20;
-/** LLM 时效性判断超时（ms） */
-const TIMELINESS_TIMEOUT_MS = 15_000;
-/** 被判定为过时的记忆降级到此 score（接近物理删除阈值，但保留可恢复性） */
-const TIMELINESS_OUTDATED_SCORE = 0.05;
-/** 候选记忆内容预览长度（截断后送入 LLM） */
-const TIMELINESS_CONTENT_PREVIEW_LEN = 200;
-/**
- * 记忆衰减调度器
- *
- * 使用方式：
- *   const scheduler = new MemoryDecayScheduler({ tracer, onDecayCompleted });
- *   scheduler.start(storage, intervalMs);  // 启动定时衰减
- *   scheduler.runOnce();                    // 立即执行一次衰减
- *   scheduler.stop();                       // 停止定时衰减
- *   scheduler.getMetrics();                 // 获取衰减指标快照
- */
-export class MemoryDecayScheduler {
-    /** 可观测性 Tracer（默认 NOOP，零开销） */
-    tracer;
-    /** 衰减完成事件发射回调 */
-    onDecayCompleted;
-    /** 后台 LLM Provider（可选，用于 L2 时效性评估，未注入时跳过） */
-    backgroundProvider;
-    /** 完整记忆存储（可选，用于 L2 读取低分记忆和降级，未注入时跳过） */
-    index;
-    /** 衰减定时器（null 表示未启动） */
-    decayTimer = null;
-    /** 衰减目标存储（start 时注入，stop 时释放） */
-    storage = null;
-    /**
-     * L2 时效性评估的 AbortController
-     *
-     * FIX-P0-1：stop() 时 abort，让正在进行的 evaluateTimeliness 尽快结束，
-     * 防止 close 后 LLM 回调 upsert 已关闭的 storage。
-     * 每次 evaluateTimeliness 启动时重置为新的 controller。
-     */
-    evaluateAbortController = null;
-    /**
-     * 当前正在进行的 evaluateTimeliness Promise（null 表示无）
-     *
-     * FIX-P0-1：close() 通过 awaitInflight() 等待此 Promise 完成，
-     * 确保关闭时所有 L2 评估的 upsert 都落在 storage 关闭前。
-     */
-    inflightEvaluate = null;
-    // ─── 衰减指标统计字段 ──────────────────────────────────
-    /** 衰减执行次数（每次 runOnce 实际执行 +1） */
-    metricDecayRunCount = 0;
-    /** 累计衰减记忆数（score 被调低的记忆条数总和） */
-    metricTotalDecayedCount = 0;
-    /** 上次衰减时间（ISO 8601，null 表示从未执行过） */
-    metricLastDecayAt = null;
-    constructor(opts) {
-        this.tracer = opts.tracer ?? NOOP_TRACER;
-        this.onDecayCompleted = opts.onDecayCompleted;
-        // L2 可选依赖：未注入时 evaluateTimeliness 静默跳过
-        this.backgroundProvider = opts.backgroundProvider ?? null;
-        this.index = opts.index ?? null;
-    }
-    /**
-     * 启动定期衰减
-     *
-     * @param storage 衰减目标存储（IMemoryStorage.decayScores）
-     * @param intervalMs 衰减间隔（毫秒，通常为 1 小时）
-     */
-    start(storage, intervalMs) {
-        this.storage = storage;
-        // 立即执行一次首次衰减
-        this.runOnce();
-        // 注册定期衰减
-        this.decayTimer = safeSetInterval(() => this.runOnce(), intervalMs);
-    }
-    /**
-     * 停止定期衰减，释放资源
-     *
-     * FIX-P0-1：清理定时器 + abort 正在进行的 L2 时效性评估 + 释放 storage 引用，
-     * 防止 close 后回调触发 upsert 已关闭的 storage。
-     *
-     * 注意：stop() 不等待 inflightEvaluate 完成（避免阻塞 close 流程），
-     * 调用方如需等待应使用 awaitInflight()。abort 后 LLM 调用会快速失败，
-     * evaluateTimeliness 内部的 try/catch 会捕获并降级返回。
-     */
-    stop() {
-        if (this.decayTimer) {
-            clearSafeInterval(this.decayTimer);
-            this.decayTimer = null;
-        }
-        // FIX-P0-1：abort 正在进行的 L2 评估，让 LLM 调用快速失败
-        if (this.evaluateAbortController) {
-            this.evaluateAbortController.abort();
-            this.evaluateAbortController = null;
-        }
-        this.storage = null;
-    }
-    /**
-     * 等待正在进行的 L2 时效性评估完成
-     *
-     * FIX-P0-1：Agent.close() 在 stop() 后调用此方法，确保所有 inflight 的
-     * evaluateTimeliness Promise 完成（要么正常返回，要么因 abort 快速 reject），
-     * 防止 close 后 LLM 回调 upsert 已关闭的 storage。
-     *
-     * @returns 完成 Promise，无 inflight 时立即 resolve
-     */
-    async awaitInflight() {
-        if (this.inflightEvaluate) {
-            try {
-                await this.inflightEvaluate;
-            }
-            catch {
-                // abort 导致的 reject 是预期行为，吞掉即可
-            }
-        }
-    }
-    /**
-     * 执行一次记忆衰减
-     *
-     * 对 insight/profile/work-projection 记忆执行 score 衰减，
-     * 长期未访问的记忆 score 逐渐降低，体现"自然遗忘"。
-     * 不影响 persona/rule/skill（这些是配置型记忆，不应衰减）。
-     *
-     * 衰减逻辑委派给 IMemoryStorage.decayScores()，
-     * 宿主（SqliteStorage）可用一条 SQL UPDATE 批量完成，避免 O(n) 全量加载。
-     */
-    runOnce() {
-        if (!this.storage)
-            return;
-        // 衰减 Span：记录衰减执行过程，补全衰减可观测性缺口
-        const decaySpan = this.tracer.startSpan(TRACE_SPANS.DECAY);
-        try {
-            // 治理源列表统一来自 governance.ts（v2 REPEAT-1 闭环）
-            const decayedCount = this.storage.decayScores([...GOVERNANCE_SOURCES], new Date());
-            logger.debug({ decayedCount }, '记忆衰减完成');
-            // 衰减指标统计：累计执行次数和衰减记忆数
-            this.metricDecayRunCount++;
-            this.metricTotalDecayedCount += decayedCount;
-            this.metricLastDecayAt = nowIso();
-            decaySpan.setAttribute('decayedCount', decayedCount);
-            decaySpan.setAttribute('totalRuns', this.metricDecayRunCount);
-            this.onDecayCompleted({ decayedCount });
-        }
-        catch (err) {
-            logger.warn({ err }, '记忆衰减异常，跳过本轮');
-            decaySpan.recordException(toError(err));
-        }
-        finally {
-            decaySpan.end();
-        }
-    }
-    /**
-     * 获取衰减指标快照
-     *
-     * 供 Agent.getMetrics() 合并到完整 AgentMetrics 中。
-     */
-    getMetrics() {
-        return {
-            runCount: this.metricDecayRunCount,
-            totalDecayedCount: this.metricTotalDecayedCount,
-            lastRunAt: this.metricLastDecayAt,
-        };
-    }
-    // ─── L2 时效性评估（可选，backgroundProvider + index 注入后启用） ───
-    /**
-     * 时效性评估：扫描低分记忆，调用 LLM 判断是否已过时
-     *
-     * 流程：
-     *   1. 从 insight/profile/work-projection 加载低分记忆（score < 0.3）
-     *   2. 对每条低分记忆（上限 20 条），调用 LLM 判断是否"已过时"
-     *   3. 过时则进一步降级（score → 0.05，接近物理删除阈值但保留可恢复性）
-     *   4. 返回评估报告
-     *
-     * 使用场景：
-     *   - 衰减后调用（onDecayCompleted 回调中），对低分记忆做 LLM 二次评估
-     *   - 宿主定时任务定期调用（如每天一次）
-     *   - 用户手动触发（记忆管理面板的"清理过时记忆"按钮）
-     *
-     * 安全设计：
-     *   - 不物理删除——仅降级 score，保留可恢复性
-     *   - LLM 失败降级——返回已处理的报告，不阻塞调用方
-     *   - 单条 LLM 失败不阻塞后续评估
-     *   - backgroundProvider / index 未注入时静默跳过（向后兼容）
-     *
-     * FIX-P0-1：每次启动评估创建新的 AbortController，注册到 inflightEvaluate。
-     * stop() 时 abort 让 LLM 调用快速失败，awaitInflight() 等待 Promise 完成。
-     * 外部 signal 仍可与内部 abort 信号同时使用（任一触发即取消）。
-     *
-     * @param signal 可选的外部 AbortSignal（与内部 abort 信号叠加，任一触发即取消）
-     * @returns 评估报告
-     */
-    async evaluateTimeliness(signal) {
-        // 可选依赖未注入时静默降级（向后兼容）
-        if (!this.backgroundProvider || !this.index) {
-            return {
-                scannedCount: 0,
-                outdatedCount: 0,
-                demotedIds: [],
-                skippedReason: 'backgroundProvider 或 index 未注入',
-            };
-        }
-        // FIX-P0-1：每次评估创建新的 AbortController，stop() 可主动 abort
-        this.evaluateAbortController = new AbortController();
-        const internalSignal = this.evaluateAbortController.signal;
-        // 外部 signal 与内部 signal 叠加：任一 abort 即触发
-        // 使用 AbortSignal.any 需 Node 18+，兼容方案是手动转发
-        const combinedSignal = signal
-            ? AbortSignal.any([internalSignal, signal])
-            : internalSignal;
-        // 注册到 inflightEvaluate，让 awaitInflight() 可等待
-        const promise = this.doEvaluateTimeliness(combinedSignal);
-        this.inflightEvaluate = promise;
-        try {
-            return await promise;
-        }
-        finally {
-            // 评估完成（成功/失败/abort）后清理引用
-            if (this.inflightEvaluate === promise) {
-                this.inflightEvaluate = null;
-            }
-            if (this.evaluateAbortController?.signal === internalSignal) {
-                this.evaluateAbortController = null;
-            }
-        }
-    }
-    /**
-     * 实际执行 L2 时效性评估的核心逻辑
-     *
-     * 从 evaluateTimeliness 拆出，便于 inflightEvaluate Promise 注册和清理。
-     *
-     * @param combinedSignal 已叠加内部 + 外部的 AbortSignal
-     */
-    async doEvaluateTimeliness(signal) {
-        // ── 步骤 1：加载低分记忆 ──
-        const lowScoreMemories = [];
-        for (const source of GOVERNANCE_SOURCES) {
-            const memories = this.index.getBySource(source);
-            // 筛选低分记忆（score 低于阈值）
-            lowScoreMemories.push(...memories.filter((m) => m.score < TIMELINESS_LOW_SCORE_THRESHOLD));
-        }
-        if (lowScoreMemories.length === 0) {
-            return {
-                scannedCount: 0,
-                outdatedCount: 0,
-                demotedIds: [],
-                skippedReason: '无低分记忆需评估',
-            };
-        }
-        // 按 score 升序排列（最低分优先评估），取前 20 条
-        lowScoreMemories.sort((a, b) => a.score - b.score);
-        const limited = lowScoreMemories.slice(0, TIMELINESS_EVALUATE_LIMIT);
-        // ── 步骤 2：逐条调用 LLM 判断时效性 ──
-        const demotedIds = [];
-        let outdatedCount = 0;
-        for (const memory of limited) {
-            // abort 后提前退出循环，避免无谓的 LLM 调用
-            if (signal.aborted)
-                break;
-            try {
-                const verdict = await this.judgeTimeliness(memory, signal);
-                if (verdict.isOutdated) {
-                    this.demoteOutdatedMemory(memory);
-                    demotedIds.push(memory.id);
-                    outdatedCount++;
-                    logger.info({ memoryId: memory.id, reason: verdict.reason }, '时效性评估：降级过时记忆');
-                }
-            }
-            catch (err) {
-                // 单条 LLM 判断失败不阻塞后续评估（abort 导致的失败也走此分支）
-                logger.warn({ err, memoryId: memory.id }, '时效性评估：LLM 判断失败，跳过此条');
-            }
-        }
-        return {
-            scannedCount: limited.length,
-            outdatedCount,
-            demotedIds,
-        };
-    }
-    /**
-     * 调用 LLM 判断单条记忆的时效性
-     *
-     * 使用结构化 JSON 输出（isOutdated + reason），
-     * 流式累积 + parseLlmJson + 异常封装委托给 llmJudgeHelper.judgeWithLlm。
-     *
-     * LLM 失败时抛出 MemoraError（由 evaluateTimeliness 捕获并降级跳过此条）。
-     *
-     * @param memory 待评估的记忆
-     * @param signal 可选的 AbortSignal
-     * @returns LLM 判断结果
-     */
-    async judgeTimeliness(memory, signal) {
-        const messages = buildTimelinessMessages(memory);
-        const parsed = await judgeWithLlm(this.backgroundProvider, messages, { maxTokens: 200, timeoutMs: TIMELINESS_TIMEOUT_MS, signal }, 'LLM 时效性判断返回非法 JSON');
-        return {
-            memoryId: memory.id,
-            isOutdated: parsed.isOutdated === true,
-            reason: typeof parsed.reason === 'string' ? parsed.reason : '(LLM 未提供理由)',
-        };
-    }
-    /**
-     * 降级过时记忆（score → TIMELINESS_OUTDATED_SCORE）
-     *
-     * 安全设计：
-     *   - 不物理删除，仅降低 score，保留可恢复性
-     *   - 更新 accessedAt，标记最近被处理过
-     *
-     * @param memory 待降级的过时记忆
-     */
-    demoteOutdatedMemory(memory) {
-        // MIND2-L3：改用 setScore 原子操作，消除 spread 旧快照覆盖其他字段
-        // 原模式 spread 旧快照后整条 upsert，会覆盖期间被 boost/decay 改的 content 等字段
-        this.index.setScore(memory.id, TIMELINESS_OUTDATED_SCORE, nowIso());
-    }
-}
-// ─── L2 时效性评估 Prompt 模板（模块级函数，与 buildDedupMessages 同模式） ───
-/**
- * 构建时效性判断的 LLM 消息
- *
- * 设计要点：
- *   - system 消息定义判断规则（过时 = 信息已失效/不再适用）
- *   - user 消息携带记忆内容和元数据（source/score/createdAt）
- *   - 要求输出结构化 JSON（isOutdated + reason）
- *   - few-shot 示例降低 LLM 误判率
- *
- * @param memory 待评估的记忆
- * @returns system + user 消息数组
- */
-function buildTimelinessMessages(memory) {
-    const content = memory.content.length > TIMELINESS_CONTENT_PREVIEW_LEN
-        ? truncate(memory.content, TIMELINESS_CONTENT_PREVIEW_LEN, '…[截断]')
-        : memory.content;
-    return [
-        {
-            role: 'system',
-            content: `你是记忆时效性评估助手。判断给定的记忆是否已过时（信息已失效或不再适用）。
-
-判断规则：
-- 已过时 = 信息明确失效（如旧版本号、已废弃的 API、已变更的偏好）
-- 未过时 = 信息仍然有效（如通用编程原则、长期偏好、历史事件记录）
-- 不确定时倾向"未过时"（避免误删有效记忆）
-
-输出 JSON 格式：
-{
-  "isOutdated": true/false,
-  "reason": "判断理由（简短说明）"
-}
-
-示例：
-输入: "用户使用 React 16 进行开发"（createdAt: 2020-01-01）
-输出: {"isOutdated": true, "reason": "React 16 已是旧版本，当前普遍使用 React 18+"}
-
-输入: "用户偏好函数式编程风格"
-输出: {"isOutdated": false, "reason": "编程风格偏好通常是长期的"}`,
-        },
-        {
-            role: 'user',
-            content: `请判断以下记忆是否已过时：
-
-记忆详情：
-- 名称：${memory.name}
-- 来源：${memory.source}
-- 当前 score：${memory.score}（低分，可能因长期未访问而衰减）
-- 创建时间：${memory.createdAt}
-- 内容：${content}
-
-请输出 JSON 判断结果。`,
-        },
-    ];
-}
-//# sourceMappingURL=memoryDecayScheduler.js.map

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

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

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

@@ -1,131 +0,0 @@
-/**
- * 关系构建器 — ADR-014 记忆关系构建的专职 Manager
- *
- * 从 InsightExtractor 拆分出来，负责：
- *   - 召回关系判断候选记忆（top-5 关键词搜索）
- *   - 构建关系判断 prompt 片段（候选列表 + 关系类型说明）
- *   - 解析 LLM 输出的 relations 字段并写入 IMemoryRelationStore
- *   - contradicts 关系检测 + onConflict 回调通知
- *
- * 设计原则：
- *   - 独立于 InsightExtractor 生命周期，仅依赖 IMemoryStorage + IMemoryRelationStore
- *   - 静默降级——relationStore 未注入时所有方法返回空/no-op（ADR-014 降级优先）
- *   - 薄层代理——关系写入直接透传到 IMemoryRelationStore，仅增加 weight 推断 + targetId 校验
- *
- * 与 InsightExtractor 的分工（1.0 接口稳定化）：
- *   - InsightExtractor：insight 提取 + 去重 + 写入 + 输入分类
- *   - RelationBuilder：候选召回 + prompt 构建 + 关系写入 + 冲突检测
- *
- * 详见 ADR-014（记忆关系侧车模型）
- */
-import type { Memory } from '../../memory/types.js';
-import type { IMemoryStorage } from '../../memory/storageInterface.js';
-import type { IMemoryRelationStore } from '../../memory/relationStore.js';
-/**
- * 冲突信息（contradicts 关系检测到时传递给宿主）
- *
- * 由 RelationBuilder.buildRelations 检测到 contradicts 关系时构造，
- * 通过 onConflict 回调传递给 Agent，Agent emit('conflictDetected') 通知宿主。
- */
-export interface ConflictInfo {
-    /** 新写入的 insight 记忆 ID */
-    newMemoryId: string;
-    /** 新洞察内容（用于 UI 展示） */
-    newInsight: string;
-    /** 被矛盾的已有记忆 ID */
-    targetId: string;
-    /** 被矛盾的已有记忆内容（用于 UI 展示） */
-    targetContent: string;
-}
-/**
- * 关系构建器
- *
- * 封装 ADR-014 记忆关系构建的全部逻辑，从 InsightExtractor 拆分。
- * relationStore 未注入时所有方法静默降级（返回空/no-op）。
- */
-export declare class RelationBuilder {
-    private readonly index;
-    private readonly relationStore;
-    /** 冲突检测回调（由 Agent 通过 bindOnConflict 注入，检测到 contradicts 时触发） */
-    private onConflict;
-    /**
-     * @param index 记忆存储（用于候选召回的关键词搜索）
-     * @param relationStore 记忆关系存储（可选，未注入时所有方法静默降级）
-     */
-    constructor(index: IMemoryStorage, relationStore?: IMemoryRelationStore | null);
-    /** 关系构建是否启用（relationStore 已注入时为 true） */
-    get enabled(): boolean;
-    /**
-     * 绑定冲突检测回调
-     *
-     * 由 Agent.init() 在创建 InsightExtractor 后调用（与 bindGetRecentHistory 同模式），
-     * 解决 Agent 实例晚于 InsightExtractor 创建的时序循环依赖。
-     * buildRelations 检测到 contradicts 关系时调用此回调，Agent 在回调中 emit('conflictDetected')。
-     *
-     * @param fn 冲突检测回调（传入 null 可解除绑定）
-     */
-    bindOnConflict(fn: ((info: ConflictInfo) => void) | null): void;
-    /**
-     * 召回关系判断候选记忆（top-5）
-     *
-     * 用用户输入关键词搜索已有记忆，作为 LLM 关系判断的参考。
-     * 用户输入与提取出的 insight 通常相关，候选记忆也相关。
-     * relationStore 未注入时返回空数组（降级）。
-     *
-     * @param userInput 用户输入（用于关键词搜索）
-     * @returns 候选记忆列表（id + content 截断）
-     */
-    recallRelationCandidates(userInput: string): Memory[];
-    /**
-     * 构建候选记忆列表的 prompt 片段
-     *
-     * 格式：
-     *   已有记忆（供关系判断参考）：
-     *   [1] id: xxx, content: xxx
-     *   [2] id: xxx, content: xxx
-     *
-     * @param candidates 候选记忆列表
-     * @returns prompt 片段（空候选时返回空字符串）
-     */
-    buildCandidatesPrompt(candidates: Memory[]): string;
-    /**
-     * 构建关系判断的 prompt 指令片段
-     *
-     * 包含 relations 字段格式说明 + 关系类型说明 + 注意事项。
-     * relationStore 未注入时返回空字符串（降级，不影响 insight 提取主流程）。
-     *
-     * @returns prompt 指令片段（relationStore 未注入时为空字符串）
-     */
-    buildRelationsPrompt(): string;
-    /**
-     * 构建关系（写入 IMemoryRelationStore）
-     *
-     * 解析 LLM 输出的 relations 字段，验证 targetId 在候选列表中，写入关系存储。
-     * 降级策略：relationStore 未注入/relations 为空/targetId 无效 → 跳过，不阻塞主流程。
-     *
-     * 检测到 contradicts 关系时，通过 onConflict 回调通知 Agent，
-     * Agent emit('conflictDetected') 触发宿主消费链路（ProactiveBanner 通知用户）。
-     *
-     * @param insightId 新写入的 insight ID
-     * @param insightContent 新写入的 insight 内容（用于冲突通知 UI 展示）
-     * @param relations LLM 输出的关系列表
-     * @param candidates 候选记忆列表（用于验证 targetId + 查找 targetContent）
-     */
-    buildRelations(insightId: string, insightContent: string, relations: Array<{
-        targetId?: unknown;
-        type?: unknown;
-    }>, candidates: Memory[]): void;
-    /**
-     * 根据关系类型推断 weight（ADR-014 §4）
-     *
-     * LLM 只输出 type，weight 由代码层推断：
-     * - contradicts → 1.0（确定关系，矛盾是强关系）
-     * - supports/follows/refines/caused → 0.7（强相关）
-     * - related → 0.3（弱相关）
-     * - 未知类型 → 0.5（未判断兜底）
-     *
-     * 设计理由：降低 LLM 认知负担，离散值比连续浮点稳定
-     */
-    private weightByType;
-}
-//# sourceMappingURL=relationBuilder.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"relationBuilder.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/relationBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAetE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAThC,+DAA+D;IAC/D,OAAO,CAAC,UAAU,CAA+C;IAEjE;;;OAGG;gBAEgB,KAAK,EAAE,cAAc,EACrB,aAAa,GAAE,oBAAoB,GAAG,IAAW;IAGpE,yCAAyC;IACzC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAM/D;;;;;;;;;OASG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAMrD;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM;IAWnD;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM;IAqB9B;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,EACxD,UAAU,EAAE,MAAM,EAAE,GACnB,IAAI;IA4CP;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;CAYrB"}