提示词工程

硬约束与边界 — 5 个 Anti-pattern 修复

以下是生产中最常见的提示词错误，每条附修复方案：

❌ Anti-pattern 1：约束用「尽量/应该」等软词
尽量不要输出敏感信息。

✅ 修复：用「禁止/必须」+ 机器可检测的边界信号
禁止输出任何匹配 /[A-Za-z0-9+/]{40,}={0,2}/ 的字符串（可能是密钥）。
若检测到，输出 REDACTED 并停止。

❌ Anti-pattern 2：角色描述空泛
你是一个有帮助的 AI 助手。

✅ 修复：角色包含领域、语气、禁止的隐含行为
你是 Acme 公司 B2B 售前工程师，仅回答与 Acme 产品相关的技术问题，
不承诺未在官方文档出现的功能，不贬低竞品。

❌ Anti-pattern 3：输出格式只说「输出 JSON」
请以 JSON 格式回答。

✅ 修复：给出完整 schema + 禁止额外包装
仅输出如下 JSON，无围栏外文字，无注释，无尾逗号：
{"items": [{"id": "string", "score": 0.0}], "total": 0}

❌ Anti-pattern 4：Few-shot 示例与正式 schema 不一致
（示例输出宽松 Markdown，正文要求严格 JSON）

✅ 修复：示例输出格式必须与正文 schema 完全一致
示例 → 输出：{"items": [...], "total": 2}  ← 与正文 schema 相同

❌ Anti-pattern 5：没有空输入/工具失败的处理路径
（静默返回空或随机编造）

✅ 修复：显式定义降级输出格式
输入为空时输出：{"error": "EMPTY_INPUT"}
工具调用失败时输出：{"error": "TOOL_ERROR", "detail": "{原因}"}

少样本（Few-shot）正确格式

Few-shot 示例必须覆盖：①正常路径、②边界/空输入、③工具失败或歧义。每个示例是一个完整的「输入 → 输出」对，输出格式与正文 schema 完全一致。

## 示例（放在系统提示的 EXAMPLES 区块）

示例 1 — 正常路径
用户输入：{"order_id": "ORD-9921", "question": "发货了吗？"}
期望输出：{"answer": "ORD-9921 已于 2024-03-12 发出，预计 3 日内到达。", "citations": ["order-db/ORD-9921"]}

示例 2 — 信息不足（触发 MISSING_FIELDS）
用户输入：{"question": "我的订单到了吗？"}
期望输出：{"error": "MISSING_FIELDS", "fields": ["order_id"]}
// rationale：问题中无订单号，无法查询，不能猜测

示例 3 — 工具调用失败
用户输入：{"order_id": "ORD-0001", "question": "物流状态？"}
工具返回：{"status": 503, "message": "数据库超时"}
期望输出：{"error": "TOOL_ERROR", "detail": "物流查询服务暂时不可用，请稍后重试。"}

示例 4 — 越界问题（触发拒答）
用户输入：{"question": "你们竞品 XYZ 的价格是多少？"}
期望输出：{"error": "OUT_OF_SCOPE", "suggestion": "请访问 XYZ 官网获取价格信息。"}

• 核心 2 例放在系统提示中，其余示例通过 RAG 检索按需注入，避免挤占指令区 token。
• 示例中一律用占位符替代真实订单号、客户名、密钥。

结构化输出 — 完整 Schema 示例

提示中必须给出完整的输出 schema，包括字段名、类型、枚举值、必填项和 null 处理。不能只说「输出 JSON」。

// 在系统提示中这样定义输出 schema：
仅输出以下 JSON 结构，无 Markdown 围栏外的任何文字，无注释，无尾逗号：

{
  "status": "success" | "partial" | "failed",   // 必填，枚举
  "items": [
    {
      "id": "string",          // 必填，来自检索结果的原始 id
      "title": "string",       // 必填
      "score": number,         // 0.0–1.0，保留两位小数
      "snippet": "string | null"  // 无摘要时为 null，禁止省略此字段
    }
  ],
  "total": number,             // items 数组长度，必填
  "error": "string | null"     // status 为 failed 时必填，否则为 null
}

// 正确示例（status=success）：
{"status":"success","items":[{"id":"doc-42","title":"安装指南","score":0.91,"snippet":"运行 npm install..."}],"total":1,"error":null}

// 正确示例（status=failed）：
{"status":"failed","items":[],"total":0,"error":"检索服务超时，请重试"}

• 禁止尾逗号（JSON 标准不支持），禁止 // 注释（JSON 标准不支持）。
• 若下游用 JSON.parse，在提示中明确：「仅输出 JSON 对象，第一个字符必须是 {」。

提示前后对比 — 完整改写示例

同一个「邮件回复」任务，模糊版本 vs 完整四块式版本的实际差异：

────────────────── 修改前（3 行，无结构）──────────────────
你是助手，帮用户写邮件回复。
客户来信：{customer_email}
请给我一个专业的回复。

问题：语气不确定 / 可能编造政策 / 输出格式不可解析 / 没有失败路径

────────────────── 修改后（四块式，可测试）──────────────────
## 角色
你是 Acme 公司 B2B 客服，语气专业、简短，使用「您」敬称客户。

## 任务
根据「客户来信」和「知识库条目」起草回复邮件正文（不含主题行）。
成功判据：回复包含 greeting、body、closing 三段，body 针对来信中的具体问题。

## 约束
- 不承诺知识库中未出现的退款政策或交货日期。
- 不编造订单号或产品型号。
- 若信息不足以回答，body 字段输出：「请提供以下信息：[问题列表，不超过3条]」
- 工具调用失败时输出 {"error": "TOOL_ERROR", "detail": "{原因}"}

## 输出格式
仅输出以下 JSON，无围栏外文字，无注释，无尾逗号：
{"greeting": "string", "body": "string", "closing": "string"}

提示迭代循环 — 版本控制规范

把提示演进当成代码发布：每次改动必须对应可复现的失败样本和验收用例。commit message 格式建议如下：

# 提示词 commit message 格式（参考 Conventional Commits）
prompt(scope): 动作 — 失败原因摘要

# 实际示例：
prompt(email-reply): fix — 模型在缺少订单号时仍生成回复而非 MISSING_FIELDS
prompt(email-reply): feat — 新增 confidence 字段到输出 schema
prompt(email-reply): refactor — 将约束从散文改为编号列表，提高解析稳定性
prompt(search): fix — few-shot 示例 schema 与正文不一致导致格式漂移

# CHANGELOG 条目（放在提示仓库的 CHANGELOG.md 或 SKILL front matter）
## v1.3.0 — 2024-03-15
### Changed
- section-constraints: 新增 TOOL_ERROR 信号格式
- section-output: score 字段类型从 string 改为 number（破坏性变更）
### Fixed
- few-shot 示例 #2 的输出格式与正文 schema 对齐
### Test
- 新增 golden 用例：empty_input, tool_timeout, out_of_scope

    [ 起草 / 变更 vN ]
          │
          ▼
    [ 固定用例 + 红队用例（边界/对抗）]
          │
     ┌────┴────┐
     ▼         ▼
 [解析/业务 OK?]  [记录失败模式 → 最小修改]
     │
     ▼
    [ commit: prompt(scope): fix — 失败原因 ]
          │
          ▼
    [ 更新 CHANGELOG + golden 文件 ]
          │
          ▼
    [ 发布到仓库 / 运行时配置 ]

草稿估算与模板

下方文本框用于粗略估算长度：字符数实时统计；token 按常见启发式「约 ÷4」（中英混合时仅供参考）。按钮轮换填入三个预置模板（四块式 / 目标-判据式 / 工具调用式），可直接在此修改后复制到正式提示仓库。