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

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

• 版本：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 本书（希泊尼战纪/机武风暴/机破星河）不在本次范围。

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

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 抽取全流程（一个窗）

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

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 行遗留，清理。