writing-agent/docs/design-orchestrator-guide.md

# 创作设计指导（编排器 / 分步 design skills）

> **文档层级：工作流计划 / 创作方法（非系统架构）。**  
> 运行内核边界见 [`architecture.md`](./architecture.md)；本文不定义相位机、持久化或 Context Compiler。

权威说明：如何从用户意图收成 **实例规格（`设计.worker集` JSON）**，并指导 play 期声明调度。  
非固定创作流水线；`world-simulator` 等只是可选能力 ref，不是默认总形态。

相关：`context-assembly.md`（拼装）、`preset-format.md`（全局预设）、`tag-blackboard.md`（黑板）、`run-snapshot.md`（快照）。

包内落地（现行 `skills/dialogue/world-simulator/`）：

| 文件 | 角色 |
|------|------|
| `orchestrator.md` | 编排器调度 |
| `recipes/` | 配方选项（新建 UI 选一层） |
| `modules/{id}/prompt.md` | 技能正文（design-step 注入） |
| `workers/design-flow/` | 编排近期 `设计.创作流程` |
| `workers/design-step/` | 执行当前能力步 |
| `workers/opening-generator/` | 可选开场白 |
| `worker-templates/` | play 执行单元默认契约 |

旧 `design-core` / `design-fixed` / `design-worker` / `design-refine` / `design-common.md` / `design-intake` **已移除**。  
**运行时以包内 SKILL + modules 为准**；本文是方法长文，改方法时与 skill / 能力切片一起改。清单见 `world-simulator-modules.md`。

---

## 0. 总原则

```text
三大步（每步含自检，可反复，无强制题材工序）
  A 核心    → 站位 + 系统扮演/输出/交互 + 体验检验
  B 细节交互 → Worker/常驻上下文能否撑起世界与交互；冲突请用户选
  C 细化     → 钉死不能瞎发挥的关键前提；表/数据拓扑/副作用；用户是否满意

全程正推：需要 [体验] → 用 [常驻上下文 | 表 | worker | 程序 | 预设 | tool] 维持/产出
每增必问：能否缩减？常驻上下文能否替代？能否合并？黑板够不够/是否多余？
```

**禁止**

- 题材 → 固定 worker 清单；否定式路由；完整历史喂 LLM 再筛给另一 LLM
- 格式/排版专用 worker；临时生成 tool；默认 input 整理 worker
- 把「世界模拟」当成开场默认答案
- 固定 instantiate 管道（world-blueprint 等）

**预设**：凡 LLM 请求（编排器 / agent / worker）均插入用户预设。  
**进 play**：用户手动满意后进入（程序不强制开局锁定）。  
**Play 回合**：用户新输入 = 认可上一轮最终展示；否则重 roll / 编辑后重 roll。表维护可延后。

**规格格式**：`设计.worker集` 为 **JSON**（权威存储）；解析层可兼容旧 YAML 草稿，新产出必须 JSON。

---

## 1. 交互流程（先定「怎么和人轮转」）

输出本质可以都是「系统给出一截用户可见结果」，但 **轮转形态**不同，规格必须写明：

| 形态 | 典型 | 规格要点 |
|------|------|----------|
| 对话回合 | 最终展示一轮 ↔ 用户一轮 | 终稿 tag；无每轮验收 |
| 助手分段 | 先大纲/细纲，用户填表再继续 | 表可编辑；阶段门控；大纲可走表副作用 |
| 其它 | 旁观多角、写手统筹… | 站位 + 系统扮演共同决定 |

用户可 **编辑表（精确到字段格）** → 必须有 **字段级版本**（见 §5）。

---

## 2. 三大步

### A. 核心

#### A1. 用户站位（扮演什么）

单角代入 / 代理操控 / 旁观·实验 / 写手统筹 / 多角切换…  
→ 谁决策、输入如何解释、结构骨架。

#### A2. 系统扮演什么（play agent 整体）

指整个 **play agent 系统** 要：

- **扮演什么**（世界执行者？对白对手？写作助手？陈述实验？）
- **输出什么**（叙事、摘要、选项、表、大纲块…）
- **怎么输出**（单段终稿 / 监控栏+正文分块 / 文末小块 / 隐藏变量段；见正文组成）
- **怎么与用户交互**（回合对话、填表驱动、先大纲后正文…）

由此才谈：要不要转述、程序拼格式、表是否上屏等。

#### A3. 核心体验检验（首要评分，自检必做）

对当前理解与「现有 worker/上下文草案」打分或文字判定。

**对内**：可只在思维链里过一遍。  
**对外**（编排器 `ask_user.assessment`，或关键分叉复述）：写成用户可读的完备度评价，再据此出题。

**首要（必须检）**

| 维 | 含义 |
|----|------|
| 核心体验 / 满足来源 | 用户最想反复感到什么；爽点从哪来（权力、求生、关系、解谜…）——**一切评价与追问以此为轴** |
| 用户–`<user>` 关系 | 用户与代入角色/叙述对象的关系是否清楚 |
| 焦点位置 | 注意力与镜头落在哪 |

**可选（有缺口才写，不必凑齐）**

| 维 | 含义 |
|----|------|
| 内容维度 | 情节/日常/战斗/推理…比重与情绪质感 |
| 人物与关系 | 核心关系动态 |
| 身体与感官 | 物质、亲密、暴力等描写边界 |
| 背景与规则 | 世界架与规则用途 |
| 意义与主题 | 快感 / 代价 / 终点 |

`assessment` 建议结构（按需删维）：

```text
# 内容维度
核心感觉: 完备度 40%
  已知: …
  待探: 用户期望的【情绪质感】是【方向A】？【方向B】？还是组合？

人物与关系: 完备度 50%
  已知: …
  待探: …
```

`questions`：只针对「待探」里必须用户拍板的点；一次 1～2 题。  
- `prompt`：明确题干（「你更倾向于哪种…」）  
- `options`：**建议示范**（可含短场景钩子 + 点题句），用户可改写后采用；禁止空泛是/否  

自问：缺口是常驻上下文、表、worker，还是必须问用户？能推断就别问。

变造世界提示：用户常给「基础架 + 变种设定」；核心体验往往来自变种——从设定读内核，但 **不要**写成固定工序，也不要题材锁死体验。

#### A 步通用自检

见 §3。

---

### B. 细节交互

对照 A 的结论，检查草案：

1. **现有 worker（+ 常驻上下文）能否满足需求？**
2. **能否支撑起整个世界/助手流程？**
3. **有无冲突必须用户选择？**（两套互斥满足来源、互斥交互形态等 → `ask_user`）

仍用正推补洞；能固定上下文则不上 worker（§6：示例话题可问用户，不是填空表）。  
**顺序软规则**：纲领类固定上下文（风格/叙事/美学）宜先于大量 worker——同一份 tag 挂多个 worker，而不是先列 worker 再填上下文。  
然后 §3 自检。

---

### C. 细化

原则：只钉 **不能交给 AI 自由发挥、又对体验关键** 的东西。  
变造世界已能推出的（已知现代 → 不问常规科技树）默认不问，除非用户提过。

常钉类（按需）：规则与 **核心实现前提**、状态、**表结构**、**整体叙事指南**（≠ 文风：管世界态度与体验边界）、输入协议。

本步更盯 **数据**：

- 什么要 **拓扑化**（依赖、阶段边、触发边）？
- 什么要 **数据化/进表**？
- 表字段、显隐（折叠防剧透，非防用户）、维护规则、副作用是否清楚？
- **用户是否满意** 这些钉死项？

大纲：**不必**单独「大纲管道」。需要时用 **表 + 副作用**——例如表字段 `当前章=第一章` → 边沿触发插入「第一章细纲」上下文（与好感改人设同一套机制，见 §5）。

然后 §3 自检。

---

## 3. 每一步自检清单（三大步与每一小步共用）

每完成一截推理或改草案，强制过一遍：

| # | 问 |
|---|-----|
| 1 | **能否缩减？** 这条能力/字段/worker 删了是否仍成立？ |
| 2 | **增加的必要性？** 删掉会丢掉哪段体验？ |
| 3 | **上文是否足够** 辅助主 LLM 完成其 duty？不足补常驻/表/黑板，而非盲目加工人 |
| 4 | **写入黑板的内容** 够不够？是否多余？ |
| 5 | **能否与其它 worker 合并？** 或 **常驻上下文替代？** |
| 6 | **上下文插入是否按「变动/重要度」顺序？**（稳定块与易变块分层；参考 ST 注入位思路） |
| 7 | （C 步加重）数据传播、表、副作用、字段版本是否自洽？有无「持续为真每轮触发」？ |

复述给用户时：说明有什么、**为何没有** 某重型件。

---

## 4. 短板加装（表见 §5）

| 短板 | 做法 |
|------|------|
| 可见文本质量 | 转述 worker **或** 常驻文风；能轻则轻 |
| 记忆 / 长线 / 大纲 / 随机分支 / 人设阶段 | **统一用表**（§5）：维护 + 显隐 + 副作用插换上下文 |
| 信息差玩法 | 分角 worker；极贵，慎用 |
| 格式 | 程序拼 |
| 真随机 / 骰子卡组计算 | 固定按需槽 `chance`（程序工具：roll/compare/draw/pick）→ `运行.本轮.机遇`；`play_slots.chance` 开启后由编排器 run_worker；禁止临时造 LLM「骰子演员」 |
| 用户不应知道的信息 | 程序固定注入，不进可见区；非 input 整理 worker |
| 输入协议 | 常驻上下文（`()` 元要求、`""` 对白、无包裹=事实等） |

长线记忆：**不上**则靠模型；**要上**则 RAG（固定少设计）或表；禁止历史互喂筛选。

---

## 5. 表（结构 · 版本 · 维护 · 副作用 · 大纲）

### 5.1 用途

状态与物品、显隐信息、阶段/章节、随机与事件权重、人设态度段、**大纲/细纲挂载**、驱动常驻上下文插入或替换。

### 5.2 结构与显隐

- 扁平、利于二维表 UI；schema 写在 Worker 集
- **显形 / 隐藏（可折叠）**：防剧透、分层观看，不是防用户
- 维护规则可执行，并带触发语义（默认 once + edge）

### 5.3 字段格版本（防互相覆盖）

每一 **字段格**（非仅整表）含至少：

```text
value, rev, updatedAt, source  # source: user | worker:<id> | system
```

合并规则：

- 用户编辑升 `rev`，`source=user`
- Worker 写回须带 **读时的 rev**；若当前 rev 已变 → **不覆盖**，跳过或 ask_user
- 禁止无条件用维护结果盖掉用户格

### 5.4 维护 worker

读：正文/裁决、维护规则、当前表 → 写：字段更新。  
可不写用户终稿；可与展示链解耦、**延后**跑。

### 5.5 副作用（含大纲、人设、事件）

表值变化满足条件 → 触发声明内专用逻辑（改写态度段、插入第 N 章细纲、替换某常驻块等）。

优先：查表换段；跨阶段再跑改写 LLM。

**防无限触发（程序约定，写入规格）：**

1. **边沿**：`prev` 不满足且 `now` 满足才触发
2. **阶段字段**：规则绑「进入 stage」，不绑「处于 stage」
3. **`fired` / ruleId**：once 规则触发后标记，不再入队
4. 可重复须显式（`mode: every_edge`）+ 冷却/边沿
5. 同 round 同 ruleId 最多一次；对本轮维护用快照算边沿，限制连锁爆炸

例：`好感>=60→恋爱` 不得每轮触发；`当前章=第一章`→插入细纲须 edge 或章字段变更 once。

**规格字段（`tables.side_effects[]`）：**

```json
{
  "id": "affinity-romance",
  "field": "好感",
  "op": "gte",
  "value": 60,
  "mode": "once",
  "action": {
    "type": "write_tag",
    "tag": "上下文.角色态度",
    "content": "恋爱模式：……"
  }
}
```

| 字段 | 含义 |
|------|------|
| `op` | `eq` / `neq` / `gte` / `lte` / `gt` / `lt` / `truthy` / `changed` |
| `mode` | `once`（边沿 + 记 fired）\| `every_edge`（可反复跨边沿） |
| `action.type` | `write_tag` / `replace_tag` / `queue_worker` |

实现：`src/blackboard/table-side-effects.ts`；写 `变量.当前` / `运行.初始变量` 后由 runtime 求值；fired 存 `运行.表副作用.fired`。

方法与技能落点（真值 / Data / Progressive、写入源、少拆执行单元）：**`progressive-data-design.md`**；创作技能：`variable-design`、`variable-context`。

### 5.6 与交互流程

助手流：生成大纲/细纲 → **用户写入/改表** → 副作用或调度读表继续；始终尊重字段 `rev`。

---

## 6. 固定上下文族与预设

**「固定上下文」是概称**：不必单独开 worker、由程序按契约插入 prompt 的内容。  
**不上 worker ≠ 不重要**——谈清楚并写进规格的纲领/范式，往往比某个中间 worker 更决定体验。

### 6.0 Tag 的真正用途（纠正）

固定上下文用稳定 **tag / 单位 id** 命名（如美学纲领、叙事指南），便于：

1. **同一份正文挂到多个 worker**（`mount` / `contextSegments` / 声明映射）——这是主收益  
2. **创作单位分块验收**——扯皮过程可折叠，定稿切片进「创作.已验收内容」（已做）

**不是**「只报 tag 名就能省掉创作期依赖正文」。写 B 块时若依赖 A 的内容，仍要把 A 的定稿喂给写 B 的 LLM；tag 不能替代依赖传递。

```text
能省：反复扯皮直到定稿之前的过程（验收折叠）
不能省：写下游时对上游定稿正文的依赖
主收益：跨 worker 复用同一份固定上下文，而不是为每个 worker 各写一份
```

### 6.1 用法（重要：不是填空）

§6.2 里的名称 **只是示例话题**：告诉 design / 编排器——**可以向用户询问类似内容**，再收成固定上下文。

```text
不是：按表逐项填空、默认必谈、谈完才算过关
而是：对话中若体验需要钉死某类边界/呈现/协议 → 可以按这类话题问用户 → 写入规格并注入
```

正推仍成立：需要维持 [体验/边界/呈现] 且宜稳定注入 → 固定上下文；会变 → 表；本轮推理 → worker。  
问什么、问几句、要不要问，由当前体验缺口决定——**禁止把示例表当成问卷。**

### 6.2 示例话题（可问用户的方向）

| 话题（示例） | 大致在问什么 | 若收成规格，常见落点 |
|--------------|--------------|----------------------|
| 交互怎么转 | 站位、系统扮演、输出、怎么一轮一轮交手 | `interaction`（多由 `phase:core` 收） |
| 叙事指南 | 世界/助手态度与体验边界（≠ 文风） | `narrative_guide` |
| 美学纲领 | 呈现给用户的可读终稿气质 | `presentation` / 常驻美学块 |
| 输入协议 | `()` / `""` / 无包裹等约定 | `input_protocol` |
| 核心前提 | 不能瞎发挥又关键的硬前提 | `core_premises` |
| 其它常驻片段 | 只给部分 worker 的稳定句（态度段、轻规则…） | `resident_context[]` |

落点 id（`fixed:*` / `resident:*`）仅在 **已经写出内容、要当创作单位验收** 时使用；没有内容就不要当成待填格子。  
实现里的 `FIXED_CONTEXT_CATALOG` 同样是提示目录，不是 UI 填空项。

### 6.3 创作顺序（软）

```text
phase:core（核心体验 + 交互）
  → 纲领类固定上下文（风格 / 叙事 / 美学…）——宜先于大量 worker
  → 一次一个 worker（声明挂载哪些已有 tag，勿复制纲领）
  → 杂项常驻 / 表 / 副作用 → 终稿
```

**禁止默认**「先写完 worker 列表，再为每个 worker 填写上下文」。  
游玩拓扑只勾选固定槽（主世界层 / 转述 / 可选视角等），禁止自由发明执行单元；读写与美学长文分别由模板合并与上游常驻上下文承担。

**UI**：检查器把固定上下文做成 **独立卡片区**（非 Worker 子项），每张卡展示 **塞进哪些 Worker**；见 `worker-set-view.ts` 的 `contextTags`。

### 6.4 常驻条目与预设

杂项常驻（`resident_context[]`）形状示例：

```json
{
  "id": "tone",
  "position": "static",
  "importance": 2,
  "content": "文风克制、偏冷",
  "mount": ["narrator"]
}
```

- 默认黑板 tag `上下文.常驻.{id}`；可显式 `tag`
- `mount` 空 = 全部 worker；否则仅列出的 ref
- 能常驻则不上 worker；叙事指南 / 美学 / 交互等 **若已谈清**，用对应规格字段，不要全塞进含糊 `tone`
- 越稳、越决定体验边界 → 插入位越靠上

预设 = 全局；固定上下文 = 实例/worker 级。  
用户不可见、模型必须知 → **程序固定拼装**，不是整理用户输入的 worker。  
实现：`src/skills/resident-context.ts`。

---

## 7. 产出与验收

产出：`设计.worker集` JSON，建议包含：

- `interaction`：站位、系统扮演、输出形态、与用户轮转方式
- `experience_check`：首要三维（及可选维）摘要
- `workers[]`：`ref` / `duty` / `rationale` / **`acceptance`（run 验收点，见 §7.3）**
- `resident_context[]`：位置、内容摘要、挂载哪些 worker
- `tables`：schema、显隐、维护规则、副作用（含 edge/once/stage）
- `narrative_guide` / `core_premises`：叙事指南与核心实现前提
- `input_protocol`：若需要
- `design_end`：可选开局 · 开场白等备忘（非强制管道）

验收复述须含：站位；系统扮演/输出/交互；体验首要三维；有何 worker/表/副作用；**run 在哪些 worker 后停下来给人看**；为何没有某件；进 play 由用户决定。

交稿自检：题材词可替换仍成立；§3 清单通过；无持续为真每轮触发；格式程序化；字段级 rev 已设计；每个面向用户的可读终稿点有明确 `acceptance`。

---

## 7.1 强用户可读（前端约定）

创作期检查器须让用户看懂：

| 面板 | 内容 |
|------|------|
| **设计** | Worker 集卡片（含 run 验收点标注）、设计进度 |
| **验收** | 当前产物结构化预览 + 接受/不接受（主确认点） |
| **上下文** | 终产物 tag、活跃 tag、定稿摘要、已归档过程计数 |
| **历史** | 调度时间线（可折叠） |

主 feed：隐藏过程调度；验收中的全文进验收 Tab；**创作对话 messages 全量保留供浏览**；拼给下一 design worker 的「创作.对话」才裁 AI（见 §7.2）。

---

## 7.2 创作与 Run：两套上下文（勿混）

| | 创作 `design` | Run / play |
|--|---------------|------------|
| 单位 | **创作单位**：一个 worker，或固定上下文族中的一块（交互范式 / 叙事指南 / 美学纲领 / …），同级 | 声明内的 run worker |
| 会话 | 用户 ↔ 设计讨论进 **session `messages`（全量，用户可回看）**；**隐藏 AI 历史只作用于拼给模型的 transcript** | Worker **按契约从黑板重装**（`contextSegments` / `inputTags`） |
| 验收后折叠 | **不删 messages**；产物在黑板/规格；同步「创作.对话」供下一单位 | 过程 tag 归档 + `上下文.定稿摘要`（`compress-after-worker.ts`） |
| 禁止 | 一次收齐整份 worker 集 + 全部固定上下文；把纲领当成「顺便写的备注」 | 把创作闲聊塞进 worker prompt |

### 创作单位（粒度）

「固定上下文」= **族名**。族内某块 **只有谈出来并写入规格后** 才成为创作单位；§6.1 示例话题不是待填格子。

典型推进（非强制工序）：

1. `phase:core`：站位 + 交互 + 核心体验  
2. 需要时：风格 / 叙事 / 美学等 **纲领类** 固定上下文先验收（`design-fixed`）  
3. 各 `worker:{ref}`：挂载已有 tag，勿复制纲领  
4. 其它 `resident:*` → 表 / 副作用 → 终稿 `设计.worker集`

单位跑只写 `设计.worker集.草稿`；终稿才写 `设计.worker集`（才 `designInstanceReady`）。

### 创作会话（简单）

```text
本单位进行中：问答、复述、草稿讨论 → 照常 append 到 messages（用户浏览全量）
拼给 AI：写入黑板 tag「创作.对话」= 用户全量 + 仅最后一次 AI 输出（含未完成提问）
不需要：步内 policy、创作专用拼装栈改写 messages
```

### 创作折叠（简单）

```text
用户接受本单位产物
  → session.messages 不删（用户可继续浏览历史）
  → 产物本身在黑板/规格里；已验收内容写入「创作.已验收内容」
  → 同步「创作.对话」transcript（仍按：用户全量 + AI 只留最后一次）
  → 下一单位从「已定稿产物 + 新对话」继续
```

不在创作期做「定稿摘要再注入下一 design LLM」的复杂链；产物本身在黑板/规格里，够用。
「隐藏 AI 历史」= 仅 transcript 裁剪，**绝不**从主 feed 删掉或折叠创作过程消息。

### Run 压缩（与创作正交）

```text
用户在 run 验收点接受产物
  → 终产物 tag 标记 final
  → 过程 tag（worker 答复、*.草稿 等）归档
  → 写入 上下文.定稿摘要
  → 下一 worker 按契约重装时带上摘要与终产物
```

实现：`src/runtime/compress-after-worker.ts`。  
禁止把完整过程讨论继续喂给下一 **run** worker。

---

## 7.3 Run 验收点（创作时必须设计进 Worker 集）

**不是**「整条 run 有没有验收」的二选一，也不是创作阶段的特例。

**是：** 规定 **跑完哪个 worker 之后必须停下来让用户阅读/验收**；其余可连续调度。

| `workers[].acceptance` | 含义 |
|------------------------|------|
| `review` | 本 worker 完成后进入用户验收；接受后才压缩并允许续跑 |
| `continue` | 完成后可接着调下一个，不打断用户 |

**正推示例（写入 rationale / 复述给人听）：**

| 意图 | 典型停点 |
|------|----------|
| 自主长篇 | 大纲 / 主题 worker → `review`；正文链多段 → `continue`，直到用户叫停或大纲段落再 `review` |
| 交互 / RP | 产出用户可见终稿的转述（如 narrator）→ `review`；世界裁决等中间层 → `continue` |

创作期按 **§7.2 创作单位** 分块验收（worker 与固定上下文同级），与上表正交。  
design-flow / design-step / 创作调度必须为 **每个** run worker 写出 `acceptance`；缺省时不得假设「全都不用验收」——面向用户的可读输出默认倾向 `review`，纯中间层倾向 `continue`，吃不准就 ask_user。

---

## 7.4 开局 · 开场白（opening-generator）

创作末尾、Worker 集已 accept 之后。此时 **世界设定、故事设定、表结构通常已经很详细**。

**主产物是开场白**（玩家迈进世界的第一段可读文本），不是填表。

```text
结合前面的世界 + 故事 + 表结构 → 写开场白
初值表 = 与开场同一真相的状态快照（辅）
能从已有设定/用户话推出的字段 → 直接填并对齐开场，别问卷
只有开场必须成立却推不出的点 → 轻量 ask_user
```

例：已有校园末日设定 + 用户「普通大学生」→ 开场写宿舍/校园第一拍；表里年龄/资产/身份自然对齐；**不要**先发一张年龄资产问卷。

产出：`输出.开场白`（主）+ `运行.初始变量` / `变量.当前`（辅，字段格）。  
须用户验收。实现：`workers/opening-generator/SKILL.md`。

---

## 8. Play / Run 边界（给编排器；运行时按声明执行）

- 只 `run_worker` 声明内的 ref
- 遇 `acceptance: review` → 停、给人看、接受后压缩再继续
- 遇 `acceptance: continue` → 可在 burst 内续调下一 worker（受 burst 上限约束）
- 表维护 / 副作用可在终稿展示之后延后；写表须尊重字段 `rev` / `source=user`
- 开局类 skill 仅创作末尾可选，禁止当 run 每轮技能