@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/managers/dedupManager.js

@@ -0,0 +1,248 @@
+// LLM judge 高阶函数（流式累积 + parseLlmJson + configError 封装）
+import { judgeWithLlm } from '../../agent/managers/llmJudgeHelper.js';
+// LLM 治理共享常量（统一由 governance.ts 维护）
+import { GOVERNANCE_SOURCES } from '../../memory/governance.js';
+import { levenshtein } from '../../memory/sourceValidation.js';
+import { byAccessedDesc } from '../../utils/array.js';
+import { nowIso } from '../../utils/time.js';
+import { truncate } from '../../utils/strings.js';
+import { logger } from '../../logging/logger.js';
+// ─── L1 语义去重常量 ────────────────────────────────────
+/** 单次去重扫描候选条数上限 */
+const DEDUP_CANDIDATE_LIMIT = 50;
+/** 单次 LLM 判断候选对数上限（每对约 200 tokens） */
+const DEDUP_PAIR_LIMIT = 10;
+/** 名称相似度阈值（归一化 Levenshtein 距离 ≤ 此值视为高度相似进入 LLM 判断） */
+const DEDUP_NAME_SIMILARITY_THRESHOLD = 0.3;
+/** LLM 去重判断超时（ms） */
+const DEDUP_TIMEOUT_MS = 15_000;
+/** 候选内容预览长度（送入 LLM 前截断，控制 token） */
+const DEDUP_CONTENT_PREVIEW_LEN = 200;
+// ─── 类 ──────────────────────────────────────────────────
+/** 语义去重管理器：扫描名称高度相似的记忆对，LLM 判断语义等价性，降级低分记忆。assembler 组合根创建，由 Agent 透传调用。 */
+export class DedupManager {
+    index;
+    onCompleted;
+    /** 后台 LLM Provider（可选，未注入时降级跳过） */
+    backgroundProvider;
+    /** 治理源列表（默认 GOVERNANCE_SOURCES；空治理源时去重空转，测试可显式注入） */
+    sources;
+    constructor(index, backgroundProvider = null, 
+    /** 去重完成回调（宿主据此发射事件通知用户） */
+    onCompleted, sources = GOVERNANCE_SOURCES) {
+        this.index = index;
+        this.onCompleted = onCompleted;
+        this.backgroundProvider = backgroundProvider;
+        this.sources = sources;
+    }
+    /**
+     * 语义去重：加载候选（上限 50）→ 名称相似度筛选对（上限 10）→ LLM 判断语义等价 → 等价则软删重复方。
+     * 安全设计：不物理删除仅软删（可恢复）；LLM 失败降级不阻塞；provider 未注入静默返回 skippedReason。
+     */
+    async deduplicateMemories(signal) {
+        // provider 未注入时静默降级
+        if (!this.backgroundProvider) {
+            return {
+                scannedCount: 0,
+                pairCount: 0,
+                deduplicatedCount: 0,
+                demotedIds: [],
+                skippedReason: 'backgroundProvider 未注入',
+            };
+        }
+        const candidates = [];
+        for (const source of this.sources) {
+            const memories = this.index.getBySource(source);
+            candidates.push(...memories);
+        }
+        // 按 accessedAt 降序（最近使用优先，score 退役后无分可排序）
+        candidates.sort(byAccessedDesc);
+        const limited = candidates.slice(0, DEDUP_CANDIDATE_LIMIT);
+        const pairs = this.findNameOverlapPairs(limited);
+        if (pairs.length === 0) {
+            return {
+                scannedCount: limited.length,
+                pairCount: 0,
+                deduplicatedCount: 0,
+                demotedIds: [],
+                skippedReason: '未发现名称相似的记忆对',
+            };
+        }
+        const demotedIds = [];
+        const verdicts = [];
+        let deduplicatedCount = 0;
+        for (const pair of pairs) {
+            try {
+                const verdict = await this.judgeDuplicate(pair, signal);
+                if (verdict.isDuplicate) {
+                    // 先写合并内容再降级 b：合并写入失败时不破坏 b 原始状态（原子性）
+                    if (verdict.mergedContent) {
+                        this.keepMerged(pair.a, verdict.mergedContent);
+                    }
+                    // 重复方软删（score 退役后无降级语义，soft-delete 保留可恢复）
+                    this.demoteMemory(pair.b);
+                    demotedIds.push(pair.b.id);
+                    // 收集审计详情（供 UI 展示"为什么降级"和"合并后保留了什么"）
+                    verdicts.push({
+                        demotedId: pair.b.id,
+                        reason: verdict.reason,
+                        mergedContent: verdict.mergedContent,
+                    });
+                    deduplicatedCount++;
+                    logger.info({ demotedId: pair.b.id, keptId: pair.a.id, reason: verdict.reason }, '语义去重：降级重复记忆并合并内容到保留方');
+                }
+            }
+            catch (err) {
+                // 单对失败不阻塞后续对
+                logger.warn({ err, pairId: `${pair.a.id}↔${pair.b.id}` }, '语义去重：LLM 判断失败，跳过此对');
+            }
+        }
+        this.onCompleted?.({
+            scannedCount: limited.length,
+            pairCount: pairs.length,
+            deduplicatedCount,
+            demotedIds,
+        });
+        return {
+            scannedCount: limited.length,
+            pairCount: pairs.length,
+            deduplicatedCount,
+            demotedIds,
+            verdicts,
+        };
+    }
+    /**
+     * 筛选名称高度相似的候选记忆对。判定：归一化 Levenshtein ≤0.3 或一方包含另一方。
+     * 已配对的记忆不再参与后续配对（避免三元组产生多对）；按相似度升序（越相似越优先）取前 10 对。
+     */
+    findNameOverlapPairs(candidates) {
+        const pairs = [];
+        const usedIds = new Set();
+        // 双重循环生成所有可能对，按相似度排序后贪心选取
+        const allPairs = [];
+        for (let i = 0; i < candidates.length; i++) {
+            for (let j = i + 1; j < candidates.length; j++) {
+                const a = candidates[i]; // i 前 j 后：candidates 已按 accessedAt 降序，a 为更近使用方（保留候选）
+                const b = candidates[j]; // b 为较远使用方（重复候选）
+                const similarity = DedupManager.computeNameSimilarity(a.name, b.name);
+                if (similarity <= DEDUP_NAME_SIMILARITY_THRESHOLD) {
+                    allPairs.push({ a, b, nameSimilarity: similarity });
+                }
+            }
+        }
+        // 按相似度升序，越相似越优先处理
+        allPairs.sort((x, y) => x.nameSimilarity - y.nameSimilarity);
+        // 贪心选取：已配对的记忆不再参与后续配对
+        for (const { a, b, nameSimilarity } of allPairs) {
+            if (usedIds.has(a.id) || usedIds.has(b.id))
+                continue;
+            pairs.push({ a, b, nameSimilarity });
+            usedIds.add(a.id);
+            usedIds.add(b.id);
+            if (pairs.length >= DEDUP_PAIR_LIMIT)
+                break;
+        }
+        return pairs;
+    }
+    /** 名称归一化相似度（0-1，越小越相似）。规则：包含关系=0；否则 Levenshtein 距离 / max(len)。 */
+    static computeNameSimilarity(nameA, nameB) {
+        // 空名称防御：includes("") 恒真会误判所有记忆高度相似，故空名与任何名称视为完全不同
+        if (!nameA || !nameB) {
+            return 1;
+        }
+        // 规则 2：包含关系（如"用户偏好" vs "用户偏好设置"）
+        if (nameA.includes(nameB) || nameB.includes(nameA)) {
+            return 0;
+        }
+        // 规则 1：归一化 Levenshtein 距离
+        const maxLen = Math.max(nameA.length, nameB.length);
+        if (maxLen === 0)
+            return 0; // 两个空字符串视为完全相似（已被上面拦截，此处防御）
+        const distance = levenshtein(nameA, nameB);
+        return distance / maxLen;
+    }
+    /**
+     * 调用 LLM 判断单对记忆语义等价：结构化 JSON 输出（isDuplicate+mergedContent+reason）。
+     * 流式累积/解析/异常封装委托 llmJudgeHelper.judgeWithLlm；失败抛 MemoraError 由调用方捕获跳过。
+     */
+    async judgeDuplicate(pair, signal) {
+        const messages = buildDedupMessages(pair);
+        const parsed = await judgeWithLlm(this.backgroundProvider, messages, { maxTokens: 300, timeoutMs: DEDUP_TIMEOUT_MS, signal }, 'LLM 去重判断返回非法 JSON');
+        return {
+            isDuplicate: parsed.isDuplicate === true,
+            mergedContent: typeof parsed.mergedContent === 'string' ? parsed.mergedContent : undefined,
+            reason: typeof parsed.reason === 'string' ? parsed.reason : '(LLM 未提供理由)',
+        };
+    }
+    /** 软删重复记忆（不物理删除保留可恢复；合并内容由 keepMerged 单独写回 a）。重复方以 delete 进入回收站。 */
+    demoteMemory(memory) {
+        this.index.delete(memory.id);
+    }
+    /** 将合并内容写回保留方 a：保持 id/source/name/createdAt 不变，仅刷新 content + accessedAt */
+    keepMerged(memory, mergedContent) {
+        const updated = {
+            ...memory,
+            content: mergedContent,
+            accessedAt: nowIso(),
+        };
+        this.index.upsert(updated);
+        logger.info({ keptId: memory.id }, '语义去重：保留方已合并对方内容');
+    }
+}
+// ─── L1 语义去重 Prompt 模板（模块级函数） ───
+/** 构建语义去重判断的 LLM 消息：system 定义语义等价规则 + user 携带候选对内容预览，few-shot 降误判率 */
+function buildDedupMessages(pair) {
+    const contentA = pair.a.content.length > DEDUP_CONTENT_PREVIEW_LEN
+        ? truncate(pair.a.content, DEDUP_CONTENT_PREVIEW_LEN, '…[截断]')
+        : pair.a.content;
+    const contentB = pair.b.content.length > DEDUP_CONTENT_PREVIEW_LEN
+        ? truncate(pair.b.content, DEDUP_CONTENT_PREVIEW_LEN, '…[截断]')
+        : pair.b.content;
+    return [
+        {
+            role: 'system',
+            content: `你是记忆去重助手。判断给定的两条记忆是否语义等价（表达同一事实/偏好/洞察）。
+
+判断规则：
+- 语义等价 = 核心信息相同，仅措辞/格式/细节程度不同
+- 语义不等价 = 核心信息不同，或一条是另一条的补充/细化（非等价）
+- 忽略时间戳、ID 等元数据差异
+- 忽略措辞风格差异（如"喜欢"vs"偏爱"）
+
+输出 JSON 格式：
+{
+  "isDuplicate": true/false,
+  "mergedContent": "合并后的内容（仅 isDuplicate=true 时提供，保留两条记忆的完整信息）",
+  "reason": "判断理由（简短说明）"
+}
+
+示例：
+输入 A: "用户偏好简洁的 UI 设计"
+输入 B: "用户喜欢简洁的界面风格"
+输出: {"isDuplicate": true, "mergedContent": "用户偏好简洁的 UI/界面设计风格", "reason": "核心偏好相同，仅措辞差异"}
+
+输入 A: "用户是 TypeScript 开发者"
+输入 B: "用户偏好使用 TypeScript 进行后端开发"
+输出: {"isDuplicate": false, "reason": "B 是 A 的细化（限定后端），非语义等价"}`,
+        },
+        {
+            role: 'user',
+            content: `请判断以下两条记忆是否语义等价：
+
+记忆 A（保留候选）：
+- 名称：${pair.a.name}
+- 来源：${pair.a.source}
+- 内容：${contentA}
+
+记忆 B（重复候选）：
+- 名称：${pair.b.name}
+- 来源：${pair.b.source}
+- 内容：${contentB}
+
+名称相似度：${pair.nameSimilarity.toFixed(2)}（0=完全相同，1=完全不同）
+
+请输出 JSON 判断结果。`,
+        },
+    ];
+}
+//# sourceMappingURL=dedupManager.js.map

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

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

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

@@ -0,0 +1,42 @@
+/**
+ * 目标一致性校验器（目标版本一致性校验）。
+ * 两层校验：确定性层（关键约束提取 + 文本相似度）+ LLM 层（可选，仅对需确认场景生成解释）。
+ * 关键约束由确定性规则提取而非 LLM（防自我引用）。漂移等级：same(>0.7 无需确认)/confirm(0.4-0.7 建议确认)/drift(<0.4 需确认)。
+ */
+/** 漂移等级：same(>0.7 自动应用)/confirm(0.4-0.7 建议确认)/drift(<0.4 需确认) */
+export type DriftLevel = 'same' | 'confirm' | 'drift';
+/** 一致性校验结果 */
+export interface GoalConsistencyResult {
+    /** 漂移等级 */
+    level: DriftLevel;
+    /** 文本相似度（0-1） */
+    similarity: number;
+    /** 从 mainGoal 中提取的关键约束列表 */
+    constraints: string[];
+    /** 约束一致性（true = 所有约束均满足，false = 有约束冲突） */
+    constraintsConsistent: boolean;
+    /** 冲突的约束说明（可选，仅 constraintsConsistent 为 false 时有值） */
+    conflictExplanation?: string;
+}
+/** 目标一致性校验器：纯函数式（无状态无副作用），SessionManager / Agent 层直接可用，不依赖外部服务 */
+export declare class GoalConsistencyChecker {
+    /** 提取关键约束：从目标描述中按确定性规则提取"必须/不能/需要/确保"等关键词句段（不依赖 LLM 防自我引用），去重返回 */
+    extractConstraints(goal: string): string[];
+    /** 计算文本相似度：长文本（>20 字符）用 Jaccard，短文本用字符级 bigram（对短文本更敏感） */
+    computeSimilarity(a: string, b: string): number;
+    /** 执行一致性校验：提取约束 → 算相似度定漂移等级（>0.7 same / >=0.4 confirm / else drift）→ 检查约束是否仍满足 */
+    checkConsistency(mainGoal: string, newGoal: string): GoalConsistencyResult;
+    /** 检查约束在新目标是否仍满足：对每条约束提取核心词，任一命中即视为满足；全不满足则标记冲突 */
+    private checkConstraintsConsistent;
+    /** 提取约束核心词：去除标记词保留核心名词短语（如"必须使用TypeScript" → "使用TypeScript"），再按分隔符切分；剥离前缀由 CONSTRAINT_KEYWORDS 生成 */
+    private extractKeywords;
+    /** Jaccard 相似度：分词后交集/并集。分词策略：中文字符逐字 + 英文单词 + 数字 */
+    private jaccardSimilarity;
+    /** 字符级 bigram 相似度：拆相邻字符对求交集/并集，适用于短文本 */
+    private bigramSimilarity;
+    /** 分词：提取中文字符（逐字，对中文更敏感）+ 英文单词（小写）+ 数字；零外部依赖 */
+    private tokenize;
+    /** 获取字符级 bigram：拆相邻字符对（如 "TypeScript" → ["Ty","yp",...]） */
+    private getBigrams;
+}
+//# sourceMappingURL=goalConsistencyChecker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"goalConsistencyChecker.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/goalConsistencyChecker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAgBtD,cAAc;AACd,MAAM,WAAW,qBAAqB;IACpC,WAAW;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0CAA0C;IAC1C,qBAAqB,EAAE,OAAO,CAAC;IAC/B,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,kEAAkE;AAClE,qBAAa,sBAAsB;IACjC,mEAAmE;IACnE,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAqB1C,2DAA2D;IAC3D,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAkB/C,kFAAkF;IAClF,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,qBAAqB;IA6B1E,mDAAmD;IACnD,OAAO,CAAC,0BAA0B;IA6BlC,qGAAqG;IACrG,OAAO,CAAC,eAAe;IAQvB,mDAAmD;IACnD,OAAO,CAAC,iBAAiB;IAgBzB,yCAAyC;IACzC,OAAO,CAAC,gBAAgB;IAgBxB,+CAA+C;IAC/C,OAAO,CAAC,QAAQ;IAgChB,4DAA4D;IAC5D,OAAO,CAAC,UAAU;CAOnB"}

package/dist/agent/managers/goalConsistencyChecker.js

@@ -0,0 +1,178 @@
+/**
+ * 目标一致性校验器（目标版本一致性校验）。
+ * 两层校验：确定性层（关键约束提取 + 文本相似度）+ LLM 层（可选，仅对需确认场景生成解释）。
+ * 关键约束由确定性规则提取而非 LLM（防自我引用）。漂移等级：same(>0.7 无需确认)/confirm(0.4-0.7 建议确认)/drift(<0.4 需确认)。
+ */
+/** 约束关键词单一真源：提取 pattern（全文匹配）与剥离前缀（checkConstraintsConsistent 用）共用，防双列表漂移 */
+const CONSTRAINT_KEYWORDS = [
+    '必须',
+    '不能',
+    '需要',
+    '确保',
+    '禁止',
+    '只能',
+    '至少',
+    '不允许',
+    '应当',
+    '不得',
+];
+/** 目标一致性校验器：纯函数式（无状态无副作用），SessionManager / Agent 层直接可用，不依赖外部服务 */
+export class GoalConsistencyChecker {
+    /** 提取关键约束：从目标描述中按确定性规则提取"必须/不能/需要/确保"等关键词句段（不依赖 LLM 防自我引用），去重返回 */
+    extractConstraints(goal) {
+        if (!goal || goal.trim() === '')
+            return [];
+        const constraints = [];
+        // 约束关键词匹配模式——由 CONSTRAINT_KEYWORDS 单一真源生成（全文匹配）
+        const constraintPatterns = CONSTRAINT_KEYWORDS.map((kw) => new RegExp(`${kw}[^，。！？；\n,;.!?]*`, 'g'));
+        for (const pattern of constraintPatterns) {
+            const matches = goal.match(pattern);
+            if (matches) {
+                constraints.push(...matches.map((m) => m.trim()));
+            }
+        }
+        // 去重
+        return [...new Set(constraints)];
+    }
+    /** 计算文本相似度：长文本（>20 字符）用 Jaccard，短文本用字符级 bigram（对短文本更敏感） */
+    computeSimilarity(a, b) {
+        if (!a && !b)
+            return 1;
+        if (!a || !b)
+            return 0;
+        const aTrim = a.trim();
+        const bTrim = b.trim();
+        if (aTrim === bTrim)
+            return 1;
+        // 短文本：字符级 bigram（对短文本更敏感）
+        if (aTrim.length <= 20 || bTrim.length <= 20) {
+            return this.bigramSimilarity(aTrim, bTrim);
+        }
+        // 长文本：Jaccard
+        return this.jaccardSimilarity(aTrim, bTrim);
+    }
+    /** 执行一致性校验：提取约束 → 算相似度定漂移等级（>0.7 same / >=0.4 confirm / else drift）→ 检查约束是否仍满足 */
+    checkConsistency(mainGoal, newGoal) {
+        const constraints = this.extractConstraints(mainGoal);
+        const similarity = this.computeSimilarity(mainGoal, newGoal);
+        // 确定漂移等级
+        let level;
+        if (similarity > 0.7) {
+            level = 'same';
+        }
+        else if (similarity >= 0.4) {
+            level = 'confirm';
+        }
+        else {
+            level = 'drift';
+        }
+        // 检查约束一致性
+        const { constraintsConsistent, conflictExplanation } = this.checkConstraintsConsistent(constraints, newGoal);
+        return {
+            level,
+            similarity,
+            constraints,
+            constraintsConsistent,
+            conflictExplanation,
+        };
+    }
+    /** 检查约束在新目标是否仍满足：对每条约束提取核心词，任一命中即视为满足；全不满足则标记冲突 */
+    checkConstraintsConsistent(constraints, newGoal) {
+        if (constraints.length === 0) {
+            return { constraintsConsistent: true };
+        }
+        const conflictConstraints = [];
+        for (const constraint of constraints) {
+            // 提取约束核心词并检查新目标是否包含
+            const keywords = this.extractKeywords(constraint);
+            const satisfied = keywords.some((k) => newGoal.includes(k));
+            if (!satisfied) {
+                conflictConstraints.push(constraint);
+            }
+        }
+        if (conflictConstraints.length > 0) {
+            return {
+                constraintsConsistent: false,
+                conflictExplanation: `以下约束在新目标中未体现：${conflictConstraints.join('；')}`,
+            };
+        }
+        return { constraintsConsistent: true };
+    }
+    /** 提取约束核心词：去除标记词保留核心名词短语（如"必须使用TypeScript" → "使用TypeScript"），再按分隔符切分；剥离前缀由 CONSTRAINT_KEYWORDS 生成 */
+    extractKeywords(constraint) {
+        const cleaned = constraint
+            .replace(new RegExp(`^(${CONSTRAINT_KEYWORDS.join('|')})`), '')
+            .trim();
+        const parts = cleaned.split(/[,，、\s]+/).filter(Boolean);
+        return parts.length > 0 ? parts : [cleaned];
+    }
+    /** Jaccard 相似度：分词后交集/并集。分词策略：中文字符逐字 + 英文单词 + 数字 */
+    jaccardSimilarity(a, b) {
+        const tokensA = this.tokenize(a);
+        const tokensB = this.tokenize(b);
+        if (tokensA.size === 0 && tokensB.size === 0)
+            return 1;
+        if (tokensA.size === 0 || tokensB.size === 0)
+            return 0;
+        let intersection = 0;
+        for (const token of tokensA) {
+            if (tokensB.has(token))
+                intersection++;
+        }
+        const union = tokensA.size + tokensB.size - intersection;
+        return union > 0 ? intersection / union : 0;
+    }
+    /** 字符级 bigram 相似度：拆相邻字符对求交集/并集，适用于短文本 */
+    bigramSimilarity(a, b) {
+        const bigramsA = this.getBigrams(a);
+        const bigramsB = this.getBigrams(b);
+        if (bigramsA.size === 0 && bigramsB.size === 0)
+            return 1;
+        if (bigramsA.size === 0 || bigramsB.size === 0)
+            return 0;
+        let intersection = 0;
+        for (const bigram of bigramsA) {
+            if (bigramsB.has(bigram))
+                intersection++;
+        }
+        const union = bigramsA.size + bigramsB.size - intersection;
+        return union > 0 ? intersection / union : 0;
+    }
+    /** 分词：提取中文字符（逐字，对中文更敏感）+ 英文单词（小写）+ 数字；零外部依赖 */
+    tokenize(text) {
+        const tokens = new Set();
+        // 中文字符序列（逐字作为 token）
+        const chineseChars = text.match(/[\u4e00-\u9fff\u3400-\u4dbf]+/g);
+        if (chineseChars) {
+            for (const seq of chineseChars) {
+                for (const char of seq) {
+                    tokens.add(char);
+                }
+            }
+        }
+        // 英文单词（小写归一化，大小写不敏感）
+        const englishWords = text.match(/[a-zA-Z_][a-zA-Z0-9_]*/g);
+        if (englishWords) {
+            for (const word of englishWords) {
+                tokens.add(word.toLowerCase());
+            }
+        }
+        // 数字
+        const numbers = text.match(/\d+/g);
+        if (numbers) {
+            for (const num of numbers) {
+                tokens.add(num);
+            }
+        }
+        return tokens;
+    }
+    /** 获取字符级 bigram：拆相邻字符对（如 "TypeScript" → ["Ty","yp",...]） */
+    getBigrams(text) {
+        const bigrams = new Set();
+        for (let i = 0; i < text.length - 1; i++) {
+            bigrams.add(text.slice(i, i + 2));
+        }
+        return bigrams;
+    }
+}
+//# sourceMappingURL=goalConsistencyChecker.js.map

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

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

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

@@ -0,0 +1,124 @@
+/**
+ * LLM 调用族 — 模型触碰面（重试 / 任务类型路由 / 流式分类）
+ *
+ * 本族的 loop 私有 state 触点**全是「可注入的协作者」**（metrics / strategy / contextManager /
+ * tracer / opts），没有一个是「loop 自己的可变状态」，故经构造注入取值器（getter）取用即可，
+ * 属「换位置仍自治」；而工具编排本体（`executeToolCalls`，多处写 loop 状态）不在此族。
+ *
+ * ## 两条不可回退的纪律
+ *
+ * 1. **必须传 getter 而非快照**：`strategy` / `provider` 均为运行时可热切换
+ *    （`setStrategy` 浅合并新对象、`setProvider` 改 `opts.provider`），且
+ *    `strategy.errorHandling` 在**重试循环体内**被读 3 次——传快照会在重试中途读到旧值。
+ * 2. **`routeCache` 由 loop 持有并跨族共享**：它在**每轮 turn 入口**（`processUserInput`）
+ *    被 `clear()`，而 turn 内单轮问答查表即中——若改为本类实例字段且调用方逐次新建实例，
+ *    **每轮都重算路由**（跨轮缓存失效），而缓存的语义是「单轮内复用，跨轮重置」。故 Map 归
+ *    loop，本类只经读写回调操作它。
+ */
+import type { LlmProvider, Message, ChatOptions } from '../../llm/provider.js';
+import type { ProviderRouter, TaskType, LlmChunk } from '../../llm/types.js';
+import type { AgentChunk, TextChunkStage } from '../../agent/types.js';
+import type { ITracer } from '../../agent/tracer.js';
+import type { LoopMetrics } from '../../agent/managers/loopMetrics.js';
+/** 上下文估算能力窄面（`ContextManager.estimateTokens`） */
+export interface TokenEstimator {
+    estimateTokens(messages: readonly Message[]): number;
+}
+/**
+ * 多模型路由所需的 loop 侧能力子集。
+ * 全部为**取值器 / 回调**而非值快照——保证热切换（`setProvider` / `setStrategy`）即时生效。
+ */
+export interface LlmCallerDeps {
+    /** 运行时指标容器（loop 持有，引用共享；搬走不影响计数正确性） */
+    readonly metrics: LoopMetrics;
+    /** 当前 L2 策略。**必须是 getter**：`errorHandling` 在重试循环内被读 3 次 */
+    readonly getStrategy: () => LlmCallerStrategyView;
+    /** 当前 Provider。**必须是 getter**：`setProvider` 为热切换 */
+    readonly getProvider: () => LlmProvider;
+    /** 任务类型路由回调；未注入时走固定 Provider */
+    readonly getProviderRouter: () => ProviderRouter | undefined;
+    /** 路由缓存读（Map 归 loop 持有，见文件头纪律 2） */
+    readonly getCachedProvider: (taskType: TaskType) => LlmProvider | undefined;
+    /** 路由缓存写 */
+    readonly setCachedProvider: (taskType: TaskType, provider: LlmProvider) => void;
+    /** 上下文管理器（token 估算） */
+    readonly contextManager: TokenEstimator;
+    /** 追踪器 */
+    readonly tracer: ITracer;
+    /** 本闭环是否已执行过工具。**必须是 getter**：同一 turn 内会被 set true */
+    readonly hasToolExecutedThisTurn: () => boolean;
+}
+/** `LlmCaller` 实际读取的策略字段（避免整体依赖 `L2RuntimeStrategy` 造成接口面膨胀） */
+export interface LlmCallerStrategyView {
+    /** 出错处理：'stop' 立即抛出 / 'degrade' 降级为已生成文本 / 其余走重试 */
+    readonly errorHandling: string;
+    /** 'manual' → 强制低推理深度（provider 支持时） */
+    readonly multiStepReasoning: string;
+    /** 'fixed' → 跳过路由，固定用默认 Provider */
+    readonly providerRouting: string;
+}
+/** LLM 调用结果（loop 侧消费者：`_callAndRoute` / `handleToolCalls` / `handleAskUser` /
+ *  `handleTextResponse`，均在本族之外，故为导出类型） */
+export interface LlmCallResult {
+    fullContent: string;
+    toolCalls: Message['toolCalls'];
+    aborted: boolean;
+    /**
+     * 文本通道剥离缓冲：工具轮叙述文本（本闭环已执行过工具后的整条消息文本，
+     * 或收到 toolCalls 信号后后续/同条的 content）累积于此。结果路由据此发射
+     * narrate 事件，不进回答正文；纯文本闭环（无工具史）正文保持按流式实时 yield。
+     */
+    pendingNarrate: string;
+    /**
+     * 本轮正文是否曾逐字流式 yield（工具闭环内延迟分类的消息未 yield → false）。
+     * 结果路由据此在纯文本/中断路径补发整段 text，避免缓冲文本对 UI 不可见。
+     */
+    textStreamed: boolean;
+    /**
+     * 回抽：本闭环内逐字流式 yield 进正文区的**原文**（stage='answer'）。
+     *
+     * 首轮（无工具史）消息级分类前无法预判工具轮 → 文本已实时流式进正文；一旦收到 toolCalls，
+     * 结果路由据此发 `narrate.withdrawn` 告知消费者「该段其实属过程叙述，先撤回再渲染」。
+     * 纯文本闭环（正文即最终交付）与工具闭环内延迟分类路径（未 yield）恒为空串。
+     */
+    streamedText: string;
+    /**
+     * 末次 chat 尝试回传的 finish_reason（诊断分型证据）。
+     * `'length'` = 输出预算截断（思考/生成吃满上限），loop 据此把空响应判「截断型」；
+     * 中转不回传则 undefined = 按「瞬态型」降级（降级不劣化，维持现状文案）。
+     */
+    finishReason?: LlmChunk['finishReason'];
+    /** 末次 chat 尝试的 thinking 字符数（reasoning_content 增量累计；无思考模型恒 0。重试重置，取末次口径） */
+    thinkingChars: number;
+    /** 收场前的 chat 尝试总数（1 = 首试即收场；空响应重试累加。重试属同一步内的多次尝试，非多个 step） */
+    attempts: number;
+}
+/**
+ * 确定当前回合任务类型（多模型路由）：含代码块→code；长文本(>500字符)→reasoning；其余→simple
+ *
+ * 纯函数（零 state 触点），独立导出便于单测与复用。
+ */
+export declare function determineTaskType(messages: readonly Message[]): TaskType;
+/** LLM 调用执行器：多模型路由 + 指数退避重试 + 流式文本通道分类 */
+export declare class LlmCaller {
+    private readonly deps;
+    constructor(deps: LlmCallerDeps);
+    /**
+     * 多模型路由：按任务类型选 Provider；单轮内缓存同一 taskType 结果，避免重复路由计算。
+     * 三分支收敛：strategy='fixed' → 默认 Provider；有 providerRouter → 路由 + 缓存；否则 fallback 默认。
+     */
+    resolveProvider(safeMessages: readonly Message[]): LlmProvider;
+    /**
+     * 调用 LLM（带指数退避重试，仅在流式输出前失败时重试；流式已开始则直接上抛，因用户已看到部分结果）。
+     * 经 providerRouter 按任务类型路由到对应 Provider。
+     */
+    callWithRetry(safeMessages: readonly Message[], chatOpts: ChatOptions, signal: AbortSignal | undefined, iteration: number, 
+    /** 流式文本阶段标识（默认正常交付 'answer'；自审查应答由调用方传 'self_review'） */
+    stage?: TextChunkStage): AsyncGenerator<AgentChunk, LlmCallResult, unknown>;
+    /**
+     * 重试延迟 + abort 支持：发射 retry chunk，等待指数退避延迟（支持中途 abort）；
+     * 调用方在延迟后自行检查 signal.aborted 决定是否退出重试循环
+     */
+    waitForRetryWithAbort(attempt: number, lastError: Error | null, signal: AbortSignal | undefined): AsyncGenerator<AgentChunk, void, unknown>;
+}
+//# sourceMappingURL=llmCaller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmCaller.d.ts","sourceRoot":"","sources":["../../../src/agent/managers/llmCaller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAQnE,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAC;CACtD;AAQD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,qBAAqB,CAAC;IAClD,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,WAAW,CAAC;IACxC,gCAAgC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAC7D,oCAAoC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,WAAW,GAAG,SAAS,CAAC;IAC5E,YAAY;IACZ,QAAQ,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAChF,uBAAuB;IACvB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,UAAU;IACV,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,uBAAuB,EAAE,MAAM,OAAO,CAAC;CACjD;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,oCAAoC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;0CAC0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACxC,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,QAAQ,CAuBxE;AAED,0CAA0C;AAC1C,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD;;;OAGG;IACH,eAAe,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,GAAG,WAAW;IAgB9D;;;OAGG;IACI,aAAa,CAClB,YAAY,EAAE,SAAS,OAAO,EAAE,EAChC,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM;IACjB,yDAAyD;IACzD,KAAK,GAAE,cAAyB,GAC/B,cAAc,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC;IA8TrD;;;OAGG;IACI,qBAAqB,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,KAAK,GAAG,IAAI,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC;CA0B7C"}