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

package/README.md

@@ -8,33 +8,24 @@
 模型不可用时明确降级到 FTS，不会伪造向量结果。Markdown 中的
 本地图片会与正文一起交给 WeMM，因此图片不是独立知识类型。
 
-## 承载范围（五个视图 = 一个挂载单元）
+## 承载范围（五个视图）
 
-侧边栏 `TitaAgent` 面板声明的五个视图就是本插件的全部范围，`src/` 的目录结构按它们组织：
+侧边栏 `TitaAgent` 面板的五个视图就是本插件的全部范围：
 
-| 视图 | 面板标签 | 宿主实现 | 冻结契约 |
-| --- | --- | --- | --- |
-| `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 词表的
+| 视图 | 面板标签 | 冻结契约 |
+| --- | --- | --- |
+| `overview` | Agent 概览 | 各设置的挂载节点 |
+| `intent` | 意图 | `intent_*` 工具名、`/intent/*` 路由、`tita-data-agent-intent` 设置、`titaDataAgentIntent` 服务；配置与留痕落 `<agentRoot>/intent/` |
+| `knowledge` | 知识库 | `recall_knowledge` 等工具名、`/knowledge/*` 与 `/convert` 路由、`tita-data-agent-knowledge` / `-convert` 设置 |
+| `memory` | 记忆 | 版本快照、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；磁盘目录布局 |
+| `eval` | 评测 | 问题集格式（开发期能力，不注册运行时入口） |
+
+意图的**配置与留痕**落在 `<agentRoot>/intent/`：`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` 不同——
-那次是宿主→宿主的回环，可以改成进程内调用。
-
 ## 五段链路
 
 | 段 | 名称 | 产物 | 关键配置 |
@@ -45,14 +36,14 @@
 | 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 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步
-> ——架构图里也仍是两个节点——但「跑一次真实召回长什么样」是一个问题，分两栏会让用户
-> 先跑召回、再切到重排才能看到同一次运行的全貌，而且两栏各有一个测试按钮。
+> 第 4、5 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步，
+> 但「跑一次真实召回长什么样」是一个问题，分两栏会让用户先跑召回、再切到重排才能
+> 看到同一次运行的全貌。
 
 > 术语迁移：SourceRaw 曾叫 SourceRow / SourceTruth。磁盘目录 `01_source_truth`、工具名
 > `add_source` / `query_source_truth`、HTTP `/knowledge/sources`、设置键 `allowSourceTruth`
 > 与错误码 `SOURCE_TRUTH_DISABLED` 作为兼容名保留，语义等同 SourceRaw。
-> 本轮的「编译 / 构建」仍是同一次 `rebuild()`：编译的**按主题聚合**由 Agent 完成，
+> 「编译 / 构建」是同一次 `rebuild()`：编译的**按主题聚合**由 Agent 完成，
 > **wiki↔wiki 双向链接**与**分阶段重建**是设计目标，图谱当前只有 `supported_by` 溯源边。
 
 - 设置项**不再有独立入口**：它们挂在 Agent 概览架构图的对应节点上（SourceRaw → 收录开关与
@@ -72,15 +63,15 @@
 
 ## 本地启用 WeMM
 
-在 Apple Silicon 上执行一次：
+在 Apple Silicon 上执行一次（在插件包目录内）：
 
 ```bash
-./plugins/dsh-data-domain-knowledge/scripts/setup-embedding.sh
+bash scripts/setup-embedding.sh
 ```
 
 脚本会把 Python 环境放到 `~/.tita-data-agent/embedding-venv`，把量化模型放到
-`~/.tita-data-agent/models/WeMM-Embedding-2B-Quantized`，不会把 1.8GB 权重提交
-进仓库。新配置会自动发现这两个路径；如果 DSH 中已经保存过旧配置，则在
+`~/.tita-data-agent/models/WeMM-Embedding-2B-Quantized`。新配置会自动发现这两个路径；
+如果 DSH 中已经保存过旧配置，则在
 Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
 
 - Provider：`WeMM Python（本地）`
@@ -90,7 +81,7 @@ Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
 - 设备：`自动（优先 MPS）`
 
 知识库默认保存在 `~/.tita-data-agent/knowledge`；设置了 `DSH_KNOWLEDGE_ROOT`
-或已有旧的仓库内 `domain_knowledge` 时会优先沿用。点击「编译」后，
+或已有旧的 `domain_knowledge` 目录时会优先沿用。点击「编译」后，
 `03_compiled` 会生成 `wiki_notes.json`、`knowledge_graph.json`、
 `vector-manifest.json`、`vectors.binary` 和 `vectors.int8`。未修改的 wikiNote
 会复用已有向量，只有新增或变更的 note 重新编码；编码与重排各自使用常驻 Python
@@ -100,8 +91,7 @@ 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`。
+加载成功但给所有输入同一个分（`RERANK_TOKENIZER_DEGENERATE`）。
 
 知识写入、编译、SourceRaw 读取和召回支持统一的
 `sessionId/turnId/intentId/taskId/subtaskId/runId/traceId/domain` lineage。卡片把
@@ -112,20 +102,12 @@ BERT 重排默认使用 `BAAI/bge-reranker-base`；如需完全离线，可把
 可以通过工具 `check_knowledge_embeddings` 或 `GET /knowledge/embedding/health`
 查看 provider、模型、设备、索引条数和最后一次错误。
 
-## 格式转换（convert seam，0018）
+## 格式转换（convert）
 
-多格式转换的 **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
-```
+多格式转换是本插件的一个子模块（`src/convert/`），与知识库共用同一次挂载、同一个
+侧边栏 Tab、同一套 runtime。解析由可选内核 `dsh-convert-core` 完成（内核不挂载，可独立
+运行），底层是 `@firecrawl/anydoc`（MIT / Rust / 预编译绑定），支持 doc、docx、ppt、
+pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF。
 
 | 项 | 值 |
 | --- | --- |
@@ -134,40 +116,30 @@ packages/dsh-convert-core   内核（不挂载，可独立运行：node bin/tita
 | 设置命名空间 | `tita-data-agent-convert`（冻结契约，由本插件安装） |
 | 交付目录 | `~/.tita-data-agent/convert-out/<taskId>/`（`index.md` / `assets/` / `manifest.json`） |
 
-**依赖是可选的。** `dsh-convert-core` 声明在 `optionalDependencies`，由
-`core-loader.ts` 在首次调用时 `import()`。平台没有 anydoc 预编译绑定、或用户显式不装时，
+**依赖是可选的。** `dsh-convert-core` 声明在 `optionalDependencies`，首次调用时才加载。
+平台没有 anydoc 预编译绑定、或用户显式不装时，
 `convert_*` 与 `/convert` 面板返回 `DEPENDENCY_MISSING` 并给出安装建议，**knowledge 本体
-（`add_source` / 编译 / 召回）照常可用**。不要把它改成静态 import：有一条测试守着这件事。
+（`add_source` / 编译 / 召回）照常可用**。
 
-**入库是进程内调用。** `ingestDelivery()` 直接调 `runtime.addSource()`，不再走
-`POST /knowledge/sources` 回环。少了一次 JSON 序列化，也因此没有旧的 ~1.2 MB body 上限。
-单条 SourceRaw **没有字符数上限**：`maxSourceBytes` 在 0029 撤掉了（先撤面板上的字段，
-后来连运行层那道闸门一起撤 —— 只撤面板等于留一个用户改不了、也找不到的硬上限）。
+**单条 SourceRaw 没有字符数上限**：`maxSourceBytes` 已撤除。
 真正的边界是转换内核的 `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` 的旧接口与旧工具一律作用于默认库，行为不变**。
+默认库 id 固定为 `default`，其 `rootDir` 始终来自插件设置 `rootDir`；
+**不传 `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()`。
+**计算字段**，由真实 runtime 重新统计并缓存进同一个 JSON，
+HTTP `GET /knowledge/bases` 在返回前先刷新。
 
-0029 / 0032：**根路径下是六段**：
+**根路径下是六段**：
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
@@ -178,40 +150,43 @@ interface KnowledgeBase { id; name; description; rootDir; isDefault; sourceTypes
 | `tmp/` | 运行期临时文件，二级按日期分桶 | 只影响未完成的任务 |
 | `resource/` | 模型、Python 环境、`knowledge-bases.json` | 失去语义检索（嵌入/重排不可用） |
 
-**记忆与意图为什么与知识树平级**（0032 的架构调整）：记忆装的是版本快照与审计流水 ——
+**记忆与意图为什么与知识树平级**：记忆装的是版本快照与审计流水 ——
 那是**关于这个 Agent 的动作留痕**，不是关于知识的断言；留在知识树里会让「备份知识树」
 被迫连审计一起备份，也让「知识树有哪几段」这个问题混进一个横切层。意图则是**会话级**的
-（同一句话在哪个知识库下说，理解方式不该变），所以它不分库；它的两份东西原来一个住在
-宿主的 settings 文档里、一个只在内存里，都不是「这个 Agent 自己的文件」。搬出来之后，
-知识、记忆、意图三段都是可以直接备份、直接 diff 的用户文件。
+（同一句话在哪个知识库下说，理解方式不该变），所以它不分库。这样知识、记忆、意图三段
+都是可以直接备份、直接 diff 的用户文件。
 
-知识树内部（`domain_knowledge/<知识库 id>/`）0032 起是**四段**：`00_schema`（0030 撤，
-它从建出来起就是空目录）与 `04_memory`（0032 搬去 `memory/`）都已不在。
+知识树内部（`domain_knowledge/<知识库 id>/`）现在是**三段**：schema 段与记忆段都已不在
+（后者搬去了 `memory/`）。
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
 | `01_source_truth/<source_type>/` | SourceRaw，一级是**来源分类**，二级是文档 | 丢数据 |
 | `02_wiki/<entity_type>/` | Wiki 卡片，一级是卡片类型 | 丢结论 |
-| `03_compiled/` | wikiNotes / 向量 / 知识图谱 | 可重建 |
-| `05_diagnosis/` | 智能归因图谱 | 可重建 |
+| `03_compiled/` | wikiNotes / 向量 / 知识图谱 / 归因图谱 | 可重建 |
+
+**归因图谱也在这三段里**（v1.1）：一次排查的产物是一条来源分类为 `agent_diagnosis_case`
+的 SourceRaw（落 `01_source_truth/`），模板卡由类型定义派生、不落盘，字段级的归因图
+落 `03_compiled/diagnosis_graph.json`。旧的 `05_diagnosis/` 撤销了；它里面的 `*.jsonl`
+如果还在，角色是**只读的迁移输入与历史快照** —— 不再被写，但仍然读得出来（证据与根因
+就从那里来），所以旧知识根不会因为这次改动而读不出内容。
 
-`00_schema` 撤掉的依据：它从建出来那天起就是一个**空目录**。分类注册表与 Wiki 类型
-注册表一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是配置，跟着根路径走）；
-`00_schema` 里没有一行代码写过东西。「磁盘上有一个文件夹」本身是一种承诺，空着就是
-误导。`ensureLayout` 会在启动时把空的 `00_schema` 删掉 —— **非空则保留**：那就不属于
-「没用的空文件夹」了，删掉别人的文件比留一个空目录危险得多。
+schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类注册表与 Wiki 类型注册表
+一直住在 `<agentRoot>/resource/knowledge-bases.json`（那是配置，跟着根路径走）。
+启动时会把空的那个目录删掉 —— **非空则保留**：那就不属于「没用的空文件夹」了，
+删掉别人的文件比留一个空目录危险得多。
 
 `01_source_truth` 按分类分目录（而不是平铺）的理由与 `02_wiki` 一致：分类是每份来源的
 必备元数据（frontmatter 的 `source_type`），提到目录名上之后「按分类找东西」在文件系统
 层面直接成立，不依赖界面。平铺在真实使用里会先变成垃圾场 —— 几十份来源混在一层，`ls`
 读不出「我的指标口径在哪」。启动时一次性把平铺的文档搬进分类目录；读路径不依赖这个层级
-（`sourceIndex` 递归扫全段建 slug → path 索引），所以旧布局、新布局与两者并存的中间态
+（启动时会递归扫全段建 slug → path 索引），所以旧布局、新布局与两者并存的中间态
 都能读。**改分类 = 换目录**：`add_source` 用同一 `sourceId` 配新 `sourceType` 时，旧目录
 里那份会被删掉，不会留下孤儿。
 
-`resource/` 是 0029 新增的：模型与虚拟环境原来住在 `~/.tita-data-agent`，现在搬进
-根路径 —— 「这个 Agent 的全部磁盘足迹」因此是一个目录，备份 / 迁移 / 整个删掉都只
-需要认一个路径。启动时一次性搬迁（先 `rename`，跨卷**不自动复制**，因为可能有几个
+`resource/` 装模型、虚拟环境与 `knowledge-bases.json` —— 「这个 Agent 的全部磁盘足迹」
+因此是一个目录，备份 / 迁移 / 整个删掉都只需要认一个路径。模型与虚拟环境原先住在
+`~/.tita-data-agent`，启动时一次性搬迁（先 `rename`，跨卷**不自动复制**，因为可能有几个
 GB）；旧的 `TITA_DATA_AGENT_HOME` 留在解析链上作为兜底，所以搬与没搬都能跑。
 搬迁**按条目合并**：`resource/models/` 里已经有用户自己放的模型时，仍会把旧的嵌入模型
 搬进来，只跳过同名的那个 —— 否则「目标目录存在」会让另一样东西永远搬不过来。
@@ -221,31 +196,24 @@ GB）；旧的 `TITA_DATA_AGENT_HOME` 留在解析链上作为兜底，所以搬
 的顺序解析。设置面板用占位符显示解析后的真实路径，并在**家当不在 `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:<模型目录名>` —— **身份与位置解耦**，
+向量清单里记的模型名是 `local:<模型目录名>` —— **身份与位置解耦**，
 否则把模型搬一次就让整个索引判成「配置不匹配」而作废。
 
-0029：**「文件类型 → 解析引擎」那张规则表已撤。** 它唯一被读的地方是浏览器决定
+**「文件类型 → 解析引擎」那张规则表已撤。** 它唯一被读的地方是浏览器决定
 「这份文件直读还是送转换内核」，而那个判断现在只看扩展名本身（`DIRECT_READ_EXT`）；
 真正决定用哪个适配器的是**转换内核自己的格式表**（`ANYDOC/SCANNED/IDDOC/TEXT_EXTENSIONS`），
 它从来不读这张表 —— 也就是说「把 .docx 设成直读文本」这类配置**改了不生效**。撤掉
 之后：上传选择框的 `accept` 问内核要（`/convert/api/capabilities`），文件类型筛选项
 和计数从**这一库真实的文档**推导。两边都不可能再与内核漂移。
 
-**文档扩展名 `ext` 的推导是有损的**（`deriveSourceExt`，代码注释同）：优先取
+**文档扩展名 `ext` 的推导是有损的**：优先取
 `metadata.source_path` 的 basename 扩展名；否则 `source_format === 'markdown'` → `.md`，
-`'office'` → `.docx`，其余 → `.` + `source_format`；都没有 → `.md`。只有上游
-`convert/ingest.ts` 写了 `source_path` 时才精确。
+`'office'` → `.docx`，其余 → `.` + `source_format`；都没有 → `.md`。只有来源写了
+`source_path` 时才精确。
 
-文档的 `parser` 字段说的是**谁解析了这份文档**：经转换内核进来的由
-`convert/ingest.ts` 写 `metadata.parser`（如 `anydoc@1/pdf`），直接写进来的
-（`add_source`、浏览器直读文本）是 `direct` —— 没有解析器。0029 之前这里会按扩展名
-猜一个引擎名（`.pdf` → `anydoc`），那是在陈述一件没有发生过的事。
+文档的 `parser` 字段说的是**谁解析了这份文档**：经转换内核进来的会写
+`metadata.parser`（如 `anydoc@1/pdf`），直接写进来的
+（`add_source`、浏览器直读文本）是 `direct` —— 没有解析器。
 
 ### HTTP API
 
@@ -255,13 +223,32 @@ 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?kb=                             → { document }（正文截前 4000 字符）
+GET    /knowledge/documents/:docId/content?kb=&offset=&limit=      → { text, offset, nextOffset, totalChars, eof }
+GET    /knowledge/documents/:docId/view?kb=                        → 独立整页（HTML，读全文）
 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/*                                     → 知识库根目录下的文件流
+GET    /knowledge/doc-page.js                                      → 独立整页的脚本（构建产物）
+GET    /knowledge/card-proposals?kb=&status=                       → { total, proposals }（默认只看待审）
+POST   /knowledge/card-proposals/review { kb, proposal_id, action, reason? } → { proposalId, status, written }
+POST   /diagnosis/run           { kb, record }                     → { sourceId, proposalId }
 ```
 
+**`/knowledge/card-proposals/review` 是「人的确认动作」，刻意不做成 Agent 工具。**
+类型层的写入现在有两段：Agent 与编译只**提议**（`propose_wiki_cards`、Pass 0），
+未确认的提议不落 `02_wiki/`、不进编译、不参与召回、不在归因图上出现；人在面板上
+逐条 review（通过并写入 / 仅确认 / 拒绝），确认之后才走 `write_knowledge_card` ——
+而那个工具现在要求一条**已确认且尚未落卡**的 `proposal_id`，确认凭证是一次性的。
+提议落在记忆段 `<agentRoot>/memory/<库 id>/card-proposals/`，不在知识树里。
+
+**原文预览只发前 4000 个字符。** `GET /knowledge/documents/:docId` 返回的 `content` 是
+截断过的，全文长度在 `contentChars`、是否截断在 `contentTruncated`。理由是抽屉只有
+380px 宽，读不完一份几十万字的文档 —— 而把整份正文发过去正是「打开弹层要等半天」的
+成因。要读全文走 `.../view` 那个独立整页：它按 `offset`/`limit` **一页一段**地取
+（默认 20000 字符一页，切点对齐空行），所以任何一次响应都不与文档大小成正比。
+
 `/knowledge/stats`、`/knowledge/search`、`/knowledge/rebuild`、`/knowledge/cards`、
 `/knowledge/sources`、`/knowledge/graph`、`/knowledge/embedding/health` 与全部
 `*_knowledge*` 工具都接受**可选** `kb`（query 或 body 字段）。`docId` 含 `:`
@@ -293,7 +280,7 @@ GET    /knowledge/assets/:kb/*                                     → 知识库
 **回滚 = 用快照内容重新调用 `addSource`**：因此回滚前会把当时的 head 再快照一次，
 历史只增不减，**回滚本身也可回滚**。回滚 `current-*` 是 no-op。
 
-### 召回链路（0031 起：两路 + 图谱 boost）
+### 召回链路（两路 + 图谱 boost）
 
 ```text
 query → R0 分词 → R1 两路各自超采并过阈值（候选池 50）
@@ -303,22 +290,21 @@ query → R0 分词 → R1 两路各自超采并过阈值（候选池 50）
       → R5 弃答（insufficientEvidence）
 ```
 
-- **R0 分词**（`fts.ts`）：中文按**单字 + 相邻双字**切分（不用词典），ASCII 按 `unicode61`
-  的口径切开。0030 的 `tokens()` 只按非字母数字切，整句中文会变成一个 token ——
-  实测 `排查`→6 命中、`怎么排查指标异常`→**0**。
+- **R0 分词**：中文按**单字 + 相邻双字**切分（不用词典），ASCII 按 `unicode61`
+  的口径切开。
 - **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 的加权和让向量输出常数时所有命中同分）。
+  查询编码一次 → binary/Hamming 预筛 → int8 精算**原始余弦**（`dot / 127²`）→
+  `vectorThreshold`。
+- **R2 融合**：**RRF**（`k=60`，关键词 0.3 / 向量 0.7）——只吃**名次**，所以各路分数
+  量纲不同这件事不再影响排序。
 - **R2 图谱**：**boost，不是第三路**。它给已经在候选池里的条目加一个 RRF 项，**不能自己
   制造候选**。代价是「只提到某份来源、没提到任何卡片正文」的查询没有第二条路 ——
   由关键词索引收录 **note 的溯源身份**（sourceRefs + 来源标题）来补偿。
-- **R3 重排**：作用在**候选池**上（不再是已截断的 topK，0014 点名的「分层只做了一半」），
+- **R3 重排**：作用在**候选池**上（不是已截断的 topK），
   低于 `rerankThreshold` 的一律丢弃并报出丢了几条。阈值与 WeKnora 同刻度（**原始 logit**）。
   worker 用 `predict_raw()`（`activation_fn=Identity`）返回 logit —— `CrossEncoder.predict`
   对 `num_labels == 1` 默认套 sigmoid，直接拿返回值比 0.2 会让阈值永远不生效；展示用的
@@ -331,8 +317,7 @@ query → R0 分词 → R1 两路各自超采并过阈值（候选池 50）
   并标注判据强度（`rerank-threshold` / `vector-threshold` / `relative-only` / `not-needed`）。
   宁可说「没有」，也不凑满 topN 让模型编。
 - **降级不谎报**：`routes` 只列**通过健康门且真的跑起来**的路；每一路的状态、候选数、
-  最高分、阈值与降级原因都在 `diagnostics.routes` 里。0030 的向量路坏掉时照样上报
-  `routes: ["fts","vector","graph"]`，是这次要修的核心问题之一。
+  最高分、阈值与降级原因都在 `diagnostics.routes` 里。
 - `mode: 'graph'` 与 `hybrid` **同义**（图谱不能制造候选，「只靠图谱」不成立）。
 - 阈值初值：`keywordThreshold 0.3` / `rerankThreshold 0.2` 沿用 WeKnora 的出厂值；
   **`vectorThreshold` 是 0.5，不是它的 0.15** —— 那个数是它自己 embedding 模型的刻度，
@@ -344,14 +329,12 @@ query → R0 分词 → R1 两路各自超采并过阈值（候选池 50）
   余弦 < 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`，修复等于没发生）。
+  已有向量作废，否则 `rebuild all` 会按 contentHash 把旧向量原样复用。
 
 `listDocuments()` / `readDocument(docId)` / `listVersions(docId)` /
-`revertDocument(docId, versionId)` / `deleteDocument(docId)` 是 `KnowledgeRuntime` 上
-新增的文档接口；详情页的 `assets[].url` 即 `/knowledge/assets/<kbId>/<rel>`。
+`revertDocument(docId, versionId)` / `deleteDocument(docId)` 是文档接口；
+详情页的 `assets[].url` 即 `/knowledge/assets/<kbId>/<rel>`。
 
 ## 评测
 

package/cordis.patch.yml

@@ -112,11 +112,17 @@
                 3. **Never invent a number.** Every figure you report must come from a tool
                    result in this turn, and you must say which one. "I don't have that data" is
                    a correct answer; a made-up number is not.
-                4. **Put it in writing while you still have the evidence.** A definition, a
-                   metric's exact calculation, a process, a diagnosed cause — if it will be
-                   asked again, write it as a card with `write_knowledge_card`, with
-                   `source_refs` that already exist in the store. A card whose refs point
-                   nowhere is rejected, and rightly so.
+                4. **Put it in writing while you still have the evidence — as a proposal, not
+                   a card.** A definition, a metric's exact calculation, a process, a diagnosed
+                   cause — if it will be asked again, call `propose_wiki_cards` with the
+                   `source_id` you just wrote and drafts whose `source_refs` already exist in
+                   the store. A draft whose refs point nowhere is rejected, and rightly so.
+                   **You cannot write a card yourself**: `write_knowledge_card` only accepts a
+                   proposal a human has already confirmed, and unconfirmed proposals never
+                   reach the wiki — they are not compiled, not recalled and not on the graph.
+                   So say what you proposed and that it is waiting for review; do not claim the
+                   card exists. Call `list_card_proposals` first so you do not re-propose
+                   something a human already turned down.
                 5. **Correct a card, do not quietly overwrite it.** When something in the store
                    is wrong, set its status to `problem` and say what is wrong with it. Cards
                    marked `problem` drop out of recall by default — that is how a wrong