writing-agent/docs/play-presentation-shells.md

游玩呈现壳（P1）· 可微调前端模板

阶段：P1 = 定类与契约；P2 = 程序/样式适配与灌数。
上游：游玩管线 auditor → gm → narrator（已落地）。
创作挂钩：设计.正文组成 / 设计.监控栏；终稿 tag 通常 输出.用户展示。
创作定位：基于固定壳做适配微调，不是从零设计前端。

1. 创作怎么做（权威口径）

固定壳（本仓库预置，少数几种）
  → 创作期：选一个 shell_id
  → 只改允许的微调轴（字段、显示名、开关、tone_chrome…）
  → 禁止改分区骨架、禁止发明第五种布局
游玩期：往壳的区域里灌数（present.v1 / 投影 / settlement）

「正文组成」= 壳适配单，不是 UI 创意稿。
用户看见的差异应来自同壳不同绑定，而不是每局一套新布局。

2. 问题（若不用壳）

创作期若只写散文式「想要好看界面」，模型难稳定产出可跑界面，也会和程序渲染脱节。
壳把布局钉死，创作只填内容契约。

创作：选壳 + 微调绑定（字段/文案/开关）
游玩：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. 与创作产物的映射

设计.正文组成
  正文.呈现壳.shell_id     → 必须是四大之一（选壳）
  正文.呈现壳.微调         → 只填允许轴（适配）
  正文.可见块[]            → 挂到壳已有区域，不新开区域
  正文.监控栏锚点          → chat_monitor / turn_panel 的字段意图
  正文.隐藏段              → 区域 hidden

设计.监控栏
  → 灌入该壳 monitor 区的字段表（仍是微调，不是新布局）

运行.本轮.裁决 (settlement.v1)
  → body 事实来源；suggested_actions → footer（若壳开启）

输出.用户展示
  → 优先 present.v1 灌进壳区域；纯 Markdown → body

5. 游玩灌数契约（P2 实现目标）

推荐 输出.用户展示 在分块壳下为：

{
  "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；口径明确为创作基于壳适配微调。