# 参考书作品面数据入库方案

- 版本：v6（2026-07-14。v1→v3：两轮独立评审修正事实与幂等/隔离/回滚；v4：第三轮评审补存储落点与真实额度时间线；v5：创始人五条反馈后换核——废分层、全实体统一生长、正文窗直抽+缓存友好；**v6：第四轮复审后修三处硬伤——实体索引改窗内机械预扫（防重蹈章级实体膨胀坑）、判重与更新预算上修并设总额闸、补出场留档表防跨窗漏立卡**）
- 目标读者：创始人
- 状态：**待你过目，批准前不动工**
- 源起：你 2026-07-14 指令「这几本书本身也是被导入的作品，对应的数据也都需要入库」+ 同日五条反馈与核心问题「已存在该卡片应该怎么办」

## 你需要做什么

读完本方案（约 6 分钟），重点看「五、实体卡生命周期」（直答你的核心问题）与「七、你已拍板的记录+1 个新决策点」。

## 一、这件事是什么

5 本参考书拆出来的东西分两类：

- **写作手法卡**（脱敏的范式，归公共库）——已在正式候选层，216 张等你确认，不在本方案范围；
- **作品面数据**（每本书自己的角色、地点、物品、势力、力量体系、事件、人物关系、细纲、大纲）——目前只存在拆书过程的中间表里，还不是正式数据。

本方案解决后一半：把每本书当成一部正式导入的作品，作品面数据按正式作品的规矩入库、挂上各自的作品知识库。

## 二、现状盘点（以下全部查库核实过）

| 数据 | 现在在哪 | 差距 |
|---|---|---|
| 逐章细纲 | 拆书中间表，一章一行 | 章节正式表有「细纲快照」列，目前装的是导入期的卷号定位信息（全部 11777 章非空）——回填细纲须**併写新键**，不能覆盖既有内容 |
| 窗级大纲 | 拆书中间表，约每 30 章一行 | 全书没有一张汇总大纲 |
| 实体（角色/地点/物品/势力/力量体系/事件） | 中间表里的「首次出场登记」：只有名字 + 一句话 | 离正式卡差得远——正式角色卡有 11 个字段（性格底色/欲望与恐惧/说话方式……） |
| 人物关系 | 没抽过 | 空白（字段合同已启用：甲方/乙方/关系类型/演变轨迹等 8 字段） |
| 知识库骨架 | 已有 2 个库：「参考书私有库」（挂 10 份原文档案）、「公共范式库」（挂范式卡） | 每本书自己的作品知识库没建；正式实体表、关系表、绑定表都是 0 行 |

规模感（管线在跑、数字持续增长，以下为 2026-07-14 01:09 快照；口径=拆书中间表实体清单按名称去重、六类合计）：每书已拆 358–413 章，累计去重实体名 552–1160——深空之影一书已实测破千。绝大多数是单章路人——按元数据规范既有的立卡门槛（**有跨章戏份才立卡**）自然挡住，不需要人为分层（v5 已废除 v4 的「前 15 名」分层设计，见 §5.2）。

## 三、目标与边界

**做：**

1. 每本书建一个自己的作品知识库（库行 + 与作品的绑定）；
2. 所有跨章实体一实体一卡，从正文窗滚动抽取、随出场生长（按字段合同），进正式候选层等确认；
3. 人物关系一并抽取，进候选层；
4. 逐章细纲併写进章节正式表的细纲快照列（新增细纲键，保留既有卷号键），解析待审列置「待确认」；
5. 全书大纲做成一书一张大纲卡，进候选层。

**不做：**

- 不动任何已确认的正式数据（正式实体表现在 0 行，不存在覆盖风险）；
- 不覆盖快照列里既有的导入期信息（只加键，不清列）；
- 不自行确认——所有卡停在候选层，等确认门（任务清单 B5，你的指令）；
- 未拆的 3 本书（希泊尼战纪/机武风暴/机破星河）不在本次范围。

## 四、数据落到哪（核心设计）

```mermaid
flowchart LR
    A[原文章节表] -->|"正文窗直抽（AI，缓存友好）"| G["实体观察：新实体 / 已有实体的新信息 / 出场登记"]
    G -->|"检索判重：名字精确 → 嵌入近邻 → AI 终判"| C["候选层 muse_knowledge_draft<br/>一实体一卡，随出场滚动生长<br/>（独立来源标记，与范式卡隔离判重）"]
    B["拆书中间表<br/>细纲，保留作证据链"] -->|"机械併写，零 AI 成本"| D["章表细纲快照列<br/>（加细纲键，标待确认）"]
    C -->|"确认门（你拍板，按书批量）"| E["正式层<br/>muse_knowledge_entity / relation<br/>挂各书作品库"]
    F["一书一库骨架<br/>（库行 + 挂到作品的绑定行）"] -. 归属 .-> E
```

| 数据 | 正式落点 | 关键设计 |
|---|---|---|
| 每本书的知识库 | 知识库表（`muse_knowledge_base`）一书一行 + 绑定表（`muse_knowledge_binding`）把库挂到作品名下 | 与正式产品「一部作品一个私有知识库」形态一致；实体表本身就有库、作品双归属列 |
| 实体卡（六类） | 候选表（`muse_knowledge_draft`）候选行（挂书）；确认后升正式实体表（`muse_knowledge_entity`），打「本书私有」标记，归属该书作品库 | **一实体一张卡**（正式表唯一键=作品×型×归一名，天然保证），字段随出场滚动生长，不再分「全卡/轻卡」两个物种；候选行用**独立来源标记**（区别于范式卡的拆书标记），判重、检索、确认互不掺和 |
| 人物关系卡 | 同上；确认后升 `muse_knowledge_relation` | 草稿期甲方/乙方**记对方实体卡的草稿编号**（名字只作展示）——确认升格时机械换算成正式编号，改名/并名不悬空；确认顺序天然先实体、后关系 |
| 逐章细纲 | `muse_content_chapter.outline_snapshot` **併写**新键 + 原生解析待审列置待确认 | 主仓建表时就为「导入作品的逆向解析」留了这两列；既有卷号键原样保留，回滚=只删自己写的键 |
| 全书大纲 | 一书一张「大纲」型卡入候选层（主线一句话 + 分卷粗纲两字段，其余四字段属连载创作期、完结参考书不适用，留空并在卡内注明） | 作品表没有大纲列，实验库也没有规划表——大纲卡与实体卡同走确认门（按书批量，不单独「就地确认」）；实验台内的消费方=**检索验证与范式对照**（参考书没有装配文件，不进创作上下文组装）；回填主仓时归位到规划模块（列入对齐清单） |
| 窗级大纲、首次出场登记 | 留在拆书中间表，不动 | 证据链（每张卡可回溯来历），不是正式数据 |

## 五、实体卡生命周期（直答你的核心问题：已存在该卡片怎么办）

先说结论：**一个实体不管出现多少章，库里永远只有一张卡**；抽到已存在的实体不是「再新增一张」，而是**把新信息合并进这张卡**——合并方式按字段性质分三类。主仓建表时已为此留好机制，全程零新正式表。

### 5.1 一个实体在表里长什么样

正式实体表的唯一键=作品×型×归一名×可见范围，数据库层面锁死「一实体一行」——前提是可见范围取值恒定，故立规矩：**作品面卡的可见范围恒为「本书私有」**，不得出现第二种取值绕开唯一性。卡体是一个 JSON，字段按该型的元数据合同定义，按演进方式分三类：

| 字段类 | 例子 | 多章反复出现时怎么变 |
|---|---|---|
| 底色字段 | 性格底色、说话方式、欲望与恐惧 | **覆写式**：初见粗填，后文显露更准的就改写，改前旧值留审计 |
| 演进字段 | 成长弧线、关系演变轨迹 | **追加式**：一条条往后加，每条自带「依据窗号」，永不改旧条 |
| 当前态字段 | 当前境界、当前阵营、生死状态 | **覆写式**：永远保持「读到即最新」，被换下的旧状态沉淀进演进字段成历史 |

另有三样随卡维护：出场章清单（机械追加）、修订号（每次合并 +1，主仓表原生列）、嵌入向量（卡体变了就重算，供语义检索）。

**这个形态是为「读路径」设计的**：生成正文时拿到卡即拿到实体的最新累积态，不需要回放全书历史——这就是「高质量上下文」的来源（见 5.5）。

### 5.2 抽取全流程（一个窗）

你说的理解基本就是设计本身，补全后的完整闭环：

```mermaid
flowchart TD
    Z["⓪ 机械预扫（零 AI）：拿全库实体名+别名在本窗正文里精确扫描<br/>→ 得「本窗在场的已知实体」子集（通常几十个）"] --> A
    A["① 组装上下文：正文窗 3–5 万字（固定前缀，吃缓存）<br/>+ 仅「窗内命中」的实体索引（名字+别名+一句话）+ 按型抽取合同"] --> B["② 实体观察（AI，每窗 1 次）：<br/>新名字（顺带按合同产初卡）/ 已知实体的新信息点 / 纯出场登记"]
    B --> C{"③ 判重（对每个「新名字」）：<br/>查出场留档与别名表 → 同书同型语义近邻 → 可疑者 AI 终判"}
    C -->|"确属新+已跨章"| D["新增候选卡（初卡入库+算嵌入）"]
    C -->|"其实是已有实体的别名"| E["初卡整卡转作观察材料，交该卡下一次更新裁决合并；<br/>该名字记入别名表"]
    C -->|"单章龙套"| I["只记出场留档表，不立卡；<br/>后窗再现且合计跨章 → 用留档补立卡"]
    D --> F["④ 卡更新（AI，按需 1–3 次）：只对「有新信息」的卡，<br/>每批 ≤6 张：读全卡 → 只回变更字段 → 按 5.1 三类规则合并"]
    E --> F
    F --> G["⑤ 关系增量（AI，每窗 1 次）：<br/>核心角色两两关系变化 → 滚进关系卡"]
    G --> H["⑥ 机械收尾（零 AI）：纯出场者追加出场章清单；<br/>窗状态记完成、卡水位推进、变更卡重算嵌入"]
```

**成本靠「更新触发」控，不靠「谁配有卡」控**——这是对你质疑「为什么只保留前 15」的正面回答，v4 的分层门槛**作废**：

- 路人出场 1 次：初卡在观察调用里顺带产出，不占任何单独调用；
- 配角出场 30 章但只有 5 章有实质新信息：25 章只做机械出场登记（零 AI），5 章各触发一次合并；
- 主角几乎每窗都有新信息：每窗都在更新批里——卡自然长得最厚。

**卡的丰富度是信息量的自然结果，不是预划的等级**。「轻卡」概念随之消解：出场少的实体=字段还没长起来的卡，同一张卡、同一套机制，后文戏份重了自然变厚——不存在「到了后面只能获取 15 个人」，检索面对的是全部实体。立卡门槛沿用元数据规范的既有约定：**有跨章戏份才立卡**，单章龙套不立卡但记出场留档表（见 §五B 第 5 张工作表）——后窗再现、两窗合计跨章时用留档补立卡，防「窗内视角判不准跨章」漏卡，也防几千个一次性路人污染检索。

两个防膨胀设计（第四轮评审补强）：

- **索引侧**：观察调用**不带全库实体索引**——书末期全库索引会涨到 4–5 万 token，重蹈章级解析「前文实体膨胀」的原坑（你当时亲自纠偏过）。改为零成本机械预扫：拿全库名字+别名在本窗正文精确扫描，只把「本窗在场」的几十个实体的索引带进调用，token 从数万压到数千，且不随书的进度膨胀；
- **输出侧**：观察输出一次涵盖新名字+新信息+出场登记，为防「长清单丢字段」老坑（更新调用已有每批 ≤6 张的防护，观察调用同样要设）：一窗新名字超过 12 个或章数超过 15，窗内对半分段补抽。

### 5.3 「已存在怎么办」的两阶段答案（主仓机制原生支持）

| 阶段 | 卡的状态 | 抽到已存在实体时 | 主仓机制 |
|---|---|---|---|
| **拆书回放期**（本方案） | 候选卡，未确认 | **就地合并**进候选卡（按 5.1 三类规则），修订号+1，最后按书批量过一次确认门 | 候选表一行一卡，卡体直接累积 |
| **创作期**（muse 正式产品，将来） | 已确认的正式卡 | **不动正式卡**，产一条「变更提案」：指向该卡、只装变更字段、留下提案时刻的正式卡快照——确认门批准后才合并、修订号+1 | 候选表原生三列：指向哪张卡、提议改什么、当时卡长什么样——主仓建表时就按此机制设计，本次查表核实 |

两阶段共用同一套「观察→判重→合并」流程骨架，只差合并落点：未确认的卡直接长，已确认的卡走提案。**拆参考书=创作期机制的高强度回放验证**——创作期没有「全书统计」的上帝视角（书还没写完），只能滚动生长；v4「先全书统计再分层」验证不了 muse 的真实机制，这是废除它的第二个理由。

**同人两卡的合并**（改名/化名/夺舍导致先立了两张卡）：不自动合并（字段冲突需要裁决），标人工待办随样张呈报，你裁决后低修订卡并入高修订卡、并入方从其立卡窗重滚补齐。

### 5.4 抽的是哪些型（对齐元数据 23 型）

23 型按两轴组织（领域×粒度）。本方案覆盖**作品面 8 型**：

- 实体域六型：**角色 / 地点 / 物品 / 势力 / 力量体系 / 事件**——一实体一卡，走 5.2 流程；
- 关系域一型：**人物关系**——甲乙双方记卡编号（名字只作展示），随窗滚动；
- 作品域一型：**大纲**——一书一张，全书窗走完后汇总产出。

范式五型（技法/打斗/情感/场景范式/套路）是公共面，已在既有出卡管线跑，不在本方案内；其余型（章、场景、文风、叙事状态等）属创作期实例，参考书不产。

### 5.5 生成时怎么用（读路径——入库设计的最终目的）

写第 N 章正文前，上下文组装这样取数：

1. **定位在场者**：本章大纲/场景名字精确匹配 + 大纲文本语义检索（限本作品库）双路召回；
2. **取当前态**：在场实体卡直接给——5.1 的形态保证拿到即最新，无需回放计算；
3. **控制篇幅**：演进字段只取最近几条 + 与本章大纲语义相关条；字段按元数据合同的「可进 AI 上下文」控制项裁剪；
4. **关系补充**：在场者两两关系卡（只取有卡的对）；
5. 生成完成后，新正文回到 5.2 流程抽取——**写与读闭环**，卡随创作持续生长。

拆书场景没有第 5 步的循环（书已完结），但 1–4 正是「检索验证」（任务清单 B3）要验的查询模式——本方案入库的卡就是 B3 的靶子。

## 五B、管线运行设计（窗、缓存、敏感、幂等）

- **窗的定义**：正文窗 3–5 万字（约 10–15 章，边界对齐章边界），与范式出卡的 30 章细纲窗是**两条工序两种窗**，互不干扰。抽取直接读正文而非细纲——细纲是 3–5% 的有损压缩，会丢对话风格与细节；正文直抽也与创作期机制同构（创作期从新写正文抽取）。
- **缓存机制（你拍板第 4 点的落实）**：同一窗的全部调用（观察→卡更新分批→关系）共用「正文窗+固定规则」前缀、连续发送，最大化前缀缓存命中；每批跑批呈报实测缓存命中数。注意：主力模型此前实测**不吃**前缀缓存（恒定命中 128，属其内部模板），按缓存友好排布是无悔设计——若首窗试跑确认仍不吃，再给你两个选项（换吃缓存的模型 / 接受全价按细纲窗降级），用实测数据说话。
- **敏感拦截**：复用章级已验证的模型降级链（主力被拦→两级备选）；一窗全链被拦=该窗记失败、该书暂停（窗间有依赖，跳窗丢演变），人工处置后从失败窗续跑。
- **断点续跑与幂等**：同一窗重跑先撤该窗写入再重写——追加字段按窗号删条目，覆写字段按审计还原旧值（出卡管线「重跑自噬」老坑，必须防住）；**初卡的全部首窗字段以「旧值=空」入覆写审计**，保证错认别名拆回时初卡原始态可还原。存储落点 5 张实验层工作表（沿用为幂等专门建表的先例，不动主仓正式表）：

| 表 | 作用 | 关键列 | 撤销怎么用它 |
|---|---|---|---|
| 升格-别名表 | 判重审计：谁被认定为谁的别名 | 书、正名、别名、依据窗、机械/AI 终判、时间 | 错认=按行拆回，对应卡从该窗重滚 |
| 升格-出场留档表 | 未立卡实体的跨窗出场记忆 | 书、窗号、章号、名字、一句话观察 | 判重先查此表；两窗合计跨章→用留档补立卡；撤销=按窗删行 |
| 升格-窗状态表 | 一书一窗一行处理状态 | 书、窗号、起止章、状态（待跑/完成/失败）、错误信息 | 断点续跑=跳过「完成」，从「失败」续 |
| 升格-卡水位表 | 每张候选卡滚到第几窗 | 卡号、书、已滚至窗号 | 重跑判断起点；错认卡归零 |
| 升格-覆写审计表 | 覆写类字段的旧值流水 | 卡号、窗号、字段名、旧值、新值、时间 | 同窗重跑=按（卡号+窗号）还原再重写 |

- **守卫照旧**：卡按字段合同校验、越合同字段裁剪留审计、候选卡全量嵌入；出卡管线踩过的坑（占位符抄写、空返回偷懒、长清单丢字段）的机械检测同样套用。
- **细纲回填与大纲卡**：细纲从中间表机械併写进章表快照列（分钟级），同章「解析待审」列置**待确认**、你按书放行后置**已确认**（确认脚本执行留日志）；全书大纲由 AI 读全部窗级大纲汇总，一书一次。

## 六、确认门、回滚与隔离

- **确认门（按书批量，不逐张翻牌）**：实体卡、关系卡、大纲卡、细纲同一口径——你看该书样张、抽验通过后整书一次放行；想逐张细看随时可以，但不作为默认流程（7345 章细纲、上千张卡逐张翻不现实）；
- **回滚**：候选行软删即可；章表快照只删自己写的细纲键（卷号等既有键不动）；库骨架行软删；错认别名按审计拆回、该卡从错认窗重滚；
- **判重隔离**：现行范式卡判重池只认「拆书来源」标记，但无书间隔离。作品面卡用独立来源标记入池，且近邻判重**限定同书同型**——绝不与范式卡互判，也不跨书互判（机动风暴与机武风暴同作者同题材，跨书误并风险真实存在）；
- **检索隔离**：后续检索验证按库/按作品过滤；
- **顺手卫生**：嵌入表现有 783 行中 567 行挂在已软删草稿上（历次重出卡的遗留）。现行判重查询已正确排除软删行，**不构成正确性风险**，纯属存储垃圾，列入清理项。

## 七、你已拍板的记录 + 现在只剩 1 个决定

你 2026-07-14 五条反馈的落实情况：

1. **「为什么只保留前 15」——质疑成立，分层门槛作废**：改为全实体统一生长机制（§5.2），实体天然具备查询/更新/新增闭环，卡的丰富度随出场信息量自然分化，检索面对全部实体。
2. **「每类卡对应哪些元数据、轻卡的意义」**：作品面对应 23 型中的 8 型（§5.4）；「轻卡」不是任何一个型、属体系外发明，已消解——它只是字段还没长起来的同型卡。
3. **「几万本书几万个库？底层单库+框架封装是否可行」——现状正是你说的形态**：一书一库是**逻辑库**（库表一行=一个库），物理上所有书共用同一套表；实体表自带作品+库双归属列和组合索引（查表核实），唯一键=作品×型×归一名。几万本书=库表几万行，物理零扩张；检索封装层强制带作品号/库号过滤（安全约束在查询层强制，不靠调用方自觉）。
4. **「同意；复用窗口文本缓存，一窗抽好几次」**：已落实为管线核心（§五B）——正文窗固定前缀、同窗多调用连续发；首窗试跑呈报实测缓存命中。
5. **「放进一个额度池；安排抽取顺序+缓存优化」**：顺序见 §八；缓存见 §五B。

**你已批准开工（「认可」，2026-07-14）**。开工序：先建 5 张工作表（机械，零额度）→ 首书机动风暴（已全章完成、篇幅最短）试跑约 10 个窗出样张 → **另加深空之影末段 3 个窗做压力用例**（它实体最多，专验书末期索引与判重不膨胀——首书最轻，只看它会把坑掩盖到放量期）→ 你过目样张后定放量节奏。

## 八、成本、耗时与额度池内的抽取顺序

**额度池统一后的排序原则**：依赖优先（细纲是窗大纲/出卡的原料）+ 同窗调用连续发（吃缓存）+ 尽早给你看到样张（先短书）。

| 顺 | 工序 | 剩余量 | 估算请求数 | 说明 |
|---|---|---|---|---|
| 1 | 章级解析收尾 | 约 1845 章（星环 528/机战 1299/超神 17/深空 1） | 约 2100 次 | 批 6 起消化，细纲是后续一切的原料 |
| 2 | 窗大纲+范式出卡（细纲窗） | 约 236 窗 | 约 800–1500 次 | 机动/深空已可开跑，不必等其他书章级收尾 |
| 3 | **作品面抽取（本方案，正文窗）** | 约 610 窗（7345 章 ÷ 12 章/窗） | **约 3000–4800 次**（观察 610 + 更新约 900–1800 + 关系 610 + 判重终判约 800–1800 + 分段补抽/大纲余量） | 首书机动风暴（56 窗）+深空末段压测先出样张；同窗调用连续发吃缓存 |
| — | 合计从现在起 | — | **约 5900–8400 次** | 每批呈报列明「本批花在哪几道工序」 |

- 判重终判与更新批次是估算里最不准的两项（第四轮评审判定原估低一个量级已上修：5 书累计实体名过万，别名同质性高；观察调用没有全卡视野、会过报新信息）——故设**总额上限闸：作品面抽取全程 5000 次封顶**，试跑样张出实测单价后重新校准，超闸即停、呈报你再定；
- 按你的发放节奏折算：每批 2000 次 → 约 3–5 批、**约 2 天**全链收口；每批 500 次 → 约 12–17 批、约 3–4 天；
- **token 账（对你透明）**：正文窗直抽每次调用输入约 3–5 万 token（正文占大头；实体索引经窗内机械预扫已压到数千且不随书进度膨胀），全程输入约 1 亿 token，与章级解析全程同量级、约为细纲滚动方案的 4 倍——换来一手细节质量 + 与创作期机制同构；若前缀缓存实测生效，同窗第 2 次起正文近乎免费，有效输入可压到约一半以下。首窗试跑给实测数，不生效再给你降级选项；
- 建库骨架、细纲併写、出场登记、窗内预扫、留档查询：全机械，零额度。

## 九、交付物与验证（都是仓库里的人读文件）

- 每书一份《作品面数据样张》markdown：实体对账表（立卡数/单章路人挡下数/判重合并数/人工待办数）、分型列卡全字段、别名与出场章、关系表、大纲卡全文、**实测缓存命中数据**；试跑样张另附**深空末段压力数据**（书末期单窗输入 token、判重终判次数——验证防膨胀设计成立）；
- 抽验口径：每书随机 5 张卡**回原文核对事实忠实度**（人名事件对不对得上原文）——作品面卡验的是「像不像这本书」，与范式卡评手法质量的三角色审核是两码事；
- 章表快照列回填覆盖率（应为 100%，缺口列明章号）。

## 十、批准后的收尾动作（不用你操心，列出备查）

- 拆书技能文档同步订正：参考书「脚手架留档、不需逐章确认」的旧表述，与本方案「细纲併写+按书批量确认」对齐；
- 续跑序总账（README §九）补作品面升格一步；
- 原文档案表「机战无限」「超神机械师」各一条重复登记行，核实后软删；
- 嵌入表挂已软删草稿的 567 行遗留，清理。