writing-agent/docs/briefs/capability-authoring-brief.md

技能撰写交接简报（泛用）

用途：把本文整份交给另一 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
用编排器按用户体验编排用哪些技能、什么顺序	死板选单 DAG，或全程让 LLM 自由发明工序
产物可解析、可渲染、对人可读	产物里堆满英文变量名让用户难受
运行规格（能复用的声明）与一局游玩过程分离	每种玩法重写一套运行时

1.3 两段生命周期

【创作】选配方 → 编排工作流计划（步骤=技能）→ 逐步执行技能 → 谈成运行规格
        │
        ▼ 用户手动进入
【游玩】用户输入 → 执行单元按规格上场 → 可见终稿；可存档 / 重 roll

• 创作：谈清「这局要什么体验、用哪些技能钉成什么产物」。
• 游玩：按已验收运行规格跑；用户新输入通常视为认可上一轮展示（否则重 roll）。

1.4 运行时怎么分工（撰写技能时必须懂）

角色	做什么	不做什么
编排器	决定下一步调哪个执行单元；编排工作流计划步骤	不直接写小说正文；不私自改相位
程序（Runtime）	校验权限；按契约拼上下文；切步；发 opening；验收门控	不替用户发明体验
技能（modules）	某一步「怎么和用户谈、产出什么形状」的方法正文	不是整场流水线
执行单元（Worker）	一次 LLM 执行（创作期跑技能，或游玩期跑声明内 ref）	不决定全局调度

关键路径：

用户选【配方】（如世界模拟器）
  → design-flow：从【技能】排出**近期**步骤，写出 设计.创作流程（工作流计划）
       （可变增量 DAG：每步 id + 固定中文名 + depends_on；status=open|closed）
  → 用户验收近期流程
  → 反复 design-step：程序注入「当前技能」的 prompt 切片 + 依赖产物
  → 步骤做完仍 open → 再 design-flow（可追加同技能多次，如生成规则 / 具体实例）
  → closed 后收成可进游玩的运行规格，如 设计.worker集
  → 用户手动进游玩

1.5 磁盘上两层内容（作者视角）

【配方】recipes/{配方id}/recipe.yaml     方法论（适用/核心思路/设计流程/原则）+ 近期起点
【技能】modules/{技能id}/prompt.md       共用工序；编排读 meta 选型，执行读方法全文
       modules/catalog.yaml             技能目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）

• 新建作品只选配方一层，不再叠第二层选型。
• 配方给出的步骤是近期起点；本局可增量追加、可反复调用标了 repeatable 的技能；验收的是本局【工作流计划】与【运行规格】，不是磁盘死菜谱。

---

第二部分：称呼定义（必须统一）

对用户与技能正文，优先用下表中文。括号内为业界叫法 / 内部 id，撰写时勿当用户主词堆砌。

2.1 六个核心词

称呼	业界叫法	含义	内部大致对应	禁止对用户说
配方	Recipe	新建时选一次的方法起点（世界模拟器、扩写助手…）	recipes/	导演（旧）、能力包（作第二层选项）
编排器	Orchestrator	会话里负责调度的 Agent	Main Agent / orchestrator	导演、总管（旧）
工作流计划	Workflow Plan / Horizon DAG	本局谈成的近期增量步骤图	设计.创作流程	剧本（旧，流程部分）、死板流程卡
运行规格	Runtime Spec	可进游玩的执行声明	设计.worker集 等	剧本（旧，规格部分）
执行单元	Worker	上场执行的一次单元	Worker / run_worker	演员（旧）；对用户堆 english-id
技能	Skill	共用工序模块；编排器从池里选型编排	modules/{id}/	能力（旧）、组件池

关系口诀：

选配方 → 用技能编排 → 谈成工作流计划 → 收成运行规格 → 执行单元按规格上场

2.2 阶段与界面

称呼	含义
创作	lifecycle design：谈工作流计划与运行规格
游玩	lifecycle play：执行单元上场
产物	某步待验收输出（写入黑板 tag）
验收 / 接受	用户确认产物算数（人工审批）
黑板	按 tag 存正文的上下文板
询问卡	结构化提问（选项可改写）

2.3 创作调度相关（可出现在作者文档，少直接甩给用户）

内部 id	用户可见	含义
design-flow	创作 · 流程编排	编排/增量修订工作流计划 → 设计.创作流程
design-step	创作 · 执行步骤	执行工作流计划中当前那一个技能
opening-generator	开局 · 开场白	可选；规格收成后的开场白

2.4 工作流计划 JSON（编排产物：增量 DAG）

{
  "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 能力在系统中的生命周期

catalog 登记（短声明给编排看；可选 repeatable）
    → 编排器增量选入 设计.创作流程（可同技能多次）
    → 用户验收流程（或后续扩步后再验）
    → 轮到该步：若有 opening → 程序先发出
    → 用户首答 → LLM 按能力方法谈/写
    → 写入 artifact tag → 用户验收
    → 下游能力可读该产物（若 depends_on 声明了）
    → 不够则再 design-flow 追加同能力新 id

3.3 能力作者要交付的两样东西

交付物	路径	给谁看
目录行	modules/catalog.yaml 一行	索引、repeatable、编排 params
方法全文	modules/{id}/prompt.md	执行该步的 LLM + 程序切割；编排读 meta 的 when/when_not/boundary

编排时注入能力 meta 选型字段（非全文 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 标准骨架

# {能力中文名}

> 可选说明。

## 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 一行

- id: example-id
  name: 示例能力中文名
  declaration: >-
    一句话说明何时选用、解决什么
  artifact: 设计.示例能力中文名

字段	谁用
declaration	插入编排提示，选型
name / artifact	流程与执行映射
opening	可选覆盖；一般只写在 prompt 的 opening 块

改 name 会破坏已有工作流计划 JSON，尽量不改。

4.5 opening 节奏（通用）

若 opening 非空：
  程序发 opening → 用户首答 → 再调 LLM
  LLM 上下文含：方法块（通常不含再贴一遍 opening 策略以产品为准）
               + 首答 + 依赖产物 + 用户需求
task 必须写：禁止重复同一开场；在首答上补洞。

4.6 注入 LLM 时包含哪些块

按顺序拼接切割结果，默认不含 opening（开场已由程序发出）。
meta 是否注入以运行实现为准；撰写时把给人/模型的方法写在 task/principles/probe/output/checklist。

4.7 产物（output）通用要求

• 形状稳定，便于 UI 按 JSON 渲染。
• 键名对人友好（中文或稳定中文标签）。
• 机器 id（如 ref）若需要，与中文名成对出现。
• 写清「本步完成的定义」；未决放 开放问题，不要假完备。
• 不要在本技能产物里偷偷交下游能力该交的终稿（除非本技能就是收成步）。
• 中段「上下文创作」技能须输出 §4.9 的 context-fragment.v1（含 schema / brief / 正文）；收成类技能用自有 schema（见 docs/context-fragment-design.md）。

4.8 追问（probe）通用要求

• 一轮 1～2 点，只写进产物 追问（建议选项 + 示例）。
• 程序会把 追问 挂到询问卡；禁止同一问再抄一份顶层 askUser（askUser 留 null）。
• 优先：可直接采用或微调的完整句选项 / 短场景。
• 能推断则先写入再复述；只问影响本步核心且不能瞎填的点。
• 依赖产物已钉死的内容禁止重问。

4.9 上下文片段公共头（context-fragment.v1）

中段技能（美学、机制、世界、叙事、变量…）的产物不是自由发明执行单元，而是可挂载的上下文片段。完整说明见 docs/context-fragment-design.md。

所有上下文创作技能共用三段外壳（键名固定）；正文内部维度与自评维度名按技能自定，但两块都必须有。

{
  "schema": "context-fragment.v1",
  "技能": "{与 catalog 一致的中文名}",
  "brief": "一句话概括",
  "mount": ["world-simulator"],
  "稳变": "stable",
  "正文": { },
  "自评": {
    "维度": [{ "名": "…", "分数": 8, "说明": "…" }],
    "薄弱点": "…"
  },
  "追问": {
    "导语": "…",
    "题目": [
      {
        "问": "…",
        "建议选项": ["…", "其它（请写明）"],
        "示例": "可选短钩子"
      }
    ]
  },
  "开放问题": []
}

段	说明
正文	产物主体。技能自定内部结构（如美学步＝设定逻辑 + 交互范式 + 美学纲领）；须含「详细各个方面」。禁止整份只交散文。
自评	自评评分。维度[] 名目按技能定（美学步常用：交互范式 / 美学纲领 / 整体协调）；分数 为 0–10 十分制（可一位小数；高质约 8–10）；可含 薄弱点。禁止用 0–100 百分数。
追问	示例 + 建议选项。给用户的下一问（程序挂询问卡）；题目 可空数组。禁止同一问再写入顶层 askUser。

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

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

第五部分：撰写任一能力时的工作步骤

1. 定身份：中文名、id、artifact；写清 when / when_not / boundary。
2. 看邻接：上/下游能力各定什么；禁止重叠问卷。
3. 定产物形状：先定 output JSON（中段须含 §4.9 公共头），再写 task/probe 如何填满它。
4. 定 opening：需要程序先问再 LLM → 写 opening；否则留空。
5. 写 principles / probe / checklist：正推、缩减、禁止套件；checklist 含 schema/brief/正文。
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 文件正文。

出题方填写：

能力中文名：
id：
artifact：
上游依赖（常见）：
明确不做（交给谁）：
特殊产物要求（可选）：

---

第七部分：当前技能池速查（选题，非本文重点）

世界模拟器常用（编排按需，勿默认全选）：

能力	id	状态（以仓库为准）
美学纲领与交互范式	aesthetics-interaction	范例
实现机制	mechanism	已写
舞台骨架	world-blueprint	已写（context-fragment.v1；社会结构 + 世界状况）
生成规则	generation-rules	已写（context-fragment.v1；可反复；合同严、正文可长）
具体实例	concrete-instances	已写（context-fragment.v1；可反复；只按规则执行）
叙事指南与故事推进	narrative	已写（context-fragment.v1；遣词/笔墨/禁忌+推进；旧称叙事指南）
正文组成	reply-format	已写（用户可见版式+隐藏段+前端拆分；旧称设计回复格式）
设计监控栏	status-bar	已写（只盯会变信息；旧称设计状态栏）
开场白与开场变量	opening-setup	已写（开场正文+初值；守正文组成）
拓扑图谱	topology	待细写
变量设计与更新规则	variable-design	已写；见 progressive-data-design.md
变量控制上下文	variable-context	已写
游玩拓扑	worker-spec	已写（勾选固定槽，不可反复发明）
细化终稿	refine	已写（按槽收成）

配方：世界模拟器、扩写助手（见 recipes/；写 core/process/principles + 起步 steps）。

---

附录：与旧文档关系

文档	关系
本文	泛用能力撰写 + 项目/称呼；给外部 AI 的主交接
world-simulator-modules.md	仓库内清单与格式摘要
context-fragment-design.md	片段 schema、槽位、投影排序与拼装阶段
ui-glossary.md	用户可见文案权威
architecture.md	运行内核；写能力时不必复述实现细节
（已删）单能力特例简报	以本文为准；勿再恢复特例交接文