引入游玩呈现壳与旁观维护槽，完善结算合并、十分制自评与技能产物 UI。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 02:03:29 +08:00
parent 94f67fa744
commit 120d67ee82
46 changed files with 2513 additions and 236 deletions
--- a/docs/briefs/capability-authoring-brief.md
+++ b/docs/briefs/capability-authoring-brief.md
@@ -376,7 +376,7 @@ task 必须写：禁止重复同一开场；在首答上补洞。
  "稳变": "stable",
  "正文": { },
  "自评": {
-    "维度": [{ "名": "…", "分数": 0, "说明": "…" }],
+    "维度": [{ "名": "…", "分数": 8, "说明": "…" }],
    "薄弱点": "…"
  },
  "追问": {
@@ -396,7 +396,7 @@ task 必须写：禁止重复同一开场；在首答上补洞。
 | 段 | 说明 |
 |----|------|
 | `正文` | **产物主体**。技能自定内部结构（如美学步＝设定逻辑 + 交互范式 + 美学纲领）；须含「详细各个方面」。禁止整份只交散文。 |
-| `自评` | **自评评分**。`维度[]` 名目按技能定（美学步常用：交互范式 / 美学纲领 / 整体协调）；可含 `薄弱点`。 |
+| `自评` | **自评评分**。`维度[]` 名目按技能定（美学步常用：交互范式 / 美学纲领 / 整体协调）；**`分数` 为 0–10 十分制**（可一位小数；高质约 8–10）；可含 `薄弱点`。禁止用 0–100 百分数。 |
 | `追问` | **示例 + 建议选项**。给用户的下一问；`题目` 可空数组。与程序 askUser 可并存，但产物里要留结构化题面。 |

 | 规则 | 说明 |
@@ -404,10 +404,11 @@ task 必须写：禁止重复同一开场；在首答上补洞。
 | `schema` | 必须原样写出，供前端友好渲染 |
 | `mount` | 挂哪些槽/ref；**不要**写最终数字 `order` |
 | `稳变` | `stable` \| `semi` \| `volatile`，供「上下文投影排序」 |
+| **视图** | 产出形状固定后，该技能须有对应**专用正文卡**（前端按 `技能` / 正文键分流）；无专用卡时退回通用结构化。作者交付物＝`prompt.md`（含稳定 output）+ 可验收的阅读视图（实现或在清单中登记待做）。 |
 | 收成例外 | 游玩拓扑 / 上下文投影排序 / 细化终稿用自有 schema，不套本头 |

 范例对齐：`modules/aesthetics-interaction/prompt.md`（output 块）。
-
+前端已落地专用卡示例：生成规则 / 舞台骨架 / 实现机制 / 美学 mosaic；自评条显示为 `x/10`。
 ---

 # 第五部分：撰写任一能力时的工作步骤
--- a/docs/briefs/prompt-revision-inventory.md
+++ b/docs/briefs/prompt-revision-inventory.md
@@ -17,7 +17,7 @@
 | `modules/context-order/prompt.md` | **骨架已写**（`context-order.v1`） |
 | `docs/context-fragment-design.md` | **已写**；范例技能已对齐 `context-fragment.v1` |
 | 程序：片段解析 / 扁平投影序 / `对话.历史` 可投影 | **已落地**（非硬双锚） |
-| `orchestrator.md` | **仍待**：play 调度顺序 perspective? → gm → narrator |
+| `orchestrator.md` | **已改**：play 调度 auditor → perspective? → gm → narrator |

 ## 优先级 P1（能力归属 feeds）

@@ -56,7 +56,7 @@
 ```json
 // 设计.worker集（世界模拟）
 {
-  "play_slots": { "gm": true, "narrator": true, "perspective": false },
+  "play_slots": { "auditor": true, "gm": true, "narrator": true, "perspective": false },
  "tables": { "side_effects": [/* 来自变量设计 */] },
  "workers": [/* 可空，由程序按槽展开；或覆盖 context/outputs */]
 }
@@ -76,6 +76,16 @@
 }
 ```

+```json
+// 运行.本轮.旁观（多数轮空）
+{
+  "schema": "maintain.v1",
+  "need_generate": false,
+  "table_ops": [],
+  "notes": []
+}
+```
+
 ## 建议你改的顺序

 1. `refine` + `worker-spec`（或新拓扑技能）对齐 `play_slots`  
--- a/docs/context-fragment-design.md
+++ b/docs/context-fragment-design.md
@@ -21,11 +21,13 @@

 | 槽键 | 默认 ref | 用户可见 | 默认 |
 |------|----------|----------|------|
+| `auditor` | `auditor` | 旁观维护 | 开 |
 | `gm` | `world-simulator` | 主世界层 | 开 |
 | `narrator` | `narrator` | 叙事转述 | 开 |
 | `perspective` | `role-decide` | 角色视角 | 关 |

-推荐游玩调度：`perspective? → gm → narrator`。
+推荐游玩调度：`auditor → perspective? → gm → narrator`。  
+旁观维护默认**不注入**「对话.历史」；主世界层 / 转述按投影排序表裁剪历史。

 ## 3. 上下文片段：`context-fragment.v1`

@@ -45,7 +47,7 @@
 生成规则正文：必要性判断 + `rules[]`（生成与描写 + **单层**产物格式 + 可选多池绑顶层字段）；自评＝必要性/属性妥当/格式准确。  
 美学纲领自评仍为：交互范式 / 美学纲领 / 整体协调（勿与生成规则三维混用）。  
 叙事指南与故事推进正文：纲领 / 风格与遣词(+示范) / 笔墨焦点 / 禁忌与不偏好 / 情境备用 / 推进与决策 / 内容与表达；自评＝写法可执行/推进可执行/与美学对齐；artifact=`设计.叙事指南与故事推进`。  
-正文组成：用户可见块序 + 监控栏锚点 + 隐藏变量段 + 前端拆分意图（非程序报文）；artifact=`设计.正文组成`。  
+正文组成：**基于固定呈现壳适配微调**（选 `shell_id` + 微调轴；块只挂壳已有区域）；artifact=`设计.正文组成`。见 `docs/play-presentation-shells.md`。
 设计监控栏：只监控会变字段（可含攻略目标/场景交互物）；artifact=`设计.监控栏`（旧称状态栏）。  
 变量设计：真值 + **维护语句** + **Data映射索引**（指向具体实例）+ side_effects。  
 变量控制上下文：各槽视野 + **旁观汇总**（当前档摘要）。  
@@ -121,11 +123,20 @@ API：`POST /api/sessions/:id/context-order`（`move` / `set_projection` / `set_

 ## 6. UI 渲染

-| schema | 友好渲染 |
+| schema / 技能 | 友好渲染 |
 |--------|----------|
-| `context-fragment.v1` | 概要 / 挂载 / 正文 |
+| `context-fragment.v1` 外壳 | brief / 挂载 / **自评十分制（x/10）** / 追问 |
+| 美学纲领与交互范式 | mosaic（设定逻辑 / 交互范式 / 美学纲领） |
+| 生成规则 | 必要性 + 规则卡（方法、单层字段表、池） |
+| 舞台骨架 | 尺度 / 社会 / 状况 / 关键区实体卡 |
+| 实现机制 | 支撑点卡 + 关系 + 覆盖检验 |
+| 其它技能正文 | 通用结构化（KV）；**应补专用卡** |
 | `context-order.v1` | 扁平序表；历史行高亮 |

+解析失败时勿只甩 JSON 墙：提示无法解析并保留原文折叠。自评 `分数` 契约为 **0–10**（旧百分数会按 /10 兼容显示）。
+
+技能作者：output 键稳定后，须登记或实现对应视图（见 `capability-authoring-brief.md` §4.9「视图」）。
+
 ## 7. 配方链路

 ```text
--- a/docs/play-presentation-shells.md
+++ b/docs/play-presentation-shells.md
@@ -0,0 +1,143 @@
+# 游玩呈现壳（P1）· 可微调前端模板
+
+> **阶段**：P1 = 定类与契约；**P2** = 程序/样式适配与灌数。  
+> 上游：游玩管线 `auditor → gm → narrator`（已落地）。  
+> 创作挂钩：`设计.正文组成` / `设计.监控栏`；终稿 tag 通常 `输出.用户展示`。  
+> **创作定位：基于固定壳做适配微调，不是从零设计前端。**
+
+## 1. 创作怎么做（权威口径）
+
+```text
+固定壳（本仓库预置，少数几种）
+  → 创作期：选一个 shell_id
+  → 只改允许的微调轴（字段、显示名、开关、tone_chrome…）
+  → 禁止改分区骨架、禁止发明第五种布局
+游玩期：往壳的区域里灌数（present.v1 / 投影 / settlement）
+```
+
+「正文组成」= **壳适配单**，不是 UI 创意稿。  
+用户看见的差异应来自**同壳不同绑定**，而不是每局一套新布局。
+
+## 2. 问题（若不用壳）
+
+创作期若只写散文式「想要好看界面」，模型难稳定产出可跑界面，也会和程序渲染脱节。  
+壳把布局钉死，创作只填内容契约。
+
+```text
+创作：选壳 + 微调绑定（字段/文案/开关）
+游玩：narrator / 程序灌入对应区域
+伪 0 层：壳自带的 HUD 区，不是新 LLM
+```
+
+## 3. 四大常用壳（微调模板，非成品皮肤）
+
+| id | 中文 | 主场景 | 默认分区 | 默认可调 |
+|----|------|--------|----------|----------|
+| `prose` | 纯散文流 | 只要沉浸正文、不要 HUD | 单流 `body` | 文末可选折叠备注 |
+| `chat_monitor` | 对话 + 顶栏监控 | 网恋 / 日常扮演 / 轻 AIRP | `monitor` 顶栏 + `body` 主聊 | 监控字段；是否显示建议行动 |
+| `turn_panel` | 回合面板 | 强机制、资源/检定、场景交互 | `monitor` + `body` + `footer`（建议行动/检定结果） | 栏位；footer 开闭；机遇区 |
+| `chapter_reader` | 章节阅读 | 长文 / 爽文 / 助手分段 | `header`（章题/卷）+ `body` + 可选 `aside`（进度） | 章标题样式；是否显示大纲进度 |
+
+旧规格未写 `shell_id` → 运行时视为 `prose`（与「可不排正文组成」一致）。
+
+### 3.1 各壳固定槽位（程序认这些区域 id；创作不得增删分区）
+
+| 区域 id | prose | chat_monitor | turn_panel | chapter_reader |
+|---------|-------|--------------|------------|----------------|
+| `monitor` | — | 顶栏 | 顶/侧栏 | — 或弱化进 header |
+| `header` | — | 可选会话抬头 | 可选回合号 | **章题/卷信息** |
+| `body` | **主文** | **主聊/场面** | **场面叙述** | **章正文** |
+| `footer` | 可选 | 可选短吐槽 | **建议行动 / 机遇摘要** | 可选作者注 |
+| `aside` | — | — | 可选场景交互物 | **进度/卷纲摘要** |
+| `hidden` | 变量段 | 变量段 | 变量段 | 变量段 |
+
+隐藏段从不进用户主视线（默认折叠/调试可见）。
+
+### 3.2 微调轴（创作只许改这些；布局骨架只读）
+
+每壳允许覆盖、禁止改布局骨架：
+
+| 轴 | 说明 | 例 |
+|----|------|-----|
+| `monitor_fields` | 监控栏字段子集（来自设计.监控栏） | 好感、体力、今日话题 |
+| `block_labels` | 可见块显示名 | 「场面」→「短信记录」 |
+| `show_suggested_actions` | 是否渲染 settlement.suggested_actions | turn_panel 默认开 |
+| `tone_chrome` | 极轻装饰关键词（非完整 CSS） | `messenger` / `terminal` / `book` |
+| `empty_states` | 监控/aside 空态文案 | 「尚无攻略目标」 |
+
+**禁止**创作期输出完整 CSS/工程；`tone_chrome` 只是壳内预设皮肤键。  
+**禁止**增删壳的分区、禁止自造第五种 `shell_id`（要新壳走仓库改模板，不走单局创作）。
+
+## 4. 与创作产物的映射
+
+```text
+设计.正文组成
+  正文.呈现壳.shell_id     → 必须是四大之一（选壳）
+  正文.呈现壳.微调         → 只填允许轴（适配）
+  正文.可见块[]            → 挂到壳已有区域，不新开区域
+  正文.监控栏锚点          → chat_monitor / turn_panel 的字段意图
+  正文.隐藏段              → 区域 hidden
+
+设计.监控栏
+  → 灌入该壳 monitor 区的字段表（仍是微调，不是新布局）
+
+运行.本轮.裁决 (settlement.v1)
+  → body 事实来源；suggested_actions → footer（若壳开启）
+
+输出.用户展示
+  → 优先 present.v1 灌进壳区域；纯 Markdown → body
+```
+
+## 5. 游玩灌数契约（P2 实现目标）
+
+推荐 `输出.用户展示` 在分块壳下为：
+
+```json
+{
+  "schema": "present.v1",
+  "shell": "chat_monitor",
+  "blocks": {
+    "monitor": { "好感": "暖络", "今日": "下雨" },
+    "body": "……用户可读正文……",
+    "footer": ""
+  },
+  "meta": {
+    "suggested_actions": ["回一句关心", "约周末"],
+    "hide": ["<<<VARS>>>…<<<END>>>"]
+  }
+}
+```
+
+- `shell` 可省略 → 用规格里正文组成的 `shell_id`。  
+- 若整段非 JSON：壳把全文写入 `body`，其它区用变量投影/监控栏程序填（P2）。  
+- `prose`：只需 `body` 字符串或 Markdown。
+
+## 6. 创作期只做适配（正文组成）
+
+1. **选壳**（四选一）：无 HUD → `prose`；对话+状态 → `chat_monitor`；机制重 → `turn_panel`；写章 → `chapter_reader`。  
+2. **微调**：监控字段、块显示名、建议行动开关、`tone_chrome`、空态文案。  
+3. **不要**：重画分区、发明新区域 id、写 CSS、谈「另一种全新界面」。  
+4. `版式隐喻` 仅供人读；**程序只认 `shell_id` + 微调轴**。
+
+## 7. P2 适配清单
+
+| 序 | 项 | 状态 |
+|----|----|------|
+| 1 | `web/` 四壳最小渲染器 | **已接** `web/present-shells.js` + CSS |
+| 2 | 读 `设计.正文组成` 微调进 SessionView | **已接** `presentationTweaks` |
+| 3 | 解析 `present.v1` / 纯文本回退 | **已接** `src/skills/present-packet.ts` |
+| 4 | narrator 模板按壳输出 | **已接** `worker-templates/narrator.yaml` |
+| 5 | 正文组成只产出壳适配单 | **已接**（P1 prompt） |
+
+仍可加深：监控栏字段程序灌 monitor、tone 皮肤精修、章阅读 aside 自动进度。
+
+## 8. 与路线图
+
+| 本文 | `px-roadmap` |
+|------|----------------|
+| P1 定壳 | 创作 = 选壳适配 |
+| P2 灌数渲染 | 挂 **PX2 阅读面** |
+
+---
+
+修订记录：2026-08-11 · P1；口径明确为创作基于壳适配微调。
--- a/docs/progressive-data-design.md
+++ b/docs/progressive-data-design.md
@@ -94,8 +94,9 @@ Progressive 投影              本轮主世界层只看见「当前档」；未

 ```text
 用户输入
-  → 主世界层（世界推演）：读变量 + 已投影 data，交事件/改真值（按规则）
-  →（可选）旁观审计：只出意见，不写 canon
+  → 旁观维护（副 LLM）：合同+表+本轮工单；默认空操作（maintain.v1）
+  →（可选）角色视角：强信息隔离时出反应建议
+  → 主世界层（世界推演）：读变量 + 已投影 data + 旁观包，交事件/改真值（按规则）
  →（可选）叙事转述：把裁决写成用户可见正文
  → 用户看到的终稿通常来自「呈现/叙事」执行单元，或主世界层兼呈现（规格决定）
 ```
@@ -105,10 +106,13 @@ Progressive 投影              本轮主世界层只看见「当前档」；未
 | 世界观、地点、势力百科 | 主世界层 + 常驻/查表 | 「世界观执行单元」 |
 | 好感与分档性格 | 真值 + Progressive 投影 | 「性格执行单元」 |
 | 大纲按章推进 | 真值 `章节` + 章表投影 | 每章一个执行单元 |
-| 知密视角 / 强信息隔离 | 才考虑额外执行单元 | 为「更聪明」而拆 |
-| 长跑漂移检查 | 旁观审计（只读建议） | 第三个创作主笔 |
+| 知密视角 / 强信息隔离 | 才考虑角色视角槽 | 为「更聪明」而拆 |
+| 表字段补充 / 按需触发生成规则 | 旁观维护（默认空操作） | 第三个创作主笔 |
+| 长跑漂移检查 | 旁观维护 notes | 第三个创作主笔 |

-用户可见名：`ui-glossary.md`（世界推演、叙事转述…）。作者文档可称 **主世界层 / 旁观**，与酒馆「主 GM + auditor」同构；**不要**对用户改称整套系统为「GM 框架」而废弃「执行单元」。
+用户可见名：`ui-glossary.md`（主世界层、旁观维护、叙事转述…）。作者文档可称 **主世界层 / 旁观维护**，与酒馆「主 GM + auditor」同构；**不要**对用户改称整套系统为「GM 框架」而废弃「执行单元」。
+
+**维护路径（不是 chance toolcall）**：主世界层输出 settlement.v1 → Runtime 合并 `variable_changes` 进 `变量.当前` → `side_effects` 换投影；旁观维护输出 maintain.v1 → Runtime 按需合并 `table_ops`；chance 只负责骰子/抽签。

 ## 6. 世界模拟器技能落点

@@ -122,6 +126,4 @@ Progressive 投影              本轮主世界层只看见「当前档」；未
 | **开场白与开场变量** | 开场正文（守版式）+ 与开场同真相的初值 |
 | **游玩拓扑 / 上下文投影排序 / 细化终稿** | 固定槽；扁平投影序；tables 收成 |

-**维护路径（不是 chance toolcall）**：主世界层输出可解析变更 → Runtime 合并 `变量.当前` → `side_effects` 换投影；chance 只负责骰子/抽签。
-
 编排口诀：体验与机制 → 要不要真值 → 映射表用生成规则/实例 → 维护语句与旁观汇总 → 开场同真相 → 收成。
--- a/docs/ui-glossary.md
+++ b/docs/ui-glossary.md
@@ -124,6 +124,7 @@
 | `narrator` | **叙事转述** |
 | `role-decide` | **角色决策** |
 | `world-simulator` | **主世界层**（旧称：世界推演） |
+| `auditor` | **旁观维护**（表/规则检查；默认空操作） |
 | `chance` | **机遇裁定**（按需：骰子/抽签/比点；程序工具） |
 | `round-present` | **回合呈现** |

@@ -139,10 +140,13 @@

 | 作者可用 | 典型 ref | 含义 |
 |----------|----------|------|
+| **旁观维护** | `auditor` | 副 LLM：表/规则检查与按需补充；默认每轮上场、多数轮空操作；不写真相 |
 | **主世界层** | `world-simulator` | 读变量与 Progressive 投影、按规则改真值/交事件；多数世界观与查表归这里 |
 | **叙事转述** | `narrator` | 把裁决写成用户可见正文（若规格拆了呈现） |
 | **机遇裁定** | `chance` | 按需程序工具（掷骰/比点/抽签）；不进每轮管线；结果 tag `运行.本轮.机遇` |
-| **旁观 / 审计** | 可选自建 | 只出意见，不写 canon；不为「更聪明」而拆 |
+| **角色视角** | `role-decide` | 仅强信息隔离；只出反应建议 |
+
+推荐调度：`auditor → perspective? → gm → narrator`。

 默认少拆：百科、分档性格、章大纲投影 → 主世界层 + 表副作用，**不要**再拆「世界观执行单元」「性格执行单元」。详见 `docs/progressive-data-design.md` §5。

--- a/docs/world-simulator-modules.md
+++ b/docs/world-simulator-modules.md
@@ -5,6 +5,7 @@
 > **标准范例**：`modules/aesthetics-interaction/prompt.md`。  
 > **真值 / Data / Progressive（变量与门控）**：**`docs/progressive-data-design.md`**。  
 > **上下文片段 / 槽位 / 投影排序**：**`docs/context-fragment-design.md`**。  
+> **游玩呈现壳（P1）**：**`docs/play-presentation-shells.md`**。  
 > **提示词待改清单**：**`docs/briefs/prompt-revision-inventory.md`**。  
 > **给外部 AI 的完整泛用规范**：**`docs/briefs/capability-authoring-brief.md`**（含 `context-fragment.v1`）。

@@ -124,15 +125,15 @@ recipes/world-simulator|expand-assistant/recipe.yaml

 | 能力 | id | 状态 |
 |------|-----|------|
-| 美学纲领与交互范式 | `aesthetics-interaction` | **范例已写** |
-| 实现机制 | `mechanism` | **已写**：`context-fragment.v1`（支撑点正文 + 自评 + 追问）；`feeds: gm` |
-| 舞台骨架 | `world-blueprint` | **已写**：`context-fragment.v1`；社会结构 + 世界状况 |
-| 生成规则 | `generation-rules` | **已写**：`context-fragment.v1`；宽原则 + 严合同键；可反复；`params.target` |
+| 美学纲领与交互范式 | `aesthetics-interaction` | **范例已写**；前端 mosaic 视图 |
+| 实现机制 | `mechanism` | **已写**：`context-fragment.v1`（支撑点正文 + 自评 + 追问）；`feeds: gm`；**专用卡已接** |
+| 舞台骨架 | `world-blueprint` | **已写**：`context-fragment.v1`；社会结构 + 世界状况；**专用卡已接** |
+| 生成规则 | `generation-rules` | **已写**：`context-fragment.v1`；宽原则 + 严合同键；可反复；`params.target`；**专用卡已接** |
 | 具体实例 | `concrete-instances` | **已写**：`context-fragment.v1`；只按规则执行；可反复；`params.rule_id` |
 | 叙事指南与故事推进 | `narrative` | **已写**：遣词/笔墨焦点/禁忌与不偏好 + 推进；挂转述 |
 | 拓扑图谱 | `topology` | 骨架，待细写 |
 | 设计监控栏 | `status-bar` | **已写**：只盯会变信息；旧称状态栏 |
-| 正文组成 | `reply-format` | **已写**：用户可见版式+隐藏段+前端拆分；旧称回复格式 |
+| 正文组成 | `reply-format` | **已写**：壳适配微调；P2 present 渲染已接；见 `docs/play-presentation-shells.md` |
 | 变量设计与更新规则 | `variable-design` | **已写**：真值+维护语句+Data映射索引+side_effects |
 | 变量控制上下文 | `variable-context` | **已写**：挂载+旁观汇总 |
 | 开场白与开场变量 | `opening-setup` | **已写**：开场守版式+同真相初值 |
@@ -141,13 +142,13 @@ recipes/world-simulator|expand-assistant/recipe.yaml

 | 能力 | id | 状态 |
 |------|-----|------|
-| 游玩拓扑 | `worker-spec` | **已写**：勾选固定槽，禁止自由发明 worker（旧称 Worker 规格） |
-| 上下文投影排序 | `context-order` | **已写**：扁平投影序（含对话.历史）；收成进 `context_order`；Runtime 已拼装 |
+| 游玩拓扑 | `worker-spec` | **已写**：勾选固定槽（含旁观维护 auditor）；禁自由发明 worker |
+| 上下文投影排序 | `context-order` | **已写**：扁平投影序（含对话.历史；旁观维护默认无历史）；收成进 `context_order`；Runtime 已拼装 |
 | 细化终稿 | `refine` | **已写**：按 `play_slots`（及排序表）收成 `设计.worker集` |

 | 编排器 | 状态 |
 |------|------|
-| 世界模拟器 | 链路已写：体验→挂槽写上下文→投影排序→终稿；起点：美学纲领与交互范式 |
+| 世界模拟器 | 创作链路已写；**play**：`auditor → perspective? → gm → narrator`；settlement/maintain 合并变量已接 |
 | 扩写助手 | 方法论已写；起点：美学纲领与交互范式；勿默认套世界模拟全套 |

 ---