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

Load present shells from a skill-pack catalog and list leftover creation modules.

Browse Source 
Design-flow now sees leftover catalog skills and aesthetics-card commitments; reply-format injects present-shells/, and world-simulator prompts add random-range plus a tighter module set.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
chenmoranzhi
2026-09-07 01:21:10 +08:00
co-authored by Cursor
parent 770a8fdcdc
commit 3c751988de
59 changed files with 2793 additions and 1638 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skill-format.md
+61 -429
View File
@@ -2,447 +2,131 @@
> **文档层级：Skill 包格式（非系统架构）。**
> 系统级模块与调度边界见 [`architecture.md`](./architecture.md)。
>
> **现行唯一落地包**：`skills/dialogue/world-simulator/`（见该包 README、`world-simulator-modules.md`）。
> 下文部分示例仍保留历史 `novel/` / `weird-rules-short` 树形说明，**仓库内已不存在**；写新内容请以 world-simulator 为准。
> 创作流水线现行名：`design-flow` + `design-step`（旧称 `design-intake` 已废弃）。
> 创作流水线：`design-flow` + `design-step`。
## 1. 定位：两层 Skill
本文只写**包怎么落盘、registry、启动时怎么绑包**。manifest 正文见 `orchestrator-skill-format.md`；磁盘 Worker 见 `worker-skill-format.md`；建包步骤见 `skill-design-guide.md`。
本项目有 **两种 Skill 文档**，不要混在一个文件里：
---
## 1. 两层 Skill
| 类型 | 路径 | 消费者 | 写什么 |
|------|------|--------|--------|
| **编排器 Skill** | `skills/{bookKind}/{name}/orchestrator.md` | Main Agent | **何时**调哪个 worker、验收方式、启动询问 |
| **编排器 Skill** | `skills/{bookKind}/{name}/orchestrator.md` | Main Agent | **何时**调哪个 worker、验收方式、启动引导 |
| **Worker Skill** | `workers/{workerId}/SKILL.md` | Worker Agent | **inputTags/outputTags**、怎么做 |
```text
选 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）两份**。
```text
会话开始
→ 询问 1：选哪个编排器 Skill（skills/{bookKind}/{name}/orchestrator.md）
→ 加载编排器 Skill
→ 询问 2：读编排器 Skill「## 启动询问」
→ 之后编排器按「Worker 编排」调度；Worker 读本 skill 包内 workers/{id}/SKILL.md
→ 自动绑定默认编排器包（world-simulator）
→ UI 选配方（recipes/，不是再选 skill 包）
→ 编排器按 tool loop 调度；Worker 读本包 workers/{id}/SKILL.md
```
**何时评估** = 编排器 Skill。
**如何评估** = 对应 Worker Skill（或运行规格里的声明）。
---
## 2. 存储位置
Skill 以 **Skill 包（skill pack）** 为单位：一个编排器 + 其专属 workers，**同包绑定，不跨包复用 worker**。
Skill 以 **Skill 包** 为单位：一个编排器 + 其专属 workers，**同包绑定，不跨包复用 worker**。
```text
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/
└── world-simulator/
├── orchestrator.md
├── recipes/
├── modules/
├── worker-templates/
└── workers/
└── turn/SKILL.md
├── design-flow/SKILL.md
├── design-step/SKILL.md
└── opening-generator/SKILL.md
```
规则：
```text
第一层文件夹 = 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
orchestrator.md 编排器 Skill
workers/{id}/ 本包专属 worker；id 在包内唯一
```
**为何不复用 worker：** 同一「产出形状」（如规则表）在不同编排器下的写法、Rubric、自检完全不同；共享 worker 会把体裁细节塞进编排器或搞混上下文。需要相似流程时 **复制 worker 包再改**，而不是引用全局 worker。
loader 仍扫描 `skills/novel/` 与 `skills/dialogue/`（平铺 `.md` 或 `{name}/orchestrator.md`）。仓库里目前只有 `dialogue/world-simulator`。
与 Cursor skill 的区别：
| | Cursor Skill | 本项目 Skill |
|---|---|---|
| 位置 | `.cursor/skills/` | `skills/` |
| 触发 | Agent 自动或显式引用 | **会话开始必须选一个** |
| 内容 | 通用任务指南 | **创作流程 + 思维链 + 询问策略** |
| 消费者 | Cursor Agent | 编排器 LLM |
**为何不复用 worker：** 同一产出形状在不同编排器下的写法、验收完全不同；需要相似流程时复制后再改。
---
## 3. SKILL.md 结构
## 3. Frontmatter（编排器）
### 3.0 两层分类（重要）
Skill 分类分**两层**，不要混为一层：
```text
第一层：Book 形态（category / bookKind，选定后不可换）
novel 类小说存储：卷、章、大纲、正文（含各类小说子类型）
dialogue 多轮多角色对话：回合、角色、场景（roleplay / 剧场）
第二层：具体 Skill 包（name，用户启动时选）
每个包 = orchestrator.md + workers/，不是 category 下的平铺 .md 枚举。
```
示例：
```text
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` 区分：
```yaml
---
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 正文。
```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 字段
```yaml
---
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
---
```
loader（`src/skills/loader.ts`）从 `orchestrator.md` 解析的字段：
| 字段 | 必需 | 用途 |
|---|---|---|
| `name` | ✅ | skill id；通常与文件名一致（不含 .md） |
| `description` | ✅ | 启动选择列表展示；编排器判断用户描述是否匹配 |
| `name` | ✅ | skill id |
| `description` | ✅ | 列表展示、匹配 |
| `category` | ✅ | 与 `bookKind` 一致：`novel` \| `dialogue` |
| `bookKind` | 建议 | 选定后 Book 结构固定；缺省时由所在文件夹推断 |
| `tags` | | 体裁细分：`weird_rules`、`standard` 等 |
| `path` | registry | 相对路径，如 `novel/weird-rules-short.md` |
| `defaultFlowId` | | 选中后默认 execution flow |
| `suggestedWorkers` | | 编排器选 worker 时的白名单提示 |
| `bookKind` | 建议 | 缺省时由所在文件夹推断 |
| `workers` | 建议 | 本包可调度的 design worker id（亦认 `suggestedWorkers`） |
| `demandTag` | | 启动写入目标；缺省 `book.brief` |
| `startupMode` | | `agent-first`（默认）或 `intake`（legacy） |
| `uiPrompt` | | agent-first 首屏引导 |
| `tags` | | 体裁细分 |
| `version` | | 数字 |
### 3.2 撰写标准：写作生命周期（推荐）
Skill 文件本质上是**给 LLM 与 Runtime 读的字符串规格**。下面这套「触发 → 写前 → 写中 → 写后 → 质量维度」与现有阶段机、验收模式对齐，**应作为所有 skill `.md` 的撰写标准**。
```text
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 触发条件 │ → │ 写作前 │ → │ 写作中 │ → │ 写作后 │ → │ 质量维度 │
│ 何时激活 │ │ 需求分析 │ │ 分步引导 │ │ 自检润色 │ │ 可量化 Rubric│
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
frontmatter 启动询问 推荐阶段 自检清单 质量评估标准
+ tags + 创作总纲 + 示例/约束 + 验收策略 + 接受度(预留)
+ 询问策略 + 禁用行为
```
#### 与正文章节的对应关系
| 生命周期 | 对应章节 | 写什么 |
|---|---|---|
| **触发条件** | frontmatter `description` + `tags` | 何时应选本 skill；用户说什么话时应匹配（如「规则怪谈」「短篇怪谈」） |
| **写作前 · 需求分析** | `## 启动询问` + `## 创作总纲` | 对象、受众、语气、目标、禁忌；**禁止直接动笔**；写入哪个 key |
| **写作中 · 分步引导** | `## 推荐阶段` + `## 示例` + `## 禁用行为` | 阶段链、每步约束、好/坏示例；对应 worker 与产出 key |
| **写作后 · 自检润色** | `## 自检清单` + `## 验收策略` | 产出前检查点；LLM 自审 vs 人工 vs 程序验收 |
| **质量评估** | `## 质量评估标准` | 可量化维度 + 各 stage 的 acceptanceMode |
| **编排** | `## 编排器思维链` + `## 询问策略` + `## 推荐 Worker` | 编排器如何调度；谁向用户提问 |
不必每个 skill 都写独立 `# 写作前` 大标题；**用统一章节名即可**，内容覆盖上表即可。
#### `## 质量评估标准`（必需）
避免只写「写得更好」。每个 skill 应列出 **可检查的质量维度**，格式建议：
```markdown
## 质量评估标准
| 维度 | 说明 | 检查方式 |
|---|---|---|
| 完整性 | 是否满足启动询问中的必收集项 | 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 或编排器应过的检查点（字符串列表即可）：
```markdown
## 自检清单
### rules.draft 提交前
- [ ] 每条规则能否对应非玄学的危险动机？
- [ ] 是否未直接写出 core.danger？
- [ ] 是否无「违反即抹杀」空规则？
### content.chapter.* 提交前
- [ ] 是否遵守 rules.draft 已 accepted 版本？
- [ ] …
```
与 `programmatic_review` 的关系：自检清单 = LLM/人读的规范；程序验收 = 可机械执行的子集。
#### 模板骨架（`skills/{bookKind}/{name}.md`）
```markdown
---
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` 外链。
正文章节、验收与禁用行为见 `orchestrator-skill-format.md`。不要再写「推荐阶段 / 质量评估标准 / 推荐 Worker」那套旧 SKILL 骨架。
---
## 4. registry.yaml（可选）
## 4. registry.yaml
启动时列举可用 skill，不必扫描目录：
启动时列举可用 skill，不必全靠扫盘：
```yaml
skills:
- name: novel-standard
description: 标准长篇小说：大纲 → 事件 → 正文
category: novel
- name: weird-rules-short
description: 短篇规则怪谈：隐含核心 → 护命规则 → 成章
category: novel
- name: theater-roleplay
description: 剧场式角色扮演：角色 → 场景 → 回合互动
- name: world-simulator
description: 默认包：选配方 → 编排工作流计划 → 执行单元上场
category: dialogue
- name: forum-thread
description: 论坛体连载：楼主身份 → 回帖风格 → 楼层
category: novel
bookKind: dialogue
path: dialogue/world-simulator/orchestrator.md
```
若无 `registry.yaml`，Runtime 扫描 `skills/novel/*.md` 与 `skills/dialogue/*.md`。
**registry 列举的是第二层 skill（name），不是 category。**
无 `registry.yaml` 时，Runtime 扫描 `skills/novel/` 与 `skills/dialogue/`。
registry 列举的是第二层 skill（`name`），不是 category。
---
## 5. 会话启动：描述需求，而非选包
## 5. 会话启动
新建作品 **不再** 让用户输入 skill name 或列表编号。Runtime 自动加载默认 orchestrator（`world-simulator`，见 `src/config/default-orchestrator.ts`），直接进入 intake。
### 5.1 启动转移
新建作品 **不** 让用户输入 skill name。Runtime 加载默认编排器（`world-simulator`，见 `src/config/default-orchestrator.ts`），用户只选**配方**。
```text
idle
session_started { initialSkill }
→ waiting_user(intake)
→ waiting_user(intake) # 展示 uiPrompt；用户描述需求
```
`session_started` 携带 `initialSkill` 时跳过 `skill_selection`。
registry 中其它包仅供 `startWithOrchestrator` / 旧作品读档兼容。
registry 中其它包仅供 `startWithOrchestrator` / 旧作品读档。
**Legacy（旧会话恢复）：**
无 `initialSkill` 的旧快照才可能出现 `waiting_user(skill_selection)`。
```text
session_started（无 initialSkill）
→ waiting_user(skill_selection) # 仅旧快照可能出现
```
```ts
| { kind: "skill_selection"; availableSkills: SkillIndexEntry[] } // legacy
| { kind: "intake"; prompt: string }
```
### 5.2 向用户展示
来自 orchestrator `## 启动询问`，例如 world-simulator：
```text
请用你自己的话描述想做什么，例如：
- 西幻升级、长篇 AI 交互、世界推着走
- 部分代入：() 是指令，"" 是角色话，【】 是行动
- 或：仿写/扩写、规则怪谈、快节奏爽文……
Agent 会根据你的描述推理需要哪些 Worker，并产出 Worker 集。
```
### 5.3 用户回答方式
```text
直接描述创作目标（一句话即可）
```
Runtime 写入 `用户.需求`（或 skill 指定的 startupTargetKey），确认后进入 design stage。
### 5.4 两阶段启动（现行）
```text
阶段 1（系统） 自动绑定默认 orchestrator
阶段 2（intake） 启动询问 → 用户描述需求 → confirm → agent burst
```
**Agent 根据需求编排能力并收成 worker 集**（`design-flow` → `design-step`），不再让用户在 registry 里四选一。
用户回答写入 `demandTag`（现行包为 `用户.需求`），之后 `design-flow` → `design-step` 编排并收成 worker 集。
---
## 6. 编排器如何使用已选 Skill
## 6. 解析与加载
`session.slots.activeSkill` 加载后，编排器 prompt 注入：
| 文件 | 干嘛的 |
|---|---|
| `src/skills/types.ts` | SkillIndexEntry、ParsedSkill、ParsedWorkerSkill |
| `src/skills/loader.ts` | 读 registry 或扫盘；解析 orchestrator.md 与 workers/*/SKILL.md |
| `src/config/default-orchestrator.ts` | 默认包 id、uiPrompt 兜底 |
```text
当前 skill: novel-standard
category: novel
创作总纲: （SKILL.md 摘要或全文）
当前推荐阶段: outline（由 resolver 根据黑板推断）
询问策略: 编排器应先问 brief；outline 细节交给 worker
建议 worker: outline-worker, drafting-worker
defaultFlowId: ghostwriting-flow
```
编排器决策仍通过 tool / JSON 决策，**不**直接改 phase。
---
## 7. 示例
完整示例见仓库内真实文件（不要只在文档里维护一份）：
完整示例以仓库内真实文件为准：
```text
skills/dialogue/world-simulator/orchestrator.md
@@ -451,62 +135,10 @@ skills/dialogue/world-simulator/modules/catalog.yaml
skills/dialogue/world-simulator/recipes/catalog.yaml
```
（历史示例 `skills/novel/weird-rules-short`、`theater-roleplay` 已不在仓库。）
---
## 8. 解析与加载（将来代码）
## 7. 与其它文档
| 文件 | 干嘛的 |
|---|---|
| `src/skills/types.ts` | SkillIndexEntry、ParsedSkill 类型 |
| `src/skills/loader.ts` | 扫描 skills/、解析 frontmatter + 正文 |
| `src/skills/registry.ts` | 读 registry.yaml 或目录扫描 |
| `src/skills/resolver.ts` | 根据黑板 index 推断当前 stage |
加载流程：
```text
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 怎么写、放哪、启动时怎么选）。
关系：
```text
Creation Playbook（概念）
= SKILL.md（存储）+ stages.yaml（可选结构化）
+ session.slots.activeSkill（运行时）
```
`creation-playbook.md` 中的 TS 类型，实现时可从 SKILL.md 解析或从 stages.yaml 读取。
---
## 11. 第一版范围
```text
skills/ 目录 + 示例 orchestrator 包
启动 → 自动绑定默认 orchestrator → intake（描述需求）
编排器 prompt 注入 skill 摘要
registry.yaml 可选（legacy 包 / 读档兼容）
```
不做：
```text
skill 可视化编辑器
运行时 LLM 自动生成 skill
与 Cursor .cursor/skills 混用（路径独立）
```
`creation-playbook.md` 描述创作/游玩流程概念。
本文件描述包怎么存、启动时怎么绑。
方法正文见 `design-orchestrator-guide.md`。