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

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

文档层级：工作流计划 / 创作方法（非系统架构）。
运行内核边界见 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. 总原则

三大步（每步含自检，可反复，无强制题材工序）
  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 建议结构（按需删维）：

# 内容维度
核心感觉: 完备度 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 字段格版本（防互相覆盖）

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

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[]）：

{
  "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 不能替代依赖传递。

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

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

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

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

正推仍成立：需要维持 [体验/边界/呈现] 且宜稳定注入 → 固定上下文；会变 → 表；本轮推理 → 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 创作顺序（软）

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

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

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

6.4 常驻条目与预设

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

{
  "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）。

创作会话（简单）

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

创作折叠（简单）

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

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

Run 压缩（与创作正交）

用户在 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 之后。此时 世界设定、故事设定、表结构通常已经很详细。

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

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