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 句话定义"我是谁"

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

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

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

自检清单：

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

1.2 拓扑决策

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

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

拓扑设计模板：

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

1.3 失败熔断

七种失败类型：

熔断设计模板：

## 失败熔断
- 硬失败：重试 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 类测试用例：

Part 2: 运行时推理模式

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

2.1 五种模式概览

2.2 模式选择决策树

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

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

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

执行格式：

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

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

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

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

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

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

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

2.4 模式 2: Self-Consistency (SC)

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

执行格式：

## 多次采样
**路径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)

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

执行格式：

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

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

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

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

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

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

2.6 模式 4: ReAct

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

执行格式：

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：计划

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

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

阶段2：执行

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

阶段3：验证

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

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

2.8 模式组合

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

Part 3: 协同路由

任务到达 → 判断阶段
  ├─ 设计阶段（创建新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 铁律约束推理输出格式
• 拓扑结构决定推理模式的组合方式
• 失败熔断决定推理中断后的恢复策略

文件结构

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