muse-agent-example/muse/sot/domains/08-数据权威与可视化领域.md

数据权威与可视化领域 SoT

本领域定义“数据以谁为准、输入产出如何落库、raw 如何进库、只读看板怎么工作、库如何恢复”。“一切输入产出必须落库可见”这条全系统硬纪律的 owner 在领域索引 §3，本领域只定义它的存储与可恢复侧：哪些东西进哪类表、写入顺序、可恢复要求。原则不在此重复。

1. 唯一职责

本领域拥有：

• 数据权威层级：PostgreSQL 是正式内容权威，Git 退回代码与文档的家。
• 输入产出落库的机制侧：哪些输入产出必须进哪类表，以及落库的可恢复要求。
• raw（完整原文、完整问答、标准答案、供应商响应）进库与访问控制。
• 只读可视化看板的合同：它对库只读、绝不写。
• 可恢复性：库如何从备份加上 Git 里的代码与 DDL 重建。

本领域不拥有作品、实体、范式的业务语义（那些在各内容领域），也不决定候选质量或用户接受结果（那些在质量与复利领域、创作流程领域）。本领域只回答“数据放在哪、谁能看、能不能恢复”。

2. 权威层级

PostgreSQL（muse-example 库） = 正式内容权威（SoT）
Git                           = 代码 / Skill / Agent 提示词 / meta（schema 与 chains）/ 文档 / DDL 的权威
                                + 这些东西的版本历史与备份
库内向量索引（pgvector）       = 数据库一侧的检索加速，不是独立权威，可从库重建
仓外 vault                    = 可选备份，不是合同要求

• 正式内容都在库里：作品、章、正文、实体、范式、用户决策、运行回执，以及 raw。判断“系统里有没有这个东西”，以库里能不能查到为准。
• Git 不是正式内容权威。它保存让系统能跑起来、能重建的代码和 DDL 及其变更历史；也可以对作品相关信息和作品文本留痕（历史、备份）。但留痕只是痕迹，不是权威——正式内容以库为准，看板只读库，两者冲突时以库为准。
• 向量索引只是加速检索（快速找出相关实体和知识）的手段，删掉或损坏不影响正式内容，能从库里的正文和知识重建。
• 旧主张“Git 文件是正式内容 SoT、数据库是可删除投影、删库零丢失”已作废，全部反过来。

3. 一切输入产出落库（机制侧）

落库原则（每个输入、每个产出都要落库，没落库等于不存在）见领域索引 §3，那里是唯一 owner。本节把它落成存储合同：每类输入产出进哪类表。落库动作由各业务管线与 Skill 负责执行，本领域负责“必须落库的清单”和“可恢复”两件事。

输入产出	落库去向
作品、章、正文（正式）	内容表（作品 / 章 / 正文 block）
实体、关系、叙事状态、世界规则	实体与知识表
范式（写法、适用条件、证据、生命周期）	范式表
用户意图、规划、细纲、冻结的上下文、范式选择	规划与上下文冻结表
AI 待审候选正文（未接受）	候选表（raw 访问控制，见 §5）
检测、评分、审核、实验结果	质量结果表 + 运行回执（见 §7）
AI 味案例卡（既有作品回填 / 创作反馈）	example_ai_flavor_case；检测命令完成后自动写入，默认 shadow
AI 味来源重验证批次与逐卡回执	example_ai_flavor_revalidation_batch + example_ai_flavor_revalidation；append-only，记录 verified/stale/unavailable/card_mismatch
用户的接受 / 合并 / 丢弃决策	用户决策记录
每次运行的回执	运行回执表（见 §7）
补证、重写记录	对应的候选 / 回执记录
模型调用的提示词与执行配置	模型调用记录表（raw 访问控制，见 §5）
完整原文、完整问答、标准答案、供应商响应	raw 表（见 §5）

硬要求：

• 上表每一类都必须有库内记录；只读看板看不到的，就是没落库。
• 每条记录要能回答“它是谁产生的、针对哪个作品/章/候选、什么时候”。
• 落库写入必须走 access-database Skill 这一条数据库通道，不裸连、不散写一次性脚本（见 §9 与 07-Agent与Skill领域）。

4. 写入顺序

校验输入
  -> 写库（正式内容权威）
  -> 记录安全事件 / 变更
  -> 异步刷新库内检索加速（向量索引）

• 向量刷新失败不回滚已经成功的库写入。向量索引只是加速，可从库重建（见 §8）。
• 检索加速失败只影响速度，不改变内容语义、不跳过审核。
• 模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。
• AI 味检测的卡片写入与同次重验证回执在同一持久化事务内完成；数据库写失败时检测命令失败关闭，不返回“只生成成功”的假绿结果。
• 任何外部系统、缓存或投影都不得反过来改写库里的正式内容。

5. raw 进库与访问控制

raw 指不适合直接当正文、但需要留存可查的完整材料：完整 Prompt/Response、未接受的候选正文、标准答案、原书全文、供应商原始响应。

• raw 进库，放在单独的表里并加访问控制；只读看板可以看全文。
• 代价明账：raw 进库、全文可看，是用外部可审计性换全文可走查性——评测证据与生产共享同一信任根，系统之外不再有能独立审计它的立足点。这是单用户场景的刻意取舍，是明账不是纯收益。
• 访问分离，不是隔离：raw 与正式内容同库，靠访问控制（默认不进检索、看全文须显式指定）分离，不是物理隔离。措辞用“访问分离 / 引擎强制”，不用“隔离”——相信还有隔离，是最终失去隔离的方式。
• 旧主张“raw 必须留仓外、仓外 vault 是合同要求”已作废：仓外 vault 降级为可选备份，不再是合同要求。
• 内容表（作品 / 章 / 正文 / 实体）里只放正式内容与安全摘要，不直接塞完整 Prompt/Response。
• 密钥、token 和外部连接凭据仍不得写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。

访问控制的最小要求：

• raw 表默认不进入普通检索结果；要看全文须显式指定。
• 看板展示 raw 全文时，不展示密钥 / token / 凭据字段。

6. 只读可视化模块

一个本地 web 看板，把库里的状态随时渲染给人看。核心不变量：纯标准库实现、只对库做只读查询并渲染、绝不触发任何写（接受、丢弃等写操作仍由 decide-candidate Skill 与主会话走，看板只展示结果）；看板看到的等于库里的，因此它倒逼 §3 一切落库——看板上空白的地方，就是落库的缺口。

完整合同（只读硬约束、技术形态、视图清单、raw 访问控制、验收）见 可视化模块合同，那里是本模块的唯一 SoT，本节不复制。

7. 运行回执库表合同

每次生成、检测、审核或接受运行，都在库内留下一条回执。旧版“作品内 runs/ 文件合同”改为库表合同：回执存在库里，不再靠 Git 文件读出。

一条回执至少包含：

• run_id、attempt：哪一次运行、第几次尝试。
• candidate_version、candidate_sha256：针对哪个候选版本、正文哈希是多少。
• context_sha256：用的是哪一份冻结上下文。
• 检测与质量结果的安全摘要：结论和失败类别（完整 Prompt/Response 不落这里，落 raw 表）。
• 用户决策：接受、合并或丢弃。
• raw 归档指针：完整内容在库内 raw 表的哪条记录。

硬要求：

• 回执写入后不改写；新的尝试产生新的记录（不可变账本）。
• 回执字段合同由本领域拥有；作品领域只提供一个在作品下的归档关系，质量领域只消费其中的结果摘要。
• 现有实现里 record-run-evidence 的不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）即属此合同的落地。

8. 可恢复性

数据库是权威，所以可恢复性围绕数据库建立：

• 库结构与数据：靠数据库备份、快照或 dump 恢复。
• 从零重建：用 Git 里的代码与 DDL（muse/authority/db/ddl/ 审计文件）重建库结构，再恢复数据。
• 向量索引：可从库里的正文与知识重建，不单独备份也不算丢。
• 代码与文档：靠 Git 历史恢复。

不再承诺“删掉数据库零丢失”。删库后可恢复的前提是有可用的备份或 dump，加上 Git 里的代码与 DDL。DB 备份与重建脚本属待建项（见 §10）。

9. Git 角色

• Git 保存代码、Skill、Agent 提示词、meta/（schema 与 chains）、文档、DDL 的版本历史，提供差异审查、回滚依据和备份。
• Git 不是正式内容权威，也不是实时消息总线。它可以对作品信息与作品文本留痕（历史、备份），但留痕不等于权威；正式内容以库为准，看板只读库，冲突时以库为准。
• 一次 git commit 不等于用户接受。接受语义由创作流程和库内状态决定，见 05-创作流程领域。
• 数据库写入、DDL 应用走 access-database Skill 单一通道；DDL 先落 muse/authority/db/ddl/ 审计文件再应用，不绕过。

可承认的现有实现（引用即可，细节以各自载体为准）：

• access-database：单一数据库通道。
• record-run-evidence：不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）。
• 额度账本：muse/authority/db/ddl/95-example额度账本.sql。
• 清洗日志：muse/authority/db/ddl/92-example清洗日志.sql。
• 参考作品授权快照：muse/authority/db/ddl/96-example参考作品授权快照.sql（决定不启用，领域索引 §9；DDL 留存不 apply）。
• import-book：参考书 / 旧稿导入落库。

10. 待建（目标合同）

以下为当前尚未满足、但属于本领域目标合同的缺口：

• 一切输入产出落库：AI 味案例三表（104）与 capture-ai-flavor-cases 检测写路径已接通；运行注册 / 回执 / 质量评判 / 模型调用明细（97/98）已建；候选、用户决策、规划与冻结（99/100）的写路径已由生产链接通（persist_writer_execution / write_canonical / persist_planning / persist_freeze）。本轮新增并已接通：候选语义审查列（105）、事实增量提案与正典账本（106）、投影登记（107）、经验升格登记（108）、候选 CAS 状态链（109）。
• 投影的异步执行：接受时只登记 pending 投影（章后抽取等），worker 与重建调度未建（登记/失效/重试/巡检合同已建，见 projection_registry）。
• 只读可视化看板：首版已建（总览/作品/知识库/运行记录四空间）；运行详情下钻、智能体空间、工作区标签待建。
• raw 全文进库的表与访问控制（101）。
• DB 备份与重建脚本。

11. 验收条件

1. 删库后，能用数据库备份 / dump 加上 Git 里的代码与 DDL 重建出库结构和数据。
2. raw 全文（完整原文、完整问答、标准答案、供应商响应）能从库里读到，且受访问控制。
3. 只读看板对库零写：它发起的所有数据库操作都是只读查询。
4. §3 表中的每一类输入产出，在库里都查得到对应记录；看板看不到的即判为缺口。
5. 向量索引被删除或损坏后，正式内容不丢，且能从库重建索引。
6. 运行回执写入后不可改写，新尝试产生新记录。
7. 内容表与运行报告里查不到密钥 / token / 外部凭据。
8. 检索加速或模型运行失败时，库里已有的正式内容不被损坏、审核终态不被跳过。

12. 关联 SoT

• 横切合同 owner（一切输入产出落库）：领域索引 §3
• 内容权威的业务语义：01-作品领域、02-实体领域、03-范式领域
• 上下文冻结与取数：04-上下文领域
• 候选、用户决策与接受语义：05-创作流程领域
• 检测 / 审核 / 实验结果消费回执：06-质量与复利领域
• 数据库通道与 Skill 边界：07-Agent与Skill领域
• 外部交互上级合同：专题-05