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

package/README.md

@@ -11,8 +11,7 @@
 
 Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/tita-agent`）。
 设置面板只展示这个目录并提供「打开目录」，不允许切换根路径；知识库、意图记录、记忆、
-模型和 Python 环境都从这里派生。新版本不读取、不搬运旧版本的
-`~/Desktop/titaagent` 与 `~/.tita-data-agent` 数据；旧数据需要用户自行处理。
+模型和 Python 环境都从这里派生。
 
 ## 承载范围（五个视图）
 
@@ -27,8 +26,7 @@ Tita Agent 的固定数据根目录是 `$DSH_HOME/tita-agent`（默认 `~/.dsh/t
 | `eval` | 评测 | 问题集格式（开发期能力，不注册运行时入口） |
 
 意图的**会话审计留痕**落在 `<agentRoot>/intent/`：`intent.db` 保存当前记录与追加历史
-（按 `sessionKey#turn` 读取时取当前版本，所以内存里「一轮一条」的语义不变）。旧的
-`records.ndjson` 只做一次性迁移，不再继续写入。
+（按 `sessionKey#turn` 读取时取当前版本，所以内存里「一轮一条」的语义不变）。
 分类与 act 是代码内置的固定契约，不提供编辑入口。读接口 `/intent/store` 与 `/intent/overview` 读的是**留痕**：
 引擎内存里那份有 600 秒 TTL，重启或隔一段时间回来不该让面板上的历史凭空消失。
 
@@ -39,7 +37,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 段在**界面上是同一栏**（知识库 → 召回重排）。它们在流水线上仍是两步，
@@ -93,24 +91,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 +138,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 +173,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 +193,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 +201,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 +250,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 +260,7 @@ interface KnowledgeBase { id; name; description; rootDir; isDefault; wikiTypes;
 **计算字段**，由真实 runtime 重新统计并缓存进同一个 JSON，
 HTTP `GET /knowledge/bases` 在返回前先刷新。
 
-**根路径下是六段**：
+**Agent 数据根目录包含以下内容**：
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
@@ -299,51 +277,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 +316,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 +406,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 +428,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 +442,7 @@ Document ──▶ Knowledge × N ──▶ 坐标 (对象 × 动作 × 场景)
 ```jsonc
 { "progress": { "runId": "rebuild_…", "startedAt": "…", "finishedAt": "…",
                 "steps": [ /* 四段 */ ], "outcome": "索引 v21：…",
-                "report": { /* 与旧版 rebuild 响应同一份 RebuildReport */ } } }
+                "report": { /* RebuildReport */ } } }
 ```
 
 `?runId=<编号>` 指名要哪一趟；不给编号时给**正在跑**的那一趟（没有在跑就给最近结束的那一趟）。