muse-agent-example/docs/2026-07-14-参考书作品面数据入库方案.md

218 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 参考书作品面数据入库方案
- 版本v62026-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 快照;口径=拆书中间表实体清单按名称去重、六类合计):每书已拆 358413 章,累计去重实体名 5521160——深空之影一书已实测破千。绝大多数是单章路人——按元数据规范既有的立卡门槛**有跨章戏份才立卡**自然挡住不需要人为分层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["① 组装上下文:正文窗 35 万字(固定前缀,吃缓存)<br/>+ 仅「窗内命中」的实体索引(名字+别名+一句话)+ 按型抽取合同"] --> B["② 实体观察AI每窗 1 次):<br/>新名字(顺带按合同产初卡)/ 已知实体的新信息点 / 纯出场登记"]
B --> C{"③ 判重(对每个「新名字」):<br/>查出场留档与别名表 → 同书同型语义近邻 → 可疑者 AI 终判"}
C -->|"确属新+已跨章"| D["新增候选卡(初卡入库+算嵌入)"]
C -->|"其实是已有实体的别名"| E["初卡整卡转作观察材料,交该卡下一次更新裁决合并;<br/>该名字记入别名表"]
C -->|"单章龙套"| I["只记出场留档表,不立卡;<br/>后窗再现且合计跨章 → 用留档补立卡"]
D --> F["④ 卡更新AI按需 13 次):只对「有新信息」的卡,<br/>每批 ≤6 张:读全卡 → 只回变更字段 → 按 5.1 三类规则合并"]
E --> F
F --> G["⑤ 关系增量AI每窗 1 次):<br/>核心角色两两关系变化 → 滚进关系卡"]
G --> H["⑥ 机械收尾(零 AI纯出场者追加出场章清单<br/>窗状态记完成、卡水位推进、变更卡重算嵌入"]
```
**成本靠「更新触发」控,不靠「谁配有卡」控**——这是对你质疑「为什么只保留前 15」的正面回答v4 的分层门槛**作废**
- 路人出场 1 次:初卡在观察调用里顺带产出,不占任何单独调用;
- 配角出场 30 章但只有 5 章有实质新信息25 章只做机械出场登记(零 AI5 章各触发一次合并;
- 主角几乎每窗都有新信息:每窗都在更新批里——卡自然长得最厚。
**卡的丰富度是信息量的自然结果,不是预划的等级**。「轻卡」概念随之消解:出场少的实体=字段还没长起来的卡,同一张卡、同一套机制,后文戏份重了自然变厚——不存在「到了后面只能获取 15 个人」,检索面对的是全部实体。立卡门槛沿用元数据规范的既有约定:**有跨章戏份才立卡**,单章龙套不立卡但记出场留档表(见 §五B 第 5 张工作表)——后窗再现、两窗合计跨章时用留档补立卡,防「窗内视角判不准跨章」漏卡,也防几千个一次性路人污染检索。
两个防膨胀设计(第四轮评审补强):
- **索引侧**:观察调用**不带全库实体索引**——书末期全库索引会涨到 45 万 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 步的循环(书已完结),但 14 正是「检索验证」(任务清单 B3要验的查询模式——本方案入库的卡就是 B3 的靶子。
## 五B、管线运行设计窗、缓存、敏感、幂等
- **窗的定义**:正文窗 35 万字(约 1015 章,边界对齐章边界),与范式出卡的 30 章细纲窗是**两条工序两种窗**,互不干扰。抽取直接读正文而非细纲——细纲是 35% 的有损压缩,会丢对话风格与细节;正文直抽也与创作期机制同构(创作期从新写正文抽取)。
- **缓存机制(你拍板第 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 窗 | 约 8001500 次 | 机动/深空已可开跑,不必等其他书章级收尾 |
| 3 | **作品面抽取(本方案,正文窗)** | 约 610 窗7345 章 ÷ 12 章/窗) | **约 30004800 次**(观察 610 + 更新约 9001800 + 关系 610 + 判重终判约 8001800 + 分段补抽/大纲余量) | 首书机动风暴56 窗)+深空末段压测先出样张;同窗调用连续发吃缓存 |
| — | 合计从现在起 | — | **约 59008400 次** | 每批呈报列明「本批花在哪几道工序」 |
- 判重终判与更新批次是估算里最不准的两项第四轮评审判定原估低一个量级已上修5 书累计实体名过万,别名同质性高;观察调用没有全卡视野、会过报新信息)——故设**总额上限闸:作品面抽取全程 5000 次封顶**,试跑样张出实测单价后重新校准,超闸即停、呈报你再定;
- 按你的发放节奏折算:每批 2000 次 → 约 35 批、**约 2 天**全链收口;每批 500 次 → 约 1217 批、约 34 天;
- **token 账(对你透明)**:正文窗直抽每次调用输入约 35 万 token正文占大头实体索引经窗内机械预扫已压到数千且不随书进度膨胀全程输入约 1 亿 token与章级解析全程同量级、约为细纲滚动方案的 4 倍——换来一手细节质量 + 与创作期机制同构;若前缀缓存实测生效,同窗第 2 次起正文近乎免费,有效输入可压到约一半以下。首窗试跑给实测数,不生效再给你降级选项;
- 建库骨架、细纲併写、出场登记、窗内预扫、留档查询:全机械,零额度。
## 九、交付物与验证(都是仓库里的人读文件)
- 每书一份《作品面数据样张》markdown实体对账表立卡数/单章路人挡下数/判重合并数/人工待办数)、分型列卡全字段、别名与出场章、关系表、大纲卡全文、**实测缓存命中数据**;试跑样张另附**深空末段压力数据**(书末期单窗输入 token、判重终判次数——验证防膨胀设计成立
- 抽验口径:每书随机 5 张卡**回原文核对事实忠实度**(人名事件对不对得上原文)——作品面卡验的是「像不像这本书」,与范式卡评手法质量的三角色审核是两码事;
- 章表快照列回填覆盖率(应为 100%,缺口列明章号)。
## 十、批准后的收尾动作(不用你操心,列出备查)
- 拆书技能文档同步订正:参考书「脚手架留档、不需逐章确认」的旧表述,与本方案「细纲併写+按书批量确认」对齐;
- 续跑序总账README §九)补作品面升格一步;
- 原文档案表「机战无限」「超神机械师」各一条重复登记行,核实后软删;
- 嵌入表挂已软删草稿的 567 行遗留,清理。