chenmoranzhi/writing-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善配方驱动的创作编排

Browse Source 
为可重复技能补充参数校验与展示，统一配方、编排器和执行单元术语。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
moran
2026-07-30 17:59:20 +08:00
parent e670a5129c
commit 6392af54b4
49 changed files with 1671 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
docs/briefs/capability-authoring-brief.md
View File

@@ -1,11 +1,11 @@
# 能力撰写交接简报（泛用）
# 技能撰写交接简报（泛用）
> **用途**：把本文**整份**交给另一 AI / 作者，用于撰写任意【能力】的 `modules/{id}/prompt.md`。
> **用途**：把本文**整份**交给另一 AI / 作者，用于撰写任意【技能】的 `modules/{id}/prompt.md`。
> **本文是自洽规范**：不依赖读者已熟悉本仓库。
> **不要**让撰写方改程序代码；**不要**只写某一能力的特例而不遵守通用格式。
> **不要**让撰写方改程序代码；**不要**只写某一技能的特例而不遵守通用格式。
范例（深度与结构对齐）：`skills/dialogue/world-simulator/modules/aesthetics-interaction/prompt.md`
能力池清单（选题用）：`docs/world-simulator-modules.md`
技能池清单（选题用）：`docs/world-simulator-modules.md`
术语权威：`docs/ui-glossary.md` §0
---
@@ -14,91 +14,93 @@
## 1.1 一句话
**writing-agent** 是本地运行的多 Agent **文本创作 / 游玩**系统：用户选一个【导演】，在【创作】期谈成【剧本】，再在【游玩】期让【演员】按剧本上场，产出可读文本（角色扮演、长文/爽文、扩写、思想实验等共用同一内核）。
**writing-agent** 是本地运行的多 Agent **文本创作 / 游玩**系统：用户选一个【配方】，在【创作】期谈成【工作流计划】与【运行规格】，再在【游玩】期让【执行单元】按规格上场，产出可读文本（角色扮演、长文/爽文、扩写、思想实验等共用同一内核）。
## 1.2 要解决什么问题
| 要 | 不要 |
|----|------|
| 用程序控制「每一步注入什么上下文」 | 把整本长说明书一次塞进 LLM |
| 用 Agent 按用户体验**编排**用哪些能力、什么顺序 | 死板选单 DAG，或全程让 LLM 自由发明工序 |
| 用编排器按用户体验**编排**用哪些技能、什么顺序 | 死板选单 DAG，或全程让 LLM 自由发明工序 |
| 产物可解析、可渲染、对人可读 | 产物里堆满英文变量名让用户难受 |
| 规格（能复用的声明）与一局游玩过程分离 | 每种玩法重写一套运行时 |
| 运行规格（能复用的声明）与一局游玩过程分离 | 每种玩法重写一套运行时 |
## 1.3 两段生命周期
```text
【创作 design】选导演 → 编排剧本（步骤=能力）→ 逐步执行能力 → 谈成可运行规格
【创作】选配方 → 编排工作流计划（步骤=技能）→ 逐步执行技能 → 谈成运行规格
│
▼ 用户手动进入
【游玩 play】用户输入 → 演员按规格上场 → 可见终稿；可存档 / 重 roll
【游玩】用户输入 → 执行单元按规格上场 → 可见终稿；可存档 / 重 roll
```
- **创作**：谈清「这局要什么体验、用哪些能力钉成什么产物」。
- **游玩**：按已验收规格跑；用户新输入通常视为认可上一轮展示（否则重 roll）。
- **创作**：谈清「这局要什么体验、用哪些技能钉成什么产物」。
- **游玩**：按已验收运行规格跑；用户新输入通常视为认可上一轮展示（否则重 roll）。
## 1.4 运行时怎么分工（撰写能力时必须懂）
## 1.4 运行时怎么分工（撰写技能时必须懂）
| 角色 | 做什么 | 不做什么 |
|------|--------|----------|
| **导演（Agent）** | 决定下一步调哪个演员；编排剧本步骤 | 不直接写小说正文；不私自改相位 |
| **编排器** | 决定下一步调哪个执行单元；编排工作流计划步骤 | 不直接写小说正文；不私自改相位 |
| **程序（Runtime）** | 校验权限；按契约拼上下文；切步；发 opening；验收门控 | 不替用户发明体验 |
| **能力（modules）** | 某一步「怎么和用户谈、产出什么形状」的方法正文 | 不是整场流水线 |
| **演员（Worker）** | 一次 LLM 执行（创作期跑能力，或游玩期跑声明内 ref） | 不决定全局调度 |
| **技能（modules）** | 某一步「怎么和用户谈、产出什么形状」的方法正文 | 不是整场流水线 |
| **执行单元（Worker）** | 一次 LLM 执行（创作期跑技能，或游玩期跑声明内 ref） | 不决定全局调度 |
关键路径：
```text
用户选【导演】（如世界模拟器）
→ design-flow：从【能力】排出**近期**步骤，写出 设计.创作流程
用户选【配方】（如世界模拟器）
→ design-flow：从【技能】排出**近期**步骤，写出 设计.创作流程（工作流计划）
（可变增量 DAG：每步 id + 固定中文名 + depends_on；status=open|closed）
→ 用户验收近期流程
→ 反复 design-step：程序注入「当前能力」的 prompt 切片 + 依赖产物
→ 步骤做完仍 open → 再 design-flow（可追加同能力多次，如生成规则 / 具体实例）
→ closed 后收成可进游玩的规格，如 设计.worker集
→ 反复 design-step：程序注入「当前技能」的 prompt 切片 + 依赖产物
→ 步骤做完仍 open → 再 design-flow（可追加同技能多次，如生成规则 / 具体实例）
→ closed 后收成可进游玩的运行规格，如 设计.worker集
→ 用户手动进游玩
```
## 1.5 磁盘上两层内容（作者视角）
```text
【导演】recipes/{导演id}/recipe.yaml 该方法的建议近期起点 / 调味说明
【能力】modules/{能力id}/prompt.md 共用工序；多导演可选用同一能力
modules/catalog.yaml 能力目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）
【配方】recipes/{配方id}/recipe.yaml 方法论（适用/核心思路/设计流程/原则）+ 近期起点
【技能】modules/{技能id}/prompt.md 共用工序；编排读 meta 选型，执行读方法全文
modules/catalog.yaml 技能目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）
```
- 新建作品**只选导演一层**，不再叠「能力包 + 配方」。
- 导演给出的步骤是**近期起点**；本局可增量追加、可反复调用标了 `repeatable` 的能力；验收的是本局【剧本】，不是磁盘死菜谱。
- 新建作品**只选配方一层**，不再叠第二层选型。
- 配方给出的步骤是**近期起点**；本局可增量追加、可反复调用标了 `repeatable` 的技能；验收的是本局【工作流计划】与【运行规格】，不是磁盘死菜谱。
---
# 第二部分：称呼定义（必须统一）
对用户与能力正文，优先用**拍摄隐喻**。括号内为内部/旧称，撰写时勿当用户主词。
对用户与技能正文，优先用下表中文。括号内为业界叫法 / 内部 id，撰写时勿当用户主词堆砌。
## 2.1 四个核心词
## 2.1 六个核心词
| 称呼 | 含义 | 内部大致对应 | 禁止对用户说 |
|------|------|--------------|--------------|
| **导演** | ① 新建时选一次的方法起点（世界模拟器、扩写助手…）；② 会话里负责调度的 Agent | `recipes/`、Main Agent / orchestrator | 总管、配方（作选型主词）、能力包（作第二层选项） |
| **剧本** | 本局谈成的流程与规格（活的） | `设计.创作流程` + 各能力产物 + 终稿 `设计.worker集` 等 | 「剧本 Skill 菜单」、死板流程卡 |
| **演员** | 上场执行的一次单元 | Worker / `run_worker` | 对用户堆 `Worker · english-id` |
| **能力** | 共用工序模块；导演从池里选型编排 | `modules/{id}/` | 组件池、模块（作者文档可用；用户文案用「能力」） |
| 称呼 | 业界叫法 | 含义 | 内部大致对应 | 禁止对用户说 |
|------|----------|------|--------------|--------------|
| **配方** | 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`：演员上场 |
| **创作** | lifecycle `design`：谈工作流计划与运行规格 |
| **游玩** | lifecycle `play`：执行单元上场 |
| **产物** | 某步待验收输出（写入黑板 tag） |
| **验收 / 接受** | 用户确认产物算数 |
| **验收 / 接受** | 用户确认产物算数（人工审批） |
| **黑板** | 按 tag 存正文的上下文板 |
| **询问卡** | 结构化提问（选项可改写） |
@@ -106,11 +108,11 @@
| 内部 id | 用户可见 | 含义 |
|---------|----------|------|
| `design-flow` | 创作 · 流程编排 | 编排/增量修订可变 DAG → `设计.创作流程` |
| `design-step` | 创作 · 执行步骤 | 执行剧本中当前那一个能力 |
| `design-flow` | 创作 · 流程编排 | 编排/增量修订工作流计划 → `设计.创作流程` |
| `design-step` | 创作 · 执行步骤 | 执行工作流计划中当前那一个技能 |
| `opening-generator` | 开局 · 开场白 | 可选；规格收成后的开场白 |
## 2.4 剧本流程 JSON（编排产物：增量 DAG）
## 2.4 工作流计划 JSON（编排产物：增量 DAG）
```json
{
@@ -128,52 +130,53 @@
|------|------|
| `status` | `open` = 还可追加；`closed` = 不再扩步。缺省兼容旧稿视为已收口 |
| `steps` 顺序 | 建议执行顺序 |
| `id` | 本局步骤唯一键；同能力多次必须不同 |
| `name` | 必须与能力目录中的**固定中文名**完全一致（可重复） |
| `id` | 本局步骤唯一键；同技能多次必须不同 |
| `name` | 必须与技能目录中的**固定中文名**完全一致（可重复） |
| `depends_on` | 依赖的其它步骤 **id**（若某 name 在本流程唯一，也可写 name） |
程序用中文 `name` 映射到 `artifact` tag；流程 JSON **不写**英文模块 id / tag。
**禁止**一次排死全程固定长链；「生成规则」「具体实例」等标了 `repeatable` 的能力应允许多次编入。
**禁止**一次排死全程固定长链；「生成规则」「具体实例」等标了 `repeatable` 的技能应允许多次编入。
## 2.5 已合并能力（勿拆回）
## 2.5 已合并技能（勿拆回）
| 错误拆法 | 正确能力 |
| 错误拆法 | 正确技能 |
|----------|----------|
| 「交互范式」+「美学纲领」两步 | **美学纲领与交互范式**（`aesthetics-interaction`）一步 |
询问相近则合并为一步；不要在新能力里建议再拆开。
询问相近则合并为一步；不要在新技能里建议再拆开。
## 2.6 命名纪律
| 种类 | 规则 | 例 |
|------|------|-----|
| 能力中文名 | 稳定、给人看、进流程 JSON | `实现机制` |
| 能力 id | 英文 kebab，= 文件夹名 | `mechanism` |
| 技能中文名 | 稳定、给人看、进流程 JSON | `实现机制` |
| 技能 id | 英文 kebab，= 文件夹名 | `mechanism` |
| 产物 tag | 通常 `设计.{中文名或约定名}` | `设计.实现机制` |
| 游玩演员 ref | 英文 kebab | `narrator` |
| 游玩演员展示名 | 中文 `name` | `叙事转述` |
| 游玩执行单元 ref | 英文 kebab | `narrator` |
| 游玩执行单元展示名 | 中文 `name` | `叙事转述` |
| UI | 禁止裸露内部英文 id | 不要写 `design-step` 给用户 |
---
# 第三部分：什么是「能力」（泛用定义）
# 第三部分：什么是「技能」（泛用定义）
## 3.1 定义
**能力** = 创作期可被编排进剧本的**一步工序**：
**技能** = 创作期可被编排进工作流计划的**一步工序**：
1. 有固定中文名与产物 tag；
2. 有一份程序可切割的方法文档（`prompt.md`）；
3. 执行时只注入**本能力**方法 + **依赖产物** + 用户表述；
3. 执行时只注入**本技能**方法 + **依赖产物** + 用户表述；
4. 与用户对话后产出**可验收**的结构化结果。
能力**不是**：整场游戏引擎、游玩期每轮演员、也不是导演本身。
技能**不是**：整场游戏引擎、游玩期每轮执行单元、也不是配方/编排器本身。
## 3.2 能力在系统中的生命周期
```text
catalog 登记（短声明给编排看；可选 repeatable）
→ 导演/编排增量选入 设计.创作流程（可同能力多次）
→ 编排器增量选入 设计.创作流程（可同技能多次）
→ 用户验收流程（或后续扩步后再验）
→ 轮到该步：若有 opening → 程序先发出
→ 用户首答 → LLM 按能力方法谈/写
@@ -185,25 +188,25 @@ catalog 登记（短声明给编排看；可选 repeatable）
| 交付物 | 路径 | 给谁看 |
|--------|------|--------|
| 目录行 | `modules/catalog.yaml` 一行 | 编排：只看短 `declaration` |
| 方法全文 | `modules/{id}/prompt.md` | 执行该步的 LLM + 程序切割 |
| 目录行 | `modules/catalog.yaml` 一行 | 索引、`repeatable`、编排 `params` |
| 方法全文 | `modules/{id}/prompt.md` | 执行该步的 LLM + 程序切割；**编排读 `meta` 的 when/when_not/boundary** |
编排时**禁止**把全文 prompt 塞进导演上下文；执行时才注入切割后的方法块。
编排时注入能力 **meta 选型字段**（非全文 prompt）；执行时才注入切割后的方法块。
## 3.4 能力之间如何相处
- **正推**：需要 [体验/产物] → 才纳入某能力；勿默认全选池内能力。
- **正推**：需要 [体验/产物] → 才纳入某技能；勿默认全选池内能力。
- **边界**：每个能力在 `meta.boundary` 写清「本步定什么 / 不定什么 / 交给谁」。
- **依赖**：由剧本 `depends_on` 声明；执行期程序注入对应产物。
- **依赖**：由工作流计划 `depends_on` 声明；执行期程序注入对应产物。
- **合并**：询问主题高度重叠 → 合成一个能力（如美学+交互）。
- **缩减**：每增必问能否删、能否常驻替代、能否合并。
## 3.5 方法层硬禁止（写任何能力都适用）
- 题材 → 固定演员清单。
- 题材 → 固定执行单元清单。
- 否定式路由（「因为是 X 所以不需要 Y」）；应写「需要 A 体验 → 用 B 手段」。
- 把「世界模拟」当成一切开场的默认答案。
- 为排版/格式单独发明演员；能程序拼则程序拼。
- 为排版/格式单独发明执行单元；能程序拼则程序拼。
- 临时发明 tool。
- 一次 burst 写齐全部能力产物。
- 在能力产物里堆大量用户看不懂的英文变量名（机器 id 可有，但须有中文展示字段）。
@@ -251,7 +254,7 @@ when: |
when_not: |
{什么情况下不要进来}
boundary: |
本能力：…
本技能：…
邻接能力：…（点名其它能力中文名，说明分工）
```
@@ -306,7 +309,7 @@ boundary: |
| `id` | 英文 id（= 目录名） |
| `artifact` | 本步写入的黑板 tag |
| `declaration` | 给编排看的短声明（不是全文） |
| `when` / `when_not` | 何时该/不该入选剧本 |
| `when` / `when_not` | 何时该/不该入选工作流计划 |
| `boundary` | 与邻接能力的分工 |
## 4.4 `catalog.yaml` 一行
@@ -321,11 +324,11 @@ boundary: |
| 字段 | 谁用 |
|------|------|
| `declaration` | 插入导演/编排提示，选型 |
| `declaration` | 插入编排提示，选型 |
| `name` / `artifact` | 流程与执行映射 |
| `opening` | 可选覆盖；一般只写在 prompt 的 `opening` 块 |
改 `name` 会破坏已有剧本 JSON，尽量不改。
改 `name` 会破坏已有工作流计划 JSON，尽量不改。
## 4.5 opening 节奏（通用）
@@ -348,7 +351,7 @@ task 必须写：禁止重复同一开场；在首答上补洞。
- **键名对人友好**（中文或稳定中文标签）。
- 机器 id（如 `ref`）若需要，与中文名成对出现。
- 写清「本步完成的定义」；未决放 `开放问题`，不要假完备。
- 不要在本能力产物里偷偷交下游能力该交的终稿（除非本能力就是收成步）。
- 不要在本技能产物里偷偷交下游能力该交的终稿（除非本技能就是收成步）。
## 4.8 追问（`probe`）通用要求
@@ -373,7 +376,7 @@ task 必须写：禁止重复同一开场；在首答上补洞。
# 第六部分：给撰写 AI 的通用任务指令（粘贴用）
请撰写（或重写）一个【能力】文档：
请撰写（或重写）一个【技能】文档：
`skills/dialogue/world-simulator/modules/{id}/prompt.md`
（具体中文名 / id / 边界由出题方在指令末行指定。）
@@ -381,7 +384,7 @@ task 必须写：禁止重复同一开场；在首答上补洞。
1. 本文**第一部分～第四部分**的项目理解、称呼与格式契约。
2. 只使用规定的 fence 块；不要发明新 fence 名。
3. 对用户话术使用导演/剧本/演员/能力；不要写「总管调度 design-xxx」。
3. 对用户话术使用配方/编排器/工作流计划/执行单元/技能；不要写「编排器调度 design-xxx」。
4. 正推：体验 → 手段；禁止题材套件与否定式路由。
5. 交互与美学已合并为「美学纲领与交互范式」；禁止建议拆回两步。
6. 不要修改程序代码；默认只交付 `prompt.md`（除非出题方要求改 catalog）。
@@ -400,27 +403,27 @@ artifact：
---
# 第七部分：当前能力池速查（选题，非本文重点）
# 第七部分：当前技能池速查（选题，非本文重点）
世界模拟器常用（编排按需，勿默认全选）：
| 能力 | id | 状态（以仓库为准） |
|------|-----|-------------------|
| 美学纲领与交互范式 | `aesthetics-interaction` | 范例 |
| 实现机制 | `mechanism` | 待细写 |
| 实现机制 | `mechanism` | 已写 |
| 世界蓝图与人文地理 | `world-blueprint` | 已写 |
| 生成规则 | `generation-rules` | 待细写 |
| 具体实例 | `concrete-instances` | 待细写 |
| 生成规则 | `generation-rules` | 已写（可反复） |
| 具体实例 | `concrete-instances` | 已写（可反复） |
| 叙事指南 | `narrative` | 已写 |
| 拓扑图谱 | `topology` | 待细写 |
| 叙事指南 | `narrative` | 待细写 |
| 变量设计与更新规则 | `variable-design` | 待细写 |
| 变量控制上下文 | `variable-context` | 待细写 |
| 设计状态栏 | `status-bar` | 待细写 |
| 设计回复格式 | `reply-format` | 待细写 |
| Worker 规格 | `worker-spec` | 待细写 |
| 细化终稿 | `refine` | 待细写 |
| Worker 规格 | `worker-spec` | 已写（可反复） |
| 细化终稿 | `refine` | 已写 |
导演示例：世界模拟器、扩写助手（见 `recipes/`）。
配方：世界模拟器、扩写助手（见 `recipes/`；写 `core`/`process`/`principles` + 起步 steps）。
---
@@ -432,4 +435,4 @@ artifact：
| `world-simulator-modules.md` | 仓库内清单与格式摘要 |
| `ui-glossary.md` | 用户可见文案权威 |
| `architecture.md` | 运行内核；写能力时不必复述实现细节 |
| 旧 `capability-mechanism-handoff.md` | 已过时为「单能力特例」；以本文为准 |
| （已删）单能力特例简报 | 以本文为准；勿再恢复特例交接文 |