Initial commit
This commit is contained in:
184
docs/skill-design-guide.md
Normal file
184
docs/skill-design-guide.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Skill 设计指南
|
||||
|
||||
指导 **如何从零设计一个 orchestrator 包**（skill 能力库 + run skill 组合）。
|
||||
格式见 `skill-format.md`、`orchestrator-skill-format.md`、`worker-skill-format.md`；上下文见 `context-assembly.md`。
|
||||
|
||||
**设计顺序：**
|
||||
|
||||
```text
|
||||
1. 用户意图 → run skill 清单（交互范式 skill 产出）
|
||||
2. 每个 run skill 倒推需要哪些 instantiate skill / tag
|
||||
3. 定义各 skill 的 inputTags、outputTags、contextSegments
|
||||
4. 上下文隔离与验收边界
|
||||
5. orchestrator manifest（能力注册，非逐步剧本）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 实例化：agent 选 skill，不是填步骤
|
||||
|
||||
### 1.1 两层倒推
|
||||
|
||||
```text
|
||||
用户意图（长篇 / 短篇 / 思想实验 / 角色卡扮演 …）
|
||||
→ 交互范式 skill：产出 设计.run_skill清单
|
||||
→ 每个 run skill 需要什么输入？
|
||||
→ agent 按需 invoke instantiate skill（能力库中的 SKILL.md）
|
||||
→ declare_instance_ready → play stage
|
||||
```
|
||||
|
||||
**能力库**（如 world-simulator 包内十几个 instantiate skill）不是 1→N 管道；agent 跳过不需要的 skill，并记录 `设计.跳过.{skillId}`。
|
||||
|
||||
### 1.2 示例：不同意图的 run skill 组合
|
||||
|
||||
| 用户意图 | run skill 示例 | 实例化倒推 |
|
||||
|----------|----------------|------------|
|
||||
| 长篇小说 | 变量管理、大纲推荐、转述者、世界机 | 变量目录 skill、叙事指南、世界蓝图… |
|
||||
| 短篇 | 情感流生成器 | 美学纲领、情感曲线约定 |
|
||||
| 思想实验 | 世界模拟器 | 规则、行动格式；**无**转述者 |
|
||||
| 角色卡扮演 | 转述者（+ 可选世界机） | 角色卡确认稿、口吻、回复格式 |
|
||||
|
||||
### 1.3 run 阶段交互形态
|
||||
|
||||
agent 在 play stage 的 burst 内调度 run skill，形态因包而异：
|
||||
|
||||
| 形态 | 适用 | sketch |
|
||||
|------|------|--------|
|
||||
| 单 skill 直出 | 简单大纲 | `outline` |
|
||||
| 行动–反应循环 | 博弈、世界模拟 | 世界机 ↔ 角色决策 ↔ 展示 |
|
||||
| 分叉验收 | 规则怪谈 | `write` → 双 `review` |
|
||||
|
||||
形态写在各 skill 的 **能力说明**里，**不**写进全局编排表逐步剧本。
|
||||
|
||||
---
|
||||
|
||||
## 2. 暂停与用户
|
||||
|
||||
### 2.1 边界 tool 即暂停
|
||||
|
||||
agent tool loop 在下列情况 **退出 burst**，进入 `waiting_user`：
|
||||
|
||||
```text
|
||||
ask_user / review_blackboard
|
||||
run_worker + requiresApproval
|
||||
worker 完成 + user_confirmed → review_artifact
|
||||
worker ask_user → worker_questions
|
||||
```
|
||||
|
||||
暂停策略写在 orchestrator manifest 的 **验收策略**，不是「第几步必须停」的管道表。
|
||||
|
||||
### 2.2 user-turn
|
||||
|
||||
用户亲自决策的环节：独立 skill，`用户.最新输入` 写入与 LLM 角色同形 tag，供世界机裁决。见 `worker-skill-format.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 上下文：上半固定、下半动态
|
||||
|
||||
每个 skill（`SKILL.md`）声明：
|
||||
|
||||
```text
|
||||
inputTags / outputTags 黑板接口
|
||||
contextSegments static（上）+ dynamic（下）
|
||||
contextIsolation 谁看不见什么
|
||||
contextProfile variants 实例化时选档位
|
||||
```
|
||||
|
||||
原则：**稳定在上、增量在下**；Runtime 拼接，agent 不改。
|
||||
全文见 `docs/context-assembly.md`。
|
||||
|
||||
### 3.1 分层示例（roleplay-game-theory）
|
||||
|
||||
| tier | 含义 | tag 示例 |
|
||||
|------|------|----------|
|
||||
| static | 前提、实体设定 | `情境.实验.设定`、`角色.{id}.设定` |
|
||||
| dynamic | 历史、本轮 | `运行.事件流`、`可见信息` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 倒推标签
|
||||
|
||||
对每个 skill 填表：
|
||||
|
||||
```text
|
||||
skill id | 职责 | stage(design/play) | inputTags | outputTags | contextSegments | 验收者
|
||||
```
|
||||
|
||||
### 4.1 角色扮演博弈（摘录）
|
||||
|
||||
| skill | 读取 | 写入 | 验收 |
|
||||
|-------|------|------|------|
|
||||
| setup-scenario | `用户.博弈需求` | 情境、规则、角色设定 | 用户 |
|
||||
| world-engine | 情境、规则、事件流、行动 | 可见信息、事件流 | 程序 |
|
||||
| role-decide | 本人设定、事件流、可见信息 | `.思考`、`.行动` | 程序 |
|
||||
| present-round | 本轮产物 | `输出.用户展示` | 用户 |
|
||||
|
||||
展示类 skill 单独存在；agent 调度，不拼长文。
|
||||
|
||||
---
|
||||
|
||||
## 5. 上下文隔离（必查）
|
||||
|
||||
```text
|
||||
□ 哪些 tag 只给用户、不注入生产 skill？
|
||||
□ 盲读 review 不可见哪些 tag？
|
||||
□ 草稿 vs 确认稿：下游何时可当作事实？
|
||||
□ 多角色：role_pov 是否生效？
|
||||
```
|
||||
|
||||
靠 `inputTags` + `contextIsolation` + Runtime 过滤，不靠 prompt 口头禁止。
|
||||
|
||||
---
|
||||
|
||||
## 6. orchestrator manifest（非编排表）
|
||||
|
||||
orchestrator.md 应包含：
|
||||
|
||||
```text
|
||||
□ 启动询问（最小 intake）
|
||||
□ instantiate skill 注册表（id、stage、description）
|
||||
□ run skill 注册表
|
||||
□ 验收策略（哪些 skill 产出需 user_confirmed）
|
||||
□ contextProfile 可选 variant 说明
|
||||
□ declare_instance_ready 最低可行性（按 run_skill清单 动态校验）
|
||||
```
|
||||
|
||||
**不应包含：** 逐步思维链、「第 5 步必须跑 world-engine」类管道脚本。
|
||||
|
||||
---
|
||||
|
||||
## 7. checklist
|
||||
|
||||
```text
|
||||
□ 1. 一句话：本包 play stage 的交互形态
|
||||
□ 2. 交互范式 skill 产出 run_skill清单 的 schema
|
||||
□ 3. 每个 run skill 倒推 instantiate skill 需求
|
||||
□ 4. 各 SKILL.md：input/output、contextSegments、隔离
|
||||
□ 5. shared-context.md（static 上半）
|
||||
□ 6. manifest：注册表 + 验收 + readiness
|
||||
□ 7. skills/README.md 注册
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例包
|
||||
|
||||
| 包 | 特点 |
|
||||
|----|------|
|
||||
| `basic` | 单 run skill，最小上下文 |
|
||||
| `weird-rules-short` | 分叉验收 |
|
||||
| `roleplay-game-theory` | 行动–反应循环 |
|
||||
| `world-simulator`（规划） | 大能力库 + agent 实例化 |
|
||||
|
||||
对照时复用 **方法**，不照搬 tag 名或 skill 数量。
|
||||
|
||||
---
|
||||
|
||||
## 9. 相关文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `context-assembly.md` | 拼接规格 |
|
||||
| `creation-playbook.md` | 概念 |
|
||||
| `orchestrator-skill-format.md` | manifest 写法 |
|
||||
| `book-storage.md` | 过程与资产归档 |
|
||||
Reference in New Issue
Block a user