Files

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

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-30 17:59:20 +08:00

19 KiB

Raw Blame History

Skill 格式与存储

文档层级：Skill 包格式（非系统架构）。
系统级模块与调度边界见 architecture.md。

现行唯一落地包：skills/dialogue/world-simulator/（见该包 README、world-simulator-modules.md）。
下文部分示例仍保留历史 novel/ / weird-rules-short 树形说明，仓库内已不存在；写新内容请以 world-simulator 为准。
创作流水线现行名：design-flow + design-step（旧称 design-intake 已废弃）。

1. 定位：两层 Skill

本项目有 两种 Skill 文档，不要混在一个文件里：

类型	路径	消费者	写什么
编排器 Skill	`skills/{bookKind}/{name}/orchestrator.md`	Main Agent	何时调哪个 worker、验收方式、启动询问
Worker Skill	`workers/{workerId}/SKILL.md`	Worker Agent	inputTags/outputTags、怎么做

选 weird-rules-short（编排器 Skill）
  → 编排器：brief 齐了 → run ruleset-worker，input=[project.brief]
  → Worker：读 workers/ruleset-worker/SKILL.md → 写 core / rules / commentary
  → 编排器：rules accepted → run review-worker
  → Worker：读 workers/review-worker/SKILL.md → 评估怎么做

何时评估 = 编排器 Skill 的 Worker 编排表。
如何评估 = review-worker 的 Worker Skill。

详细规范：

编排器 Skill → docs/orchestrator-skill-format.md
Worker Skill → docs/worker-skill-format.md

旧称「Skill = 创作说明书」仍成立，但说明书 拆成编排（编排器）与执行（worker）两份。

会话开始
  → 询问 1：选哪个编排器 Skill（skills/{bookKind}/{name}/orchestrator.md）
  → 加载编排器 Skill
  → 询问 2：读编排器 Skill「## 启动询问」
  → 之后编排器按「Worker 编排」调度；Worker 读本 skill 包内 workers/{id}/SKILL.md

2. 存储位置

Skill 以 Skill 包（skill pack） 为单位：一个编排器 + 其专属 workers，同包绑定，不跨包复用 worker。

skills/
├── registry.yaml
├── novel/                                    # Book 形态
│   ├── basic/
│   │   └── orchestrator.md                   # 编排器 Skill
│   ├── weird-rules-short/
│   │   ├── orchestrator.md                   # 编排器：何时调谁、黑板 key
│   │   └── workers/                          # 本编排器专属，不与其他 skill 共享
│   │       ├── write-rules/
│   │       │   └── SKILL.md                  # 规则怪谈：怎么写规则+解析
│   │       └── review/
│   │           └── SKILL.md                  # 规则怪谈：怎么检查
│   └── novel-standard/
│       ├── orchestrator.md
│       └── workers/
│           ├── outline/SKILL.md
│           └── drafting/SKILL.md
└── dialogue/
    └── theater-roleplay/
        ├── orchestrator.md
        └── workers/
            └── turn/SKILL.md

规则：

第一层文件夹 = bookKind（novel | dialogue），决定 Book 存储结构
第二层文件夹 = 一个 skill 包，名与 frontmatter.name 一致
  orchestrator.md   编排器 Skill（编排、启动询问、验收）
  workers/{id}/     本包专属 worker；id 在包内唯一即可
Worker 不复用：novel-standard 的 outline worker ≠ weird-rules-short 的任何 worker
registry.yaml 的 path 指向 orchestrator.md，如 novel/weird-rules-short/orchestrator.md

为何不复用 worker： 同一「产出形状」（如规则表）在不同编排器下的写法、Rubric、自检完全不同；共享 worker 会把体裁细节塞进编排器或搞混上下文。需要相似流程时 复制 worker 包再改，而不是引用全局 worker。

与 Cursor skill 的区别：

	Cursor Skill	本项目 Skill
位置	`.cursor/skills/`	`skills/`
触发	Agent 自动或显式引用	会话开始必须选一个
内容	通用任务指南	创作流程 + 思维链 + 询问策略
消费者	Cursor Agent	编排器 LLM

3. SKILL.md 结构

3.0 两层分类（重要）

Skill 分类分两层，不要混为一层：

第一层：Book 形态（category / bookKind，选定后不可换）
  novel     类小说存储：卷、章、大纲、正文（含各类小说子类型）
  dialogue  多轮多角色对话：回合、角色、场景（roleplay / 剧场）

第二层：具体 Skill 包（name，用户启动时选）
  每个包 = orchestrator.md + workers/，不是 category 下的平铺 .md 枚举。

示例：

category: novel          ← 第一层：Book 怎么存
name: novel-standard       ← 第二层：标准长篇流程
name: weird-rules-short    ← 第二层：规则怪谈短篇（仍是 novel Book）
name: basic               ← 第二层：最小演示

category: dialogue
name: theater-roleplay     ← 第二层：剧场式多角色互动

不要把「规则怪谈」做成与 novel 平级的 category。
规则怪谈是 novel 形态下的专精 skill，用 name + tags 区分：

---
name: weird-rules-short
description: 短篇规则怪谈：从隐含核心反推护命规则，再成章撰写。
category: novel
bookKind: novel
tags: [novel, weird_rules, short, horror]
---

层级	字段	谁选	例子
Book 形态	`category` / `bookKind`	选 skill 时确定，之后不变	`novel` / `dialogue`
具体流程	`name`	启动询问 1：选哪个 SKILL.md	`weird-rules-short`
体裁标签	`tags`	可选，供匹配与过滤	`weird_rules`, `standard`

启动 UI 可以按 category 分组展示，组内列出多个 name（如「小说」下：标准长篇、规则怪谈短篇、…）。

参考 Cursor SKILL.md：YAML frontmatter + Markdown 正文。

---
name: novel-standard
description: >-
  标准长篇小说创作：先简报、再大网、事件细化、正文。
  适用于用户要写小说、章节、大纲时使用。
category: novel
version: 1
defaultFlowId: ghostwriting-flow
tags: [novel, outline, draft]
---

# 标准小说创作

## 启动询问

（流程 2：选 skill 后向用户展示什么、必收集项、写入 book.brief）

## 创作总纲

（给编排器：这类内容是什么、总体顺序、禁忌）

## 编排器思维链

（每轮决策前先检查什么、如何选 worker）

## 推荐阶段

（brief → outline → plotline → style → draft）

## 询问策略

### 编排器应先问
### 交给 Worker 问

## 推荐 Worker

## 示例

3.1 Frontmatter 字段

---
name: novel-standard                    # 必需，唯一 id，[a-z0-9-]
description: >                          # 必需，供启动时向用户展示、供编排器匹配
  第三人称描述 WHAT + WHEN。
category: novel                         # 必需：Book 形态，见 §3.0
bookKind: novel                         # 建议与 category 对齐；选定后 Book 结构固定
version: 1
defaultFlowId: ghostwriting-flow        # 可选，绑定 execution flow
defaultPresetId: writing-default        # 可选
tags: [novel, standard]                 # 体裁/子类型标签，如 weird_rules、short
suggestedWorkers:                       # 可选，本 skill 常用 worker
  - outline-worker
  - plotline-worker
  - drafting-worker
---

字段	必需	用途
`name`	✅	skill id；通常与文件名一致（不含 .md）
`description`	✅	启动选择列表展示；编排器判断用户描述是否匹配
`category`	✅	与 `bookKind` 一致：`novel` \| `dialogue`
`bookKind`	建议	选定后 Book 结构固定；缺省时由所在文件夹推断
`tags`		体裁细分：`weird_rules`、`standard` 等
`path`	registry	相对路径，如 `novel/weird-rules-short.md`
`defaultFlowId`		选中后默认 execution flow
`suggestedWorkers`		编排器选 worker 时的白名单提示

3.2 撰写标准：写作生命周期（推荐）

Skill 文件本质上是给 LLM 与 Runtime 读的字符串规格。下面这套「触发 → 写前 → 写中 → 写后 → 质量维度」与现有阶段机、验收模式对齐，应作为所有 skill .md 的撰写标准。

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  触发条件    │ → │  写作前      │ → │  写作中      │ → │  写作后      │ → │  质量维度    │
│  何时激活    │   │  需求分析    │   │  分步引导    │   │  自检润色    │   │  可量化 Rubric│
└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
     frontmatter        启动询问          推荐阶段          自检清单         质量评估标准
     + tags             + 创作总纲        + 示例/约束       + 验收策略       + 接受度(预留)
                        + 询问策略        + 禁用行为

与正文章节的对应关系

生命周期	对应章节	写什么
触发条件	frontmatter `description` + `tags`	何时应选本 skill；用户说什么话时应匹配（如「规则怪谈」「短篇怪谈」）
写作前 · 需求分析	`## 启动询问` + `## 创作总纲`	对象、受众、语气、目标、禁忌；禁止直接动笔；写入哪个 key
写作中 · 分步引导	`## 推荐阶段` + `## 示例` + `## 禁用行为`	阶段链、每步约束、好/坏示例；对应 worker 与产出 key
写作后 · 自检润色	`## 自检清单` + `## 验收策略`	产出前检查点；LLM 自审 vs 人工 vs 程序验收
质量评估	`## 质量评估标准`	可量化维度 + 各 stage 的 acceptanceMode
编排	`## 编排器思维链` + `## 询问策略` + `## 推荐 Worker`	编排器如何调度；谁向用户提问

不必每个 skill 都写独立 # 写作前 大标题；用统一章节名即可，内容覆盖上表即可。

`## 质量评估标准`（必需）

避免只写「写得更好」。每个 skill 应列出 可检查的质量维度，格式建议：

## 质量评估标准

| 维度 | 说明 | 检查方式 |
|---|---|---|
| 完整性 | 是否满足启动询问中的必收集项 | programmatic / 人工 |
| 体裁符合 | 是否符合创作总纲（如规则怪谈：规则可反推危险） | LLM 自审 + 人工 |
| 一致性 | 与已 accepted 上游产物是否矛盾 | programmatic |
| **接受度** | 用户/系统是否接受该产物（预留） | user_confirmed → 记录 accept/reject |

各 stage 默认 acceptanceMode 见「验收策略」。

「接受度」维度（预留）：

第一版：不强制数值打分；用阶段机的 user_accepted_artifact / reject 记录二元结果即可。
后续可在 Book / Session 元数据写入 acceptanceScore 或 acceptanceNotes（字符串或 1–5 分），与 Skill Rubric 对齐。
Skill 里写清楚：接受度由验收事件沉淀，不由 LLM 自报分数代替人工。

`## 自检清单`（必需）

写作后、提交验收前，worker 或编排器应过的检查点（字符串列表即可）：

## 自检清单

### rules.draft 提交前
- [ ] 每条规则能否对应非玄学的危险动机？
- [ ] 是否未直接写出 core.danger？
- [ ] 是否无「违反即抹杀」空规则？

### content.chapter.* 提交前
- [ ] 是否遵守 rules.draft 已 accepted 版本？
- [ ] …

与 programmatic_review 的关系：自检清单 = LLM/人读的规范；程序验收 = 可机械执行的子集。

模板骨架（`skills/{bookKind}/{name}.md`）

---
name: …
description: …          # 触发条件（WHEN）
tags: …
category / bookKind: …
suggestedWorkers: …
---

# 标题

## 启动询问              # 写作前 · 需求分析
## 创作总纲
## 编排器思维链
## 推荐阶段              # 写作中 · 分步引导
## 询问策略
## 推荐 Worker
## 示例                  # 写作中 · 约束与范例
## 禁用行为
## 自检清单              # 写作后
## 验收策略              # 写作后 · 与 acceptanceMode 绑定
## 质量评估标准          # Rubric + 接受度（预留）
## Book 结构             # 可选，novel / dialogue 形态说明

代码当前结构化解析的仍主要是 ## 启动询问；其余章节整段注入编排器 prompt（待 buildSkillContext）。全部是 Markdown 字符串，不矛盾。

3.3 正文必需章节（检查清单）

章节	生命周期	内容
frontmatter	触发	name、description、tags、bookKind
启动询问	写前	必收集项、写入 key
创作总纲	写前	顺序、边界、体裁原则
推荐阶段	写中	阶段链、worker、产出 key、prerequisites
示例	写中	好/坏对照或完整流程范例
禁用行为	写中	绝对不要做的事
自检清单	写后	提交验收前的检查点
验收策略	写后	各 stage 的 acceptanceMode
质量评估标准	质量	可量化维度 + 接受度（预留）
编排器思维链	编排	每轮决策检查
询问策略	编排	编排器问 vs worker 问
推荐 Worker	编排	与 suggestedWorkers 一致

可选：## Book 结构、examples.md 外链。

4. registry.yaml（可选）

启动时列举可用 skill，不必扫描目录：

skills:
  - name: novel-standard
    description: 标准长篇小说：大纲 → 事件 → 正文
    category: novel
  - name: weird-rules-short
    description: 短篇规则怪谈：隐含核心 → 护命规则 → 成章
    category: novel
  - name: theater-roleplay
    description: 剧场式角色扮演：角色 → 场景 → 回合互动
    category: dialogue
  - name: forum-thread
    description: 论坛体连载：楼主身份 → 回帖风格 → 楼层
    category: novel

若无 registry.yaml，Runtime 扫描 skills/novel/*.md 与 skills/dialogue/*.md。 registry 列举的是第二层 skill（name），不是 category。

5. 会话启动：描述需求，而非选包

新建作品不再让用户输入 skill name 或列表编号。Runtime 自动加载默认 orchestrator（world-simulator，见 src/config/default-orchestrator.ts），直接进入 intake。

5.1 启动转移

idle
  session_started { initialSkill }
    → waiting_user(intake)

session_started 携带 initialSkill 时跳过 skill_selection。
registry 中其它包仅供 startWithOrchestrator / 旧作品读档兼容。

Legacy（旧会话恢复）：

session_started（无 initialSkill）
  → waiting_user(skill_selection)   # 仅旧快照可能出现

| { kind: "skill_selection"; availableSkills: SkillIndexEntry[] }  // legacy
| { kind: "intake"; prompt: string }

5.2 向用户展示

来自 orchestrator ## 启动询问，例如 world-simulator：

请用你自己的话描述想做什么，例如：

- 西幻升级、长篇 AI 交互、世界推着走
- 部分代入：() 是指令，"" 是角色话，【】 是行动
- 或：仿写/扩写、规则怪谈、快节奏爽文……

Agent 会根据你的描述推理需要哪些 Worker，并产出 Worker 集。

5.3 用户回答方式

直接描述创作目标（一句话即可）

Runtime 写入 用户.需求（或 skill 指定的 startupTargetKey），确认后进入 design stage。

5.4 两阶段启动（现行）

阶段 1（系统）  自动绑定默认 orchestrator
阶段 2（intake） 启动询问 → 用户描述需求 → confirm → agent burst

Agent 根据需求编排能力并收成 worker 集（design-flow → design-step），不再让用户在 registry 里四选一。

6. 编排器如何使用已选 Skill

session.slots.activeSkill 加载后，编排器 prompt 注入：

当前 skill: novel-standard
category: novel
创作总纲: （SKILL.md 摘要或全文）
当前推荐阶段: outline（由 resolver 根据黑板推断）
询问策略: 编排器应先问 brief；outline 细节交给 worker
建议 worker: outline-worker, drafting-worker
defaultFlowId: ghostwriting-flow

编排器决策仍通过 tool / JSON 决策，不直接改 phase。

7. 示例

完整示例见仓库内真实文件（不要只在文档里维护一份）：

skills/dialogue/world-simulator/orchestrator.md
skills/dialogue/world-simulator/workers/design-flow/SKILL.md
skills/dialogue/world-simulator/modules/catalog.yaml
skills/dialogue/world-simulator/recipes/catalog.yaml

（历史示例 skills/novel/weird-rules-short、theater-roleplay 已不在仓库。）

8. 解析与加载（将来代码）

文件	干嘛的
`src/skills/types.ts`	SkillIndexEntry、ParsedSkill 类型
`src/skills/loader.ts`	扫描 skills/、解析 frontmatter + 正文
`src/skills/registry.ts`	读 registry.yaml 或目录扫描
`src/skills/resolver.ts`	根据黑板 index 推断当前 stage

加载流程：

listSkills() → SkillIndexEntry[]
loadSkill(skillId) → ParsedSkill（含 startupInquiry 解析自 ## 启动询问）
selectSkill(session, skillId) → session.slots.activeSkill
getStartupPrompt(activeSkill) → 流程 2 展示文案
buildSkillContext(activeSkill, blackboardIndex) → 编排器 prompt 片段

10. 与 creation-playbook.md 的关系

creation-playbook.md 描述概念与数据结构（Playbook、Stage、InquiryPolicy）。

本文件描述落盘格式（SKILL.md 怎么写、放哪、启动时怎么选）。

关系：

Creation Playbook（概念）
  = SKILL.md（存储）+ stages.yaml（可选结构化）
  + session.slots.activeSkill（运行时）

creation-playbook.md 中的 TS 类型，实现时可从 SKILL.md 解析或从 stages.yaml 读取。

11. 第一版范围

skills/ 目录 + 示例 orchestrator 包
启动 → 自动绑定默认 orchestrator → intake（描述需求）
编排器 prompt 注入 skill 摘要
registry.yaml 可选（legacy 包 / 读档兼容）

不做：

skill 可视化编辑器
运行时 LLM 自动生成 skill
与 Cursor .cursor/skills 混用（路径独立）

19 KiB Raw Blame History Unescape Escape