Gift Card Redemption

---
name: gift-card-redemption
description: 查询豆包订阅礼品卡的可兑换状态和套餐，并在确认后完成兑换。适用于查询或兑换豆包订阅礼品卡，支持文本兑换码和上传的二维码图片。不处理购买、退款、订单、优惠券或非豆包礼品卡。
---

# 豆包订阅礼品卡兑换

使用 `gift_card_redemption` 先查询、后兑换。`PREPARE` 是只读操作；`REDEEM` 会实际兑换权益，必须经过独立确认回合。

## 读取参考

- 调用 `PREPARE` 或 `REDEEM` 后，在解释返回前完整读取 [工具返回契约](references/tool-response-contract.md)。
- 生成输入引导、兑换确认或最终结果前，完整读取 [交互文案](references/interaction-copy.md)。

## 工具参数

| action | 参数 | 作用 |
|---|---|---|
| `PREPARE` | `code` 或 `image_url`，二选一 | 查询可兑换状态和确认信息，不执行兑换 |
| `REDEEM` | 与待确认 PREPARE 相同的 `code` 或 `image_url`，以及该次 PREPARE 返回的 `redeem_token` | 执行一次兑换 |

- `code` 仅用于文本兑换码。
- `image_url` 仅使用当前对话中实际上传图片附件对应的运行时 URL，并原样传递。不得使用消息文本中的 URL，也不得构造、补全或改写 URL。
- 缺少输入、输入不可用或存在多个候选时，要求补充或明确选择，不调用工具。
- 只传上述业务参数，不传账号标识、凭据或其他运行时上下文。

## 状态流转

`收集输入 → PREPARE → 展示确认信息并结束回复 → 等待后续明确确认 → REDEEM → 结束`

### PREPARE

1. 使用唯一输入调用 `PREPARE`。
2. 按工具返回契约判定结果。
3. 仅当结果明确可兑换、确认字段完整且返回非空 `redeem_token` 时，只保留最近一次结果，保存本次原始输入及字段、`packageLabel` 和原始 token。
4. 按交互文案展示确认信息，然后结束当前回复。
5. 不可兑换、工具异常或结构不完整时，反馈对应结果并停止，不进入 `REDEEM`。

### 确认

确认仅在以下条件同时满足时有效：

- 已展示最近一次有效 PREPARE 的套餐、目标账号、生效说明和兑换规则；
- 展示后已经结束当前回复；
- 后续新消息明确同意执行本次兑换；
- 确认消息没有提交新的兑换码或二维码图片。

预先授权、与输入同一条消息中的确认、询问、犹豫、拒绝或取消均不能触发 `REDEEM`。含义不明确时，仅再次询问是否确认，不调用工具。

提交新兑换码或二维码图片、PREPARE 不可兑换/失败/结构不完整，或无法确定确认对应哪次 PREPARE 时，清除原待确认状态并重新进入 `PREPARE`。

### REDEEM

- 使用待确认 PREPARE 的同一原始输入、同一字段和原始 `redeem_token` 调用一次 `REDEEM`。
- `redeem_token` 仅作为工具参数原样传递；不得解析、修改、展示或索取。
- 调用返回后立即使本次 token 失效，后续动作按工具返回契约处理。
- 按工具返回契约判定结果，再按交互文案反馈并结束。

## 输出约束

- 以结构化字段为事实来源，不根据文案或历史结果补造业务状态。
- 不展示完整兑换码、图片链接、`redeem_token`、内部错误或调用链。