338e3a7dbb
- /runs 落地页(运行列表+常驻双维入口+候选决策占位)；/runs/by-work、/runs/by-role 服务端下拉筛选(无JS) - /runs/<run_id> 运行详情：运行信息+回执链(样本·revision哈希链)+质量评判+模型调用+候选与决策，沿来源下钻起点 - do_GET 解析 query 参数；合同 §9 待建清单收敛(运行详情/双维已建成)
226 lines
18 KiB
Markdown
226 lines
18 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。**真门禁是库级只读连接**（写语句被 PostgreSQL 直接拒）；“grep 无写语句”是辅助门，须用 `\bINSERT\b` / `\bUPDATE\b` / `\bDELETE\b` 词边界查（否则 `deleted=false` 里的 DELETE 子串会误报）。
|
||
- **不接会写的通道**：看板不调用 `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` |
|
||
| 授权快照（不启用） | 单用户本地不做多租户授权机制；参考书出处见“参考书与拆书”视图 | 96 不启用（领域索引 §9） |
|
||
|
||
### 4.2 待落库（合同要求、表尚未建/未接通；看板预留视图，暂显示“无数据 / 待落库”）
|
||
|
||
| 视图 | 看什么 | 落库去向 |
|
||
|---|---|---|
|
||
| 待审候选 | 候选正文、版本、哈希、状态、所属作品/章 | 候选表（待建，见 08 §3） |
|
||
| 用户决策 | 接受 / 合并 / 丢弃的历史与依据 | 用户决策记录（待建） |
|
||
| 运行回执 | 每次运行的回执、结果摘要、raw 指针 | `example_run_receipt`（98 已建，写路径未接通，见 08 §7） |
|
||
| 运行列表 | 一次运行的作品 / 触发 / 终态，运行页的索引 | `example_run`（98 已建，写路径未接通） |
|
||
| 质量评判 | 每次检测 / 评分 / 审核 / 实验的结论、分值、量表版本、失败类别 | `example_quality_result`（98 已建，写路径未接通，06 §3/§5） |
|
||
| 模型调用 | 提示词、执行配置、花费 | `example_llm_call`（97 已建，写路径未接通） |
|
||
| 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. 落库表分两类：**运行注册 / 运行回执 / 质量评判（98）与模型调用（97）已建**，但写路径未接通，视图暂空；候选 / 用户决策 / raw 全文 / 规划冻结（99/100/101）尚未建。没有它们 §4.2 的视图就是空的。
|
||
2. `db/ddl/96` 授权快照表**决定不启用**（领域索引 §9，单用户本地不做多租户授权），DDL 留存不 apply。
|
||
3. 看板首版已建成（总览 / 作品 / 知识库 / 智能体 / 运行记录五空间，只读 HTTP + §4.1 部分视图 + 待落库占位格；智能体空间读 102 登记表；运行记录含按作品/按角色双维 + 运行详情下钻）；待建 = 作品/章工作区标签、沿来源下钻链（raw 下钻依赖 101）。页面与信息架构见 §10。
|
||
|
||
## 10. 页面与信息架构（产品形态 SoT）
|
||
|
||
看板有两重定位，都是它存在的理由：
|
||
|
||
- **记录留痕的验收面**：一切输入产出落不落库，看板上一目了然；空白处就是缺口，也就是后续抽取优化要补的地方。
|
||
- **内容与复利原料的浏览面**：作品正文、知识卡、公共范式、运行产出，可浏览、可沿来源下钻。
|
||
|
||
### 10.1 菜单树（对齐 muse 领域布局，五空间）
|
||
|
||
**两条层级原则**（防止把菜单项和详情页混级）：
|
||
|
||
- **菜单项 = 稳定、无参数入口**（列表 / 集合 / 筛选视图），进左侧菜单栏。
|
||
- **详情页 = 从列表下钻**（带 `:id`，依赖上下文），**不进菜单栏**，靠面包屑回退；详情页内用**二级标签**分区。
|
||
|
||
顶级分区**对齐 muse 领域布局**（muse-studio 的「作品 / 知识库 / 智能体」三空间 + 领域索引分区 + 运行记录独立成空间）——按领域看库，不按功能切。
|
||
|
||
**标记**：`▸` 菜单项 · `└→` 详情下钻 · `[标签]` 详情页内二级标签 · 数据源 `✓ 已有` / `◌ 待落库` / `⚠ 需登记`。
|
||
|
||
```text
|
||
1. 总览 / 〔数据权威 08〕 单页
|
||
├─ 落库账本 各承接表：有数/0行/待落库（验收面） ✓
|
||
├─ 四域简要卡 作品·知识库·智能体·运行（点击跳对应空间） ✓
|
||
├─ 额度水位 MiniMax $/24 · 调用/6000 ✓
|
||
└─ 近况 最近运行 ✓ / 最近决策 ◌（决策表未建）
|
||
|
||
2. 作品 /works 〔作品 01〕
|
||
▸ 作品列表 作品表格（标题/状态/类型/字数/在写章）
|
||
└→ 作品工作区 /works/:id 〔二级标签〕
|
||
[章节] ✓
|
||
├─ 在写章节卡 当前进度（next_action/最新章派生）→ 直达章工作区
|
||
└─ 章节列表 序/标题/状态/字数
|
||
└→ 章工作区 /works/:id/ch/:n
|
||
├─ 正文 content_text 全文 ✓
|
||
├─ 本章细纲 该章章级细纲 ◌
|
||
├─ 出场实体卡 本章出场的人物/地点/事件…（时态区间，依赖 02 §7 两套时态对齐） ◌
|
||
├─ 相关范式 本章引用的范式卡 ◌
|
||
├─ 本章候选 针对该章的候选 ◌
|
||
└─ 本章运行 target_chapter=该章 的运行 ✓
|
||
[大纲] 作品大纲（总纲+卷纲） ◌
|
||
[细纲] 章级细纲列表（逐章·草稿/已确认） ◌
|
||
[设定] 作品核心/世界观/力量体系/文风 ◌
|
||
[知识库] → 即 3.3 作品知识（预筛到本作）
|
||
[叙事状态] 作品级叙事状态（as_of 可重建） ◌
|
||
[运行] → 即 5.1 按作品（预筛到本作）
|
||
|
||
3. 知识库 /knowledge 〔实体 02 · 范式 03〕
|
||
▸ 知识库列表 /knowledge muse_knowledge_base（公共范式库/参考书库/作品库） ✓
|
||
└→ 库详情 /knowledge/:kb 该库的卡列表
|
||
▸ 公共范式 /knowledge/public work_id=0 范式卡
|
||
├─ 窗级五型分布 trope/craft/scene_pattern/emotion/combat（style/pacing 书级画像，当前 0） ✓
|
||
├─ 按型分面卡列表 ✓
|
||
└→ 范式卡详情 名称/摘要/写法要点/适用条件/例证出处/来源 ✓
|
||
▸ 作品知识 /knowledge/works 〔页内作品选择器〕
|
||
├─ 实体卡（九型分面） character/character_relation/event/location/item/
|
||
│ faction/power_system/world/narrative_state ✓
|
||
├─ 作品范式（六型） work_id=本作 ✓
|
||
├─ 草稿 vs 已确认（现状已确认≈0，如实标注） ✓
|
||
└→ 实体卡详情 字段/时态区间/来源/revision；范式卡详情 ✓
|
||
▸ 参考书·拆书·清洗 /knowledge/refs
|
||
├─ 参考书档案 ✓ └→ 参考书详情（分章/逐章脚手架/窗级大纲/清洗记录）
|
||
├─ 拆书任务（章×两阶段状态） ✓
|
||
└─ 清洗审计（批次/理由/模型/删了几处） ✓
|
||
▸ 结构本体 /knowledge/meta 〔框架视图·次要〕 23型/字段/aiContext/保护节点/功能链 ✓
|
||
|
||
4. 智能体 /agents 〔Agent 07〕
|
||
▸ 角色 /agents 5 角色卡（writer/planner/extractor/detector/judge）
|
||
└→ 角色详情 /agents/:role
|
||
├─ 角色画像 职责/模型归属 ⚠（登记表）
|
||
├─ 可配置项 model/effort/预算/工具 ⚠（登记表）
|
||
├─ 本角色运行 run_receipt.adapter_role=该角色 ✓
|
||
├─ 本角色调用 llm_call.caller=该角色 ✓
|
||
└─ 本角色质量评判 ✓
|
||
▸ 技能 /agents/skills 24 skill 清单
|
||
└→ 技能详情 /agents/skills/:name
|
||
├─ 技能画像 目的/用法/红线 ⚠（登记表）
|
||
├─ 读写合同 读/写哪些表 ⚠（登记表）
|
||
└─ 调用情况 ✓
|
||
|
||
5. 运行记录 /runs 〔流程 05 · 质量 06〕
|
||
▸ 按作品看运行 /runs/by-work 〔作品选择器〕 ✓
|
||
▸ 按角色看运行 /runs/by-role 〔角色选择器〕 ✓
|
||
└→ 运行详情 /runs/:run_id
|
||
├─ 运行信息 触发/作品/章/终态/起止 ✓
|
||
├─ 回执链 各 revision + 哈希链 + 阶段 ✓
|
||
├─ 质量评判 检测/评分/审核/实验 + 量表版本 ✓
|
||
├─ 候选与决策 待审候选 + 用户决策 ◌
|
||
├─ 模型调用 调用方/模型/token/成本 ✓
|
||
└─ raw 下钻 全文（访问控制） ◌
|
||
▸ 写命令审计 /runs/commands 〔次要〕 muse_content_command_log（写命令幂等） ✓
|
||
```
|
||
|
||
**跨空间互联**（一处看全、处处能跳）：
|
||
|
||
| 从 | 到 | 连接键 |
|
||
|---|---|---|
|
||
| 作品工作区[知识库] | 3.3 作品知识 | 预筛 `work_id` |
|
||
| 作品工作区[运行] | 5.1 按作品 | 预筛 `work_id` |
|
||
| 章工作区·出场卡 | 3.3 实体卡详情 | source / 时态区间 |
|
||
| 章工作区·相关范式 | 3.2/3.3 范式卡详情 | 冻结上下文指针 |
|
||
| 运行详情·候选 | 章工作区·本章候选 | `candidate.target_chapter` |
|
||
| 角色详情·运行 | 5.2 按角色 | `adapter_role` |
|
||
| 公共范式卡 | 来源参考书 | `source_type/source_id` → 3.4 |
|
||
|
||
**智能体页的 ⚠ 来源（A 方案，2026-07-30 拍板）**：角色画像 / 可配置项 / 技能合同在 Git 侧（`.claude/agents/`、`.claude/skills/`），库里没有。看板只读库，故新增**智能体/技能登记表**（`example_agent_role` + `example_skill`，设计见落库设计稿），把角色、模型归属、可配置项、技能读写合同**登记入库**——智能体配置也纳入留痕，看板只读这张表。
|
||
|
||
**分阶段点亮（认）**：首版实现为五空间（总览 / 作品 / 知识库 / 智能体 / 运行记录；智能体空间读 102 登记表 `example_agent_role`/`example_skill`，登记表由 `db/scripts/sync_agent_registry.py` 从 Git 侧同步，Git 仍是配置权威）。作品工作区**先上 [章节]**（正文已有），其余标签（大纲/细纲/设定/叙事状态、章工作区的细纲与出场卡）随对应表落库（规划表、候选表，落库设计稿第 3/2 步）逐格点亮；点亮前显示"待落库"占位，不假装已有。
|
||
|
||
### 10.2 UI 形态
|
||
|
||
- 纯标准库 HTTP 服务端渲染 HTML（§3），相对路径 + 注入 base（仿 open-wenmo hub），无 SPA 框架。
|
||
- 布局：左侧顶级导航（§10.1 五个领域空间，各项标注对应领域，顶级项下缩进列出二级子菜单）+ 主区。列表页 = 表格 + 分面过滤 + 分页；详情下钻页**不进菜单**、顶部显示面包屑（如 `作品 / 深空之影 / 第 5 章`），页内用二级标签分区（作品工作区 / 章工作区）；正文 = 可读排版；raw = 等宽全文 + 访问控制提示。
|
||
- 交互只有两类：只读浏览、沿来源下钻。**无任何写操作**（§2 硬约束）；接受 / 丢弃仍走 `confirm` skill。
|
||
- 过滤 / 搜索用 query 参数、服务端渲染；每次请求实时查库，不缓存（§7）。
|
||
|
||
### 10.3 信息披露的重点（怎么组织、为什么）
|
||
|
||
1. **核心交互是“沿来源下钻”**：任何内容 → 它的候选 → 运行 → 模型调用 → raw。这是数据库看板相对“看文件”的唯一独特价值，所以是首要重点。作品页的每章每卡、运行页的每条回执，都带这条下钻链。
|
||
2. **如实优先于好看**：0 行就显示 0（`muse_knowledge_entity` / `binding` 当前 0 行），待落库就灰显“待落库”，草稿≠已确认明确标注（§7）。看板是验收面，不是营销页。
|
||
3. **留痕完整性是一等公民**：首页健康面 + 每个 §4.2 空视图都在提示“这里还没记录”。先看到缺什么，才知道优化什么——直接服务“后续抽取优化”。
|
||
4. **公共范式要可挖掘**：近万张公共卡是复利原料，给分面浏览（型 / 状态 / 搜索）和分布图，不给逐条死列表。
|
||
|
||
### 10.4 其他可视化场景（已纳入 / 暂缓）
|
||
|
||
- 已纳入：输入侧（参考书·拆书·清洗）、运营侧（额度水位）、落库健康（首页账本）、结构本体（知识库空间次级）、智能体/技能登记（智能体空间，读登记表）。
|
||
- 次要、暂不上树：升级审计（`db/ddl/94` 五表）、导入审计（`muse_content_import_task`）——属审计面，需要时再给入口。
|
||
- 暂缓（二期，依赖待落库表）：质量与复利的跨运行聚合（评分趋势 / 经验升格观察，是视图层）。
|
||
|
||
## 11. 关联 SoT
|
||
|
||
- 数据权威、落库合同、可恢复性：[领域索引](domains/_index.md) §2/§3、[08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)
|
||
- 库内表清单与现状：[`db/表映射.md`](../../../db/表映射.md)
|
||
- 形态参照：open-wenmo（纯标准库 hub + 门禁）
|