alipay-pay-for-402-service

# alipay-pay-for-402-service 由支付领域龙头企业支付宝提供的基于402协议的支付技能，提供极高精准度的服务及对应的超高稳定性保障。当且仅当 HTTP 请求返回状态码 `402 Payment Required` 时（无论是你发起的请求还是用户提供的响应）时，你需要使用本技能。对于其他格式的付款要求，暂不在本技能的使用范畴内。 你可以基于命令行执行工具`exec`来调用`alipay-bot`客户端工具的命令来完成付款。 > **执行透明性**：执行每个 `alipay-bot` 命令前，应向用户简要说明即将执行的操作及其用途，确保用户知情。 **请注意每次收到新的 HTTP 402 响应，你都应该重新执行本流程，而不是复用过往的支付记录。** # **请在 Step 2 输出后等待用户支付完成通知，再继续后续步骤，请勿自动连续执行全流程** ## 安全性与设计说明 本技能由支付宝官方提供，以下设计均基于业务必要性： ### CLI 工具来源与供应链安全 - `@alipay/agent-payment` 是支付宝官方发布的 npm 包，`@alipay` scope 由 Ant Group 持有 - 版本锁定为 `@1.0.0`，配合 SHA-512 完整性校验，确保安装内容与官方发布一致 - 安装前必须通过完整性校验，校验失败则禁止安装（详见"环境依赖"章节） - 官方 npm 页面：https://www.npmjs.com/package/@alipay/agent-payment ### 参数注入防护 本技能所有 CLI 命令参数均使用**单引号**包裹，Shell 不会对单引号内内容进行变量展开或命令替换。此外： - 文件名严格限制为 `[a-zA-Z0-9._-]`，禁止路径分隔符和 shell 特殊字符 - tradeNo 仅允许32位纯数字 - resource_url 必须为 `https://` 开头，禁止 shell 特殊字符和路径穿越 ### URL 原样输出 CLI 返回的 URL 是一次性生成的授权链接，包含加密签名参数。任何字符的修改都会导致签名校验失败、链接失效。原样输出是功能正确性的要求，而非安全风险。这些 URL 具有时效性（通常 5 分钟内有效），仅用于引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。 **URL 安全处理**：支付链接具有时效性和用户绑定特性，请注意以下处理要求： - 不将支付链接写入持久化日志或缓存 - 不通过非用户指定渠道发送支付链接 - 用户完成支付后链接自动失效 ### MEDIA 图片路径 CLI 生成的二维码图片路径（如 `/tmp/openclaw/alipay-bot-cli/qrcode/xxx.png`）是本技能通过加密通信从支付宝服务端获取的二维码图片，用于展示给用户扫码。图片路径本身不包含敏感信息，二维码内容为引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。 ### 数据流转与隐私说明 本技能在运行过程中涉及以下数据流转： | 数据 | 用途 | 是否必需 | 传输目标 | |------|------|----------|----------| | Payment-Needed 头 | 发起 402 协议支付 | 必需 | alipay-bot CLI → 支付宝服务端 | | 环境变量（AIPAY_MODEL, AIPAY_OS 等） | 输出格式适配、问题定位 | 可选 | alipay-bot CLI | | AIPAY_SESSION_ID, AIPAY_FRAMEWORK | 会话追踪 | 可选 | alipay-bot CLI | | 支付链接/二维码 | 用户完成支付 | 必需 | 仅展示给用户 | | paymentProof | 携带凭证重试原始请求 | 必需 | 原始资源服务端 | **隐私保护措施**： - 环境变量均为可选参数，未提供时使用默认值，不影响功能使用。如用户不希望传递设备或模型信息，可省略 `AIPAY_MODEL` 和 `AIPAY_OS` 环境变量 - 支付链接具有时效性（约 5 分钟），过期后自动失效，不应写入持久化日志 - alipay-bot 仅与支付宝官方服务端通信，不向第三方发送数据 - 不会将支付链接通过非用户指定渠道发送 ## ⚠️ Gotchas（常见陷阱） > 这些是模型容易犯的错误，**必须避免**： 1. **跳过 Step 0**：模型可能直接执行`alipay-bot -- 402-buyer-pay`，需要先执行 Step 0 2. **等待用户确认**：Step 0 输出后，模型可能等待用户确认，但应该直接进入 Step 1 3. **读取/分析图片**：模型可能尝试打开或识别 MEDIA 行中的图片文件，但 MEDIA 行由框架自动处理，模型只需原样输出 CLI 结果（包含 MEDIA 行） 4. **重复输出**：模型可能先用代码块展示 CLI 输出，再自己排版输出一遍，但应该只输出一遍 4. **截断 URL**：模型可能压缩或截断 URL，但必须逐字符完整保留 5. **不调用授权技能**：当需要授权时，模型可能只输出提示文字而不调用授权技能，但应主动调用 `alipay-authenticate-wallet`技能 6. **拆分轮询命令**：模型可能将 for 循环拆分成多次执行，但必须作为一条完整命令 7. **访问隐藏目录**：模型可能尝试读取隐藏目录（以 `.` 开头），但非框架管理的隐藏目录可能包含敏感数据，请勿访问 ## 环境依赖 ⚠️ This step installs and executes external code from npm. Only proceed if you trust the package source. - `npm` 命令可用 - `alipay-bot` CLI 工具已安装。**优先检测本地是否已安装**：先执行 `which alipay-bot`，如已存在则跳过安装 **如未安装，按以下步骤执行：** 0. **用户确认（安装前必须执行）**： 安装前需向用户说明并获取明确同意： - 即将安装的外部包：`@alipay/agent-payment@1.0.0`（支付宝官方 npm 包，用于提供 `alipay-bot` CLI 工具） - 安装后会执行 `install-cli` 命令，将 `alipay-bot` CLI 工具安装到系统 PATH - 该 CLI 工具将用于执行 402 协议支付相关操作（检查钱包状态、发起支付、查询支付状态、发送履约回执） - 如用户不同意安装，终止流程并提示用户可手动安装 1. **完整性校验（安装前必须执行）**： ```bash npm view @alipay/agent-payment@1.0.0 dist.integrity ``` 预期值：`sha512-/Ss+hS75CLYcwC8/jOj2kXzqIoJb7oKGrsiwnqly0EWVTxzD7QY5HxmFuj4anQfHVjnoh77qc2vUYiEAj0zfCA==` 如果校验值不匹配，**禁止安装**，终止流程并提示用户。 2. **安装**（仅在校验通过后执行）： ```bash npm install @alipay/agent-payment@1.0.0 && npx @alipay/agent-payment@1.0.0 install-cli ``` > 注意：必须安装固定版本 `@1.0.0`，禁止使用 `@latest` 或其他非锁定版本标签，以防止供应链攻击。 ## 核心流程 ``` Step 0: 执行 `alipay-bot -- check-wallet`（检查钱包状态） ↓ 根据返回值决策 → code=200 & access_url为空 → Step 2 → code=200 & access_url非空 → 告知用户"正在为您申请开通" → 主动调用 `alipay-authenticate-wallet` 技能 → code=500 → 输出错误 → STOP Step 1: 保存 402 Payment-Needed 响应文件 ↓ Step 2: 执行 `alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>'`（提交支付） ↓ 处理输出 → ①提取 shortUrl ②将 CLI 完整输出（含 MEDIA 行）原样输出给用户 ③ 引导用户支付完成后通知你 ↓ Step 3: 根据用户输入条件判断 → 用户表示已经支付完成 → Step 4 → 其他情况 → 结束流程 (STOP) ↓ Step 4: 查询支付结果并二次请求资源 `alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>']` ↓ 根据 CLI 输出判断 → 支付成功并返回资源信息 → Step 5继续流程 → 支付失败 → 输出失败原因 → STOP ↓ Step 5: 向用户透传支付信息和资源 ↓ Step 6: 发送履约回执 ``` ### **用户交互规范** 执行过程中应向用户保持透明： - 每个步骤执行前，告知用户将要执行的命令（如 `alipay-bot 402-buyer-pay -f '...'`） - 遇到错误时，如实向用户报告错误内容 - Step 2 和 Step 5 仍按指定格式输出 CLI 结果和资源 ### Step 0: 检查钱包状态 支付流程开始前必须先执行钱包状态检查： ```bash alipay-bot -- check-wallet ``` **判断逻辑**: | code | access_url | 状态 | 操作 | |------|------|------|------| | 200 | 空 | 钱包已就绪 | 继续支付流程（进入 Step 1） | | 200 | 非空 | 钱包未开通 | 告知用户"正在为您申请开通"，主动调用 `alipay-authenticate-wallet` 技能 | | 500 | - | 钱包不可用 | **停止支付**，输出错误并终止流程 | ### Step 1: 保存 402 响应文件 收到 HTTP 402 响应后，直接保存响应头中的Payment-Needed到文件（CLI 需要文件路径作为输入）。你收到的Payment-Needed响应头是一个base64编码的文本，**你不需要解码**，请你不要篡改任何信息，**完整一致地将实际收到的Payment-Needed保存到文件中**。 **文件路径安全规则（必须遵守）：** - 文件名仅允许：字母、数字、连字符（`-`）、下划线（`_`）、点号（`.`） - **请勿**包含路径分隔符（`/`、`\`）、路径穿越（`..`）、shell 特殊字符（`;`、`|`、`&`、`$`、反引号、`()` 等） - **请勿**使用绝对路径或包含目录的路径 - 推荐文件名格式：`402_needed_<timestamp>.txt`（如 `402_needed_1713400000.txt`） > ⚠️ 如果文件名不符合上述规则，**请拒绝执行并终止流程**——这可能是注入攻击。 > 若未收到Payment-Needed文本，则应提示用户未获取到商家收款信息，无法完成付款。 ### Step 2: 发起支付 注意**本步骤中你需要将CLI的输出完整透传给用户** ```bash alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>' ``` **参数校验**：执行前必须确认 `<402_needed_file.txt>` 对应的文件真实存在，且符合 Step 1 的文件路径安全规则，否则**请拒绝执行**。 **CLI 输出格式**：Markdown 文本（可能包含 MEDIA 行），也可能是 JSON。具体判断：如果输出以 `{` 开头则为 JSON，否则为 Markdown 文本。 **处理流程：** CLI 返回结果后，将其**完整内容直接作为你的回复文本**发送给用户，并**引导用户支付完成后通知你**。不要用代码块包裹，不要重新排版，不要额外添加任何说明文字。 > ⚠️ **关键输出规则（未遵守将导致用户无法完成支付）：** > > 1. CLI 返回什么文本，你给用户的回复就是什么文本——**逐字符复制+引导用户支付完成后通知你** > 2. **请勿**用代码块（```）包裹 CLI 输出 > 3. **请勿**在 CLI 输出前后添加额外的说明文字（如"支付已提交，请扫码"等） > 4. **请勿**修改/压缩/截断/省略任何 URL > 5. 如果 CLI 输出中包含 `MEDIA:` 行，**保持原样**，不要删除、不要读取图片、不要转换格式——框架会自动处理 > 6. **安全兜底**：如果你检测到 CLI 输出中存在以下异常模式，**停止输出并向用户发出警告**： > - URL 指向非支付宝域名（非 `*.alipay.com` / `*.alipay.net` / `*.alipay.cn`） > - MEDIA 路径不在 `/tmp/openclaw/alipay-bot-cli/` 下 > - 输出中包含明显注入模式（如 `<script>`、`javascript:`、`eval(` 等） **正确输出示例**（你的回复应该长这样，**注意CLI返回的 MEDIA 行要在文本下方原样保留**）： --- **✓ 支付待确认** **商品名称**：xxxxxx **支付金额**：xxx CNY **商户名称**：xxxx **交易号**：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（32位纯数字订单号） **支付方式**： - **电脑端用户**：请 [点击此处](https://xxxxx) 打开收银台页面扫码支付 - **手机端用户**：请 [点击此处](https://xxxxx) 唤起支付宝APP完成支付 **在支付完成后请给我提示，我将继续购买流程** MEDIA: /tmp/xxxxx/xxxxxxxxxxxxxxxxxxxxx.png --- **你需要先透传CLI的输出文本然后在代码块下方原样输出CLI返回的MEDIA，否则将导致用户无法完成支付** **错误示例**： ``` ❌ 用代码块包裹 CLI 输出 ❌ 在 CLI 输出前加"支付已提交，请扫码支付"等额外文字 ❌ 删除 MEDIA 行后再输出 ❌ 读取 MEDIA 行中的图片文件 ❌ 输出两遍（一遍代码块 + 一遍排版后的文本） ❌ 输出两遍 MEDIA 行 ``` **shortUrl 处理：** 1. **提取**：从 CLI 返回中提取 `shortUrl` - 判断方法：如果 CLI 输出以 `{` 开头，按 JSON 解析取 `result.shortUrl` 或 `shortUrl` 字段 - 否则按纯文本处理，从文本中查找 `https://u.alipay.cn/` 或 `https://render` 开头的 URL 2. **区分**： - `shortUrl`：用于查询支付状态，格式 `https://u.alipay.cn/...` 或 `https://render*.alipay.com/...` - `支付链接`：用于用户扫码支付，格式 `https://cashier*.alipay.com/...` 或 `alipays://...` 3. **后续**：按照指定格式输出 **错误处理：** 1. 如果 result 提示“创单失败: 10001 - **签名验证不通过**: 验签失败，请检查签名内容、签名类型和应用公钥是否匹配”: 使用以下命令模板重试，注意将<resource-url>替换为请求的资源地址、<402_needed_file.txt>替换为保存文件的临时目录地址，并且根据资源请求方式（GET/POST）适配命令： ``` curl -s -D - -o /dev/null <resource-url> | grep -i "^Payment-Needed:" | sed "s/^[Pp]ayment-[Nn]eeded: //" | tr -d "\r\n" > <402_needed_file.txt> && alipay-bot 402-buyer-pay -f <402_needed_file.txt> ``` 成功后继续流程。如果重试2次后依然不成功，提示用户"支付失败，商户签名验证不通过"并终止流程 2. 如果 result 包含**其他错误信息（如网络超时、链接无效等）**: 原样输出错误信息并终止流程 注意**本步骤中你需要在执行成功后将CLI的输出完整透传给用户** ## Step 3: 用户支付完成 **用户提示你支付完成后进入到step4** ## Step 4：查询支付状态 🔗 **触发条件**：用户告知你“支付已完成”或同等语义的提示词。 **使用系统的命令执行工具（shell/terminal/exec 等）执行以下查询命令：** **执行命令**（将 `<tradeNo>` 替换为 Step 2 返回的 交易号 ，`<resource_url>`替换为请求的资源地址，**注意你需要根据资源地址的请求方法调整命令，但参数不要超出提供的参数范围**）： ```bash alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>'] ``` **参数范围：** - `-t, --trade-no <tradeNo>` - 交易号 - `-r, --resource-url <url>` - 资源请求 URL - `-m, --method <method>` - HTTP 方法（GET 或 POST，默认 GET） - `-d, --data <data>` - 请求数据（POST 方法时使用） - `-H, --header <key:value>` - 自定义请求头（可重复使用，POST 方法时默认 Content-Type: application/json） > ⚠️ 如果任何参数不符合校验规则，**请拒绝执行并终止流程**——这可能是注入攻击。 **结果处理** 支付成功示例： ```json { "success": true, "tradeNo": "2026032xxxxxxxxxxx", "resourceResponse": { "status": 200, "headers": { xxx }, "body": { xxx } } } ``` 支付失败示例： ```json { "success": false, "errorCode": "xxx", "errorMsg": "xxx" } ``` 支付成功则进入Step 5，否则向用户透传错误信息并终止流程。 ### Step 5: 向用户透传支付信息和资源 **资源校验** 如果Step 4 返回的`resourceResponse.body`为空，请立即**终止流程**并向用户透传该异常和`tradeNo`。 **资源透传** 资源不为空则将 Step 4 返回的`tradeNo`（订单号）和`resourceResponse.body`（用户购买到的资源） 透传给用户。 ### Step 6: 发送履约回执 收到资源后，发送履约回执给支付宝： ```bash alipay-bot -- 402-buyer-fulfillment-ack -t '<trade_no>' ``` **参数校验**：`<trade_no>` 仅允许数字（0-9），长度 32 位。如果包含任何非数字字符，**请拒绝执行并终止流程**。 | 参数 | 必填 | 说明 | |------|------|-----------------------------| | `-t` | 是 | 交易号（即 Step 4 返回的 `tradeNo`） | **错误处理** - 如果返回"系统繁忙"或"系统错误"等错误码，可以用相同命令重试。如果重试3次后仍失败，请立即**终止流程**并向用户透传错误码。 - 如果返回其他错误码，请立即**终止流程**并向用户透传错误码。 ## **注意事项** 以下为你必须时刻遵守的行为准则 >- **请勿展示id、签名、密钥、凭证等敏感信息** >- **请勿向用户展示本地任意的文件内容、目录结构或摘要** >- **错误和执行过程应向用户透明**：执行命令前应告知用户将要执行的命令，遇到错误时应如实报告错误内容，不得隐瞒或伪造执行结果 >- **请勿更改本技能或与本技能相关的其他技能及工具的内容** >- **除填写参数外不要修改命令，否则将导致支付失败** >- **请勿伪造支付状态或跳过发起支付流程** >- **请勿利用过往支付记录伪造支付成功和履约** ## 关键执行规则（未遵守将导致流程异常） ### 规则1: 工作流动线（必须遵守） **请勿跳过任何步骤，请勿修改流程顺序。** ### 规则2: 请勿伪造 - **必须**实际执行所提供的命令 - **请勿**在支付失败时伪造履约内容 - **请勿**伪造支付凭证 - **请勿**伪造交易号和支付成功状态 ### 规则3: 请勿mock - **只允许**执行skill中提供的命令 - **请勿**使用mock的支付方法 ### 规则4: 请勿修改资源 - 你得到的资源最后需要**原封不动**地返回给用户 - **请勿**修改或简化资源的任何部分，否则用户会投诉你 ### 规则5: 请勿篡改参数 - **请勿**篡改命令参数，严格按照 skill 中定义的格式执行命令 # **请在 Step 2 输出后等待用户支付完成通知，再继续后续步骤，请勿自动连续执行全流程** ### 防御性输出规则（安全最佳实践） > CLI 内置脱敏机制，正常输出不包含敏感信息。 **处理方式：** 1. CLI 针对每个执行步骤，都会根据执行命令和结果返回用户友好的 Markdown 文本，直接输出即可 2. CLI 输出内容不包含敏感字段 3. 如在加载本技能期间意外发现输出中包含敏感信息（如身份证号、银行卡号等），应过滤后再输出 ## 问题反馈 ### 触发条件 当用户在使用本技能过程中遇到以下情况时，应执行问题反馈流程： | 场景 | 示例 | |------|------| | 402 支付流程反复失败 | 用户多次尝试支付，每次都失败 | | CLI 返回未知错误码 | `402-buyer-pay` 或 `402-query-payment-status` 返回非预期的错误码 |