63a65ae9ff
- 新增 docs/2026-07-30 落库与看板设计稿：97-102 表设计(含 102 智能体/技能登记表 A 方案)、写路径、raw 合同、实施顺序 - 可视化合同 §10 重写为领域布局菜单树(五空间+作品工作区+章工作区+跨空间互联+数据来源标注+分阶段点亮) - 清理'不启用 96'残留：合同§9、02/04/08 领域、落库稿统一改为不启用/以 reference_work 为准 - 03 范式补 draft_type 现状标注；_index §4 零依赖口径对齐合同；08 §9/§10 状态收敛
9.3 KiB
实体领域 SoT
1. 唯一职责
实体领域拥有单部作品内可被稳定引用的正式事实（Canonical），包括人物、关系、事件、地点、物品、组织、能力体系、世界规则和叙事状态。它回答“作品世界中有哪些对象、对象之间是什么关系、截至某章哪些事实成立”。
实体领域不拥有正文、规划、跨作品写作范式、模型候选或评测分数。
实体就是库里的一行，不是文件。正式内容权威是 PostgreSQL（muse-example 库）：未确认的叫待审候选（Shadow），确认后才成为正式内容。数据权威的总原则见 领域索引 §2。
2. 数据合同
实体的“长什么样”由两处共同决定，实体领域不另行复制字段：
- 型（有哪些实体类型、各型有哪些字段）：由
meta/schemas/拥有。本领域承认九个实体型：character、character_relation、event、location、item、faction、power_system、world、narrative_state。 - 存放（字段落在哪张库表）：由库表拥有。草稿落
muse_knowledge_draft，已确认落muse_knowledge_entity（关系另有muse_knowledge_relation）。每个实体的可变业务字段放在该行的 JSONBpayload里，型决定 payload 里允许有哪些字段。
一句话：型看 meta/schemas/，字段权威 = meta/schemas/ 的九型 + 库表。本文件只描述实体合同，不复制九型的字段清单。
3. 最小实体合同
一个实体在库里至少要能被这几个字段说清楚（字段名留英文，含义当场白话）：
| 字段 | 含义 |
|---|---|
稳定 id |
作品内唯一，且不因改名而变化 |
type |
实体型，必须落在九型之一 |
status |
生命周期状态（见下） |
| 时态 | 该事实从第几章起成立、到第几章止 |
revision |
第几次被用户确认修改 |
| 来源 | 回到正式正文、已确认设定或已确认规划的位置与内容哈希 |
状态的目标合同是三态：
draft：草稿，未确认，不进正式上下文。canonical：正式事实。retired：已退役，不再作为当前事实参与，但保留记录。
现状标注：库里实际用的状态名是草稿表
pending / confirmed / ignored加正式表active，与设计三态draft / canonical / retired不是一一对应。实现状态名与设计三态待对齐，对齐前以库内实际状态为准、以本节为目标。
约束：
id在作品内稳定，改名不换 id。type必须是meta/schemas/已登记的九型之一。- 只有用户确认或正式正文支持的事实才能成为正式内容；草稿不得静默进入后续正式上下文。
- 来源要能回到不可变位置和内容哈希，不能只写“某章某段”。
- 会随剧情变化的事实必须带生效章区间，不能用终态覆盖历史时点。
4. 实体与作品关系
- 作品侧只引用实体
id，不复制实体的详细字段。 - 作品级设定可以定义创作边界和主题，但不得成为人物、地点、事件的第二事实源。
- 正文保存或候选接受后可以产生实体草稿；草稿不进入后续正式上下文。
- 草稿到正式是一次库内状态流转：由用户确认（
confirm）把草稿从pending翻成confirmed，并落出正式表active行、revision加一。没有用户确认，草稿不会自己变正式。 - 实体的演进历史由库与 Git 共同留痕（库留当前合同与必要时态区间，Git 留 DDL、代码与变更历史），不在实体行里另写一份不可校验的历史叙述副本。
5. 拆书与知识草稿入口
本项目不只写自己的书，也拆别人的书：把参考书导入、分章、解析，抽出可复用的知识，经审核形成知识草稿。这条链的一个落点就是实体领域——参考书里的人物、关系、设定可以成为本作品的实体草稿。
- 参考书导入后先分章解析，解析结果是待审候选，不是正式事实。
- 解析结果经审核、再由用户确认，才成为实体草稿并最终落库为正式实体；和从正文产生的草稿走同一条确认链，不因来源是参考书而跳过确认。
- 拆书得到的“写法经验”不落实体领域，归范式领域，见 03-范式领域。
- 参考书全文按 raw 规则进库（单独表加访问控制，只读看板可看全文），不再留仓外，见 领域索引 §8。
6. 作品面实体入库管线（本领域拥有）
这一节归实体领域拥有。它把参考书里的人物、关系卡抽进库的正式层，是一条确定性管线：
- 抽取：从参考书解析结果里抽出人物卡、关系卡，写入草稿表。
- 别名判重：同一人物在不同书里叫法不同，按别名归并到同一实体，避免一人多卡。
- 跨窗出场留档：人物在长篇里分窗（按窗口切分的大段）出现，逐窗记录其出场与状态变化，留作证据。
- 覆写审计：每次抽取或覆写都留痕，能追溯“这条卡是谁、何时、依据哪段原文写进来的”。
- 灾备导出：正式层可导出，配合数据库备份用于恢复。
- 参考作品的出处与导入信息以
example_reference_work/muse_knowledge_document为准（领域索引 §9：不做多租户授权机制，96 授权快照不启用）。
注意区分两个“升格”：本节是作品面实体升格——把参考书的人物/关系抽进库的正式层。06 质量与复利领域的“经验升格”是另一件事——把写法经验从写法→范式→Skill 逐级固化。两者只是都叫“升格”，对象和去向完全不同，不要混为一谈。作品面升格对应实现：upgrade skill 加
db/ddl/94-example作品面升格.sql。
7. 关系与状态
- 关系作为独立实体，引用两端实体
id，并带方向、关系类型、有效章区间和来源。 - 事件记录参与者、发生章、结果和来源，不把正文摘要当作完整事实。
- 叙事状态（
narrative_state）保存可变状态，如位置、持有物、知情范围、伤势和关系阶段；状态必须能按“截至某章”（as_of）重建。 - 无法证明章号或来源的状态只能标为草稿或省略，不能推断成正式事实。
现状标注：叙事时态目前用“演变历程”的双层模型表达（一条当前态加一条演变记录），与设计里的
valid_from / valid_to_chapter章区间并存。两套时态表示待对齐，对齐前两者都承认、以库内实际为准。
8. 检索
实体检索 = 库内查询 + 库内检索加速（向量）。
- 按
id、名称、别名、型、章号过滤，直接在库里查。 - 语义召回走库内检索加速（pgvector 向量索引），它只是数据库一侧的加速，不是独立权威，可从库重建。
- 命中后回读库行并校验内容哈希，确认拿到的是库里当前正式行——不是回读任何文件。
- 检索加速失败只影响速度，不改变实体内容语义、不跳过审核。
9. 验收条件
- 任一正式实体都能回到库内来源行，并经内容哈希校验一致。
- 同一事实只有一个 owner 行，不要求同时维护 Markdown 与 JSON 两份人工事实。
- 按目标章冻结上下文时，不会读取该章之后才成立的状态。
- 实体草稿不会静默进入正式创作上下文（可机械验证：未被用户确认的草稿不出现在冻结的正式上下文里）。
- 参考书导入产生的实体草稿与正文产生的实体草稿走同一条确认链（可机械验证：两类草稿的确认都经
confirm触发、都产生正式表行）。 - 向量召回命中后回读的是库行而非文件（可机械验证：命中结果带库行 id 与内容哈希，且哈希与库一致）。
- 作品面入库管线的每一次覆写都有审计记录，可追到来源原文。
- 可恢复性（库损坏后能否重建）见 08-数据权威与可视化领域。
10. 关联 SoT
- 类型结构：
meta/schemas/ - 数据权威与可恢复性：08-数据权威与可视化领域
- 作品引用：01-作品领域
- 上下文冻结：04-上下文领域
- 经验升格（与作品面实体升格不同）：06-质量与复利领域
- 父仓元数据合同：专题-06
附：现状与目标合同对照
可承认的现有实现（已建成，引用即可）：
- 拆书与作品面实体入库管线（抽取、别名判重、跨窗留档、覆写审计）。
- review-cards 三角色审核（番茄作家 / 起点作家 / 主编）作为拆书常设步骤。
aiContext字段级用途裁剪（按用途只取需要的字段）。- 参考作品授权快照表（
db/ddl/96）：决定不启用（领域索引 §9），DDL 留存不 apply。
待建（目标合同，尚未跑通）：
- 草稿→确认的后半段真正跑通（当前正式表、绑定表基本为空，卡多在
pending）。 - 稳定
id不因改名变化的保证。 retired退役态。- 删库可恢复（见 08）。