# 实体领域 SoT

## 1. 唯一职责

实体领域拥有单部作品内可被稳定引用的正式事实（Canonical），包括人物、关系、事件、地点、物品、组织、能力体系、世界规则和叙事状态。它回答“作品世界中有哪些对象、对象之间是什么关系、截至某章哪些事实成立”。

实体领域不拥有正文、规划、跨作品写作范式、模型候选或评测分数。

实体就是库里的一行，不是文件。正式内容权威是 PostgreSQL（`muse-example` 库）：未确认的叫待审候选（Shadow），确认后才成为正式内容。数据权威的总原则见 [领域索引](./_index.md) §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`）。每个实体的可变业务字段放在该行的 JSONB `payload` 里，型决定 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/` 已登记的九型之一。
- 只有用户确认或正式正文支持的事实才能成为正式内容；草稿不得静默进入后续正式上下文。
- 来源要能回到不可变位置和内容哈希，不能只写“某章某段”。
- 会随剧情变化的事实必须带生效章区间，不能用终态覆盖历史时点。

> 边界说明：正文提交时随事务登记的**事实增量账本**（`example_fact_delta` / `example_fact_ledger`，见 [08-数据权威](08-数据权威与可视化领域.md) §10）记录的是"哪次提交批准了哪条类型化变更"的变更流证据，绑正文块 revision；**实体当前事实**（人物位置、关系、知情范围等的现行态）的 owner 仍是本领域。增量账本不是实体事实的第二事实源，二者是"变更流水"与"现行状态"的分工。

## 4. 实体与作品关系

- 作品侧只引用实体 `id`，不复制实体的详细字段。
- 作品级设定可以定义创作边界和主题，但不得成为人物、地点、事件的第二事实源。
- 正文保存或候选接受后可以产生实体草稿；**草稿不进入后续正式上下文**。
- 草稿到正式是一次**库内状态流转**：由用户确认（`decide-candidate`）把草稿从 `pending` 翻成 `confirmed`，并落出正式表 `active` 行、`revision` 加一。没有用户确认，草稿不会自己变正式。
- 实体的演进历史由库与 Git 共同留痕（库留当前合同与必要时态区间，Git 留 DDL、代码与变更历史），不在实体行里另写一份不可校验的历史叙述副本。

## 5. 拆书与知识草稿入口

本项目不只写自己的书，也拆别人的书：把参考书导入、分章、解析，抽出可复用的知识，经审核形成知识草稿。这条链的一个落点就是实体领域——参考书里的人物、关系、设定可以成为本作品的实体草稿。

- 参考书导入后先分章解析，解析结果是待审候选，不是正式事实。
- 解析结果经审核、再由用户确认，才成为实体草稿并最终落库为正式实体；和从正文产生的草稿走**同一条确认链**，不因来源是参考书而跳过确认。
- 拆书得到的“写法经验”不落实体领域，归范式领域，见 [03-范式领域](03-范式领域.md)。
- 参考书全文按 raw 规则**进库**（单独表加访问控制，只读看板可看全文），不再留仓外，见 [领域索引](./_index.md) §8。

## 6. 作品面实体入库管线（本领域拥有）

这一节归实体领域拥有。它把参考书里的人物、关系卡抽进库的正式层，是一条确定性管线：

- **抽取**：从参考书解析结果里抽出人物卡、关系卡，写入草稿表。
- **别名判重**：同一人物在不同书里叫法不同，按别名归并到同一实体，避免一人多卡。
- **跨窗出场留档**：人物在长篇里分窗（按窗口切分的大段）出现，逐窗记录其出场与状态变化，留作证据。
- **覆写审计**：每次抽取或覆写都留痕，能追溯“这条卡是谁、何时、依据哪段原文写进来的”。
- **灾备导出**：正式层可导出，配合数据库备份用于恢复。
- 参考作品的出处与导入信息以 `example_reference_work` / `muse_knowledge_document` 为准（领域索引 §9：不做多租户授权机制，96 授权快照不启用）。

> 注意区分两个“升格”：本节是**作品面实体升格**——把参考书的人物/关系抽进库的正式层。06 质量与复利领域的“经验升格”是另一件事——把写法经验从写法→范式→Skill 逐级固化。两者只是都叫“升格”，对象和去向完全不同，不要混为一谈。作品面升格对应实现：`extract-work-knowledge`，加维护三件套 `backup-work-extraction` / `reset-work-extraction` / `repair-work-extraction` 与 `db/ddl/94-example作品面升格.sql`。

## 7. 关系与状态

- 关系作为独立实体，引用两端实体 `id`，并带方向、关系类型、有效章区间和来源。
- 事件记录参与者、发生章、结果和来源，不把正文摘要当作完整事实。
- 叙事状态（`narrative_state`）保存可变状态，如位置、持有物、知情范围、伤势和关系阶段；状态必须能按“截至某章”（`as_of`）重建。
- 无法证明章号或来源的状态只能标为草稿或省略，不能推断成正式事实。

> 现状标注：叙事时态目前用“演变历程”的双层模型表达（一条当前态加一条演变记录），与设计里的 `valid_from / valid_to_chapter` 章区间并存。**两套时态表示待对齐**，对齐前两者都承认、以库内实际为准。

## 8. 设计决策：设定全书闭环与台账

### 背景

演变历程 `{章, 台阶, 周期}` 的字段合同在 `meta/schemas/` 与 [专题-06](../../../../../design-docs/专题-06-元数据驱动的智能体架构.md) §4.5，三期消费语义（规划/检测/写作）在 [专题-07](../../../../../design-docs/专题-07-知识消费契约与质量闭环.md) §5。现状合同里它是**只追加的已发生日志**：一条一台阶、只追加不覆写。由此留下两个无主缺口：

- **只记已发生、不约束未来**：台阶只记到 登场/成长/高光/退场，“这条设定最终去哪”没有结构义务。角色有没有结局、力量体系如何退场，全靠作者记忆——升级线崩、线索太监、续写提前收线，都没有机械门禁提前拦。
- **没有全书视角**：哪条设定被哪几章消费过、哪些从没被碰、哪些还没收口，只能靠人判断，不能机械计算。

检测维度 `canon_compliance`（[专题-04](../../../../../design-docs/专题-04-生成质量门控与创作健康度设计方案.md)）只查候选是否与已立正式事实矛盾（**一致性**）；它不查设定自身是否有始有终、被消费、被收口（**完整性**）。完整性目前无 owner。

### 选项

| 选项 | 做法 | 为何不选/选 |
|---|---|---|
| A. 维持只追加日志，闭环靠人工 | 演变历程不动，全书闭环靠人记忆与人工审计 | 不选：不可机械验证、不能提前拦；百万字规模人工审计必漏 |
| B. 只在写作/检测期补闭环 | 检测智能体发现未收口线时报警 | 不选：检测是章级、事后；且一致性与完整性是两种义务，塞进同一条检测链难收敛 |
| C. 入库即闭环义务 + 全书台账 | 设定首次确认时门禁“计划弧线有始有终”；台账机械计算设定×章消费矩阵，常设报警未被碰/未收口 | 选：义务落在最早时点（设定拆条确认），机械可验；台账不手工镜像，可从库表随时重算 |

### 结论

采 C。实体领域拥有**闭环义务合同**与**台账数据形状**；不重定义 演变历程/成长弧线 的字段语义（归 `meta/schemas/` 与 专题-06 §4.5），不改其三期消费合同（归 专题-07 §5），不重定义 `canon_compliance`（归 专题-04）。

**① 闭环义务：从只追加日志升级为闭环**

- 义务对象：`meta/schemas/` 登记了 演变历程 的六个型——`character` / `event` / `faction` / `location` / `item` / `power_system`。未登记 演变历程 的型（如 `narrative_state`、`character_relation`）不受此义务约束。
- 闭环定义：一条设定的“已发生台阶（演变历程）”与“未来计划”合起来必须覆盖 登场 → … → 结局。即有明确的 登场 台阶，并有声明的 结局 方向——未来记在该型的未来计划字段，已发生的结局记在 演变历程（周期=结局）。“有终”指计划明写这条设定如何收场（角色的结局、力量体系的退场或湮灭、物品的归属），不是只有成长台阶。
- 机械执行时点：
  - **入库硬门禁**：设定草稿首次经 `decide-candidate` 成为正式行时（draft→canonical 确认路径），校验计划弧线有始有终，缺一则确认失败、不落正式行。机械失败不可被 Agent 主观覆判（与 [06-质量与复利领域](06-质量与复利领域.md) 质量链一致）。弧线的合法变更只走用户确认的正式修订（`revision` 加一）或带审计的 `retired`（§3 三态），这两条不是绕过门禁。
  - **完本硬门禁**：作品状态转 完本（`completed` 流转归 [01-作品领域](01-作品领域.md)）前，校验所有义务设定已在 演变历程 落到 结局（实现收口）或经 `retired` 带审计；存在 未收口 则不得转 完本。
  - **常设不变量**：台账（②）持续运行，把 未被碰/未收口 项曝为创作健康度项（与 06 长期验证轴一致），违反即报警。

**② 全书设定台账：数据形状与计算来源**

- 性质：派生视图，从库表机械计算，**不建手工镜像存储**（与 01 §3“派生量不手工镜像”、索引 §3“一切输入产出落库”一致）。数据形状合同归实体领域，渲染由 [08-数据权威与可视化领域](08-数据权威与可视化领域.md) 的只读看板承载。
- 形状：设定×章消费矩阵。行 = 本作义务设定（`muse_knowledge_entity` 的 active 行），列 = 章（`muse_content_chapter`）。格状态按“截至该章”的累计口径取三值；未收口 是行级（全书）结论：

  | 标记 | 判据 |
  |---|---|
  | 未被碰 | 截至第 n 章，该设定无已发生台阶、也无正式正文消费 |
  | 已消费 | 截至第 n 章有已发生消费，但尚未出现 结局 台阶 |
  | 已收口 | 截至第 n 章存在 周期=结局 的台阶（实现收口） |
  | 未收口（行级） | 计划弧线声明了 结局 方向，但截至当前最新章（或完本时）尚未实现 结局 台阶 |

- 计算来源（全部库表，可随时重算）：
  - 已发生台阶与实现收口：实体行 JSONB 里的 演变历程——每条 `{章, 台阶, 周期}` 直接给出“该设定在哪章推进”，周期=结局 给出收口。
  - 正文消费：`muse_content_block_source_attribution`（确认时写入的来源归因）把正文块关联到实体，经 `muse_content_block` / `muse_content_chapter` 给出“实际在哪章被消费”。
  - 计划弧线与结局方向：实体行 JSONB 里的未来计划字段（`character` 为 成长弧线）。
  - 计划消费：`example_planning_section` 的章级细纲（`fine_outline`）声明的必须出场实体与伏笔动作，只用于计算“计划碰而实际没碰”的偏差信号，不改格的已发生状态。

**③ 与 `canon_compliance` 的边界**

- `canon_compliance`（专题-04）问“是否与已立事实矛盾”，是一致性；闭环与台账问“是否有始有终、被消费、被收口”，是完整性。两者正交：不合并、不互相替代。
- 候选通过一致性检测，不豁免设定的闭环义务；台账报 未收口，也不代表任何候选吃了设定。

> 现状标注：未来计划字段目前只有 `character` 登记（成长弧线）；其余五个义务型只有 演变历程（已发生），无未来计划字段——它们的计划闭环暂不可机械校验。字段合同补齐归 `meta/schemas/`（术语与字段合同见 专题-06 §4.5），本节只定义义务、不定义字段。补齐前，这五型的入库门禁降级为校验已发生部分（须有 登场 台阶），结局方向暂由规划（大纲/细纲）声明、在台账登记为 未收口；字段补齐后升级为完整的计划闭环校验。

### 后果

- `decide-candidate` 路径新增一项入库门禁：设定首次确认必须带 有始有终 的计划弧线，否则不落正式行。
- 作品新增一个全书常设视图（台账），由 08 只读看板渲染；完本新增一项实现收口硬门禁（流转归 01 作品领域，校验归本领域）。
- 演变历程的消费语义不变：续写仍不给 演变历程 全线（专题-07 §5 与其验收条款 6）；台账是全书健康度视图，不改逐章上下文注入。
- 待建：`decide-candidate` 的计划弧线门禁、台账视图、完本收口门禁均未建成；建成前闭环不被机械校验（登记于本文件 附·待建）。

## 9. 检索

实体检索 = 库内查询 + 库内检索加速（向量）。

- 按 `id`、名称、别名、型、章号过滤，直接在库里查。
- 语义召回走库内检索加速（pgvector 向量索引），它只是数据库一侧的加速，不是独立权威，可从库重建。
- **命中后回读库行并校验内容哈希**，确认拿到的是库里当前正式行——不是回读任何文件。
- 检索加速失败只影响速度，不改变实体内容语义、不跳过审核。

## 10. 验收条件

1. 任一正式实体都能回到库内来源行，并经内容哈希校验一致。
2. 同一事实只有一个 owner 行，不要求同时维护 Markdown 与 JSON 两份人工事实。
3. 按目标章冻结上下文时，不会读取该章之后才成立的状态。
4. 实体草稿不会静默进入正式创作上下文（可机械验证：未被用户确认的草稿不出现在冻结的正式上下文里）。
5. 参考书导入产生的实体草稿与正文产生的实体草稿走同一条确认链（可机械验证：两类草稿的确认都经 `decide-candidate` 触发、都产生正式表行）。
6. 向量召回命中后回读的是库行而非文件（可机械验证：命中结果带库行 id 与内容哈希，且哈希与库一致）。
7. 作品面入库管线的每一次覆写都有审计记录，可追到来源原文。
8. 义务型设定草稿首次确认时，计划弧线缺 登场 或 结局 方向则不落正式行（可机械验证：任一义务型正式设定行都能回读出含 登场 台阶与 结局 方向的弧线）。
9. 台账从库表机械重算、无手工镜像：同一设定×同一章的消费状态两次重算一致，库内不存在台账镜像行。
10. 可恢复性（库损坏后能否重建）见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。

## 11. 关联 SoT

- 类型结构：[`meta/schemas/`](../../../../meta/schemas/README.md)
- 数据权威与可恢复性：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)
- 作品引用：[01-作品领域](01-作品领域.md)
- 上下文冻结：[04-上下文领域](04-上下文领域.md)
- 经验升格（与作品面实体升格不同）：[06-质量与复利领域](06-质量与复利领域.md)
- 演变历程三期消费语义（owner，本领域 §8 只加完整性义务、不改消费）：[专题-07](../../../../../design-docs/专题-07-知识消费契约与质量闭环.md) §5
- 一致性检测维度 `canon_compliance`（与 §8 闭环完整性正交）：[专题-04](../../../../../design-docs/专题-04-生成质量门控与创作健康度设计方案.md)
- 父仓元数据合同：[专题-06](../../../../../design-docs/专题-06-元数据驱动的智能体架构.md)

---

## 附：现状与目标合同对照

可承认的现有实现（已建成，引用即可）：

- 拆书与作品面实体入库管线（抽取、别名判重、跨窗留档、覆写审计）。
- review-knowledge-cards 三角色审核（番茄作家 / 起点作家 / 主编）作为拆书常设步骤。
- `aiContext` 字段级用途裁剪（按用途只取需要的字段）。
- 参考作品授权快照表（`db/ddl/96`）：**决定不启用**（领域索引 §9），DDL 留存不 apply。

待建（目标合同，尚未跑通）：

- 草稿→确认的后半段真正跑通（当前正式表、绑定表基本为空，卡多在 `pending`）。
- 稳定 `id` 不因改名变化的保证。
- `retired` 退役态。
- 设定全书闭环与台账（§8）：`decide-candidate` 计划弧线入库门禁、全书设定台账视图、完本实现收口门禁；建成前闭环不被机械校验。
- 五个义务型（`event`/`faction`/`location`/`item`/`power_system`）的未来计划字段补齐（字段合同归 `meta/schemas/`，见 §8 现状标注）。
- 删库可恢复（见 08）。