dsh-data-domain-knowledge 0.1.0-alpha.13 → 0.1.0-alpha.14

package/README.md

@@ -1,12 +1,12 @@
 # dsh-data-domain-knowledge
 
-本地知识库插件：一个知识库是一个目录，里面四样东西。`knowledge.db` 保存 **SourceRaw**
-（原始可追溯文档）、按主题聚合可双向链接的 wiki 卡片，以及**两者的每一个版本**；
-`derived.db` 输出可检索的 **wikiNotes**、wiki
-知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存操作日志、抽取轨迹、访问审计与反馈。
+本地知识库插件：一个知识库对应一个目录。`knowledge.db` 保存 **SourceRaw**
+（原始可追溯文档）、轴、Knowledge、Event、wiki 卡片、版本与阶段检查点；
+`derived.db` 保存可重建的 **wikiNotes**、知识图谱和向量索引，`assets/` 保存图片与附件。
+知识库目录外的 `<agentRoot>/memory/<库 id>` 保存任务与正式输出、抽取轨迹、操作日志、访问审计与反馈。
 默认使用本地 Python 推理：`BAAI/bge-small-zh-v1.5` 生成 512 维文本向量，
 `BAAI/bge-reranker-base` 对召回候选做交叉编码重排。部署入口必须完成环境自检，
-索引必须匹配当前模型；不满足时提示准备环境或重新编译。
+索引必须匹配当前模型；不满足时提示准备环境或构建检索索引。
 需要图片语义检索时，可配置 WeMM 多模态模型与匹配维度，Markdown 中的本地图片
 会与正文一起交给模型。图片不作为独立知识类型。
 
@@ -16,10 +16,10 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 
 ## 首次运行环境准备
 
-向量模型和重排模型是部署必需项。打开 Tita 设置 → 环境准备 → 一键安装 / 修复。
-系统用 DSH 自带的 Python 3.12 创建专属依赖环境，不另行下载 Python；再下载固定 revision 的 `BAAI/bge-small-zh-v1.5`
-（512 维）和 `BAAI/bge-reranker-base`，然后运行真实推理自检。阶段、错误和下载日志
-可查看；下载失败可以重试。未就绪时阻止编译和知识召回，来源与历史内容仍可保存、读取。
+向量模型和重排模型在 Tita 设置 → 环境准备中选择，再安装 / 修复。
+系统用 DSH 自带的 Python 3.12 创建专属依赖环境，不另行下载 Python；再下载所选模型，
+默认是 `BAAI/bge-small-zh-v1.5`（512 维）和 `BAAI/bge-reranker-base`，然后运行真实推理自检。阶段、错误和下载日志
+可查看；下载失败可以重试。就绪检查按所用能力执行：抽取、归一和物化只需要 LLM；构建向量索引需要向量模型；召回按启用的向量和重排能力检查。来源与历史内容仍可保存、读取。
 自检不单独检查 `sentencepiece`；依赖安装失败会显示安装错误，模型真实推理失败会显示对应模型的错误。
 
 命令行入口：
@@ -31,7 +31,7 @@ pnpm --filter dsh-data-domain-knowledge doctor
 ```
 
 自检失败时命令返回非零退出码。依赖装在 Tita 专属虚拟环境中，不修改系统 Python，也不隐式运行 npm postinstall
-模型下载。已有知识在准备完成后需重新编译；宿主无需重启。自定义路径保留，使用默认
+模型下载。已有卡片在准备完成后需构建检索索引，文档无需重新抽取；宿主无需重启。自定义路径保留，使用默认
 资源时把高级设置中的路径恢复为空，并使用匹配的向量维度。
 细节见 [运行环境准备与自检](../../docs/current/16-知识运行环境准备与自检.md)。
 
@@ -52,19 +52,49 @@ pnpm --filter dsh-data-domain-knowledge doctor
 分类与 act 是代码内置的固定契约，不提供编辑入口。读接口 `/intent/store` 与 `/intent/overview` 读的是**留痕**：
 引擎内存里那份有 600 秒 TTL，重启或隔一段时间回来不该让面板上的历史凭空消失。
 
-## 五段链路
+## 独立运行知识链路
 
-| 段 | 名称 | 产物 | 关键配置 |
-| --- | --- | --- | --- |
-| 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` |
-| 5 | 重排 Rerank | BERT cross-encoder 对候选 wikiNotes 精排，取 `contextTopN`（默认 5）组成 `context` | `contextTopN` / `rerankProvider` / `rerankModel` |
+导入默认只保存来源。打开「知识处理」页面，按需运行以下阶段。也可以选择「全链路运行」。
+
+| 阶段 | 输入 → 产物 | 模型与复用 |
+| --- | --- | --- |
+| 入库 | 文档 → SourceRaw 与版本 | 不调用模型；`import_sources` 默认 `compile: false` |
+| 抽取 Knowledge / Event | 指定来源版本 → 原始 mention、引文与抽取检查点 | 本库所选 LLM；默认表格输出，兼容历史 JSON；未变化来源复用 |
+| 归一合并 | 保存的抽取返回 → canonical 轴、Knowledge、Event | 精确查注册表；必要时模型补判；不重新抽取文档 |
+| 物化 WikiCard | Knowledge 完整坐标分组 → 卡片与章节；Event 只建立同坐标引用 | 可选模型组织；Event 不进入卡片正文，也不单独生成 WikiCard |
+| 构建检索索引 | 已保存卡片 → Wiki Note、FTS、向量与图谱 | 使用所选向量模型；事务发布一份检索快照 |
+| 召回与重排 | Query → 多路候选 → RRF / 图谱加权 → 重排 → Context | 候选池先于最终截断；单个候选也经过重排阈值；停用卡片不召回 |
+
+向量、重排模型在环境准备中按列表选择；安装并通过实际推理后启用。选择托管模型会替换高级设置中的自定义模型路径，自检失败会恢复。更换向量模型只需重建索引，不需要重新抽取。
+
+本库「编译设置」支持选择 LLM 与模型声明的思考强度。任务入队时保存实际路由、强度、抽取备注与卡片组织设置；修改设置作用于后续任务。
+
+### 运行接口
+
+- `run_knowledge_pipeline`：`stage` 为 `extract`、`normalize`、`materialize`、`build` 或 `all`。`source_ids` 限定文档，`group_keys` 限定完整卡片分组。`force` 显式强制当前阶段。
+- `get_knowledge_pipeline`：不传 `task_id` 返回阶段待办与任务历史；传任务 ID 与 `after` 游标读取状态和正式输出。刷新后可补读。
+- `get_knowledge_events`：按召回 WikiCard 的 `metadata.event_refs` 读取对应 Event，不把整库事件加入每次召回。
+- `GET/POST /knowledge/pipeline`：阶段状态 / 创建后台任务。`GET /knowledge/pipeline-tasks` 分页读历史，`GET/POST /knowledge/pipeline-task` 读输出 / 暂停、继续、停止、重新运行。
+- `import_sources` 显式 `compile: true` 对本批写入的来源运行完整链路。`rebuild_knowledge` 仅重建已保存卡片的检索产物；正式抽取使用独立阶段接口。
+- 抽取试跑仅保存审计报告；预览实体解析使用隔离副本，不写正式 Knowledge 或实体注册表。
+
+旧 `runtime.rebuild` 保留兼容的规则抽取兜底。当前 HTTP / 工具重建默认只构建已保存卡片的检索产物；独立阶段的模型失败会明确失败，不自动切换到规则抽取。
+
+### 增量、失败与证据
+
+抽取指纹包括文档正文、标题、抽取契约、备注、LLM 路由与强度；卡片模板与无关实体更新不会强制重抽。归一、物化分别维护自己的依赖指纹。
+
+归一时先在内存副本解析实体。提交前核验来源版本和实体注册表；在短事务中提交实体、Knowledge、Event 和归一检查点。重新归一会撤回该来源旧版本的有效贡献，并保留出处历史。其他来源支撑的同一事实继续有效。Event 根据明确身份归并，文本相似不触发跨文档合并。
+
+来源已变化或新抽取尚未归一时，涉及的卡片分组显示「先归一来源」。物化按唯一坐标分组计数；不按 Knowledge 条数估算卡片数。Event 与 Knowledge 同层独立保存；WikiCard 只由 Knowledge 生成，并保存同坐标 Event 的引用。物化失败保留旧卡片。归一与物化不会提前更新已发布检索索引；构建成功后统一发布。删除与停用仍立即限制召回可见性。
+
+任务状态与输出写入既有抽取审计库。暂停、停止在当前文档或卡片边界生效。服务重启把未结束任务标记为中断，已完成检查点保留；重新运行默认复用成功项。实时预览每份来源最多 4 MB，完整模型返回保存在报告中；页面显示最近输出。
+
+**目录边界的原理：** `src/pipeline/` 只承接阶段契约、持久检查点和任务编排；领域归一、成卡与检索继续调用现有运行时。业务检查点仍在 `knowledge.db`，任务审计仍在原有记忆库，索引仍在 `derived.db`。不新增一套业务真源，也不把不可重建的模型返回放进可清理的派生层。
+
+### 表格格式基准
 
-> 第 4、5 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步，
-> 但「跑一次真实召回长什么样」是一个问题，分两栏会让用户先跑召回、再切到重排才能
-> 看到同一次运行的全貌。
+运行 `pnpm bench:extraction-format`。脚本使用同一份中文语义载荷，以 `o200k_base` 比较 TOON 与紧凑 JSON 的输出 token；不代表具体模型账单或抽取准确率。示例中，12 条知识减少 43.8%，40 条减少 51.6%；单条增加 6.9%，因为固定表头有开销。实际效果取决于字段长度、引文重复率和模型 tokenizer。
 
 ## Knowledge / Wiki Card 的存储约束
 
@@ -73,8 +103,10 @@ pnpm --filter dsh-data-domain-knowledge doctor
 | 层 | 真源 | 说明 |
 | --- | --- | --- |
 | Knowledge | `knowledge` + `knowledge_sources` | 原子事实、坐标、来源、状态；不保存 Card 的排版 |
+| Event | `event` | 一次事件、时间线、结果、证据与来源；独立于 WikiCard 保存 |
 | Wiki Card | `card` + `blob` + `revision` | 面向阅读和召回组装的正文；正文中的 Markdown 标题是 Section 真源 |
 | Knowledge 落位 | `card_knowledge` | 记录 Knowledge 在某张 Card 中的 Section 和顺序；这是关联索引，不是 Knowledge 属性 |
+| Event 引用 | `card_event` | 连接同坐标的 WikiCard 与 Event；引用更新不改卡片正文或检索文本 |
 | Wiki Note / FTS / Vector / Graph | `derived.db` | 可以从 Card 和 Knowledge 重新构建；编译结果在同一事务发布 |
 
 ### 状态语义
@@ -120,14 +152,20 @@ Notes、FTS、向量、图和 manifest 在 `derived.db` 中通过一次事务发
 
 ## Knowledge、Wiki Card、Wiki Note 的生命周期
 
-三者不是三个并列的知识真源，而是同一条知识链上的三个层次：
+这条链路包含原始证据、并列的 Knowledge / Event 事实、知识组织卡片和检索派生片段：
 
 ```text
-SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
-             事实真源     阅读组织视图     检索派生片段
+SourceRaw → 抽取 → { Knowledge, Event }
+                    │          │
+                    ↓          │ card_event
+                 WikiCard ←────┘
+                    │
+                    ↓
+                 WikiNote → FTS / Vector / Rerank
 ```
 
-- Knowledge 是不可由 Card 反向重建的事实记录。抽取、来源追加、合并、冲突裁决和状态变化都发生在这里。
+- Knowledge 是不可由 Card 反向重建的事实记录。归一、来源追加、合并、冲突裁决和状态变化都发生在这里；抽取阶段只保存原始返回与检查点。
+- Event 与 Knowledge 是并列事实，分别保留事件时间线和可复用判断。WikiCard 只组织 Knowledge；它按坐标引用 Event，不复制 Event 正文。
 - Wiki Card 是 Knowledge 的组织视图。Card 正文、摘要、Section 和阅读顺序可以重新编排；重新编排不应修改 Knowledge。
 - Wiki Note 是 Card 的检索切片。它没有独立的业务生命周期，`status` 只是父 Card 状态的快照；Card 变化后重新编译 Wiki Note，索引随之重建。
 
@@ -137,11 +175,7 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
 
 - 知识库设置集中在侧边抽屉：数据位置、向量模型、检索与上下文。召回固定使用多路径融合；
   低频设备、阈值和模型细节收在高级设置中。Agent 系统提示词常显，并链接到 preset 真源目录。
-- **编译直接入库（0044）**：`rebuild_knowledge` 的 Pass 0 对指纹变了的来源做实体抽取，
-  按 `entityType:entityId` / `title` / `metadata.aliases` 三重索引判重 —— 命中已有卡片就把
-  新正文**追加**进去（不覆盖、不丢弃），没命中就新建。缺必填小节 / 字段的卡片**照常入库**，
-  问题写进 `metadata.schema_issues`，面板显示成「待补」。**没有任何确认门**：卡片一写盘就进
-  wikiNotes、向量与图谱，立刻可召回。
+- **知识处理分开运行**：抽取只保存检查点，归一写入事实，物化按坐标产出卡片。只有构建检索索引后，新卡片才进入正式召回。任务失败保留已完成项，可查看输出和报告后重新运行。
 - **正文只读，备注可加**：卡片正文由编译产出，人改不了（手工写正文返回
   `WIKI_CARD_IMMUTABLE`）。人的判断落在 front matter 的 `annotations` 上
   （`kind: 'anomaly'` 表示异常点），**编译不会覆盖它**。review（`review_wiki_card`）在入库
@@ -150,16 +184,11 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
   不动 `active` / `deprecated` / `problem` —— 那些是人另外做过的决定）。
   标注异常点会把有效评分压到 `ANOMALY_SCORE`，但卡片**照样召回得到**，只是排在后面。
 
-  **合并按小节折进去**：同一实体被第二份文档命中时，新正文并进相同标签的小节里，
-  每个小节只出现一次；原来还是占位（「（文档未说明）」）的小节被真内容替换。
-  两份正文里只要有一份没有 `##` 结构（规则路径切出来的原文），退回整段拼接。
-- **批量导入只编译一次**（0045）：`import_sources` 收一组来源（一次最多 50 份），逐份写入、
-  **整批只编译一次**，逐条汇报成败 —— 第 7 份坏了不会让前 6 份白写。十份文档不再是十次审批、
-  十次往返、十次抽取。它与 `POST /knowledge/import` 落到同一个运行时方法 `runtime.importSources`，
-  与单份的 `add_source` 只差「一次多少份」。
+- **物化整组重算**：同一坐标的有效 Knowledge 一起组织，沿用卡片 ID、review 和备注；Event 只更新关联引用。只重试物化时不会再次抽取文档。
+- **批量导入只入库**：逐份保存、逐条报告导入失败；显式 `compile: true` 才运行本批来源的全链路。
 - **对话流里有专用卡片**（0045）：`import_sources` / `recall_knowledge` / `rebuild_knowledge` /
   `add_source` / `propose_wiki_cards` 各自带 `presentationMeta`，浏览器半按**工具名**注册
-  `tool.call.toolview`，于是对话里显示的是「导入 3 份来源并编译 · 写入 3 份 · 新建 2 张卡」
+  `tool.call.toolview`，显式编译或回放旧记录时，对话里可显示「导入 3 份来源并编译 · 写入 3 份 · 新建 2 张卡」
   与可展开的命中列表（名次、分数、`entityType:entityId`、review 评分），而不是一坨 JSON。
   meta 随会话日志落盘，所以**回放与当时看到的一致**。
 - **来源里的图跟着文字进卡片**（0047）：抽取那一段交给模型的是文字，模型不会把图带回来，
@@ -170,17 +199,18 @@ SourceRaw → Knowledge → Wiki Card → Wiki Note → FTS / Vector / Rerank
   进 `warnings`。收尾的署名图 / 二维码（图后没有正文且锚点很短）故意不挂。每张 wikiNote
   只带**自己那一节**的图，因为多模态编码只吃每条的**第一张**图。图不参与抽取指纹，所以
   0047 之前编好的库重编时，来源虽然被指纹跳过，图仍然会被补上。
-- **图片引用有三种写法，解析只认「真实存在的那个」**（0047）：`01_source_raw/_assets/…`
-  （规范形，知识库根相对）、`_assets/…`（转换内核早期写进 SourceRaw 的形式）、
+- **旧图片引用兼容三种写法，解析只认「真实存在的那个」**（0047 历史）：`01_source_raw/_assets/…`
+  （当时的知识库根相对规范形）、`_assets/…`（转换内核早期写进 SourceRaw 的形式）、
   `../../01_source_raw/_assets/…`（`cardHints` 给手工建卡的形式）。文档的资产清单与卡片的
   `imagePaths` 走同一个 `assetRefCandidates`（根目录 → `01_source_raw/` → 文件自己的目录），
   否则同一张图在文档里找得到、在卡片里找不到。派生字段（图片路径、溯源链）变了也算
-  「语料变了」，否则增量编译的空操作会把刷新结果丢掉。
+  「语料变了」，否则增量编译的空操作会把刷新结果丢掉。当前新资产写入 `assets/`，
+  上述旧路径不定义新的知识库目录结构。
 - **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` /
+  本身：地址、标题、作者、发布时间）。`created_at` /
   `updated_at` / `metadata` / `lineage` 是我们的扩展键（OKF 明确允许，且要求消费者容忍
   未知键）。
   规范：<https://github.com/GoogleCloudPlatform/open-knowledge-format>（v0.2）。
@@ -247,14 +277,15 @@ bash scripts/setup-embedding.sh
 - 维度：`2048`
 - 设备：`自动（优先 MPS）`
 
-知识库默认保存在 `~/.dsh/tita-agent/domain_knowledge/<库 id>`。点击「编译」后，
-编译结果写入 `derived.db`。未修改的 wikiNote
+知识库默认保存在 `~/.dsh/tita-agent/domain_knowledge/<库 id>`。运行「构建检索索引」后，
+检索产物写入 `derived.db`。未修改的 wikiNote
 会复用已有向量，只有新增或变更的 note 重新编码；编码与重排各自使用常驻 Python
-worker（同一份 `src/python/embedding_worker.py`），避免每个请求重复加载模型。
+worker（同一份 `src/python/embedding_worker.py`），避免每个请求重复加载模型。换向量模型后重建索引，不重抽文档。
 
 BERT 重排默认使用 `BAAI/bge-reranker-base`；如需完全离线，可把模型放到
 `~/.dsh/tita-agent/resource/models/bge-reranker-base`（会被自动发现），或设置
-`DSH_RERANK_MODEL` / 在设置里填写本地路径。未安装时召回会降级到融合分数并给出警告。
+`DSH_RERANK_MODEL` / 在设置里填写本地路径。启用重排的召回按该能力的自检结果放行；
+未就绪时先准备环境，显式停用重排则使用融合分数。
 **目录必须含分词器**（`tokenizer.json` 或 `sentencepiece.bpe.model`）——只有权重时模型会
 加载成功但给所有输入同一个分（`RERANK_TOKENIZER_DEGENERATE`）。
 
@@ -311,14 +342,14 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
 | `domain_knowledge/` | 知识树，按知识库 id 分叉 | 丢数据 |
-| `memory/<知识库 id>/` | 抽取轨迹、轴 / Knowledge 真源、处理日志、反馈与访问审计（append-only） | 丢历史，不可重建 |
+| `memory/<知识库 id>/` | 任务与正式输出、抽取轨迹、处理日志、反馈与访问审计 | 丢历史，不可重建 |
 | `intent/` | `intent.db`（当前记录 + 审计历史） | 丢审计流 |
 | `output/` | 交付物，二级按日期分桶 | 什么都不损失 |
 | `tmp/` | 运行期临时文件，二级按日期分桶 | 只影响未完成的任务 |
 | `resource/` | 模型、Python 环境、`knowledge-bases.json` | 失去语义检索（嵌入/重排不可用） |
 
-**记忆与意图为什么与知识树平级**：记忆装的是**关于这个 Agent 的动作留痕**（抽取轨迹、
-轴与 Knowledge 真源、处理日志、审计流水），不是关于知识的断言；留在知识树里会让「备份知识树」
+**记忆与意图为什么与知识树平级**：记忆装的是**关于这个 Agent 的动作留痕**（任务、正式输出、
+抽取轨迹、处理日志、审计流水），知识断言及其阶段检查点保存在 `knowledge.db`。把动作留痕放进知识树，会让「备份知识树」
 被迫连审计一起备份，也让「知识树有哪几段」这个问题混进一个横切层。意图则是**会话级**的
 （同一句话在哪个知识库下说，理解方式不该变），所以它不分库。这样知识、记忆、意图三段
 都是可以直接备份、直接 diff 的用户文件。
@@ -327,7 +358,7 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 
 | 文件或目录 | 内容 | 删除影响 |
 | --- | --- | --- |
-| `knowledge.db` | SourceRaw、Knowledge、Wiki Card 与版本记录 | 丢失知识真源 |
+| `knowledge.db` | SourceRaw、轴、Knowledge、Event、Wiki Card、版本记录与阶段检查点 | 丢失知识真源 |
 | `derived.db` | wikiNotes、知识图谱、检索索引 | 可重新编译 |
 | `assets/` | 来源图片与附件 | 丢失对应素材 |
 
@@ -390,8 +421,9 @@ POST   /knowledge/card-review   { kb, entity_id, action }          → { entityI
 POST   /diagnosis/run           { kb, record }                     → { sourceId, entityId }
 ```
 
-**0044：入库之后才 review，不再是「确认之后才入库」。** 编译（Pass 0）与
-`propose_wiki_cards` 都**直接写 `02_wiki`**，卡片立刻进编译、进图、能被召回。
+**0044：入库之后才 review，不再是「确认之后才入库」（历史演进）。** 当时编译（Pass 0）与
+`propose_wiki_cards` 直接写 `02_wiki`，随后进入编译与召回。当前卡片保存在 `knowledge.db`，
+新物化的卡片在构建检索索引后进入正式召回；review 仍作用于已经入库的卡片。
 人在面板上做的是 `POST /knowledge/card-review`（review 抬分 / 撤销）与
 `POST /knowledge/card-annotate`（加备注 / 标异常点）—— 两个动作都可逆，
 而且都作用在**已经存在于库里的卡片**上。原来的提议队列

package/cordis.patch.yml

@@ -78,10 +78,9 @@
                 - **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:
+                  where it came from), Knowledge facts, independent Event records, and WikiCards
+                  that organize Knowledge and point to related Events — plus every card version
+                  and who changed what and when. `derived.db` is what `recall_knowledge` 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
@@ -113,28 +112,33 @@
                    record, then continue.
                 2. **Recall before you answer about this organisation.** For its own rules,
                    definitions, metrics, processes or history, call `recall_knowledge` first and
-                   answer from what comes back. An empty result is a finding, not a licence to
+                   answer from what comes back. If a relevant card has `metadata.event_refs`, read
+                   those IDs with `get_knowledge_events` before answering about incident history.
+                   An empty result is a finding, not a licence to
                    improvise — say the store has nothing on it. The wiki layer answers "what does
                    this organisation mean by X"; when you need "where exactly does it say that",
                    or a card and the document behind it disagree, go read the source.
                 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. **Compiling is the normal path, and it writes cards by itself.** You do not
-                   have to create wiki cards: when a source is added or changed, `rebuild_knowledge`
-                   extracts entities from it, follows each wiki type's schema (required sections and
-                   fields), checks whether the wiki already has that entity, and either appends to
-                   the existing card or creates a new one. A card with missing sections is still
-                   written — the store keeps what it knows and fills the rest in when a later
-                   document covers it. So after adding a source, rebuild; then `recall_knowledge`
-                   and answer from what comes back. **More than one document at a time: use
-                   `import_sources`** — it writes the whole batch and compiles once, in one call.
-                   Ten documents through `add_source` means ten approvals and ten compiles, and the
-                   first nine results are thrown away by the tenth.
+                4. **Import and knowledge processing are separate stages.** Use `import_sources`
+                   for a batch. By default it only stores sources; adding or changing a source
+                   never means the user asked to extract or publish it. Report the saved sources
+                   and pending stages. When processing is requested, use `run_knowledge_pipeline`
+                   with `extract`, then `normalize`, then `materialize`, then `build` as needed.
+                   Track its durable task with `get_knowledge_pipeline`; use the output cursor
+                   to inspect model text and failures. `source_ids` limits extraction to selected
+                   documents. Materialization selects complete coordinate groups, combines all
+                   their current Knowledge and Events, and retains the existing card identity.
+                   An explicit full-chain request can use stage `all` or `compile: true` during
+                   import. Unchanged results are reused; never force extraction just to build
+                   indexes or retry materialization. `rebuild_knowledge` rebuilds saved cards'
+                   retrieval artifacts without extracting documents. After successful index
+                   publication, call `recall_knowledge` and answer from returned evidence.
                 5. **You can add to the wiki, but you cannot rewrite it.** Call `propose_wiki_cards`
                    with the `source_id` you just wrote and cards whose `source_refs` already exist in
                    the store when you already have structured cards in hand — it writes them
-                   straight into `02_wiki`, they are recalled from the next compile on. A card whose
+                   into the card store in `knowledge.db`; they are recalled after index publication. A card whose
                    refs point nowhere is rejected, and rightly so. **A card body is read-only**: it
                    belongs to the compiler. When something in the store is wrong, or a card and its
                    source disagree, do not rewrite it — attach an annotation with

package/eval/benchmark-extraction-format.mjs

@@ -0,0 +1,20 @@
+import { encode as tokens } from 'gpt-tokenizer'
+import { encodeExtractionTable, decodeExtractionTable } from '../lib/types/extract-table.js'
+
+// Compare the same semantic payload with the same o200k_base tokenizer.
+// This measures transport size, not model extraction accuracy or the provider's billing.
+function payload(count) {
+  const quote = '经营报表核对前，需要先统一订单状态、统计周期和退款口径。'
+  const sources = [{ quote, heading_path: ['经营报表', '口径核验'] }]
+  return { subject: '经营报表', knowledge: Array.from({ length: count }, (_, index) => ({ id: `k${index+1}`, text: `第 ${index+1} 项核验：统一统计周期，并检查订单状态与退款口径。`, object: '经营报表', action: '核对', scene: '周报', section: '核验步骤', order: index+1, sources })), events: [], objects: [{ mention: '经营报表', definition: '经营指标报表', evidence: quote }], actions: [{ mention: '核对', definition: '核验报表口径', evidence: quote }], scenes: [{ mention: '周报', definition: '每周报表场景', evidence: quote }], dropped: [] }
+}
+const results = [1, 12, 40].map(count => {
+  const value = payload(count)
+  const table = encodeExtractionTable(value)
+  decodeExtractionTable(table)
+  const json = tokens(JSON.stringify(value)).length
+  const toon = tokens(table).length
+  return { knowledge: count, jsonTokens: json, tableTokens: toon, outputReduction: `${((1-toon/json)*100).toFixed(1)}%` }
+})
+console.table(results)
+console.log('固定表头对小样本有额外开销；真实节省取决于行数、字段长度、引文重复率和所选模型的 tokenizer。')