dsh-data-domain-knowledge 0.1.0-alpha.6 → 0.1.0-alpha.9

package/README.md

@@ -1,7 +1,8 @@
 # dsh-data-domain-knowledge
 
-本地知识库插件：`01_source_raw` 保存 **SourceRaw**（原始可追溯文档），`02_wiki` 保存
-按主题聚合、可双向链接的 wiki 卡片，`03_compiled` 输出可检索的 **wikiNotes**、wiki
+本地知识库插件：一个知识库是一个目录，里面四样东西。`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 **重排**不是一回事）；
@@ -15,24 +16,24 @@
 | 视图 | 面板标签 | 冻结契约 |
 | --- | --- | --- |
 | `overview` | Agent 概览 | 各设置的挂载节点 |
-| `intent` | 意图 | `intent_*` 工具名、`/intent/*` 路由、`tita-data-agent-intent` 设置、`titaDataAgentIntent` 服务；配置与留痕落 `<agentRoot>/intent/` |
+| `intent` | 意图 | `intent_record` / `intent_store_view`、`/intent/*` 路由、`titaDataAgentIntent` 服务；会话审计留痕落 `<agentRoot>/intent/` |
 | `knowledge` | 知识库 | `recall_knowledge` 等工具名、`/knowledge/*` 与 `/convert` 路由、`tita-data-agent-knowledge` / `-convert` 设置 |
-| `memory` | 记忆 | 版本快照、`feedback.ndjson`、`access-audit.ndjson`，根在 `<agentRoot>/memory/<库 id>`；磁盘目录布局 |
+| `memory` | 记忆 | 抽取轨迹、轴 / Knowledge 真源、处理日志、`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` 读的是**留痕**：
+意图的**会话审计留痕**落在 `<agentRoot>/intent/`：`intent.db` 保存当前记录与追加历史
+（按 `sessionKey#turn` 读取时取当前版本，所以内存里「一轮一条」的语义不变）。旧的
+`records.ndjson` 只做一次性迁移，不再继续写入。
+分类与 act 是代码内置的固定契约，不提供编辑入口。读接口 `/intent/store` 与 `/intent/overview` 读的是**留痕**：
 引擎内存里那份有 600 秒 TTL，重启或隔一段时间回来不该让面板上的历史凭空消失。
 
 ## 五段链路
 
 | 段 | 名称 | 产物 | 关键配置 |
 | --- | --- | --- | --- |
-| 1 | SourceRaw | 原始可追溯文档：`01_source_raw/*.md` | `allowSourceTruth` / `rootDir` |
-| 2 | 编译 Compile | wiki：`02_wiki`（**按 wiki 类型 schema 抽实体，直接入库**）；wikiNotes：`03_compiled/wiki_notes.json` | `extractCandidates` / `extractWithModel` / `wikiTypes` |
-| 3 | 构建 Build | wikiNotes → 向量索引；wiki → `03_compiled/knowledge_graph.json` | `embeddingProvider` / `embeddingModel` / `python` |
+| 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` |
 | 5 | 重排 Rerank | BERT cross-encoder 对候选 wikiNotes 精排，取 `contextTopN`（默认 5）组成 `context` | `contextTopN` / `rerankProvider` / `rerankModel` |
 
@@ -40,6 +41,61 @@
 > 但「跑一次真实召回长什么样」是一个问题，分两栏会让用户先跑召回、再切到重排才能
 > 看到同一次运行的全貌。
 
+## Knowledge / Wiki Card 的存储约束
+
+这套存储的边界固定如下，不因检索策略变化而把所有内容塞进同一张表：
+
+| 层 | 真源 | 说明 |
+| --- | --- | --- |
+| 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 重新构建，不是真实知识来源 |
+
+### 状态语义
+
+Knowledge 的状态回答“这条事实现在能否被当作事实使用”，Card 的 status/review 回答“这张卡的内容是否被审核、是否适合展示”。两者不互相替代：
+
+- `candidate`：已进入真源但还没有人工或规则确认；可以召回，但必须标注“待确认”。
+- `active`：当前可作为正常事实使用。
+- `disputed`：存在相反来源；两条知识都保留，召回时必须显式提示。
+- `deprecated`：历史上成立或曾被采用，但当前不应作为首选事实；仍保留用于追溯。
+
+### 身份与 Scope
+
+Knowledge ID 只在一个 `knowledge.db` 内有意义。相同文本在同一个知识库内，即使来自不同来源或不同 Coordinate，也沿用同一个 ID；Coordinate 是归类和落位信息，不是当前的判重键。不同知识库是不同 Scope，不会因为 ID 算法相同而自动合并。
+
+这意味着当前实现适用于“一个知识库对应一个业务范围”的模型。未来如果一个库需要混合多个租户、环境或有效期，再把 Scope 纳入判重策略。
+
+### Knowledge 类型
+
+当前不把 `Fact` / `Rule` / `Procedure` / `Constraint` 加成 Knowledge 的正式列。类型暂作为抽取或 Card metadata 的扩展信息，只有当不同类型需要不同的召回、验证或执行策略时，才升级为结构化字段。
+
+## Knowledge、Wiki Card、Wiki Note 的生命周期
+
+三者不是三个并列的知识真源，而是同一条知识链上的三个层次：
+
+```text
+SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
+             事实真源     阅读组织视图     检索派生片段
+```
+
+- Knowledge 是不可由 Card 反向重建的事实记录。抽取、来源追加、合并、冲突裁决和状态变化都发生在这里。
+- Wiki Card 是 Knowledge 的组织视图。Card 正文、摘要、Section 和阅读顺序可以重新编排；重新编排不应修改 Knowledge。
+- Wiki Note 是 Card 的检索切片。它没有独立的业务生命周期，`status` 只是父 Card 状态的快照；Card 变化后重新编译 Wiki Note，索引随之重建。
+
+状态也按层分开：Knowledge 使用 `candidate / active / disputed / deprecated`，Card 使用 `unreviewed / draft / reviewed / active / deprecated / problem`。同名状态不表示同一件事：Knowledge 的 `active` 是事实可采用，Card 的 `active` 是页面可展示。
+
+因此，删除来源、合并 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。
@@ -87,22 +143,16 @@
   （规范形，知识库根相对）、`_assets/…`（转换内核早期写进 SourceRaw 的形式）、
   `../../01_source_raw/_assets/…`（`cardHints` 给手工建卡的形式）。文档的资产清单与卡片的
   `imagePaths` 走同一个 `assetRefCandidates`（根目录 → `01_source_raw/` → 文件自己的目录），
-  否则同一张图在文档里找得到、在卡片里找不到。派生字段（图片路径、来源分类）变了也算
+  否则同一张图在文档里找得到、在卡片里找不到。派生字段（图片路径、溯源链）变了也算
   「语料变了」，否则增量编译的空操作会把刷新结果丢掉。
-- **SourceRaw 的 front matter 是 OKF v0.2 形状**（0048）：`type`（唯一必填键，值就是
-  来源分类）、`title`、`description`、`resource`（底层资产地址）、`tags`、
+- **SourceRaw 的 front matter 是 OKF v0.2 形状**（0048）：`title`、`description`、
+  `resource`（底层资产地址）、`tags`、
   `generated: {by, at}`（`by` = 谁解析的，`at` = **采集时间** —— OKF 里没有「抓取时间」
   这个概念）、`sources: [{id, resource, title, author, last_modified}]`（对网页就是那个页面
   本身：地址、标题、作者、发布时间）。`source_id` / `external_id` / `created_at` /
   `updated_at` / `metadata` / `lineage` 是我们的扩展键（OKF 明确允许，且要求消费者容忍
-  未知键）。**旧文件的 `source_type` 仍然读得到**，存量文件由 `ensureLayout` 一次性迁移
-  （只搬已有的值，不编作者与发布时间 —— 0048 之前适配器把它们抽出来就扔了）。
+  未知键）。旧 schema 的知识库不做兼容迁移，需要重新建立。
   规范：<https://github.com/GoogleCloudPlatform/open-knowledge-format>（v0.2）。
-- **来源分类可以声明元数据字段**（0048）：`SourceTypeDef.metadataFields` 是
-  `{key, label, description, required}` 的清单，`key` 用 front matter 顶层键或
-  `sources[0].author` 这种路径。面板「类型定义 → 来源分类」里可编辑；缺必填字段时
-  `add_source` 回一条 warning（`status: partial`）而**不拒收** —— 元数据缺失是信息不全，
-  不是「这份知识不存在」，拒收的代价是知识直接丢了。
 - **召回组装按「卡片」而不是按「片段」**（0050）：R1–R3 不变（多路召回 + RRF + 对候选池重排，
   召回与重排的对象都是 wikiNotes），R4 改成四步 —— ① 取 notes 对应的 wiki 去重，一张卡片的等级
   取它名下 note 的**最高重排分**，命中的小节挂在同一条上；② **在这之后**做 wiki → wiki 的
@@ -118,9 +168,9 @@
   含被预算挡住的），末尾写「最终 N 个 wiki 进上下文」。旋钮跟着步骤走：路线与召回 topK 在第一步，
   上下文 topN 在第三步。这份「面板账本」只在 HTTP 的 `detail=true` 上返回，工具调用不带它。
 - **编译的收尾段产出三样东西**（0049），都不调模型：
-  ①**索引页** `03_compiled/wiki-index.md` —— 按类型分组列出库里现有的卡片（链接 + 状态 +
+  ①**索引页** `derived.db` 的 `wiki-index.md` —— 按类型分组列出库里现有的卡片（链接 + 状态 +
   待补数），末尾单列断链。它刻意不写生成时间与版本号：写了它每次重建都变一个字节，而增量
-  编译要靠「索引页变了没有」判断这一轮要不要真的落盘。落在 `03_compiled/` 而不是 `02_wiki/`，
+  编译要靠「索引页变了没有」判断这一轮要不要真的落盘。落在派生库而不是卡片那一层，
   因为后者每一份 `.md` 都会被当成一张卡片读进卡片清单。
   ②**相关卡片** —— 写进卡片正文末尾一块（块首带 `<!-- compiled:related -->`，整块替换而不是
   追加）。关系来源有两个：来源文档里写明的关系（双向都记），以及「同一份来源」（补前面没覆盖
@@ -194,14 +244,15 @@ BERT 重排默认使用 `BAAI/bge-reranker-base`；如需完全离线，可把
 运行），底层是 `@firecrawl/anydoc`（MIT / Rust / 预编译绑定），支持 doc、docx、ppt、
 pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF；另有本地音视频/图片
 （`iddoc`）、扫描件轻量 OCR（`scanned`：`.pdf` 报 `needsOcr` 时**自动兜底**）与
-网页 / 微信公众号文章（`web`：`kind=url` 抓链接，`.html/.htm` 收另存下来的页面）。
+网页 / 微信公众号文章（`web`：收另存到本机的 `.html/.htm` 页面，从 `og:url` / `canonical`
+把原始地址找回来；内核不联网，`kind=url` 已从契约删除）。
 
 | 项 | 值 |
 | --- | --- |
 | 工具 | `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`） |
+| 交付目录 | `<工作区>/output/<YYYY-MM-DD>/<中文名>/`（`index.md` / `assets/` / `manifest.json`）；叶子名取文档标题，同名让路 `-2` |
 
 **依赖是可选的。** `dsh-convert-core` 声明在 `optionalDependencies`，首次调用时才加载。
 平台没有 anydoc 预编译绑定、或用户显式不装时，
@@ -219,10 +270,10 @@ pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF；另有
 **不传 `kb` 的旧接口与旧工具一律作用于默认库，行为不变**。
 
 ```ts
-interface KnowledgeBase { id; name; description; rootDir; isDefault; sourceTypes; wikiTypes; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
+interface KnowledgeBase { id; name; description; rootDir; isDefault; wikiTypes; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
 ```
 
-`sourceCount` / `cardCount` / `noteCount` / `buildVersion` 和每条分类/类型的计数都是
+`sourceCount` / `cardCount` / `noteCount` / `buildVersion` 都是
 **计算字段**，由真实 runtime 重新统计并缓存进同一个 JSON，
 HTTP `GET /knowledge/bases` 在返回前先刷新。
 
@@ -231,14 +282,14 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
 | `domain_knowledge/` | 知识树，按知识库 id 分叉 | 丢数据 |
-| `memory/<知识库 id>/` | 版本快照、反馈、访问审计（append-only） | 丢历史，不可重建 |
-| `intent/` | `registry.json`（分类 / act 词表）+ `records.ndjson`（每轮一条留痕） | 丢配置与审计流 |
+| `memory/<知识库 id>/` | 抽取轨迹、轴 / Knowledge 真源、处理日志、反馈与访问审计（append-only） | 丢历史，不可重建 |
+| `intent/` | `intent.db`（当前记录 + 审计历史） | 丢审计流 |
 | `output/` | 交付物，二级按日期分桶 | 什么都不损失 |
 | `tmp/` | 运行期临时文件，二级按日期分桶 | 只影响未完成的任务 |
 | `resource/` | 模型、Python 环境、`knowledge-bases.json` | 失去语义检索（嵌入/重排不可用） |
 
-**记忆与意图为什么与知识树平级**：记忆装的是版本快照与审计流水 ——
-那是**关于这个 Agent 的动作留痕**，不是关于知识的断言；留在知识树里会让「备份知识树」
+**记忆与意图为什么与知识树平级**：记忆装的是**关于这个 Agent 的动作留痕**（抽取轨迹、
+轴与 Knowledge 真源、处理日志、审计流水），不是关于知识的断言；留在知识树里会让「备份知识树」
 被迫连审计一起备份，也让「知识树有哪几段」这个问题混进一个横切层。意图则是**会话级**的
 （同一句话在哪个知识库下说，理解方式不该变），所以它不分库。这样知识、记忆、意图三段
 都是可以直接备份、直接 diff 的用户文件。
@@ -248,12 +299,12 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
-| `01_source_raw/<source_type>/` | SourceRaw，一级是**来源分类**，二级是文档（**文件名 = 标题**，0051） | 丢数据 |
+| `01_source_raw/` | SourceRaw，文件名 = 标题（0051） | 丢数据 |
 | `02_wiki/<entity_type>/` | Wiki 卡片，一级是卡片类型 | 丢结论 |
 | `03_compiled/` | wikiNotes / 向量 / 知识图谱 / 归因图谱 | 可重建 |
 
-**归因图谱也在这三段里**（v1.1）：一次排查的产物是一条来源分类为 `agent_diagnosis_case`
-的 SourceRaw（落 `01_source_raw/`），模板卡由类型定义派生、不落盘，字段级的归因图
+**归因图谱也在这三段里**（v1.1）：一次排查的产物是一份带溯源信息的 SourceRaw（落
+`01_source_raw/`），模板卡由类型定义派生、不落盘，字段级的归因图
 落 `03_compiled/diagnosis_graph.json`。旧的 `05_diagnosis/` 撤销了；它里面的 `*.jsonl`
 如果还在，角色是**只读的迁移输入与历史快照** —— 不再被写，但仍然读得出来（证据与根因
 就从那里来），所以旧知识根不会因为这次改动而读不出内容。
@@ -263,7 +314,7 @@ schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类
 启动时会把空的那个目录删掉 —— **非空则保留**：那就不属于「没用的空文件夹」了，
 删掉别人的文件比留一个空目录危险得多。
 
-**文件名用标题（0051）。** `01_source_raw/<分类>/阿里集团大数据建设OneData体系.md` —— `ls`
+**文件名用标题（0051）。** `01_source_raw/阿里集团大数据建设OneData体系.md` —— `ls`
 认得出、`grep` 文件名有用、`git diff` 看得出改的是哪份材料；`source_id`（`article:bc82…`）仍是
 稳定身份，住在 front matter 里。三条配套规则：①标题里的路径不安全字符换成 `-`、截断到 120 字符、
 只剩替换字符时退回 `source_id`；②**重名默认拒收**（`SOURCE_TITLE_DUPLICATED`，报错指出被谁占着，
@@ -272,13 +323,8 @@ schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类
 并回一条 warning。改名与迁移（老段名 `01_source_truth` → `01_source_raw`、文件名换成标题）在
 `ensureLayout` 里一次性完成，**可重入**；存量正文里带老段名的图片引用不改写，解析器认两个段名。
 
-`01_source_raw` 按分类分目录（而不是平铺）的理由与 `02_wiki` 一致：分类是每份来源的
-必备元数据（frontmatter 的 `source_type`），提到目录名上之后「按分类找东西」在文件系统
-层面直接成立，不依赖界面。平铺在真实使用里会先变成垃圾场 —— 几十份来源混在一层，`ls`
-读不出「我的指标口径在哪」。启动时一次性把平铺的文档搬进分类目录；读路径不依赖这个层级
-（启动时会递归扫全段建 slug → path 索引），所以旧布局、新布局与两者并存的中间态
-都能读。**改分类 = 换目录**：`add_source` 用同一 `sourceId` 配新 `sourceType` 时，旧目录
-里那份会被删掉，不会留下孤儿。
+`01_source_raw` 直接平铺来源文档：文件名就是标题，`source_id` 保留稳定身份，格式、作者、
+外部链接等通用信息写在 front matter。目录结构不承担业务分类职责。
 
 `resource/` 装模型、虚拟环境与 `knowledge-bases.json` —— 「这个 Agent 的全部磁盘足迹」
 因此是一个目录，备份 / 迁移 / 整个删掉都只需要认一个路径。模型与虚拟环境原先住在
@@ -316,17 +362,21 @@ GB）；旧的 `TITA_DATA_AGENT_HOME` 留在解析链上作为兜底，所以搬
 ```text
 GET    /knowledge/bases                                            → { bases, defaultBaseId }
 POST   /knowledge/bases        { name, description?, rootDir? }    → { base }
-PATCH  /knowledge/bases/:id    { name?, description?, sourceTypes?, wikiTypes? } → { base }
+PATCH  /knowledge/bases/:id    { name?, description?, wikiTypes? } → { base }
 DELETE /knowledge/bases/:id                                        → { deleted: true }
-GET    /knowledge/documents?kb=&query=&source_type=&limit=&offset= → { documents, total }
+GET    /knowledge/documents?kb=&query=&limit=&offset=        → { documents, total }
 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 }
+GET    /knowledge/documents/:docId/delete-impact?kb=               → { knowledge, cards, extractionRuns }（只读，删除前查账）
 POST   /knowledge/documents/:docId/revert?kb= { versionId }        → { document }
-DELETE /knowledge/documents/:docId?kb=                             → { deleted: true }
+DELETE /knowledge/documents/:docId?kb=                             → { deleted: true }（级联：知识、卡片、抽取轨迹）
 GET    /knowledge/assets/:kb/*                                     → 知识库根目录下的文件流
 GET    /knowledge/doc-page.js                                      → 独立整页的脚本（构建产物）
+GET    /knowledge/pages/trial?kb=                                  → 抽取试跑（HTML 整页）
+GET    /knowledge/pages/help/:topic                                → 说明整页（compile / intent）
+GET    /knowledge/pages.js                                         → 通用整页的脚本（构建产物）
 POST   /knowledge/import       { kb, sources[], compile? }          → { written[], failed[], attempted, compile|null }
 POST   /knowledge/card-annotate { kb, entity_id, kind?, note?, remove_id? } → { entityId, annotations, reviewScore }
 POST   /knowledge/card-review   { kb, entity_id, action }          → { entityId, review, reviewScore, status }
@@ -353,8 +403,8 @@ POST   /diagnosis/run           { kb, record }                     → { sourceI
 成因。要读全文走 `.../view` 那个独立整页：它按 `offset`/`limit` **一页一段**地取
 （默认 20000 字符一页，切点对齐空行），所以任何一次响应都不与文档大小成正比。
 
-`/knowledge/stats`、`/knowledge/search`、`/knowledge/rebuild`、`/knowledge/cards`、
-`/knowledge/sources`、`/knowledge/graph`、`/knowledge/embedding/health` 与全部
+`/knowledge/stats`、`/knowledge/search`、`/knowledge/rebuild`、`/knowledge/export`、
+`/knowledge/cards`、`/knowledge/sources`、`/knowledge/graph`、`/knowledge/embedding/health` 与全部
 `*_knowledge*` 工具都接受**可选** `kb`（query 或 body 字段）。`docId` 含 `:`
 （如 `document:ab12…`），必须 URL 编码。
 
@@ -362,9 +412,6 @@ POST   /diagnosis/run           { kb, record }                     → { sourceI
 
 | 操作 | 条件 | 错误码 | 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 |
 
@@ -372,17 +419,92 @@ POST   /diagnosis/run           { kb, record }                     → { sourceI
 同时给出 envelope 的 `error.code` 与顶层 `code`/`message`。删除知识库只删注册表条目，
 **不删磁盘内容**（删文档用 `DELETE /knowledge/documents/:docId`）。
 
+### 抽取的参考：已有坐标进提示词（0068）
+
+抽取提示词里**带上了库里已有的坐标**（名字 + 别名 + 定义 + 人写的指导），模型据此**指认**
+「原文讲的这个东西就是已有的某一个」，而不是每份文档都造一套新名字：
+
+```jsonc
+// 模型输出的 objects / actions / scenes 每一项
+{ "name": "坑位点击", "definition": "一句话说清它指什么", "existing": "通天塔坑位click" }
+```
+
+三条要点：
+
+- **模型的话是提案**。`existing` 要换成实体 id 才交给注册表，而换不到（查不到 / 不同轴 /
+  已被并）就退回机械解析 + 新建 —— 与卡片层 `existing_id` 同一条纪律。
+- **定义有主**。模型只在新建时写、或给一个还没有定义的实体补一次；人改过之后
+  （`description_source = human`）模型一个字都改不了。
+- **截断不静默**。每类最多下发 200 条，超了在提示词里明说「还有 N 个没列出来」，报告里
+  写「下发 40 / 共 312」。模型看不到某条坐标时会把「清单里没有」读成「库里没有」。
+
+坐标清单进的是**用户提示词**（system 是缓存前缀，不许带库内数据）。每库还有一条
+**坐标提取备注**（`knowledge-bases.json` 的 `extractionNote`），逐字进提示词 ——
+它是用户唯一能「指挥模型怎么认坐标」的地方，抽取规则本身不可编辑。
+
+### 坐标即卡片身份（0069）
+
+```text
+Document ──▶ Knowledge × N ──▶ 坐标 (对象 × 动作 × 场景) ──▶ Wiki Card（唯一）──▶ 章节是检索单元
+                                    索引                  组织与交付视图            知识是证据层
+```
+
+> **一个坐标最多一张卡**，这件事由 `knowledge.db` 的 `card.coordinate_key` **主键**兜着，
+> 不是靠约定。`entity_id` 仍保留为旧接口、版本历史和关联表使用的稳定别名。
+
+四条要点：
+
+- **卡片上记着它的坐标**（`card.object_id / action_id / scene_id` + front matter 的
+  `coordinate`）。坐标在这一层是**轴实体 id**，卡名只是显示 —— 0069 之前坐标算出来、
+  推出卡名、然后被丢掉，「这张卡是哪个坐标」只能从卡名字面反推。
+- **判重的顺序是「先坐标，再认领，最后新建」**。第 2 级「认领」同时是存量数据的迁移
+  路径：0069 之前的卡片三列全空、**补不回来也不许猜**，由第一份带来该坐标的文档把它绑上。
+- **不同坐标推同一个卡名 = 两张卡**（0069 之前它们会被按名字静默并成一张）。
+  撞名仍然报 warning，但它的后果从「身份错」退化成「标题重」。
+- **落位落库**（`card_knowledge`，0063 §4.5）：`section` / `ordinal` 是**关联**的属性。
+  召回命中**章节**之后，按这一节取它落位的知识（含四档状态与出处引文）——
+  0069 之前 `disputed`（「有相反的说法」）渲染进正文后与确定的事实长得一样。
+
+**坐标不替代图。** 图是**从 Knowledge 派生的可选关系索引**，回答的是「通天塔依赖哪些表」
+这类任意关系与反向关系；坐标回答的是「这条知识关于什么」。见
+[docs/current/14](../../docs/current/14-智能归因.md) §7.3。
+
 ### 版本存储与回滚语义
 
-在 `addSource` 覆盖写入之前，如果目标文件**正文**与新的正文不同，就把**旧文件字节**
-原样快照到 `memory/<库 id>/source-versions/<docSlug>/<versionId>.md`，
-`versionId = <紧凑ISO时间>-<contentHash 前 8 位>`（如 `20260102T030405123Z-9f3c1a2b`）。
-内容完全相同的重复写入不产生版本。快照本身也是 markdown（含 frontmatter），
-`listVersions` 返回新→旧，并把当前 head 作为 `isCurrent: true` 的第一条一并列出
-（head 的 `versionId` 形如 `current-<hash8>`）。
+**版本住在 `knowledge.db` 的 `revision` 表里**（0062 v2）。一次写入 = 一行 `revision`
+（身份是 `(entity_kind, entity_id, version)`）+ 一行 `blob`（正文按 sha256 内容寻址）。
+正文完全相同的重复写入**不产生新版本**，只更新 front matter 那类记账字段。
+`listVersions` / `cardVersions` 返回新→旧，并把当前 head 标成 `isCurrent: true`；
+`versionId` 就是**整数版本号的字符串形式**（卡片那些旧 `'head'` 哨兵会被 `VERSION_IS_HEAD`
+拒掉）。
+
+**回滚 = 用历史版本的正文重新写一次**：回滚前会把当时的 head 再记一版，所以历史只增不减，
+**回滚本身也可回滚**。回滚到当前版本是 no-op。
+
+`memory/<库 id>/source-versions/` 与 `card-versions/` 是**旧的文件式快照**：仍然被读
+（迁移把它们当历史导入），但**不再被写**。
+
+### 起编译的语义（0066）
+
+`POST /knowledge/rebuild` **立即返回** `202 { runId, queued }` —— 它只回答「这一趟的编号
+是什么」与「前面还有没有人在跑」。编译在后台跑完，结论写进
+`GET /knowledge/compile-progress` 的记录里：
+
+```jsonc
+{ "progress": { "runId": "rebuild_…", "startedAt": "…", "finishedAt": "…",
+                "steps": [ /* 四段 */ ], "outcome": "索引 v21：…",
+                "report": { /* 与旧版 rebuild 响应同一份 RebuildReport */ } } }
+```
+
+`?runId=<编号>` 指名要哪一趟；不给编号时给**正在跑**的那一趟（没有在跑就给最近结束的那一趟）。
+已结束的记录按编号留 8 条，所以后面那一趟开始跑**不会**抹掉上一趟的结论。
+
+**为什么结论不走那条 POST 的响应**：编译是分钟量级的，而一条 HTTP 请求活不了那么久。实机上
+312 秒的编译在 300 秒被切断，面板于是把「请求死了」读成「没有编译」—— 而编译 11 秒后就成功了。
+结论因此落在**与任何一条请求都无关**的记录里。
 
-**回滚 = 用快照内容重新调用 `addSource`**：因此回滚前会把当时的 head 再快照一次，
-历史只增不减，**回滚本身也可回滚**。回滚 `current-*` 是 no-op。
+`rebuild_knowledge` 工具**仍然是同步的**（`runtime.rebuild()`）：工具调用不是浏览器请求，
+等得起，要的就是「跑完了，结论是什么」。同一时刻只有一次编译在跑，后来的排队。
 
 ### 召回链路（两路 + 图谱 boost）
 

package/cordis.patch.yml

@@ -1,12 +1,11 @@
-# data-domain-knowledge bundle patch: mount the knowledge / intent / convert host.
+# data-domain-knowledge bundle patch: mount the knowledge / intent audit / convert host.
 #
 # 0.1.7 起这条 entry **自己就是设置文档**：插件导出的 `Config`（见
-# `src/config-schema.ts`）把三块设置合成一个 schema —— `knowledge` / `intent` /
-# `convert`，正是 0.1.5 那三个设置命名空间（`tita-data-agent-knowledge` /
-# `-intent` / `-convert`）。设置页里的改动由 `configEditor` 写回**本 entry 的
+# `src/config-schema.ts`）把两块设置合成一个 schema —— `knowledge` / `convert`。
+# 会话意图使用固定审计契约，不属于 entry config。设置页里的改动由 `configEditor` 写回**本 entry 的
 # `config:`**，客户端按路径读写（`{op:'set', path:['knowledge','recallTopK']}`）。
 #
-# 所以这里**故意不写 `config:`**：三组字段全都有 schema `.default()`，而
+# 所以这里**故意不写 `config:`**：两组字段全都有 schema `.default()`，而
 # `knowledge.agentRoot` 的默认值就是 `~/Desktop/titaagent`（`defaultAgentRoot()`，
 # 可被 `DSH_AGENT_ROOT` 覆盖）。往这里写死一个 `agentRoot` 会把「Agent 的家在哪」
 # 这件事从代码挪进某台机器的配置文件里 —— 那正是 0029 想收拢的那一个答案。
@@ -43,8 +42,8 @@
           #    提示词。这一行是**这个 preset 存在的理由** —— 它 shadow 掉部署级的 persona，
           #    所以只有加入这个 preset 的会话会以数据 Agent 的身份说话。提示词正文就在下面，
           #    直接改它即可；改完**新建一个会话**才生效（preset 在会话创建时固定）。
-          # 2. **意图工具**（`intent-tools` 行）：`intent_record` / `intent_store_view` /
-          #    `intent_registry_list` 三个工具搬到 agent 平面，只有这个 preset 的会话能看到。
+          # 2. **意图工具**（`intent-tools` 行）：`intent_record` / `intent_store_view` 两个工具
+          #    搬到 agent 平面，只有这个 preset 的会话能看到。
           #    DSH 里「只有某个 preset 能用」唯一支持的形态就是注册作用域，所以它们必须在这里
           #    挂载，而不是在宿主平面全局注册（那会让每个 agent 都看到 intent_record）。
           # 3. **子代理不许继承意图工具**：子代理会加入父会话的组合，所以要在 delegation 的每一
@@ -76,14 +75,17 @@
 
                 ## What you work with
 
-                - **The knowledge store.** Each knowledge base on disk is a tree.
-                  `01_source_raw` holds SourceRaw: the original business documents, never
-                  rewritten, kept so that a conclusion can point back at where it came from.
-                  `02_wiki` holds the cards people read — one per entity, each with mandatory
-                  `source_refs`, each following a type (`concept`, `metric`, `table`, `event`,
-                  `playbook`, `case`). `03_compiled` is what `recall_knowledge` actually
-                  searches: wikiNotes, a vector index and a knowledge graph. `05_diagnosis` is
-                  the attribution graph the panel renders. There can be several bases.
+                - **The knowledge store.** Each knowledge base is one directory holding three
+                  things. `knowledge.db` is the knowledge itself: SourceRaw (the original
+                  business documents, never rewritten, kept so a conclusion can point back at
+                  where it came from), the cards people read — one per entity, each with
+                  mandatory `source_refs`, each following a type (`concept`, `metric`, `table`,
+                  `event`, `playbook`, `case`) — and every version of both, plus who changed
+                  what and when. `derived.db` is what `recall_knowledge` actually searches:
+                  wikiNotes, a vector index, a knowledge graph and a keyword index; it is
+                  recomputed, never backed up. `assets/` holds images. There are no
+                  per-segment folders inside a base; use the knowledge tools, not the
+                  filesystem, to read or write documents. There can be several bases.
 
                 - **The data surfaces, which are a different thing.** `workbook_*` reads and
                   writes the workbooks the user has open; `notebook_*` runs SQL in the user's
@@ -92,8 +94,9 @@
                   a `table` card says what one row means. Computing without the definition gets
                   you a number nobody agreed to.
 
-                - **Conversion.** `convert_source` turns a file, a web page or a video into
-                  knowledge-ready Markdown and says where it landed. It is not knowledge until
+                - **Conversion.** `convert_source` turns a local file (including a web page
+                  saved to disk as `.html`) or a video into knowledge-ready Markdown and says
+                  where it landed. It never fetches a URL itself. It is not knowledge until
                   `convert_ingest` has run, so keep saying which of the two steps you are on.
 
                 ## Working rules
@@ -147,10 +150,13 @@
                 9. **Deliverables belong to the project, not to your home.** Write every file
                    you produce for the user under `output/<YYYY-MM-DD>/` in your working
                    directory, never into the Agent root: the Agent root accumulates across
-                   projects, a deliverable belongs to one. Name it `<topic>-<kind>.<ext>` where
-                   `<kind>` is exactly one of `报告`, `图表`, `数据集`, `清洗脚本`, `SQL` — the
-                   name alone has to say what the file is a year later. Append `-2`, `-3` rather
-                   than overwriting, and say the path in your answer.
+                   projects, a deliverable belongs to one. Name the file `<中文名>.<ext>` — at
+                   most 25 characters, keeping 汉字, letters, digits, `-`, `_` and `.`, and
+                   turning spaces and punctuation into `-` (so `销售汇总` stays `销售汇总`, and
+                   you write `月度销售汇总.xlsx`, not `output1.xlsx`). **Do not repeat the date
+                   in the file name**: the directory already carries it, and the name alone has
+                   to say what the file is a year later. Append `-2`, `-3` rather than
+                   overwriting, and say the path in your answer.
 
                 ## How to write
 
@@ -332,7 +338,6 @@
                     deny:
                       - intent_record
                       - intent_store_view
-                      - intent_registry_list
 
               # Fork omits model selection so provider/model stay equal to the parent and
               # the inherited history remains eligible for KV Cache reuse. This preset
@@ -348,7 +353,6 @@
                     deny:
                       - intent_record
                       - intent_store_view
-                      - intent_registry_list
 
               # Production dsh does not install these optional providers. Install the
               # matching Bundle in this Profile and restart the Host, then copy this
@@ -366,7 +370,6 @@
                     deny:
                       - intent_record
                       - intent_store_view
-                      - intent_registry_list
 
               - id: tool-subagent-claude-code
                 name: '@deepseek-ai/dsh-tool-subagent'
@@ -380,7 +383,6 @@
                     deny:
                       - intent_record
                       - intent_store_view
-                      - intent_registry_list
 
               # 0.1.7 把这行换掉了：旧包名 `@deepseek-ai/dsh-workflow-worker-thread` 在
               # 0.1.7 的安装里已经不存在，对应物是 `@deepseek-ai/dsh-workflow-ptc`

package/eval/README.md

@@ -7,8 +7,8 @@
 ## qrels 格式
 
 每行一个 JSON 对象，`relevant_unit_ids` 使用编译后的稳定 `unitId`，例如
-`metric:sales_amount`。可以附加 `source_types`、`include_problems` 和 `subset`，用于
-分组评测文本、图片 Markdown、表格截图等场景。
+`metric:sales_amount`。可以附加 `include_problems` 和 `subset`，用于分组评测文本、
+图片 Markdown、表格截图等场景。
 
 ```json
 {"id":"q1","query":"销售额如何计算","relevant_unit_ids":["metric:sales_amount"],"subset":"text"}