框架(设计): 立落库与看板设计稿，看板菜单树重订为领域布局，清理不启用96残留

- 新增 docs/2026-07-30 落库与看板设计稿：97-102 表设计(含 102 智能体/技能登记表 A 方案)、写路径、raw 合同、实施顺序 - 可视化合同 §10 重写为领域布局菜单树(五空间+作品工作区+章工作区+跨空间互联+数据来源标注+分阶段点亮) - 清理'不启用 96'残留：合同§9、02/04/08 领域、落库稿统一改为不启用/以 reference_work 为准 - 03 范式补 draft_type 现状标注；_index §4 零依赖口径对齐合同；08 §9/§10 状态收敛
2026-07-31 00:31:16 +08:00 · 2026-07-31 00:31:16 +08:00 · 63a65ae9ff
commit 63a65ae9ff
parent eeac03373c
7 changed files with 411 additions and 17 deletions
--- a/.agent/docs/architecture/domains/02-实体领域.md
+++ b/.agent/docs/architecture/domains/02-实体领域.md
@ -72,7 +72,7 @@
 - **跨窗出场留档**：人物在长篇里分窗（按窗口切分的大段）出现，逐窗记录其出场与状态变化，留作证据。
 - **覆写审计**：每次抽取或覆写都留痕，能追溯“这条卡是谁、何时、依据哪段原文写进来的”。
 - **灾备导出**：正式层可导出，配合数据库备份用于恢复。
- 参考作品的授权与来源以授权快照表为准（`db/ddl/96-example参考作品授权快照.sql`）。
+- 参考作品的出处与导入信息以 `example_reference_work` / `muse_knowledge_document` 为准（领域索引 §9：不做多租户授权机制，96 授权快照不启用）。

 > 注意区分两个“升格”：本节是**作品面实体升格**——把参考书的人物/关系抽进库的正式层。06 质量与复利领域的“经验升格”是另一件事——把写法经验从写法→范式→Skill 逐级固化。两者只是都叫“升格”，对象和去向完全不同，不要混为一谈。作品面升格对应实现：upgrade skill 加 `db/ddl/94-example作品面升格.sql`。

@ -123,7 +123,7 @@
 - 拆书与作品面实体入库管线（抽取、别名判重、跨窗留档、覆写审计）。
 - review-cards 三角色审核（番茄作家 / 起点作家 / 主编）作为拆书常设步骤。
 - `aiContext` 字段级用途裁剪（按用途只取需要的字段）。
- 参考作品授权快照表（`db/ddl/96`）。
+- 参考作品授权快照表（`db/ddl/96`）：**决定不启用**（领域索引 §9），DDL 留存不 apply。

 待建（目标合同，尚未跑通）：

--- a/.agent/docs/architecture/domains/03-范式领域.md
+++ b/.agent/docs/architecture/domains/03-范式领域.md
@ -22,7 +22,7 @@
 一张范式卡至少由这些库内字段说清楚：

 - `work_id`：0 为公共，非 0 为作品级，决定这张卡的适用范围。
- `draft_type`：范式型，取六个范式型之一。
+- `draft_type`：范式型，取六个范式型之一。**现状**：库内活卡 `draft_type` 恒为 `entity`、无区分力；型在 `draft_payload` 中文键「型」（公共卡）/ 英文键 `type`（作品卡），见可视化合同 §7；目标合同待对齐。
 - `draft_payload`（JSONB）：至少含 `名称`、`一句话摘要`、`标签`、`来源`（手工 / 抽取@第N章 / 拆书@书名），以及该型在 `meta/schemas` 定义的特有字段（如通用桥段的场景类型、目标结构、推进机制、例证出处）。
 - `status`：库内状态字段。现状取值是“待确认 → 确认 / 丢弃”，见第 4 节。
 - `confidence`：可信度，供召回排序参考，不单独决定卡是否成立。
--- a/.agent/docs/architecture/domains/04-上下文领域.md
+++ b/.agent/docs/architecture/domains/04-上下文领域.md
@ -47,7 +47,7 @@
 数据库读取器是本领域的核心实现，对齐 [`read-context`](../../../../.claude/skills/read-context/SKILL.md) 现状：从库读可信来源、冻结、再投影。它必须能够：

 1. 从库中枚举作品、实体和范式，按 ID、类型、名称、别名、scope、scenario 和章号过滤。
-2. 解析库内 schema 与来源授权快照，确认每条来源可被本次任务合法读取。
+2. 解析库内 schema 并确认来源可溯（来源能回到已导入参考书或作品自身正式内容）；不做多租户授权快照重验（96 不启用，领域索引 §9），确认每条来源可被本次任务合法读取。
 3. 对选中内容计算稳定哈希：先剔除运行期易变字段，再对规范化后的 JSON 求哈希（`retrieval_identity`），保证同一内容不因无关字段变动而改变身份。
 4. 在固定排序和预算下产生可重复的冻结清单（manifest）；排序规则固定为按相似度分降序、版本升序、来源升序、偏移升序，同样输入必得同样来源集合与哈希。
 5. 按指针回读库行（在只读、可重复读事务中按 `sourceId` / `sourceVersion` 取正式内容行），构造角色投影。
--- a/.agent/docs/architecture/domains/08-数据权威与可视化领域.md
+++ b/.agent/docs/architecture/domains/08-数据权威与可视化领域.md
@ -130,16 +130,16 @@ raw 指不适合直接当正文、但需要留存可查的完整材料：完整
 - `runtime`：不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）。
 - 额度账本：`db/ddl/95-example额度账本.sql`。
 - 清洗日志：`db/ddl/92-example清洗日志.sql`。
- 参考作品授权快照：`db/ddl/96-example参考作品授权快照.sql`。
+- 参考作品授权快照：`db/ddl/96-example参考作品授权快照.sql`（**决定不启用**，领域索引 §9；DDL 留存不 apply）。
 - `import` skill：参考书 / 旧稿导入落库。

 ## 10. 待建（目标合同）

 以下为当前尚未满足、但属于本领域目标合同的缺口：

- 一切输入产出落库的缺失项：候选正文、用户决策、运行回执、补证记录、模型调用提示词的库内落库尚未全部接通。
- 只读可视化看板模块本身。
- raw 全文进库的表与访问控制。
+- 一切输入产出落库：运行注册 / 回执 / 质量评判 / 模型调用明细表已建（97/98），写路径未接通；候选正文、用户决策、补证记录、规划与冻结（99/100）尚未建。
+- 只读可视化看板：首版已建（总览/作品/知识库/运行记录四空间）；运行详情下钻、智能体空间、工作区标签待建。
+- raw 全文进库的表与访问控制（101）。
 - DB 备份与重建脚本。

 ## 11. 验收条件
--- a/.agent/docs/architecture/domains/_index.md
+++ b/.agent/docs/architecture/domains/_index.md
@ -31,7 +31,7 @@

 ## 4. 只读可视化模块

- 一个纯 Python 标准库的本地 web 看板，零 pip 依赖，内网或 Tailscale 访问，形态参照 open-wenmo。
+- 一个纯 Python 标准库的本地 web 看板（web 层零框架、零新增依赖；psycopg 复用 `.venv` 现成的，非标准库），内网或 Tailscale 访问，形态参照 open-wenmo。
 - 只对数据库做只读查询并渲染，**不触发任何写操作**；接受、丢弃等写操作仍由 `confirm` skill 和主会话走，看板只展示结果。
 - 它看到的内容等于库里的内容，因此它倒逼第 3 条“一切落库”。
 - 合同细节见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
@ -87,6 +87,7 @@
 - 不实现管理员控制台、租户、角色权限、市场、计费、资产交易或多用户协作。
 - 不复制父仓完整业务有界上下文。
 - 可视化模块不写库。
+- 不做多租户参考书授权机制：`db/ddl/96` 授权快照表**不启用**（单用户本地，授权人/使用者/机器是同一人，重型授权合规是从父仓过度继承）；参考书出处与导入信息用 `example_reference_work` / `muse_knowledge_document` 即可（2026-07-30 拍板）。
 - 不再声称 Git 是正式内容权威，也不再承诺“删库零丢失”或“本地文件模式必选”。

 ## 10. 上级 SoT
--- a/.agent/docs/architecture/可视化模块合同.md
+++ b/.agent/docs/architecture/可视化模块合同.md
@ -16,7 +16,7 @@
 这是看板的命根子，验收时按机械门查：

 - **连接只读**：看板用独立的只读连接，默认事务只读（`SET TRANSACTION READ ONLY` 或库侧只读角色）；连接串与写通道（`db` skill）分开。
- **代码无写语句**：全模块只允许 `SELECT`，不得出现任何 `INSERT/UPDATE/DELETE` 或 DDL。审查以“grep 全代码无写语句”为门。
+- **代码无写语句**：全模块只允许 `SELECT`，不得出现任何 `INSERT/UPDATE/DELETE` 或 DDL。**真门禁是库级只读连接**（写语句被 PostgreSQL 直接拒）；“grep 无写语句”是辅助门，须用 `\bINSERT\b` / `\bUPDATE\b` / `\bDELETE\b` 词边界查（否则 `deleted=false` 里的 DELETE 子串会误报）。
 - **不接会写的通道**：看板不调用 `confirm` 或任何会写库的 skill，只自己读库。
 - **挂了不牵连**：看板进程崩了、断网了，库内正式内容和创作链不受任何影响。

@ -40,7 +40,7 @@
 | 额度账本 | 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**） |
+| 授权快照（不启用） | 单用户本地不做多租户授权机制；参考书出处见“参考书与拆书”视图 | 96 不启用（领域索引 §9） |

 ### 4.2 待落库（合同要求、表尚未建/未接通；看板预留视图，暂显示“无数据 / 待落库”）

@ -48,8 +48,10 @@
 |---|---|---|
 | 待审候选 | 候选正文、版本、哈希、状态、所属作品/章 | 候选表（待建，见 08 §3） |
 | 用户决策 | 接受 / 合并 / 丢弃的历史与依据 | 用户决策记录（待建） |
-| 运行回执 | 每次运行的回执、结果摘要、raw 指针 | 运行回执表（待建，见 08 §7） |
-| 模型调用 | 提示词、执行配置、花费 | 模型调用记录表（待建） |
+| 运行回执 | 每次运行的回执、结果摘要、raw 指针 | `example_run_receipt`（98 已建，写路径未接通，见 08 §7） |
+| 运行列表 | 一次运行的作品 / 触发 / 终态，运行页的索引 | `example_run`（98 已建，写路径未接通） |
+| 质量评判 | 每次检测 / 评分 / 审核 / 实验的结论、分值、量表版本、失败类别 | `example_quality_result`（98 已建，写路径未接通，06 §3/§5） |
+| 模型调用 | 提示词、执行配置、花费 | `example_llm_call`（97 已建，写路径未接通） |
 | raw 全文 | 完整原文、完整问答、标准答案、供应商响应 | raw 表（待建，受 §5 访问控制） |
 | 规划与冻结上下文 | 规划、细纲、冻结上下文清单 | 规划与上下文冻结表（待建） |

@ -85,11 +87,138 @@

 ## 9. 待建（实现期，按依赖排序）

-1. 候选 / 用户决策 / 运行回执 / 模型调用 / raw 全文 / 规划冻结各表——这属于“一切落库”那批实现工作，不是看板本身，但没有它们 §4.2 的视图就是空的。
-2. `db/ddl/96` 授权快照表 apply 入库。
-3. 看板模块本体：只读 HTTP 服务 + 各视图渲染。
+1. 落库表分两类：**运行注册 / 运行回执 / 质量评判（98）与模型调用（97）已建**，但写路径未接通，视图暂空；候选 / 用户决策 / raw 全文 / 规划冻结（99/100/101）尚未建。没有它们 §4.2 的视图就是空的。
+2. `db/ddl/96` 授权快照表**决定不启用**（领域索引 §9，单用户本地不做多租户授权），DDL 留存不 apply。
+3. 看板首版已建成（总览 / 作品 / 知识库 / 运行记录四空间，只读 HTTP + §4.1 部分视图 + 待落库占位格）；待建 = 运行记录的分维列表与运行详情下钻、智能体空间（读 102 登记表）、作品/章工作区标签、沿来源下钻链。页面与信息架构见 §10。

-## 10. 关联 SoT
+## 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 登记表建好后上）。作品工作区**先上 [章节]**（正文已有），其余标签（大纲/细纲/设定/叙事状态、章工作区的细纲与出场卡）随对应表落库（规划表、候选表，落库设计稿第 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)
--- a/docs/2026-07-30-落库与看板设计.md
+++ b/docs/2026-07-30-落库与看板设计.md
@ -0,0 +1,264 @@
+# 落库与看板设计 v2（八张待落库表 + 只读看板）
+
+> 目标读者：创始人。状态：**设计待审（已吸收四路评审），未动代码**。
+> 任务：把"一切输入产出必须落库可见"落成具体的表、写路径与只读看板。
+> SoT 去向：本文件是**任务设计**，不是长期 SoT。实现后蒸馏进三处——表结构进 `db/ddl/`、表清单与约定进 `db/表映射.md`、"哪些输入产出进哪类表"进领域文档（08 §3/§7、01、05、04、06）——届时本文件删除。设计期间这三处不提前改，避免把还没建的表写成既成事实。
+> v2 相对 v1：吸收四路评审（逻辑闭环 / 可实现性 / 合理性 / SoT 父仓一致性）。表从 6 张增至 8 张（新增运行注册 `example_run`、质量结果 `example_quality_result`）；改正来源追溯方向与上下文哈希连接；raw 改靠访问控制；质量评判本期记录可见。
+
+## 1. 背景与口径
+
+- 数据权威已翻成 PostgreSQL（`muse-example` 库）为正式内容权威，Git 退回代码与文档的家并可留痕。见 [08-数据权威与可视化领域](../.agent/docs/architecture/domains/08-数据权威与可视化领域.md)。
+- 落库原则唯一 owner 是 [领域索引 §3](../.agent/docs/architecture/domains/_index.md)；看板合同唯一 owner 是 [可视化模块合同](../.agent/docs/architecture/可视化模块合同.md)。本设计不重复二者，只把它们落成具体表与写路径。
+- **这套东西的两重定位**：记录留痕的验收面（空白处就是缺口，也是后续抽取优化要补的地方）+ 内容与复利原料的浏览面。
+- **诚实的工作量判断**：建表不是主体，真正的成本在写路径改造。其中 raw 进库（§4）、正文 Canonical 写入层（§2.9）不是"改现有写点"，是新建组件或重定义安全合同；planner 落库（§2.6）是从零建一条管线。第 2/3/4 步工作量按此估计，不当成顺手事。
+
+**本设计覆盖 08 §3 落库合同表的哪些行、其余在哪挂起**（回应"一切落库是否全闭合"）：
+
+| 08 §3 输入产出类 | 本设计承接 |
+|---|---|
+| 作品/章/正文（正式） | 现有 `muse_content_*`；写入层见 §2.9 |
+| 实体/关系/叙事状态/世界规则 | 现有 `muse_knowledge_*`（双轨） |
+| 范式 | 现有 `muse_knowledge_draft`（work_id=0） |
+| 用户意图、规划、细纲、冻结上下文、范式选择 | `example_planning_section` + `example_context_freeze`（§2.6）；**用户意图全文本期不单列，随运行触发记入 `example_run.trigger_source`/`trigger_detail`，挂起更完整的意图档案于 05** |
+| AI 待审候选正文 | `example_candidate`（§2.4） |
+| 检测/评分/审核/实验结果 | `example_quality_result`（§2.3）+ 回执摘要 |
+| 用户的接受/合并/丢弃决策 | `example_user_decision`（§2.5） |
+| 每次运行的回执 | `example_run` + `example_run_receipt`（§2.2） |
+| 补证/重写记录 | 回执的修订类别列（§2.2） |
+| 模型调用提示词与执行配置 | `example_llm_call`（§2.1）+ raw |
+| Agent/Skill 元数据（角色画像 / 可配置项 / 技能读写合同） | `example_agent_role` + `example_skill`（§2.10 登记表；权威在 Git 侧，登记入库供看板智能体页只读） |
+| 完整原文/问答/标准答案/供应商响应 | `example_raw_lease` + `example_raw_content`（§2.7） |
+| 实体/范式观察草稿（05 §2 末步） | **挂起于 05 §6 待建，本期不建** |
+| 质量结果的结构化 reviews/experiments 量表全量 | 本期记 `example_quality_result`；跨运行聚合视图二期（06 §9） |
+| DB 备份与重建脚本 | 挂起于 08 §10，本设计不含 |
+
+建表约定（照现有 `91/96` 风格）：
+
+- 文件名 `db/ddl/<编号>-<中文主题>.sql`，编号从 **97** 起（90–96 已占）。`CREATE TABLE IF NOT EXISTS`；主键 `id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY`。
+- **公共列分界**（统一口径，文件头各写理由）：运行态设施表（`example_llm_call`）**不带**业务公共列（仿 `95`）；业务溯源账本（候选/决策/规划/冻结/raw/质量结果）带归属列 `creator/create_time/tenant_id`；**append-only 表一律不带 `updater/update_time/deleted` 三死列**（禁改删时它们永不写入）。
+- **append-only 表**（回执/决策/冻结/raw/质量结果）用 BEFORE UPDATE OR DELETE 触发器禁改写（仿 `96`）；可变表（候选/规划）带 `trg_*_updated_at`。
+- 唯一键含归属、命名 `uk_example_*`；CHECK `chk_example_*`；索引 `idx_example_*`。
+- **哈希归一规则**：runtime/CAS 系用 `sha256:<hex>`（71 字符），snapshot 系用裸 64 hex。**入库一律剥 `sha256:` 前缀存裸 64 hex**，列统一 `CHAR(64)`；读取按列语义决定是否复原。所有 `*_sha256` 列同此。
+- 一律 `.venv/bin/python .claude/skills/db/scripts/db.py apply db/ddl/<文件>`，整文件单事务回滚。
+
+## 2. 表设计
+
+外加：文件分组 97 调用 / 98 运行+回执+质量 / 99 候选+决策 / 100 规划+冻结 / 101 raw / 102 智能体·技能登记。**不启用 96 授权快照**：单用户本地，多租户授权机制是从父仓过度继承的（创始人 2026-07-30 拍板，见领域索引 §9）；参考书出处信息已在 `example_reference_work`/`muse_knowledge_document`。
+
+### 2.1 模型调用明细 `example_llm_call`（97）
+
+- **用途**：逐次记录每笔模型调用。今天只在 stderr 留一行（易失），库里只有按窗聚合的额度水位 `example_llm_quota`（4 列，非 MiniMax 成本记 0）。
+- **形态**：运行态设施表，**不带业务公共列**（仿 `95`，文件头写明：运行态、append-only、无业务归属）；append-only。**不扩额度账本**（账本是按窗 `+=` 累加器，语义打架）。
+- **列**：`id` PK；`window_key VARCHAR(16)`（→ 额度窗）；`run_id VARCHAR(64)`（可空，清洗/拆书批处理无 run，靠 caller 区分）；`caller VARCHAR(64)`；`requested_model_id`/`actual_model_id VARCHAR(64)`；`model_match BOOLEAN`；`in_tokens`/`cached_tokens`/`out_tokens INTEGER`；`cost_usd NUMERIC(14,8)`（本地估算，非网关权威，已知）；`stop_reason VARCHAR(32)`；`duration_ms INTEGER`；`prompt_sha256 CHAR(64)`（全文落 raw）；`raw_content_id BIGINT`（→ raw）；`call_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP`（兼作创建时间）；`creator VARCHAR(64)`（记写入方；设施表只留这两列）。
+- **索引**：`idx(window_key)`、`idx(caller, call_time)`、`idx(run_id)`。
+- **写路径（按可实现性修正）**：`duration/tokens/stop_reason/raw 响应体`都在 `chat()` 内部即弃，`chat_governed` 那层拿不到——所以写点是 **`chat()` 内置 hook**（不是贴在 `chat_governed` 的 `_bump_window` 后），由 `chat()` 在拿到响应处直接记；`caller`/`run_id` 由调用方传入（下游 6 处：parse_llm/parse_outline/parse_ingest/migrate_upgrade_windows/review_cards/clean_detect，加可选参数不破坏兼容）。`chat()` 只回 `(content, usage)`，raw 响应体要往上带（扩返回或回调）。
+- **owner**：06-模型边界。
+
+### 2.2 运行注册 + 运行回执 + 质量结果（98，三表同文件，运行级账本）
+
+**`example_run`**（运行注册，可变表——回应"run_id 无主"）：一次运行一行，所有子表挂它。
+- 列：`run_id VARCHAR(64) PRIMARY KEY`（自然键）；`work_id BIGINT`（→ 作品，回答"哪个作品"，08 §3 硬要求）；`target_chapter INTEGER`；`trigger_source VARCHAR(32)`（user/replay_eval/diagnostic，触发来源；**不用 trigger，那是 SQL 保留字**）；`trigger_detail JSONB`（用户意图摘要等）；`started_at`/`finished_at TIMESTAMP`；`terminal_state VARCHAR(20)`（running/completed/failed）；公共列六件套（可变表，带软删）。
+- 写路径：运行开始时写一行（生产由主会话发起、回放由 replay-eval 发起），结束时更新终态。
+
+**`example_run_receipt`**（运行身份账本，append-only）：字段平移自 `ExecutionReceipt.as_dict()` ⊕ CAS 身份 ⊕ 哈希链。
+- 列：`id` PK；`run_id VARCHAR(64) NOT NULL`（→ `example_run`）；`sample_id VARCHAR(64) NOT NULL`（**生产侧也造一个运行内标识，不得空**——CAS revision 按样本单调，sample_id 必须进唯一键）；`revision INTEGER NOT NULL`（CAS 样本内单调号）；`arm VARCHAR(32)`；`attempt INTEGER DEFAULT 1`；`adapter_role VARCHAR(32)`（writer/planner/detector/judge…）；`stage_kind VARCHAR(20)`（**generation/detection/supplement/rewrite/accept**——补证/重写独立成类，配 `loop_seq INTEGER` 循环序号，回应"补证数不出次数"；与 attempt=失败重试 分工）；`candidate_version VARCHAR(32)`；`candidate_sha256 CHAR(64)`；`context_sha256 CHAR(64)`（**→ `example_context_freeze.context_sha256`，不是 manifest_sha256**）；`previous_state_sha256 CHAR(64)`（哈希链）；`requested_model_id`/`actual_model_id`；`model_match`；`effort`；`total_cost_usd NUMERIC(14,8)`；`usage JSONB`；`stop_reason`/`terminal_reason`；`is_error BOOLEAN`；`safe_summary JSONB`（结论 + 失败类别的安全摘要；完整 prompt/response 落 raw）；`result_sha256 CHAR(64)`；`raw_content_id BIGINT`；归属列 `creator/create_time/tenant_id`（唯一键含 tenant_id）。
+- **唯一键 `uk(run_id, sample_id, revision)`**（CAS 身份；revision 按样本单调，单 run_id 下不同样本各有 revision=1，故 sample_id 必入键）。
+- **连接说明**：`candidate_version`/`candidate_sha256` 是数据列兼到候选表的连接键（05 §3 绑定键 `run_id+attempt+candidate_version+candidate_sha256`），**不是回执自身身份**。回执↔候选是**四列 1:N**（一个候选对应生成/检测/审核多条回执）；筛"产生该候选的生成回执"用 `adapter_role='writer' AND stage_kind='generation'`。
+- 写路径：评测 `ledger.complete()`（replay-eval/execute.py）、质量门 `issue_gate_report_and_receipt()`（quality-gate/writer_gate.py）、生产 `continuation/run_writer.py::run_writer_with_receipt`。
+- **owner**：08 §7（字段合同）、05 §3（绑定键）。回执**不含**"用户决策"字段（偏离 08 §7 字面：回执是 append-only 身份账本，决策独立成表见 §2.5；蒸馏时回改 08）。
+
+**`example_quality_result`**（质量评判账本，append-only——回应"有质量评判就记录、就可见"）：
+- 列：`id` PK；`run_id VARCHAR(64)`（→ run）；`receipt_id BIGINT`（→ 回执）；`candidate_sha256 CHAR(64)`（绑候选，06 §5）；`judge_kind VARCHAR(20)`（detection/scoring/review/experiment）；`dimension VARCHAR(32)`（评分维度，评分类用）；`scale_version VARCHAR(32)`（量表/质量政策版本，06 §3）；`score NUMERIC`；`conclusion VARCHAR(20)`（pass/fail/revise…）；`failure_class VARCHAR(32)`；`detail JSONB`（审核的问题/修复/复验；实验的基线/假设/干预/预期/结论）；`raw_content_id BIGINT`；归属列 + `create_time`。
+- **索引**：`idx(candidate_sha256)`、`idx(run_id)`、`idx(judge_kind)`。幂等唯一键用表达式索引 `uk(tenant_id, run_id, judge_kind, COALESCE(dimension,''), COALESCE(candidate_sha256,''))`（dimension/candidate_sha256 可空，朴素 UNIQUE 在 PG 里 NULL 互不相等会破坏幂等，故 COALESCE；重跑检测不重复记）。
+- 写路径：detect / quality-gate / eval 在各自签发处落一条。**本期：每次评判都记录、看板运行详情逐条可见；跨运行评分趋势/复利聚合视图二期**（06 §9，那是视图聚合不是记录）。
+- **owner**：06-质量与复利。
+
+### 2.3 （编号承接上文）：98 文件含运行/回执/质量三表，见 2.2。
+
+### 2.4 待审候选 `example_candidate`（99）
+
+- **用途**：登记 AI 待审候选（Shadow）。今天候选是内存对象 `InMemoryCasStateStore`；关联字段全在 `CandidateEnvelope v2`。
+- **形态**：可变表（状态流转），带归属列 + updated_at 触发器。
+- **列**：`id` PK；`work_id BIGINT NOT NULL`（→ 作品）；`target_chapter INTEGER NOT NULL`；`run_id VARCHAR(64)`（→ run；**merge 候选的 run_id = 复检重跑那次运行**，因为用户改后合并的版本没有生成 run，其"产出"是用户编辑 + 一次重跑检测，见 §2.9 来源说明）；`attempt INTEGER`；`run_type VARCHAR(20) NOT NULL`（**production/eval/diagnostic——评测候选不得成正文，05 §8.4 四层机械隔离的第一层；`acceptance_eligible` 是由 run_type 派生的缓存位，以 run_type 为准**）；`candidate_version VARCHAR(32) NOT NULL`；`candidate_sha256 CHAR(64) NOT NULL`；`candidate_body TEXT`（候选正文，看板待审视图直接读；候选表整体按 raw 级访问控制——见 §4，**不重复塞 raw 表**）；`context_sha256 CHAR(64)`（→ freeze.context_sha256）；`quality_policy_version VARCHAR(32)`；`mode VARCHAR(20)`（continuation/rewrite/expansion/polish）；`source_role VARCHAR(20)`；`state VARCHAR(20) NOT NULL DEFAULT 'draft'`；`acceptance_eligible BOOLEAN`；归属列 + `update_time`/`deleted`。
+- **状态机**（对齐 [05 §3](../.agent/docs/architecture/domains/05-创作流程领域.md)，列名/值与 05 统一）：
+
+```text
+draft -> checking -> passed      （机械门 + 语义检测 + 质量审核通过）
+                  -> rejected    （不通过，修订后以新候选版本重跑，不就地改）
+draft/checking/passed -> discarded   （用户在任一态都可丢弃，对齐 05）
+passed -> accepted               （用户原样接受，confirm 写）
+accepted -> archived             （归档，对齐 05 单条 ACCEPTED→ARCHIVED）
+```
+
+- 7 态全进库是 SoT 逼出来的（05 §3、§8 条目 6 要看板渲染候选当前命运），非冲突。列名 `state`、值小写（库惯例），与 05 §3 大写状态名语义对应（ACCEPTED↔accepted、DISCARDED↔discarded 等）。
+- **唯一键** `uk(tenant_id, work_id, target_chapter, candidate_version)`；**索引** `idx(tenant_id, work_id, state)`、`idx(tenant_id, run_type)`（评测隔离查询）。
+- 写路径：`continuation/run_writer_pipeline.py` PASSED 终态登记（替换内存 store）；confirm 的 PG 版状态迁移。
+- **owner**：01-作品领域（存储）、05 §3（状态机）。
+
+### 2.5 用户决策记录 `example_user_decision`（99，与候选同文件）
+
+- **用途**：记录用户每次接受/合并/丢弃 + **理据**（补现在缺的"为什么"——今天唯一留痕是 git commit message，翻库后不算数）。
+- **命名锚定（拆父仓雷）**：本表是父仓 **Candidate Decision Archive**（后端-04 §7/§11，用户处理候选**之后**的审计归档）的单用户落地，**不是** ADR-018 删除的 Candidate Decision Envelope（接受**前**预封装的裁决闸门）；不缓存来源/质量/合规裁决，接受时实时校验（05 §5 六道保护步）。
+- **形态**：append-only（一条决策一行，改主意=插新行覆盖候选 state）。
+- **列**：`id` PK；`candidate_id BIGINT`（→ 候选）；`work_id BIGINT`/`target_chapter INTEGER`（决策当时的快照，append-only 故不会失步）；`decision VARCHAR(20) NOT NULL`（accept/merge/discard）；`rationale TEXT`（理据）；`basis_ref VARCHAR(256)`（依据，如 大纲@日期/细纲版本）；`decided_by VARCHAR(64)`（单用户=创始人）；`expected_revision INTEGER`（接受时比对的**正文** revision，冲突报 REVISION_CONFLICT）；`command_id VARCHAR(120)`（幂等键，**直连 `muse_content_command_log.command_id`**——它无 sha256 列，故不叫 command_sha256）；`canonical_block_id BIGINT`（接受/合并后落成的正式正文 → `muse_content_block.id`；**冗余正向指针，不是来源权威——来源权威在正文块自带的归因，见 §2.9**）；归属列 + `create_time`。
+- **范围**：只记正文/规划候选的 accept/merge/discard。知识卡确认是另一个动词（confirm），走 `muse_knowledge_draft.status` 双轨 + `muse_knowledge_entity`，不进本表（避免多态关联；父仓后端-04 §11 亦分表分状态）。
+- 写路径：confirm 新增写库层（该目录现零 DB 代码）；决策写入后翻候选 state。
+- **owner**：05-创作流程（接受语义）、01（存储）。
+
+### 2.6 规划与上下文冻结（100，两表同文件）
+
+今天三类产物库里零存量零表：规划/细纲在文件与 gitignore 临时目录（planning 连脚本都没有，planner 智能体直接写文件），冻结 manifest 是仓外临时 JSON 算完即弃；主仓 `muse_content_planning_section` 暂缓未建。两表新建。
+
+**`example_planning_section`**（可变表，带归属列 + updated_at）：
+- 列：`id` PK；`work_id BIGINT NOT NULL`；`target_chapter INTEGER`（章级 section=细纲 填章号；书级=设定/大纲/状态/装配 为空）；`section_type VARCHAR(32)`（setting/outline/state/assembly/fine_outline）；`schema_type VARCHAR(32)`（对应 meta/schemas 型）；`version INTEGER`；`payload JSONB NOT NULL`（结构化内容）；`state VARCHAR(20) DEFAULT 'shadow'`（shadow/confirmed）；`confirmed_at TIMESTAMP`；归属列 + `update_time`/`deleted`。
+- **唯一键用两个部分唯一索引**（仿 V26 partial unique，因 target_chapter 可空）：书级 `uk(tenant_id, work_id, section_type, version) WHERE target_chapter IS NULL`；章级 `uk(tenant_id, work_id, section_type, target_chapter, version) WHERE target_chapter IS NOT NULL`。
+- **已确认细纲取用**（补今天的无持久化缺口）：`SELECT payload FROM example_planning_section WHERE work_id=? AND section_type='fine_outline' AND target_chapter=? AND state='confirmed' ORDER BY version DESC LIMIT 1`。read-context 取数需改道读库（不再当内存参数）。
+
+**`example_context_freeze`**（append-only，冻结一旦生成不可改）：
+- 列：`id` PK；`work_id BIGINT`；`target_chapter INTEGER`；`as_of_chapter INTEGER NOT NULL`（冻结上界，严格 `<= asOf`）；`manifest_sha256 CHAR(64) NOT NULL UNIQUE`（manifest 自身哈希）；`context_sha256 CHAR(64)`（**WriterContext 回执哈希 = `retrieval_identity(context)`，回执表连的是这一列**；非唯一，接受一对多或加索引）；`reference_work_id BIGINT`；`reference_version VARCHAR(64)`；`arm_config JSONB`；`sections JSONB`（每节 sourceId/sourceVersion/sha256/charCount）；`token_budget INTEGER`；`omitted_fields`/`omitted_sources JSONB`；归属列 + `create_time`。
+- **写路径（点名具体落点，不用含糊的"编排层"）**：snapshot 纯函数（build/check/audit）**不动**，asOf/哈希校验原样当入库前失败关闭闸。落库挂在 **read-context 的 `assemble_writer_context.py::assemble_context()` 之后**——这是生产路径真实存在且被调用的函数（主会话调 read-context 组装上下文），算出 `context_sha256` 后即弃处改为经 db skill 落一行。回放路径由 replay-eval 在其编排里同样落。**不新建独立"生产编排器"**：本仓生产编排=主会话按 AGENTS §7 顺序调 skill，落库挂各 skill 现有调用点即可。
+- **owner**：04-上下文领域、01（规划存储）。
+
+### 2.7 raw 元数据与全文（101，两表同文件）
+
+**raw 合同已改写**（创始人批准，详 §4）：放弃时效语义，改靠**访问控制 + append-only**；密钥/token 绝不入表。
+
+**`example_raw_lease`**（元数据，append-only，字段自 `_lease_record` 平移）：
+- 列：`id` PK；`vault_id CHAR(32)`；`run_id VARCHAR(64)`；`source_version VARCHAR(128)`；`content_hashes JSONB`；`purpose VARCHAR(64)`；`status VARCHAR(20)`（open/migrated/closed，**保留作历史状态，不再是删期限闸门**）；`retain_until TIMESTAMP`（**批准的留存期限，留作溯源；进库后不触发自动删除，将来若加清理策略以此为据**——诚实留档，非僵尸）；`archive_id`/`archive_sha256`（仓外备份若仍做）；`file_count`/`total_bytes`；`run_authorization_id VARCHAR(128)`（本次运行授权标识，来自执行授权——运行时对象，不查库、不指 96）；`source_work_id BIGINT`（raw 来源参考书 → `example_reference_work.id`，出处溯源）；归属列 + `create_time`。
+
+**`example_raw_content`**（全文，append-only，受访问控制）：
+- 列：`id` PK；`lease_id BIGINT`（→ lease）；`kind VARCHAR(32)`（prompt/response/source_text/oracle/supplier——**删 `candidate`：候选正文单存候选表，不进 raw**）；`run_id VARCHAR(64)`；`role VARCHAR(32)`；`content_sha256 CHAR(64) NOT NULL`；`content TEXT NOT NULL`；归属列 + `create_time`。
+- **唯一键 `uk(lease_id, content_sha256)`**（同一次进库内重试幂等去重；**跨进库各留一行，授权归属不串**——不用全局 UNIQUE(content_sha256)，否则同一本书两份授权共享一行、溯源指错）。
+- **访问控制**：默认不进普通检索，看全文须显式指定；看板可看全文；密钥/token/凭据列级 + 写入前过滤双禁。
+- 写路径：raw_vault 写点 + 各调用方 `_raw_json` 改走 db skill 参数化通道（§3）。
+- **owner**：08 §5。
+
+### 2.8 增删改查形态（回答"能不能简洁 CRUD"）
+
+| 类别 | 表 | 增 | 查 | 改 | 删 |
+|---|---|---|---|---|---|
+| 账本（不可变） | llm_call / run_receipt / quality_result / user_decision / context_freeze / raw_lease / raw_content | INSERT | SELECT | ✗ 触发器禁；"改"=插新行 | ✗ 触发器禁 |
+| 可变 | run / candidate / planning_section / agent_role / skill | INSERT | SELECT | UPDATE（终态/状态/配置） | 软删 `deleted=TRUE` |
+
+- **archived vs deleted 分界**：归档走候选 `state='archived'`（业务命运，看板历史照常可见）；清垃圾行/测试行走 `deleted=TRUE`（行级行政隐藏，默认不显示）。
+- 真实场景查询都是一两条带索引的等值/范围查询：
+  - **看板看待审候选并接受**：`SELECT … FROM example_candidate WHERE work_id=? AND state IN ('draft','checking','passed') AND run_type='production'`（正文就在 `candidate_body`）；接受=插一条决策 + `UPDATE candidate SET state='accepted'`。
+  - **一次运行全链路排查**（给 run_id）：`example_run` 拿作品/触发/终态；回执/候选/质量结果/raw/模型调用各 `WHERE run_id=?`；冻结用回执 `context_sha256` 连 `freeze.context_sha256`。
+  - **这段正式正文从哪来**：见 §2.9——权威从**正文块自带归因**反查，不经决策表正向指针。
+  - **按章取已确认细纲**：见 §2.6 SQL。
+  - **某候选被判了什么**：`SELECT … FROM example_quality_result WHERE candidate_sha256=?`。
+
+### 2.9 正文来源归因（写正文入库的前置合同）
+
+这是看板"沿来源下钻"立身之本，也是评审最集中的洞，单列前置合同：
+
+- **方向**：来源权威落在**正文块自身**，不是决策表的正向指针。依据父仓 [架构-02 §3](../../../design-docs/架构-02-核心数据结构与双轨模型.md)："正文来源归因是当前正文 revision 的一部分，不能只依赖历史候选 Archive"。父仓正文块来源归因表（`muse_content_block_source_attribution`，主仓 V1 已有、暂空置）存 `decision_id` **反向引用**决策归档。
+- **用主仓现成表，不另起炉灶**：`muse_content_block_source_attribution`（`block_id + revision + source_type + source_object_id + source_version + lineage_payload JSONB + authorization_snapshot_id`，唯一键 `(tenant_id, block_id, revision)`）天生**按版本归因**——一章可 accept→merge→merge 出多个 revision，每个 revision 一行归因，`lineage_payload` 装候选身份（candidate_id/run_id/candidate_sha256）。这解决了"revision=2 是哪次决策造成的"。
+- **`user_decision.canonical_block_id` 降级**为冗余正向指针（看板从决策跳正文用），**不当唯一溯源路径**。
+- **写正文 Canonical 写入层**：本设计的前置依赖，不是顺手事，**提为独立子任务并估工**。写入序列（单事务，定死 crash-in-between 形态）：
+
+```text
+校验（accept preflight，05 §5 六道保护步，含 revision CAS）
+  -> 写 muse_content_block（content_text，revision + 1）        [拿到 block_id]
+  -> 写 muse_content_block_source_attribution（block_id, revision, lineage_payload=候选身份）
+  -> 写 example_user_decision（canonical_block_id=block_id, command_id 幂等）
+  -> UPDATE example_candidate SET state='accepted'
+  （同事务提交；任一失败整体回滚，不留"无来源指针的正式正文"）
+```
+
+- **merge 候选来源**：用户改后合并的版本无生成 run，其 run_id=复检重跑运行，归因 `lineage_payload` 标 `source_type='user_merge'` + 原候选 + 重跑检测回执。
+- **本期缩小声明**：单用户暂不做多租户导出/来源撤权重验，但归因落块的方向按架构-02 §3 执行，不埋"只靠归档"的债。来源撤权时候选作废，本期不做撤权重验（不启用 96），接受时实时校验兜底（05 可补 invalidated 语义）。
+
+### 2.10 智能体与技能登记 `example_agent_role` + `example_skill`（102）
+
+看板"智能体"空间的画像 / 可配置项 / 技能合同的数据源（**A 方案，2026-07-30 拍板**）。这些元数据的权威在 Git 侧（`.claude/agents/*.md`、`.claude/skills/*/SKILL.md`），但看板只读库——故登记入库，把智能体配置也纳入留痕。登记表是 Git 侧权威在库内的**影子**（类比 `muse_meta_function_chain` 是 meta/chains 的库内影子）：**Git 仍是配置权威，登记表只供看板只读**。
+
+**`example_agent_role`**（角色登记，可变表，带公共列 + updated_at）：
+
+- 列：`id` PK；`role VARCHAR(32) NOT NULL`（writer/planner/extractor/detector/judge）；`display_name VARCHAR(64)`；`model VARCHAR(64)`（模型归属，opus/其它）；`effort VARCHAR(16)`；`budget_usd NUMERIC(14,8)`；`tools JSONB`（可用工具）；`responsibility TEXT`（职责白话描述）；`source_ref VARCHAR(256)`（Git 侧 .md 路径，出处可溯）；`synced_at TIMESTAMP`（最近一次从 Git 同步时间）；公共列六件套。
+- 唯一键 `uk(tenant_id, role)`。
+
+**`example_skill`**（技能登记，可变表，带公共列 + updated_at）：
+
+- 列：`id` PK；`skill_name VARCHAR(64) NOT NULL`；`purpose TEXT`（一句话用途）；`consumer VARCHAR(64)`（给谁用：主会话/某角色/其它 skill）；`reads JSONB`（读哪些表）；`writes JSONB`（写哪些表）；`red_lines TEXT`（红线）；`model_used VARCHAR(64)`（用模型则记，确定性工具为空）；`source_ref VARCHAR(256)`（SKILL.md 路径）；`synced_at TIMESTAMP`；公共列六件套。
+- 唯一键 `uk(tenant_id, skill_name)`。
+
+**登记机制**：新增确定性登记脚本（建议 `db/scripts/sync_agent_registry.py`，或挂到现有种子机制），从 Git 侧 md 抽取 frontmatter 与"数据库读写合同"段，**upsert 两表**（幂等可重跑，仿 `seed_schemas`）；配置变更后重跑即同步。看板只读这两表、不读 Git（守住看板只读库的合同）。
+
+## 3. 写路径改造（落库挂各 skill 现有调用点；不新建独立生产编排器）
+
+本仓生产编排=主会话按 AGENTS §7 顺序调 skill。落库挂在每个 skill 真实存在的调用点上，唯一新建组件是 §2.9 的正文写入层。
+
+| skill | 改什么 | 落库点 |
+|---|---|---|
+| **db**（前置） | `db.py exec` 现收裸 SQL 字符串、无参数化；百 KB raw 全文过 CLI 参数不可行（shell 转义 + ARG_MAX）。**扩展 db.py 提供参数化/stdin 执行通道**（登记为新工作） | — |
+| **正文写入层**（新建，§2.9） | 写 block + source_attribution + decision + 翻 state 的单事务序列 | confirm 触发 |
+| **confirm**（动最重） | SKILL.md description（还是 git 那句）+ 采纳/丢弃/推送三段换写库语义；scripts/ 新增 PG 版候选状态存储 + 决策写入 + 调正文写入层。**注意 confirm 是 DB/git 混合体**：知识卡确认与"既有创作文件采纳"仍走 git，正文候选走 DB——SKILL.md 写清双通道分界，不是整体切换 | decision + candidate.state |
+| **continuation** | `run_writer_pipeline` PASSED 终态登记候选（替换内存 store / result_path 文件）；`candidateArtifact` 进 raw | candidate + raw |
+| **llm** | `chat()` 内置 hook 落明细；响应体往上带；caller/run_id 由 6 个下游传入 | llm_call |
+| **detect / quality-gate / eval** | 签发处落质量评判 + 回执 | quality_result + receipt |
+| **read-context** | `assemble_context()` 算出 context_sha256 后落冻结；取已确认细纲改道读库 | context_freeze |
+| **planning / fine-outline**（从零建管线，单拆一步） | ① planner 智能体契约改写（opus 自由 Markdown→按 schema_type 产严格 JSON）；② planning validator（从无到有，对等 writer_contract）；③ Markdown/frontmatter→payload JSONB 规则；④ 主会话落库代码；⑤ read-context 细纲读取改道。先交付①②再落库；版本语义（version 谁递增、shadow→confirmed 是否走 confirm）拍定 | planning_section |
+| **runtime（raw_vault）** | raw 进库改写见 §4，是重定义安全终态，不是改一个写点 | raw_lease + raw_content |
+
+**写入通道口径（修正自相矛盾）**：所有写入经 **db skill 的 DSN 与约定**，在各 skill 的 `scripts/` 内以**参数化短连接**执行（仿 `_bump_window` 的即开即关，Tailscale 不持长事务）；大对象（raw 全文）走 db.py 参数化/stdin 通道。不是"每笔起一次 db CLI 子进程"，也不是裸连各写各的。
+
+## 4. raw 合同改写（创始人批准，单列拍死三件事）
+
+旧合同（raw 留仓外 `/tmp` 租约保险库、24h 过期即删、评测后 migrate 归档、回执不带路径）作废。新合同：**raw 进库、靠访问控制 + append-only、可看全文**。实现前先把三件事拍死（否则第 4 步是重做半个 replay-eval）：
+
+1. **过期条款的 DB 形态**：**放弃时效语义**（单用户本地），改靠**访问控制 + append-only**；`retain_until` 只留档溯源，不触发自动删除。raw_vault 的 `RAW_LEASE_EXPIRED`/`min_remaining`/调前复检（`_assert_raw_call_window`）这三条可执行安全条款，在库模型下由"访问控制 + 禁删触发器"替代，不再做时效裁决。
+2. **run 成功终态的新定义**：今天 `COMPLETED` 的必要条件是 `raw_disposition_ok`（migrate 成功），CAS 终态记 `cleanup_state=migrated/failed`。raw 常驻库后 migrate 降为**可选仓外备份**，`COMPLETED` 改以"raw 已落库（lease+content 写入成功）"为终态判据；`cleanup_state` 枚举与 manifest 的 `rawDisposition` 相应重定义。连带 `test_raw_vault.py / test_run_writer_replay.py / test_audit_leakage.py` 重写。
+3. **授权门简化（不启用 96）**：单用户本地，授权人/使用者/机器是同一人，原"用途授权有效（关联 96 快照）"门改为轻量出处门——raw 须来自已导入参考书（`source_work_id` → `example_reference_work`，出处可溯）且仅本地用途即可；不做版权状态/用途数组/到期重验那套多租户合规仪式。`run_authorization_id` 仅记运行授权出处（运行时对象，不查库）。密钥/token 禁入表的门保留。
+
+**对账父仓**：raw 全量留存是对 [专题-05 §9.2](../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)"provider 原始响应默认不长期保存"的**刻意覆盖**——单用户锻炉需全量 raw 可见以供走查；密钥/凭据禁入表仍从父仓（§9.1）。此覆盖写明于 08 §5。
+
+**改写落点**（实现第 4 步动）：08 §5、runtime `SKILL.md`、[可视化模块合同 §5](../.agent/docs/architecture/可视化模块合同.md)、`db/表映射.md`。§4 旧 raw 清单删"未接受候选正文"、`raw_content.kind` 删 `candidate`（候选正文单存候选表，整表 raw 级访问控制——对齐 08 §3 落库合同表）。
+
+## 5. 看板模块设计
+
+合同在 [可视化模块合同](../.agent/docs/architecture/可视化模块合同.md)，这里只补实现排序：
+
+- **只读硬约束**（机械门）：独立只读连接（`SET TRANSACTION READ ONLY`）；全代码 grep 无 `INSERT/UPDATE/DELETE`/DDL；不接写通道；挂了不牵连创作链。
+- **技术形态**：纯标准库 HTTP 服务端渲染（仿 open-wenmo hub），无 SPA 框架；查库复用 `.venv` psycopg **只读连接**。
+- **关键解耦**：合同 §4.1 各视图（作品/知识卡/参考书拆书/清洗/额度/结构本体/写命令审计；授权快照不启用）**全读现有表，可立即并行起步**；§4.2 视图随落库逐格点亮，未建显示"无数据/待落库"。
+- **质量评判本期可见**：运行详情页逐条展示该 run 的 `example_quality_result`（检测/评分/审核/实验 + 量表版本 + 失败类别）；**跨运行评分趋势/复利聚合视图二期**（依赖已有数据，是视图层）。
+- **防误导**（合同 §7）：型别看 `draft_payload` 中文/英文两套键不看 `draft_type`；公共/作品看 `work_id`；entity/binding 0 行如实显示"已确认为 0"；数字实时查库不缓存。
+- **门禁**：本机/局域网/Tailscale 免验证；公网走 TOTP；单用户信任。
+
+## 6. 实施顺序与验收
+
+```text
+第 0 步（门）    raw 旧合同作废落 08 §5；拍死 §4 三件事；定 §2.9 正文写入层归属（不启用 96，无需 apply）
+第 1 步（打底，风险最小，可并行看板§4.1）
+                db.py 参数化通道扩展；97 llm_call；98 run+receipt+quality（含 run_type/修订类别/唯一键修正）；
+                102 智能体·技能登记表 + 登记脚本（读 Git→upsert，看板智能体页据此可建）
+第 2 步（心脏）  99 候选+决策 + 正文 Canonical 写入层（§2.9 单事务序列）+ confirm 写库改造
+第 3 步         planning 管线（planner 合同+validator 先行）+ 100 规划与冻结 + read-context 改道
+第 4 步         101 raw（按 §4 新合同）+ runtime 安全终态重定义 + 测试重写，卡用途授权门
+看板            与上并行：先发 §4.1；§4.2 随落库点亮；质量评判随 98 上线即在运行详情可见；复利聚合视图二期
+```
+
+每步验收（对照各领域 SoT）：
+
+1. DDL 先落 `db/ddl/` 再 apply；`db/表映射.md` 同步登记。
+2. 写路径走 db skill 参数化短连接；离线自测覆盖关键路径与失败路径，失败明确失败关闭。
+3. 看板对应视图渲染实时数据；未建表显示"无数据/待落库"。
+4. 全链路无密钥/token 进表；raw 受访问控制。
+5. 来源链可机械验证：`source_attribution` 按 `(block_id, revision)` 反查到候选；评测候选 `run_type='eval'` 不得 `state='accepted'`（05 §8.4）。
+6. 框架改动与创作内容分开审查、分开提交；git 提交先取授权。
+
+## 7. 关联 SoT 与蒸馏去向
+
+- 落库原则 owner：[领域索引 §3](../.agent/docs/architecture/domains/_index.md)
+- 存储/可恢复/raw/回执字段合同：[08](../.agent/docs/architecture/domains/08-数据权威与可视化领域.md) §3/§5/§7
+- 候选状态机/绑定键/接受语义/评测隔离：[05](../.agent/docs/architecture/domains/05-创作流程领域.md) §3/§5/§8.4
+- 候选/规划存储结构：[01](../.agent/docs/architecture/domains/01-作品领域.md)
+- 上下文冻结与取数：[04](../.agent/docs/architecture/domains/04-上下文领域.md)
+- 质量评判记录与量表版本：[06](../.agent/docs/architecture/domains/06-质量与复利领域.md) §3/§5/§9
+- 正文来源归因方向：[父仓 架构-02 §3](../../../design-docs/架构-02-核心数据结构与双轨模型.md)；归因表 `muse_content_block_source_attribution`（主仓 V1）
+- 决策归档命名锚定：父仓 后端-04 §7/§11（Candidate Decision Archive）；ADR-018（删的是 Decision Envelope）
+- raw 留存对账：[父仓 专题-05 §9.2](../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)
+- 只读看板合同：[可视化模块合同](../.agent/docs/architecture/可视化模块合同.md)
+- 表清单与现状：[`db/表映射.md`](../db/表映射.md)
+- 蒸馏去向：实现后表结构→`db/ddl/97–102`；清单约定→`db/表映射.md`；"哪些输入产出进哪类表"具体表名→08 §3。本文件届时删除。