180 lines
14 KiB
Markdown
180 lines
14 KiB
Markdown
# 数据权威与可视化领域 SoT
|
||
|
||
> 本领域定义“数据以谁为准、输入产出如何落库、raw 如何进库、只读看板怎么工作、库如何恢复”。“一切输入产出必须落库可见”这条全系统硬纪律的 owner 在[领域索引 §3](_index.md)，本领域只定义它的**存储与可恢复侧**：哪些东西进哪类表、写入顺序、可恢复要求。原则不在此重复。
|
||
|
||
## 1. 唯一职责
|
||
|
||
本领域拥有：
|
||
|
||
- 数据权威层级：PostgreSQL 是正式内容权威，Git 退回代码与文档的家。
|
||
- 输入产出落库的机制侧：哪些输入产出必须进哪类表，以及落库的可恢复要求。
|
||
- raw（完整原文、完整问答、标准答案、供应商响应）进库与访问控制。
|
||
- 只读可视化看板的合同：它对库只读、绝不写。
|
||
- 可恢复性：库如何从备份加上 Git 里的代码与 DDL 重建。
|
||
|
||
本领域**不拥有**作品、实体、范式的业务语义（那些在各内容领域），也**不决定**候选质量或用户接受结果（那些在质量与复利领域、创作流程领域）。本领域只回答“数据放在哪、谁能看、能不能恢复”。
|
||
|
||
## 2. 权威层级
|
||
|
||
```text
|
||
PostgreSQL（muse-example 库） = 正式内容权威（SoT）
|
||
Git = 代码 / Skill / Agent 提示词 / meta（schema 与 chains）/ 文档 / DDL 的权威
|
||
+ 这些东西的版本历史与备份
|
||
本地 SQLite（data/muse.db） = 运行态账本：默认派发留痕、本地人审、卡片/向量镜像、lesson 本地状态机；
|
||
不产生 Canonical，与 PG 冲突时以 PG 为准（表清单见表映射.md）
|
||
库内向量索引（pgvector） = 数据库一侧的检索加速，不是独立权威，可从库重建
|
||
仓外 vault = 可选备份，不是合同要求
|
||
```
|
||
|
||
- 正式内容都在库里：作品、章、正文、实体、范式、用户决策、运行回执，以及 raw。判断“系统里有没有这个东西”，以库里能不能查到为准。
|
||
- Git 不是正式内容权威。它保存让系统能跑起来、能重建的代码和 DDL 及其变更历史；也可以对作品相关信息和作品文本留痕（历史、备份）。但留痕只是痕迹，不是权威——正式内容以库为准，看板只读库，两者冲突时以库为准。
|
||
- 向量索引只是加速检索（快速找出相关实体和知识）的手段，删掉或损坏不影响正式内容，能从库里的正文和知识重建。
|
||
- 本地 SQLite 运行态账本（2026-08-28 存储裁决）承接默认派发（未显式传 PG 连接工厂时）的 runs/events 留痕、本地人审动作（reviews/revisions）、卡片与向量镜像、lesson 本地状态机和外部反馈数据；schema 变更走 `data/migrations/` 版本化迁移文件。它不产生 Canonical；与 PG 冲突时以 PG 为准。
|
||
- 旧主张“Git 文件是正式内容 SoT、数据库是可删除投影、删库零丢失”已作废，全部反过来。
|
||
|
||
## 3. 一切输入产出落库（机制侧）
|
||
|
||
落库原则（每个输入、每个产出都要落库，没落库等于不存在）见[领域索引 §3](_index.md)，那里是唯一 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） |
|
||
|
||
硬要求：
|
||
|
||
- 上表每一类都必须有库内记录；只读看板看不到的，就是没落库。
|
||
- 每条记录要能回答“它是谁产生的、针对哪个作品/章/候选、什么时候”。
|
||
- 落库写入走受控入口：PG 侧统一经 `muse_db.connect`（DSN 锁死 muse-example），各 Skill 的写函数内聚自己的事务与幂等；本地 SQLite 侧统一经 `muse.store.connect`。严禁智能体或一次性脚本裸连直写（见 §9 与 [07-Agent与Skill领域](07-Agent与Skill领域.md)）。
|
||
|
||
## 4. 写入顺序
|
||
|
||
```text
|
||
校验输入
|
||
-> 写库（正式内容权威）
|
||
-> 记录安全事件 / 变更
|
||
-> 异步刷新库内检索加速（向量索引）
|
||
```
|
||
|
||
- 向量刷新失败**不回滚**已经成功的库写入。向量索引只是加速，可从库重建（见 §8）。
|
||
- 检索加速失败只影响速度，不改变内容语义、不跳过审核。
|
||
- 模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。
|
||
- AI 味检测的卡片写入与同次重验证回执在同一持久化事务内完成；数据库写失败时检测命令失败关闭，不返回“只生成成功”的假绿结果。
|
||
- 任何外部系统、缓存或投影都不得反过来改写库里的正式内容。
|
||
|
||
## 5. raw 进库与访问控制
|
||
|
||
raw 指不适合直接当正文、但需要留存可查的完整材料：完整 Prompt/Response、未接受的候选正文、标准答案、原书全文、供应商原始响应。
|
||
|
||
- raw **进库**，放在单独的表里并加访问控制；只读看板可以看全文。
|
||
- **代价明账**：raw 进库、全文可看，是用**外部可审计性**换**全文可走查性**——评测证据与生产共享同一信任根，系统之外不再有能独立审计它的立足点。这是单用户场景的刻意取舍，是明账不是纯收益。
|
||
- **访问分离，不是隔离**：raw 与正式内容同库，靠访问控制（默认不进检索、看全文须显式指定）分离，不是物理隔离。措辞用“访问分离 / 引擎强制”，不用“隔离”——相信还有隔离，是最终失去隔离的方式。
|
||
- 旧主张“raw 必须留仓外、仓外 vault 是合同要求”已作废：仓外 vault 降级为可选备份，不再是合同要求。
|
||
- 内容表（作品 / 章 / 正文 / 实体）里只放正式内容与安全摘要，不直接塞完整 Prompt/Response。
|
||
- 密钥、token 和外部连接凭据**仍不得**写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。
|
||
|
||
访问控制的最小要求：
|
||
|
||
- raw 表默认不进入普通检索结果；要看全文须显式指定。
|
||
- 看板展示 raw 全文时，不展示密钥 / token / 凭据字段。
|
||
|
||
## 6. 只读可视化模块
|
||
|
||
一个本地 web 看板，把库里的状态随时渲染给人看。核心不变量：纯标准库实现、只对库做只读查询并渲染、**绝不触发任何写**（接受、丢弃等写操作仍由 `决定正文候选去留` Skill 与主会话走，看板只展示结果）；看板看到的等于库里的，因此它倒逼 §3 一切落库——看板上空白的地方，就是落库的缺口。
|
||
|
||
完整合同（只读硬约束、技术形态、视图清单、raw 访问控制、验收）见 [可视化模块合同](../可视化模块合同.md)，那里是本模块的唯一 SoT，本节不复制。
|
||
|
||
### 6.1 本地人审工作台（web/app.py）
|
||
|
||
`web/app.py` 是与 PG 只读看板不同的另一个本地面：它只读 `data/muse.db`，另带三个受控写端点，写面闭集为 `reviews` / `revisions` / `adopt`（机械测试 `tests/e2e/test_compounding.py` 固定该闭集）。它是本地单机草稿人审留痕通道：采纳/修订只落在运行态账本的 reviews/revisions，不产生 Canonical；正式采纳仍走 `决定正文候选去留` → `write_canonical` 的 PG 注册决策通道。写入口统一为 `muse.flow.adopt.adopt_candidate` 与 `muse.store.add_review`，工作台不自行拼 SQL。
|
||
|
||
## 7. 运行回执库表合同
|
||
|
||
每次生成、检测、审核或接受运行，都在库内留下一条回执。旧版“作品内 `runs/` 文件合同”改为库表合同：回执存在库里，不再靠 Git 文件读出。
|
||
|
||
一条回执至少包含：
|
||
|
||
- `run_id`、`attempt`：哪一次运行、第几次尝试。
|
||
- `candidate_version`、`candidate_sha256`：针对哪个候选版本、正文哈希是多少。
|
||
- `context_sha256`：用的是哪一份冻结上下文。
|
||
- 检测与质量结果的安全摘要：结论和失败类别（完整 Prompt/Response 不落这里，落 raw 表）。
|
||
- 用户决策：接受、合并或丢弃。
|
||
- raw 归档指针：完整内容在库内 raw 表的哪条记录。
|
||
|
||
硬要求：
|
||
|
||
- 本节完整回执合同适用于 PG 侧 `example_run_receipt`（结构化身份回执，字段见上）。本地 SQLite 运行态账本的 `runs` 表是它的最小子合同：run_id、冻结输入 JSON、原始产出文本与 skill 集哈希，支撑同输入重跑 diff 回放；不要求携带本节全部字段。
|
||
- 回执写入后**不改写**；新的尝试产生新的记录（不可变账本）。
|
||
- 回执字段合同由本领域拥有；作品领域只提供一个在作品下的归档关系，质量领域只消费其中的结果摘要。
|
||
- 现有实现里 `记录运行证据` 的不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）即属此合同的落地。
|
||
|
||
## 8. 可恢复性
|
||
|
||
数据库是权威，所以可恢复性围绕数据库建立：
|
||
|
||
- **库结构与数据**：靠数据库备份、快照或 dump 恢复。
|
||
- **本地运行态账本**：`data/muse.db` 以文件复制备份——run 前 `cp` 即得数据基线快照，哈希即冻结；误删可由最近副本加 `data/migrations/` 重建 schema 后回填。
|
||
- **从零重建**：用 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-创作流程领域](05-创作流程领域.md)。
|
||
- 数据库写入、DDL 应用走 `访问数据库` Skill 单一通道；DDL 先落 `muse/authority/db/ddl/` 审计文件再应用，不绕过。
|
||
|
||
可承认的现有实现（引用即可，细节以各自载体为准）：
|
||
|
||
- `访问数据库`：单一数据库通道。
|
||
- `记录运行证据`：不可改回执（内容寻址账本）与租约 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）。
|
||
- `导入书稿`：参考书 / 旧稿导入落库。
|
||
|
||
## 10. 待建（目标合同）
|
||
|
||
以下为当前尚未满足、但属于本领域目标合同的缺口：
|
||
|
||
- 一切输入产出落库：AI 味案例三表（104）与 `记录机器味案例` 检测写路径已接通；运行注册 / 回执 / 质量评判 / 模型调用明细（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](_index.md)
|
||
- 内容权威的业务语义：[01-作品领域](01-作品领域.md)、[02-实体领域](02-实体领域.md)、[03-范式领域](03-范式领域.md)
|
||
- 上下文冻结与取数：[04-上下文领域](04-上下文领域.md)
|
||
- 候选、用户决策与接受语义：[05-创作流程领域](05-创作流程领域.md)
|
||
- 检测 / 审核 / 实验结果消费回执：[06-质量与复利领域](06-质量与复利领域.md)
|
||
- 数据库通道与 Skill 边界：[07-Agent与Skill领域](07-Agent与Skill领域.md)
|
||
- 外部交互上级合同：[专题-05](../../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)
|