4adc85cafd
- 八个领域 SoT + 索引：正式内容权威从 Git 文件改为 PostgreSQL；Git 退回代码/文档/DDL 权威，可对作品信息与文本留痕但非权威。 - 立横切合同：一切输入产出必须落库可见；raw 进库可看全文（访问控制）。 - 08 更名为数据权威与可视化领域；新增独立 可视化模块合同（只读查库渲染，绝不写）。 - AGENTS.md / README.md 同步翻面。
7.6 KiB
7.6 KiB
只读可视化模块合同
本文件是只读可视化模块（下称“看板”）的设计 SoT。数据权威、落库原则和可恢复性见 领域索引 §2/§3 与 08-数据权威与可视化领域；本文件只定义看板这个只读模块本身。库内有哪些表、各表现状以
db/表映射.md为准。
1. 它是什么，不做什么
看板是一个本地 web 页面，把 muse-example 库里的状态随时渲染给你看。
- 它只干两件事：对库做只读查询，把结果渲染成人能读的页面。
- 它绝不触发任何写操作。接受、合并、丢弃、确认这些写，仍由
confirmskill 和主会话走，看板只展示结果。 - 它看到的 = 库里的。看板上空白的地方，就是落库的缺口——所以看板天然是“一切输入产出必须落库”这条纪律的验收面。
- 它服务本机单用户，不做多用户、权限管理、对外分享。
2. 只读硬约束（怎么保证它绝不写）
这是看板的命根子，验收时按机械门查：
- 连接只读：看板用独立的只读连接，默认事务只读（
SET TRANSACTION READ ONLY或库侧只读角色）；连接串与写通道（dbskill）分开。 - 代码无写语句：全模块只允许
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. 与现有通道的关系
- 看板不替代
dbskill。dbskill 是面向 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. 验收条件
- 全模块代码无任何
INSERT/UPDATE/DELETE/DDL；只读事务下任何写尝试都报错。 - 看板进程挂掉或断网，库内正式内容零影响，创作链不受影响。
- §4.1 的每个视图都能从对应表渲染出实时数据。
- §4.2 的视图在表未建时显示“无数据 / 待落库”，不报错、不假装已有。
- raw 全文视图受访问控制；任何视图都不显示密钥 / token。
- 型别与公共/作品归属按 §7 的库内约定正确渲染，不把草稿显示为已确认。
- web 层不引入任何 web 框架（纯标准库 HTTP）；数据库驱动仅复用
.venv现成 psycopg 的只读连接。
9. 待建（实现期，按依赖排序）
- 候选 / 用户决策 / 运行回执 / 模型调用 / raw 全文 / 规划冻结各表——这属于“一切落库”那批实现工作，不是看板本身，但没有它们 §4.2 的视图就是空的。
db/ddl/96授权快照表 apply 入库。- 看板模块本体：只读 HTTP 服务 + 各视图渲染。
10. 关联 SoT
- 数据权威、落库合同、可恢复性：领域索引 §2/§3、08-数据权威与可视化领域
- 库内表清单与现状：
db/表映射.md - 形态参照：open-wenmo（纯标准库 hub + 门禁）