prompt-engineering

提示词工程全栈——设计时规范（角色锚定/拓扑决策/失败熔断/上下文管理/测试用例）+ 运行时推理模式（CoT/SC/ToT/ReAct/P&E）

Install

openclaw skills install @paudyyin/prompt-engineering

Prompt Engineering v1.0.0

提示词工程全栈：设计时规范（构建什么）→ 运行时推理模式（怎么推理）→ 协同路由。

来源：prompt-craft v1.0.0（设计时规范）+ prompting-modes v1.0.0（运行时推理模式）

Part 1: 设计时规范

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

1.1 角色锚定 + 铁律

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

角色定义（Identity）：1-2 句话定义"我是谁"

markdown

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

铁律（Iron Rules）：硬性约束，用"禁止"/"必须"表述，不可违反：

markdown

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

自检清单：

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

1.2 拓扑决策

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

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

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

拓扑设计模板：

markdown

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

1.3 失败熔断

七种失败类型：

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

熔断设计模板：

markdown

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

1.4 上下文管理

预算指导原则：

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

压缩策略：

Chain-of-Draft：强制要求 AI 先输出 3-5 个关键决策点（Bullet Points），确认方向后再展开。节省 30%-50% Token
优先级截断：超限时按以下顺序裁减：
1. 保留：角色定义 + 铁律
2. 保留：工作流核心步骤
3. 裁减：Few-shot 示例（保留最相关的 2-3 个）
4. 裁减：历史对话摘要

1.5 测试用例

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

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

Part 2: 运行时推理模式

五种经过验证的推理策略，可根据任务类型自动或手动选择。来源：吴恩达《AI Prompting for Everyone》课程核心方法论

2.1 五种模式概览

模式	核心思想	适用场景	触发词
Chain-of-Thought	逐级分解，显式展示中间推理	数学/逻辑/需要透明解释	"一步一步"/"解释过程"
Self-Consistency	多次采样，多数投票选最可靠	客观题/追求高准确率	"确定答案"/"多验证几次"
Tree-of-Thought	探索多条路径，评价后选最优	复杂规划/创意/多解问题	"几种方案"/"ToT"/"头脑风暴"
ReAct	思考-行动-观察循环，调用工具	需要搜索/计算/查询的任务	"搜索"/"查询"/"实时"
Plan-and-Execute	先完整计划，再逐步执行	多步骤项目/长链条任务	"计划"/"步骤"/"规划"

2.2 模式选择决策树

text

用户请求
    │
    ├─ 需要调用外部工具？ ──是──→ ReAct
    │否
    ├─ 需要客观确定答案？ ──是──→ Self-Consistency
    │否
    ├─ 存在多种可行路径？ ──是──→ Tree-of-Thought
    │否
    ├─ 任务步骤多步？ ──是──→ Plan-and-Execute
    │否
    ├─ 需要透明解释？ ──是──→ Chain-of-Thought
    │否
    └─ 默认：直接回答

2.3 模式 1: Chain-of-Thought (CoT)

核心思想：将复杂问题分解为中间推理步骤，显式展示思考过程。

执行格式：

markdown

## 问题重述
[用自己的话复述问题]

## 已知条件
- 条件1: ...
- 条件2: ...

## 分步推理
**步骤1**: [推理内容] → 得到: [中间结论]
**步骤2**: [推理内容] → 得到: [中间结论]

## 最终答案
[基于推理链得出的结论]

## 验证
[反向验证答案是否正确]

适用场景：数学计算、逻辑推理、需要解释"为什么"的问题、调试代码分析原理。

参数建议：温度 0.3（低温度保证推理稳定性），详细程度高。

2.4 模式 2: Self-Consistency (SC)

核心思想：对同一问题生成多个独立答案，通过多数投票选出最可靠的结果。

执行格式：

markdown

## 多次采样
**路径1**: [推理过程] → 答案A
**路径2**: [推理过程] → 答案B
**路径3**: [推理过程] → 答案A
**路径4**: [推理过程] → 答案A
**路径5**: [推理过程] → 答案C

## 投票结果
| 答案 | 出现次数 | 占比 |
|------|---------|------|
| 答案A | 3 | 60% |
| 答案B | 1 | 20% |
| 答案C | 1 | 20% |

## 最终答案：答案A（多数投票结果，置信度 60%）

适用场景：选择题、事实性问题、需要高准确率的场景。

注意事项：采样路径应有差异化；投票分散说明问题有歧义，需向用户澄清；成本较高（5次推理），仅在必要时使用。

2.5 模式 3: Tree-of-Thought (ToT)

核心思想：探索多条推理路径，评估每条路径的可行性，选择最优分支深入。

执行格式：

markdown

## 生成初始分支（3个思路）
**分支A**: [思路描述]
**分支B**: [思路描述]
**分支C**: [思路描述]

## 初步评价
| 维度 | 分支A | 分支B | 分支C |
|------|-------|-------|-------|
| 可行性 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
| 成本 | 中 | 低 | 高 |
| 风险 | 低 | 中 | 高 |

## 淘汰
淘汰分支B（原因：...）

## 深入展开剩余分支
### 分支A深入 / 分支C深入
...

## 最终推理
推荐分支C，理由：...

适用场景：架构设计、技术选型、方案对比、创意发散。

2.6 模式 4: ReAct

核心思想：交替进行推理（Thought）和行动（Action），通过工具获取信息，观察结果后继续推理。

执行格式：

text

Thought: [当前推理，分析下一步需要什么信息]
Action: [工具名称]
Action Input: [工具参数]
Observation: [工具返回结果]
Thought: [基于观察继续推理]
...
Final Answer: [最终答案]

与 OpenClaw 的映射：

Thought → 分析当前状态，决定下一步
Action → 调用工具（web_search/read/exec/browser等）
Observation → 工具返回结果
循环 → 直到有足够信息得出 Final Answer

执行规则：每轮必须有 Thought + Action；最多 5 轮 Action（防止无限循环）；5 轮后仍无答案则向用户说明。

2.7 模式 5: Plan-and-Execute (P&E)

核心思想：先生成完整计划，再逐步执行，最后验证结果。

执行格式：

阶段1：计划

markdown

## 执行计划
| 步骤 | 任务 | 预期输出 | 依赖 |
|------|------|---------|------|
| 1 | ... | ... | 无 |
| 2 | ... | ... | 步骤1 |

## 风险预判
- 步骤X可能失败，备选方案：...

阶段2：执行

markdown

### 步骤1: [任务名]
- 操作: ...
- 结果: ...
- 状态: ✅完成 / ❌失败（原因: ...）

阶段3：验证

markdown

## 结果验证
- 目标: [原始目标]
- 实际输出: [实际结果]
- 是否达成: 是/否
- 偏差说明: ...

适用场景：多步骤项目、需要明确里程碑的任务、复杂报告生成。

2.8 模式组合

复杂任务可以组合多种模式：

组合	场景	执行方式
P&E + CoT	多步骤推理项目	每步执行时用 CoT 展示推理
P&E + ReAct	多步骤信息收集	每步执行时调用工具
ToT + P&E	方案对比后执行	先用 ToT 选方案，再用 P&E 执行
SC + CoT	高准确率推理	多次采样后用 CoT 解释最终答案

Part 3: 协同路由

text

任务到达 → 判断阶段
  ├─ 设计阶段（创建新skill/新代理系统）
  │   → Part 1 设计时规范
  │   → 角色锚定 + 拓扑决策 + 失败熔断 + 测试用例
  │   → 在设计中预留推理模式选择（如代理内部用CoT还是ReAct）
  │
  ├─ 执行阶段（已有系统，执行具体任务）
  │   → Part 2 运行时推理模式
  │   → 根据决策树选择 CoT/SC/ToT/ReAct/P&E
  │   → 受设计时约束影响（如上下文预算、失败恢复策略）
  │
  └─ 混合场景（设计+执行同步进行）
      → Part 1 定义骨架 → Part 2 填充推理逻辑 → 迭代优化

设计时考虑运行时：

拓扑选择时考虑代理内部的推理模式需求（如 ReAct 代理需要工具访问权限）
失败熔断设计时考虑推理模式的特性（如 ToT 的分支淘汰 vs Evaluator-Optimizer 的循环）
上下文预算分配时预留推理空间（CoT 需要更多 token 展示推理过程）

运行时受设计约束：

代理的 System Prompt 铁律约束推理输出格式
拓扑结构决定推理模式的组合方式
失败熔断决定推理中断后的恢复策略

文件结构

text

prompt-engineering/
├── SKILL.md                          # 本文档
└── references/
    ├── modes-reference.md            # 五种推理模式的学术背景和最佳实践
    └── implementation-guide.md       # OpenClaw 中的具体实现指南

约束

提示词是规格书：模型没按预期输出 = 规格书写得模糊
铁律可验证：❌ "清晰" → ✅ "JSON Schema 校验通过"
拓扑默认层级：除非有特殊理由，否则用 Hierarchical
禁止 Mesh：网状拓扑是调试噩梦
上下文 70% 原则：总上下文不超过模型窗口的 70%
推理模式按需选择：不要为了用而用，简单问题直接回答

Version 1.0.0 — 合并自 prompt-craft v1.0.0 + prompting-modes v1.0.0