重构世界模拟器为模块化配方架构，完善创作编排、会话运行时与 Web UI，并清理过时技能。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-30 00:39:32 +08:00
parent 2b74c30d36
commit e670a5129c
167 changed files with 22955 additions and 5659 deletions
--- a/docs/briefs/capability-authoring-brief.md
+++ b/docs/briefs/capability-authoring-brief.md
@@ -0,0 +1,435 @@
+# 能力撰写交接简报（泛用）
+
+> **用途**：把本文**整份**交给另一 AI / 作者，用于撰写任意【能力】的 `modules/{id}/prompt.md`。  
+> **本文是自洽规范**：不依赖读者已熟悉本仓库。  
+> **不要**让撰写方改程序代码；**不要**只写某一能力的特例而不遵守通用格式。
+
+范例（深度与结构对齐）：`skills/dialogue/world-simulator/modules/aesthetics-interaction/prompt.md`  
+能力池清单（选题用）：`docs/world-simulator-modules.md`  
+术语权威：`docs/ui-glossary.md` §0
+
+---
+
+# 第一部分：项目是什么
+
+## 1.1 一句话
+
+**writing-agent** 是本地运行的多 Agent **文本创作 / 游玩**系统：用户选一个【导演】，在【创作】期谈成【剧本】，再在【游玩】期让【演员】按剧本上场，产出可读文本（角色扮演、长文/爽文、扩写、思想实验等共用同一内核）。
+
+## 1.2 要解决什么问题
+
+| 要 | 不要 |
+|----|------|
+| 用程序控制「每一步注入什么上下文」 | 把整本长说明书一次塞进 LLM |
+| 用 Agent 按用户体验**编排**用哪些能力、什么顺序 | 死板选单 DAG，或全程让 LLM 自由发明工序 |
+| 产物可解析、可渲染、对人可读 | 产物里堆满英文变量名让用户难受 |
+| 规格（能复用的声明）与一局游玩过程分离 | 每种玩法重写一套运行时 |
+
+## 1.3 两段生命周期
+
+```text
+【创作 design】选导演 → 编排剧本（步骤=能力）→ 逐步执行能力 → 谈成可运行规格
+        │
+        ▼ 用户手动进入
+【游玩 play】用户输入 → 演员按规格上场 → 可见终稿；可存档 / 重 roll
+```
+
+- **创作**：谈清「这局要什么体验、用哪些能力钉成什么产物」。  
+- **游玩**：按已验收规格跑；用户新输入通常视为认可上一轮展示（否则重 roll）。
+
+## 1.4 运行时怎么分工（撰写能力时必须懂）
+
+| 角色 | 做什么 | 不做什么 |
+|------|--------|----------|
+| **导演（Agent）** | 决定下一步调哪个演员；编排剧本步骤 | 不直接写小说正文；不私自改相位 |
+| **程序（Runtime）** | 校验权限；按契约拼上下文；切步；发 opening；验收门控 | 不替用户发明体验 |
+| **能力（modules）** | 某一步「怎么和用户谈、产出什么形状」的方法正文 | 不是整场流水线 |
+| **演员（Worker）** | 一次 LLM 执行（创作期跑能力，或游玩期跑声明内 ref） | 不决定全局调度 |
+
+关键路径：
+
+```text
+用户选【导演】（如世界模拟器）
+  → design-flow：从【能力】排出**近期**步骤，写出 设计.创作流程
+       （可变增量 DAG：每步 id + 固定中文名 + depends_on；status=open|closed）
+  → 用户验收近期流程
+  → 反复 design-step：程序注入「当前能力」的 prompt 切片 + 依赖产物
+  → 步骤做完仍 open → 再 design-flow（可追加同能力多次，如生成规则 / 具体实例）
+  → closed 后收成可进游玩的规格，如 设计.worker集
+  → 用户手动进游玩
+```
+
+## 1.5 磁盘上两层内容（作者视角）
+
+```text
+【导演】recipes/{导演id}/recipe.yaml     该方法的建议近期起点 / 调味说明
+【能力】modules/{能力id}/prompt.md       共用工序；多导演可选用同一能力
+       modules/catalog.yaml             能力目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）
+```
+
+- 新建作品**只选导演一层**，不再叠「能力包 + 配方」。  
+- 导演给出的步骤是**近期起点**；本局可增量追加、可反复调用标了 `repeatable` 的能力；验收的是本局【剧本】，不是磁盘死菜谱。
+
+---
+
+# 第二部分：称呼定义（必须统一）
+
+对用户与能力正文，优先用**拍摄隐喻**。括号内为内部/旧称，撰写时勿当用户主词。
+
+## 2.1 四个核心词
+
+| 称呼 | 含义 | 内部大致对应 | 禁止对用户说 |
+|------|------|--------------|--------------|
+| **导演** | ① 新建时选一次的方法起点（世界模拟器、扩写助手…）；② 会话里负责调度的 Agent | `recipes/`、Main Agent / orchestrator | 总管、配方（作选型主词）、能力包（作第二层选项） |
+| **剧本** | 本局谈成的流程与规格（活的） | `设计.创作流程` + 各能力产物 + 终稿 `设计.worker集` 等 | 「剧本 Skill 菜单」、死板流程卡 |
+| **演员** | 上场执行的一次单元 | Worker / `run_worker` | 对用户堆 `Worker · english-id` |
+| **能力** | 共用工序模块；导演从池里选型编排 | `modules/{id}/` | 组件池、模块（作者文档可用；用户文案用「能力」） |
+
+关系口诀：
+
+```text
+选导演 → 用能力编排 → 谈成剧本 → 演员按剧本上场
+```
+
+## 2.2 阶段与界面
+
+| 称呼 | 含义 |
+|------|------|
+| **创作** | lifecycle `design`：谈剧本 |
+| **游玩** | lifecycle `play`：演员上场 |
+| **产物** | 某步待验收输出（写入黑板 tag） |
+| **验收 / 接受** | 用户确认产物算数 |
+| **黑板** | 按 tag 存正文的上下文板 |
+| **询问卡** | 结构化提问（选项可改写） |
+
+## 2.3 创作调度相关（可出现在作者文档，少直接甩给用户）
+
+| 内部 id | 用户可见 | 含义 |
+|---------|----------|------|
+| `design-flow` | 创作 · 流程编排 | 编排/增量修订可变 DAG → `设计.创作流程` |
+| `design-step` | 创作 · 执行步骤 | 执行剧本中当前那一个能力 |
+| `opening-generator` | 开局 · 开场白 | 可选；规格收成后的开场白 |
+
+## 2.4 剧本流程 JSON（编排产物：增量 DAG）
+
+```json
+{
+  "brief": "可选：一句话体验复述",
+  "status": "open",
+  "steps": [
+    { "id": "美学纲领与交互范式", "name": "美学纲领与交互范式", "depends_on": [] },
+    { "id": "生成规则", "name": "生成规则", "depends_on": ["美学纲领与交互范式"] },
+    { "id": "生成规则#2", "name": "生成规则", "depends_on": ["生成规则"] }
+  ]
+}
+```
+
+| 字段 | 规则 |
+|------|------|
+| `status` | `open` = 还可追加；`closed` = 不再扩步。缺省兼容旧稿视为已收口 |
+| `steps` 顺序 | 建议执行顺序 |
+| `id` | 本局步骤唯一键；同能力多次必须不同 |
+| `name` | 必须与能力目录中的**固定中文名**完全一致（可重复） |
+| `depends_on` | 依赖的其它步骤 **id**（若某 name 在本流程唯一，也可写 name） |
+
+程序用中文 `name` 映射到 `artifact` tag；流程 JSON **不写**英文模块 id / tag。  
+**禁止**一次排死全程固定长链；「生成规则」「具体实例」等标了 `repeatable` 的能力应允许多次编入。
+
+## 2.5 已合并能力（勿拆回）
+
+| 错误拆法 | 正确能力 |
+|----------|----------|
+| 「交互范式」+「美学纲领」两步 | **美学纲领与交互范式**（`aesthetics-interaction`）一步 |
+
+询问相近则合并为一步；不要在新能力里建议再拆开。
+
+## 2.6 命名纪律
+
+| 种类 | 规则 | 例 |
+|------|------|-----|
+| 能力中文名 | 稳定、给人看、进流程 JSON | `实现机制` |
+| 能力 id | 英文 kebab，= 文件夹名 | `mechanism` |
+| 产物 tag | 通常 `设计.{中文名或约定名}` | `设计.实现机制` |
+| 游玩演员 ref | 英文 kebab | `narrator` |
+| 游玩演员展示名 | 中文 `name` | `叙事转述` |
+| UI | 禁止裸露内部英文 id | 不要写 `design-step` 给用户 |
+
+---
+
+# 第三部分：什么是「能力」（泛用定义）
+
+## 3.1 定义
+
+**能力** = 创作期可被编排进剧本的**一步工序**：
+
+1. 有固定中文名与产物 tag；  
+2. 有一份程序可切割的方法文档（`prompt.md`）；  
+3. 执行时只注入**本能力**方法 + **依赖产物** + 用户表述；  
+4. 与用户对话后产出**可验收**的结构化结果。
+
+能力**不是**：整场游戏引擎、游玩期每轮演员、也不是导演本身。
+
+## 3.2 能力在系统中的生命周期
+
+```text
+catalog 登记（短声明给编排看；可选 repeatable）
+    → 导演/编排增量选入 设计.创作流程（可同能力多次）
+    → 用户验收流程（或后续扩步后再验）
+    → 轮到该步：若有 opening → 程序先发出
+    → 用户首答 → LLM 按能力方法谈/写
+    → 写入 artifact tag → 用户验收
+    → 下游能力可读该产物（若 depends_on 声明了）
+    → 不够则再 design-flow 追加同能力新 id
+```
+## 3.3 能力作者要交付的两样东西
+
+| 交付物 | 路径 | 给谁看 |
+|--------|------|--------|
+| 目录行 | `modules/catalog.yaml` 一行 | 编排：只看短 `declaration` |
+| 方法全文 | `modules/{id}/prompt.md` | 执行该步的 LLM + 程序切割 |
+
+编排时**禁止**把全文 prompt 塞进导演上下文；执行时才注入切割后的方法块。
+
+## 3.4 能力之间如何相处
+
+- **正推**：需要 [体验/产物] → 才纳入某能力；勿默认全选池内能力。  
+- **边界**：每个能力在 `meta.boundary` 写清「本步定什么 / 不定什么 / 交给谁」。  
+- **依赖**：由剧本 `depends_on` 声明；执行期程序注入对应产物。  
+- **合并**：询问主题高度重叠 → 合成一个能力（如美学+交互）。  
+- **缩减**：每增必问能否删、能否常驻替代、能否合并。
+
+## 3.5 方法层硬禁止（写任何能力都适用）
+
+- 题材 → 固定演员清单。  
+- 否定式路由（「因为是 X 所以不需要 Y」）；应写「需要 A 体验 → 用 B 手段」。  
+- 把「世界模拟」当成一切开场的默认答案。  
+- 为排版/格式单独发明演员；能程序拼则程序拼。  
+- 临时发明 tool。  
+- 一次 burst 写齐全部能力产物。  
+- 在能力产物里堆大量用户看不懂的英文变量名（机器 id 可有，但须有中文展示字段）。
+
+---
+
+# 第四部分：能力文档格式规范（程序契约）
+
+每个能力 = `modules/{id}/prompt.md` + `catalog.yaml` 一行。
+
+程序**只认 fence 的语言标签**切割，**不认**仅靠 `##` 标题。
+
+## 4.1 块一览
+
+| fence 标签 | 必填 | 用途 |
+|------------|------|------|
+| `meta` | 强烈建议 | YAML 元数据：选型与边界 |
+| `opening` | 可选 | **默认问题**；程序发给用户，**不经**本步 LLM |
+| `task` | **必填** | 本步任务与验收边界 |
+| `principles` | 强烈建议 | 原则 |
+| `probe` | 强烈建议 | 追问策略 |
+| `output` | **必填** | 产物形状（多为 JSON） |
+| `checklist` | 强烈建议 | 自检 |
+| `examples` | 可选 | 好/坏对照 |
+
+未列出的 fence 名：**不要发明**（除非先改程序切割器）。
+
+## 4.2 标准骨架
+
+````markdown
+# {能力中文名}
+
+> 可选说明。
+
+## meta
+
+```meta
+name: {与 catalog 完全一致的中文名}
+id: {文件夹 id}
+artifact: 设计.{…}
+declaration: >
+  {一行选型话术；与 catalog 对齐}
+when: |
+  {什么情况下应被编排进来}
+when_not: |
+  {什么情况下不要进来}
+boundary: |
+  本能力：…
+  邻接能力：…（点名其它能力中文名，说明分工）
+```
+
+## opening
+
+```opening
+{用户第一眼看到的引导；整块可省略或留空 = 本步直接 LLM}
+```
+
+## task
+
+```task
+{只做本步；写清产物 tag；如何对待 opening 首答与依赖产物}
+```
+
+## principles
+
+```principles
+{正推、缩减、禁止项、与体验的关系}
+```
+
+## probe
+
+```probe
+{缺什么问什么；一轮 1～2 点；优先具体选项/短场景；勿重复已答清}
+```
+
+## output
+
+```output
+{推荐产物 JSON 形状：中文键、可渲染}
+```
+
+## checklist
+
+```checklist
+- [ ] …
+```
+
+## examples
+
+```examples
+{可选}
+```
+````
+
+## 4.3 `meta` 字段
+
+| 字段 | 含义 |
+|------|------|
+| `name` | 固定中文名（= 流程 `steps[].name`） |
+| `id` | 英文 id（= 目录名） |
+| `artifact` | 本步写入的黑板 tag |
+| `declaration` | 给编排看的短声明（不是全文） |
+| `when` / `when_not` | 何时该/不该入选剧本 |
+| `boundary` | 与邻接能力的分工 |
+
+## 4.4 `catalog.yaml` 一行
+
+```yaml
+- id: example-id
+  name: 示例能力中文名
+  declaration: >-
+    一句话说明何时选用、解决什么
+  artifact: 设计.示例能力中文名
+```
+
+| 字段 | 谁用 |
+|------|------|
+| `declaration` | 插入导演/编排提示，选型 |
+| `name` / `artifact` | 流程与执行映射 |
+| `opening` | 可选覆盖；一般只写在 prompt 的 `opening` 块 |
+
+改 `name` 会破坏已有剧本 JSON，尽量不改。
+
+## 4.5 opening 节奏（通用）
+
+```text
+若 opening 非空：
+  程序发 opening → 用户首答 → 再调 LLM
+  LLM 上下文含：方法块（通常不含再贴一遍 opening 策略以产品为准）
+               + 首答 + 依赖产物 + 用户需求
+task 必须写：禁止重复同一开场；在首答上补洞。
+```
+
+## 4.6 注入 LLM 时包含哪些块
+
+按顺序拼接切割结果，**默认不含** `opening`（开场已由程序发出）。  
+`meta` 是否注入以运行实现为准；撰写时把给人/模型的方法写在 `task`/`principles`/`probe`/`output`/`checklist`。
+
+## 4.7 产物（`output`）通用要求
+
+- 形状稳定，便于 UI 按 JSON 渲染。  
+- **键名对人友好**（中文或稳定中文标签）。  
+- 机器 id（如 `ref`）若需要，与中文名成对出现。  
+- 写清「本步完成的定义」；未决放 `开放问题`，不要假完备。  
+- 不要在本能力产物里偷偷交下游能力该交的终稿（除非本能力就是收成步）。
+
+## 4.8 追问（`probe`）通用要求
+
+- 一轮 askUser **1～2** 点。  
+- 优先：可直接采用或微调的完整句选项 / 短场景。  
+- 能推断则先写入再复述；只问影响本步核心且不能瞎填的点。  
+- 依赖产物已钉死的内容禁止重问。
+
+---
+
+# 第五部分：撰写任一能力时的工作步骤
+
+1. **定身份**：中文名、id、artifact；写清 when / when_not / boundary。  
+2. **看邻接**：上/下游能力各定什么；禁止重叠问卷。  
+3. **定产物形状**：先定 `output` JSON，再写 task/probe 如何填满它。  
+4. **定 opening**：需要程序先问再 LLM → 写 opening；否则留空。  
+5. **写 principles / probe / checklist**：正推、缩减、禁止套件。  
+6. **对照范例**：深度不低于 `aesthetics-interaction`。  
+7. **自检**：§4 块齐全；name 与 catalog 一致；用户文案无裸英文 id。
+
+---
+
+# 第六部分：给撰写 AI 的通用任务指令（粘贴用）
+
+请撰写（或重写）一个【能力】文档：  
+`skills/dialogue/world-simulator/modules/{id}/prompt.md`  
+（具体中文名 / id / 边界由出题方在指令末行指定。）
+
+必须遵守：
+
+1. 本文**第一部分～第四部分**的项目理解、称呼与格式契约。  
+2. 只使用规定的 fence 块；不要发明新 fence 名。  
+3. 对用户话术使用导演/剧本/演员/能力；不要写「总管调度 design-xxx」。  
+4. 正推：体验 → 手段；禁止题材套件与否定式路由。  
+5. 交互与美学已合并为「美学纲领与交互范式」；禁止建议拆回两步。  
+6. 不要修改程序代码；默认只交付 `prompt.md`（除非出题方要求改 catalog）。  
+7. 输出完整 Markdown 文件正文。
+
+出题方填写：
+
+```text
+能力中文名：
+id：
+artifact：
+上游依赖（常见）：
+明确不做（交给谁）：
+特殊产物要求（可选）：
+```
+
+---
+
+# 第七部分：当前能力池速查（选题，非本文重点）
+
+世界模拟器常用（编排按需，勿默认全选）：
+
+| 能力 | id | 状态（以仓库为准） |
+|------|-----|-------------------|
+| 美学纲领与交互范式 | `aesthetics-interaction` | 范例 |
+| 实现机制 | `mechanism` | 待细写 |
+| 世界蓝图与人文地理 | `world-blueprint` | 已写 |
+| 生成规则 | `generation-rules` | 待细写 |
+| 具体实例 | `concrete-instances` | 待细写 |
+| 拓扑图谱 | `topology` | 待细写 |
+| 叙事指南 | `narrative` | 待细写 |
+| 变量设计与更新规则 | `variable-design` | 待细写 |
+| 变量控制上下文 | `variable-context` | 待细写 |
+| 设计状态栏 | `status-bar` | 待细写 |
+| 设计回复格式 | `reply-format` | 待细写 |
+| Worker 规格 | `worker-spec` | 待细写 |
+| 细化终稿 | `refine` | 待细写 |
+
+导演示例：世界模拟器、扩写助手（见 `recipes/`）。
+
+---
+
+# 附录：与旧文档关系
+
+| 文档 | 关系 |
+|------|------|
+| 本文 | **泛用**能力撰写 + 项目/称呼；给外部 AI 的主交接 |
+| `world-simulator-modules.md` | 仓库内清单与格式摘要 |
+| `ui-glossary.md` | 用户可见文案权威 |
+| `architecture.md` | 运行内核；写能力时不必复述实现细节 |
+| 旧 `capability-mechanism-handoff.md` | 已过时为「单能力特例」；以本文为准 |