@alipay/alipay-aipay 1.7.0 → 1.7.2

package/skill-pre/references/integration/modules/interface-contract/notify-url-contract.md

@@ -0,0 +1,68 @@
+# 异步通知本地契约
+
+本文是 AI 网页应用收款和 AI 移动应用收款共用的异步通知实现依据。AI 按量付费不使用本契约。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/async-notify-verify.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/async-notify-verify.md>
+
+当前两份官方文档内容一致。运行时默认读取本文和当前语言 `1-通用接口/异步通知处理代码示例.md`；在线文档只在 fallback 条件下读取。
+
+## 适用范围
+
+| 产品 | 是否适用 | 说明 |
+| --- | --- | --- |
+| AI 网页应用收款 | 是 | `alipay.trade.page.pay` 下单时通过公共参数 `notify_url` 指定 |
+| AI 移动应用收款 | 是 | `alipay.trade.app.pay` 下单时通过公共参数 `notify_url` 指定 |
+| AI 按量付费 | 否 | 使用 `Payment-Proof` 验付和履约确认，不使用统一收单异步通知 |
+
+`notify_url` 是商家服务端接收支付宝 POST 表单通知的地址，不是前端页面地址，也不是支付宝生成的 URL。
+
+本地正式验收或本地生产参数验收时，若暂时没有公网 HTTPS 通知地址，可以不传 `notify_url`，但仍必须实现通知处理代码并用交易查询兜底。不要向 SDK 传 `undefined`、`null`、空字符串或占位 URL；没有可用地址时应直接省略该字段或不调用对应 setter。真实生产或公网联调时必须传入可公网访问的 HTTPS `notify_url`，地址不能包含多余字符或发生重定向。
+
+## 必须实现的处理链路
+
+1. 接收支付宝 POST 表单参数，不能按 JSON 请求体解析。
+2. 收集完整参数 map，验签前不得丢字段、改字段名或改字段值。
+3. 用通知中的 `app_id` 在本地选择运行时支付配置和验签上下文；这是为了选择本地支付宝公钥或 SDK 实例，不表示信任通知内容。
+4. 使用当前项目已安装的支付宝 SDK 验签能力验证 `sign`；Java 官方示例为 `AlipaySignature.rsaCheckV1`。
+5. 验签失败时记录脱敏异常并返回纯文本 `fail`。
+6. 验签通过后，用 `out_trade_no` 查询商家本地订单，并校验 `app_id`、`out_trade_no`、`total_amount`、`seller_id` 或 `seller_email`。
+7. `app_id`、`seller_id` / `seller_email` 以运行时支付配置为准，不默认从订单对象或通知参数本身取可信预期值。
+8. 只有 `TRADE_SUCCESS` 或 `TRADE_FINISHED`，且不是退款、关单、分账等事件时，才认定买家付款成功；至少排除 `out_biz_no`、`gmt_refund`、`refund_fee` 等事件特征。
+9. 使用持久化订单状态、`notify_id`、`out_trade_no`、`trade_no` 和事件类型做幂等处理，避免重复发货、重复记账或重复变更。内存订单、内存 Map 或进程内锁只能用于非生产 demo。
+10. 业务处理成功后返回纯文本 `success`；不是 `success` 时支付宝会按策略重试。
+11. 未收到通知或支付状态未知时，必须调用 `alipay.trade.query` 补偿查询。
+
+默认至少处理参数：`notify_type`、`notify_id`、`sign_type`、`sign`、`trade_no`、`app_id`、`out_trade_no`、`trade_status`、`total_amount`、`seller_id` 或 `seller_email`。退款或其他事件可能出现 `out_biz_no`、`gmt_refund`、`refund_fee`，不能误判为付款成功。
+
+## 状态处理
+
+| `trade_status` | 默认处理 |
+| --- | --- |
+| `TRADE_SUCCESS` | 买家付款成功；同时确认不是退款、关单、分账等事件后，幂等标记本地订单已支付 |
+| `TRADE_FINISHED` | 交易结束且付款成功；同时确认不是退款、关单、分账等事件后，幂等标记本地订单已支付 |
+| `WAIT_BUYER_PAY` | 不认定付款成功；记录或忽略，必要时等待查询 |
+| `TRADE_CLOSED` | 不认定付款成功；可记录关闭或退款完成事件 |
+
+退款通知、关闭通知、分账通知等不是付款成功通知。通知本身验签和业务归属校验通过后，可以返回 `success` 避免重复推送，但不得把本地订单改成已支付。支付成功通知至少满足付款成功状态且不包含 `out_biz_no`；退款通知通常包含 `gmt_refund`、`refund_fee`、`out_biz_no`。
+
+## 验收分层
+
+- 本地正式验收 / 本地生产参数验收模式：允许暂时没有公网 HTTPS `notify_url`，但通知处理代码、验签、业务字段校验、持久化幂等和主动查询兜底必须存在；公网通知联调标记为人工待验证。没有可用通知地址时省略 `notify_url`，不要向 SDK 传 `undefined`、`null`、空字符串或占位 URL。
+- 真实生产上线：必须配置公网 HTTPS `notify_url`，完成支付宝服务器可访问联调、验签、关键字段校验、幂等处理、返回 `success` 和补偿查询。
+
+没有完成真实生产上线层时，不得表述为生产就绪或正式上线完成。
+
+## 本地示例索引
+
+| 语言 | 示例 |
+| --- | --- |
+| Java | `code-examples/java/1-通用接口/异步通知处理代码示例.md` |
+| Python | `code-examples/python/1-通用接口/异步通知处理代码示例.md` |
+| Node.js | `code-examples/nodejs/1-通用接口/异步通知处理代码示例.md` |
+| PHP | `code-examples/php/1-通用接口/异步通知处理代码示例.md` |
+| C# | `code-examples/csharp/1-通用接口/异步通知处理代码示例.md` |
+
+Java 官方示例明确使用 `AlipaySignature.rsaCheckV1`。Node.js 示例给出 `checkNotifySignV2(params)` 的落地形态，但 Agent 落地前必须先读取目标项目 `alipay-sdk` 的 package.json 和类型定义，确认当前版本确实暴露该 API。Python、PHP、C# 示例使用项目内支付宝 SDK 验签适配器表示验签边界；适配器必须封装当前项目实际 SDK API，禁止临时手写不确定的 RSA 验签实现。

package/skill-pre/references/integration/modules/interface-contract/webpay-interface-contract.md

@@ -0,0 +1,44 @@
+# AI 网页应用收款本地接口契约
+
+本文是 AI 网页应用收款专用下单接口的默认本地依据。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.md>
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.md>
+
+## 默认范围
+
+AI 网页应用收款必须覆盖：`alipay.trade.page.pay`、交易查询、退款、退款查询、关闭交易、异步通知和默认同步回跳结果页。
+
+查询、退款、退款查询、关闭交易读取 `common-trade-contract.md`；异步通知读取 `notify-url-contract.md`。
+
+官方目录中的 `alipay.data.dataservice.bill.downloadurl.query` 不是当前 Skill 默认交付项。用户明确要求对账时再按在线文档 fallback 处理，不能加入默认 checklist。
+
+## 下单接口
+
+`alipay.trade.page.pay` 是AI 网页应用收款唯一默认下单接口，电脑网页、手机浏览器网页和 H5 场景均使用该接口，不改用其他网页支付产品接口。
+
+公共参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `method` | 固定 `alipay.trade.page.pay` |
+| `notify_url` | 生产或公网联调时传入；本地生产参数验收模式可临时不传，但通知处理代码必须存在 |
+| `return_url` | 用户未明确关闭同步回跳时默认传入，且对应当前项目实际 GET 路由 |
+
+业务参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `out_trade_no` | 必填，商户订单号，商户侧唯一 |
+| `total_amount` | 必填，单位元，精确到小数点后两位，范围 `[0.01,100000000]` |
+| `subject` | 必填，订单标题 |
+| `product_code` | 必填且固定 `FAST_INSTANT_TRADE_PAY` |
+
+## 响应与结果
+
+- 必须使用页面跳转方法：Java `pageExecute`、Python `page_execute`、PHP `pageExecute`、Node.js `pageExec`、C# `PageExecute`。
+- 推荐 POST 方式，响应为 HTML form 或同等页面跳转内容，必须在浏览器渲染并提交。
+- `curl` 获取到 HTML form 只能证明接口有响应，不能替代浏览器付款入口和沙箱付款体验。
+- `return_url` 或前台页面只作支付结束通知，不能作为付款成功依据；付款成功以验签通过的异步通知或交易查询为准。

package/skill-pre/references/integration/modules/interface-guide.md

@@ -0,0 +1,61 @@
+# 接口说明与代码示例索引
+
+本文件只做本地接口契约和代码示例路由。正常代码开发默认读取本地契约与当前语言示例；在线文档只作为 `sourceUrl` 和 fallback，不作为默认运行时必读材料。
+
+本文中的 `./code-examples/...` 路径一律相对本文件所在目录 `references/integration/modules/` 解析。从 `references/integration/flow.md` 所在目录读取示例时，实际路径必须写成 `modules/code-examples/...`；例如 Node.js AI 按量付费示例是 `modules/code-examples/nodejs/4-按量付费/A2MPaymentDemo.md`。禁止查找不存在的 `references/integration/code-examples/...`。
+
+## 默认读取路由
+
+下表同时是 `integration_context_runner.mjs` 的产品路由事实源。修改产品契约、示例或沙箱验收边界时只改本表，不在 runner 中维护副本。
+
+| productType | 产品 | 必读本地契约 | 必读示例目录 | 沙箱验收动作 | 沙箱参考 |
+| --- | --- | --- | --- | --- | --- |
+| `aipay` | AI 按量付费 | `interface-contract/aipay-interface-contract.md` | `4-按量付费` | `A2M_AUTO_COMPLETE` | `sandbox/a2m-sandbox-test.md` |
+| `webpay` | AI 网页应用收款 | `interface-contract/webpay-interface-contract.md`、`interface-contract/common-trade-contract.md`、`interface-contract/notify-url-contract.md` | `2-网站支付`、`1-通用接口` | `WEB_PAYMENT_EXPERIENCE` | `sandbox/sandbox-setup-guide.md` |
+| `apppay` | AI 移动应用收款 | `interface-contract/apppay-interface-contract.md`、`interface-contract/common-trade-contract.md`、`interface-contract/notify-url-contract.md` | `3-APP支付`、`1-通用接口` | `NOT_APPLICABLE` | - |
+
+fallback 仅在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时触发。触发后只读取当前产品和当前接口直接相关页面，不递归抓取无关文档。
+
+## 代码示例路径
+
+语言目录固定为：`java`、`python`、`nodejs`、`php`、`csharp`。选择当前项目服务端语言对应目录，禁止混用不同语言。
+
+### AI 按量付费
+
+| 语言 | 示例 |
+| --- | --- |
+| Java | `./code-examples/java/4-按量付费/A2MPaymentDemoController.md` |
+| Python | `./code-examples/python/4-按量付费/A2MPaymentDemo.md` |
+| Node.js | `./code-examples/nodejs/4-按量付费/A2MPaymentDemo.md` |
+| PHP | `./code-examples/php/4-按量付费/A2MPaymentDemo.md` |
+| C# | `./code-examples/csharp/4-按量付费/A2MPaymentDemo.md` |
+
+AI 按量付费使用 402、`Payment-Needed`、`Payment-Proof`、验付和履约确认；不读取通用收单接口或异步通知示例。五语言 Markdown 示例均提供一个语言标签匹配的源码代码块，包含完整的严格验付与幂等履约控制流，并暴露项目持久化端口；生成项目文件时只使用该代码块，不复制 Markdown 标题和说明。必须把持久化端口绑定到项目已有数据库/ORM：返回 402 前创建待支付订单，按 `out_trade_no` 查询订单，原子准备或复用履约结果，并在 `fulfillment.confirm` 成功后标记最终完成。禁止猜测项目数据层、回退到进程内存，或保留可到达的固定资源与未验付交易号兜底。
+
+### AI 网页应用收款
+
+- 专用下单示例：`./code-examples/<语言>/2-网站支付/统一收单下单并支付页面接口代码示例.md`
+- 通用接口示例：读取下方“通用收单示例”
+
+AI 网页应用收款覆盖 PC 网页和手机浏览器网页/H5，底层接口固定 `alipay.trade.page.pay`。用户未明确关闭同步回跳时，还必须按 `alipay-sdk-reminder.md` 实现并验证同步回跳结果页；支付成功仍以验签通过的异步通知或交易查询为准。
+
+### AI 移动应用收款
+
+- 专用下单示例：`./code-examples/<语言>/3-APP支付/APP支付接口代码示例.md`
+- 通用接口示例：读取下方“通用收单示例”
+
+AI 移动应用收款默认完成商家服务端能力，返回 `orderStr` 给 APP 客户端；客户端 SDK 接入不属于本 Skill 默认服务端改造范围。客户端同步结果只作支付结束通知，不能作为付款成功依据。
+
+### 通用收单示例
+
+AI 网页应用收款和 AI 移动应用收款必须读取当前语言目录下的通用示例：
+
+| 接口 | 文件 |
+| --- | --- |
+| 交易查询 | `./code-examples/<语言>/1-通用接口/统一收单交易查询接口代码示例.md` |
+| 退款 | `./code-examples/<语言>/1-通用接口/统一收单交易退款接口代码示例.md` |
+| 退款查询 | `./code-examples/<语言>/1-通用接口/统一收单交易退款查询接口代码示例.md` |
+| 关闭交易 | `./code-examples/<语言>/1-通用接口/统一收单交易关闭接口代码示例.md` |
+| 异步通知 | `./code-examples/<语言>/1-通用接口/异步通知处理代码示例.md` |
+
+本地未上线时，可按 `../flow.md` 的“本地生产参数验收模式”先完成本地结果确认链路验证；正式上线前仍必须补齐公网 HTTPS `notify_url`、验签、幂等、关键字段校验、`success` 回写和补偿查询。用户明确要求对账时再读取官方对账单下载文档作为 fallback；当前默认 checklist 不包含对账单下载。

package/skill-pre/references/integration/modules/product-decision.md

@@ -0,0 +1,73 @@
+# 产品决策
+
+用于用户集成支付宝支付产品时的产品决策。**本 Skill 仅支持 AI 按量付费、AI 网页应用收款、AI 移动应用收款三种产品**。
+
+---
+
+## 支持的产品
+
+> 术语说明：本 Skill 对客统一使用“AI 网页应用收款”，覆盖电脑网页和手机浏览器网页/H5 场景；“网站支付”“电脑网站支付”“PC网站支付”“手机网站支付”“H5支付”均作为输入别名路由到该产品。底层接口固定使用 `alipay.trade.page.pay`，即使是手机浏览器/H5 场景，也不得改用或推荐其他网页支付接口。
+
+| 产品 | 定义 | 适用场景 |
+|------|------|----------|
+| **AI 按量付费** | 面向 AI 智能体的机器支付收款产品 | API、数字内容、算力资源、智能体按调用付费、402 协议收款 |
+| **AI 网页应用收款** | 用户在电脑网页或手机网页发起支付 | PC 官网、电商网站、在线教育、政务缴费网站、手机 H5 页面 |
+| **AI 移动应用收款** | 原生 App 内调起支付宝支付 | iOS/Android/鸿蒙原生 App 内支付 |
+
+---
+
+## 产品决策树
+
+```
+用户咨询支付宝接入
+        |
+        +-- 面向 AI 智能体收款？402 协议？
+        |       +-- AI 按量付费
+        |
+        +-- 线上网页支付？
+        |       +-- 电脑浏览器网页 --> AI 网页应用收款
+        |       +-- 手机浏览器 H5 --> AI 网页应用收款
+        |
+        +-- 原生 APP 支付？
+                +-- iOS/Android/鸿蒙 --> AI 移动应用收款
+```
+
+---
+
+## 场景关键词匹配
+
+根据用户输入的关键词快速路由到对应产品：
+
+| 关键词 | 路由产品 |
+| --- | --- |
+| 402协议、Agent收款、A2A、ACT协议、A2M、AI支付、Agent支付、智能体、API收费、按调用付费、机器支付 | **AI 按量付费** |
+| PC支付、电脑网站、网页支付、电脑端支付、PC网页、电脑浏览器、网站支付、传统网页支付、网页收银台、H5支付、手机网页 | **AI 网页应用收款** |
+| APP 支付、移动应用支付、iOS支付、Android支付、鸿蒙支付、App内支付、原生 APP 支付、手机 APP 支付、移动端App、SDK支付、客户端支付 | **AI 移动应用收款** |
+
+---
+
+## ❌ 不支持的产品
+
+> ⚠️ 以下产品**不在本 Skill 支持范围内**。拒绝引导话术见 `../../normal/rejection-guide.md`
+
+| 不支持的产品 | 处理方式 |
+|-------------|----------|
+| 当面付 | 使用 rejection-guide.md 中的标准引导 |
+| 订单码支付 | 使用 rejection-guide.md 中的标准引导 |
+| JSAPI支付 | 使用 rejection-guide.md 中的标准引导 |
+| 预授权支付 | 使用 rejection-guide.md 中的标准引导 |
+| 商家扣款 | 使用 rejection-guide.md 中的标准引导 |
+
+---
+
+## 产品澄清
+
+用户描述模糊或关键词匹配不明确时，执行下列命令固定渲染 `product.clarify`，等待用户以自然语言回复产品名称和业务需求。本模块不维护第二份澄清模板；不得临场增加不支持产品、改写 AI 网页应用收款接口或省略三种支持产品。
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message product-clarify --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+### 不支持场景回复
+
+> 使用标准拒绝引导话术，详见 `../../normal/rejection-guide.md`

package/skill-pre/references/integration/modules/sandbox/a2m-sandbox-test.md

@@ -0,0 +1,235 @@
+# 按量付费沙箱测试
+
+> ⚠️ **仅当产品为「按量付费」时执行本文档定义的联调**。网站支付不执行本文档，但仍必须按 `sandbox-setup-guide.md` 第 5.5 节完成网站支付沙箱付款提示；APP 支付按集成主流程跳过步骤 6。
+
+本文档定义按量付费 402 协议的沙箱端到端服务端联调流程。测试脚本位于 `../scripts/local_402_sandbox_pay.py`。
+
+> 本文档位于 `references/integration/modules/sandbox/`，文中的 `../scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/integration/modules/scripts/...`。
+
+---
+
+## 前提条件
+
+在执行此步骤前，必须满足：
+
+1. **已完成步骤 5 代码生成**：按量付费集成代码已生成并整合进用户项目
+2. **用户本地服务已启动**：服务端已运行在可访问的地址上（如 `http://localhost:5000/demo/a2m/resource`）
+3. **已知沙箱买家 2088 账号**：从步骤 3 沙箱配置中获取实际 `userId`（例如 `<SANDBOX_BUYER_USER_ID>`）
+4. **Python 3 可用**：测试脚本依赖 Python 3 运行
+5. **已使用沙箱服务 ID**：用户服务的沙箱运行配置中 `serviceId` 固定为 `api_mock_service_id`，不要向用户索要正式 `serviceId`
+
+---
+
+## 测试前预检
+
+执行沙箱测试脚本前，先用固定 `precheck` 解码服务返回的 `Payment-Needed` 并确认关键字段存在。`SERVICE_URL` 使用用户实际服务地址。所有平台统一执行当前 Skill 的受控入口；禁止临时编写 Python、curl 管道或近似解析器：
+
+```bash
+# GET
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m precheck --url "$SERVICE_URL" --method GET --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+
+# POST
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m precheck --url "$SERVICE_URL" --method POST --body "@$POST_BODY_FILE" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+POST body 必须来自已确认目标项目中的实际文件。`seller_signature` 由代码示例中的 `generateSellerSignature` / `generate_seller_signature` 生成，签名入参中的 `service_id` 与 `method.service_id` 都必须使用 `api_mock_service_id`；禁止使用空值、其他占位符或要求用户提供正式 `serviceId`。预检输出只打印校验结论和字段名，不打印字段值。
+
+`precheck` 只请求本地服务并校验 HTTP 402/字段，不调用沙箱收银。Windows 也使用相同的 Node 单行入口，由启动器选择可用的 Python 3：
+
+```powershell
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m precheck --url "$SERVICE_URL" --method GET --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m precheck --url "$SERVICE_URL" --method POST --body "@$POST_BODY_FILE" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+---
+
+## 测试脚本路径
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+Windows 使用 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"`；启动器只允许该内置脚本，并按系统选择可用的 Python 3 命令。
+
+脚本只提供 `run` 子命令，并要求使用 `--auto-complete` 在同一次命令内获取 Payment-Needed、调用沙箱收银和携带 Payment-Proof 重试原始服务。不存在跨轮 `complete` 或恢复命令。
+
+---
+
+## 完成条件
+
+- [INT.A2M.SERVICE_READY] 已确认用户本地按量付费服务已启动可访问
+- [INT.A2M.PRECHECK_PASSED] 已完成 Payment-Needed 预检，确认 HTTP 402 和关键字段存在
+- [INT.A2M.AUTO_COMPLETE_RUN] 已执行沙箱支付测试脚本 `run --auto-complete`，成功获取 Payment-Needed、生成付款链接并连续执行服务端联调
+- [INT.A2M.DELIVERY_EVIDENCE] 已携带 Payment-Proof 重试原服务并取得 HTTP 200、非空可归属资源、无明确业务失败和有效 Payment-Validation 证据
+- [INT.A2M.TEST_PASSED] 已确认 402 沙箱服务端联调流程通过
+
+---
+
+## 测试流程
+
+### 第一步：确定服务与测试参数
+
+先从已确认的目标项目、已有运行上下文和已校验沙箱配置中确定：
+1. 按量付费集成代码已部署到本地服务
+2. 服务已启动并可通过 URL 访问
+3. 服务实现了 402 协议（无 Payment-Proof 时返回 HTTP 402 + Payment-Needed 头）
+
+**确定测试参数**：
+- `SERVICE_URL`：本地服务请求地址（含 GET 参数，如 `http://localhost:5000/demo/a2m/resource?gift=demo`）
+- `HTTP_METHOD`：`GET` 或 `POST`
+- `BUYER_2088`：沙箱买家 2088 账号（实际 `userId`，例如 `<SANDBOX_BUYER_USER_ID>`）
+
+> ⚠️ 只有缺少无法从当前上下文取得的真实值时，才询问用户对应信息。不要编造买家账号，也不得将补齐参数变成“是否执行测试”的确认。参数和服务就绪后，向用户输出测试说明并直接进入第二步。
+
+### 第二步：执行沙箱支付测试脚本
+
+**⚠️ 脚本的收银接口地址和付款链接前缀已硬编码在脚本中（`PAY_ENDPOINT`、`PAY_URL_PREFIX`），执行时无需额外指定。**
+
+先按统一 runtime 的 `integration-message a2m-execution-guard` 当前会话 receipt 契约校验项目快照、服务 URL、HTTP 方法和可选 POST body。项目快照按代码和配置的实际内容计算，仅文件时间戳变化或同内容重写不产生新的执行机会；实际内容变化时才允许生成新的 `RUN` receipt。只有 `decision=RUN` 才使用 `../../../normal/json/customer-messages.json` 的 `a2m.test.start` 渲染固定联调说明并立即运行脚本；`REUSE_PASSED|BLOCK_UNCHANGED|UNKNOWN_PREVIOUS_EXECUTION` 均不得重复发起完整联调。服务地址和 HTTP 方法只用于实际命令，不在开始消息中展示。
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message a2m-test-start --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+不得在模块或 Agent 回复中维护第二份近似开始话术。
+
+GET 请求：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE_URL" --method GET --buyer-id "$BUYER_2088" --auto-complete --require-payment-validation --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+POST 请求：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE_URL" --method POST --body "$BODY" --buyer-id "$BUYER_2088" --auto-complete --require-payment-validation --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+Windows 从本文件所在目录按实际 HTTP 方法执行对应单行命令：
+
+```powershell
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE_URL" --method GET --buyer-id "$BUYER_2088" --auto-complete --require-payment-validation --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE_URL" --method POST --body "@$POST_BODY_FILE" --buyer-id "$BUYER_2088" --auto-complete --require-payment-validation --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+**脚本执行步骤**：
+1. 请求 `$SERVICE_URL`，提取 `Payment-Needed` 响应头
+2. Base64 解码账单 JSON
+3. 将下划线字段转换为驼峰字段（适配沙箱收银接口）
+4. 补充 `method.buyerUniqueIdKey = "buyerExternalId"`
+5. 补充 `protocol.buyerUniqueId = <买家 2088>`
+6. 补充 `signature` 字段
+7. POST 到沙箱收银接口 `http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay`
+8. 生成浏览器付款链接
+9. 使用同一过程产物构建 Payment-Proof 并重试原始服务
+10. 仅在 HTTP 200、非空且可归属的资源、无明确业务失败，并且当前示例要求的 `Payment-Validation` 校验通过时输出服务端联调成功
+11. 命令结束前清理敏感过程产物；失败后重新执行完整联调，不保存跨轮恢复状态
+
+**脚本输出**：
+- Payment-Needed 获取结果（终端不输出原始值）
+- 脱敏后的账单 JSON
+- 脱敏后的收银接口请求体
+- 收银接口返回
+- **浏览器付款链接**（格式：`https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema=...`）
+- Payment-Proof 重试后的服务响应与测试结论；`Payment-Validation` 原始值不在终端输出
+
+**错误处理**：
+- 沙箱化 Agent 环境执行本脚本时，首次执行即申请可联网权限；如果已因网络受限失败，复用同一条命令申请可联网权限重试
+- 如果未找到 `Payment-Needed` 响应头，确认服务端是否实现了 402 协议
+- 如果收银接口返回 `PARAM_INVALID: protocol.sellerSignature不能为空`，回到预检步骤检查 `protocol.seller_signature` 是否为空、缺失或仍是占位符
+- 如果 `pay_before` 相关参数报错，检查是否使用 ISO 8601 带时区格式
+- 如果收银接口返回 `PAY_SUBMIT_FAILED`、`系统繁忙` 等已识别临时错误，脚本只在同一次命令内按既有预算自动重试；仍失败时清理本轮敏感产物并停止。Agent 不得通过重复执行 `run --auto-complete`、追加 `--pay-retries`/`--pay-retry-delay` 或手工复用上轮 Payment-Needed 扩大远程写动作；只有联网权限恢复后重试同一未发出命令，或代码、配置、URL、方法、POST body 实际变化并由 guard 产生新 `RUN` receipt 时才能重新发起完整联调。
+
+### 第三步：连续验证 Payment-Proof 重试
+
+标准流程只使用第二步命令中的 `--auto-complete`。脚本生成付款链接后，在同一次进程内继续构建 Payment-Proof、重试原始服务并输出结果；进程中断后重新执行完整联调。
+
+**脚本执行步骤**：
+1. 读取过程产物目录中的 `state.json`
+2. 使用前面沙箱收银接口下单返回的 `trade_no` 构建 `Payment-Proof` 请求头（含 `payment_proof`、`trade_no`、`client_session`）
+3. 携带 `Payment-Proof` 请求头重试原始服务地址
+4. 校验最终服务响应并打印脱敏结论；不打印 `Payment-Validation` 原始值
+5. 成功后安全清理敏感过程产物
+
+**Payment-Proof 处理约束**：
+- `trade_no` 必须使用前面沙箱收银接口返回并写入 `state.json` 的交易号；不得改用商户侧 `out_trade_no` 或重新生成。
+- `payment_proof`、`client_session` 和最终请求头由脚本按沙箱联调约定自动处理；Agent 不得手工拼接、改写或向用户展开其原始值和内部处理规则。
+- 进程中断后只能在确认上次命令未取得可用过程产物时重新执行完整 `run --auto-complete` 联调，不复用旧过程产物；明确业务失败、服务实现失败或脚本已输出失败结论时，禁止立即重复执行同一联调命令刷远程动作，必须先处理失败原因。
+
+Payment-Proof 参考结构：
+
+```json
+{
+  "protocol": {
+    "payment_proof": "<脚本生成并保存到受限权限过程产物，禁止对客展示>",
+    "trade_no": "<沙箱收银接口实际返回的交易号>"
+  },
+  "method": {
+    "client_session": "<脚本生成并保存到受限权限过程产物，禁止对客展示>"
+  }
+}
+```
+
+**验证要点**：
+- 服务必须返回 HTTP 200；任意其他状态（包括 204）均失败
+- JSON 响应体必须同时包含非空 `resource_id` / `resourceId` 和非空 `content`；非 JSON 资源必须有可验证的 `Payment-Validation` 证明归属
+- 响应中不得存在当前五语言示例已经定义的明确验付、资源或履约失败，如 `VERIFY_FAILED`、`RESOURCE_ID_MISMATCH`、`FULFILLMENT_CONFIRM_FAILED`
+- 当前五语言示例实现了 `Payment-Validation`，标准命令必须传 `--require-payment-validation`；响应头必须能解码为 JSON，且包含 `validated=true`、非空 `trade_no` / `tradeNo` 和 `resource_id` / `resourceId`，资源 ID 必须与响应体一致
+- 只有以上证据同时成立，脚本退出码才为 0，才能输出“沙箱服务端联调通过”
+
+**常见失败与排查**：
+- `ORDER_NOT_FOUND`：`alipay.aipay.agent.payment.verify` 成功只代表支付宝凭证有效，不代表商户本地订单已匹配成功。检查服务端是否在返回 `Payment-Needed` 前持久化了 `out_trade_no`、`resource_id`、金额和订单状态；验证成功后应优先用验付返回的 `outTradeNo` 查询订单。沙箱响应字段可能为空字符串，排查时先判断字段是否非空；如果本地服务重启导致内存订单丢失，已付款旧链接不能继续用于重启后的服务。
+- `RESOURCE_ID_MISMATCH`：检查验付返回的 `resourceId` 是否非空且与本地订单保存的资源一致。沙箱字段为空时不要把空字符串当作有效资源字段参与强校验；生产环境必须把资源字段缺失作为异常处理。
+- `FULFILLMENT_CONFIRM_FAILED` 或 HTTP 5xx：资源生成后调用 `alipay.aipay.agent.fulfillment.confirm` 失败时，不要返回成功交付；应保留服务结果并允许同一笔 `Payment-Proof` 重试履约确认。
+
+### 第四步：测试结论与可选付款体验
+
+测试结束后使用 `a2m.test.result`：只有脚本退出码和本模块要求的组合证据都成立时选择 `PASSED`；其他情况选择 `FAILED` 并传入实际证据与确定恢复动作。不得把用户付款体验、沙箱配置落盘或任意 2xx 响应替代通过证据。
+
+输出测试结论后，使用 `a2m.payment.experience/FULL` 展示付款链接和已经通过快速沙箱字段校验的实际买家账号。缺少任一账号字段时，当前沙箱配置必须已经在前置校验进入待配置状态，不得执行本联调或输出付款体验，也不得编造缺失凭据。随后执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message sandbox-android-client --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"` 统一输出 Android-only 官方下载与失败兜底。两条消息都不增加阻塞点，也不反向改变服务端联调结论。
+
+最后必须提醒用户：
+
+> 当前 `serviceId=api_mock_service_id` 仅用于沙箱联调。正式上线前，必须替换为支付宝服务市场注册或复用服务后实际返回的真实 `serviceId`。
+
+脚本使用权限不宽于 `0700/0600` 的临时目录传递敏感中间值，并在命令退出前清理。该目录不用于用户进度或后续恢复，Agent 不向用户索要、展示或复用其中的 Payment-Proof。
+
+**沙箱支付宝下载红线（Agent 内部约束，不要作为用户提示逐字输出）：**
+- 默认只提供上方沙箱支付宝安装直链，复制到网页浏览器打开，并使用支付宝客户端扫码下载。
+- 严禁声称 iOS 也有沙箱版支付宝或可在 iOS 完成沙箱支付宝安装。
+- 严禁引导用户去应用市场、应用商店、搜索引擎或任何第三方站点搜索/下载“沙箱支付宝”。
+- 严禁提供 `https://sandbox.alipay.com`、其他自编 URL、二维码、安装包名称或下载方式。
+- 如果用户明确反馈上述直链、页面二维码无法打开或无法下载，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装沙箱版支付宝；不得自行补充其他替代渠道。
+
+---
+
+## 注意事项
+
+1. **沙箱收银接口**：脚本默认使用 `http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay`，此地址已硬编码在脚本中
+2. **付款链接**：前缀为 `https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema=`，通过 URL 编码的 `payScheme` 拼接
+3. **过程产物**：只在当前命令的系统临时专用目录中短时存在，目录/文件权限为 `0700/0600`；命令成功、失败或异常退出都执行清理，不提供自定义目录和跨轮恢复
+4. **买家签名**：默认占位值 `-`，无需修改
+5. **沙箱化 Agent 网络权限**：脚本内 `fetch_payment_needed` 使用 curl，且收银测试会访问沙箱接口；沙箱化 Agent 环境首次执行即申请可联网权限
+6. **沙箱支付宝安装包**：沙箱支付宝当前仅支持安卓系统；默认引导用户复制 `https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original` 到网页浏览器打开，并使用支付宝客户端扫码下载。若用户明确反馈该直链、页面二维码无法打开或无法下载，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装沙箱版支付宝。严禁引导用户使用 iOS 沙箱支付宝、应用市场搜索、`https://sandbox.alipay.com` 或其他自编下载 URL。
+
+---
+
+## 脚本内部流程概要
+
+```
+用户服务 (无 Payment-Proof)
+    ↓ HTTP 402 + Payment-Needed (base64 JSON)
+脚本提取并解码
+    ↓ snake_case → camelCase + 补充买家ID
+沙箱收银接口
+    ↓ payScheme
+浏览器付款链接（保留为可选体验入口）
+    ↓
+脚本连续构建 Payment-Proof
+    ↓ base64(protocol + method)
+重试用户服务
+    ↓ HTTP 200 + 非空可归属资源 + 无明确失败
+校验 Payment-Validation（当前五语言示例要求）
+    ↓ 成功后清理敏感过程产物
+验证通过 ✅
+```

package/skill-pre/references/integration/modules/sandbox/alipay-sandbox-tool.md

@@ -0,0 +1,142 @@
+# Alipay Sandbox Tool
+
+提供沙箱能力：**创建快速沙箱**。
+
+本文件记录 `sandbox_config.sh` 内部使用的冻结 MCP 命令、响应结构和维护规则。运行时 Agent 不直接执行本文件的原始 MCP 命令；只执行 integration flow 登记的 `sandbox_config.sh ensure|reverify|verify|summary`，命中登记终态后立即转移，不追加临时 jq 或其他诊断。
+
+## 1. 环境检测
+
+> ⚠️ **前置要求**：在调用沙箱工具前，必须先按 `../../../normal/alipay-cli-env.md` 完成 alipay-cli 检测与安装
+
+```bash
+which alipay-cli 2>/dev/null && alipay-cli version
+```
+
+> 📎 详细检测、安装、验证流程及环境检测结果不透出规范见 `../../../normal/alipay-cli-env.md`
+
+## 2. 创建快速沙箱
+
+**重要：工具返回的 `data` 只是候选沙箱配置；必须先按 `sandbox-setup-guide.md` 完成字段完整性校验，校验通过后再写入正式本地配置文件。创建阶段不对客输出字段核对表、独立校验结论或沙箱环境摘要表；代码开发完成并通过配置后置校验后，才按该指南输出一张沙箱环境摘要表。该结果不代表沙箱支付测试通过。privateKey、publicKey 等密钥字段不得展开。**
+
+`createAnonymousSandbox` 的 MCP 请求体只有业务入参 `request.appType`，当前固定为 `PUBLICAPP`。`PLATFORM`、`PLATFORM_ID` 和 `ALIPAYCLI_BIZ_INFO` 是 alipay-cli 上下文环境变量，禁止写入 `--data` 的 JSON。匿名沙箱创建不依赖本轮最终选择的支付产品，因此不得为了创建沙箱先编造或强行确认 `PRODUCT`。
+
+```bash
+PLATFORM="<PLATFORM>" \
+PLATFORM_ID="<run_id>" \
+ALIPAYCLI_BIZ_INFO='{"skill":"alipay-aipay","skill_version":"v<当前 VERSION>","skill_user_id":"machine_<32位匿名机器哈希>"}' \
+alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
+  --data '{"request":{"appType":"PUBLICAPP"}}' \
+  --json
+```
+
+**固定参数：**
+
+| 字段 | 固定值 | 说明 |
+|------|------|------|
+| `request.appType` | `PUBLICAPP` | 不随用户最终选择的按量付费、网站支付或 APP 支付变化 |
+
+**上下文变量：**
+
+| 变量 | 来源 | 取值规则 |
+|------|------|----------|
+| `PLATFORM` | AI 编程工具识别结果 | 参考通用脚本 `../../../normal/scripts/detect_dev_tool.sh` 识别当前工具后使用其输出值；缺失时使用 `unknown`。例如 Codex 环境检测结果为 `codex` |
+| `PLATFORM_ID` | 第三方项目 ID；缺失时为当前逻辑 `run_id` | 由 `sandbox_config.sh` 通过 `common.sh` 读取，遥测开启或关闭都不影响该值；第三方项目 ID 只用于项目维度，不能生成逻辑 `run_id`，缺失时才保持 `PLATFORM_ID <- run_id` fallback，且不阻断沙箱创建 |
+| `ALIPAYCLI_BIZ_INFO` | 当前生效 Skill 的 `VERSION` 与匿名机器哈希 | 由 `common.sh` 动态生成 JSON：`{"skill":"alipay-aipay","skill_version":"v<当前 VERSION>","skill_user_id":"machine_<32位匿名机器哈希>"}`；`skill` 固定，版本统一带 `v` 前缀，`skill_user_id` 复用 telemetry 的 `machineUserID`，极端环境无法取得合法 `machine_` 标识时省略该字段；禁止由 Agent 手写或沿用外部同名值 |
+| `PRODUCT` | 不再传入 | 该 MCP 方法当前不需要产品上下文；不得把产品名写入 `--data` 或 CLI 环境变量 |
+
+**Codex 环境示例：**
+
+```bash
+PLATFORM=codex \
+PLATFORM_ID=<run_id> \
+ALIPAYCLI_BIZ_INFO='{"skill":"alipay-aipay","skill_version":"v<当前 VERSION>","skill_user_id":"machine_<32位匿名机器哈希>"}' \
+alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
+  --data '{"request":{"appType":"PUBLICAPP"}}' \
+  --json
+```
+
+**结果解析：**
+
+1. 取 `result.content[0].text`，去转义还原 JSON
+2. `success === true` → 提取 `data` 字段作为候选沙箱配置，先按 [沙箱环境初始化](sandbox-setup-guide.md) 的必含字段清单做完整性校验
+3. 字段完整性校验通过 → 将 `data` 字段完整写入正式本地配置文件；创建阶段只输出受控机器标记和实际配置路径，不输出沙箱环境摘要表、字段核对表、独立校验结论或“沙箱测试通过”等表述
+4. 代码开发完成并通过配置后置校验后 → 按 `sandbox-setup-guide.md` 使用 `sandbox_config.sh summary` 复核并只输出一张沙箱环境摘要表，保持本地文件中的原始字段值不变，不在对话中复述密钥等长字段
+5. `success !== true` 或 `data` 字段缺失/字段不完整 → 不得写入正式 `.alipay-sandbox.json`；按错误处理完成既定重试，耗尽后返回待配置终态并继续代码实现
+
+## 3. 错误处理
+
+CLI 输出不暴露 HTTP 状态码，统一按响应体中的 `success` 字段判断：
+
+| 条件 | 策略 |
+|------|------|
+| `success === false` 且 `msg` 含"证书密钥"等当前已识别临时错误 | 固定 runner 静默等待 2 秒后自动重试 1 次；仍失败则进入待配置终态 |
+| `success === false` 且 `msg` 含"版本过旧"，或 CLI 退出码非 0 且不是已识别网络错误 | 不重试，保留实际失败类别和可执行恢复动作 |
+| CLI 执行超时或已识别网络/服务错误 | 同一参数最多自动重试 2 次，每次间隔 3 秒 |
+| 候选 `data` 或已有配置缺少必含字段 | 同一流程动作最多自动重试 2 次，每次间隔 3 秒；仍失败则进入 `CREATE_PENDING|VERIFY_PENDING` |
+
+`ensure|reverify` 的重试耗尽后由 `sandbox_config.sh` 内部固定渲染 `sandbox.configuration.pending/CREATE|VERIFY`，并返回对应 `FLOW:SANDBOX_CONFIG_PENDING_*`；Agent 不得二次渲染、直接转述原始响应、临场拼装错误话术或自行增加重试确认。`SANDBOX_ERROR`、`errorCode` 和实际返回的 `traceId` 只属于严格 `create|verify` 子动作的受控诊断，待配置终态不对客展开原因。待配置不得产生沙箱 PASS 条件，只允许继续不依赖沙箱字段的代码实现。
+
+## 4. 注意事项
+
+- 本文件的原始命令只用于维护 `sandbox_config.sh` 的冻结契约，不对客展示，也不作为运行时二次调用入口。
+- `request.appType` 与 CLI 上下文均由脚本固定。参数或返回结构无法按当前契约确认时停止并交由维护者核对，不向用户增加参数确认，不临场改写命令。
+  
+## 返回结构示例
+
+### 成功结构示例
+
+> 下例仅用于说明字段结构；真实执行时创建阶段不输出字段摘要或账号密码。只有代码开发完成且配置后置校验通过后，才按 `sandbox-setup-guide.md` 输出受控沙箱摘要；完整私钥、公钥等密钥字段只写入本地配置文件。
+
+```json
+{
+  "appIds": [
+    {
+      "alipayPublicKey": "<ALIPAY_PUBLIC_KEY_BASE64>",
+      "appId": "<SANDBOX_APP_ID>",
+      "appPrivateKey": "<APP_PRIVATE_KEY_PKCS8_BASE64>",
+      "appPrivatePkcsKey": "<APP_PRIVATE_KEY_PKCS1_BASE64>",
+      "appPublicKey": "<APP_PUBLIC_KEY_BASE64>",
+      "pid": "<SANDBOX_SELLER_USER_ID>",
+      "type": null,
+      "uid": null
+    }
+  ],
+  "isClaimed": false,
+  "sandboxAccounts": {
+    "partner": {
+      "accountDesc": "商家账号",
+      "acctrans": "<SANDBOX_SELLER_BALANCE>",
+      "email": "<SANDBOX_SELLER_EMAIL>",
+      "merchantId": "<SANDBOX_MERCHANT_ID>",
+      "userId": "<SANDBOX_SELLER_USER_ID>"
+    },
+    "user": {
+      "accountDesc": "买家账号",
+      "acctrans": "<SANDBOX_BUYER_BALANCE>",
+      "email": "<SANDBOX_BUYER_EMAIL>",
+      "userName": "<SANDBOX_BUYER_NAME>",
+      "userId": "<SANDBOX_BUYER_USER_ID>",
+      "logonPassword": "<SANDBOX_BUYER_LOGIN_PASSWORD>",
+      "payPassword": "<SANDBOX_BUYER_PAY_PASSWORD>",
+      "certNo": "<SANDBOX_BUYER_CERT_NO>",
+      "certType": "IDENTITY_CARD"
+    }
+  },
+  "sandboxId": "<SANDBOX_ID>",
+  "sandboxName": "<SANDBOX_NAME>"
+}
+```
+
+### 错误示例
+
+```json
+{
+  "data": null,
+  "errorCode": null,
+  "msg": "查询沙箱证书密钥信息失败",
+  "resultCode": null,
+  "resultMsg": null,
+  "success": false,
+  "traceId": "218f563417783158778985995e4b5d"
+}
+```