dsh-data-domain-knowledge 0.1.0-alpha.1

package/lib/types/migrate.js

@@ -0,0 +1,280 @@
+/**
+ * 0029 的一次性迁移：把旧布局的知识树搬进新根路径。
+ *
+ * ## 为什么要迁移
+ *
+ * 0029 之前，「知识树在哪」由用户直接设的那个 `rootDir` 决定，而它指向的是**知识树
+ * 本身** —— `01_source_truth` 直接躺在它下面。新布局多了一层：`rootDir` 变成
+ * `agentRoot`，知识树退到 `<agentRoot>/domain_knowledge/<知识库 id>`。
+ *
+ * 也就是说，对**改过** `rootDir` 的用户，磁盘上那棵树的位置变了。数据不能跟着
+ * 设置一起改语义就消失，所以这里搬一次。
+ *
+ * ## 四条纪律
+ *
+ * 1. **只在真的有必要时动手。** 四个前置条件缺一不可：旧设置非空、旧位置确实是一棵
+ *    知识树、新位置不是同一处、新旧不是同一个目录。
+ * 2. **目标已有树就不碰。** 那说明用户已经在新布局下建过库，旧的那棵不是它的前身；
+ *    合并两棵来路不同的树比不迁移更糟。
+ * 3. **逐个目录搬，且只搬目标里还没有的。** 这既让迁移可重入（中断后重跑接着搬），
+ *    也保证永远不覆盖目标里已有的数据。
+ * 4. **搬不动就如实说，不回滚也不假装。** 失败时返回 `failed` 与原因，两边数据
+ *    都留在原地；调用方把它写进 `/knowledge/stats`，界面上能看到。
+ *
+ * 用同步 fs：迁移发生在设置解析的回调里，而 runtime 必须在**迁移完成之后**才按新
+ * 路径构造 —— 异步化会把这段顺序打散。搬的是目录项（`rename` 是元数据操作，与树
+ * 的大小无关），跨卷时退化成复制，代价可控。
+ *
+ * @module
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, rmSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { knowledgeBaseRoot, looksLikeKnowledgeTree, memoryRoot, resourceRoot } from './layout.js';
+/**
+ * 知识树的段。与 `runtime.ts` 的 `LAYOUT` 同源，这里重列是为了不引入 runtime 依赖。
+ *
+ * 0030 撤掉了 `00_schema`：它从建出来起就是空目录，分类与 Wiki 类型注册表一直住在
+ * `<agentRoot>/resource/knowledge-bases.json`。这里也一并去掉，免得迁移又把一个
+ * 没人用的空目录建回新树上。
+ *
+ * 0032 撤掉了 `04_memory`：记忆（版本快照 / 反馈 / 访问审计）搬到了
+ * `<agentRoot>/memory/<库 id>`，由 `migrateLegacyMemory` 负责搬。它留在这里会让
+ * 知识树迁移把 `04_memory` 当成「一段知识」搬进新树 —— 那是搬错方向。
+ */
+const LAYOUT_DIRS = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'];
+/** 无需迁移的结论。 */
+function skipped(reason, from, to) {
+    return { status: 'skipped', reason, ...(from ? { from } : {}), ...(to ? { to } : {}) };
+}
+/**
+ * 把 `legacyRoot` 下的知识树搬进 `<agentRoot>/domain_knowledge/<kbId>`。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.legacyRoot - 用户旧设置里的知识树根；空串表示没有旧设置。
+ * @param input.kbId - 承接这棵树的知识库 id，缺省 `default`。
+ * @returns 迁移结论。**不抛异常** —— 迁移失败不该让插件起不来。
+ */
+export function migrateLegacyKnowledgeTree(input) {
+    const to = knowledgeBaseRoot(input.agentRoot, input.kbId ?? 'default');
+    const legacy = input.legacyRoot?.trim();
+    if (!legacy)
+        return skipped('没有旧的根目录设置', undefined, to);
+    const from = resolve(legacy);
+    if (from === resolve(to))
+        return skipped('新旧路径相同', from, to);
+    if (!existsSync(from))
+        return skipped('旧路径不存在', from, to);
+    if (!looksLikeKnowledgeTree(from))
+        return skipped('旧路径不是一棵知识树', from, to);
+    // 目标已经是一棵树 = 用户已在新布局下建过库，旧的那棵不是它的前身。
+    if (looksLikeKnowledgeTree(to))
+        return skipped('新位置已有一棵知识树，不覆盖', from, to);
+    const moved = [];
+    try {
+        mkdirSync(to, { recursive: true });
+        for (const name of LAYOUT_DIRS) {
+            const source = join(from, name);
+            const target = join(to, name);
+            if (!existsSync(source) || existsSync(target))
+                continue;
+            try {
+                renameSync(source, target);
+            }
+            catch (cause) {
+                // 跨卷（EXDEV）或权限受限：退化成复制 + 删除，语义仍然是「搬」。
+                if (cause?.code !== 'EXDEV')
+                    throw cause;
+                cpSync(source, target, { recursive: true });
+                rmSync(source, { recursive: true, force: true });
+            }
+            moved.push(name);
+        }
+    }
+    catch (cause) {
+        return {
+            status: 'failed',
+            from,
+            to,
+            moved,
+            reason: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+    if (moved.length === 0)
+        return skipped('旧位置没有可搬的目录', from, to);
+    return { status: 'moved', from, to, moved, reason: `已搬迁 ${moved.length} 个目录` };
+}
+/**
+ * 0029：把 Agent 的**家当**从 `~/.tita-data-agent` 搬进 `<agentRoot>/resource`。
+ *
+ * 搬三样：`models/` → `resource/models`、`embedding-venv/` → `resource/python`、
+ * `knowledge-bases.json` → `resource/knowledge-bases.json`。
+ *
+ * ## 四条纪律
+ *
+ * 1. **先 rename，不先 copy。** 这三样加起来 2.7G，而 `~/.tita-data-agent` 与默认
+ *    根路径在同一个卷上，`rename` 是元数据操作、瞬间完成。跨卷（EXDEV）时**不自动
+ *    复制** —— 一个 2.7G 的静默复制可能填满磁盘、可能花十分钟，那不是迁移该偷偷
+ *    做的事，所以如实报 `failed` 让用户自己决定。
+ * 2. **目标已存在就不动。** 用户可能已经在新位置放了自己的模型；覆盖它是不可接受
+ *    的失败。
+ * 3. **只搬存在的。** 全新安装没有这些东西，那就不搬，不是错误。
+ * 4. **按条目合并，不按目录整体跳过。** 「目标目录存在」不等于「这一样搬完了」：
+ *    用户可能只往 `resource/models/` 里放了一个重排模型，而 `models/` 里的嵌入模型
+ *    还留在旧位置 —— 整体跳过会让它**永远搬不过来**（因为迁移只跑一次）。所以
+ *    `models/` 逐个子项搬，目标里已有的子项跳过。这同时让迁移更可重入。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.legacyHome - 旧的 `TITA_DATA_AGENT_HOME`（默认 `~/.tita-data-agent`）。
+ * @returns 迁移结论；`moved` 里是真正搬过去的项（`models/<名字>` 会带上子项名）。
+ */
+export function migrateLegacyResources(input) {
+    const from = resolve(input.legacyHome);
+    const to = resourceRoot(input.agentRoot);
+    if (from === resolve(to))
+        return { status: 'skipped', reason: '家当目录与根路径相同', from, to };
+    if (!existsSync(from))
+        return { status: 'skipped', reason: '旧家当目录不存在', from, to };
+    /**
+     * 一样家当的搬法：`source` 是一个目录时逐个子项合并，是文件时整体搬。
+     * 返回真正搬过去的条目名。
+     */
+    const move = (source, target) => {
+        if (!existsSync(source))
+            return [];
+        if (!statSync(source).isDirectory()) {
+            if (existsSync(target))
+                return [];
+            renameSync(source, target);
+            return [basename(source)];
+        }
+        const moved = [];
+        for (const name of readdirSync(source)) {
+            const child = join(source, name);
+            const childTarget = join(target, name);
+            if (existsSync(childTarget))
+                continue;
+            mkdirSync(target, { recursive: true });
+            renameSync(child, childTarget);
+            moved.push(name);
+        }
+        return moved;
+    };
+    const plan = [
+        ['models', join(to, 'models')],
+        ['embedding-venv', join(to, 'python')],
+        ['knowledge-bases.json', join(to, 'knowledge-bases.json')],
+    ];
+    const moved = [];
+    try {
+        let created = false;
+        for (const [name, target] of plan) {
+            const source = join(from, name);
+            if (!existsSync(source))
+                continue;
+            if (!created) {
+                mkdirSync(to, { recursive: true });
+                created = true;
+            }
+            try {
+                /**
+                 * 报告粒度按**这一样家当是不是一个集合**来分：
+                 *
+                 * - `models/` 是集合，而「目标里已经有别的模型」正是最容易出问题的情况，
+                 *   所以要报**哪几个**搬了（`models/WeMM-Embedding-2B-Quantized`）；
+                 * - `embedding-venv` / `knowledge-bases.json` 是单件，报一次就够。
+                 *
+                 * 这里原来写的是「按 `move()` 返回的条目逐个 push 类别名」，于是 venv 有几个
+                 * 子目录就报几次 `embedding-venv` —— 实测报出 8 项，而真正搬的是 3 项。
+                 */
+                const items = move(source, target);
+                if (name === 'models')
+                    for (const item of items)
+                        moved.push(`${name}/${item}`);
+                else if (items.length > 0)
+                    moved.push(name);
+            }
+            catch (cause) {
+                // 跨卷：**不复制**。2.7G 的静默复制不是迁移该做的事。
+                if (cause?.code === 'EXDEV') {
+                    return { status: 'failed', from, to, moved, reason: `${name} 与根路径不在同一个卷上，需要你手动搬（不自动复制，因为可能有几个 GB）` };
+                }
+                throw cause;
+            }
+            // 搬空了的旧目录不留着：它只会让人以为家当还在那儿。
+            try {
+                rmdirSync(source);
+            }
+            catch { /* 还有别的东西在里面，保留 */ }
+        }
+    }
+    catch (cause) {
+        return { status: 'failed', from, to, moved, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+    if (moved.length === 0)
+        return { status: 'skipped', reason: '家当已经在新位置，或旧位置没有可搬的', from, to };
+    return { status: 'moved', from, to, moved, reason: `已搬迁 ${moved.length} 项家当` };
+}
+/**
+ * 0032：把记忆段从知识树里搬出来 —— `<知识库根>/04_memory` → `<agentRoot>/memory/<库 id>`。
+ *
+ * ## 为什么搬
+ *
+ * 记忆装的是版本快照、反馈与访问审计：它们是**关于这个 Agent 的动作留痕**，不是
+ * 关于知识的断言。留在知识树里有三个说不通的地方：备份知识树被迫连审计流水一起
+ * 备份；「知识树有哪几段」这个问题里混进了一个横切层；多知识库时每棵树各存一份
+ * 同构的流水。搬出来之后知识树只剩知识，记忆与它平级、同样按库分叉。
+ *
+ * ## 纪律
+ *
+ * 与家当迁移同源，但**这里允许合并**：目标里已经有同名条目时跳过（用户可能已经
+ * 在新位置写过记忆），其余照搬。跨卷时退化成复制 + 删除 —— 记忆是**数据**，不是
+ * 可以重新下载的模型，所以这里不像家当迁移那样「不自动复制」：丢掉版本历史比
+ * 复制几百 MB 严重得多。
+ *
+ * @param input.agentRoot - 新的 Tita Agent 根路径。
+ * @param input.kbRoot - 这个知识库的根（`<agentRoot>/domain_knowledge/<id>`）。
+ * @param input.kbId - 知识库 id，决定记忆落在 `memory/` 下的哪一格。
+ * @returns 迁移结论。**不抛异常** —— 迁移失败不该让插件起不来。
+ */
+export function migrateLegacyMemory(input) {
+    const from = join(resolve(input.kbRoot), '04_memory');
+    const to = memoryRoot(input.agentRoot, input.kbId);
+    if (resolve(from) === resolve(to))
+        return skipped('记忆段与目标位置相同', from, to);
+    if (!existsSync(from))
+        return skipped('这个知识库里没有旧的记忆段', from, to);
+    const moved = [];
+    try {
+        for (const name of readdirSync(from)) {
+            const source = join(from, name);
+            const target = join(to, name);
+            if (existsSync(target))
+                continue;
+            mkdirSync(to, { recursive: true });
+            try {
+                renameSync(source, target);
+            }
+            catch (cause) {
+                if (cause?.code !== 'EXDEV')
+                    throw cause;
+                // 跨卷：记忆是数据，**复制 + 删除**，与家当迁移的「不自动复制」不同。
+                cpSync(source, target, { recursive: true });
+                rmSync(source, { recursive: true, force: true });
+            }
+            moved.push(name);
+        }
+    }
+    catch (cause) {
+        return { status: 'failed', from, to, moved, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+    // 搬空了的旧段删掉：留着它会让人以为记忆还在知识树里（而且它会出现在「知识树
+    // 有哪几段」的扫描里）。还有东西没搬走就保留。
+    try {
+        rmdirSync(from);
+    }
+    catch { /* 还有别的东西在里面 */ }
+    if (moved.length === 0)
+        return skipped('记忆已经在新位置', from, to);
+    return { status: 'moved', from, to, moved, reason: `已把记忆搬到 ${to}（${moved.length} 项）` };
+}
+//# sourceMappingURL=migrate.js.map

package/lib/types/migrate.js.map

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

package/lib/types/recall-rank.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 召回链路的**纯函数**部分（0031）：融合、boost、去冗余、证据抽取。
+ *
+ * 与 `graph/layout.ts`、`problem-domains.ts` 同一个理由：把不依赖 runtime、不碰磁盘的
+ * 那部分单独放，于是它们可以在 `node:test` 里被直接断言。这里的每个函数都对应 0031
+ * 的一个设计决定，注释写的是**为什么**，不是做了什么。
+ *
+ * @module
+ */
+import type { RecallEvidence, RecallRoute } from './types.js';
+/** 一路的排序结果（已过阈值、已按分数降序）。 */
+export interface RouteRanking {
+    unitId: string;
+    /** 该路自己的分数，只用于阈值与展示 —— 融合不读它。 */
+    score: number;
+}
+export interface FusedHit {
+    unitId: string;
+    score: number;
+    /** 每一路的名次（1 起）。缺失 = 那一路没有召回它。 */
+    ranks: Partial<Record<RecallRoute, number>>;
+}
+export interface RrfOptions {
+    /** RRF 的平滑常数；越大越平（削弱第一名）。WeKnora 默认 60。 */
+    k: number;
+    weights: Partial<Record<RecallRoute, number>>;
+}
+/**
+ * 名次级融合（Reciprocal Rank Fusion）。
+ *
+ * **为什么不用分数加权和**：三路的分数是三个不同的量纲 —— 关键词是归一化 BM25、
+ * 向量是余弦、图谱是命中分/最大命中分。把它们乘权重相加，等于假设「0.5 的关键词分」
+ * 与「0.5 的余弦」一样好，而这个假设没有任何依据。0030 的实际后果就是：向量路输出
+ * 常数时，hybrid 的 55% 权重全是噪声，排序退化成 `unitId` 字典序（实测 4 条命中
+ * 分数完全相同：`0.2753 = 0.5 × 0.55`）。
+ *
+ * RRF 只吃**名次**，所以量纲问题从根上消失，而权重变成「我更信哪一路的排序」——
+ * 这是一个可以校准、也可以被解释的量。
+ */
+export declare function rrfFuse(rankings: Partial<Record<RecallRoute, RouteRanking[]>>, options: RrfOptions): FusedHit[];
+/**
+ * 图谱作为**boost**，不是第三路。
+ *
+ * 0009/0014 都把知识图谱定位为**构建产物**（wiki→图谱），没有把它当作召回路线；
+ * 而 0030 把它做成第三路时，匹配逻辑与关键词路同源（词面匹配 title / id / 关系词），
+ * 等于把关键词路的弱点复制一遍，还多贡献了一份不可比的分数。
+ *
+ * 现在的语义是：图谱命中的实体及其 1 跳邻居，**只给已经在候选池里的条目**加一个
+ * RRF 项。它因此不能凭自己制造候选（那是「路」的权力），只能重排（那是「boost」的
+ * 职责）—— 于是它既保留了「命中实体 → 带出邻居」的价值，又不会污染融合。
+ */
+export declare function graphBoost(fused: FusedHit[], graphRanking: RouteRanking[], options: RrfOptions): {
+    hits: FusedHit[];
+    applied: number;
+};
+/**
+ * 按阈值裁剪一路的候选，并给出这一路的诊断。
+ *
+ * 关键词路的分是**相对**归一的（见 `fts.ts` 的量纲说明），所以这里的阈值挡得住
+ * 「弱命中」、挡不住「整批都弱」；向量路的分是原始余弦，是绝对的。两者都要如实
+ * 写进诊断，不能让人以为「过了阈值」等于「相关」。
+ */
+export declare function applyThreshold(ranking: RouteRanking[], threshold: number): {
+    kept: RouteRanking[];
+    dropped: number;
+    topScore: number;
+};
+/**
+ * 从原文里挑出与查询最相关的若干段，作为**证据片段**。
+ *
+ * 为什么要有这一步：`context` 原来只带 wiki 卡片，模型要核对原文还得再调一次工具。
+ * 把证据放进上下文，「每一个数字都能指回它的口径定义与原始文档」才在上下文层面
+ * 成立，而不是靠模型自觉去查。
+ *
+ * 段落按空行切（Markdown 的自然段），逐段算**查询词覆盖率**，取最高的几段。
+ * 覆盖率是绝对的，所以「找不到相关段落」会如实返回空数组，而不是硬塞一段无关文字。
+ */
+export declare function evidenceExcerpts(sourceId: string, title: string | undefined, text: string, queryTerms: string[], options?: {
+    maxExcerpts?: number;
+    maxChars?: number;
+    minCoverage?: number;
+}): RecallEvidence[];
+/**
+ * 一条 note 进关键词索引的**完整文本**。
+ *
+ * 它包含三部分：标题、正文、以及**溯源身份**（它引用的 sourceId 与那些来源的标题）。
+ * 溯源身份不是锦上添花：图谱降为 boost 之后，「只提到某份来源、没提到任何卡片正文」
+ * 的查询再也没有第二条路可走，所以「这份台账派生出了哪些结论」必须由关键词路回答。
+ *
+ * 这个函数被**两处**共用 —— 建索引时写进去的文本，与召回时算查询词覆盖率的文本。
+ * 两处各写一份的话，覆盖率会对着不同的文本算，好命中会被静默丢掉（实测：查 `ledger`
+ * 时索引命中了、覆盖率却是 0）。
+ */
+export declare function noteIndexText(note: {
+    title: string;
+    content: string;
+    sourceRefs: string[];
+}, titleOf: (sourceId: string) => string | undefined): string;
+/** 一段文本的词集合，用于 MMR 的冗余度（Jaccard）。 */
+export declare function tokenSet(text: string): Set<string>;
+export interface MmrOptions<T> {
+    /** 相关性（通常就是融合分）。 */
+    relevance: (item: T) => number;
+    /** 该条目的词集合。 */
+    tokens: (item: T) => Set<string>;
+    /** 该条目属于哪张 wiki —— 用于「每张卡最多几条」的硬约束。 */
+    wikiKey: (item: T) => string;
+    /** 相关性 vs 多样性的权衡；0.7 = 偏相关性（与 WeKnora 的 grep_chunks 一致）。 */
+    lambda?: number;
+    /** 每张 wiki 最多入选几条。 */
+    perWikiCap?: number;
+    /** 总共要几条。 */
+    limit: number;
+}
+/**
+ * 选上下文条目：**每张 wiki 封顶 + MMR 去冗余**。
+ *
+ * 为什么必须有：0030 的图谱路刻意给同一张 wiki 的分节 note 0.8 的权重，于是 5 条上下文
+ * 可以全部来自同一张卡 —— 一屏塞满、信息量为 1。这是「召回质量差」里最容易被忽略的一半：
+ * 前 5 条不是「5 条相关」，而是「1 条相关的 5 个片段」。
+ *
+ * 冗余度用**词集合的 Jaccard**，不用向量：它对编码器是否可用不敏感，因此去冗余在
+ * 向量路降级时依然生效 —— 依赖一个可能坏掉的组件的功能，等于把它的可靠性绑在那个组件上。
+ */
+export declare function selectContext<T>(items: T[], options: MmrOptions<T>): T[];
+/** `match` 字段由名次推导：两路及以上命中 = hybrid。 */
+export declare function matchOf(ranks: Partial<Record<RecallRoute, number>>): 'fts' | 'vector' | 'graph' | 'hybrid';
+/** 展示用的概率：`rerankScore` 是 logit 的 sigmoid。 */
+export declare function sigmoidLogit(logit: number): number;
+export interface RerankOutcome<T> {
+    /** 过阈值的条目，按 logit 降序；`rerankScore` 是 logit 的 sigmoid。 */
+    kept: Array<T & {
+        rerankScore: number;
+    }>;
+    /** 被阈值丢掉的条数。 */
+    dropped: number;
+    /** 候选池里最高的 logit —— 跨查询可比的「这一批到底有多相关」。 */
+    topLogit: number;
+}
+/**
+ * Stage 4：**在 logit 刻度上**过阈值，展示值才做一次 sigmoid。
+ *
+ * 刻度必须只有一个。cross-encoder 的价值就在于此：它的分是**跨查询可比**的，
+ * 所以「低于 0.2 就不要」是一个绝对判据，而关键词/向量的阈值做不到这一点。
+ * 0031 落地时这里错了两层：
+ *
+ * 1. worker 用 `CrossEncoder.predict` 的默认行为，拿到的是 **sigmoid 之后**的值
+ *    （(0,1)），却按 logit 阈值 0.2 去比 —— 于是 `dropped` 恒为 0，绝对闸门从未生效。
+ * 2. Host 又 sigmoid 了一次做展示，把无关文档（logit −10.2）显示成 `0.500`
+ *    —— 一个「看起来刚好在门槛上」的分数。
+ *
+ * 现在 worker 返回 logit（`predict_raw`），阈值与排序都在 logit 上，展示只 sigmoid 一次。
+ * 这个函数是纯的，所以刻度这件事可以在 `node:test` 里被钉住。
+ */
+export declare function applyRerank<T extends {
+    unitId: string;
+}>(scores: number[], items: T[], threshold: number): RerankOutcome<T>;
+//# sourceMappingURL=recall-rank.d.ts.map

package/lib/types/recall-rank.d.ts.map

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