muse-agent-example/.agent/docs/architecture/可视化模块合同.md

# 只读可视化模块合同

> 本文件是只读可视化模块（下称“看板”）的设计 SoT。数据权威、落库原则和可恢复性见 [领域索引](domains/_index.md) §2/§3 与 [08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)；本文件只定义看板这个**只读**模块本身。库内有哪些表、各表现状以 [`db/表映射.md`](../../../db/表映射.md) 为准。

## 1. 它是什么，不做什么

看板是一个本地 web 页面，把 `muse-example` 库里的状态随时渲染给你看；质量证据的离线 JSON 只作为数据库不可用时的明确回退。

- 它只干两件事：对库做**只读查询**，把结果渲染成人能读的页面。
- 它**绝不触发任何写操作**。接受、合并、丢弃、确认这些写，仍由 `decide-candidate` Skill 和主会话走，看板只展示结果。
- 它看到的 = 库里的。看板上空白的地方，就是落库的缺口——所以看板天然是“一切输入产出必须落库”这条纪律的验收面。
- `/ai-flavor` 也是数据库视图：默认读取 AI 味案例卡与重验证账本表，页面明确标注“候选命中，不是确认结论”；只有数据库不可用时才显示离线回退及原因。其余视图同样以数据库为权威。
- 它服务本机单用户，不做多用户、权限管理、对外分享。

## 2. 只读硬约束（怎么保证它绝不写）

这是看板的命根子，验收时按机械门查：

- **连接只读**：看板用独立的只读连接，默认事务只读（`SET TRANSACTION READ ONLY` 或库侧只读角色）；连接串与写通道（`access-database` Skill）分开。
- **代码无写语句**：全模块只允许 `SELECT`，不得出现任何 `INSERT/UPDATE/DELETE` 或 DDL。**真门禁是库级只读连接**（写语句被 PostgreSQL 直接拒）；“grep 无写语句”是辅助门，须用 `\bINSERT\b` / `\bUPDATE\b` / `\bDELETE\b` 词边界查（否则 `deleted=false` 里的 DELETE 子串会误报）。
- **不接会写的通道**：看板不调用 `decide-candidate` 或任何会写库的 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` |
| AI 味案例回填 | 作品扫描的候选命中、来源哈希/位置、Shadow 状态和复核详情 | `example_ai_flavor_case`（检测命令自动写入） |
| AI 味案例来源重验证 | 当前来源是否仍与案例卡的哈希/位置一致，以及 stale/unavailable/mismatch 结果 | `example_ai_flavor_revalidation_batch` + `example_ai_flavor_revalidation`（append-only） |
| 授权快照（不启用） | 单用户本地不做多租户授权机制；参考书出处见“参考书与拆书”视图 | 96 不启用（领域索引 §9） |
| 待审候选 | 候选正文、版本、哈希、机械/语义状态、所属作品/章 | `example_candidate`（生产链 `persist_writer_execution` 落候选，`write_canonical` 翻 accepted/discarded） |
| 候选 CAS 状态链 | 每次生产运行的 DRAFT/CHECKING/PASSED/REJECTED 迁移与 revision | `example_candidate_cas`（109，生产编排实时写） |
| 用户决策 | 接受 / 合并 / 丢弃的历史与依据 | `example_user_decision`（`write_canonical` 单事务 append-only 归档） |
| 运行列表 / 回执 / 质量评判 | 一次运行的作品/触发/终态；逐段身份回执；机械/语义检测结论 | `example_run` / `example_run_receipt` / `example_quality_result`（98，生产与评测写路径已接通） |
| 模型调用 / raw 全文 | 逐次调用的模型/花费/提示词哈希；完整输入输出与供应商响应 | `example_llm_call`（97）/ `example_raw_content`（101，`record-run-evidence` 随调用原子落库） |
| 规划与冻结上下文 | 规划、细纲、冻结上下文清单与授权快照 | `example_planning_section` / `example_context_freeze`（100，`persist_planning` / `persist_freeze` 写） |
| 事实增量 | 候选提出的类型化增量（proposed/accepted/rejected）与已进账本的变更流 | `example_fact_delta` / `example_fact_ledger`（106，接受候选同事务写入） |
| 投影登记 | 摘要/抽取/embedding 等投影的 pending/completed/failed/stale 与重试 | `example_projection_run`（107，接受候选同事务登记） |
| 经验升格 | lesson/win 证据与 proposed→reviewing→promoted/rejected 流转 | `example_lesson`（108，`lesson_registry` 写） |

### 4.2 待落库 / 待建视图

数据面：上表所列各表均已建表且写路径接通，无“表未建”项。

仍待建的是**消费侧**：

| 项 | 现状 |
|---|---|
| 上述新表（候选/CAS/决策/事实增量/投影/经验）的看板渲染视图 | 看板首版只有总览/作品/知识库/运行记录四空间，新视图待画 |
| 投影的异步执行 worker | 接受时只登记 pending 投影，执行与重建调度未建（合同见 `projection_registry`） |

## 5. raw 全文与访问控制

- raw 全文表受访问控制；看板按单用户本地信任，可看全文。
- 任何视图都**不得显示密钥、token、外部凭据**——库内本就不该有这些，看板再加一层“不渲染”。
- 看板只服务本机单用户；对外分享、截图不在合同内。

## 6. 与现有通道的关系

- 看板**不替代** `access-database` 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 部分视图 + 待落库占位格；AI 味案例查 104 三表；智能体空间读 102 登记表；运行记录含按作品/按角色双维 + 运行详情下钻）；待建 = 作品/章工作区标签、沿来源下钻链（raw 下钻依赖 101）。页面与信息架构见 §10。

## 10. 页面与信息架构（产品形态 SoT）

看板有两重定位，都是它存在的理由：

- **记录留痕的验收面**：一切输入产出落不落库，看板上一目了然；空白处就是缺口，也就是后续抽取优化要补的地方。
- **内容与复利原料的浏览面**：作品正文、知识卡、公共范式、运行产出，可浏览、可沿来源下钻。

### 10.1 菜单树（对齐 muse 领域布局，六空间）

**两条层级原则**（防止把菜单项和详情页混级）：

- **菜单项 = 稳定、无参数入口**（列表 / 集合 / 筛选视图），进左侧菜单栏。
- **详情页 = 从列表下钻**（带 `:id`，依赖上下文），**不进菜单栏**，靠面包屑回退；详情页内用**二级标签**分区。

顶级分区**对齐 muse 领域布局**（muse-studio 的「作品 / 知识库 / 智能体」三空间 + 领域索引分区 + 运行记录独立成空间）——按领域看库，不按功能切。

**标记**：`▸` 菜单项 · `└→` 详情下钻 · `[标签]` 详情页内二级标签 · 数据源 `✓ 已有` / `◌ 待落库` / `⚠ 需登记`。

AI 味案例的固定入口是 `/ai-flavor`。列表按作品、模式分页，卡片详情显示卡 ID、状态、人工标签、来源许可、全文/命中哈希、行/字符位置、重验证状态、当前用途和作用域；页面只读，不触发重验证。

```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. 质量证据 /ai-flavor  〔质量 06 · 数据库〕
   ▸ AI 味案例回填     作品/模式筛选、候选卡分页、来源锚点详情；只显示 hash/位置，不显示未授权原文

5. 智能体 /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
           ├─ 技能画像   目的/用法/红线 ⚠（登记表）
           ├─ 读写合同   读/写哪些表 ⚠（登记表）
           └─ 调用情况 ✓

6. 运行记录 /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`，设计见落库设计稿），把角色、模型归属、可配置项、技能读写合同**登记入库**——智能体配置也纳入留痕，看板只读这张表。

**分阶段点亮（认）**：首版实现为六空间（总览 / 作品 / 知识库 / 质量证据 / 智能体 / 运行记录，见 §9.3；智能体空间读 102 登记表 `example_agent_role`/`example_skill`，登记表由 `.claude/skills/access-database/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 硬约束）；接受 / 丢弃仍走 `decide-candidate` 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 + 门禁）