zizi-al/muse-agent-example
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
muse-agent-example/muse/sot/domains/02-实体领域.md

18 KiB
Raw Blame History

实体领域 SoT

1. 唯一职责

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

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

实体就是库里的一行，不是文件。正式内容权威是 PostgreSQL（muse-example 库）：未确认的叫待审候选（Shadow），确认后才成为正式内容。数据权威的总原则见 领域索引 §2。

2. 数据合同

实体的“长什么样”由两处共同决定，实体领域不另行复制字段：

  • 型（有哪些实体类型、各型有哪些字段）：由 muse/content/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 里允许有哪些字段。

一句话：型看 muse/content/meta/schemas/，字段权威 = muse/content/meta/schemas/ 的九型 + 库表。本文件只描述实体合同，不复制九型的字段清单。

3. 最小实体合同

一个实体在库里至少要能被这几个字段说清楚（字段名留英文，含义当场白话）：

字段 含义
稳定 id 作品内唯一，且不因改名而变化
type 实体型，必须落在九型之一
status 生命周期状态（见下）
时态 该事实从第几章起成立、到第几章止
revision 第几次被用户确认修改
来源 回到正式正文、已确认设定或已确认规划的位置与内容哈希

状态的目标合同是三态：

  • draft：草稿，未确认，不进正式上下文。
  • canonical：正式事实。
  • retired：已退役，不再作为当前事实参与，但保留记录。

现状标注：库里实际用的状态名是草稿表 pending / confirmed / ignored 加正式表 active，与设计三态 draft / canonical / retired 不是一一对应。实现状态名与设计三态待对齐，对齐前以库内实际状态为准、以本节为目标。

约束：

  • id 在作品内稳定，改名不换 id。
  • type 必须是 muse/content/meta/schemas/ 已登记的九型之一。
  • 只有用户确认或正式正文支持的事实才能成为正式内容；草稿不得静默进入后续正式上下文。
  • 来源要能回到不可变位置和内容哈希，不能只写“某章某段”。
  • 会随剧情变化的事实必须带生效章区间，不能用终态覆盖历史时点。

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

4. 实体与作品关系

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

5. 拆书与知识草稿入口

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

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

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

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

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

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

7. 关系与状态

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

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

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

背景

演变历程 {章, 台阶, 周期} 的字段合同在 muse/content/meta/schemas/ 与 专题-06 §4.5，三期消费语义（规划/检测/写作）在 专题-07 §5。现状合同里它是只追加的已发生日志：一条一台阶、只追加不覆写。由此留下两个无主缺口：

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

检测维度 canon_compliance（专题-04）只查候选是否与已立正式事实矛盾（一致性）；它不查设定自身是否有始有终、被消费、被收口（完整性）。完整性目前无 owner。

选项

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

结论

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

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

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

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

  • 性质：派生视图，从库表机械计算，不建手工镜像存储（与 01 §3“派生量不手工镜像”、索引 §3“一切输入产出落库”一致）。数据形状合同归实体领域，渲染由 08-数据权威与可视化领域 的只读看板承载。

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

后果

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

9. 检索

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

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

10. 验收条件

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

11. 关联 SoT

附：现状与目标合同对照

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

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

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

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