# 交接 · 中医知识库「结构优先」改造 · 新对话从这里开始

> **新对话第一件事：读本文件。**它把任务目标、硬规则、当前状态、可复用脚本、开工步骤、待办全部收在一起，**不需要再读前面 5 份旧交接**（2026-10-02 13:48 / 14:08 / 14:24 / 15:10 / 16:53 那几份，作为历史留档即可）。
> 数字均为本机实测，时间：**2026-10-02 晚**。

---

## 一、任务目标（一句话）

把 46 本中医 EPUB 从**原件**按「结构优先」重新分块，建进一个库；要求**原文完整、出处可追溯、图片与脚注不丢**，检索时能一次命中「一条」而不是半条或几千字一大块。

**总原则（用户已多次确认）**
1. 原文完整、可溯源 **>** 分块与检索效果
2. 不覆盖旧库、不删原文件、不改插件（要改先问）
3. 按书族分类处理，不把一本书的规则机械套到所有书
4. 分批建库、逐本验收；每族首本做完即交付人工/外部复核
5. 图片（含字形图）与脚注必须从 EPUB 保回来

---

## 二、三条硬规则（本任务最容易踩的坑，务必遵守）

1. **判定「条目起首」只按白名单，白名单外一律不拆分。**
   理由：「穴名/脉名/病证名 + 别名 + 空格」的正则会命中**针法口诀、手法连续论述**的句首（形似穴名起首、实为同一段连续论述）。实测：《针灸大成》「一片内含 ≥2 穴条起首」= **0 例**；《脈經校注》「以注释开头的片」= **0 例**。此条是给古籍点校本预置的防误判约束。

2. **逐字无损判据用「12 字滑窗全覆盖」，不要用顺序拼接或元素多重集。**
   理由：源 EPUB 的目录常是**嵌套 div**（同级内容被 level-1、level-2 各包一次），顺序/多重集判据必误报缺字。《针灸大成》目录 522 个嵌套元素实测触发过 1 处假缺口，查实是被父元素完整包含。
   做法：把源 XHTML **每个元素**的文本按 12 字滑窗，检查每个窗口是否出现在库内文本中；顺序无关，缺口 0 才算过。**比对时先去掉 `〔源：…〕` 标记**（标记夹在两片之间会把原文断口误报成缺口）。

3. **必须按「每篇文档自身」的字符预算再收口一次。**
   理由：插件按整篇文档算 `charsPerToken`，各篇预算不同（实测 1296–3015）。不收口会被 `windowBlock` 带重叠切开 → 内容重复、不再逐字无损。

**其他技术约束**
- 单元内部用**单换行**、单元之间用**空行**（插件 `splitBlocks` 以空行为唯一边界）
- 标记行后面**不能多出空行**（否则被切成「标记 + 正文」两块）
- `#`/`##` 开头的行会被 `splitBlocks` 吃掉并变成该块的 `heading`；不想被吃就别用 `#`
- 插件**没有移动文档的接口** → 迁目录只能「取回 `rawText` → 删除 → 按 `parentDirectoryId` 重新入库」
- 源 EPUB 存在 `parseEpub` 不读 OPF spine 的通用缺陷（本批 10 个 EPUB 实测 spine 序 == ZIP 序，无实际损害；上游 issue 未提）

---

## 三、当前状态（2026-10-02 晚）

| 项 | 值 |
|---|---|
| **主库** | **`中医·结构优先`** = `8bf27782-5f61-49c8-8d9a-af2b89158239`（由「经络腧穴学·结构优先」改名，**库 id 未变**） |
| 主库体量 | 文档 461（含 8 个目录条目）；**453 篇正文 / 4006 块 / 133.9 万字符** |
| 检索启用范围 | 开关值 `enabled=True, enabledBaseIds=[8bf27782]`（**但见第六节：此开关检索时不生效**） |
| 库级配置 | 仅 `siblingChunks=0`，其余继承全局（未动） |
| 全局配置（未动） | 嵌入 `Qwen/Qwen3-Embedding-4B`(2560d)、重排 `Qwen/Qwen3-Reranker-8B`、`chunkSize 800`、`chunkOverlap 100`、`smartChunk=true`、`topK=4` |
| 原 EPUB | 10 个，位于 `C:\Users\xy192\DSH云端备份\4-原始底本\epubtest\00-原始EPUB\` —— **全部未动** |
| 旧库 | 「中医」`c16b54af-…`（47 文档）、「中医新」`8c95794f-…`（6535 块）—— 保留、停用、未改 |
| 临时验收库 | `_tmp-素问语译-结构C`（`eff1d602`，83 篇）、`_tmp-针灸大成-结构C`（`5cde9779`，233 篇）、`_tmp-脈經校注-结构C`（`488695c9`，105 篇）—— 保留备查 |
| 库总数 | **13 个**（含 6 个可清理的 `_tmp-*`：五章 3 个、第三章策略 2 个、空壳 `_tmp-针灸大成-结构C` `73de11d4`、中间态 `_tmp-脈經校注-结构C` `acbabe9b`） |

**主库目录结构（4 个类 + 4 个书目录）**

| 目录 | 篇数 | 块数 | 字符 | 处理记录 |
|---|---|---|---|---|
| 教材讲义类 / 经络腧穴学 | 29 | 676 | 297,000 | 无（第 1 本原型，验收在 `新库抽查单-经络腧穴学-20261002.md`） |
| 医经语译类 / 黄帝内经素问语译 | 84 | 963 | 386,200 | 有（《素问语译》验收报告 + 修订记录） |
| 针灸专著类 / 针灸大成 | 234 | 1,607 | 378,648 | 有（含书目信息、卷次决定、误报说明） |
| 医经校注类 / 脈經校注 | 106 | 760 | 276,841 | 有 |

> 目录 id 全部记在 `工作区\_tmp\main_reorg.json`。

---

## 四、已完成 4 本（＝旧库 47 本里的 4 本）

| 书 | 书族 | 篇/片 | 核验 |
|---|---|---|---|
| 经络腧穴学 | 教材讲义类（首本原型） | 29 篇 / 676 块 | 逐篇块数一致、逐字无损、676/676 出处可回解 |
| 黄帝内经素问语译 | 医经语译类（首本） | 83 篇正文 / 931 片 | 84/84 篇块数一致；12 字滑窗 0 缺口；931/931 出处；558/558 图片；【注解】771、【语译】864 |
| 针灸大成 | 针灸专著类（首本） | 233 篇正文 / 1573 片 | 232/233 篇块数一致（唯一差异＝书目篇多 1 块=插件注入的标题上下文）；0 缺口；1859/1859 出处；考正穴法穴条 359/359 逐经吻合 |
| 脈經校注 | 医经校注类（首本） | 105 篇正文 / 743 片 | 105/105 篇块数一致；0 缺口；2557/2557 出处；图片 155/155 |

**检索实测（显式限定 `baseId=主库`，TopK=4，均单块精确命中）**：中府 定位（经络腧穴学，339 字符完整条目）、上古天真论 女子七岁（451 字符，原文+注解+语译同块）、考正穴法 中府（针灸大成，192 字符）、标幽赋 注解（195 字符）、浮脈 舉之有餘（脈經校注，371 字符；旧 md 版是 1294 字一大块）、寸口脈浮 中風 發熱（341 字符）。

---

## 五、按同一套路做下一本书：5 步

1. **查边界**：读 `_tmp\five\boundaries_fixed.json`（38 本合集内图书的页码表，格式 `start/end/cip`；`start` = CIP 页 −2，含本书封面/内封）。
2. **探体例**：仿 `_tmp\gen_mj.py` 头部写一个 probe，打印「每页首元素 + 元素类分布 + 标题层级计数」，据此定**文档层级**（卷/篇/门）与**单元规则**（一条＝什么）。遇到新体例先给用户确认再铺开。
3. **写生成器**：复制同族模板改三处——`EPUB` 路径、`P0,P1` 页范围、`BOOK` 名，再改单元组装与 `BIB_PAGES`（书目信息页）。
4. **跑核验**：`verify_xx.py` 导入临时库 `_tmp-<书名>-结构C`，看四项：逐篇块数一致、逐篇无损、**12 字滑窗 0 缺口**、出处全可回解。
5. **入库 + 留档**：用 `_tmp\import_book_main.py`（改 CONF 段）导入主库对应书目录，再写「处理记录」与「抽查单」，并把处理记录也作为文档放进该书目录。

**三族模板现成可用**

| 书族 | 生成器 | 单元规则 |
|---|---|---|
| 医经语译类 | `_tmp\gen_suwen.py` | 一条 = 原文段 +【注解】+注文 +【语译】+译文；篇 = 文档 |
| 针灸专著类 | `_tmp\gen_jd.py` | 四模式自适应（歌赋注解／短行打包／长段／考正穴法穴条）；一穴一条；相邻短条 ≤400 字打包 |
| 医经校注类 | `_tmp\gen_mj.py` | 一条 = 原文段 + **紧随其后**的注释段（注释段以〔N〕开头，遇新原文/标题收束）；篇标题+提要+按语同片；相邻短条打包 |

**剩余 42 本**：医经校注类剩 4 本（鍼灸甲乙經校注上下、難經校注、傷寒論校注、中藏經校注）、医经语译类 2 本（灵枢经、伤寒论语译）、针灸专著类 2 本（针灸甲乙经、单玉堂针灸配穴通俗讲话）、教材讲义类 5 本（刺法灸法学、中药学 OCR、针灸治疗学、方剂学讲稿、中药学讲稿等）、方书类 6 本（千金翼方、备急千金要方、局方、证治准绳六部）、其余「较粗」的书 —— **这批要连图片、脚注、字形图一起从 EPUB 重做**。
书单与分类：`_tmp\five\worklist.json`、`md_classified.json`。

---

## 六、⚠ 必须知道的两个环境事实

### 1. 检索开关的「启用范围」实际不生效
`GET /knowledge/knowledge-toggle` 的 `enabledBaseIds` **只被存取、供面板显示**；检索链路 `search()` / `searchSingle()` 只认请求里的 `baseId` / `baseIds`，**从不读 `getEnabledBaseIds()`**。
- 后果：不带 `baseId` 检索时，旧「中医」库 + 6 个 `_tmp-*` 库都会参与竞争（实测问「浮脈 舉之有餘 按之不足」，前 3 名全是旧库，新库排第 4）。
- 另实测：`docIds` 也不是硬过滤，**只有 `baseId` / `baseIds` 是硬过滤**。
- 本会话对 `knowledge_search` 工具调用时也没能限定到主库（它的默认范围是全部库）。
- **三个候选处置（未执行，等用户定）**：① 调用时显式带 `baseId`；② 改插件让检索回落到 `getEnabledBaseIds()`（属 DSH 本体改动，需批准 + 重启）；③ 删掉 6 个废弃 `_tmp-*` 库。
- **本会话没有动插件本体，也没有删任何库。**

### 2. 发布直链的方法（用户要链接时用）
- 凭据（**只进内存、不打印、不写文件、不进回复**）：`C:\Users\xy192\DeepSeekHarness\.secrets\cloudflare-pages.conf`（含 `CLOUDFLARE_ACCOUNT_ID`、`CF_PAGES_PROJECT`）＋ `…\.secrets\cloudflare-pages.token`
- 命令：`npx --yes wrangler@3 pages deploy <舞台目录> --project-name=kb-xy919 --commit-dirty=true`
- 舞台目录 `工作区\_tmp\deploy-kb\`：**必须有 `index.html`**；`_headers` **必须 LF 行尾**（CRLF 会被静默忽略）；每次部署**别忘带旧文件**，否则旧直链 404
- 正式域 `https://kb-xy919.pages.dev/`；最新首页 `https://kb-xy919.pages.dev/`
- **用户偏好：要链接时只发文件下载直链（`/dl/*.md`），不要顺手做 HTML 阅读页、入口页、zip 等变体。**
- 台账写在 `工作区\静态发布说明.md`。

---

## 七、待办（按优先级）

1. **等外部复核《脈經校注》抽查单 34 条** → `工作区\抽查单-脈經校注-20261002.md`（已发布直链 `https://kb-xy919.pages.dev/dl/kb-spotcheck-mj-20261002.md`）
2. **定第六节第 1 条的处置**（检索范围/临时库清理）
3. 按第五节 5 步流程**继续批处理剩余 42 本**（每族首本做完即交付复核）
4. **字形图提字**单独立项：全 10 个 EPUB 共 **13588 张字形图 / 约 1.36 万字**，旧 md 里全是 `〔缺字〕`；建议先做 1 本验证准确率，机器输出标「机器识别/待核」，不直接当权威正文
5. 历史遗留：凭据轮换（`GET /knowledge/config` 与 `/knowledge/bases` 明文返回 key 且本机接口无鉴权）、`parseEpub` 不读 spine 的上游 issue、清理 6 个废弃 `_tmp-*` 库

---

## 八、本轮成果文件（工作区根目录）

| 文件 | 说明 |
|---|---|
| `知识库结构优先-本轮总结-20261002.md` | 本轮进度与成果总结（可转外部评审） |
| `处理记录-针灸大成-20261002.md` | 含书目信息页处理、卷次决定表、连续起首不拆分 |
| `处理记录-脈經校注-20261002.md` | 医经校注类模板 + 核验数据 |
| `验收报告-素问语译-20261002.md` | 含第五节修订记录（书目信息篇、12 字滑窗判据） |
| `抽查单-脈經校注-20261002.md` | 34 条待复核 |
| `抽查单-素问语译-20261002.md` / `抽查单-针灸大成-20261002.md` | 已通过复核 |
| `静态发布说明.md` | 直链台账与部署方法 |

**脚本（`工作区\_tmp\`，权威清单）**
- 生成：`gen_jd.py`、`gen_suwen.py`、`gen_mj.py`（三族模板）
- 核验：`verify_jd.py`、`verify_suwen.py`、`verify_mj.py`
- 抽查单：`accept_jd.py`、`accept_mj.py`、`make_spotcheck2.py`
- 主库操作：`main_reorg.py`（改名+建目录+迁入）、`import_book_main.py`（按目录导书）、`import_jd_main.py`、`refresh_records.py`
- 边界/书单：`fix_boundaries.py`、`align_books3.py`、`_tmp\five\boundaries_fixed.json`、`worklist.json`
- 发布：`stage_deploy7.py`（最新，保留全部旧直链）

*本文件不含任何 API key 或凭据。*