My Pay Skill
Overview
本 Skill 包含两部分能力：
- 免费基础能力：无需付费即可使用的入门功能（在此描述你的免费部分）。
- 付费核心内容：托管在你的自有服务端，按次收费，通过支付宝 AI 按量付费（A2M 402）协议完成支付与交付。
> ⚠️ 上线前必改的三处占位符：
> 1. SERVICE_URL：替换为你的自有服务器地址（禁止与 Skill 包托管地址相同）
> 2. 单价：PRICE_PLACEHOLDER（支付宝登记价 = 服务端账单价 = SkillHub 展示价，三处必须一致）
> 3. 沙箱 api_mock_service_id：替换为真实 service_id（上线前必须替换，保留沙箱标识将无法通过审核）
免费基础能力
[在此描述免费部分的功能与用法。付费验付失败时，本 Skill 自动降级为免费基础能力继续工作，不让用户走死路。]
付费内容说明
- 付费资源端点（SERVICE_URL）：
https://YOUR-SERVER.example.com/api/resource - 计费方式：按次付费，单价以服务端下发的 402 账单为准（当前配置：
PRICE_PLACEHOLDERCNY/次） - 付费内容：[描述付费后交付的具体内容]
支付流程（支付宝 AI 按量付费 / HTTP 402）
服务端为已通过线上验证的支付宝 AI 按量付费（A2M 402）服务。Agent 按以下三步执行，付款、收银与签名全部交给支付宝官方能力完成。
第一步：取账单（probe）
未付款请求付费资源，服务端返回 HTTP 402 Payment Required，响应头 Payment-Needed 携带 Base64URL 编码账单：
python scripts/pay_client.py --info
解析出的账单结构：
{
"out_trade_no": "订单号（全局唯一）",
"amount": "PRICE_PLACEHOLDER",
"currency": "CNY",
"goods_name": "my-pay-skill 付费内容",
"service_id": "你的 service_id"
}
第二步：收银（pay）
⚠️ 必须先向用户明示金额、商品与收款方，取得用户明确同意后才能继续。
由官方买家能力收银，意图摘要必须写清原始业务目的，保留用户最初想做的事：
alipay-bot 402-buyer-pay \
--resource-url "https://YOUR-SERVER.example.com/api/resource?skill=my-pay-skill&feature=default" \
--intent-summary "获取 my-pay-skill 的付费核心内容"
用户完成支付后取得 Payment-Proof 凭证。
第三步：取回资源（complete）
携带 Payment-Proof 重试同一个原始请求（URL、feature、请求头与请求体逐字节一致，付款后不重新下单），服务端流程：
- 调用官方验付接口
alipay.aipay.agent.payment.verify验证凭证 - 本地校验：
active=true且账单金额、订单号、资源标识与请求一致，不一致只返回 402，不交付资源 - 验付通过后下发付费内容，
HTTP 2xx即履约完成 - 服务端发送履约确认回执：
alipay.aipay.agent.fulfillment.confirm（同一订单重试保持幂等，即 ack）
python scripts/pay_client.py --payment-proof "<Payment-Proof 凭证>"
Agent 注意事项
- 三步复用同一个原始请求，付款后不重新下单；
- 需要支付时以退出码
2退出，并在 stdout 输出账单 JSON（含bill、next_action），等待用户确认； - 支付状态不明时先查单（官方
alipay-bot 402-query-payment-status），不重复付款、不追加独立回执； - 履约回执失败时服务端对同一订单重试并保持幂等，不因回执失败要求用户重新付款；
- 验付失败（凭证无效或过期）时服务端不交付资源，本 Skill 自动降级为免费基础能力继续工作。
订单持久化与幂等（服务端强制规范）
- 订单以
out_trade_no为主键落盘持久化（数据库或文件），禁止使用内存 Map——进程重启后订单状态必须可恢复； - 订单状态机：
PENDING（已出账单）→PREPARED（验付通过）→FULFILLED（已交付并 ack）； - 同一
out_trade_no的验付、交付、回执操作全部幂等，防止重复扣费或重复交付； - 详细协议与本地校验清单见
references/payment-protocol.md。
错误处理
| 场景 | 处理方式 |
|---|---|
| 未付款请求 | 服务端返回 402 + Payment-Needed 账单 |
| 用户拒绝支付 | 降级为免费基础能力，告知付费内容的价值 |
| 验付失败 | 不交付资源，返回 402，提示重新发起 |
| 支付状态不明 | 调官方查单能力确认，不重复下单 |
| 回执发送失败 | 服务端重试同一订单，幂等处理 |
Resources
scripts/
pay_client.py：买家端付费流程脚本（probe 解析 402 账单 / 携带 Payment-Proof 重试），无需第三方依赖。
references/
payment-protocol.md：402 协议细节、服务端验付 6 项本地校验、审核自查 8 项清单。server-reference.md：服务端参考实现说明（402 控制器、订单持久化、履约确认）。
server/
app.py：服务端参考实现（纯标准库，可本地联调完整 402 闭环；上线前按references/server-reference.md完成生产化替换）。
