@alipay/alipay-aipay 1.0.2 → 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,33 +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`，用于调大沙箱收银接口临时失败时的重试次数与间隔。
 
-### 第三步：用户完成付款
+### 第三步：连续验证 Payment-Proof 重试
 
-**必须将脚本输出的付款链接发给用户**，并提示：
+标准流程使用第二步命令中的 `--auto-complete`。脚本生成付款链接后，使用同一过程产物继续执行 `complete` 逻辑并输出服务端联调结果。
 
-> 请在浏览器打开以下链接，使用沙箱买家账号完成付款：
-> - 买家账号：`{email}`（如 `xxxxx@sandbox.com`）
-> - 登录密码：`{logonPassword}`（如 `111111`）
-> - 支付密码：`{payPassword}`（如 `111111`）
->
-> {付款链接}
-
-同时提醒用户：
-
-> 沙箱支付宝当前仅支持安卓系统。如果尚未安装沙箱版支付宝，请复制以下链接到网页浏览器打开，并使用支付宝客户端扫码下载沙箱版支付宝安装包：
->
-> https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original
-
-等待用户确认付款成功后，记录过程产物目录 `$ARTIFACT_DIR`，进入第四步。
-
-### 第四步：验证 Payment-Proof 重试
-
-用户确认付款成功后，运行 `complete` 命令：
+如果标准命令在生成付款链接后因进程中断而未完成最终重试，使用同一过程产物恢复：
 
 ```bash
 python3 ../scripts/local_402_sandbox_pay.py complete \
@@ -181,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
 {
@@ -211,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 值（可选）
@@ -233,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 请求。
@@ -247,7 +276,7 @@ python3 ../scripts/local_402_sandbox_pay.py run   --url "$SERVICE_URL"   --metho
 3. **过程产物**：默认写入 `/tmp/alipay_local_402_sandbox_pay_<timestamp>`，可通过 `--artifact-dir` 指定
 4. **买家签名**：默认占位值 `-`，无需修改
 5. **沙箱化 Agent 网络权限**：脚本内 `fetch_payment_needed` 使用 curl，且收银测试会访问沙箱接口；沙箱化 Agent 环境首次执行即申请可联网权限
-6. **沙箱支付宝安装包**：沙箱支付宝当前仅支持安卓系统；如无法完成付款，引导用户复制 `https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original` 到网页浏览器打开，并使用支付宝客户端扫码下载沙箱版支付宝安装包
+6. **沙箱支付宝安装包**：沙箱支付宝当前仅支持安卓系统；默认引导用户复制 `https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original` 到网页浏览器打开，并使用支付宝客户端扫码下载。若用户明确反馈该直链、页面二维码无法打开或无法下载，只能引导用户前往支付宝开放平台沙箱工具页 `https://open.alipay.com/develop/sandbox/tool`，按页面指引安装沙箱版支付宝。严禁引导用户使用 iOS 沙箱支付宝、应用市场搜索、`https://sandbox.alipay.com` 或其他自编下载 URL。
 
 ---
 
@@ -260,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. 创建快速沙箱
 
-**重要：输出时必须完整展示所有字段，不允许省略 privateKey、publicKey 等长字段。如果输出被截断，需按 `sandbox-setup-guide.md` 的表格格式重新输出完整字段。**
+**重要：工具返回的 `data` 只是候选沙箱配置；必须先按 `sandbox-setup-guide.md` 完成字段完整性校验，校验通过后再写入正式本地配置文件。字段无缺失时，不对客输出字段核对表或独立校验结论，只按该指南输出一张沙箱环境摘要表；该结果不代表沙箱支付测试通过。privateKey、publicKey 等密钥字段不得展开。**
 
 `createAnonymousSandbox` 的 MCP 请求体只有业务入参 `request.appType`。`PLATFORM`、`PRODUCT` 是 alipay-cli 上下文环境变量，禁止写入 `--data` 的 JSON。
 
@@ -54,8 +54,9 @@ alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
 **结果解析：**
 
 1. 取 `result.content[0].text`，去转义还原 JSON
-2. `success === true` → 输出简短成功提示，将 `data` 字段**完整原样**按 [沙箱环境初始化](sandbox-setup-guide.md) 中的沙箱信息输出格式以表格展示，保持原始字段值不变，不做任何脱敏、省略或重排
-3. `success !== true` → 按错误处理流程
+2. `success === true` → 提取 `data` 字段作为候选沙箱配置，先按 [沙箱环境初始化](sandbox-setup-guide.md) 的必含字段清单做完整性校验
+3. 字段完整性校验通过 → 将 `data` 字段完整写入正式本地配置文件，并按 `sandbox-setup-guide.md` 只输出一张沙箱环境摘要表；不输出字段核对表、独立校验结论或“沙箱测试通过”等表述，保持本地文件中的原始字段值不变，不在对话中复述密钥等长字段
+4. `success !== true` 或 `data` 字段缺失/字段不完整 → 按错误处理流程阻断；不得写入正式 `.alipay-sandbox.json`
 
 ## 3. 错误处理
 
@@ -74,9 +75,11 @@ CLI 输出不暴露 HTTP 状态码，统一按响应体中的 `success` 字段
 - 执行前向用户展示即将运行的命令
 - 参数不确定时先向用户确认
   
-## 返回示例
+## 返回结构示例
 
-### 成功示例
+### 成功结构示例
+
+> 下例仅用于说明字段结构；真实执行时按 `sandbox-setup-guide.md` 输出关键字段摘要及工具实际返回的沙箱测试账号登录密码和支付密码，完整私钥、公钥等密钥字段只写入本地配置文件。
 
 ```json
 {

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

@@ -14,7 +14,7 @@
 ### 1.2 Windows 用户注意事项
 **快速沙箱 CLI 工具暂不支持 Windows 系统**。
 
-Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用 自行获取沙箱信息。
+Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用，自行获取沙箱信息。
 
 ### 1.3 其他说明
 沙箱环境暂不支持用户主动通过看板查看测试账号的交易信息（如：卖家余额、交易状态等）。**严禁**引导用户访问所谓的“支付宝沙箱网页版”查看测试账户的余额变动等。
@@ -32,96 +32,52 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 - 沙箱配置直接使用沙箱返回的对应私钥字段；生产配置必须确认应用私钥格式与项目语言匹配
 - 写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、其他前后缀、包装行或说明文字
 - 生产应用私钥格式与当前语言 SDK 要求不一致时，使用支付宝开放平台密钥工具做私钥格式转换后再配置
-- 禁止因 `ERR_OSSL_UNSUPPORTED` 推断私钥格式有问题（通常是 SDK 配置参数错误）
+- 禁止因 `ERR_OSSL_UNSUPPORTED` 推断私钥格式或运行时不兼容；应先检查复制污染、字段映射和 SDK 配置参数
 - 详见 [SDK 说明文档 - 私钥格式](../alipay-sdk-reminder.md)
 
 ---
 
-## 3. 配置流程
+## 3. 沙箱初始化流程
 
-### 3.1 调用工具创建环境
+### 3.1 获取候选沙箱配置
 
-参考 [alipay-sandbox-tool](alipay-sandbox-tool.md) 创建快速沙箱环境。
+- Unix/macOS/Linux：参考 [alipay-sandbox-tool](alipay-sandbox-tool.md) 调用快速沙箱工具。
+- Windows：快速沙箱 CLI 工具暂不支持，按第 1.2 节引导用户自行获取沙箱信息。
+- 工具返回 `success === true` 只代表拿到候选 `data`；必须完成第 4 节字段完整性校验后，才允许写入正式配置文件。
+- `success !== true`、`data` 缺失或字段不完整时，按第 6 节失败处理阻断流程。
 
-**异常处理**：创建失败时提示 "❌ 快速沙箱创建失败，请稍后重试"。
+### 3.2 固定处理顺序
 
-### 3.2 沙箱信息输出格式
+1. 提取候选 `data`。
+2. 按第 4 节逐项校验必含字段。
+3. 校验通过后，将候选 `data` 按原始 JSON 结构写入正式本地配置文件。
+4. 输出第 5 节规定的关键字段摘要和实际配置文件路径。
+5. 后续写入项目 `.env` 或 SDK 配置时，统一从该本地 JSON 文件读取并映射，避免在对话中复述密钥等长字段。
 
-**必须按以下表格格式**输出，**严禁**使用 JSON 代码块。所有字段完整原样展示，不得脱敏、省略或截断。
-
-**应用配置**
-
-| 字段 | 说明 | 值 |
-|------|------|-----|
-| `appId` | 沙箱应用 ID | {实际返回值} |
-| `appPrivateKey` | 应用私钥（PKCS#8，Java 语言使用） | {实际返回值} |
-| `appPrivatePkcsKey` | 应用私钥（PKCS#1，非 Java 语言使用） | {实际返回值} |
-| `alipayPublicKey` | 支付宝公钥 | {实际返回值} |
-| `appPublicKey` | 应用公钥 | {实际返回值} |
-| `pid` | 商户 PID | {实际返回值} |
-
-**商家账号**
-
-| 字段 | 值 |
-|------|-----|
-| `accountDesc` | {实际返回值} |
-| `email` | {实际返回值} |
-| `merchantId` | {实际返回值} |
-| `userId` | {实际返回值} |
-| `acctrans` | {实际返回值} |
-
-**买家账号**
-
-| 字段 | 值 |
-|------|-----|
-| `accountDesc` | {实际返回值} |
-| `email` | {实际返回值} |
-| `userName` | {实际返回值} |
-| `userId` | {实际返回值} |
-| `logonPassword` | {实际返回值} |
-| `payPassword` | {实际返回值} |
-| `certNo` | {实际返回值} |
-| `certType` | {实际返回值} |
-| `acctrans` | {实际返回值} |
-
-**沙箱信息**
-
-| 字段 | 值 |
-|------|-----|
-| `sandboxId` | {实际返回值} |
-| `sandboxName` | {实际返回值} |
+校验和落盘可使用 Agent 的结构化 JSON 处理能力、Node.js/Python 标准库或其他可用工具实现，不强依赖 `jq`。
 
 ---
 
-## 4. 强校验规则（卡点）
+## 4. 字段完整性校验（卡点）
 
-工具返回环境信息后，**必须执行逐项强校验**，校验通过方可进入后续步骤。未通过则**阻断流程**，要求重新创建。
+工具返回环境信息后，必须先逐项校验。任一必含字段缺失或为空时，立即停止，不得写入正式 `.alipay-sandbox.json`，并明确告知具体缺失字段。
 
 ### 4.1 必含字段清单
 
-以下字段必须全部存在且非空：
+以下字段必须按项目语言和测试账号要求存在且非空：
 
 | 字段 | 说明 |
 |---|---|
 | `appId` | 沙箱应用 ID |
-| `appPrivateKey` / `appPrivatePkcsKey` | 应用私钥（Java 使用 `appPrivateKey`，非 Java 使用 `appPrivatePkcsKey`） |
+| 应用私钥 | Java 必须存在 `appPrivateKey`；非 Java 必须存在 `appPrivatePkcsKey` |
 | `alipayPublicKey` | 支付宝公钥 |
 | `appPublicKey` | 应用公钥 |
 | 商家账号 | 沙箱商家登录账号 |
 | 买家账号 | 沙箱买家测试账号 |
+| 买家账号 `logonPassword` | 沙箱买家登录密码 |
+| 买家账号 `payPassword` | 沙箱买家支付密码 |
 
-### 4.2 绝对禁止（红线）
-
-**以下行为严格禁止：**
-
-1. **禁止编造字段** —— 不得生成、拼接、模拟、猜测缺失的字段值
-2. **禁止用占位符冒充真实数据** —— 当沙箱成功返回完整配置时，禁止用占位符代替真实返回值
-3. **禁止假数据** —— 不得自行生成示例私钥、示例账号等任何假数据
-4. **禁止假设存在** —— 不得假设"工具返回的应该都有"而不逐项检查
-5. **禁止部分通过** —— 不得因"只有 1 个字段缺失"而继续执行
-6. **禁止跳过校验** —— 不得在未完成逐项校验的情况下直接使用返回结果
-
-### 4.3 校验执行清单
+### 4.2 校验执行清单
 
 **规则：** 任一字段缺失 → **立即停止** → 输出错误提示 → **禁止继续**
 
@@ -134,85 +90,169 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
   - 非 Java：检查 `appPrivatePkcsKey`（PKCS#1）
   IF 缺失：输出 "❌ 沙箱环境校验失败：应用私钥字段为空，无法继续集成，请重新创建沙箱环境。" → STOP
 
-□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号
+□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号 / 买家账号 logonPassword / 买家账号 payPassword
   IF 任一缺失：输出对应字段缺失错误 → STOP
 
-□ 全部通过 → 输出 "✅ 沙箱环境校验通过"
+□ 全部通过 → 不对客输出字段核对表、字段列表、独立的“字段完整性校验通过”提示或任何“沙箱测试通过”表述；直接进入落盘，并按第 5.2 节只输出一张沙箱环境摘要表。
 ```
 
-### 4.3.1 配置写入后的后置校验
+---
 
-后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先重新复制沙箱字段或修正 SDK 配置。必须确认以下目标：
+## 5. 落盘与摘要输出
 
-- 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置，且与沙箱返回配置一致。
-- 确认应用私钥不是占位符、示例值或其他来源的密钥，未出现复制截断或粘贴污染。
-- 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
-- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字。
-- 校验输出不得包含私钥、公钥、签名串或完整支付表单。
+### 5.1 本地配置文件
 
-**常见失败处理：**
-- 私钥不完整、配置不一致或 SDK 初始化/解析失败：重新复制完整私钥字段，禁止补字符、猜测或格式转换。
-- `DECODER routines::unsupported`：优先检查私钥是否复制完整、是否错误添加 PEM 头尾或其他前后缀、`keyType` 是否错误，不要切换成 PKCS#8 试错。
+- 默认写入已确认的目标项目根目录 `.alipay-sandbox.json`；若该目标目录不适合写入，则写入系统临时目录 `alipay-sandbox-<timestamp>.json`，不得改写到 Agent 原始工作目录或其他项目。
+- JSON 文件必须保留沙箱返回的原始字段名和嵌套结构，不要转换成 `.env` 扁平键值。
+- 文件权限应尽量限制为当前用户可读写，例如 `chmod 600`。
+- 配置落盘后，必须在对话中输出实际路径。路径必须可定位，例如 `/path/to/project/.alipay-sandbox.json` 或 `./.alipay-sandbox.json`。
 
-### 4.4 重试与失败处理
+### 5.2 对话摘要
 
-| 失败场景 | 处理策略 |
-|---------|---------|
-| 首次失败 | 提示 "❌ 快速沙箱创建失败，请稍后重试"，等待用户指示后重试 |
-| 字段缺失 | 明确告知**具体缺失字段名称**，禁止只说"部分字段缺失" |
-| 反复失败（≥2次） | 输出强提醒，提供两个选项：①重新输入指令 ②自行申领沙箱应用，禁止继续自动重试 |
-| 用户提供手动配置 | 仍需按「校验执行清单」逐项校验，通过后方可继续 |
+字段无缺失并完成落盘后，对客只用下方一张表展示沙箱信息，不再展示字段核对表、已校验字段列表或独立的校验结论。表中包含本地配置文件路径、关键标识，以及工具实际返回的沙箱测试账号登录密码和支付密码；密钥、完整签名串和完整支付表单等长字段不得展开。账号没有返回某一可选字段时省略对应内容，禁止编造。
 
-**反复失败提示模板**：
 ```
-🚨 快速沙箱环境多次创建失败/字段不完整
+沙箱环境摘要
 
-缺失字段：[列出具体缺失的字段名称]
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-请您选择以下方式之一解决：
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-【选项一】重新输入创建快速沙箱指令
-  操作方式：在对话中重新输入"创建快速沙箱"或类似指令
-  适用场景：可能因服务波动导致创建失败，稍后重试可能成功
-
-【选项二】自行申领沙箱应用
-  操作方式：前往支付宝开放平台（https://open.alipay.com）手动申领沙箱应用
-  适用场景：需要使用自己的沙箱账号，获取 appId、应用私钥、支付宝公钥等信息后手动配置
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️ 在配置完整之前，无法继续集成流程。
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| 信息 | 内容 |
+|---|---|
+| 配置文件 | `<本地配置文件路径>` |
+| 应用 | `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. 成功创建后提示（卡点）
+这张表表示沙箱配置字段完整且已经落盘，不表示支付链路已经测试。禁止把表名、前后提示或后续总结改写为“沙箱环境校验通过”“沙箱测试通过”“沙箱环境测试通过”等结论。
 
-**⛔ 强制要求：校验通过后，必须在回复中完整输出以下内容。**
+### 5.3 成功创建后提示（卡点）
 
-- **禁止省略**：不得跳过、缩减
-- **禁止改写**：必须按原文输出
-- **未输出此提示即继续 = 违规**
+输出第 5.2 节摘要后，必须继续输出以下成功提示。提示可以和摘要连续输出，但不得省略关键提醒。
 
 ```
 ⚠️ 快速沙箱环境已创建完成
 
 📌 环境说明
 - 当前快速沙箱环境仅供测试，不涉及真实资金
-- 完整展示沙箱信息，无需对内容脱敏
-- 切勿在项目日志中打印私钥信息
+- 完整沙箱信息已写入本地配置文件；对话中展示工具实际返回的沙箱测试账号登录密码和支付密码，以便完成沙箱付款，不展开私钥、公钥、完整签名串或完整支付表单等长字段
+- 切勿在项目日志、对话总结或测试结果中打印私钥信息
 - 切勿提交正式环境、沙箱环境信息至公共代码仓库（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. 红线与失败处理
+
+### 6.1 绝对禁止
+
+1. 禁止编造、拼接、模拟、猜测缺失字段。
+2. 禁止用占位符或示例假数据冒充真实返回值。
+3. 禁止假设“工具返回的应该都有”而跳过逐项校验。
+4. 禁止字段不完整时继续集成或写入正式 `.alipay-sandbox.json`。
+5. 除沙箱测试账号的登录密码和支付密码外，禁止把密钥等长字段整段刷屏输出；禁止展示真实生产账号密码。
+
+### 6.2 重复创建红线
+
+- 候选 `data` 通过第 4 节字段完整性校验后，必须使用本次返回的 `data` 完成正式落盘。
+- 禁止为了“把 data 写入本地文件”“避免对话展示长字段”或“重新拿一份完整配置”再次创建沙箱。
+- 如果第一次通过校验的 `data` 因 Agent 操作失误未落盘，应先从已有工具输出、过程产物或当前可访问的执行结果中恢复；无法恢复时必须向用户说明问题并征得用户明确同意后，才可重新创建。
+
+### 6.3 重试与失败处理
+
+| 失败场景 | 处理策略 |
+|---------|---------|
+| 首次创建失败 | 提示 "❌ 快速沙箱创建失败，请稍后重试"，等待用户指示后重试 |
+| 字段缺失 | 明确告知具体缺失字段名称，禁止只说"部分字段缺失" |
+| 反复失败（≥2次） | 输出强提醒，提供两个选项：①重新输入指令 ②自行申领沙箱应用，禁止继续自动重试 |
+| 用户提供手动配置 | 仍需按第 4 节逐项校验，通过后方可继续 |
+
+反复失败时输出：
+
+```
+🚨 快速沙箱环境多次创建失败/字段不完整
+
+缺失字段：[列出具体缺失的字段名称]
+
+请您选择以下方式之一解决：
+1. 重新输入“创建快速沙箱”指令
+2. 前往支付宝开放平台（https://open.alipay.com）自行申领沙箱应用，需要使用自己的沙箱账号，获取 appId、应用私钥、支付宝公钥等信息后手动配置
+
+在配置完整之前，无法继续集成流程。
+```
+
+---
+
+## 7. 写入项目后的后置校验
+
+后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先从第 5.1 节的可信配置文件重新读取字段或修正 SDK 配置。
+
+- 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置。
+- 从第 5.1 节输出的实际配置文件结构化读取并映射字段，禁止从对话、历史代码或示例值复制密钥。
+- 以不输出字段原文的方式比较项目实际读取值与沙箱原值，确认应用私钥不是占位符、示例值或其他来源的密钥，且未出现截断、字符替换或粘贴污染。
+- 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
+- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字；业务协议直接使用原生密码库签名时，可按密码库要求临时适配调用入参，但不得修改或覆盖原始配置值。
+- 仅按量付费沙箱联调：项目沙箱运行配置中的 `serviceId` 固定为 `api_mock_service_id`，不从快速沙箱返回中寻找，也不向用户索要正式 `serviceId`。该值不得进入生产配置。
+- 校验输出不得包含私钥、公钥、签名串或完整支付表单。
+
+**常见失败处理：**
+- 私钥不完整、配置不一致或 SDK 初始化/签名失败：从第 5.1 节的可信配置文件重新读取正确字段，禁止补字符、猜测或格式转换。
+- `ERR_OSSL_UNSUPPORTED`、`DECODER routines::unsupported` 等错误：优先检查项目读取值是否与沙箱原值一致、字段映射是否正确、SDK 配置是否被加工；不要切换私钥字段或在缺少对照证据时归因于运行时、OpenSSL 或 SDK 兼容性。