b0bc7a8745
一、技能重组（动作-对象命名） - 旧目录 clean/confirm/continuation/db/detect/embed/… 重组为 clean-book-text/decide-candidate/write-next-chapter/access-database/ check-content-consistency/embed-knowledge/…（git 识别为 rename，内容保持） - agents/*.md、AGENTS.md/CLAUDE.md 收编、example_skill 登记表同步新名 二、先审后入创作闭环（本次核心） 正文接受从"机械门一过就写正典"改为"机械门+语义审查双通过+用户批准+单事务原子提交"， DB 级兜底，编排层跳步即被硬拒。 - candidate_cas.py + example_candidate_cas(109)：持久化 CAS 状态链 - fact_delta.py + example_fact_delta/example_fact_ledger(106)：结构化事实增量， 模型只提六型闭集增量+正文证据引文，仅用户批准的增量随正文同事务入账本 - projection_registry.py + example_projection_run(107)：投影登记与恢复 - acceptance_state.py：接受前置实时状态重读 - lesson_registry.py + example_lesson(108)：经验升格链，禁止自动升格 - DDL 105：example_candidate 增 semantic_status/semantic_report_sha256 - write_canonical.accept：语义兜底+同事务合并增量+登记投影； run_writer_pipeline/persist_writer_run/run_writer_semantic_detector/step2 接入全链 - claude_runtime：兼容新 CLI modelUsage 信息字段 三、审查修复（独立子代理四维审查后） - 事实增量 propose→approve 翻态正道，不撞唯一键 - 冻结配置探针重刷（CLI 2.1.211→2.1.231 漂移），profileSha256/adapterVersion 再登记 - 可视化合同悬空路径/五六空间矛盾、 SoT 旧技能名漂移、行尾空白清理 测试：离线 65 套 + 真实库集成 5 套（CAS/接受故障注入/事实增量/投影/经验升格）+ 回放 79 项全绿。 创作内容（docs/design、生成正文 artifacts）按"框架与创作分开"未入本提交。
171 lines
13 KiB
Markdown
171 lines
13 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 的权威
|
||
+ 这些东西的版本历史与备份
|
||
库内向量索引（pgvector） = 数据库一侧的检索加速，不是独立权威，可从库重建
|
||
仓外 vault = 可选备份，不是合同要求
|
||
```
|
||
|
||
- 正式内容都在库里：作品、章、正文、实体、范式、用户决策、运行回执，以及 raw。判断“系统里有没有这个东西”，以库里能不能查到为准。
|
||
- Git 不是正式内容权威。它保存让系统能跑起来、能重建的代码和 DDL 及其变更历史；也可以对作品相关信息和作品文本留痕（历史、备份）。但留痕只是痕迹，不是权威——正式内容以库为准，看板只读库，两者冲突时以库为准。
|
||
- 向量索引只是加速检索（快速找出相关实体和知识）的手段，删掉或损坏不影响正式内容，能从库里的正文和知识重建。
|
||
- 旧主张“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） |
|
||
|
||
硬要求：
|
||
|
||
- 上表每一类都必须有库内记录；只读看板看不到的，就是没落库。
|
||
- 每条记录要能回答“它是谁产生的、针对哪个作品/章/候选、什么时候”。
|
||
- 落库写入必须走 `access-database` Skill 这一条数据库通道，不裸连、不散写一次性脚本（见 §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 看板，把库里的状态随时渲染给人看。核心不变量：纯标准库实现、只对库做只读查询并渲染、**绝不触发任何写**（接受、丢弃等写操作仍由 `decide-candidate` Skill 与主会话走，看板只展示结果）；看板看到的等于库里的，因此它倒逼 §3 一切落库——看板上空白的地方，就是落库的缺口。
|
||
|
||
完整合同（只读硬约束、技术形态、视图清单、raw 访问控制、验收）见 [可视化模块合同](../可视化模块合同.md)，那里是本模块的唯一 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（`db/ddl/` 审计文件）重建库结构，再恢复数据。
|
||
- **向量索引**：可从库里的正文与知识重建，不单独备份也不算丢。
|
||
- **代码与文档**：靠 Git 历史恢复。
|
||
|
||
不再承诺“删掉数据库零丢失”。删库后可恢复的前提是有可用的备份或 dump，加上 Git 里的代码与 DDL。DB 备份与重建脚本属待建项（见 §10）。
|
||
|
||
## 9. Git 角色
|
||
|
||
- Git 保存代码、Skill、Agent 提示词、`meta/`（schema 与 chains）、文档、DDL 的版本历史，提供差异审查、回滚依据和备份。
|
||
- Git 不是正式内容权威，也不是实时消息总线。它可以对作品信息与作品文本留痕（历史、备份），但留痕不等于权威；正式内容以库为准，看板只读库，冲突时以库为准。
|
||
- 一次 `git commit` **不等于**用户接受。接受语义由创作流程和库内状态决定，见 [05-创作流程领域](05-创作流程领域.md)。
|
||
- 数据库写入、DDL 应用走 `access-database` Skill 单一通道；DDL 先落 `db/ddl/` 审计文件再应用，不绕过。
|
||
|
||
可承认的现有实现（引用即可，细节以各自载体为准）：
|
||
|
||
- `access-database`：单一数据库通道。
|
||
- `record-run-evidence`：不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）。
|
||
- 额度账本：`db/ddl/95-example额度账本.sql`。
|
||
- 清洗日志：`db/ddl/92-example清洗日志.sql`。
|
||
- 参考作品授权快照：`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](_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)
|