@alipay/alipay-aipay 1.1.0 → 1.2.2

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

@@ -1,8 +1,8 @@
 # 按量付费沙箱测试
 
-> ⚠️ **仅当产品为「按量付费」时执行此步骤**。网站支付和APP支付无需此步骤，跳过直接进入步骤 6。
+> ⚠️ **仅当产品为「按量付费」时执行本文档定义的联调**。网站支付不执行本文档，但仍必须按 `sandbox-setup-guide.md` 第 5.4 节完成网站支付沙箱付款提示；APP支付按集成主流程跳过步骤 5。
 
-本文档定义按量付费 402 协议的沙箱端到端支付测试流程。测试脚本位于 `../scripts/local_402_sandbox_pay.py`。
+本文档定义按量付费 402 协议的沙箱端到端服务端联调流程。测试脚本位于 `../scripts/local_402_sandbox_pay.py`。
 
 > 本文档位于 `references/integration/modules/sandbox/`，文中的 `../scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/integration/modules/scripts/...`。
 
@@ -16,6 +16,7 @@
 2. **用户本地服务已启动**：服务端已运行在可访问的地址上（如 `http://localhost:5000/demo/a2m/resource`）
 3. **已知沙箱买家 2088 账号**：从步骤 2 沙箱信息输出的买家账号中获取 `userId`（如 `2088722100508485`）
 4. **Python 3 可用**：测试脚本依赖 Python 3 运行
+5. **已使用沙箱服务 ID**：用户服务的沙箱运行配置中 `serviceId` 固定为 `api_mock_service_id`，不要向用户索要正式 `serviceId`
 
 ---
 
@@ -46,11 +47,13 @@ required = [
 missing = [f"{path[0]}.{path[1]}" for path in required if not data.get(path[0], {}).get(path[1])]
 if missing:
     raise SystemExit("缺少字段: " + ", ".join(missing))
+if data.get("method", {}).get("service_id") != "api_mock_service_id":
+    raise SystemExit("沙箱联调 method.service_id 必须为 api_mock_service_id")
 print("Payment-Needed 预检通过，已确认 HTTP 402 和关键字段存在。")
 print("已校验字段: " + ", ".join(f"{path[0]}.{path[1]}" for path in required))'
 ```
 
-POST 服务将首行 curl 替换为 `curl -s -D - -o /dev/null -X POST -H "Content-Type: ${CONTENT_TYPE:-application/json}" -d "$BODY" "$SERVICE_URL"`。`seller_signature` 由代码示例中的 `generateSellerSignature` / `generate_seller_signature` 生成，禁止使用空值或占位符。预检输出只打印校验结论和字段名，不打印字段值。
+POST 服务将首行 curl 替换为 `curl -s -D - -o /dev/null -X POST -H "Content-Type: ${CONTENT_TYPE:-application/json}" -d "$BODY" "$SERVICE_URL"`。`seller_signature` 由代码示例中的 `generateSellerSignature` / `generate_seller_signature` 生成，签名入参中的 `service_id` 与 `method.service_id` 都必须使用 `api_mock_service_id`；禁止使用空值、其他占位符或要求用户提供正式 `serviceId`。预检输出只打印校验结论和字段名，不打印字段值。
 
 ---
 
@@ -70,40 +73,48 @@ python3 ../scripts/local_402_sandbox_pay.py
 
 - [M-05] 已确认用户本地按量付费服务已启动可访问
 - [M-05] 已完成 Payment-Needed 预检，确认 HTTP 402 和关键字段存在
-- [M-05] 已执行沙箱支付测试脚本 `run`，成功获取 Payment-Needed 并生成付款链接
-- [M-05] 用户已在浏览器使用沙箱买家账号完成付款
-- [M-05] 已携带 Payment-Proof 重试原服务并验证响应成功
-- [M-05] 已确认全链路 402 支付流程通过
+- [M-05] 已执行沙箱支付测试脚本 `run --auto-complete`，成功获取 Payment-Needed、生成付款链接并连续执行服务端联调
+- [M-05] 已携带 Payment-Proof 重试原服务并验证服务响应成功
+- [M-05] 已确认 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`，如 `2088722100508485`）
 
-> ⚠️ 如果缺少任一值，先询问用户。不要编造买家账号。
+> ⚠️ 只有缺少无法从当前上下文取得的真实值时，才询问用户对应信息。不要编造买家账号，也不得将补齐参数变成“是否执行测试”的确认。参数和服务就绪后，向用户输出测试说明并直接进入第二步。
 
 ### 第二步：执行沙箱支付测试脚本
 
 **⚠️ 脚本的收银接口地址和付款链接前缀已硬编码在脚本中（`PAY_ENDPOINT`、`PAY_URL_PREFIX`），执行时无需额外指定。**
 
+先输出对客执行说明，然后立即运行脚本，不等待用户确认：
+
+> 开始执行按量付费沙箱服务端联调。
+> - 服务地址：`{SERVICE_URL}`
+> - HTTP 方法：`{HTTP_METHOD}`
+>
+> 我将依次验证 402 Payment-Needed、沙箱收银链路、Payment-Proof 重试和资源交付，完成后输出测试结论。
+
 GET 请求：
 
 ```bash
 python3 ../scripts/local_402_sandbox_pay.py run \
   --url "$SERVICE_URL" \
   --method GET \
-  --buyer-id "$BUYER_2088"
+  --buyer-id "$BUYER_2088" \
+  --auto-complete
 ```
 
 POST 请求：
@@ -113,7 +124,8 @@ python3 ../scripts/local_402_sandbox_pay.py run \
   --url "$SERVICE_URL" \
   --method POST \
   --body "$BODY" \
-  --buyer-id "$BUYER_2088"
+  --buyer-id "$BUYER_2088" \
+  --auto-complete
 ```
 
 **脚本执行步骤**：
@@ -125,6 +137,8 @@ python3 ../scripts/local_402_sandbox_pay.py run \
 6. 补充 `signature` 字段
 7. POST 到沙箱收银接口 `http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay`
 8. 生成浏览器付款链接
+9. 使用同一过程产物构建 Payment-Proof 并重试原始服务
+10. 输出服务端联调结果
 
 **脚本输出**：
 - Payment-Needed 获取结果和本地过程产物路径（终端不输出原始值）
@@ -133,6 +147,7 @@ python3 ../scripts/local_402_sandbox_pay.py run \
 - 收银接口返回
 - **浏览器付款链接**（格式：`https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema=...`）
 - 过程产物目录路径（`$ARTIFACT_DIR`）
+- Payment-Proof 重试后的服务响应与测试结论
 
 **错误处理**：
 - 沙箱化 Agent 环境执行本脚本时，首次执行即申请可联网权限；如果已因网络受限失败，复用同一条命令申请可联网权限重试
@@ -142,40 +157,17 @@ python3 ../scripts/local_402_sandbox_pay.py run \
 - 如果收银接口返回 `PAY_SUBMIT_FAILED`、`系统繁忙` 或缺少 `payScheme`，不要重新请求用户服务生成新订单。脚本默认会自动重试；仍失败时，复用过程产物重试收银接口：
   ```bash
   python3 ../scripts/local_402_sandbox_pay.py run \
-    --reuse-artifact "$ARTIFACT_DIR"
+    --reuse-artifact "$ARTIFACT_DIR" \
+    --auto-complete
   ```
   `--reuse-artifact` 会复用上一轮产物中的 `Payment-Needed`、服务 URL、HTTP 方法、POST 请求体和 Content-Type。脚本不会重新请求用户服务生成新订单。这样可以避免本地内存订单堆积，导致后续 `ORDER_NOT_FOUND` 或多订单兜底匹配失败。
 - `run` 命令支持 `--pay-retries` 和 `--pay-retry-delay`，用于调大沙箱收银接口临时失败时的重试次数与间隔。
 
-### 第三步：用户完成付款
-
-**必须将脚本输出的付款链接发给用户**，并提示：
-
-> 请在浏览器打开以下链接，使用沙箱买家账号完成付款：
-> - 买家账号：`{email}`（如 `xxxxx@sandbox.com`）
-> - 登录密码：`{logonPassword}`（如 `111111`）
-> - 支付密码：`{payPassword}`（如 `111111`）
->
-> {付款链接}
-
-同时提醒用户：
-
-> 沙箱支付宝当前仅支持安卓系统。如果尚未安装沙箱版支付宝，请复制以下链接到网页浏览器打开，并使用支付宝客户端扫码下载：
->
-> https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original
-
-**沙箱支付宝下载红线（Agent 内部约束，不要作为用户提示逐字输出）：**
-- 默认只提供上方沙箱支付宝安装直链，复制到网页浏览器打开，并使用支付宝客户端扫码下载。
-- 严禁声称 iOS 也有沙箱版支付宝或可在 iOS 完成沙箱支付宝安装。
-- 严禁引导用户去应用市场、应用商店、搜索引擎或任何第三方站点搜索/下载“沙箱支付宝”。
-- 严禁提供 `https://sandbox.alipay.com`、其他自编 URL、二维码、安装包名称或下载方式。
-- 如果用户明确反馈上述直链、页面二维码无法打开或无法下载，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装沙箱版支付宝；不得自行补充其他替代渠道。
-
-等待用户确认付款成功后，记录过程产物目录 `$ARTIFACT_DIR`，进入第四步。
+### 第三步：连续验证 Payment-Proof 重试
 
-### 第四步：验证 Payment-Proof 重试
+标准流程使用第二步命令中的 `--auto-complete`。脚本生成付款链接后，使用同一过程产物继续执行 `complete` 逻辑并输出服务端联调结果。
 
-用户确认付款成功后，运行 `complete` 命令：
+如果标准命令在生成付款链接后因进程中断而未完成最终重试，使用同一过程产物恢复：
 
 ```bash
 python3 ../scripts/local_402_sandbox_pay.py complete \
@@ -188,13 +180,12 @@ python3 ../scripts/local_402_sandbox_pay.py complete \
 3. 携带 `Payment-Proof` 请求头重试原始服务地址
 4. 打印最终服务响应
 
-**沙箱 Payment-Proof 构建规则**：
-- `trade_no` 必须使用前面沙箱收银接口下单返回的交易号，即脚本从 `payResponse.protocol.tradeNo`  提取并写入 `state.json` 的值；不要使用商户侧 `out_trade_no`，也不要重新生成。
-- `protocol.payment_proof` 在沙箱环境不做强校验，脚本默认用 `trade_no`、买家 2088 和当前毫秒时间戳生成一个非空 SHA-256 值。
-- `method.client_session` 是 `{"externalId":"<BUYER_2088>","signature":"-","timestamp":"<毫秒时间戳>"}` 紧凑 JSON 的 Base64 编码。
-- 最终 `Payment-Proof` 请求头值是下面整体 JSON 紧凑序列化后的 Base64 编码。
+**Payment-Proof 处理约束**：
+- `trade_no` 必须使用前面沙箱收银接口返回并写入 `state.json` 的交易号；不得改用商户侧 `out_trade_no` 或重新生成。
+- `payment_proof`、`client_session` 和最终请求头由脚本按沙箱联调约定自动处理；Agent 不得手工拼接、改写或向用户展开其原始值和内部处理规则。
+- 进程中断时只复用同一个 `$ARTIFACT_DIR` 恢复，禁止脱离脚本另行构造凭证。
 
-参考结构：
+Payment-Proof 参考结构：
 
 ```json
 {
@@ -218,21 +209,47 @@ python3 ../scripts/local_402_sandbox_pay.py complete \
 - `RESOURCE_ID_MISMATCH`：检查验付返回的 `resourceId` 是否非空且与本地订单保存的资源一致。沙箱字段为空时不要把空字符串当作有效资源字段参与强校验；生产环境必须把资源字段缺失作为异常处理。
 - `FULFILLMENT_CONFIRM_FAILED` 或 HTTP 5xx：资源生成后调用 `alipay.aipay.agent.fulfillment.confirm` 失败时，不要返回成功交付；应保留服务结果并允许同一笔 `Payment-Proof` 重试履约确认。
 
-### 第五步：测试结论
+### 第四步：测试结论与可选付款体验
 
 测试通过后输出：
 
 ```
-✅ 按量付费沙箱全链路测试通过
+✅ 按量付费沙箱服务端联调通过
 
 | 测试项 | 状态 |
 |--------|------|
 | 402 Payment-Needed 返回 | ✅ |
-| 沙箱收银台付款 | ✅ |
+| 沙箱收银链路 | ✅ |
 | Payment-Proof 重试 | ✅ |
 | 资源交付 | ✅ |
 ```
 
+输出测试结论后，将脚本生成的付款链接作为可选体验入口提供给用户，并从已校验的本地沙箱配置读取工具实际返回的沙箱买家账号和密码。字段缺失时省略对应字段，禁止编造：
+
+> 如需体验沙箱付款页面，可在浏览器打开以下链接，并使用沙箱买家账号操作：
+> - 买家账号：`{email}`（如有）
+> - 登录密码：`{logonPassword}`（如有）
+> - 支付密码：`{payPassword}`（如有）
+>
+> {付款链接}
+
+同时提供安卓客户端体验说明：
+
+> 沙箱支付宝当前仅支持安卓系统。如需安装沙箱版支付宝，请复制以下链接到网页浏览器打开，并使用支付宝客户端扫码下载：
+>
+> https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original
+
+最后必须提醒用户：
+
+> 当前 `serviceId=api_mock_service_id` 仅用于沙箱联调。正式上线前，必须替换为支付宝服务市场注册或复用服务后实际返回的真实 `serviceId`。
+
+**沙箱支付宝下载红线（Agent 内部约束，不要作为用户提示逐字输出）：**
+- 默认只提供上方沙箱支付宝安装直链，复制到网页浏览器打开，并使用支付宝客户端扫码下载。
+- 严禁声称 iOS 也有沙箱版支付宝或可在 iOS 完成沙箱支付宝安装。
+- 严禁引导用户去应用市场、应用商店、搜索引擎或任何第三方站点搜索/下载“沙箱支付宝”。
+- 严禁提供 `https://sandbox.alipay.com`、其他自编 URL、二维码、安装包名称或下载方式。
+- 如果用户明确反馈上述直链、页面二维码无法打开或无法下载，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装沙箱版支付宝；不得自行补充其他替代渠道。
+
 ---
 
 ## 已有 Payment-Needed 值（可选）
@@ -240,7 +257,12 @@ python3 ../scripts/local_402_sandbox_pay.py complete \
 如果用户已经提供了 `Payment-Needed` 响应头值（如之前已从其他渠道获取），可以通过 `--payment-needed` 参数直接传入，跳过对用户服务的首次请求：
 
 ```bash
-python3 ../scripts/local_402_sandbox_pay.py run   --url "$SERVICE_URL"   --method GET   --buyer-id "$BUYER_2088"   --payment-needed "$PAYMENT_NEEDED_VALUE"
+python3 ../scripts/local_402_sandbox_pay.py run \
+  --url "$SERVICE_URL" \
+  --method GET \
+  --buyer-id "$BUYER_2088" \
+  --payment-needed "$PAYMENT_NEEDED_VALUE" \
+  --auto-complete
 ```
 
 脚本将直接解码该值并继续后续流程，不再发起 curl 请求。
@@ -267,9 +289,9 @@ python3 ../scripts/local_402_sandbox_pay.py run   --url "$SERVICE_URL"   --metho
     ↓ snake_case → camelCase + 补充买家ID
 沙箱收银接口
     ↓ payScheme
-浏览器付款链接
-    ↓ 用户扫码/登录付款
-脚本构建 Payment-Proof
+浏览器付款链接（保留为可选体验入口）
+    ↓
+脚本连续构建 Payment-Proof
     ↓ base64(protocol + method)
 重试用户服务
     ↓ HTTP 200 + 资源内容

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

@@ -14,7 +14,7 @@ which alipay-cli 2>/dev/null && alipay-cli version
 
 ## 2. 创建快速沙箱
 
-**重要：工具返回的 `data` 只是候选沙箱配置；必须先按 `sandbox-setup-guide.md` 完成字段完整性校验，校验通过后再写入正式本地配置文件。对话中只展示关键字段摘要和配置文件路径，避免 privateKey、publicKey、账号密码等长字段刷屏。**
+**重要：工具返回的 `data` 只是候选沙箱配置；必须先按 `sandbox-setup-guide.md` 完成字段完整性校验，校验通过后再写入正式本地配置文件。字段无缺失时，不对客输出字段核对表或独立校验结论，只按该指南输出一张沙箱环境摘要表；该结果不代表沙箱支付测试通过。privateKey、publicKey 等密钥字段不得展开。**
 
 `createAnonymousSandbox` 的 MCP 请求体只有业务入参 `request.appType`。`PLATFORM`、`PRODUCT` 是 alipay-cli 上下文环境变量，禁止写入 `--data` 的 JSON。
 
@@ -55,7 +55,7 @@ alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
 
 1. 取 `result.content[0].text`，去转义还原 JSON
 2. `success === true` → 提取 `data` 字段作为候选沙箱配置，先按 [沙箱环境初始化](sandbox-setup-guide.md) 的必含字段清单做完整性校验
-3. 字段完整性校验通过 → 将 `data` 字段完整写入正式本地配置文件，并按摘要输出格式展示关键字段；保持本地文件中的原始字段值不变，不在对话中复述长字段
+3. 字段完整性校验通过 → 将 `data` 字段完整写入正式本地配置文件，并按 `sandbox-setup-guide.md` 只输出一张沙箱环境摘要表；不输出字段核对表、独立校验结论或“沙箱测试通过”等表述，保持本地文件中的原始字段值不变，不在对话中复述密钥等长字段
 4. `success !== true` 或 `data` 字段缺失/字段不完整 → 按错误处理流程阻断；不得写入正式 `.alipay-sandbox.json`
 
 ## 3. 错误处理
@@ -79,7 +79,7 @@ CLI 输出不暴露 HTTP 状态码，统一按响应体中的 `success` 字段
 
 ### 成功结构示例
 
-> 下例仅用于说明字段结构；真实执行时默认只输出关键字段摘要，完整私钥、公钥、账号密码等长字段写入本地配置文件。
+> 下例仅用于说明字段结构；真实执行时按 `sandbox-setup-guide.md` 输出关键字段摘要及工具实际返回的沙箱测试账号登录密码和支付密码，完整私钥、公钥等密钥字段只写入本地配置文件。
 
 ```json
 {

package/skill/references/integration/modules/sandbox/sandbox-setup-guide.md

@@ -32,7 +32,7 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 - 沙箱配置直接使用沙箱返回的对应私钥字段；生产配置必须确认应用私钥格式与项目语言匹配
 - 写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、其他前后缀、包装行或说明文字
 - 生产应用私钥格式与当前语言 SDK 要求不一致时，使用支付宝开放平台密钥工具做私钥格式转换后再配置
-- 禁止因 `ERR_OSSL_UNSUPPORTED` 推断私钥格式有问题（通常是 SDK 配置参数错误）
+- 禁止因 `ERR_OSSL_UNSUPPORTED` 推断私钥格式或运行时不兼容；应先检查复制污染、字段映射和 SDK 配置参数
 - 详见 [SDK 说明文档 - 私钥格式](../alipay-sdk-reminder.md)
 
 ---
@@ -52,7 +52,7 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 2. 按第 4 节逐项校验必含字段。
 3. 校验通过后，将候选 `data` 按原始 JSON 结构写入正式本地配置文件。
 4. 输出第 5 节规定的关键字段摘要和实际配置文件路径。
-5. 后续写入项目 `.env` 或 SDK 配置时，统一从该本地 JSON 文件读取并映射，避免在对话中复述长字段。
+5. 后续写入项目 `.env` 或 SDK 配置时，统一从该本地 JSON 文件读取并映射，避免在对话中复述密钥等长字段。
 
 校验和落盘可使用 Agent 的结构化 JSON 处理能力、Node.js/Python 标准库或其他可用工具实现，不强依赖 `jq`。
 
@@ -74,6 +74,8 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 | `appPublicKey` | 应用公钥 |
 | 商家账号 | 沙箱商家登录账号 |
 | 买家账号 | 沙箱买家测试账号 |
+| 买家账号 `logonPassword` | 沙箱买家登录密码 |
+| 买家账号 `payPassword` | 沙箱买家支付密码 |
 
 ### 4.2 校验执行清单
 
@@ -88,10 +90,10 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
   - 非 Java：检查 `appPrivatePkcsKey`（PKCS#1）
   IF 缺失：输出 "❌ 沙箱环境校验失败：应用私钥字段为空，无法继续集成，请重新创建沙箱环境。" → STOP
 
-□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号
+□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号 / 买家账号 logonPassword / 买家账号 payPassword
   IF 任一缺失：输出对应字段缺失错误 → STOP
 
-□ 全部通过 → 输出 "✅ 沙箱环境校验通过"
+□ 全部通过 → 不对客输出字段核对表、字段列表、独立的“字段完整性校验通过”提示或任何“沙箱测试通过”表述；直接进入落盘，并按第 5.2 节只输出一张沙箱环境摘要表。
 ```
 
 ---
@@ -100,26 +102,30 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 ### 5.1 本地配置文件
 
-- 默认写入项目根目录 `.alipay-sandbox.json`；若当前目录不适合写入，则写入系统临时目录 `alipay-sandbox-<timestamp>.json`。
+- 默认写入已确认的目标项目根目录 `.alipay-sandbox.json`；若该目标目录不适合写入，则写入系统临时目录 `alipay-sandbox-<timestamp>.json`，不得改写到 Agent 原始工作目录或其他项目。
 - JSON 文件必须保留沙箱返回的原始字段名和嵌套结构，不要转换成 `.env` 扁平键值。
 - 文件权限应尽量限制为当前用户可读写，例如 `chmod 600`。
 - 配置落盘后，必须在对话中输出实际路径。路径必须可定位，例如 `/path/to/project/.alipay-sandbox.json` 或 `./.alipay-sandbox.json`。
 
 ### 5.2 对话摘要
 
-对话默认只输出关键字段摘要和本地配置文件路径，避免私钥、密码、公钥、完整签名串或完整支付表单等长字段刷屏。
+字段无缺失并完成落盘后，对客只用下方一张表展示沙箱信息，不再展示字段核对表、已校验字段列表或独立的校验结论。表中包含本地配置文件路径、关键标识，以及工具实际返回的沙箱测试账号登录密码和支付密码；密钥、完整签名串和完整支付表单等长字段不得展开。账号没有返回某一可选字段时省略对应内容，禁止编造。
 
 ```
-✅ 沙箱环境校验通过
-
-配置文件: <本地配置文件路径>
-应用: appId=<appId>[, pid=<pid，如有>]
-商家账号: email=<email，如有>, userId=<userId，如有>
-买家账号: email=<email，如有>, userId=<userId，如有>
-沙箱: sandboxId=<sandboxId，如有>, sandboxName=<sandboxName，如有>
-长字段: appPrivateKey/appPrivatePkcsKey/alipayPublicKey/appPublicKey/logonPassword/payPassword 已写入本地配置文件，默认不在对话中展开。
+沙箱环境摘要
+
+| 信息 | 内容 |
+|---|---|
+| 配置文件 | `<本地配置文件路径>` |
+| 应用 | `appId=<appId>[, pid=<pid，如有>]` |
+| 商家账号 | `email=<email，如有>, userId=<userId，如有>[, 登录密码=<logonPassword，如有>][, 支付密码=<payPassword，如有>]` |
+| 买家账号 | `email=<email，如有>, userId=<userId，如有>, 登录密码=<logonPassword>, 支付密码=<payPassword>` |
+| 沙箱 | `sandboxId=<sandboxId，如有>, sandboxName=<sandboxName，如有>` |
+| 密钥字段 | `appPrivateKey/appPrivatePkcsKey/alipayPublicKey/appPublicKey` 已写入本地配置文件，默认不在对话中展开 |
 ```
 
+这张表表示沙箱配置字段完整且已经落盘，不表示支付链路已经测试。禁止把表名、前后提示或后续总结改写为“沙箱环境校验通过”“沙箱测试通过”“沙箱环境测试通过”等结论。
+
 ### 5.3 成功创建后提示（卡点）
 
 输出第 5.2 节摘要后，必须继续输出以下成功提示。提示可以和摘要连续输出，但不得省略关键提醒。
@@ -129,21 +135,69 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 📌 环境说明
 - 当前快速沙箱环境仅供测试，不涉及真实资金
-- 完整沙箱信息已写入本地配置文件；对话中仅展示关键字段摘要，不展开私钥、密码、公钥、完整签名串或完整支付表单等长字段
+- 完整沙箱信息已写入本地配置文件；对话中展示工具实际返回的沙箱测试账号登录密码和支付密码，以便完成沙箱付款，不展开私钥、公钥、完整签名串或完整支付表单等长字段
 - 切勿在项目日志、对话总结或测试结果中打印私钥信息
 - 切勿提交正式环境、沙箱环境信息至公共代码仓库（GitHub、GitLab 等）
 
 🔔 必做操作
 - 请自行妥善保管本地配置文件、密钥及测试账号等信息
-- 若需要迁移配置，请从本地配置文件复制，避免通过对话记录传递完整长字段
+- 若需要迁移配置，请从本地配置文件复制，避免通过对话记录传递密钥等完整长字段
 
 🔒 安全提醒
-- 正式上线前请确保您已拥有正式的应用 appId、经过审核的应用私钥及支付宝公钥，并切换至正式环境重新配置密钥
+- 正式上线前请确保您已拥有正式应用的 appId、对应的应用私钥及支付宝公钥，并确认应用和支付产品已达到上线所需状态后切换至正式环境
 - 替换生产配置或启动生产支付测试前，确认 `appId`、应用公钥、应用私钥属于同一套生产应用密钥，并根据项目语言确认私钥格式正确；格式不匹配时使用支付宝开放平台密钥工具转换
 - 正式环境网关地址：https://openapi.alipay.com/gateway.do
-- 正式环境涉及真实资金交易，强烈建议在正式上线之前在沙箱环境中完成全链路测试
+- 正式环境涉及真实资金交易，正式上线前应在沙箱环境完成所有可验证的支付链路；受本地网络条件限制的项目必须另行标记和验证
+```
+
+### 5.4 网站支付沙箱付款提示（代码生成后、集成收尾前）
+
+网站支付代码生成和配置后置校验完成后，先从已确认的目标项目脚本、路由和运行配置中确定真实的服务启动命令和支付页面访问地址，再按回跳分支处理：
+
+- **默认分支**：用户未明确关闭同步回跳时，确认 SDK 实际使用的 `return_url`。启动服务并 GET 访问不带支付结果参数的该地址，只验证路由和页面壳；无订单上下文时应展示安全的中性状态，不得放宽真实回跳请求的验签和订单归属校验。确认无 404、认证或重定向循环，且单页应用直接刷新可用。
+- **渲染验证**：Agent 具备浏览器/UI 能力时，打开回跳页确认非空白、无可见报错且关键内容正常渲染；不具备时，请用户打开精确地址确认。未取得证据时不得宣称回跳页已验证或网站支付集成完成。
+- **关闭分支**：用户已明确关闭同步回跳时，不要求或猜测 `return_url`；确认 SDK 请求未传该字段，并验证异步通知、交易查询和商户订单查询页。
+
+完成对应分支校验后，使用本次已校验沙箱配置中的真实买家账号输出以下提示。不得使用示例端口、占位 URL 或猜测地址；启动命令、支付页面访问地址或账号字段无法确定时，指出缺失项并标记为人工待补充。下方尖括号仅是模板槽位，对客输出时必须替换为真实值；缺少真实值时删除对应占位内容并说明缺失项。
+
+`curl` 调用下单接口并取得 HTML 支付表单只属于接口冒烟检查，不能替代用户付款指引，也不能据此标记步骤 5 完成。必须提供用户可在浏览器中打开的支付页面地址；页面打开沙箱收银台后，以下两种体验方式同时告知用户，由用户自行二选一。
+
+```text
+🧪 网站支付沙箱付款指引
+
+网站支付已接入沙箱环境，可以发起一笔测试付款：
+1. 启动服务并保持运行：`<从目标项目确定的真实启动命令>`
+2. 使用浏览器访问支付页面：`<从目标项目确定的真实访问地址>`
+3. 在页面中发起支付，确认页面成功唤起支付宝沙箱收银台。
+
+付款方式（二选一）：
+
+方式一：收银台账号登录
+4. 在沙箱收银台使用以下沙箱买家账号和登录密码登录，无需使用真实支付宝账号：
+   - 买家账号：<email>
+   - 登录密码：<logonPassword>
+5. 登录后输入沙箱支付密码完成核身与付款：
+   - 支付密码：<payPassword>
+
+方式二：安卓沙箱支付宝扫码
+4. 沙箱支付宝仅支持 Android。复制以下官方地址到网页浏览器打开，按页面指引安装沙箱支付宝：
+   https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original
+5. 在沙箱支付宝中使用上述沙箱买家账号和登录密码登录。
+6. 返回浏览器中的沙箱收银台，使用沙箱支付宝扫描页面二维码，再输入上述沙箱支付密码完成付款。
 ```
 
+紧接上述步骤追加结果判断，必须按实际回跳分支二选一，禁止同时输出两项：
+
+- **默认分支**：“付款后确认浏览器自动返回商户结果页，页面可正常展示并通过服务端查询呈现订单状态。”
+- **关闭分支**：“付款后不会自动返回商户网站；请手动返回商户订单查询页并刷新或查询订单状态。”
+
+两个分支都必须继续提醒：前台页面或同步回跳参数不是支付成功依据，最终结果以验签通过的异步通知或交易查询结果为准。异步通知只有在 `notify_url` 可被支付宝服务器公网访问时才能联调；当前仅有本地或局域网地址时，将该项标记为人工待验证，并明确当前结论属于“本地正式验收 / 本地生产参数验收模式”，不是生产上线完成。
+
+**下载渠道红线：**
+- 严禁声称 iOS 支持安装沙箱版支付宝。
+- 严禁引导用户前往应用市场、搜索引擎或第三方站点搜索下载。
+- 如果上述直链或页面二维码无法使用，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装。
+
 ---
 
 ## 6. 红线与失败处理
@@ -154,7 +208,7 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 2. 禁止用占位符或示例假数据冒充真实返回值。
 3. 禁止假设“工具返回的应该都有”而跳过逐项校验。
 4. 禁止字段不完整时继续集成或写入正式 `.alipay-sandbox.json`。
-5. 禁止把长字段整段刷屏输出。
+5. 除沙箱测试账号的登录密码和支付密码外，禁止把密钥等长字段整段刷屏输出；禁止展示真实生产账号密码。
 
 ### 6.2 重复创建红线
 
@@ -189,14 +243,16 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 ## 7. 写入项目后的后置校验
 
-后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先重新复制沙箱字段或修正 SDK 配置。
+后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先从第 5.1 节的可信配置文件重新读取字段或修正 SDK 配置。
 
 - 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置。
-- 确认应用私钥不是占位符、示例值或其他来源的密钥，未出现复制截断或粘贴污染。
+- 从第 5.1 节输出的实际配置文件结构化读取并映射字段，禁止从对话、历史代码或示例值复制密钥。
+- 以不输出字段原文的方式比较项目实际读取值与沙箱原值，确认应用私钥不是占位符、示例值或其他来源的密钥，且未出现截断、字符替换或粘贴污染。
 - 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
-- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字。
+- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字；业务协议直接使用原生密码库签名时，可按密码库要求临时适配调用入参，但不得修改或覆盖原始配置值。
+- 仅按量付费沙箱联调：项目沙箱运行配置中的 `serviceId` 固定为 `api_mock_service_id`，不从快速沙箱返回中寻找，也不向用户索要正式 `serviceId`。该值不得进入生产配置。
 - 校验输出不得包含私钥、公钥、签名串或完整支付表单。
 
 **常见失败处理：**
-- 私钥不完整、配置不一致或 SDK 初始化/解析失败：重新复制完整私钥字段，禁止补字符、猜测或格式转换。
-- `DECODER routines::unsupported`：优先检查私钥是否复制完整、是否错误添加 PEM 头尾或其他前后缀、`keyType` 是否错误，不要切换成 PKCS#8 试错。
+- 私钥不完整、配置不一致或 SDK 初始化/签名失败：从第 5.1 节的可信配置文件重新读取正确字段，禁止补字符、猜测或格式转换。
+- `ERR_OSSL_UNSUPPORTED`、`DECODER routines::unsupported` 等错误：优先检查项目读取值是否与沙箱原值一致、字段映射是否正确、SDK 配置是否被加工；不要切换私钥字段或在缺少对照证据时归因于运行时、OpenSSL 或 SDK 兼容性。

package/skill/references/integration/modules/scripts/local_402_sandbox_pay.py

@@ -21,6 +21,7 @@ from urllib.parse import quote
 
 PAY_ENDPOINT = "http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay"
 PAY_URL_PREFIX = "https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema="
+A2M_SANDBOX_SERVICE_ID = "api_mock_service_id"
 DEFAULT_PAYMENT_NEEDED_FILE = "/tmp/402_needed_file.txt"
 DEFAULT_PAY_RETRIES = 3
 DEFAULT_PAY_RETRY_DELAY_SECONDS = 2.0
@@ -462,6 +463,12 @@ def command_run(args: argparse.Namespace) -> int:
         )
 
     decoded_bill = b64decode_json(payment_needed)
+    method_data = decoded_bill.get("method") if isinstance(decoded_bill.get("method"), dict) else {}
+    if method_data.get("service_id") != A2M_SANDBOX_SERVICE_ID:
+        raise RuntimeError(
+            f"沙箱联调 method.service_id 必须为 {A2M_SANDBOX_SERVICE_ID}，"
+            "请修正用户服务的沙箱运行配置后重试"
+        )
     cashier_payload = build_cashier_payload(decoded_bill, buyer_id, args.buyer_signature)
 
     (artifact_dir / "payment_needed.txt").write_text(payment_needed, encoding="utf-8")
@@ -514,12 +521,13 @@ def command_run(args: argparse.Namespace) -> int:
             "errorMessage": pay_response.get("errorMessage"),
         }
         write_json(artifact_dir / "state.json", state)
+        retry_mode = " --auto-complete" if args.auto_complete else ""
         raise RuntimeError(
             "收银接口未返回 payScheme，无法生成付款链接。"
             f"过程产物已保存：{artifact_dir}。"
             "如果是 PAY_SUBMIT_FAILED/系统繁忙，可稍后复用同一个 Payment-Needed 重试：\n"
             f"python3 {shell_quote(Path(__file__).resolve())} run "
-            f"--reuse-artifact {shell_quote(artifact_dir)}"
+            f"--reuse-artifact {shell_quote(artifact_dir)}{retry_mode}"
         )
 
     pay_url = pay_url_from_response(pay_response)
@@ -528,9 +536,24 @@ def command_run(args: argparse.Namespace) -> int:
     state["tradeNo"] = trade_no
     write_json(artifact_dir / "state.json", state)
 
+    print(f"\n过程产物目录：{artifact_dir}")
+
+    if args.auto_complete:
+        print("\n继续执行 Payment-Proof 服务端联调...")
+        complete_args = argparse.Namespace(
+            artifact_dir=str(artifact_dir),
+            payment_proof=args.payment_proof,
+            buyer_signature=args.buyer_signature,
+        )
+        result = command_complete(complete_args)
+        if result == 0:
+            print("\n按量付费沙箱服务端联调通过。")
+            print("\n沙箱付款体验链接（可选）：")
+            print(pay_url)
+        return result
+
     print("\n请在浏览器打开以下链接，并使用沙箱买家账号完成付款：")
     print(pay_url)
-    print(f"\n过程产物目录：{artifact_dir}")
     print("付款成功后运行：")
     print(f"python3 {Path(__file__).resolve()} complete --artifact-dir {artifact_dir}")
 
@@ -619,7 +642,10 @@ def build_parser() -> argparse.ArgumentParser:
     run_parser.add_argument("--reuse-artifact", help="复用上一轮 run 产物中的 url/method/body/content-type/payment_needed")
     run_parser.add_argument("--pay-endpoint", default=PAY_ENDPOINT)
     run_parser.add_argument("--artifact-dir", help="生成过程产物的目录")
-    run_parser.add_argument("--payment-proof", help="使用 --wait 时可选的最终 payment_proof 值")
+    run_parser.add_argument(
+        "--payment-proof",
+        help="使用 --auto-complete 或 --wait 时可选的最终 payment_proof 值",
+    )
     run_parser.add_argument("--pay-retries", type=int, default=DEFAULT_PAY_RETRIES, help="沙箱收银接口临时失败时的重试次数")
     run_parser.add_argument(
         "--pay-retry-delay",
@@ -628,12 +654,17 @@ def build_parser() -> argparse.ArgumentParser:
         help="沙箱收银接口重试间隔秒数",
     )
     run_parser.add_argument("--dry-run", action="store_true", help="调用收银接口前停止")
+    run_parser.add_argument(
+        "--auto-complete",
+        action="store_true",
+        help="生成付款链接后连续携带 Payment-Proof 重试原始服务",
+    )
     run_parser.add_argument("--wait", action="store_true", help="等待付款后立刻重试原始服务")
     run_parser.set_defaults(func=command_run)
 
     complete_parser = subparsers.add_parser("complete", help="携带 Payment-Proof 重试原始服务")
     complete_parser.add_argument("--artifact-dir", required=True, help="run 命令生成的过程产物目录")
-    complete_parser.add_argument("--payment-proof", help="可选 payment_proof；默认生成一个确定性的非空哈希")
+    complete_parser.add_argument("--payment-proof", help="可选 payment_proof；未传时由脚本按沙箱联调约定处理")
     complete_parser.add_argument("--buyer-signature", help="买家签名占位值")
     complete_parser.set_defaults(func=command_complete)
 

package/skill/references/normal/alipay-cli-env.md

@@ -36,7 +36,7 @@ fi
 - `alipay-cli login`、`alipay-cli whoami`、`alipay-cli logout`
 - `alipay-cli mcp call ...`
 - `alipay-cli file upload ...`
-- `export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | bash`
+- `export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | ALIPAY_CLI_SKIP_PGP=true ALIPAY_CLI_SKIP_VERIFY=true bash`
 - 按量付费沙箱测试中会访问用户服务或沙箱收银接口的 `local_402_sandbox_pay.py`
 
 **执行要求：**
@@ -127,7 +127,7 @@ jq --version
 
 ```bash
 mkdir -p ~/.local/bin
-export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | bash
+export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | ALIPAY_CLI_SKIP_PGP=true ALIPAY_CLI_SKIP_VERIFY=true bash
 ```
 
 ### 4.2 PATH 处理

package/skill/references/normal/self-update.md

@@ -1,6 +1,6 @@
 # Skill 启动自更新检查
 
-本文件定义 `alipay-aipay` Skill 启动时的 best-effort 自更新检查。该检查用于降低用户继续使用旧版 Skill 的概率，但不得阻断支付集成或签约入驻主流程。
+本文件定义 `alipay-aipay` Skill 启动时的自更新检查。该检查用于降低用户继续使用旧版 Skill 的概率，但不得阻断支付集成或签约入驻主流程。
 
 ## 执行原则
 
@@ -14,7 +14,7 @@
 ## 版本读取
 
 1. 读取当前 `SKILL.md` 所在目录下的 `VERSION` 文件作为本地版本。
-2. 如果 `VERSION` 不存在，或内容不是合法 SemVer 版本号（例如 `1.0.6`），将当前安装视为“未知版本/旧版安装”，直接进入「未知版本更新规则」，不要再猜测其他安装记录文件。
+2. 如果 `VERSION` 不存在，或内容不是合法 SemVer 版本号（例如 `latest` 或 `v1`），将当前安装视为“未知版本/旧版安装”，直接进入「未知版本更新规则」，不要再猜测其他安装记录文件。
 3. 如果成功读取本地版本，执行以下命令查询 npm latest：
    ```bash
    npm view @alipay/alipay-aipay version --json