@alipay/alipay-aipay 1.2.2 → 1.4.9

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

@@ -1,6 +1,6 @@
 # 沙箱环境初始化指南
 
-本文档是沙箱环境配置的**单一可信来源**。
+本文档是沙箱环境配置的**单一可信来源**。运行时 Agent 在 Unix/macOS/Linux 只执行 integration flow 登记的 `sandbox_config.sh ensure|reverify|verify|summary`；本文档中的字段表和处理顺序是脚本维护契约，不授权 Agent 对 `.alipay-sandbox.json` 运行临时 `jq`、`cat`、`grep`、`ls`、`stat` 或另写解析脚本。
 
 ---
 
@@ -14,7 +14,11 @@
 ### 1.2 Windows 用户注意事项
 **快速沙箱 CLI 工具暂不支持 Windows 系统**。
 
-Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控制台 - 沙箱应用，自行获取沙箱信息。
+Windows 普通代码开发或完整接入请求未明确要求当前配置沙箱时，记录 `sandboxConfigState=VERIFY_PENDING` 并继续代码实现，不展示资料收集消息。只有用户明确要求现在配置或恢复 Windows 沙箱时，才使用 `../../../normal/json/customer-messages.json` 的既有 `sandbox.windows.manual_setup`，引导用户前往支付宝 AI 付站点的“选择产品 → 一站式接入 → 技术集成”页面获取当前沙箱的 APPID、公私钥和账号信息；随后只处理用户针对本轮该消息提供的资料，完整时校验并写入目标项目实际使用的本地敏感配置，部分或错误时只补问对应字段。不得要求用户自行配置、理解 `sandbox_config.sh`、执行 Bash 或手工拼接 Skill 的规范化 JSON。该资料输入例外只适用于沙箱，生产环境应用私钥和密码禁止提供给 Agent；Agent 不得在回复、摘要或普通日志中复述收到的值。
+
+```bash
+node ../../../normal/scripts/integration_message_runner.mjs windows-sandbox-setup
+```
 
 ### 1.3 其他说明
 沙箱环境暂不支持用户主动通过看板查看测试账号的交易信息（如：卖家余额、交易状态等）。**严禁**引导用户访问所谓的“支付宝沙箱网页版”查看测试账户的余额变动等。
@@ -41,30 +45,41 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 ### 3.1 获取候选沙箱配置
 
-- Unix/macOS/Linux：参考 [alipay-sandbox-tool](alipay-sandbox-tool.md) 调用快速沙箱工具。
-- Windows：快速沙箱 CLI 工具暂不支持，按第 1.2 节引导用户自行获取沙箱信息。
+- Unix/macOS/Linux：运行时只执行 integration flow 的 `sandbox_config.sh ensure`；[alipay-sandbox-tool](alipay-sandbox-tool.md) 只记录脚本内部冻结的 MCP 契约和维护依据，不作为 Agent 直调入口。
+- Windows：快速沙箱 CLI 工具暂不支持，按第 1.2 节记录 `READY|VERIFY_PENDING`；该分支不调用 `sandbox_config.sh create|verify`，也不伪造 `FLOW:SANDBOX_CONFIGURED`。
 - 工具返回 `success === true` 只代表拿到候选 `data`；必须完成第 4 节字段完整性校验后，才允许写入正式配置文件。
-- `success !== true`、`data` 缺失或字段不完整时，按第 6 节失败处理阻断流程。
+- `success !== true`、`data` 缺失或字段不完整时，先执行第 6 节既定重试；耗尽后进入本轮待配置状态，只阻断沙箱字段使用、摘要、配置校验和沙箱测试，不阻断代码实现。
+
+### 3.2 脚本内部固定处理顺序
 
-### 3.2 固定处理顺序
+Unix/macOS/Linux 快速沙箱由 `sandbox_config.sh` 在内部完成以下动作，运行时 Agent 不逐项重做：
 
 1. 提取候选 `data`。
 2. 按第 4 节逐项校验必含字段。
 3. 校验通过后，将候选 `data` 按原始 JSON 结构写入正式本地配置文件。
-4. 输出第 5 节规定的关键字段摘要和实际配置文件路径。
-5. 后续写入项目 `.env` 或 SDK 配置时，统一从该本地 JSON 文件读取并映射，避免在对话中复述密钥等长字段。
+4. 确认配置未被 Git 跟踪、项目根目录 `.gitignore` 已包含 `/.alipay-sandbox.json` 且文件权限为 `0600`，创建阶段只通过带 `ALIPAY_AIPAY_INTERNAL:` 前缀的 stderr 内部事实返回机器标记和实际配置文件路径，不对客展示关键字段摘要。
+5. 后续由商家服务端代码使用当前语言标准 JSON 解析器在运行时读取该文件并映射到 SDK；Agent 不通过 shell 输出字段原文，也不把沙箱密钥复制到源码或重复写入 `.env`。
+6. 代码开发完成且配置后置校验通过后，再使用第 5.2 节的摘要输出入口对客展示沙箱环境配置。
 
-校验和落盘可使用 Agent 的结构化 JSON 处理能力、Node.js/Python 标准库或其他可用工具实现，不强依赖 `jq`。
+Windows 手工沙箱：
+
+1. 没有资料且没有明确配置请求时记录 `VERIFY_PENDING` 并继续代码实现，不渲染消息、不探测猜测配置。
+2. 用户明确要求配置且尚未提供资料时，才使用标准消息一次收集当前沙箱应用的 APPID、支付宝公钥、应用公钥、与已确认语言匹配的应用私钥和沙箱账号信息；缺失或校验失败时只补问对应字段。
+3. 按第 4 节校验资料，随后由 Agent 写入目标项目实际使用的本地敏感配置；不要求采用快速沙箱 `data` 的嵌套结构，不把值复制到源码或普通日志。
+4. 检查敏感配置未被 Git 跟踪，并已有适用于实际路径的版本控制忽略保护；能检查 Windows 文件访问控制时确认仅当前用户可访问，不能取得证据时标记为人工待验证。
+5. 只有 `READY` 时才输出第 5 节规定的摘要和 Windows 提醒并从实际本机配置映射到 SDK；Agent 不得在回复或摘要中复述用户提供的沙箱密钥和密码，生产环境应用私钥和密码禁止提供给 Agent。
+
+Unix/macOS/Linux 快速沙箱的流程准备必须使用 integration flow 登记的 `sandbox_config.sh ensure` 入口：配置缺失时脚本内部创建，已存在时脚本内部复核；步骤 3 仅在首次准备为 `READY` 时执行 `reverify`，待配置时直接继续代码开发；代码开发完成且配置仍为 `READY` 后才使用 `summary` 展示摘要。`ensure|reverify` 会把既定重试耗尽转换为受控 `CREATE_PENDING|VERIFY_PENDING`，直接渲染统一消息并返回终态标记；Agent 不得直接选择创建分支、重复检查文件存在性或权限、读取字段结构、拼接沙箱 JSON、另写解析逻辑或自制摘要表。Windows 手工申领分支检查目标项目实际读取的本地配置，不把平台字段擅自改造成快速沙箱返回结构。
 
 ---
 
-## 4. 字段完整性校验（卡点）
+## 4. 字段完整性校验契约（脚本内部卡点）
 
-工具返回环境信息后，必须先逐项校验。任一必含字段缺失或为空时，立即停止，不得写入正式 `.alipay-sandbox.json`，并明确告知具体缺失字段。
+Unix/macOS/Linux 由 `sandbox_config.sh` 内部逐项校验，Agent 只消费退出码和 flow 登记标记，不手工执行本节清单。Windows 没有该脚本能力时，才按目标项目实际配置逐项检查。任一必含字段缺失或为空时立即停止使用当前候选：Unix/macOS/Linux 不得写入正式 `.alipay-sandbox.json`，Windows 不得把当前本机配置标记为可用；Unix/macOS/Linux 按有限重试和待配置终态继续代码实现，Windows 仍使用登记的资料补充出口。
 
 ### 4.1 必含字段清单
 
-以下字段必须按项目语言和测试账号要求存在且非空：
+以下是两条分支共同的语义要求，必须按项目语言和测试账号要求存在且非空。Unix/macOS/Linux 快速沙箱按表中的原始字段名检查；Windows 按目标项目实际配置的等价字段检查，不得为了通过校验擅自改造为快速沙箱嵌套结构：
 
 | 字段 | 说明 |
 |---|---|
@@ -73,27 +88,28 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 | `alipayPublicKey` | 支付宝公钥 |
 | `appPublicKey` | 应用公钥 |
 | 商家账号 | 沙箱商家登录账号 |
-| 买家账号 | 沙箱买家测试账号 |
+| 买家账号 `userId` | 沙箱买家用户 ID |
+| 买家账号 `email` | 沙箱买家登录账号 |
 | 买家账号 `logonPassword` | 沙箱买家登录密码 |
 | 买家账号 `payPassword` | 沙箱买家支付密码 |
 
-### 4.2 校验执行清单
+### 4.2 脚本维护校验清单
 
-**规则：** 任一字段缺失 → **立即停止** → 输出错误提示 → **禁止继续**
+**规则：** 任一字段缺失 → 停止使用当前候选或已有配置 → 执行有限重试 → 仍失败则记录待配置并继续代码实现；禁止继续任何沙箱依赖动作
 
 ```
 □ 检查 appId
-  IF 缺失：输出 "❌ 沙箱环境校验失败：appId 为空，无法继续集成，请重新创建沙箱环境。" → STOP
+  IF 缺失：当前校验失败 → RETRY_OR_PENDING
 
 □ 检查应用私钥（根据语言选择）
   - Java：检查 `appPrivateKey`（PKCS#8）
   - 非 Java：检查 `appPrivatePkcsKey`（PKCS#1）
-  IF 缺失：输出 "❌ 沙箱环境校验失败：应用私钥字段为空，无法继续集成，请重新创建沙箱环境。" → STOP
+  IF 缺失：当前校验失败 → RETRY_OR_PENDING
 
-□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号 / 买家账号 logonPassword / 买家账号 payPassword
-  IF 任一缺失：输出对应字段缺失错误 → STOP
+□ 检查 alipayPublicKey / appPublicKey / 商家账号 / 买家账号 userId / 买家登录账号 email / 买家账号 logonPassword / 买家账号 payPassword
+  IF 任一缺失：当前校验失败 → RETRY_OR_PENDING
 
-□ 全部通过 → 不对客输出字段核对表、字段列表、独立的“字段完整性校验通过”提示或任何“沙箱测试通过”表述；直接进入落盘，并按第 5.2 节只输出一张沙箱环境摘要表。
+□ 全部通过 → 不对客输出字段核对表、字段列表、独立的“字段完整性校验通过”提示或任何“沙箱测试通过”表述；创建阶段直接进入安全落盘，机器标记和实际本机配置路径只写入带统一前缀的内部事实。代码开发完成且配置后置校验通过后，才按第 5.2 节只输出一张沙箱环境摘要表。
 ```
 
 ---
@@ -102,91 +118,65 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 ### 5.1 本地配置文件
 
-- 默认写入已确认的目标项目根目录 `.alipay-sandbox.json`；若该目标目录不适合写入，则写入系统临时目录 `alipay-sandbox-<timestamp>.json`，不得改写到 Agent 原始工作目录或其他项目。
+Unix/macOS/Linux 快速沙箱：
+
+- 固定写入已确认的目标项目根目录 `.alipay-sandbox.json`。目标目录不可写、`.gitignore` 不是安全普通文件或无法建立 Git 忽略保护时不得落盘或使用当前配置；`ensure|reverify` 将其记录为待配置并继续代码实现，不降级写入系统临时目录、Agent 原始工作目录或其他项目。
 - JSON 文件必须保留沙箱返回的原始字段名和嵌套结构，不要转换成 `.env` 扁平键值。
-- 文件权限应尽量限制为当前用户可读写，例如 `chmod 600`。
-- 配置落盘后，必须在对话中输出实际路径。路径必须可定位，例如 `/path/to/project/.alipay-sandbox.json` 或 `./.alipay-sandbox.json`。
+- 文件权限必须限制为当前用户可读写，即 `chmod 600`；权限收紧或复核失败时不得使用配置或执行沙箱依赖动作。
+- 配置不得已被 Git 跟踪；项目根目录 `.gitignore` 必须包含精确规则 `/.alipay-sandbox.json`。脚本只在缺失时追加一次，不覆盖既有内容；`.gitignore` 为符号链接或非普通文件时停止。
+
+Windows 手工沙箱：
+
+- 由 Agent 根据目标项目实际结构选择并写入本机敏感配置路径，不要求用户创建 `.alipay-sandbox.json` 或自行配置项目。
+- 配置必须未被 Git 跟踪，并建立适用于该实际路径的忽略保护；不得因为 Windows 不使用 POSIX `0600` 而声称完成了该权限检查。
+- 只有实际检查到的字段才能进入后续 SDK 映射；无法自动核验的 Windows 文件访问控制或平台页面信息必须标记为人工待验证。
+
+Unix/macOS/Linux 创建阶段把实际本机配置路径和 `FLOW:SANDBOX_CONFIG_READY` 作为带 `ALIPAY_AIPAY_INTERNAL:` 前缀的 stderr 内部事实，stdout 为空；不展示账号、密码、公钥或摘要。Windows 手工分支完成后只在内部保留实际本机配置路径。两条分支在代码开发完成且配置后置校验通过后，才进入摘要展示。
 
 ### 5.2 对话摘要
 
-字段无缺失并完成落盘后，对客只用下方一张表展示沙箱信息，不再展示字段核对表、已校验字段列表或独立的校验结论。表中包含本地配置文件路径、关键标识，以及工具实际返回的沙箱测试账号登录密码和支付密码；密钥、完整签名串和完整支付表单等长字段不得展开。账号没有返回某一可选字段时省略对应内容，禁止编造。
+代码开发完成且配置后置校验通过后，Unix/macOS/Linux 从本文件所在的 `references/integration/modules/sandbox/` 目录使用 `bash ../scripts/sandbox_config.sh summary "<productType>" "<规范化项目路径>" "<已确认服务端语言>"` 复核并展示摘要；该脚本内部负责渲染 `sandbox.environment.summary` 与 `sandbox.environment.reminder`，Agent 不得绕过脚本自写摘要。Windows 使用同一消息目录从项目实际读取的本机配置生成摘要，执行：
 
+```powershell
+node ../../../normal/scripts/integration_message_runner.mjs windows-sandbox-summary --product-name "$PRODUCT_NAME" --config-path "$CONFIG_PATH" --environment-rows "$ENVIRONMENT_ROWS"
 ```
-沙箱环境摘要
 
-| 信息 | 内容 |
-|---|---|
-| 配置文件 | `<本地配置文件路径>` |
-| 应用 | `appId=<appId>[, pid=<pid，如有>]` |
-| 商家账号 | `email=<email，如有>, userId=<userId，如有>[, 登录密码=<logonPassword，如有>][, 支付密码=<payPassword，如有>]` |
-| 买家账号 | `email=<email，如有>, userId=<userId，如有>, 登录密码=<logonPassword>, 支付密码=<payPassword>` |
-| 沙箱 | `sandboxId=<sandboxId，如有>, sandboxName=<sandboxName，如有>` |
-| 密钥字段 | `appPrivateKey/appPrivatePkcsKey/alipayPublicKey/appPublicKey` 已写入本地配置文件，默认不在对话中展开 |
-```
+摘要行按当前分支的实际来源依次包含应用 `appId/pid`、商家账号、买家账号及沙箱标识；账号未返回的可选字段直接省略，禁止编造。只有 Unix/macOS/Linux 快速沙箱工具实际返回且已校验的沙箱登录密码和支付密码可以进入摘要行；Windows 手工沙箱虽然允许用户在资料收集时提供当前沙箱密码，Agent 仍不得在摘要或后续回复中复述，只展示非敏感标识和本机保存提示。两类例外都不得扩展到生产环境账号、私钥或密码。
 
-这张表表示沙箱配置字段完整且已经落盘，不表示支付链路已经测试。禁止把表名、前后提示或后续总结改写为“沙箱环境校验通过”“沙箱测试通过”“沙箱环境测试通过”等结论。
+renderer 固定输出唯一摘要表、密钥字段已落盘提示和“配置不等于测试通过”的边界。禁止另写字段核对表、独立校验结论，或把表名、前后提示改成“沙箱环境校验通过”“沙箱测试通过”“沙箱环境测试通过”。
 
-### 5.3 成功创建后提示（卡点）
+### 5.3 配置准备完成后提示（卡点）
 
-输出第 5.2 节摘要后，必须继续输出以下成功提示。提示可以和摘要连续输出，但不得省略关键提醒。
+输出 `sandbox.environment.summary` 后立即渲染 `sandbox.environment.reminder`：Unix/macOS/Linux 快速沙箱由 `sandbox_config.sh summary` 内部使用 `DEFAULT`；Windows 手工沙箱执行上方 `WINDOWS` 命令。该消息统一维护测试资金边界、本地文件与仓库安全、同一套生产密钥、私钥格式、沙箱/生产网关和按量付费 `api_mock_service_id` 替换提醒；不得在本文件或 Agent 回复中维护第二份近似话术。创建阶段不得提前渲染本提醒。
 
-```
-⚠️ 快速沙箱环境已创建完成
-
-📌 环境说明
-- 当前快速沙箱环境仅供测试，不涉及真实资金
-- 完整沙箱信息已写入本地配置文件；对话中展示工具实际返回的沙箱测试账号登录密码和支付密码，以便完成沙箱付款，不展开私钥、公钥、完整签名串或完整支付表单等长字段
-- 切勿在项目日志、对话总结或测试结果中打印私钥信息
-- 切勿提交正式环境、沙箱环境信息至公共代码仓库（GitHub、GitLab 等）
-
-🔔 必做操作
-- 请自行妥善保管本地配置文件、密钥及测试账号等信息
-- 若需要迁移配置，请从本地配置文件复制，避免通过对话记录传递密钥等完整长字段
-
-🔒 安全提醒
-- 正式上线前请确保您已拥有正式应用的 appId、对应的应用私钥及支付宝公钥，并确认应用和支付产品已达到上线所需状态后切换至正式环境
-- 替换生产配置或启动生产支付测试前，确认 `appId`、应用公钥、应用私钥属于同一套生产应用密钥，并根据项目语言确认私钥格式正确；格式不匹配时使用支付宝开放平台密钥工具转换
-- 正式环境网关地址：https://openapi.alipay.com/gateway.do
-- 正式环境涉及真实资金交易，正式上线前应在沙箱环境完成所有可验证的支付链路；受本地网络条件限制的项目必须另行标记和验证
-```
-
-### 5.4 网站支付沙箱付款提示（代码生成后、集成收尾前）
+### 5.4 沙箱对客展示白名单
 
-网站支付代码生成和配置后置校验完成后，先从已确认的目标项目脚本、路由和运行配置中确定真实的服务启动命令和支付页面访问地址，再按回跳分支处理：
+沙箱字段只能按下表进入对客消息；表外字段只能用于本机配置、SDK 初始化或内部校验，不得由 Agent 手写输出。
 
-- **默认分支**：用户未明确关闭同步回跳时，确认 SDK 实际使用的 `return_url`。启动服务并 GET 访问不带支付结果参数的该地址，只验证路由和页面壳；无订单上下文时应展示安全的中性状态，不得放宽真实回跳请求的验签和订单归属校验。确认无 404、认证或重定向循环，且单页应用直接刷新可用。
-- **渲染验证**：Agent 具备浏览器/UI 能力时，打开回跳页确认非空白、无可见报错且关键内容正常渲染；不具备时，请用户打开精确地址确认。未取得证据时不得宣称回跳页已验证或网站支付集成完成。
-- **关闭分支**：用户已明确关闭同步回跳时，不要求或猜测 `return_url`；确认 SDK 请求未传该字段，并验证异步通知、交易查询和商户订单查询页。
+| 场景 | 可对客展示 | 禁止对客展示 |
+|---|---|---|
+| Unix/macOS/Linux 快速沙箱摘要 | `sandbox_config.sh summary` 实际渲染的应用 `appId/pid`、商家 `userId`、买家 `userId/email/logonPassword/payPassword`、`sandboxId`、配置文件目录 | `appPrivateKey`、`appPrivatePkcsKey`、`alipayPublicKey`、`appPublicKey`、原始 `.alipay-sandbox.json`、完整 MCP 响应 |
+| Unix/macOS/Linux 网站支付付款体验 | 已校验的沙箱买家登录账号、登录密码、支付密码，以及实际支付页面地址和启动命令 | 商家密码、任何公钥/私钥原文、完整支付表单、签名串 |
+| Windows 手工沙箱 | 配置文件目录、非敏感应用/账号标识、官方控制台获取与本机配置完成提示 | 用户提供的应用私钥、支付宝公钥、应用公钥、沙箱账号密码原文 |
+| 按量付费自动联调 | 受控结论、付款链接和沙箱买家可选体验入口 | `Payment-Proof`、`Payment-Validation` 原文、完整收银请求、临时产物路径中的敏感内容 |
 
-完成对应分支校验后，使用本次已校验沙箱配置中的真实买家账号输出以下提示。不得使用示例端口、占位 URL 或猜测地址；启动命令、支付页面访问地址或账号字段无法确定时，指出缺失项并标记为人工待补充。下方尖括号仅是模板槽位，对客输出时必须替换为真实值；缺少真实值时删除对应占位内容并说明缺失项。
+只有 `sandboxCredential` 类型变量可以承载快速沙箱买家登录密码和支付密码；该例外不适用于生产账号、生产密码、应用私钥、公钥、token、签名串或 Payment-Proof。
 
-`curl` 调用下单接口并取得 HTML 支付表单只属于接口冒烟检查，不能替代用户付款指引，也不能据此标记步骤 5 完成。必须提供用户可在浏览器中打开的支付页面地址；页面打开沙箱收银台后，以下两种体验方式同时告知用户，由用户自行二选一。
+### 5.5 网站支付沙箱付款提示（代码生成后、集成收尾前）
 
-```text
-🧪 网站支付沙箱付款指引
+网站支付代码生成和配置后置校验完成后，先从已确认的目标项目脚本、路由和运行配置中确定真实的服务启动命令和支付页面访问地址，再按回跳分支处理：
 
-网站支付已接入沙箱环境，可以发起一笔测试付款：
-1. 启动服务并保持运行：`<从目标项目确定的真实启动命令>`
-2. 使用浏览器访问支付页面：`<从目标项目确定的真实访问地址>`
-3. 在页面中发起支付，确认页面成功唤起支付宝沙箱收银台。
+- **默认分支**：用户未明确关闭同步回跳时，确认 SDK 实际使用的 `return_url`。启动服务并 GET 访问不带支付结果参数的该地址，只验证路由和页面壳；无订单上下文时应展示安全的中性状态，不得放宽真实回跳请求的验签和订单归属校验。确认无 404、认证或重定向循环，且单页应用直接刷新可用；当前 Agent 具备浏览器/UI 能力时验证页面正常渲染，否则只记录 UI 人工待验证，不追加用户确认。
+- **渲染验证**：Agent 具备浏览器/UI 能力时，打开回跳页确认非空白、无可见报错且关键内容正常渲染；不具备时，请用户打开精确地址确认。未取得证据时不得宣称回跳页已验证或网站支付代码开发完成。
+- **关闭分支**：用户已明确表示不使用同步回跳时，不要求或猜测 `return_url`；确认 SDK 请求未传该字段，并验证异步通知、交易查询和商户订单查询页。用户未明确关闭时，缺少 `return_url` 必须修复为默认同步回跳分支。
 
-付款方式（二选一）：
+完成对应分支校验后按系统渲染：Unix/macOS/Linux 快速沙箱使用 `webpay.sandbox.experience`，传入工具实际返回并已校验的买家账号、登录密码、支付密码、项目启动命令、浏览器支付页面地址和当前回跳分支说明；Windows 手工沙箱使用 `webpay.sandbox.experience.windows`，只传启动命令、浏览器支付页面地址和回跳分支说明，密码由用户从已保存的本机配置或支付宝开放平台控制台取得，Agent 不在付款指引中复述。不得使用示例端口、占位 URL 或猜测地址；任一必需值无法确定时不渲染半模板，指出缺失项并标记为人工待补充。
 
-方式一：收银台账号登录
-4. 在沙箱收银台使用以下沙箱买家账号和登录密码登录，无需使用真实支付宝账号：
-   - 买家账号：<email>
-   - 登录密码：<logonPassword>
-5. 登录后输入沙箱支付密码完成核身与付款：
-   - 支付密码：<payPassword>
+`curl` 调用下单接口并取得 HTML 支付表单只属于接口冒烟检查，不能替代用户付款指引，也不能据此标记步骤 6 完成。必须提供用户可在浏览器中打开的支付页面地址；页面打开沙箱收银台后，以下两种体验方式同时告知用户，由用户自行二选一。
 
-方式二：安卓沙箱支付宝扫码
-4. 沙箱支付宝仅支持 Android。复制以下官方地址到网页浏览器打开，按页面指引安装沙箱支付宝：
-   https://mdn.alipayobjects.com/sandboxsys/afts/img/_itHRrdOD9oAAAAAAAAAAAAADgSLAQBr/original
-5. 在沙箱支付宝中使用上述沙箱买家账号和登录密码登录。
-6. 返回浏览器中的沙箱收银台，使用沙箱支付宝扫描页面二维码，再输入上述沙箱支付密码完成付款。
-```
+紧接当前系统对应的网站支付付款指引渲染 `sandbox.android.client`，统一输出 Android-only、官方直链、直链/页面二维码失败后的开放平台沙箱工具页，以及禁止 iOS、应用市场、第三方站点和自编 URL 的口径。
 
-紧接上述步骤追加结果判断，必须按实际回跳分支二选一，禁止同时输出两项：
+`resultPageInstruction` 必须按实际回跳分支二选一，禁止同时输出两项：
 
 - **默认分支**：“付款后确认浏览器自动返回商户结果页，页面可正常展示并通过服务端查询呈现订单状态。”
 - **关闭分支**：“付款后不会自动返回商户网站；请手动返回商户订单查询页并刷新或查询订单状态。”
@@ -207,52 +197,41 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 1. 禁止编造、拼接、模拟、猜测缺失字段。
 2. 禁止用占位符或示例假数据冒充真实返回值。
 3. 禁止假设“工具返回的应该都有”而跳过逐项校验。
-4. 禁止字段不完整时继续集成或写入正式 `.alipay-sandbox.json`。
-5. 除沙箱测试账号的登录密码和支付密码外，禁止把密钥等长字段整段刷屏输出；禁止展示真实生产账号密码。
+4. 禁止字段不完整时使用当前配置、写入正式 `.alipay-sandbox.json`、执行配置后置校验或沙箱测试；允许继续不读取沙箱字段的代码实现，最终必须标记沙箱配置未完成。
+5. Windows 只允许用户在标准资料收集消息后提供当前沙箱密钥和账号信息，Agent 不得在回复、摘要或日志中复述；Unix/macOS/Linux 只允许按登记消息展示已校验的快速沙箱买家密码。禁止展示生产环境应用私钥、账号密码或把任何密钥长字段整段刷屏输出。
+6. 禁止继续使用已被 Git 跟踪的沙箱敏感配置。Unix/macOS/Linux 快速沙箱还必须具备 `/.alipay-sandbox.json` 精确忽略规则；Windows 必须具备适用于实际本机敏感配置路径的忽略保护。
 
-### 6.2 重复创建红线
+### 6.2 快速沙箱重复创建边界
 
-- 候选 `data` 通过第 4 节字段完整性校验后，必须使用本次返回的 `data` 完成正式落盘。
-- 禁止为了“把 data 写入本地文件”“避免对话展示长字段”或“重新拿一份完整配置”再次创建沙箱。
-- 如果第一次通过校验的 `data` 因 Agent 操作失误未落盘，应先从已有工具输出、过程产物或当前可访问的执行结果中恢复；无法恢复时必须向用户说明问题并征得用户明确同意后，才可重新创建。
+- 候选 `data` 的校验、原子落盘和权限复核全部由同一次 `sandbox_config.sh ensure` 调用完成，Agent 不读取或自行恢复原始工具输出。
+- 配置已经存在时，`ensure` 必须进入 `verify`，不得重复创建、覆盖或要求用户删除配置。
+- 创建调用失败时由脚本执行既定网络/服务重试；候选字段或已有配置字段复核失败时最多自动重试 2 次、每次间隔 3 秒。耗尽后由脚本输出待配置消息并继续代码实现，不增加用户确认，也不得绕过脚本直调 MCP。
 
 ### 6.3 重试与失败处理
 
 | 失败场景 | 处理策略 |
 |---------|---------|
-| 首次创建失败 | 提示 "❌ 快速沙箱创建失败，请稍后重试"，等待用户指示后重试 |
-| 字段缺失 | 明确告知具体缺失字段名称，禁止只说"部分字段缺失" |
-| 反复失败（≥2次） | 输出强提醒，提供两个选项：①重新输入指令 ②自行申领沙箱应用，禁止继续自动重试 |
-| 用户提供手动配置 | 仍需按第 4 节逐项校验，通过后方可继续 |
-
-反复失败时输出：
+| 创建失败且既定重试耗尽 | `ensure` 使用 `sandbox.configuration.pending/CREATE`，记录 `CREATE_PENDING` 并继续代码实现；代码开发完成后固定提醒用户可对 Agent 说“重新创建并配置沙箱” |
+| 候选字段或已有配置字段复核失败 | 最多自动重试 2 次、每次间隔 3 秒；仍失败时使用 `sandbox.configuration.pending/CREATE|VERIFY` 并继续代码实现，不展示原始字段或响应 |
+| 待配置状态 | 跳过摘要、配置后置校验、按量付费联调和网站支付付款体验；最终 checklist 保持部分通过或未通过，不得宣称代码开发全部通过或生产就绪 |
+| Windows 未提供资料且未明确要求当前配置 | 记录 `VERIFY_PENDING` 并继续代码实现；不输出失败或申领消息，不探测、不读取、不伪造配置 |
+| Windows 手工申领资料或本地项目配置校验未通过 | 使用 `sandbox.create.failure/WINDOWS`；按第 4 节逐项校验，只补问或更正实际缺失、错误字段后由 Agent 更新本机配置，不要求用户执行 Skill 内部脚本，不伪造快速沙箱结果，也不调用快速沙箱重建 |
 
-```
-🚨 快速沙箱环境多次创建失败/字段不完整
-
-缺失字段：[列出具体缺失的字段名称]
-
-请您选择以下方式之一解决：
-1. 重新输入“创建快速沙箱”指令
-2. 前往支付宝开放平台（https://open.alipay.com）自行申领沙箱应用，需要使用自己的沙箱账号，获取 appId、应用私钥、支付宝公钥等信息后手动配置
-
-在配置完整之前，无法继续集成流程。
-```
+本模块不维护失败话术副本；Unix/macOS/Linux 待配置正文由 `sandbox.configuration.pending` 固定维护，Windows 缺失字段和恢复动作仍通过 `sandbox.create.failure/WINDOWS` 的受控变量传入。
 
 ---
 
-## 7. 写入项目后的后置校验
+## 7. 接入项目后的后置校验
 
-后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先从第 5.1 节的可信配置文件重新读取字段或修正 SDK 配置。
+只有本轮沙箱配置为 `READY` 时，后续步骤才把可信配置接入用户项目并立即做配置准确性后置校验；校验失败时停止联调并修正服务端加载器或 SDK 配置。待配置时只实现会在缺少有效配置时明确失败的加载边界，不读取、复制或伪造沙箱字段。
 
-- 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置。
-- 从第 5.1 节输出的实际配置文件结构化读取并映射字段，禁止从对话、历史代码或示例值复制密钥。
-- 以不输出字段原文的方式比较项目实际读取值与沙箱原值，确认应用私钥不是占位符、示例值或其他来源的密钥，且未出现截断、字符替换或粘贴污染。
+- Unix/macOS/Linux 确认服务端加载器直接读取第 5.1 节的实际 `.alipay-sandbox.json`，从同一 `appIds[0]` 映射 `appId`、应用私钥和支付宝公钥；禁止从对话、历史代码或示例值复制，禁止用 shell 把字段原文输出后再粘贴。Windows 确认项目读取同一套本机沙箱应用配置。
+- 检查加载器没有截断、替换、包装或重新编码字段；项目源码、普通日志和额外 `.env` 中不存在沙箱密钥副本。
 - 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
-- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字；业务协议直接使用原生密码库签名时，可按密码库要求临时适配调用入参，但不得修改或覆盖原始配置值。
+- 检查 SDK 实际接收的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字；业务协议直接使用原生密码库签名时，可按密码库要求临时适配调用入参，但不得修改或覆盖原始配置值。
 - 仅按量付费沙箱联调：项目沙箱运行配置中的 `serviceId` 固定为 `api_mock_service_id`，不从快速沙箱返回中寻找，也不向用户索要正式 `serviceId`。该值不得进入生产配置。
 - 校验输出不得包含私钥、公钥、签名串或完整支付表单。
 
 **常见失败处理：**
-- 私钥不完整、配置不一致或 SDK 初始化/签名失败：从第 5.1 节的可信配置文件重新读取正确字段，禁止补字符、猜测或格式转换。
+- 私钥不完整、配置不一致或 SDK 初始化/签名失败：检查实际配置路径、JSON 字段映射和 SDK 入参，禁止打印私钥、补字符、猜测或格式转换。
 - `ERR_OSSL_UNSUPPORTED`、`DECODER routines::unsupported` 等错误：优先检查项目读取值是否与沙箱原值一致、字段映射是否正确、SDK 配置是否被加工；不要切换私钥字段或在缺少对照证据时归因于运行时、OpenSSL 或 SDK 兼容性。