Files
writing-agent/docs/briefs/capability-authoring-brief.md
moranzhi 94f67fa744 引入上下文片段、固定槽与投影排序,并完善机遇裁定与游玩期 UI。
把创作产物收敛为可挂载片段与 play_slots/context_order,同步修订世界模拟器模块与运行时拼装。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-03 01:36:32 +08:00

489 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 技能撰写交接简报(泛用)
> **用途**:把本文**整份**交给另一 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_onstatus=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
{缺什么问什么;一轮 12 点;优先具体选项/短场景;勿重复已答清}
```
## 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`)通用要求
- 一轮 askUser **12** 点。
- 优先:可直接采用或微调的完整句选项 / 短场景。
- 能推断则先写入再复述;只问影响本步核心且不能瞎填的点。
- 依赖产物已钉死的内容禁止重问。
## 4.9 上下文片段公共头(`context-fragment.v1`
中段技能(美学、机制、世界、叙事、变量…)的产物**不是**自由发明执行单元,而是可挂载的上下文片段。完整说明见 **`docs/context-fragment-design.md`**。
**所有上下文创作技能**共用三段外壳(键名固定);**正文内部维度**与**自评维度名**按技能自定,但两块都必须有。
```json
{
"schema": "context-fragment.v1",
"技能": "{与 catalog 一致的中文名}",
"brief": "一句话概括",
"mount": ["world-simulator"],
"稳变": "stable",
"正文": { },
"自评": {
"维度": [{ "名": "…", "分数": 0, "说明": "…" }],
"薄弱点": "…"
},
"追问": {
"导语": "…",
"题目": [
{
"问": "…",
"建议选项": ["…", "其它(请写明)"],
"示例": "可选短钩子"
}
]
},
"开放问题": []
}
```
| 段 | 说明 |
|----|------|
| `正文` | **产物主体**。技能自定内部结构(如美学步=设定逻辑 + 交互范式 + 美学纲领);须含「详细各个方面」。禁止整份只交散文。 |
| `自评` | **自评评分**。`维度[]` 名目按技能定(美学步常用:交互范式 / 美学纲领 / 整体协调);可含 `薄弱点`。 |
| `追问` | **示例 + 建议选项**。给用户的下一问;`题目` 可空数组。与程序 askUser 可并存,但产物里要留结构化题面。 |
| 规则 | 说明 |
|------|------|
| `schema` | 必须原样写出,供前端友好渲染 |
| `mount` | 挂哪些槽/ref**不要**写最终数字 `order` |
| `稳变` | `stable` \| `semi` \| `volatile`,供「上下文投影排序」 |
| 收成例外 | 游玩拓扑 / 上下文投影排序 / 细化终稿用自有 schema不套本头 |
范例对齐:`modules/aesthetics-interaction/prompt.md`output 块)。
---
# 第五部分:撰写任一能力时的工作步骤
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` | 运行内核;写能力时不必复述实现细节 |
| (已删)单能力特例简报 | 以本文为准;勿再恢复特例交接文 |