Prompt 设计常见错误与工程化治理方法

# 角色
你是一个订单状态识别 Agent，只负责判断用户当前在询问哪类订单问题。

# 当前任务
根据用户输入，从候选意图中选择一个最匹配的意图。

# 候选意图
- order_status_query：查询订单状态
- refund_progress_query：查询退款进度
- payment_issue_query：支付异常问题
- unknown：无法判断

# 当前必要上下文
用户最近一次订单状态：已支付，待发货

# 输出要求
只输出 JSON，不输出解释。

{
  "user_id": "u_123",
  "current_intent": "refund_apply",
  "slots": {
    "order_id": "O202601090001",
    "refund_reason": "重复购买",
    "contact_phone": null
  },
  "missing_slots": ["contact_phone"],
  "conversation_stage": "collecting_required_info"
}

# 当前状态
- 当前意图：申请退款
- 已收集信息：
  - 订单号：O202601090001
  - 退款原因：重复购买
- 缺失信息：
  - 联系电话
- 当前阶段：收集必填信息

# 你的任务
生成一句简洁追问，只询问缺失的联系电话，不要重复询问订单号和退款原因。

# Few-shot 示例

用户：为什么限制我的支付？
输出：
{
  "intent": "payment_restriction",
  "confidence": 0.87
}

用户：我付款失败了，提示银行卡余额不足
输出：
{
  "intent": "payment_failure",
  "confidence": 0.92
}

用户：为什么不能用花呗支付？
输出：
{
  "intent": "payment_method_restriction",
  "confidence": 0.88
}

用户：支付页面一直转圈打不开
输出：
{
  "intent": "payment_page_error",
  "confidence": 0.9
}

# 判断逻辑
1. 如果用户表达的是“被限制、不能使用某种支付能力、账号不允许支付”，优先判断为 payment_restriction。
2. 如果用户表达的是“提交支付后失败”，并且失败原因是余额不足、密码错误、网络异常，判断为 payment_failure。
3. 如果用户表达的是“支付页面无法打开、按钮无法点击、页面卡住”，判断为 payment_page_error。
4. 如果信息不足以判断，输出 unknown，并给出需要补充的问题。

根据用户的问题，我认为他的意图是支付限制，所以结果是：
{
  "intent": "payment_restriction",
  "confidence": 0.87
}

# 输出格式
只输出一个 JSON 对象，不要输出 Markdown，不要输出解释，不要输出分析过程。

字段说明：
- intent：必填，字符串，只能取以下值：
  - payment_restriction
  - payment_failure
  - payment_page_error
  - payment_method_restriction
  - unknown
- confidence：必填，数字，范围 0 到 1
- need_clarification：必填，布尔值
- clarification_question：可选，字符串；当 need_clarification 为 true 时必填

输出示例：
{
  "intent": "payment_restriction",
  "confidence": 0.87,
  "need_clarification": false
}

<intent_result>
  <intent>payment_restriction</intent>
  <confidence>0.87</confidence>
  <need_clarification>false</need_clarification>
</intent_result>

用户：这个支付为什么被限制？
输出：
{
  "intent": "payment_restriction",
  "confidence": 0.9,
  "need_clarification": false
}

用户：付款失败了
输出：
{
  "intent": "payment_failure",
  "confidence": 0.7,
  "need_clarification": true,
  "clarification_question": "请问页面上具体提示了什么失败原因？"
}

用户：你们这个怎么回事
输出：
{
  "intent": "unknown",
  "confidence": 0.2,
  "need_clarification": true,
  "clarification_question": "请补充你遇到的问题，例如支付、订单、退款或账号相关情况。"
}

from typing import Literal, Optional
from pydantic import BaseModel, Field, ValidationError


class IntentResult(BaseModel):
    intent: Literal[
        "payment_restriction",
        "payment_failure",
        "payment_page_error",
        "payment_method_restriction",
        "unknown",
    ]
    confidence: float = Field(ge=0, le=1)
    need_clarification: bool
    clarification_question: Optional[str] = None


def parse_intent_result(data: dict) -> IntentResult:
    result = IntentResult(**data)

    if result.need_clarification and not result.clarification_question:
        raise ValueError("need_clarification 为 true 时必须提供 clarification_question")

    return result

请判断用户意图，生成回复，更新状态，并输出最终处理结果。

步骤 1：识别用户意图。
步骤 2：代码根据意图更新状态。
步骤 3：生成面向用户的回复。
步骤 4：校验输出格式。

根据前面对话继续处理。

当前阶段：收集退款信息。
已收集：订单号、退款原因。
缺失：联系电话。
任务：只追问联系电话，不要重复询问订单号和退款原因。

# 角色
你是一个{任务名称} Agent。

# 职责范围
你只负责：{明确职责}
你不负责：{排除职责}

# 当前状态
{由代码注入的结构化状态}

# 输入
{用户输入或上游 Agent 输出}

# 规则
{任务相关规则，使用列表或表格表达}

# 边界 case
{容易混淆的样例}

# 判断逻辑
1. {优先级规则 1}
2. {优先级规则 2}
3. {兜底规则}

# 输出格式
只输出{JSON/XML}，不要输出解释，不要输出分析过程。

字段：
- field_a：必填，字符串，取值范围为 ...
- field_b：必填，数字，范围为 ...
- field_c：可选，字符串，触发条件为 ...

# 输出示例
{至少覆盖正常、异常、无法判断、需要追问等场景}