@alipay/alipay-aipay 0.1.1-beta.1

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

@@ -0,0 +1,270 @@
+# 按量付费沙箱测试
+
+> ⚠️ **仅当产品为「按量付费」时执行此步骤**。网站支付和APP支付无需此步骤，跳过直接进入步骤 6。
+
+本文档定义按量付费 402 协议的沙箱端到端支付测试流程。测试脚本位于 `../scripts/local_402_sandbox_pay.py`。
+
+> 本文档位于 `references/integration/modules/sandbox/`，文中的 `../scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/integration/modules/scripts/...`。
+
+---
+
+## 前提条件
+
+在执行此步骤前，必须满足：
+
+1. **已完成步骤 4 代码生成**：按量付费集成代码已生成并整合进用户项目
+2. **用户本地服务已启动**：服务端已运行在可访问的地址上（如 `http://localhost:5000/demo/a2m/resource`）
+3. **已知沙箱买家 2088 账号**：从步骤 2 沙箱信息输出的买家账号中获取 `userId`（如 `2088722100508485`）
+4. **Python 3 可用**：测试脚本依赖 Python 3 运行
+
+---
+
+## 测试前预检
+
+执行沙箱测试脚本前，先解码服务返回的 `Payment-Needed`，确认关键字段存在。`SERVICE_URL` 使用用户实际服务地址。
+
+```bash
+curl -s -D - -o /dev/null "$SERVICE_URL" \
+  | python3 -c 'import sys, base64, json
+headers = sys.stdin.read().splitlines()
+statuses = [line.split() for line in headers if line.startswith("HTTP/")]
+status = statuses[-1][1] if statuses and len(statuses[-1]) > 1 else ""
+if status != "402":
+    raise SystemExit(f"HTTP 状态不是 402: {status or '未知'}")
+value = next((line.split(":", 1)[1].strip().strip("\"") for line in headers if line.lower().startswith("payment-needed:")), "")
+if not value:
+    raise SystemExit("未找到 Payment-Needed 响应头")
+value += "=" * ((4 - len(value) % 4) % 4)
+data = json.loads(base64.urlsafe_b64decode(value).decode())
+required = [
+    ("protocol", "out_trade_no"), ("protocol", "amount"), ("protocol", "currency"),
+    ("protocol", "resource_id"), ("protocol", "pay_before"), ("protocol", "seller_signature"),
+    ("protocol", "seller_sign_type"), ("protocol", "seller_unique_id"),
+    ("method", "seller_name"), ("method", "seller_id"), ("method", "seller_app_id"),
+    ("method", "goods_name"), ("method", "seller_unique_id_key"), ("method", "service_id"),
+]
+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))
+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` 生成，禁止使用空值或占位符。预检输出只打印校验结论和字段名，不打印字段值。
+
+---
+
+## 测试脚本路径
+
+```bash
+python3 ../scripts/local_402_sandbox_pay.py
+```
+
+脚本提供两个子命令：
+- `run`：获取 Payment-Needed 并生成沙箱付款链接
+- `complete`：携带 Payment-Proof 重试原始服务
+
+---
+
+## 完成条件
+
+- [M-05] 已确认用户本地按量付费服务已启动可访问
+- [M-05] 已完成 Payment-Needed 预检，确认 HTTP 402 和关键字段存在
+- [M-05] 已执行沙箱支付测试脚本 `run`，成功获取 Payment-Needed 并生成付款链接
+- [M-05] 用户已在浏览器使用沙箱买家账号完成付款
+- [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`），执行时无需额外指定。**
+
+GET 请求：
+
+```bash
+python3 ../scripts/local_402_sandbox_pay.py run \
+  --url "$SERVICE_URL" \
+  --method GET \
+  --buyer-id "$BUYER_2088"
+```
+
+POST 请求：
+
+```bash
+python3 ../scripts/local_402_sandbox_pay.py run \
+  --url "$SERVICE_URL" \
+  --method POST \
+  --body "$BODY" \
+  --buyer-id "$BUYER_2088"
+```
+
+**脚本执行步骤**：
+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. 生成浏览器付款链接
+
+**脚本输出**：
+- Payment-Needed 获取结果和本地过程产物路径（终端不输出原始值）
+- 脱敏后的账单 JSON
+- 脱敏后的收银接口请求体
+- 收银接口返回
+- **浏览器付款链接**（格式：`https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema=...`）
+- 过程产物目录路径（`$ARTIFACT_DIR`）
+
+**错误处理**：
+- 沙箱化 Agent 环境执行本脚本时，首次执行即申请可联网权限；如果已因网络受限失败，复用同一条命令申请可联网权限重试
+- 如果未找到 `Payment-Needed` 响应头，确认服务端是否实现了 402 协议
+- 如果收银接口返回 `PARAM_INVALID: protocol.sellerSignature不能为空`，回到预检步骤检查 `protocol.seller_signature` 是否为空、缺失或仍是占位符
+- 如果 `pay_before` 相关参数报错，检查是否使用 ISO 8601 带时区格式
+- 如果收银接口返回 `PAY_SUBMIT_FAILED`、`系统繁忙` 或缺少 `payScheme`，不要重新请求用户服务生成新订单。脚本默认会自动重试；仍失败时，复用过程产物重试收银接口：
+  ```bash
+  python3 ../scripts/local_402_sandbox_pay.py run \
+    --reuse-artifact "$ARTIFACT_DIR"
+  ```
+  `--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
+
+等待用户确认付款成功后，记录过程产物目录 `$ARTIFACT_DIR`，进入第四步。
+
+### 第四步：验证 Payment-Proof 重试
+
+用户确认付款成功后，运行 `complete` 命令：
+
+```bash
+python3 ../scripts/local_402_sandbox_pay.py complete \
+  --artifact-dir "$ARTIFACT_DIR"
+```
+
+**脚本执行步骤**：
+1. 读取过程产物目录中的 `state.json`
+2. 使用前面沙箱收银接口下单返回的 `trade_no` 构建 `Payment-Proof` 请求头（含 `payment_proof`、`trade_no`、`client_session`）
+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 编码。
+
+参考结构：
+
+```json
+{
+  "protocol": {
+    "payment_proof": "bc0535fc673722fee9d37306239859fb30bddae8fdc971df2069e37401380452",
+    "trade_no": "20260702008281225779190000002293"
+  },
+  "method": {
+    "client_session": "eyJleHRlcm5hbElkIjoiMjA4ODcyMjEwMjczMjcwNyIsInNpZ25hdHVyZSI6Ii0iLCJ0aW1lc3RhbXAiOiIxNzgyODg0OTkyODc5In0="
+  }
+}
+```
+
+**验证要点**：
+- 服务返回 HTTP 200（而非 402）
+- 响应体包含服务资源内容（如 `resource_id`、`content` 等）
+- 如果服务实现了 `Payment-Validation` 响应头，检查其内容
+
+**常见失败与排查**：
+- `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` 重试履约确认。
+
+### 第五步：测试结论
+
+测试通过后输出：
+
+```
+✅ 按量付费沙箱全链路测试通过
+
+| 测试项 | 状态 |
+|--------|------|
+| 402 Payment-Needed 返回 | ✅ |
+| 沙箱收银台付款 | ✅ |
+| Payment-Proof 重试 | ✅ |
+| 资源交付 | ✅ |
+```
+
+---
+
+## 已有 Payment-Needed 值（可选）
+
+如果用户已经提供了 `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"
+```
+
+脚本将直接解码该值并继续后续流程，不再发起 curl 请求。
+
+---
+
+## 注意事项
+
+1. **沙箱收银接口**：脚本默认使用 `http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay`，此地址已硬编码在脚本中
+2. **付款链接**：前缀为 `https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema=`，通过 URL 编码的 `payScheme` 拼接
+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` 到网页浏览器打开，并使用支付宝客户端扫码下载沙箱版支付宝安装包
+
+---
+
+## 脚本内部流程概要
+
+```
+用户服务 (无 Payment-Proof)
+    ↓ HTTP 402 + Payment-Needed (base64 JSON)
+脚本提取并解码
+    ↓ snake_case → camelCase + 补充买家ID
+沙箱收银接口
+    ↓ payScheme
+浏览器付款链接
+    ↓ 用户扫码/登录付款
+脚本构建 Payment-Proof
+    ↓ base64(protocol + method)
+重试用户服务
+    ↓ HTTP 200 + 资源内容
+验证通过 ✅
+```

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

@@ -0,0 +1,133 @@
+# Alipay Sandbox Tool
+
+提供沙箱能力：**创建快速沙箱**。
+
+## 1. 环境检测
+
+> ⚠️ **前置要求**：在调用沙箱工具前，必须先按 `../../../normal/alipay-cli-env.md` 完成 alipay-cli 检测与安装
+
+```bash
+which alipay-cli 2>/dev/null && alipay-cli version
+```
+
+> 📎 详细检测、安装、验证流程及环境检测结果不透出规范见 `../../../normal/alipay-cli-env.md`
+
+## 2. 创建快速沙箱
+
+**重要：输出时必须完整展示所有字段，不允许省略 privateKey、publicKey 等长字段。如果输出被截断，需按 `sandbox-setup-guide.md` 的表格格式重新输出完整字段。**
+
+`createAnonymousSandbox` 的 MCP 请求体只有业务入参 `request.appType`。`PLATFORM`、`PRODUCT` 是 alipay-cli 上下文环境变量，禁止写入 `--data` 的 JSON。
+
+```bash
+PLATFORM="<PLATFORM>" \
+PRODUCT="<PRODUCT>" \
+alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
+  --data '{"request":{"appType":"<APP_TYPE>"}}' \
+  --json
+```
+
+**参数推断：**
+
+| 用户关键词 | appType |
+|------|------|
+| 网页应用、移动应用、按量付费 | PUBLICAPP |
+
+**上下文变量：**
+
+| 变量 | 来源 | 取值规则 |
+|------|------|----------|
+| `PLATFORM` | AI 编程工具识别结果 | 参考通用脚本 `../../../normal/scripts/detect_dev_tool.sh` 识别当前工具后使用其输出值；缺失时使用 `unknown`。例如 Codex 环境检测结果为 `codex` |
+| `PRODUCT` | 当前 Skill 产品名称 | `按量付费` / `网站支付` / `APP支付`。用户说“手机网站支付”“H5支付”“PC网页支付”时，按本 Skill 术语归一为 `网站支付` |
+
+> `PRODUCT` 不是 `createAnonymousSandbox` 的 MCP 请求体字段，仅作为 alipay-cli 上下文变量传入。Skill 内按产品决策结果归一为上表中的产品名。
+
+**Codex 环境示例：**
+
+```bash
+PLATFORM=codex \
+PRODUCT="网站支付" \
+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. `success !== true` → 按错误处理流程
+
+## 3. 错误处理
+
+CLI 输出不暴露 HTTP 状态码，统一按响应体中的 `success` 字段判断：
+
+| 条件 | 策略 |
+|------|------|
+| `success === false` 且 `msg` 含"证书密钥"等临时错误 | 静默等待 2 秒后自动重试 1 次，仍失败则展示 `errorCode`、`msg`/`resultMsg`、`traceId` |
+| `success === false` 且 `msg` 含"版本过旧"或 CLI 退出码非 0 | 不重试，友好提示"服务不可用，可能是 CLI 版本过旧"，询问用户是否升级 CLI |
+| CLI 执行超时或网络错误 | 最多重试 2 次 |
+
+所有失败均提取 traceId 展示给用户。
+
+## 4. 注意事项
+
+- 执行前向用户展示即将运行的命令
+- 参数不确定时先向用户确认
+  
+## 返回示例
+
+### 成功示例
+
+```json
+{
+  "appIds": [
+    {
+      "alipayPublicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
+      "appId": "9021000162691374",
+      "appPrivateKey": "MIIEvQIBADANBgkqhkiG9w0BAQEFAASC...",
+      "appPrivatePkcsKey": "MIIEpAIBAAKCAQEA...",
+      "appPublicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
+      "pid": "2088721100529696",
+      "type": null,
+      "uid": null
+    }
+  ],
+  "isClaimed": false,
+  "sandboxAccounts": {
+    "partner": {
+      "accountDesc": "商家账号",
+      "acctrans": "1000000.00",
+      "email": "xxxxx@sandbox.com",
+      "merchantId": "221187076",
+      "userId": "2088721100529696"
+    },
+    "user": {
+      "accountDesc": "买家账号",
+      "acctrans": "1000000.00",
+      "email": "xxxxx@sandbox.com",
+      "userName": "xxxxx",
+      "userId": "2088722100508485",
+      "logonPassword": "111111",
+      "payPassword": "111111",
+      "certNo": "195109197300184083",
+      "certType": "IDENTITY_CARD"
+    }
+  },
+  "sandboxId": "al1458801837b7495b",
+  "sandboxName": "匿名沙箱-al1458801837b7495b"
+}
+```
+
+### 错误示例
+
+```json
+{
+  "data": null,
+  "errorCode": null,
+  "msg": "查询沙箱证书密钥信息失败",
+  "resultCode": null,
+  "resultMsg": null,
+  "success": false,
+  "traceId": "218f563417783158778985995e4b5d"
+}
+```

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

@@ -0,0 +1,218 @@
+# 沙箱环境初始化指南
+
+本文档是沙箱环境配置的**单一可信来源**。
+
+---
+
+## 1. 环境说明
+
+### 1.1 快速沙箱优势
+- ✅ **零配置启动**：无需登录支付宝开放平台，自动获取测试账号与密钥
+- ✅ **即开即用**：全自动配置网关及应用信息
+- ✅ **安全隔离**：测试环境不涉及真实资金，可放心调试
+
+### 1.2 Windows 用户注意事项
+**快速沙箱 CLI 工具暂不支持 Windows 系统**。
+
+Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用 自行获取沙箱信息。
+
+### 1.3 其他说明
+沙箱环境暂不支持用户主动通过看板查看测试账号的交易信息（如：卖家余额、交易状态等）。**严禁**引导用户访问所谓的“支付宝沙箱网页版”查看测试账户的余额变动等。
+
+---
+
+## 2. 密钥格式说明
+
+| 语言 | 私钥格式 | 使用字段 |
+|------|----------|----------|
+| Java | PKCS#8 | `appPrivateKey` |
+| 非 Java（Python、Node.js、PHP、.NET 等） | PKCS#1 | `appPrivatePkcsKey` |
+
+**⚠️ 防误判提醒**：
+- 沙箱配置直接使用沙箱返回的对应私钥字段；生产配置必须确认应用私钥格式与项目语言匹配
+- 写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、其他前后缀、包装行或说明文字
+- 生产应用私钥格式与当前语言 SDK 要求不一致时，使用支付宝开放平台密钥工具做私钥格式转换后再配置
+- 禁止因 `ERR_OSSL_UNSUPPORTED` 推断私钥格式有问题（通常是 SDK 配置参数错误）
+- 详见 [SDK 说明文档 - 私钥格式](../alipay-sdk-reminder.md)
+
+---
+
+## 3. 配置流程
+
+### 3.1 调用工具创建环境
+
+参考 [alipay-sandbox-tool](alipay-sandbox-tool.md) 创建快速沙箱环境。
+
+**异常处理**：创建失败时提示 "❌ 快速沙箱创建失败，请稍后重试"。
+
+### 3.2 沙箱信息输出格式
+
+**必须按以下表格格式**输出，**严禁**使用 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` | {实际返回值} |
+
+---
+
+## 4. 强校验规则（卡点）
+
+工具返回环境信息后，**必须执行逐项强校验**，校验通过方可进入后续步骤。未通过则**阻断流程**，要求重新创建。
+
+### 4.1 必含字段清单
+
+以下字段必须全部存在且非空：
+
+| 字段 | 说明 |
+|---|---|
+| `appId` | 沙箱应用 ID |
+| `appPrivateKey` / `appPrivatePkcsKey` | 应用私钥（Java 使用 `appPrivateKey`，非 Java 使用 `appPrivatePkcsKey`） |
+| `alipayPublicKey` | 支付宝公钥 |
+| `appPublicKey` | 应用公钥 |
+| 商家账号 | 沙箱商家登录账号 |
+| 买家账号 | 沙箱买家测试账号 |
+
+### 4.2 绝对禁止（红线）
+
+**以下行为严格禁止：**
+
+1. **禁止编造字段** —— 不得生成、拼接、模拟、猜测缺失的字段值
+2. **禁止用占位符冒充真实数据** —— 当沙箱成功返回完整配置时，禁止用占位符代替真实返回值
+3. **禁止假数据** —— 不得自行生成示例私钥、示例账号等任何假数据
+4. **禁止假设存在** —— 不得假设"工具返回的应该都有"而不逐项检查
+5. **禁止部分通过** —— 不得因"只有 1 个字段缺失"而继续执行
+6. **禁止跳过校验** —— 不得在未完成逐项校验的情况下直接使用返回结果
+
+### 4.3 校验执行清单
+
+**规则：** 任一字段缺失 → **立即停止** → 输出错误提示 → **禁止继续**
+
+```
+□ 检查 appId
+  IF 缺失：输出 "❌ 沙箱环境校验失败：appId 为空，无法继续集成，请重新创建沙箱环境。" → STOP
+
+□ 检查应用私钥（根据语言选择）
+  - Java：检查 `appPrivateKey`（PKCS#8）
+  - 非 Java：检查 `appPrivatePkcsKey`（PKCS#1）
+  IF 缺失：输出 "❌ 沙箱环境校验失败：应用私钥字段为空，无法继续集成，请重新创建沙箱环境。" → STOP
+
+□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号
+  IF 任一缺失：输出对应字段缺失错误 → STOP
+
+□ 全部通过 → 输出 "✅ 沙箱环境校验通过"
+```
+
+### 4.3.1 配置写入后的后置校验
+
+后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先重新复制沙箱字段或修正 SDK 配置。必须确认以下目标：
+
+- 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置，且与沙箱返回配置一致。
+- 确认应用私钥不是占位符、示例值或其他来源的密钥，未出现复制截断或粘贴污染。
+- 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
+- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字。
+- 校验输出不得包含私钥、公钥、签名串或完整支付表单。
+
+**常见失败处理：**
+- 私钥不完整、配置不一致或 SDK 初始化/解析失败：重新复制完整私钥字段，禁止补字符、猜测或格式转换。
+- `DECODER routines::unsupported`：优先检查私钥是否复制完整、是否错误添加 PEM 头尾或其他前后缀、`keyType` 是否错误，不要切换成 PKCS#8 试错。
+
+### 4.4 重试与失败处理
+
+| 失败场景 | 处理策略 |
+|---------|---------|
+| 首次失败 | 提示 "❌ 快速沙箱创建失败，请稍后重试"，等待用户指示后重试 |
+| 字段缺失 | 明确告知**具体缺失字段名称**，禁止只说"部分字段缺失" |
+| 反复失败（≥2次） | 输出强提醒，提供两个选项：①重新输入指令 ②自行申领沙箱应用，禁止继续自动重试 |
+| 用户提供手动配置 | 仍需按「校验执行清单」逐项校验，通过后方可继续 |
+
+**反复失败提示模板**：
+```
+🚨 快速沙箱环境多次创建失败/字段不完整
+
+缺失字段：[列出具体缺失的字段名称]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+请您选择以下方式之一解决：
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+【选项一】重新输入创建快速沙箱指令
+  操作方式：在对话中重新输入"创建快速沙箱"或类似指令
+  适用场景：可能因服务波动导致创建失败，稍后重试可能成功
+
+【选项二】自行申领沙箱应用
+  操作方式：前往支付宝开放平台（https://open.alipay.com）手动申领沙箱应用
+  适用场景：需要使用自己的沙箱账号，获取 appId、应用私钥、支付宝公钥等信息后手动配置
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ 在配置完整之前，无法继续集成流程。
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## 5. 成功创建后提示（卡点）
+
+**⛔ 强制要求：校验通过后，必须在回复中完整输出以下内容。**
+
+- **禁止省略**：不得跳过、缩减
+- **禁止改写**：必须按原文输出
+- **未输出此提示即继续 = 违规**
+
+```
+⚠️ 快速沙箱环境已创建完成
+
+📌 环境说明
+- 当前快速沙箱环境仅供测试，不涉及真实资金
+- 完整展示沙箱信息，无需对内容脱敏
+- 切勿在项目日志中打印私钥信息
+- 切勿提交正式环境、沙箱环境信息至公共代码仓库（GitHub、GitLab 等）
+
+🔔 必做操作
+- 请自行妥善保管密钥及测试账号等信息
+
+🔒 安全提醒
+- 正式上线前请确保您已拥有正式的应用 appId、经过审核的应用私钥及支付宝公钥，并切换至正式环境重新配置密钥
+- 替换生产配置或启动生产支付测试前，确认 `appId`、应用公钥、应用私钥属于同一套生产应用密钥，并根据项目语言确认私钥格式正确；格式不匹配时使用支付宝开放平台密钥工具转换
+- 正式环境网关地址：https://openapi.alipay.com/gateway.do
+- 正式环境涉及真实资金交易，强烈建议在正式上线之前在沙箱环境中完成全链路测试
+```
+
+**输出检查：** 确认包含 ⚠️📌🔔🔒 四个标记及全部内容后，方可继续后续集成步骤。