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

> **用途**：把本文**整份**交给另一 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 两段生命周期

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

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

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

| 角色 | 做什么 | 不做什么 |
|------|--------|----------|
| **编排器** | 决定下一步调哪个执行单元；编排工作流计划步骤 | 不直接写小说正文；不私自改相位 |
| **程序（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       共用工序；编排读 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}/` | 能力（旧）、组件池 |

关系口诀：

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

## 2.2 阶段与界面

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

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

| 内部 id | 用户可见 | 含义 |
|---------|----------|------|
| `design-flow` | 创作 · 流程编排 | 编排/增量修订工作流计划 → `设计.创作流程` |
| `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` 一行 | 索引、`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 标准骨架

````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.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`**。

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

```json
{
  "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 文件正文。

出题方填写：

```text
能力中文名：
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` | 运行内核；写能力时不必复述实现细节 |
| （已删）单能力特例简报 | 以本文为准；勿再恢复特例交接文 |