dsh-data-domain-knowledge 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -3,18 +3,38 @@
 本地知识库插件：一个知识库是一个目录，里面四样东西。`knowledge.db` 保存 **SourceRaw**
 （原始可追溯文档）、按主题聚合可双向链接的 wiki 卡片，以及**两者的每一个版本**；
 `derived.db` 输出可检索的 **wikiNotes**、wiki
-知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存版本快照、访问审计与反馈。默认使用本地 WeMM Python backend：从 WeMM
-原生 2048 维向量按 MRL 截取 1024 维，先做 binary/Hamming 粗筛，再用 int8 点积精算余弦
-（这是**向量路内部的粗排 → 精算**，与 stage 4 的 cross-encoder **重排**不是一回事）；
-模型不可用时明确降级到 FTS，不会伪造向量结果。Markdown 中的
-本地图片会与正文一起交给 WeMM，因此图片不是独立知识类型。
+知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存操作日志、抽取轨迹、访问审计与反馈。
+默认使用本地 Python 推理：`BAAI/bge-small-zh-v1.5` 生成 512 维文本向量，
+`BAAI/bge-reranker-base` 对召回候选做交叉编码重排。部署入口必须完成环境自检，
+索引必须匹配当前模型；不满足时提示准备环境或重新编译。
+需要图片语义检索时，可配置 WeMM 多模态模型与匹配维度，Markdown 中的本地图片
+会与正文一起交给模型。图片不作为独立知识类型。
 
 Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/tita-agent`）。
 设置面板只展示这个目录并提供「打开目录」，不允许切换根路径；知识库、意图记录、记忆、
-模型和 Python 环境都从这里派生。新版本不读取、不搬运旧版本的
-`~/Desktop/titaagent` 与 `~/.tita-data-agent` 数据；旧数据需要用户自行处理。
+模型和 Python 环境都从这里派生。
 
-## 承载范围（五个视图）
+## 首次运行环境准备
+
+Python、向量模型、重排模型是部署必需项。打开 Tita 设置 → 环境准备 → 一键安装 / 修复。
+系统使用 uv 安装专属 Python 环境，下载固定 revision 的 `BAAI/bge-small-zh-v1.5`
+（512 维）和 `BAAI/bge-reranker-base`，然后运行真实推理自检。阶段、错误和下载日志
+可查看；下载失败可以重试。未就绪时阻止编译和知识召回，来源与历史内容仍可保存、读取。
+
+命令行入口：
+
+```bash
+pnpm --filter dsh-data-domain-knowledge environment:prepare
+pnpm --filter dsh-data-domain-knowledge environment:check
+pnpm --filter dsh-data-domain-knowledge doctor
+```
+
+自检失败时命令返回非零退出码。安装不修改系统 Python，也不隐式运行 npm postinstall
+模型下载。已有知识在准备完成后需重新编译；宿主无需重启。自定义路径保留，使用默认
+资源时把高级设置中的路径恢复为空，并使用匹配的向量维度。
+细节见 [运行环境准备与自检](../../docs/current/16-知识运行环境准备与自检.md)。
+
+## 承载范围
 
 侧边栏 `TitaAgent` 面板的五个视图就是本插件的全部范围：
 
@@ -23,12 +43,11 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | `overview` | Agent 概览 | 各设置的挂载节点 |
 | `intent` | 意图 | `intent_record` / `intent_store_view`、`/intent/*` 路由、`titaDataAgentIntent` 服务；会话审计留痕落 `<agentRoot>/intent/` |
 | `knowledge` | 知识库 | `recall_knowledge` 等工具名、`/knowledge/*` 与 `/convert` 路由、`tita-data-agent-knowledge` / `-convert` 设置 |
-| `memory` | 记忆 | 抽取轨迹、轴 / Knowledge 真源、处理日志、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；磁盘目录布局 |
+| `memory` | 记忆 | 抽取轨迹、处理日志、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；轴 / Knowledge 真源在主库 |
 | `eval` | 评测 | 问题集格式（开发期能力，不注册运行时入口） |
 
 意图的**会话审计留痕**落在 `<agentRoot>/intent/`：`intent.db` 保存当前记录与追加历史
-（按 `sessionKey#turn` 读取时取当前版本，所以内存里「一轮一条」的语义不变）。旧的
-`records.ndjson` 只做一次性迁移，不再继续写入。
+（按 `sessionKey#turn` 读取时取当前版本，所以内存里「一轮一条」的语义不变）。
 分类与 act 是代码内置的固定契约，不提供编辑入口。读接口 `/intent/store` 与 `/intent/overview` 读的是**留痕**：
 引擎内存里那份有 600 秒 TTL，重启或隔一段时间回来不该让面板上的历史凭空消失。
 
@@ -39,7 +58,7 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | 1 | SourceRaw | 原始可追溯文档：`knowledge.db` 的 `source` + `blob` | `allowSourceTruth` / `rootDir` |
 | 2 | 编译 Compile | wiki：`knowledge.db` 的 `card`（**按 wiki 类型 schema 抽实体，直接入库**）；wikiNotes：`derived.db` 的 `wiki_notes.json` | `extractCandidates` / `extractWithModel` / `wikiTypes` |
 | 3 | 构建 Build | wikiNotes → 向量索引；wiki → `derived.db` 的 `knowledge_graph.json` | `embeddingProvider` / `embeddingModel` / `python` |
-| 4 | 召回 Recall | 多路（关键词 + 向量 + 知识图谱）召回 wikiNotes，取 `recallTopK`（默认 10），再解析父级 wiki 与该 wiki 的 1 跳知识图谱 | `recallTopK` / `recallMode` |
+| 4 | 召回 Recall | 多路（坐标 + 关键词 + 向量）召回 wikiNotes，取 `recallTopK`（默认 10），再解析父级 wiki 与该 wiki 的 1 跳知识图谱 | `recallTopK` |
 | 5 | 重排 Rerank | BERT cross-encoder 对候选 wikiNotes 精排，取 `contextTopN`（默认 5）组成 `context` | `contextTopN` / `rerankProvider` / `rerankModel` |
 
 > 第 4、5 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步，
@@ -55,7 +74,7 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | Knowledge | `knowledge` + `knowledge_sources` | 原子事实、坐标、来源、状态；不保存 Card 的排版 |
 | Wiki Card | `card` + `blob` + `revision` | 面向阅读和召回组装的正文；正文中的 Markdown 标题是 Section 真源 |
 | Knowledge 落位 | `card_knowledge` | 记录 Knowledge 在某张 Card 中的 Section 和顺序；这是关联索引，不是 Knowledge 属性 |
-| Wiki Note / FTS / Vector / Graph | 派生文件 | 可以从 Card 和 Knowledge 重新构建，不是真实知识来源 |
+| Wiki Note / FTS / Vector / Graph | `derived.db` | 可以从 Card 和 Knowledge 重新构建；编译结果在同一事务发布 |
 
 ### 状态语义
 
@@ -72,7 +91,29 @@ Knowledge ID 只在一个 `knowledge.db` 内有意义。相同文本在同一个
 
 这意味着当前实现适用于“一个知识库对应一个业务范围”的模型。未来如果一个库需要混合多个租户、环境或有效期，再把 Scope 纳入判重策略。
 
-### Knowledge 类型
+### 身份算法
+
+新 Knowledge ID 使用归一化文本的 SHA-256。归一化保留比较条件、小数、负号和标识符
+分隔符，判重同时比较正文。存量 ID 不重写；人工编辑正文保留 ID 并增加内容版本。
+
+### 来源更新与复核
+
+来源改版后保留旧 Knowledge 和原始证据版本，不自动判定失效。证据记录 `toVersion`，
+读取时返回 `currentVersion`、`evidenceStatus`、`quoteInCurrentVersion`。召回中缺少当前
+可定位证据的知识带 `requiresReview: true`；是否停用仍由人工裁决。
+
+引用定位不等于语义成立。组织校验能拒绝输入中没有出现的数值或比较条件，但不能证明
+任意自然语言陈述成立；召回如实返回 `claimVerification: 'unverified'`。
+
+### 编译发布与一致性
+
+Notes、FTS、向量、图和 manifest 在 `derived.db` 中通过一次事务发布。召回与图查询
+读取已发布快照；失败或取消时保留上一版结果。删除状态立即过滤旧片段。抽取失败不
+保存成功指纹，模型身份、位置或本地文件版本变化会阻止旧向量复用。
+
+目录边界、事务和验证范围见 [知识一致性与编译快照](../../docs/current/15-知识一致性与编译快照.md)。
+
+### Knowledge 类型字段
 
 当前不把 `Fact` / `Rule` / `Procedure` / `Constraint` 加成 Knowledge 的正式列。类型暂作为抽取或 Card metadata 的扩展信息，只有当不同类型需要不同的召回、验证或执行策略时，才升级为结构化字段。
 
@@ -93,24 +134,8 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
 
 因此，删除来源、合并 Knowledge、修改 Card 或重建检索索引时，都必须沿着这条依赖方向处理，不能直接把 Wiki Note 当成可编辑知识，也不能用 Card review 代替 Knowledge 验证。
 
-> **0062 v2（2026-10-05）**：正文、版本与 Knowledge 搬进 `<库根>/knowledge.db`，编译产物
-> 搬进 `<库根>/derived.db`，图片搬进 `<库根>/assets/`。
-> **0067（2026-10-06）**：转换的**原始输入**（那份 PDF / Word / HTML）搬进 `<库根>/source_raw/`，
-> 位置记在 `source` 表的 `original_rel` / `original_sha256` / `original_bytes` 三列上。
-> **知识库内不再有段目录**（原先的
-> `01_source_raw` / `02_wiki` / `03_compiled` / `05_diagnosis` 由迁移导入后删除）。
-> 「知识树能被用户直接读」由导出通道接住：`POST /knowledge/export`。
->
-> 术语迁移：SourceRaw 曾叫 SourceRow / SourceTruth。磁盘目录 `01_source_raw`、工具名
-> `add_source` / `query_source_truth`、HTTP `/knowledge/sources`、设置键 `allowSourceTruth`
-> 与错误码 `SOURCE_TRUTH_DISABLED` 作为兼容名保留，语义等同 SourceRaw。
-> 「编译 / 构建」是同一次 `rebuild()`：编译**按 wiki 类型 schema 抽实体**（模型优先、
-> 规则兜底），判重后直接写 `02_wiki`；**wiki↔wiki 双向链接**与**分阶段重建**是设计目标，
-> 图谱当前只有 `supported_by` 溯源边加规则抽出的 `relates_to`。
-
-- 设置项**不再有独立入口**：它们挂在 Agent 概览架构图的对应节点上（SourceRaw → 收录开关与
-  知识库根目录；编译 → Schema；构建 → Embedding / Python；召回 → topK / 默认路线；
-  重排 → topN / reranker；意图与上下文 → 意图路由），每个节点只保存本节点字段。
+- 知识库设置集中在侧边抽屉：数据位置、向量模型、检索与上下文。召回固定使用多路径融合；
+  低频设备、阈值和模型细节收在高级设置中。Agent 系统提示词常显，并链接到 preset 真源目录。
 - **编译直接入库（0044）**：`rebuild_knowledge` 的 Pass 0 对指纹变了的来源做实体抽取，
   按 `entityType:entityId` / `title` / `metadata.aliases` 三重索引判重 —— 命中已有卡片就把
   新正文**追加**进去（不覆盖、不丢弃），没命中就新建。缺必填小节 / 字段的卡片**照常入库**，
@@ -156,7 +181,7 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
   这个概念）、`sources: [{id, resource, title, author, last_modified}]`（对网页就是那个页面
   本身：地址、标题、作者、发布时间）。`source_id` / `external_id` / `created_at` /
   `updated_at` / `metadata` / `lineage` 是我们的扩展键（OKF 明确允许，且要求消费者容忍
-  未知键）。旧 schema 的知识库不做兼容迁移，需要重新建立。
+  未知键）。
   规范：<https://github.com/GoogleCloudPlatform/open-knowledge-format>（v0.2）。
 - **召回组装按「卡片」而不是按「片段」**（0050）：R1–R3 不变（多路召回 + RRF + 对候选池重排，
   召回与重排的对象都是 wikiNotes），R4 改成四步 —— ① 取 notes 对应的 wiki 去重，一张卡片的等级
@@ -191,10 +216,10 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
   `JSON.stringify`，同一个 `undefined` 在那里无声无息，所以这个错只在工具调用上现形。
 - 编译期一条 wiki 至少产出一条 note；正文按 `##`/`###` 分节且超过 800 字符时按节切分，
   首条 note 的 `unitId` 保持 `<entityType>:<entityId>`，后续为 `<entityType>:<entityId>#<n>`，
-  每条 note 都带 `wikiId` 指回父级 wiki。`03_compiled/knowledge_units.json` 作为旧版兼容镜像保留。
+  每条 note 都带 `wikiId` 指回父级 wiki。
 - `recall_knowledge` 返回 `hits`（重排后的 wikiNotes）、`context`（`{ note, wiki, graph }[]`）、
   `wiki`、`graph`、`routes`、`recallMode`、`rerank`、`recallTopK`、`contextTopN`；入参 `top_k`
-  控制召回条数（`limit` 为兼容别名），`top_n` 控制进入上下文的条数，`mode` 覆盖默认召回路线，
+  控制召回条数，`top_n` 控制进入上下文的条数，`mode` 覆盖默认召回路线，
   `rerank: false` 可单次关闭重排。
 - `rerankProvider` 默认 `bert-python`，模型默认 `BAAI/bge-reranker-base`
   （存在 `~/.dsh/tita-agent/resource/models/bge-reranker-base` 时优先用本地目录）。重排在独立
@@ -211,8 +236,7 @@ bash scripts/setup-embedding.sh
 
 脚本会把 Python 环境放到 `~/.dsh/tita-agent/resource/python`，把量化模型放到
 `~/.dsh/tita-agent/resource/models/WeMM-Embedding-2B-Quantized`。新配置会自动发现这两个路径；
-如果 DSH 中已经保存过旧配置，则在
-Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
+设置位于 Tita Data Agent → Agent 概览 →「构建」节点：
 
 - Provider：`WeMM Python（本地）`
 - Python：`~/.dsh/tita-agent/resource/python/bin/python`
@@ -220,10 +244,8 @@ Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
 - 维度：`1024`
 - 设备：`自动（优先 MPS）`
 
-知识库默认保存在 `~/.dsh/tita-agent/domain_knowledge/<库 id>`；旧的
-`DSH_KNOWLEDGE_ROOT` 与旧 `domain_knowledge` 目录只作为首次启动迁移来源。点击「编译」后，
-`03_compiled` 会生成 `wiki_notes.json`、`knowledge_graph.json`、`wiki-index.md`、
-`vector-manifest.json`、`vectors.binary` 和 `vectors.int8`。未修改的 wikiNote
+知识库默认保存在 `~/.dsh/tita-agent/domain_knowledge/<库 id>`。点击「编译」后，
+编译结果写入 `derived.db`。未修改的 wikiNote
 会复用已有向量，只有新增或变更的 note 重新编码；编码与重排各自使用常驻 Python
 worker（同一份 `src/python/embedding_worker.py`），避免每个请求重复加载模型。
 
@@ -271,8 +293,7 @@ pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF；另有
 
 一个**知识库 = 独立配置 + 独立内容**（产品参照 WeKnora）。注册表持久化在
 `<agentRoot>/resource/knowledge-bases.json`。
-默认库 id 固定为 `default`，其 `rootDir` 固定为 `<agentRoot>/domain_knowledge/default`；
-**不传 `kb` 的旧接口与旧工具一律作用于默认库，行为不变**。
+默认库 id 固定为 `default`，其 `rootDir` 固定为 `<agentRoot>/domain_knowledge/default`。
 
 ```ts
 interface KnowledgeBase { id; name; description; rootDir; isDefault; wikiTypes; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
@@ -282,7 +303,7 @@ interface KnowledgeBase { id; name; description; rootDir; isDefault; wikiTypes;
 **计算字段**，由真实 runtime 重新统计并缓存进同一个 JSON，
 HTTP `GET /knowledge/bases` 在返回前先刷新。
 
-**根路径下是六段**：
+**Agent 数据根目录包含以下内容**：
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
@@ -299,51 +320,23 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 （同一句话在哪个知识库下说，理解方式不该变），所以它不分库。这样知识、记忆、意图三段
 都是可以直接备份、直接 diff 的用户文件。
 
-知识树内部（`domain_knowledge/<知识库 id>/`）现在是**三段**：schema 段与记忆段都已不在
-（后者搬去了 `memory/`）。
+每个知识库的数据根目录为 `<agentRoot>/domain_knowledge/<知识库 id>/`：
 
-| 段 | 装什么 | 删掉的后果 |
+| 文件或目录 | 内容 | 删除影响 |
 | --- | --- | --- |
-| `01_source_raw/` | SourceRaw，文件名 = 标题（0051） | 丢数据 |
-| `02_wiki/<entity_type>/` | Wiki 卡片，一级是卡片类型 | 丢结论 |
-| `03_compiled/` | wikiNotes / 向量 / 知识图谱 / 归因图谱 | 可重建 |
-
-**归因图谱也在这三段里**（v1.1）：一次排查的产物是一份带溯源信息的 SourceRaw（落
-`01_source_raw/`），模板卡由类型定义派生、不落盘，字段级的归因图
-落 `03_compiled/diagnosis_graph.json`。旧的 `05_diagnosis/` 撤销了；它里面的 `*.jsonl`
-如果还在，角色是**只读的迁移输入与历史快照** —— 不再被写，但仍然读得出来（证据与根因
-就从那里来），所以旧知识根不会因为这次改动而读不出内容。
-
-schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类注册表与 Wiki 类型注册表
-一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是配置，跟着根路径走）。
-启动时会把空的那个目录删掉 —— **非空则保留**：那就不属于「没用的空文件夹」了，
-删掉别人的文件比留一个空目录危险得多。
-
-**文件名用标题（0051）。** `01_source_raw/阿里集团大数据建设OneData体系.md` —— `ls`
-认得出、`grep` 文件名有用、`git diff` 看得出改的是哪份材料；`source_id`（`article:bc82…`）仍是
-稳定身份，住在 front matter 里。三条配套规则：①标题里的路径不安全字符换成 `-`、截断到 120 字符、
-只剩替换字符时退回 `source_id`；②**重名默认拒收**（`SOURCE_TITLE_DUPLICATED`，报错指出被谁占着，
-改标题再来）—— 标题是来源的核心属性，两份不同的东西同名是要人处理的信号，不该由命名规则悄悄加后缀；
-③确实要留两份同标题材料时显式传 `allow_duplicate_title: true`，落成 `<标题>-<内容哈希前 6 位>.md`
-并回一条 warning。改名与迁移（老段名 `01_source_truth` → `01_source_raw`、文件名换成标题）在
-`ensureLayout` 里一次性完成，**可重入**；存量正文里带老段名的图片引用不改写，解析器认两个段名。
-
-`01_source_raw` 直接平铺来源文档：文件名就是标题，`source_id` 保留稳定身份，格式、作者、
-外部链接等通用信息写在 front matter。目录结构不承担业务分类职责。
-
-`resource/` 装模型、虚拟环境与 `knowledge-bases.json` —— 「这个 Agent 的全部磁盘足迹」
-因此是一个目录，备份 / 迁移 / 整个删掉都只需要认一个路径。新版本直接使用
-`<agentRoot>/resource/`，启动时不会读取、搬运或删除旧的用户目录。
-旧的 `TITA_DATA_AGENT_HOME` 不再参与解析；如果当前根路径下没有本地资源，就使用
-`python3` / HF 模型名作为兜底。
+| `knowledge.db` | SourceRaw、Knowledge、Wiki Card 与版本记录 | 丢失知识真源 |
+| `derived.db` | wikiNotes、知识图谱、检索索引 | 可重新编译 |
+| `assets/` | 来源图片与附件 | 丢失对应素材 |
+
+`resource/` 保存模型、Python 环境与 `knowledge-bases.json`。
+如果资源目录没有本地 Python 或模型，就使用 `python3` 或 Hugging Face 模型名。
 
 配置里 `python` / `embeddingModel` / `rerankModel` 三个字段的**默认值改成了空串 =
 自动**：按 `<agentRoot>/resource/…` → 兜底名（`python3` / HF 模型名）的顺序解析。
 设置面板用占位符显示解析后的真实路径，并在**资源不是当前 `resource/` 下的本地路径时
 逐条告警**。
 
-向量清单里记的模型名是 `local:<模型目录名>` —— **身份与位置解耦**，
-否则把模型搬一次就让整个索引判成「配置不匹配」而作废。
+向量清单里记的模型名是 `local:<模型目录名>` —— **身份与位置解耦**。
 
 **「文件类型 → 解析引擎」那张规则表已撤。** 它唯一被读的地方是浏览器决定
 「这份文件直读还是送转换内核」，而那个判断现在只看扩展名本身（`DIRECT_READ_EXT`）；
@@ -366,9 +359,11 @@ schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类
 ```text
 GET    /knowledge/bases                                            → { bases, defaultBaseId }
 POST   /knowledge/bases        { name, description?, rootDir? }    → { base }
-PATCH  /knowledge/bases/:id    { name?, description?, wikiTypes? } → { base }
+GET    /knowledge/models?kb=:id                                   → DSH 编译模型目录与当前默认模型状态
+PATCH  /knowledge/bases/:id    { name?, description?, extractionNote?, compileModel? } → { base }
 DELETE /knowledge/bases/:id                                        → { deleted: true }
 GET    /knowledge/documents?kb=&query=&limit=&offset=        → { documents, total }
+GET    /knowledge/events?kb=                                     → { events }
 GET    /knowledge/documents/:docId?kb=                             → { document }（正文截前 4000 字符）
 GET    /knowledge/documents/:docId/content?kb=&offset=&limit=      → { text, offset, nextOffset, totalChars, eof }
 GET    /knowledge/documents/:docId/view?kb=                        → 独立整页（HTML，读全文）
@@ -454,20 +449,17 @@ Document ──▶ Knowledge × N ──▶ 坐标 (对象 × 动作 × 场景)
 ```
 
 > **一个坐标最多一张卡**，这件事由 `knowledge.db` 的 `card.coordinate_key` **主键**兜着，
-> 不是靠约定。`entity_id` 仍保留为旧接口、版本历史和关联表使用的稳定别名。
+> 不是靠约定。`entity_id` 是版本历史和关联表使用的稳定别名。
 
 四条要点：
 
 - **卡片上记着它的坐标**（`card.object_id / action_id / scene_id` + front matter 的
-  `coordinate`）。坐标在这一层是**轴实体 id**，卡名只是显示 —— 0069 之前坐标算出来、
-  推出卡名、然后被丢掉，「这张卡是哪个坐标」只能从卡名字面反推。
-- **判重的顺序是「先坐标，再认领，最后新建」**。第 2 级「认领」同时是存量数据的迁移
-  路径：0069 之前的卡片三列全空、**补不回来也不许猜**，由第一份带来该坐标的文档把它绑上。
-- **不同坐标推同一个卡名 = 两张卡**（0069 之前它们会被按名字静默并成一张）。
-  撞名仍然报 warning，但它的后果从「身份错」退化成「标题重」。
+  `coordinate`）。坐标在这一层是**轴实体 id**，卡名只是显示。
+- **判重的顺序是「先坐标，再认领，最后新建」**。如果按坐标未命中，就检查已有卡片能否认领，
+  最后才新建卡片。
+- **不同坐标可以使用同一个卡名**。撞名会返回 warning。
 - **落位落库**（`card_knowledge`，0063 §4.5）：`section` / `ordinal` 是**关联**的属性。
-  召回命中**章节**之后，按这一节取它落位的知识（含四档状态与出处引文）——
-  0069 之前 `disputed`（「有相反的说法」）渲染进正文后与确定的事实长得一样。
+  召回命中**章节**之后，按这一节取它落位的知识（含四档状态与出处引文）。
 
 **坐标不替代图。** 图是**从 Knowledge 派生的可选关系索引**，回答的是「通天塔依赖哪些表」
 这类任意关系与反向关系；坐标回答的是「这条知识关于什么」。见
@@ -479,15 +471,11 @@ Document ──▶ Knowledge × N ──▶ 坐标 (对象 × 动作 × 场景)
 （身份是 `(entity_kind, entity_id, version)`）+ 一行 `blob`（正文按 sha256 内容寻址）。
 正文完全相同的重复写入**不产生新版本**，只更新 front matter 那类记账字段。
 `listVersions` / `cardVersions` 返回新→旧，并把当前 head 标成 `isCurrent: true`；
-`versionId` 就是**整数版本号的字符串形式**（卡片那些旧 `'head'` 哨兵会被 `VERSION_IS_HEAD`
-拒掉）。
+`versionId` 就是**整数版本号的字符串形式**。
 
 **回滚 = 用历史版本的正文重新写一次**：回滚前会把当时的 head 再记一版，所以历史只增不减，
 **回滚本身也可回滚**。回滚到当前版本是 no-op。
 
-`memory/<库 id>/source-versions/` 与 `card-versions/` 是**旧的文件式快照**：仍然被读
-（迁移把它们当历史导入），但**不再被写**。
-
 ### 起编译的语义（0066）
 
 `POST /knowledge/rebuild` **立即返回** `202 { runId, queued }` —— 它只回答「这一趟的编号
@@ -497,7 +485,7 @@ Document ──▶ Knowledge × N ──▶ 坐标 (对象 × 动作 × 场景)
 ```jsonc
 { "progress": { "runId": "rebuild_…", "startedAt": "…", "finishedAt": "…",
                 "steps": [ /* 四段 */ ], "outcome": "索引 v21：…",
-                "report": { /* 与旧版 rebuild 响应同一份 RebuildReport */ } } }
+                "report": { /* RebuildReport */ } } }
 ```
 
 `?runId=<编号>` 指名要哪一趟；不给编号时给**正在跑**的那一趟（没有在跑就给最近结束的那一趟）。

package/eval/README.md

@@ -1,19 +1,26 @@
 # Tita Knowledge Retrieval Evaluation
 
 `evaluate-retrieval.mjs` 对同一份已经编译好的 Knowledge Store，逐条运行
-`fts`、`vector`、`hybrid`，输出 Recall、MRR、nDCG 和 p50/p95 latency。它不自动
+`fts`、`vector`、`hybrid`，输出 Recall、MRR、nDCG、弃答准确率和 p50/p95 latency。它不自动
 下载公开数据集，也不会改写知识库；公开数据集需要先转换为本插件的 qrels 格式。
 
 ## qrels 格式
 
 每行一个 JSON 对象，`relevant_unit_ids` 使用编译后的稳定 `unitId`，例如
 `metric:sales_amount`。可以附加 `include_problems` 和 `subset`，用于分组评测文本、
-图片 Markdown、表格截图等场景。
+图片 Markdown、表格截图等场景。`subset` 当前保留在输入中；按子集运行时先分别生成
+qrels 文件，runner 不自动输出子集汇总。
 
 ```json
 {"id":"q1","query":"销售额如何计算","relevant_unit_ids":["metric:sales_amount"],"subset":"text"}
+{"id":"q2","query":"库内没有依据的问题","relevant_unit_ids":[],"subset":"abstention"}
 ```
 
+空 `relevant_unit_ids` 明确表示“不应召回”。必须提供这个字段，避免把漏标注误当作
+弃答样本。正例的 Recall、MRR、nDCG 只使用有正例的查询计算；弃答样本单独输出
+`abstention.count`、`falseAnswers`（任何命中均计为误召回）和 `accuracy`。
+只有弃答样本时，正例指标为 `null`。接口失败会使评测失败，不会当作成功弃答。
+
 ## 本地运行
 
 先在 UI 点击一次「编译」，再运行：
@@ -21,7 +28,7 @@
 ```bash
 pnpm --filter dsh-data-domain-knowledge build
 node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
-  --root "$HOME/.tita-data-agent/knowledge" \
+  --root "$HOME/.dsh/tita-agent/domain_knowledge/default" \
   --qrels plugins/dsh-data-domain-knowledge/eval/queries.example.jsonl
 ```
 
@@ -29,10 +36,10 @@ node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
 
 ```bash
 TITA_EVAL_PROVIDER=wemm-python \
-TITA_EVAL_PYTHON="$HOME/.tita-data-agent/embedding-venv/bin/python" \
-TITA_EVAL_MODEL="$HOME/.tita-data-agent/models/WeMM-Embedding-2B-Quantized" \
+TITA_EVAL_PYTHON="$HOME/.dsh/tita-agent/resource/python/bin/python" \
+TITA_EVAL_MODEL="$HOME/.dsh/tita-agent/resource/models/WeMM-Embedding-2B-Quantized" \
 node plugins/dsh-data-domain-knowledge/eval/evaluate-retrieval.mjs \
-  --root "$HOME/.tita-data-agent/knowledge" \
+  --root "$HOME/.dsh/tita-agent/domain_knowledge/default" \
   --qrels ./queries.jsonl
 ```
 
@@ -61,12 +68,13 @@ checkpoint 编译后再跑同一份 qrels。每次比较固定知识卡片、qre
    评测，但它仍然是模型级评测，不是 Tita 端到端评测。
 3. Tita 专属 golden set：建议先人工标注 100–200 条查询，至少包含指标口径、表/字段
    语义、同义词、跨语言、图片中的 UI/图表信息、hard negative 和“不应召回”样本。
-   每条 query 标注 1–3 个正例 unitId；每轮发布前固定这份集合，新增样本走版本控制。
+   有答案的 query 标注 1–3 个正例 unitId；不应召回的 query 使用空集合。每轮发布前
+   固定这份集合，新增样本走版本控制。
 
 ## 指标与门槛
 
 主指标使用 `nDCG@10`、`Recall@10`、`MRR@10`，辅助看 `Recall@5/20`；同时记录
-向量编译吞吐（units/min）、查询 p50/p95、模型常驻内存、`03_compiled` 索引大小和
+弃答准确率和误召回数。另行测量向量编译吞吐（units/min）、模型常驻内存、`derived.db` 大小和
 向量复用率。多模态集合要单独报告 text→image、image→text、text+image 三类结果，
 不能只看总平均。
 
@@ -74,3 +82,6 @@ checkpoint 编译后再跑同一份 qrels。每次比较固定知识卡片、qre
 至少应在语义改写和图片子集上带来可观增益；具体阈值在首轮 100–200 条标注跑完后再
 根据置信区间确定，不预先假设量化版一定优于 BF16。最终结果同时保存 qrels、配置、
 模型 revision、硬件和原始 JSON，确保可复现。
+
+runner 关闭 cross-encoder 重排，比较原始召回路线。完整 Rerank 链路的质量要另行
+测量。自动化回归测试使用小型本地语料和模型替身，不构成真实模型质量门槛的验收结果。

package/eval/evaluate-retrieval.mjs

@@ -56,8 +56,8 @@ if (!limits.length || !modes.length) usage('invalid --k or --modes')
 const lines = (await readFile(args.qrels, 'utf8')).split(/\r?\n/).map(line => line.trim()).filter(Boolean).filter(line => !line.startsWith('#'))
 const qrels = lines.map((line, index) => {
   const item = JSON.parse(line)
-  const relevant = item.relevant_unit_ids ?? item.relevant ?? []
-  if (!item.query || !Array.isArray(relevant) || relevant.length === 0) throw new Error(`qrels line ${index + 1} needs query and non-empty relevant_unit_ids`)
+  const relevant = item.relevant_unit_ids ?? item.relevant
+  if (!item.query || !Array.isArray(relevant)) throw new Error(`qrels line ${index + 1} needs query and relevant_unit_ids (empty means abstain)`)
   return { ...item, relevant_unit_ids: [...new Set(relevant.map(String))] }
 })
 if (!qrels.length) throw new Error('qrels is empty')
@@ -93,26 +93,35 @@ try {
       // is disabled and the raw fused ranking is measured.
       const response = await runtime.recall(qrel.query, maxLimit, qrel.include_problems === true, mode, undefined, { rerank: false })
       latencies.push(performance.now() - started)
+      if (!response.ok) throw new Error(`${qrel.id ?? qrel.query}: ${response.error?.code ?? 'RECALL_FAILED'}`)
       if (response.data.backend === 'fts' && mode !== 'fts') fallbackCount += 1
-      rows.push({ hits: response.data.hits, relevant: new Set(qrel.relevant_unit_ids) })
+      rows.push({ hits: response.data.hits, relevant: new Set(qrel.relevant_unit_ids), subset: qrel.subset ?? 'default' })
     }
     const metrics = {}
     for (const limit of limits) {
       let recall = 0
       let mrr = 0
       let score = 0
-      for (const row of rows) {
+      const positiveRows = rows.filter(row => row.relevant.size > 0)
+      for (const row of positiveRows) {
         const hits = row.hits.slice(0, limit)
         recall += hits.filter(hit => row.relevant.has(hit.unitId)).length / row.relevant.size
         const rank = hits.findIndex(hit => row.relevant.has(hit.unitId))
         mrr += rank < 0 ? 0 : 1 / (rank + 1)
         score += ndcg(row.hits, row.relevant, limit)
       }
-      metrics[`recall@${limit}`] = Number((recall / rows.length).toFixed(4))
-      metrics[`mrr@${limit}`] = Number((mrr / rows.length).toFixed(4))
-      metrics[`ndcg@${limit}`] = Number((score / rows.length).toFixed(4))
+      const divisor = positiveRows.length || 1
+      metrics[`recall@${limit}`] = positiveRows.length ? Number((recall / divisor).toFixed(4)) : null
+      metrics[`mrr@${limit}`] = positiveRows.length ? Number((mrr / divisor).toFixed(4)) : null
+      metrics[`ndcg@${limit}`] = positiveRows.length ? Number((score / divisor).toFixed(4)) : null
+    }
+    const negativeRows = rows.filter(row => row.relevant.size === 0)
+    const falseAnswers = negativeRows.filter(row => row.hits.length > 0).length
+    output.modes[mode] = {
+      metrics, positiveCount: rows.length - negativeRows.length,
+      abstention: { count: negativeRows.length, falseAnswers, accuracy: negativeRows.length ? Number((1 - falseAnswers / negativeRows.length).toFixed(4)) : null },
+      latencyMs: { p50: percentile(latencies, 0.5), p95: percentile(latencies, 0.95) }, fallbackCount,
     }
-    output.modes[mode] = { metrics, latencyMs: { p50: percentile(latencies, 0.5), p95: percentile(latencies, 0.95) }, fallbackCount }
   }
 } finally {
   runtime.close()

package/eval/queries.example.jsonl

@@ -1,2 +1,3 @@
 {"id":"q-agent-architecture","query":"知识编译与召回的 Agent 架构","relevant_unit_ids":["concept:agent_architecture"],"subset":"text"}
 {"id":"q-ui-architecture","query":"Tita 数据 Agent 的界面和架构","relevant_unit_ids":["concept:agent_architecture","concept:ui_reference"],"subset":"text-image"}
+{"id":"q-no-evidence","query":"火星香蕉的年度产量是多少","relevant_unit_ids":[],"subset":"abstention"}