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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoneFire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+# dsh-data-domain-knowledge
+
+本地知识库插件：`01_source_truth` 保存 **SourceRaw**（原始可追溯文档），`02_wiki` 保存
+按主题聚合、可双向链接的 wiki 卡片，`03_compiled` 输出可检索的 **wikiNotes**、wiki
+知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存版本快照、访问审计与反馈。默认使用本地 WeMM Python backend：从 WeMM
+原生 2048 维向量按 MRL 截取 1024 维，先做 binary/Hamming 粗筛，再用 int8 点积精算余弦
+（这是**向量路内部的粗排 → 精算**，与 stage 4 的 cross-encoder **重排**不是一回事）；
+模型不可用时明确降级到 FTS，不会伪造向量结果。Markdown 中的
+本地图片会与正文一起交给 WeMM，因此图片不是独立知识类型。
+
+## 承载范围（五个视图 = 一个挂载单元）
+
+侧边栏 `TitaAgent` 面板声明的五个视图就是本插件的全部范围，`src/` 的目录结构按它们组织：
+
+| 视图 | 面板标签 | 宿主实现 | 冻结契约 |
+| --- | --- | --- | --- |
+| `overview` | Agent 概览 | `src/index.ts` | 各设置的挂载节点 |
+| `intent` | 意图 | `src/intent/`（0020 自 `data-domain-intent` 并入）；配置与留痕落 `<agentRoot>/intent/` | `intent_*` 工具名、`/intent/*` 路由、`tita-data-agent-intent` 设置、`titaDataAgentIntent` 服务 |
+| `knowledge` | 知识库 | `src/runtime.ts` + `src/knowledge-bases.ts` + `src/convert/`（0018 并入） | `recall_knowledge` 等工具名、`/knowledge/*` 与 `/convert` 路由、`tita-data-agent-knowledge` / `-convert` 设置 |
+| `memory` | 记忆 | `src/runtime.ts` 的 `memoryPath()`（版本快照、`feedback.ndjson`、`access-audit.ndjson`），根在 `<agentRoot>/memory/<库 id>` | 磁盘目录布局 |
+| `eval` | 评测 | `eval/evaluate-retrieval.mjs`（开发期能力，不注册运行时入口） | 问题集格式 |
+
+**架构原理：插件的数量应当等于用户入口的数量，而不是概念的数量；而插件的名字应当指向主干概念，不指向子域。**
+意图／知识库／记忆／评测是四个概念，但它们共享同一条流水线（记录意图 → 录入来源 → 编译知识 →
+沉淀记忆 → 评测质量）和同一个入口（面板的五个 Tab）。0020 之前，「意图」Tab 已经长在本插件里、
+宿主实现却在第二个挂载单元里——**声明的信息架构与代码布局不一致**，这才是要修的东西。
+
+意图的**配置与留痕**落在 `<agentRoot>/intent/`（0033）：`registry.json` 是分类 / act 词表的
+真源（面板的「意图配置」直接读写这个文件，不再写宿主的 settings 文档），`records.ndjson`
+是每轮一条记录的 append-only 留痕（按 `sessionKey#turn` 读时取最后一条，所以内存里
+「一轮一条」的语义不变）。读接口 `/intent/store` 与 `/intent/overview` 读的是**留痕**：
+引擎内存里那份有 600 秒 TTL，重启或隔一段时间回来不该让面板上的历史凭空消失。
+
+`src/intent/` 的宿主半与 `src/client/IntentTab.tsx` 的浏览器半之间**必须保留 HTTP 边界**（`/intent/*`）：
+两者分处两个 bundle，无法直接互相 import。这与 0018 删掉的 `POST /knowledge/sources` 不同——
+那次是宿主→宿主的回环，可以改成进程内调用。
+
+## 五段链路
+
+| 段 | 名称 | 产物 | 关键配置 |
+| --- | --- | --- | --- |
+| 1 | SourceRaw | 原始可追溯文档：`01_source_truth/*.md` | `allowSourceTruth` / `rootDir` |
+| 2 | 编译 Compile | wiki：`02_wiki`（按主题聚合、可双向链接）；wikiNotes：`03_compiled/wiki_notes.json` | `schemaTypes` |
+| 3 | 构建 Build | wikiNotes → 向量索引；wiki → `03_compiled/knowledge_graph.json` | `embeddingProvider` / `embeddingModel` / `python` |
+| 4 | 召回 Recall | 多路（关键词 + 向量 + 知识图谱）召回 wikiNotes，取 `recallTopK`（默认 10），再解析父级 wiki 与该 wiki 的 1 跳知识图谱 | `recallTopK` / `recallMode` |
+| 5 | 重排 Rerank | BERT cross-encoder 对候选 wikiNotes 精排，取 `contextTopN`（默认 5）组成 `context` | `contextTopN` / `rerankProvider` / `rerankModel` |
+
+> 0033：第 4、5 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步
+> ——架构图里也仍是两个节点——但「跑一次真实召回长什么样」是一个问题，分两栏会让用户
+> 先跑召回、再切到重排才能看到同一次运行的全貌，而且两栏各有一个测试按钮。
+
+> 术语迁移：SourceRaw 曾叫 SourceRow / SourceTruth。磁盘目录 `01_source_truth`、工具名
+> `add_source` / `query_source_truth`、HTTP `/knowledge/sources`、设置键 `allowSourceTruth`
+> 与错误码 `SOURCE_TRUTH_DISABLED` 作为兼容名保留，语义等同 SourceRaw。
+> 本轮的「编译 / 构建」仍是同一次 `rebuild()`：编译的**按主题聚合**由 Agent 完成，
+> **wiki↔wiki 双向链接**与**分阶段重建**是设计目标，图谱当前只有 `supported_by` 溯源边。
+
+- 设置项**不再有独立入口**：它们挂在 Agent 概览架构图的对应节点上（SourceRaw → 收录开关与
+  知识库根目录；编译 → Schema；构建 → Embedding / Python；召回 → topK / 默认路线；
+  重排 → topN / reranker；意图与上下文 → 意图路由），每个节点只保存本节点字段。
+- 编译期一条 wiki 至少产出一条 note；正文按 `##`/`###` 分节且超过 800 字符时按节切分，
+  首条 note 的 `unitId` 保持 `<entityType>:<entityId>`，后续为 `<entityType>:<entityId>#<n>`，
+  每条 note 都带 `wikiId` 指回父级 wiki。`03_compiled/knowledge_units.json` 作为旧版兼容镜像保留。
+- `recall_knowledge` 返回 `hits`（重排后的 wikiNotes）、`context`（`{ note, wiki, graph }[]`）、
+  `wiki`、`graph`、`routes`、`recallMode`、`rerank`、`recallTopK`、`contextTopN`；入参 `top_k`
+  控制召回条数（`limit` 为兼容别名），`top_n` 控制进入上下文的条数，`mode` 覆盖默认召回路线，
+  `rerank: false` 可单次关闭重排。
+- `rerankProvider` 默认 `bert-python`，模型默认 `BAAI/bge-reranker-base`
+  （存在 `~/.tita-data-agent/models/bge-reranker-base` 时优先用本地目录）。重排在独立
+  Python worker 进程中进行，模型缺失或超时时按融合分数返回并在 `warnings` 说明，
+  不会反复重试；`rerankProvider: 'none'` 完全跳过重排。
+
+## 本地启用 WeMM
+
+在 Apple Silicon 上执行一次：
+
+```bash
+./plugins/dsh-data-domain-knowledge/scripts/setup-embedding.sh
+```
+
+脚本会把 Python 环境放到 `~/.tita-data-agent/embedding-venv`，把量化模型放到
+`~/.tita-data-agent/models/WeMM-Embedding-2B-Quantized`，不会把 1.8GB 权重提交
+进仓库。新配置会自动发现这两个路径；如果 DSH 中已经保存过旧配置，则在
+Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
+
+- Provider：`WeMM Python（本地）`
+- Python：`~/.tita-data-agent/embedding-venv/bin/python`
+- Model：`~/.tita-data-agent/models/WeMM-Embedding-2B-Quantized`
+- 维度：`1024`
+- 设备：`自动（优先 MPS）`
+
+知识库默认保存在 `~/.tita-data-agent/knowledge`；设置了 `DSH_KNOWLEDGE_ROOT`
+或已有旧的仓库内 `domain_knowledge` 时会优先沿用。点击「编译」后，
+`03_compiled` 会生成 `wiki_notes.json`、`knowledge_graph.json`、
+`vector-manifest.json`、`vectors.binary` 和 `vectors.int8`。未修改的 wikiNote
+会复用已有向量，只有新增或变更的 note 重新编码；编码与重排各自使用常驻 Python
+worker（同一份 `src/python/embedding_worker.py`），避免每个请求重复加载模型。
+
+BERT 重排默认使用 `BAAI/bge-reranker-base`；如需完全离线，可把模型放到
+`~/.tita-data-agent/models/bge-reranker-base`（会被自动发现），或设置
+`DSH_RERANK_MODEL` / 在设置里填写本地路径。未安装时召回会降级到融合分数并给出警告。
+**目录必须含分词器**（`tokenizer.json` 或 `sentencepiece.bpe.model`）——只有权重时模型会
+加载成功但给所有输入同一个分（`RERANK_TOKENIZER_DEGENERATE`），见
+`docs/0024-本地模型运行时.md`。
+
+知识写入、编译、SourceRaw 读取和召回支持统一的
+`sessionId/turnId/intentId/taskId/subtaskId/runId/traceId/domain` lineage。卡片把
+创建和状态变更写入 `provenance`，编译报告返回 `compileRunId`，召回返回
+`recallId`；这些事件也会进入 `memory/<库 id>/access-audit.ndjson`，便于从最终产物
+反查到原始任务。
+
+可以通过工具 `check_knowledge_embeddings` 或 `GET /knowledge/embedding/health`
+查看 provider、模型、设备、索引条数和最后一次错误。
+
+## 格式转换（convert seam，0018）
+
+多格式转换的 **DSH 宿主层**自 0018 起就在本插件里：不再是第二个挂载插件，而是本插件的一个
+子模块（`src/convert/`），共用同一次挂载、同一个侧边栏 Tab、同一套 runtime。
+
+```
+plugins/dsh-data-domain-knowledge/src/convert/
+  ├─ host.ts         工具 /convert_*、路由 /convert/**、设置、面板
+  ├─ ingest.ts       唯一写入口：ingestDelivery() → runtime.addSource()
+  ├─ core-loader.ts  可选内核的懒加载与降级
+  └─ types.ts
+packages/dsh-convert-core   内核（不挂载，可独立运行：node bin/tita-convert.mjs）
+  └─ @firecrawl/anydoc  MIT / Rust / 预编译绑定：doc docx ppt pptx xls xlsx odt ods odp rtf epub csv 文本层 PDF
+```
+
+| 项 | 值 |
+| --- | --- |
+| 工具 | `convert_capabilities` / `convert_source` / `convert_task` / `convert_ingest`（后两个写操作需本轮审批） |
+| 路由 | `/convert/**`（含内核 Vue3 控制台） |
+| 设置命名空间 | `tita-data-agent-convert`（冻结契约，由本插件安装） |
+| 交付目录 | `~/.tita-data-agent/convert-out/<taskId>/`（`index.md` / `assets/` / `manifest.json`） |
+
+**依赖是可选的。** `dsh-convert-core` 声明在 `optionalDependencies`，由
+`core-loader.ts` 在首次调用时 `import()`。平台没有 anydoc 预编译绑定、或用户显式不装时，
+`convert_*` 与 `/convert` 面板返回 `DEPENDENCY_MISSING` 并给出安装建议，**knowledge 本体
+（`add_source` / 编译 / 召回）照常可用**。不要把它改成静态 import：有一条测试守着这件事。
+
+**入库是进程内调用。** `ingestDelivery()` 直接调 `runtime.addSource()`，不再走
+`POST /knowledge/sources` 回环。少了一次 JSON 序列化，也因此没有旧的 ~1.2 MB body 上限。
+单条 SourceRaw **没有字符数上限**：`maxSourceBytes` 在 0029 撤掉了（先撤面板上的字段，
+后来连运行层那道闸门一起撤 —— 只撤面板等于留一个用户改不了、也找不到的硬上限）。
+真正的边界是转换内核的 `maxInputBytes`（管入口大小）与嵌入分批（管模型输入）。
+
+三条红线（改这一块前先读）：
+
+1. 内核不 import knowledge，产物只写 `convert-out/`；
+2. 转换代码写知识库只能经 `ingest.ts` 的 `IngestTarget.addSource`，别处不许直接落 `01_source_truth`；
+3. 0017 的网页 / 视频 / OCR 应做成**可选适配器包**注册进内核，不要继续往本插件里塞 ffmpeg / whisper。
+
+## 多知识库与文档（0021）
+
+一个**知识库 = 独立配置 + 独立内容**（产品参照 WeKnora）。注册表持久化在
+`<dataHome>/knowledge-bases.json`，`dataHome = process.env.TITA_DATA_AGENT_HOME || ~/.tita-data-agent`。
+默认库 id 固定为 `default`，其 `rootDir` 始终来自插件设置 `rootDir`（缺省
+`defaultKnowledgeRoot()`）；**不传 `kb` 的旧接口与旧工具一律作用于默认库，行为不变**。
+
+```ts
+interface KnowledgeBase { id; name; description; rootDir; isDefault; sourceTypes; wikiTypes; wikiSchemaMode; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
+```
+
+`sourceCount` / `cardCount` / `noteCount` / `buildVersion` 和每条分类/类型的计数都是
+**计算字段**，由 `KnowledgeBases.refresh()` 从真实 runtime 重新统计并缓存进同一个 JSON，
+所以 `list()` / `get()` 保持同步签名，HTTP `GET /knowledge/bases` 在返回前先
+`await refresh()`。
+
+0029 / 0032：**根路径下是六段**：
+
+| 段 | 装什么 | 删掉的后果 |
+| --- | --- | --- |
+| `domain_knowledge/` | 知识树，按知识库 id 分叉 | 丢数据 |
+| `memory/<知识库 id>/` | 版本快照、反馈、访问审计（append-only） | 丢历史，不可重建 |
+| `intent/` | `registry.json`（分类 / act 词表）+ `records.ndjson`（每轮一条留痕） | 丢配置与审计流 |
+| `output/` | 交付物，二级按日期分桶 | 什么都不损失 |
+| `tmp/` | 运行期临时文件，二级按日期分桶 | 只影响未完成的任务 |
+| `resource/` | 模型、Python 环境、`knowledge-bases.json` | 失去语义检索（嵌入/重排不可用） |
+
+**记忆与意图为什么与知识树平级**（0032 的架构调整）：记忆装的是版本快照与审计流水 ——
+那是**关于这个 Agent 的动作留痕**，不是关于知识的断言；留在知识树里会让「备份知识树」
+被迫连审计一起备份，也让「知识树有哪几段」这个问题混进一个横切层。意图则是**会话级**的
+（同一句话在哪个知识库下说，理解方式不该变），所以它不分库；它的两份东西原来一个住在
+宿主的 settings 文档里、一个只在内存里，都不是「这个 Agent 自己的文件」。搬出来之后，
+知识、记忆、意图三段都是可以直接备份、直接 diff 的用户文件。
+
+知识树内部（`domain_knowledge/<知识库 id>/`）0032 起是**四段**：`00_schema`（0030 撤，
+它从建出来起就是空目录）与 `04_memory`（0032 搬去 `memory/`）都已不在。
+
+| 段 | 装什么 | 删掉的后果 |
+| --- | --- | --- |
+| `01_source_truth/<source_type>/` | SourceRaw，一级是**来源分类**，二级是文档 | 丢数据 |
+| `02_wiki/<entity_type>/` | Wiki 卡片，一级是卡片类型 | 丢结论 |
+| `03_compiled/` | wikiNotes / 向量 / 知识图谱 | 可重建 |
+| `05_diagnosis/` | 智能归因图谱 | 可重建 |
+
+`00_schema` 撤掉的依据：它从建出来那天起就是一个**空目录**。分类注册表与 Wiki 类型
+注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是配置，跟着根路径走）；
+`00_schema` 里没有一行代码写过东西。「磁盘上有一个文件夹」本身是一种承诺，空着就是
+误导。`ensureLayout` 会在启动时把空的 `00_schema` 删掉 —— **非空则保留**：那就不属于
+「没用的空文件夹」了，删掉别人的文件比留一个空目录危险得多。
+
+`01_source_truth` 按分类分目录（而不是平铺）的理由与 `02_wiki` 一致：分类是每份来源的
+必备元数据（frontmatter 的 `source_type`），提到目录名上之后「按分类找东西」在文件系统
+层面直接成立，不依赖界面。平铺在真实使用里会先变成垃圾场 —— 几十份来源混在一层，`ls`
+读不出「我的指标口径在哪」。启动时一次性把平铺的文档搬进分类目录；读路径不依赖这个层级
+（`sourceIndex` 递归扫全段建 slug → path 索引），所以旧布局、新布局与两者并存的中间态
+都能读。**改分类 = 换目录**：`add_source` 用同一 `sourceId` 配新 `sourceType` 时，旧目录
+里那份会被删掉，不会留下孤儿。
+
+`resource/` 是 0029 新增的：模型与虚拟环境原来住在 `~/.tita-data-agent`，现在搬进
+根路径 —— 「这个 Agent 的全部磁盘足迹」因此是一个目录，备份 / 迁移 / 整个删掉都只
+需要认一个路径。启动时一次性搬迁（先 `rename`，跨卷**不自动复制**，因为可能有几个
+GB）；旧的 `TITA_DATA_AGENT_HOME` 留在解析链上作为兜底，所以搬与没搬都能跑。
+搬迁**按条目合并**：`resource/models/` 里已经有用户自己放的模型时，仍会把旧的嵌入模型
+搬进来，只跳过同名的那个 —— 否则「目标目录存在」会让另一样东西永远搬不过来。
+
+配置里 `python` / `embeddingModel` / `rerankModel` 三个字段的**默认值改成了空串 =
+自动**：按 `<agentRoot>/resource/…` → 旧家当目录 → 兜底名（`python3` / HF 模型名）
+的顺序解析。设置面板用占位符显示解析后的真实路径，并在**家当不在 `resource/` 下时
+逐条告警**（「还在旧位置、重启会搬」和「根本不是路径、迁移搬不了」要做的事不同）。
+
+> ⚠️ 这三个字段的 schema **不能写 `.min(1)`**。schemastery 与 zod 不同，它会**校验默认值
+> 本身**，`z.string().min(1).default('')` 会让 `settings.installSection()` 在登记命名空间
+> 时直接抛 —— 后果是整个设置分区注册不上（面板「设置服务不可用」）、家当迁移不执行、
+> `settings.yaml` 里的值一个都不生效，而界面上没有任何原因。见
+> `src/settings-schema.ts` 的模块注释与 `tests/settings-schema.test.mjs`。
+
+向量清单里记的模型名也从绝对路径改成了 `local:<模型目录名>` —— **身份与位置解耦**，
+否则把模型搬一次就让整个索引判成「配置不匹配」而作废。
+
+0029：**「文件类型 → 解析引擎」那张规则表已撤。** 它唯一被读的地方是浏览器决定
+「这份文件直读还是送转换内核」，而那个判断现在只看扩展名本身（`DIRECT_READ_EXT`）；
+真正决定用哪个适配器的是**转换内核自己的格式表**（`ANYDOC/SCANNED/IDDOC/TEXT_EXTENSIONS`），
+它从来不读这张表 —— 也就是说「把 .docx 设成直读文本」这类配置**改了不生效**。撤掉
+之后：上传选择框的 `accept` 问内核要（`/convert/api/capabilities`），文件类型筛选项
+和计数从**这一库真实的文档**推导。两边都不可能再与内核漂移。
+
+**文档扩展名 `ext` 的推导是有损的**（`deriveSourceExt`，代码注释同）：优先取
+`metadata.source_path` 的 basename 扩展名；否则 `source_format === 'markdown'` → `.md`，
+`'office'` → `.docx`，其余 → `.` + `source_format`；都没有 → `.md`。只有上游
+`convert/ingest.ts` 写了 `source_path` 时才精确。
+
+文档的 `parser` 字段说的是**谁解析了这份文档**：经转换内核进来的由
+`convert/ingest.ts` 写 `metadata.parser`（如 `anydoc@1/pdf`），直接写进来的
+（`add_source`、浏览器直读文本）是 `direct` —— 没有解析器。0029 之前这里会按扩展名
+猜一个引擎名（`.pdf` → `anydoc`），那是在陈述一件没有发生过的事。
+
+### HTTP API
+
+```text
+GET    /knowledge/bases                                            → { bases, defaultBaseId }
+POST   /knowledge/bases        { name, description?, rootDir? }    → { base }
+PATCH  /knowledge/bases/:id    { name?, description?, sourceTypes?, wikiTypes?, wikiSchemaMode? } → { base }
+DELETE /knowledge/bases/:id                                        → { deleted: true }
+GET    /knowledge/documents?kb=&query=&source_type=&limit=&offset= → { documents, total }
+GET    /knowledge/documents/:docId?kb=                             → { document }
+GET    /knowledge/documents/:docId/versions?kb=                    → { versions }
+POST   /knowledge/documents/:docId/revert?kb= { versionId }        → { document }
+DELETE /knowledge/documents/:docId?kb=                             → { deleted: true }
+GET    /knowledge/assets/:kb/*                                     → 知识库根目录下的文件流
+```
+
+`/knowledge/stats`、`/knowledge/search`、`/knowledge/rebuild`、`/knowledge/cards`、
+`/knowledge/sources`、`/knowledge/graph`、`/knowledge/embedding/health` 与全部
+`*_knowledge*` 工具都接受**可选** `kb`（query 或 body 字段）。`docId` 含 `:`
+（如 `document:ab12…`），必须 URL 编码。
+
+### 删除守卫（409）
+
+| 操作 | 条件 | 错误码 | HTTP |
+| --- | --- | --- | --- |
+| `DELETE /knowledge/bases/:id/source-types/:typeId` | 内置分类 | `SOURCE_TYPE_BUILTIN_LOCKED` | 409 |
+| `DELETE /knowledge/bases/:id/source-types/:typeId` | 该分类下还有来源 | `SOURCE_TYPE_IN_USE` | 409 |
+| `PATCH /knowledge/bases/:id`（`sourceTypes` 丢掉在用分类） | 该分类下还有来源 | `SOURCE_TYPE_IN_USE` | 409 |
+| `DELETE /knowledge/bases/:id` | 目标库是默认库 | `BASE_IS_DEFAULT` | 409 |
+| `DELETE /knowledge/bases/:id` | 库里还有文档 | `BASE_IN_USE` | 409 |
+
+守卫失败时**整体不写入**（PATCH 不会出现「名称改了、规则没删」的半成品状态），响应
+同时给出 envelope 的 `error.code` 与顶层 `code`/`message`。删除知识库只删注册表条目，
+**不删磁盘内容**（删文档用 `DELETE /knowledge/documents/:docId`）。
+
+### 版本存储与回滚语义
+
+在 `addSource` 覆盖写入之前，如果目标文件**正文**与新的正文不同，就把**旧文件字节**
+原样快照到 `memory/<库 id>/source-versions/<docSlug>/<versionId>.md`，
+`versionId = <紧凑ISO时间>-<contentHash 前 8 位>`（如 `20260102T030405123Z-9f3c1a2b`）。
+内容完全相同的重复写入不产生版本。快照本身也是 markdown（含 frontmatter），
+`listVersions` 返回新→旧，并把当前 head 作为 `isCurrent: true` 的第一条一并列出
+（head 的 `versionId` 形如 `current-<hash8>`）。
+
+**回滚 = 用快照内容重新调用 `addSource`**：因此回滚前会把当时的 head 再快照一次，
+历史只增不减，**回滚本身也可回滚**。回滚 `current-*` 是 no-op。
+
+### 召回链路（0031 起：两路 + 图谱 boost）
+
+```text
+query → R0 分词 → R1 两路各自超采并过阈值（候选池 50）
+      → R2 RRF 名次级融合 + 图谱 boost
+      → R3 对**候选池**重排，过重排阈值
+      → R4 组装：片段 → 卡片 → SourceRaw 证据（每卡封顶 + MMR）
+      → R5 弃答（insufficientEvidence）
+```
+
+- **R0 分词**（`fts.ts`）：中文按**单字 + 相邻双字**切分（不用词典），ASCII 按 `unicode61`
+  的口径切开。0030 的 `tokens()` 只按非字母数字切，整句中文会变成一个 token ——
+  实测 `排查`→6 命中、`怎么排查指标异常`→**0**。
+- **R1 关键词路**：SQLite FTS5 + **BM25**（`node:sqlite`，零新依赖；不可用时如实降级）。
+  中文之所以不用内置 tokenizer：`unicode61` 不切中文，`trigram` 要求查询 ≥3 字符且会把
+  整句变成互相 AND 的三字窗口。分数按本次最高分归一到 0..1，再过 `keywordThreshold`；
+  另有**多字词覆盖率**门槛（只数双字词与 ASCII 词，单字在中文里不是证据）。
+- **R1 向量路**：**编码器健康门**（两段无关文本必须余弦 < 0.99，否则整路停用）→
+  查询编码一次 → binary/Hamming 预筛 → int8 精算**原始余弦**（`dot / 127²`，0030 多除了
+  一个 dimension，把余弦压进 ±0.001、排序完全没有区分度）→ `vectorThreshold`。
+- **R2 融合**：**RRF**（`k=60`，关键词 0.3 / 向量 0.7）——只吃**名次**，所以三路分数
+  量纲不同这件事不再影响排序（0030 的加权和让向量输出常数时所有命中同分）。
+- **R2 图谱**：**boost，不是第三路**。它给已经在候选池里的条目加一个 RRF 项，**不能自己
+  制造候选**。代价是「只提到某份来源、没提到任何卡片正文」的查询没有第二条路 ——
+  由关键词索引收录 **note 的溯源身份**（sourceRefs + 来源标题）来补偿。
+- **R3 重排**：作用在**候选池**上（不再是已截断的 topK，0014 点名的「分层只做了一半」），
+  低于 `rerankThreshold` 的一律丢弃并报出丢了几条。阈值与 WeKnora 同刻度（**原始 logit**）。
+  worker 用 `predict_raw()`（`activation_fn=Identity`）返回 logit —— `CrossEncoder.predict`
+  对 `num_labels == 1` 默认套 sigmoid，直接拿返回值比 0.2 会让阈值永远不生效；展示用的
+  `rerankScore` 由 `applyRerank()` 只 sigmoid 一次（`0.5` 这种「刚好在门槛上」的假分数
+  是二次 sigmoid 的产物）。
+- **R4 组装**：`context` 条目带**证据片段**（`sourceRefs` 解析到 SourceRaw 正文里覆盖查询词
+  的那几段），所以「片段 → 卡片 → 原文」三层自包含；选择时**每张 wiki 封顶 2 条 + MMR**
+  （λ=0.7），否则 5 条上下文可能全是同一张卡的不同小节。
+- **R5 弃答**：一路都没过阈值 → `insufficientEvidence: true` + `diagnostics.reason`，
+  并标注判据强度（`rerank-threshold` / `vector-threshold` / `relative-only` / `not-needed`）。
+  宁可说「没有」，也不凑满 topN 让模型编。
+- **降级不谎报**：`routes` 只列**通过健康门且真的跑起来**的路；每一路的状态、候选数、
+  最高分、阈值与降级原因都在 `diagnostics.routes` 里。0030 的向量路坏掉时照样上报
+  `routes: ["fts","vector","graph"]`，是这次要修的核心问题之一。
+- `mode: 'graph'` 与 `hybrid` **同义**（图谱不能制造候选，「只靠图谱」不成立）。
+- 阈值初值：`keywordThreshold 0.3` / `rerankThreshold 0.2` 沿用 WeKnora 的出厂值；
+  **`vectorThreshold` 是 0.5，不是它的 0.15** —— 那个数是它自己 embedding 模型的刻度，
+  搬到 WeMM 上会让无关查询照样召回 43/44 条（实测无关查询最高余弦 0.42、相关查询 0.60–0.83，
+  两簇之间有 0.42–0.59 的空带）。`recallCandidatePool` 50（对齐 `EmbeddingTopK`）。
+  **阈值必须按模型与语料校准**，依据是每次召回的 `diagnostics.routes[vector].topScore`
+  与 `rerank.topLogit`。
+- **模型健康门**：两个本地模型各有一个会失败的探针 —— 编码器比自相似度（≈1 且不同文本
+  余弦 < 0.99），重排器查分词器词表（`vocab_size ≥ 1000` 且探针句有非 `<unk>` 条目，否则
+  `RERANK_TOKENIZER_DEGENERATE`）。原因是「能加载」不等于「可用」：本地快照缺分词器文件时，
+  重排器照样加载、照样出分（实测三条无关文本 `0.999 / 0.998 / 0.9994`），只有探针能发现。
+  修法与运维见 `docs/0024-本地模型运行时.md`。
+- **编码器指纹** `ENCODER_FINGERPRINT` 写在向量清单里：同一个模型换了「怎么调它」也必须让
+  已有向量作废，否则 `rebuild all` 会按 contentHash 把旧向量原样复用（0031 实测过：
+  修好编码器后构建仍报 `reused: 44`，修复等于没发生）。
+
+`listDocuments()` / `readDocument(docId)` / `listVersions(docId)` /
+`revertDocument(docId, versionId)` / `deleteDocument(docId)` 是 `KnowledgeRuntime` 上
+新增的文档接口；详情页的 `assets[].url` 即 `/knowledge/assets/<kbId>/<rel>`。
+
+## 评测
+
+公开数据集与 Tita qrels 格式、运行命令和 FTS / WeMM / hybrid 对比矩阵见
+[`eval/README.md`](eval/README.md)。本地 runner 是只读的，不会自动修改 Knowledge
+Store。