4adc85cafd
- 八个领域 SoT + 索引：正式内容权威从 Git 文件改为 PostgreSQL；Git 退回代码/文档/DDL 权威，可对作品信息与文本留痕但非权威。 - 立横切合同：一切输入产出必须落库可见；raw 进库可看全文（访问控制）。 - 08 更名为数据权威与可视化领域；新增独立 可视化模块合同（只读查库渲染，绝不写）。 - AGENTS.md / README.md 同步翻面。
97 lines
7.6 KiB
Markdown
97 lines
7.6 KiB
Markdown
# 只读可视化模块合同
|
||
|
||
> 本文件是只读可视化模块（下称“看板”）的设计 SoT。数据权威、落库原则和可恢复性见 [领域索引](domains/_index.md) §2/§3 与 [08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)；本文件只定义看板这个**只读**模块本身。库内有哪些表、各表现状以 [`db/表映射.md`](../../../db/表映射.md) 为准。
|
||
|
||
## 1. 它是什么，不做什么
|
||
|
||
看板是一个本地 web 页面，把 `muse-example` 库里的状态随时渲染给你看。
|
||
|
||
- 它只干两件事：对库做**只读查询**，把结果渲染成人能读的页面。
|
||
- 它**绝不触发任何写操作**。接受、合并、丢弃、确认这些写，仍由 `confirm` skill 和主会话走，看板只展示结果。
|
||
- 它看到的 = 库里的。看板上空白的地方，就是落库的缺口——所以看板天然是“一切输入产出必须落库”这条纪律的验收面。
|
||
- 它服务本机单用户，不做多用户、权限管理、对外分享。
|
||
|
||
## 2. 只读硬约束（怎么保证它绝不写）
|
||
|
||
这是看板的命根子，验收时按机械门查：
|
||
|
||
- **连接只读**：看板用独立的只读连接，默认事务只读（`SET TRANSACTION READ ONLY` 或库侧只读角色）；连接串与写通道（`db` skill）分开。
|
||
- **代码无写语句**：全模块只允许 `SELECT`，不得出现任何 `INSERT/UPDATE/DELETE` 或 DDL。审查以“grep 全代码无写语句”为门。
|
||
- **不接会写的通道**：看板不调用 `confirm` 或任何会写库的 skill，只自己读库。
|
||
- **挂了不牵连**：看板进程崩了、断网了，库内正式内容和创作链不受任何影响。
|
||
|
||
## 3. 技术形态
|
||
|
||
- web 层用纯 Python 标准库的 HTTP 服务（`http.server` 一类），**不引入任何 web 框架**，`python3` 直接跑。形态参照 open-wenmo 的 hub（前端相对路径 + 注入 base）。
|
||
- **一处如实说明**：查 PostgreSQL 需要数据库驱动，而驱动（psycopg）不是标准库。所以“零 pip”在这里的准确含义是——**web 层零框架、零新增依赖；数据库驱动复用本仓 `.venv` 里现成的 psycopg，且只用于只读连接**。不为看板新装任何东西。
|
||
- 门禁参照 open-wenmo：本机 / 局域网 / Tailscale 直连免验证；如需公网，走 TOTP 动态码。单用户本地信任。
|
||
- 端口、页面结构等实现细节实现期再定；本合同只约束“只读 + 查库 + 渲染”这三条不变。
|
||
|
||
## 4. 视图清单（一次画全，待落库的标明）
|
||
|
||
### 4.1 现已在库（看板一上线就有数据）
|
||
|
||
| 视图 | 看什么 | 对应表 |
|
||
|---|---|---|
|
||
| 作品全貌 | 作品列表 → 章列表 → 正文全文 | `muse_content_work` / `muse_content_chapter` / `muse_content_block`（正文在 `content_text`） |
|
||
| 知识卡（实体与范式） | 草稿卡、已确认卡、按型别与公共/作品分布 | `muse_knowledge_draft`（草稿）/ `muse_knowledge_entity`（已确认）/ `muse_knowledge_base`（库）/ `muse_knowledge_binding`（绑定） |
|
||
| 参考书与拆书 | 参考书档案、拆书任务状态、逐章脚手架、窗级大纲 | `example_reference_work` / `example_parse_task` / `example_parse_scaffold` / `example_parse_outline` / `muse_knowledge_document`（原文档案指针） |
|
||
| 清洗审计 | 每次删了哪段原文、为什么、哪个模型、哪一批，可回放 | `example_clean_log` |
|
||
| 额度账本 | 5 小时额度窗、花费与调用次数水位 | 额度账本表（`db/ddl/95-example额度账本.sql`） |
|
||
| 结构本体（框架视图，可选） | 23 型合同、字段、aiContext 控制项、保护节点、功能链 | `muse_meta_schema` / `muse_meta_field` / `muse_meta_visibility_policy` / `muse_meta_protection_node` / `muse_meta_function_chain` |
|
||
| 写命令审计 | 写命令的幂等审计记录 | `muse_content_command_log` |
|
||
| 授权快照 | 参考书原文版本对应的用途授权 | `example_reference_authorization_snapshot`（`db/ddl/96`，**待 apply**） |
|
||
|
||
### 4.2 待落库（合同要求、表尚未建/未接通；看板预留视图，暂显示“无数据 / 待落库”）
|
||
|
||
| 视图 | 看什么 | 落库去向 |
|
||
|---|---|---|
|
||
| 待审候选 | 候选正文、版本、哈希、状态、所属作品/章 | 候选表（待建，见 08 §3） |
|
||
| 用户决策 | 接受 / 合并 / 丢弃的历史与依据 | 用户决策记录（待建） |
|
||
| 运行回执 | 每次运行的回执、结果摘要、raw 指针 | 运行回执表（待建，见 08 §7） |
|
||
| 模型调用 | 提示词、执行配置、花费 | 模型调用记录表（待建） |
|
||
| raw 全文 | 完整原文、完整问答、标准答案、供应商响应 | raw 表（待建，受 §5 访问控制） |
|
||
| 规划与冻结上下文 | 规划、细纲、冻结上下文清单 | 规划与上下文冻结表（待建） |
|
||
|
||
## 5. raw 全文与访问控制
|
||
|
||
- raw 全文表受访问控制；看板按单用户本地信任，可看全文。
|
||
- 任何视图都**不得显示密钥、token、外部凭据**——库内本就不该有这些，看板再加一层“不渲染”。
|
||
- 看板只服务本机单用户；对外分享、截图不在合同内。
|
||
|
||
## 6. 与现有通道的关系
|
||
|
||
- 看板**不替代** `db` skill。`db` skill 是面向 agent 和主会话的唯一数据库通道（可写可查）；看板是面向人的独立只读渲染面。
|
||
- 看板只读库，不经过会写库的通道；它的存在和死活都不影响创作链。
|
||
|
||
## 7. 看板必须正确呈现的库内约定（防误导）
|
||
|
||
库里现在的数据有几条“坑”，看板必须按实情渲染，不能让人看错：
|
||
|
||
- **型别看 payload，不看 `draft_type` 列**：公共卡的型在 `draft_payload->>'型'`（中文键，如 craft/trope）；作品卡的型在 `draft_payload->>'type'`（英文键，如 character/item）。`draft_type` 列对所有活卡都是 `entity`，不能拿来筛型。
|
||
- **公共 vs 作品看 `work_id`**：`work_id=0` 是公共范式；`work_id=具体书`（深空之影=8）是作品级；辅以 payload 里的「目标库」。
|
||
- **草稿不等于已确认**：`muse_knowledge_entity`、`muse_knowledge_binding` 当前都是 0 行，卡全是 `pending`。看板要如实显示“已确认知识当前为 0”，不能把草稿当已确认。
|
||
- **数字实时查库**，不缓存成快照冒充实时。
|
||
|
||
## 8. 验收条件
|
||
|
||
1. 全模块代码无任何 `INSERT/UPDATE/DELETE`/DDL；只读事务下任何写尝试都报错。
|
||
2. 看板进程挂掉或断网，库内正式内容零影响，创作链不受影响。
|
||
3. §4.1 的每个视图都能从对应表渲染出实时数据。
|
||
4. §4.2 的视图在表未建时显示“无数据 / 待落库”，不报错、不假装已有。
|
||
5. raw 全文视图受访问控制；任何视图都不显示密钥 / token。
|
||
6. 型别与公共/作品归属按 §7 的库内约定正确渲染，不把草稿显示为已确认。
|
||
7. web 层不引入任何 web 框架（纯标准库 HTTP）；数据库驱动仅复用 `.venv` 现成 psycopg 的只读连接。
|
||
|
||
## 9. 待建（实现期，按依赖排序）
|
||
|
||
1. 候选 / 用户决策 / 运行回执 / 模型调用 / raw 全文 / 规划冻结各表——这属于“一切落库”那批实现工作，不是看板本身，但没有它们 §4.2 的视图就是空的。
|
||
2. `db/ddl/96` 授权快照表 apply 入库。
|
||
3. 看板模块本体：只读 HTTP 服务 + 各视图渲染。
|
||
|
||
## 10. 关联 SoT
|
||
|
||
- 数据权威、落库合同、可恢复性：[领域索引](domains/_index.md) §2/§3、[08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)
|
||
- 库内表清单与现状：[`db/表映射.md`](../../../db/表映射.md)
|
||
- 形态参照：open-wenmo（纯标准库 hub + 门禁）
|