@co-engram/core 0.1.0

package/dist/retrieval/orchestrator.js

@@ -0,0 +1,156 @@
+/**
+ * 检索编排器
+ *
+ * 协调 FTS / 过滤器 / 三因子排序，返回 Catalog Entry 列表
+ *
+ * P1 阶段实现（2.3）：
+ *   - FTS 相关度（归一化到 [0,1]）
+ *   - 三因子打分：α·relevance + β·recency + γ·importance
+ *   - 权重可通过 setWeights() 配置
+ *   - 同输入同输出（prompt cache 友好）
+ *
+ * P2 阶段会增加：
+ *   - 向量余弦相似度（RRF 融合）
+ *   - 动态自适应披露集成
+ *
+ * @module @co-engram/core/retrieval
+ */
+import { buildFtsIndex, searchFts } from "./fts.js";
+import { applyFilter } from "./filter.js";
+import { computeThreeFactorScore, DEFAULT_WEIGHTS, validateWeights, } from "./scoring.js";
+/**
+ * 检索器
+ *
+ * 需要先调用 `build()` 构建 FTS 索引；后续搜索复用索引
+ */
+export class SearchOrchestrator {
+    ftsIndex = null;
+    lines = [];
+    weights = DEFAULT_WEIGHTS;
+    nowFn = () => new Date();
+    /**
+     * 构建 FTS 索引
+     */
+    build(lines) {
+        this.lines = lines;
+        this.ftsIndex = buildFtsIndex(lines);
+    }
+    /**
+     * 配置三因子权重（默认 α=0.5, β=0.3, γ=0.2）
+     *
+     * 会校验和为 1。
+     */
+    setWeights(weights) {
+        validateWeights(weights);
+        this.weights = weights;
+    }
+    /** 读取当前权重 */
+    getWeights() {
+        return this.weights;
+    }
+    /**
+     * 注入时钟函数（测试用，避免依赖系统时间）
+     */
+    setClock(nowFn) {
+        this.nowFn = nowFn;
+    }
+    /**
+     * 搜索
+     *
+     * @param query - 查询字符串
+     * @param filter - 过滤器（可选）
+     * @param limit - 最大结果数（默认 20）
+     */
+    search(query, filter, limit = 20) {
+        if (!this.ftsIndex) {
+            throw new Error("SearchOrchestrator not built. Call build() first.");
+        }
+        // 1. FTS 搜索
+        const hits = searchFts(query, this.ftsIndex, limit * 3);
+        if (hits.length === 0)
+            return [];
+        // 2. 归一化 FTS score 到 [0,1]（除以 max）
+        const maxFts = hits[0].score;
+        const now = this.nowFn();
+        // 3. 应用过滤器 + 三因子打分
+        const scored = [];
+        for (const hit of hits) {
+            const line = this.ftsIndex.docs.get(hit.docId);
+            if (!line)
+                continue;
+            if (!applyFilter([line], filter).includes(line))
+                continue;
+            const relevance = maxFts > 0 ? hit.score / maxFts : 0;
+            const score = computeThreeFactorScore(relevance, line, {
+                now,
+                weights: this.weights,
+            });
+            scored.push({ id: line.id, score, line });
+        }
+        // 4. 稳定排序：按 score 倒序，同分按 id 字典序（prompt cache 友好）
+        scored.sort((a, b) => {
+            if (a.score !== b.score)
+                return b.score - a.score;
+            return a.id < b.id ? -1 : 1;
+        });
+        return scored.slice(0, limit).map((item) => ({
+            id: item.id,
+            score: item.score,
+            entry: {
+                id: item.line.id,
+                title: item.line.title,
+                kind: item.line.kind,
+                domainTags: item.line.domainTags,
+            },
+        }));
+    }
+    /**
+     * 按过滤器列出（无查询）
+     *
+     * 不打相关度分（score=0），按原顺序返回。
+     * 可通过 listByImportance() 获取按 importance 排序的列表。
+     */
+    listByFilter(filter, limit = 100) {
+        const filtered = applyFilter(this.lines, filter);
+        return filtered.slice(0, limit).map((line) => ({
+            id: line.id,
+            score: 0,
+            entry: {
+                id: line.id,
+                title: line.title,
+                kind: line.kind,
+                domainTags: line.domainTags,
+            },
+        }));
+    }
+    /**
+     * 按 importance + recency 排序列出（无 query）
+     *
+     * 用于"最近有效的最重要 engram"类查询（如首页推荐）。
+     */
+    listByImportance(filter, limit = 100) {
+        const filtered = applyFilter(this.lines, filter);
+        const now = this.nowFn();
+        const scored = filtered.map((line) => ({
+            id: line.id,
+            score: computeThreeFactorScore(0, line, { now, weights: this.weights }),
+            line,
+        }));
+        scored.sort((a, b) => {
+            if (a.score !== b.score)
+                return b.score - a.score;
+            return a.id < b.id ? -1 : 1;
+        });
+        return scored.slice(0, limit).map((item) => ({
+            id: item.id,
+            score: item.score,
+            entry: {
+                id: item.line.id,
+                title: item.line.title,
+                kind: item.line.kind,
+                domainTags: item.line.domainTags,
+            },
+        }));
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/retrieval/orchestrator.js.map

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

package/dist/retrieval/scoring.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 三因子检索打分
+ *
+ * 实现 spec 3.7：
+ *   score = α·relevance + β·recency + γ·importance
+ *
+ * 其中：
+ *   - relevance ∈ [0,1]：来自 FTS 归一化分（或向量余弦，P2 引入）
+ *   - recency ∈ [0,1]：`0.5^(ageDays / decayHalfLifeDays)`（Ebbinghaus 衰退）
+ *     · decayHalfLifeDays=null → recency=1（永不衰退）
+ *     · ageDays ≤ 0（未来/刚刚）→ recency=1
+ *   - importance ∈ [0,1]：`engram.importance × (1 + reinforcementScore)`
+ *     · reinforcementScore 由 P1 2.1 三信号追踪累积
+ *     · 用 min 截断到 [0,1]，避免上溢
+ *
+ * 默认权重：α=0.5, β=0.3, γ=0.2（spec 3.7 / 决策 9）
+ *
+ * 排序稳定性：相同输入产生相同输出（不依赖 Math.random/Date.now）。
+ *
+ * @module @co-engram/core/retrieval
+ */
+import type { DigestLine } from "../index/types.js";
+/** 三因子权重配置 */
+export interface ThreeFactorWeights {
+    /** relevance 权重（语义/关键词匹配） */
+    readonly alpha: number;
+    /** recency 权重（艾宾浩斯衰退） */
+    readonly beta: number;
+    /** importance 权重（价值） */
+    readonly gamma: number;
+}
+/** 默认权重（spec 3.7：α=0.5, β=0.3, γ=0.2） */
+export declare const DEFAULT_WEIGHTS: ThreeFactorWeights;
+/**
+ * 校验权重和为 1（容差 0.001）
+ */
+export declare function validateWeights(w: ThreeFactorWeights): void;
+/**
+ * 艾宾浩斯衰退函数
+ *
+ * `recency = 0.5^(ageDays / decayHalfLifeDays)`
+ *
+ * - decayHalfLifeDays=null/undefined → 1（永不衰退）
+ * - decayHalfLifeDays<=0 → 1（非法半衰期视为不衰退）
+ * - ageDays<=0 → 1（未来或刚刚）
+ */
+export declare function recencyDecay(ageDays: number, decayHalfLifeDays: number | null | undefined): number;
+/**
+ * 有效重要性
+ *
+ * `effectiveImportance = importance × (1 + reinforcementScore)`
+ *
+ * 截断到 [0,1]，避免 reinforcement 累积导致 > 1。
+ *
+ * - reinforcementScore 由 P1 2.1 累积（每次 reinforce 加 effectiveness）
+ * - 高 reinforcement → importance 接近原值上限
+ */
+export declare function effectiveImportance(importance: number, reinforcementScore: number): number;
+/**
+ * 从 DigestLine + relevance 计算三因子得分
+ *
+ * @param relevance - 归一化相关度 [0,1]
+ * @param line - DigestLine（含 recency/importance 数据）
+ * @param lastEffectiveAt - 最后有效检索时间（可选，省略则用 line.lastEffectiveAt）
+ * @param now - 当前时间（可选，便于测试；省略则 new Date()）
+ * @param weights - 权重配置（可选，省略用默认）
+ */
+export declare function computeThreeFactorScore(relevance: number, line: DigestLine, options?: {
+    lastEffectiveAt?: string | null;
+    now?: Date;
+    weights?: ThreeFactorWeights;
+}): number;
+/**
+ * 三因子批量打分（保持原数组顺序，稳定排序友好）
+ */
+export declare function computeThreeFactorScores(items: ReadonlyArray<{
+    id: string;
+    relevance: number;
+    line: DigestLine;
+}>, options?: {
+    now?: Date;
+    weights?: ThreeFactorWeights;
+}): ReadonlyArray<{
+    id: string;
+    score: number;
+}>;
+/**
+ * Reciprocal Rank Fusion (RRF)
+ *
+ * 将多个 rank list 融合为一个综合 rank。
+ * 常用场景：FTS top-K + 向量 top-K → 综合 top-K。
+ *
+ * 公式：`score(d) = Σ 1 / (k + rank_i(d))`，其中 k 默认 60（业界经验值）。
+ *
+ * - rank 从 1 开始；未出现在某 list 中的 doc 不贡献分
+ * - 输出按融合分倒序
+ *
+ * @param rankedLists - 多个有序 id 列表（每个 list 已经按相关度从高到低排好）
+ * @param k - 平滑常数（默认 60）
+ */
+export declare function reciprocalRankFusion(rankedLists: ReadonlyArray<ReadonlyArray<string>>, k?: number): ReadonlyArray<{
+    id: string;
+    score: number;
+}>;
+//# sourceMappingURL=scoring.d.ts.map

package/dist/retrieval/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../src/retrieval/scoring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,cAAc;AACd,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,EAAE,kBAI7B,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAY3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,MAAM,CAIR;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACzB,GACL,MAAM,CAmBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,EACzE,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACzB,GACL,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAK9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,EACjD,CAAC,SAAK,GACL,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB9C"}

package/dist/retrieval/scoring.js

@@ -0,0 +1,165 @@
+/**
+ * 三因子检索打分
+ *
+ * 实现 spec 3.7：
+ *   score = α·relevance + β·recency + γ·importance
+ *
+ * 其中：
+ *   - relevance ∈ [0,1]：来自 FTS 归一化分（或向量余弦，P2 引入）
+ *   - recency ∈ [0,1]：`0.5^(ageDays / decayHalfLifeDays)`（Ebbinghaus 衰退）
+ *     · decayHalfLifeDays=null → recency=1（永不衰退）
+ *     · ageDays ≤ 0（未来/刚刚）→ recency=1
+ *   - importance ∈ [0,1]：`engram.importance × (1 + reinforcementScore)`
+ *     · reinforcementScore 由 P1 2.1 三信号追踪累积
+ *     · 用 min 截断到 [0,1]，避免上溢
+ *
+ * 默认权重：α=0.5, β=0.3, γ=0.2（spec 3.7 / 决策 9）
+ *
+ * 排序稳定性：相同输入产生相同输出（不依赖 Math.random/Date.now）。
+ *
+ * @module @co-engram/core/retrieval
+ */
+/** 默认权重（spec 3.7：α=0.5, β=0.3, γ=0.2） */
+export const DEFAULT_WEIGHTS = {
+    alpha: 0.5,
+    beta: 0.3,
+    gamma: 0.2,
+};
+/**
+ * 校验权重和为 1（容差 0.001）
+ */
+export function validateWeights(w) {
+    const sum = w.alpha + w.beta + w.gamma;
+    if (Math.abs(sum - 1) > 0.001) {
+        throw new Error(`Weights must sum to 1, got ${sum} (α=${w.alpha} β=${w.beta} γ=${w.gamma})`);
+    }
+    for (const v of [w.alpha, w.beta, w.gamma]) {
+        if (v < 0 || v > 1) {
+            throw new Error(`Weight must be in [0,1], got ${v}`);
+        }
+    }
+}
+/**
+ * 艾宾浩斯衰退函数
+ *
+ * `recency = 0.5^(ageDays / decayHalfLifeDays)`
+ *
+ * - decayHalfLifeDays=null/undefined → 1（永不衰退）
+ * - decayHalfLifeDays<=0 → 1（非法半衰期视为不衰退）
+ * - ageDays<=0 → 1（未来或刚刚）
+ */
+export function recencyDecay(ageDays, decayHalfLifeDays) {
+    if (!decayHalfLifeDays || decayHalfLifeDays <= 0)
+        return 1;
+    if (ageDays <= 0)
+        return 1;
+    return Math.pow(0.5, ageDays / decayHalfLifeDays);
+}
+/**
+ * 有效重要性
+ *
+ * `effectiveImportance = importance × (1 + reinforcementScore)`
+ *
+ * 截断到 [0,1]，避免 reinforcement 累积导致 > 1。
+ *
+ * - reinforcementScore 由 P1 2.1 累积（每次 reinforce 加 effectiveness）
+ * - 高 reinforcement → importance 接近原值上限
+ */
+export function effectiveImportance(importance, reinforcementScore) {
+    if (reinforcementScore <= 0) {
+        return clamp01(importance);
+    }
+    // 衰减式提升：避免 importance × (1+∞) → 1
+    // P1 简化：直接 importance × (1 + reinforcementScore)，clamp 到 [0,1]
+    return clamp01(importance * (1 + reinforcementScore));
+}
+/**
+ * 从 DigestLine + relevance 计算三因子得分
+ *
+ * @param relevance - 归一化相关度 [0,1]
+ * @param line - DigestLine（含 recency/importance 数据）
+ * @param lastEffectiveAt - 最后有效检索时间（可选，省略则用 line.lastEffectiveAt）
+ * @param now - 当前时间（可选，便于测试；省略则 new Date()）
+ * @param weights - 权重配置（可选，省略用默认）
+ */
+export function computeThreeFactorScore(relevance, line, options = {}) {
+    const weights = options.weights ?? DEFAULT_WEIGHTS;
+    validateWeights(weights);
+    const now = options.now ?? new Date();
+    const lastEffective = options.lastEffectiveAt ?? line.lastEffectiveAt;
+    const ageDays = computeAgeDays(lastEffective, now);
+    const recency = recencyDecay(ageDays, line.decayHalfLifeDays);
+    const importance = effectiveImportance(line.importance, line.reinforcementScore);
+    return (weights.alpha * clamp01(relevance) +
+        weights.beta * recency +
+        weights.gamma * importance);
+}
+/**
+ * 三因子批量打分（保持原数组顺序，稳定排序友好）
+ */
+export function computeThreeFactorScores(items, options = {}) {
+    return items.map((item) => ({
+        id: item.id,
+        score: computeThreeFactorScore(item.relevance, item.line, options),
+    }));
+}
+/**
+ * Reciprocal Rank Fusion (RRF)
+ *
+ * 将多个 rank list 融合为一个综合 rank。
+ * 常用场景：FTS top-K + 向量 top-K → 综合 top-K。
+ *
+ * 公式：`score(d) = Σ 1 / (k + rank_i(d))`，其中 k 默认 60（业界经验值）。
+ *
+ * - rank 从 1 开始；未出现在某 list 中的 doc 不贡献分
+ * - 输出按融合分倒序
+ *
+ * @param rankedLists - 多个有序 id 列表（每个 list 已经按相关度从高到低排好）
+ * @param k - 平滑常数（默认 60）
+ */
+export function reciprocalRankFusion(rankedLists, k = 60) {
+    if (k <= 0) {
+        throw new Error(`RRF k must be > 0, got ${k}`);
+    }
+    const scores = new Map();
+    for (const list of rankedLists) {
+        for (let i = 0; i < list.length; i++) {
+            const id = list[i];
+            const rank = i + 1;
+            const contribution = 1 / (k + rank);
+            scores.set(id, (scores.get(id) ?? 0) + contribution);
+        }
+    }
+    return Array.from(scores.entries())
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        // 稳定排序：同分按 id 字典序（保证可重现）
+        return a.id < b.id ? -1 : 1;
+    });
+}
+// ============================================================
+// 辅助函数
+// ============================================================
+function clamp01(x) {
+    if (Number.isNaN(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+function computeAgeDays(lastEffectiveAt, now) {
+    if (!lastEffectiveAt)
+        return Number.POSITIVE_INFINITY; // 从未有效 → age = ∞ → recency → 0
+    const ts = new Date(lastEffectiveAt).getTime();
+    if (Number.isNaN(ts))
+        return Number.POSITIVE_INFINITY;
+    const ageMs = now.getTime() - ts;
+    if (ageMs < 0)
+        return 0; // 时钟偏差/未来
+    return ageMs / (1000 * 60 * 60 * 24);
+}
+//# sourceMappingURL=scoring.js.map

package/dist/retrieval/scoring.js.map

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

package/dist/signals/extract.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 行为信号提取规则引擎（P4 A.3）
+ *
+ * 从 ToolCallEvent 流中推断每条 engram 的"真实效用",不依赖 agent 自律上报。
+ *
+ * 设计：
+ *   - 数据驱动：每条规则是 { name, weight, match } 纯函数
+ *   - 可组合：DEFAULT_RULES 是 6 条内置规则的组合
+ *   - 可扩展：宿主可以传入自己的 rules
+ *
+ * 规则说明（按 weight 强弱）：
+ *   强正(≥ 0.6):repeated_get / get_then_action / contradicts_deleted
+ *   弱正(0.2-0.5):get_no_resimilar_search
+ *   强负(≤ -0.6):get_then_immediate_search / contradicts_created
+ *   弱负(-0.2 - -0.5):user_correction
+ *
+ * @module @co-engram/core/signals
+ */
+import type { BehavioralSignal, ToolCallEvent } from "./types.js";
+/** 默认 sliding window 大小 */
+export declare const DEFAULT_WINDOW_SIZE = 10;
+/** 单条规则 */
+export interface SignalRule {
+    /** 规则名（用于审计） */
+    readonly name: string;
+    /** 默认权重 [-1, 1] */
+    readonly weight: number;
+    /** 匹配函数：从事件流提取信号 */
+    match(events: readonly ToolCallEvent[], options?: SignalRuleOptions): readonly BehavioralSignal[];
+}
+export interface SignalRuleOptions {
+    readonly windowSize?: number;
+}
+/**
+ * 提取所有规则的信号并合并去重
+ *
+ * 合并策略：同 (engramId, source) 取 weight 绝对值最大的；不同 source 全部保留。
+ */
+export declare function extractSignals(events: readonly ToolCallEvent[], rules?: readonly SignalRule[], options?: SignalRuleOptions): readonly BehavioralSignal[];
+/**
+ * 去重：同 (engramId, source) 取绝对值最大
+ */
+export declare function dedupeSignals(signals: readonly BehavioralSignal[]): readonly BehavioralSignal[];
+/**
+ * 规则 1：同 sliding window 内同一 engram 被 engram_get ≥ 2 次
+ *
+ * 神经科学依据：反复访问 = 强化（retrieval + reinforcement）
+ * weight: +0.6（强正）
+ */
+export declare const repeatedGetRule: SignalRule;
+/**
+ * 规则 2：engram_get 后跟 file_edit / bash / git_commit 等动作
+ *
+ * 含义：从"读"变成"做",有落地证据
+ * weight: +0.8（强正）
+ */
+export declare const getFollowedByActionRule: SignalRule;
+/**
+ * 规则 3：engram_get 后 windowSize 内没有 engram_search 同主题
+ *
+ * 含义：读了一次就够了,问题已解决
+ * weight: +0.4（弱正）
+ *
+ * 注意：这是"沉默的满意"信号,容易误判（可能只是没继续做）。weight 较弱。
+ */
+export declare const getFollowedByNoSearchRule: SignalRule;
+/**
+ * 规则 4：engram_get 后 < 3 事件立即 engram_search 同主题
+ *
+ * 含义：get 没解决问题,要再找
+ * weight: -0.7（强负）
+ */
+export declare const getThenImmediateSearchRule: SignalRule;
+/**
+ * 规则 5：用户消息包含纠正词
+ *
+ * 纠正词表："不对" / "错了" / "should be" / "actually" / "wait" / "不是"
+ * 信号来源：tool args 里如果有 message / prompt / reply 字段包含纠正词
+ *
+ * 注意：这是一个保守的近似——真正的用户消息可能在 transcript 里但不在 tool args 里。
+ * 后续 hook 改造后可以从专门的 user_message 事件类型捕获。
+ *
+ * weight: -0.4（弱负）
+ */
+export declare const userCorrectionRule: SignalRule;
+/**
+ * 规则 6：创建 contradicts synapse 指向某 engram
+ *
+ * 含义：被显式反驳
+ * weight: -0.8（强负）
+ *
+ * 注意：被 contradicts 不等于被 refute（refute 是 verificationStatus 状态机的事）。
+ * 这里只记录信号,后续 metacognition 会综合其他维度决定是否 refute。
+ */
+export declare const contradictsCreatedRule: SignalRule;
+/** 默认规则集（按 weight 从强到弱排序,仅影响审计日志可读性,不影响结果） */
+export declare const DEFAULT_RULES: readonly SignalRule[];
+//# sourceMappingURL=extract.d.ts.map

package/dist/signals/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/signals/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAElE,2BAA2B;AAC3B,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,WAAW;AACX,MAAM,WAAW,UAAU;IACzB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,KAAK,CACH,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,KAAK,GAAE,SAAS,UAAU,EAAkB,EAC5C,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,gBAAgB,EAAE,CAO7B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACnC,SAAS,gBAAgB,EAAE,CAU7B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UAgD7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,UA8CrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,UAuCvC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,UAyCxC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAiDhC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAyBpC,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EAO9C,CAAC"}