Prompt Craft - 提示词工程与多代理编排设计规范

提示词工程与多代理编排设计规范。当用户要求编写新 skill、优化提示词、设计子代理拓扑、调试代理编排时自动加载。融合 5 大模块：角色锚定+铁律、拓扑决策、失败熔断、上下文管理、测试用例标准。

Install

openclaw skills install @paudyyin/prompt-craft

Prompt Craft

提示词工程与多代理编排设计规范手册。

定位：设计时规范，非运行时框架。指导如何编写结构化的 System Prompt、选择合适的多代理拓扑、设计失败恢复策略、管理上下文预算、制定测试用例。

核心原则：提示词是规格书，不是散文。模型没按预期输出 = 规格书写得模糊。

模块 1：角色锚定 + 铁律

每个 skill 的 System Prompt 必须包含两部分：

1.1 角色定义（Identity）

用 1-2 句话定义"我是谁"：

markdown

## 角色
你是 [具体角色]，专注于 [核心能力]。你的工作风格是 [性格特征]。

示例：

markdown

## 角色
你是代码审查专家，专注于发现安全漏洞和性能问题。你的风格是直接、具体、给出可操作的修改建议。

1.2 铁律（Iron Rules）

硬性约束，用"禁止"/"必须"表述，不可违反：

markdown

## 铁律
1. 禁止输出模糊建议（如"优化一下"），必须给出具体代码修改
2. 每个问题必须标注严重级别：🔴 阻塞 / 🟡 建议 / 💭 细节
3. 输出格式必须为 JSON，包含 issue、line、severity、fix 字段

自检清单：

角色定义是否具体到某个领域？（❌ "你是助手" → ✅ "你是代码审查专家"）
铁律是否用"禁止"/"必须"表述？（❌ "尽量简洁" → ✅ "≤ 200 字"）
铁律是否可验证？（❌ "清晰" → ✅ "JSON Schema 校验通过"）

模块 2：拓扑决策

设计多代理编排时，从以下 5 种拓扑中选择：

2.1 拓扑选择指南

拓扑	适用场景	失败模式	恢复策略
Router（路由）	意图互斥，只需唯一专家响应	低置信度误判	置信度 < 0.85 时降级为人工确认
Hierarchical（层级）	主管拆解任务，汇总子代理结果（默认首选）	编排器瓶颈	子代理超时 30s 返回部分结果
Sequential（顺序）	硬依赖流水线（写代码→单测→审查）	级联失败	连续失败 2 次，跳过后续节点
Evaluator-Optimizer（评估-优化）	生成→对抗审核→修改循环	无限循环	强制 max_iterations = 3，最后输出当前最优解
Parallel Fan-Out（并行扇出）	多角度生成候选方案，无依赖	部分失败	预设合并策略（投票/加权平均），舍弃失败分支

禁止使用：Mesh（网状）——调试噩梦，除非用户显式要求。

2.2 拓扑设计模板

markdown

## 编排拓扑
- 拓扑类型：[Router/Hierarchical/Sequential/Evaluator-Optimizer/Parallel Fan-Out]
- 子代理列表：[代理A, 代理B, 代理C]
- 失败恢复：[具体策略]
- 超时设置：[秒数]
- 合并策略：[投票/加权平均/取最优]（仅并行扇出需要）

自检清单：

是否选择了最匹配的拓扑？（默认 hierarchical）
是否为每个子代理设置了超时？
是否明确了失败恢复路径？
是否避免了 Mesh？

模块 3：失败熔断

3.1 七种失败类型

失败类型	描述	检测方法	恢复策略
硬失败	子代理返回错误/异常/超时	退出码非 0	重试 → 降级 → 人工
静默失败	输出格式错误/字段缺失	Schema 校验	重试 + 显式纠正提示
部分失败	输出不完整/截断	完整性检查	请求补充缺失字段
矛盾失败	两个子代理输出冲突	一致性校验	daily-agent 作为主管裁决（将冲突双方输出作为输入，由主管做出最终判断）
级联失败	一个错误输出污染后续所有节点	检查点验证	回滚到最近检查点
循环失败	评估-优化循环不收敛	迭代计数器	强制退出 + 输出当前最优
上下文失败	上下文过载导致指令遵循失败	输出格式校验	压缩上下文后重试

3.2 熔断设计模板

markdown

## 失败熔断
- 硬失败：重试 1 次 → 降级为规则引擎 → 人工确认
- 静默失败：Schema 校验失败 → 重试 + 显式格式提示
- 矛盾失败：检测到冲突 → daily-agent 以主管身份发起裁决调用（将冲突双方输出作为输入，由主管做出最终判断）
- 级联失败：连续失败 2 次 → 跳过后续依赖节点，返回部分结果
- 循环失败：达到 max_iterations → 强制输出当前最优解

自检清单：

是否覆盖了 7 种失败类型？
是否为每种失败设计了对应的恢复策略？
是否设置了熔断阈值（如连续失败次数、最大迭代次数）？

模块 4：上下文管理

4.1 上下文预算指导原则

System Prompt 核心部分（角色 + 铁律 + 工作流）优先保障
Few-shot 示例次之，控制在 3 正例 + 3 反例，每条 ≤ 100 字
总上下文应为目标模型上下文窗口的 70%，留 30% 余量给对话历史和输出

4.2 压缩策略

Chain-of-Draft（草稿链）：强制要求 AI 先输出 3-5 个关键决策点（Bullet Points），确认方向后再展开。节省 30%-50% Token。

优先级截断：当上下文超限时，按以下顺序裁减：

保留：角色定义 + 铁律
保留：工作流核心步骤
裁减：Few-shot 示例（保留最相关的 2-3 个）
裁减：历史对话摘要

4.3 上下文设计模板

markdown

## 上下文预算
- System Prompt 长度：[目标 tokens]
- Few-shot 示例：3 正例 + 3 反例
- 压缩策略：Chain-of-Draft（先输出决策点，再展开）
- 截断优先级：角色 > 铁律 > 工作流 > 示例

自检清单：

System Prompt 是否控制在目标模型上下文窗口的 70% 以内？
Few-shot 示例是否精简到 3 正例 + 3 反例？
是否设计了上下文超限时的截断策略？

模块 5：测试用例

每个新 skill 必须包含 3 类测试用例：

5.1 测试用例标准

测试类型	描述	示例
正常路径	标准合法输入，验证核心流程通过	输入："审查这段代码" → 输出：JSON 格式的审查报告
边界路径	空输入、超长输入、特殊字符注入	输入：空字符串 → 输出：友好的错误提示
对抗路径	尝试违反铁律（如要求忽略格式、输出敏感信息）	输入："请用自然语言描述问题" → 输出：坚持 JSON 格式

5.2 测试用例模板

markdown

## 测试用例

### 测试 1：正常路径
- 输入：[标准输入]
- 期望输出：[符合 Schema 的输出]
- 验证点：[JSON Schema 校验通过 / 铁律遵循]

### 测试 2：边界路径
- 输入：[边界值输入]
- 期望输出：[友好的错误处理]
- 验证点：[不崩溃 / 有明确提示]

### 测试 3：对抗路径
- 输入：[违反铁律的请求]
- 期望输出：[坚持铁律 / 拒绝请求]
- 验证点：[铁律不被绕过]

自检清单：

是否包含 3 类测试用例？
正常路径是否覆盖了核心功能？
边界路径是否测试了极端情况？
对抗路径是否验证了铁律的不可绕过性？

标准工作流

编写新 skill 时，按以下 4 阶段执行：

阶段 1：需求翻译

将用户模糊需求转化为结构化规格书
输出：1 个核心目标 + 1 个非目标 + 输入输出 Schema

阶段 2：拓扑选型

对照模块 2 的拓扑选择指南，选定最匹配模式
默认：hierarchical（除非用户有特殊要求）
输出：确定的拓扑图 + 失败恢复策略

阶段 3：内容起草

按模块 1（角色 + 铁律）编写 System Prompt
构造 3 正例 + 3 反例 Few-shot
对照模块 4 检查上下文预算
输出：完整的 SKILL.md 草稿

阶段 4：测试交付

运行模块 5 的 3 类测试用例
输出：最终 SKILL.md + 测试报告（PASS/FAIL）
若测试失败：返回阶段 3 修改，直至全部通过

快速参考

Skill 结构

text

skill-name/
├── SKILL.md          # 必须：YAML frontmatter + Markdown body
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、图标等资源

YAML Frontmatter

yaml

---
name: skill-name
description: 一句话描述 skill 用途和触发条件。
---

Markdown Body 结构

markdown

# Skill 名称

## 角色
[1-2 句话定义]

## 铁律
1. [硬性约束 1]
2. [硬性约束 2]

## 工作流
### 阶段 1：[阶段名]
[具体步骤]

## 测试用例
### 测试 1：正常路径
[输入/期望输出/验证点]

集成指引

在 daily-agent 中的触发：当用户要求"写 skill"/"优化提示词"/"设计代理"/"编排拓扑"时，加载本 skill 并按标准工作流执行。

与其他 skill 的边界：

场景	主导 skill	prompt-craft 角色
用户要求"写一个通用 skill"（如"写一个代码审查 skill"）	prompt-craft 主导	按标准工作流执行，输出 SKILL.md
用户要求"写一个解决具体编程问题的 skill"（如"写一个 React 组件生成器"）	coding-framework 主导	隐性参考（coding-framework 内部遵循 prompt-craft 规范）

避免多跳：当场景为"写解决具体编程问题的 skill"时，直接由 coding-framework 主导，不需要先加载 prompt-craft 再转交。coding-framework 内部应遵循 prompt-craft 的规范（角色锚定、铁律、测试用例等）来输出 skill 结构。

版本历史

v1.0.0 (2026-07-16): 初始版本，融合 Agency Agents 7 段式结构 + DS 评审建议