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

1.3 两段生命周期

【创作 design】选导演 → 编排剧本（步骤=能力）→ 逐步执行能力 → 谈成可运行规格
        │
        ▼ 用户手动进入
【游玩 play】用户输入 → 演员按规格上场 → 可见终稿；可存档 / 重 roll

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

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

角色	做什么	不做什么
导演（Agent）	决定下一步调哪个演员；编排剧本步骤	不直接写小说正文；不私自改相位
程序（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       共用工序；多导演可选用同一能力
       modules/catalog.yaml             能力目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）

• 新建作品只选导演一层，不再叠「能力包 + 配方」。
• 导演给出的步骤是近期起点；本局可增量追加、可反复调用标了 repeatable 的能力；验收的是本局【剧本】，不是磁盘死菜谱。

---

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

对用户与能力正文，优先用拍摄隐喻。括号内为内部/旧称，撰写时勿当用户主词。

2.1 四个核心词

称呼	含义	内部大致对应	禁止对用户说
导演	① 新建时选一次的方法起点（世界模拟器、扩写助手…）；② 会话里负责调度的 Agent	recipes/、Main Agent / orchestrator	总管、配方（作选型主词）、能力包（作第二层选项）
剧本	本局谈成的流程与规格（活的）	设计.创作流程 + 各能力产物 + 终稿 设计.worker集 等	「剧本 Skill 菜单」、死板流程卡
演员	上场执行的一次单元	Worker / run_worker	对用户堆 Worker · english-id
能力	共用工序模块；导演从池里选型编排	modules/{id}/	组件池、模块（作者文档可用；用户文案用「能力」）

关系口诀：

选导演 → 用能力编排 → 谈成剧本 → 演员按剧本上场

2.2 阶段与界面

称呼	含义
创作	lifecycle design：谈剧本
游玩	lifecycle play：演员上场
产物	某步待验收输出（写入黑板 tag）
验收 / 接受	用户确认产物算数
黑板	按 tag 存正文的上下文板
询问卡	结构化提问（选项可改写）

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

内部 id	用户可见	含义
design-flow	创作 · 流程编排	编排/增量修订可变 DAG → 设计.创作流程
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 一行	编排：只看短 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 标准骨架

# {能力中文名}

> 可选说明。

## 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.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 文件正文。

出题方填写：

能力中文名：
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	已过时为「单能力特例」；以本文为准