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

只读可视化模块合同

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

1. 它是什么，不做什么

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

• 它只干两件事：对库做只读查询，把结果渲染成人能读的页面。
• 它绝不触发任何写操作。接受、合并、丢弃、确认这些写，走独立可写通道：
  • 候选采纳/丢弃：dashboard/decision_channel.py（默认 :8767）→ decide-candidate / write_canonical
  • 经验升格人审：dashboard/lesson_confirm.py（默认 :8766）
  • 不得把写操作做进只读看板进程（:8765）
• 它看到的 = 库里的。看板上空白的地方，就是落库的缺口——所以看板天然是“一切输入产出必须落库”这条纪律的验收面。
• /ai-flavor 也是数据库视图：默认读取 AI 味案例卡与重验证账本表，页面明确标注“候选命中，不是确认结论”；只有数据库不可用时才显示 dashboard/fixtures/ 中的离线 JSON 回退及原因。其余视图同样以数据库为权威。
• 它服务本机单用户，不做多用户、权限管理、对外分享。

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

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

• 连接只读：看板用 muse_db.connect(readonly=True) 开独立只读会话（会话级 default_transaction_read_only=on，写语句被 PostgreSQL 直接拒）。禁止调用 access-database 的可写 CLI 或任何会写库的 Skill。
• 代码无写语句：全模块只允许 SELECT，不得出现任何 INSERT/UPDATE/DELETE 或 DDL。真门禁是库级只读连接（写语句被 PostgreSQL 直接拒）；“grep 无写语句”是辅助门，须用 \bINSERT\b / \bUPDATE\b / \bDELETE\b 词边界查（否则 deleted=false 里的 DELETE 子串会误报）。
• 不接会写的通道：看板不调用 decide-candidate 或任何会写库的 Skill，只自己读库。
• 挂了不牵连：看板进程崩了、断网了，库内正式内容和创作链不受任何影响。

2.1 双通道合同（只读看板 + 可写决策）

通道	端口	进程	能力
只读看板	:8765	dashboard/server.py	仅 SELECT 渲染；展示决策菜单文案与命令，不执行
经验确认	:8766	dashboard/lesson_confirm.py	lesson review / promote / reject
候选决策	:8767	dashboard/decision_channel.py	候选 accept / discard → write_canonical

三条进程物理隔离：可写进程挂了不影响看板；看板进程永不 import 写路径。人在只读页看到「可采纳」后，跳到 :8767 点按钮落库。

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 写）；看板只读 /lessons；人审写库走确认通道 :8766
候选人审决策（可写通道）	采纳 / 丢弃按钮 → write_canonical	dashboard/decision_channel.py（默认 :8767）；不进只读看板进程

4.2 待落库 / 待建视图

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

仍待建的是消费侧：

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

5. raw 全文与访问控制

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

6. 与现有通道的关系

• 看板不替代 access-database Skill。后者是面向 agent 和主会话的可写 CLI 通道；连接实现由共享运行时包 muse_db 提供。看板经 connect(readonly=True) 读库，不经会写的 CLI。
• 额度窗上限（MiniMax $24 / 全模型 6000 次）与 muse_llm 共用 muse_db.WINDOW_BUDGET_USD / WINDOW_CALL_CAP，看板只展示账本水位，不 import muse_llm。
• 看板只读库，不经过会写库的通道；它的存在和死活都不影响创作链。

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、状态、人工标签、来源许可、全文/命中哈希、行/字符位置、重验证状态、当前用途和作用域；页面只读，不触发重验证。

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 侧（.agent/agents/、.agent/skills/），库里没有。看板只读库，故新增智能体/技能登记表（example_agent_role + example_skill，设计见落库设计稿），把角色、模型归属、可配置项、技能读写合同登记入库——智能体配置也纳入留痕，看板只读这张表。

分阶段点亮（认）：首版实现为六空间（总览 / 作品 / 知识库 / 质量证据 / 智能体 / 运行记录，见 §9.3；智能体空间读 102 登记表 example_agent_role/example_skill，登记表由 .agent/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 硬约束）；接受 / 丢弃走可写决策通道 :8767，经验升格走 :8766。
• 过滤 / 搜索用 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

• 数据权威、落库合同、可恢复性：领域索引 §2/§3、08-数据权威与可视化领域
• 库内表清单与现状：db/表映射.md
• 形态参照：open-wenmo（纯标准库 hub + 门禁）