@alipay/alipay-aipay 1.0.2 → 1.1.0

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 其他说明
 沙箱环境暂不支持用户主动通过看板查看测试账号的交易信息（如：卖家余额、交易状态等）。**严禁**引导用户访问所谓的“支付宝沙箱网页版”查看测试账户的余额变动等。
@@ -37,91 +37,45 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 
 ---
 
-## 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` | 应用公钥 |
 | 商家账号 | 沙箱商家登录账号 |
 | 买家账号 | 沙箱买家测试账号 |
 
-### 4.2 绝对禁止（红线）
-
-**以下行为严格禁止：**
-
-1. **禁止编造字段** —— 不得生成、拼接、模拟、猜测缺失的字段值
-2. **禁止用占位符冒充真实数据** —— 当沙箱成功返回完整配置时，禁止用占位符代替真实返回值
-3. **禁止假数据** —— 不得自行生成示例私钥、示例账号等任何假数据
-4. **禁止假设存在** —— 不得假设"工具返回的应该都有"而不逐项检查
-5. **禁止部分通过** —— 不得因"只有 1 个字段缺失"而继续执行
-6. **禁止跳过校验** —— 不得在未完成逐项校验的情况下直接使用返回结果
-
-### 4.3 校验执行清单
+### 4.2 校验执行清单
 
 **规则：** 任一字段缺失 → **立即停止** → 输出错误提示 → **禁止继续**
 
@@ -140,73 +94,48 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 □ 全部通过 → 输出 "✅ 沙箱环境校验通过"
 ```
 
-### 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`。
+- 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，如有>
+买家账号: email=<email，如有>, userId=<userId，如有>
+沙箱: sandboxId=<sandboxId，如有>, sandboxName=<sandboxName，如有>
+长字段: appPrivateKey/appPrivatePkcsKey/alipayPublicKey/appPublicKey/logonPassword/payPassword 已写入本地配置文件，默认不在对话中展开。
 ```
 
----
-
-## 5. 成功创建后提示（卡点）
+### 5.3 成功创建后提示（卡点）
 
-**⛔ 强制要求：校验通过后，必须在回复中完整输出以下内容。**
-
-- **禁止省略**：不得跳过、缩减
-- **禁止改写**：必须按原文输出
-- **未输出此提示即继续 = 违规**
+输出第 5.2 节摘要后，必须继续输出以下成功提示。提示可以和摘要连续输出，但不得省略关键提醒。
 
 ```
 ⚠️ 快速沙箱环境已创建完成
 
 📌 环境说明
 - 当前快速沙箱环境仅供测试，不涉及真实资金
-- 完整展示沙箱信息，无需对内容脱敏
-- 切勿在项目日志中打印私钥信息
+- 完整沙箱信息已写入本地配置文件；对话中仅展示关键字段摘要，不展开私钥、密码、公钥、完整签名串或完整支付表单等长字段
+- 切勿在项目日志、对话总结或测试结果中打印私钥信息
 - 切勿提交正式环境、沙箱环境信息至公共代码仓库（GitHub、GitLab 等）
 
 🔔 必做操作
-- 请自行妥善保管密钥及测试账号等信息
+- 请自行妥善保管本地配置文件、密钥及测试账号等信息
+- 若需要迁移配置，请从本地配置文件复制，避免通过对话记录传递完整长字段
 
 🔒 安全提醒
 - 正式上线前请确保您已拥有正式的应用 appId、经过审核的应用私钥及支付宝公钥，并切换至正式环境重新配置密钥
@@ -215,4 +144,59 @@ Windows 用户请前往支付宝开放平台（https://open.alipay.com）- 控
 - 正式环境涉及真实资金交易，强烈建议在正式上线之前在沙箱环境中完成全链路测试
 ```
 
-**输出检查：** 确认包含 ⚠️📌🔔🔒 四个标记及全部内容后，方可继续后续集成步骤。
+---
+
+## 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. 写入项目后的后置校验
+
+后续步骤将沙箱配置写入用户项目后，必须立即做配置准确性后置校验；校验失败时停止联调，先重新复制沙箱字段或修正 SDK 配置。
+
+- 确认写入项目的 `appId`、应用私钥、支付宝公钥来自同一份沙箱返回配置。
+- 确认应用私钥不是占位符、示例值或其他来源的密钥，未出现复制截断或粘贴污染。
+- 检查 SDK 配置与私钥字段匹配：`appPrivatePkcsKey` 对应 PKCS#1，`appPrivateKey` 对应 PKCS#8。
+- 检查写入 SDK 配置的私钥值不包含 PEM 头尾、其他前后缀、包装行或说明文字。
+- 校验输出不得包含私钥、公钥、签名串或完整支付表单。
+
+**常见失败处理：**
+- 私钥不完整、配置不一致或 SDK 初始化/解析失败：重新复制完整私钥字段，禁止补字符、猜测或格式转换。
+- `DECODER routines::unsupported`：优先检查私钥是否复制完整、是否错误添加 PEM 头尾或其他前后缀、`keyType` 是否错误，不要切换成 PKCS#8 试错。

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

@@ -55,20 +55,22 @@ fi
 
 ## 3. 前置依赖：GPG 与 jq
 
-安装脚本需要 GPG 签名验证，先检查：
+`npx -y @alipay/alipay-aipay@latest install` 会优先保障 `alipay-cli` 可用；如果 `alipay-cli` 已安装或可直接安装成功，不需要额外安装 GPG。
+
+只有在 `alipay-cli` 首次安装失败，且失败输出指向缺少 GPG/GnuPG 时，后台准备任务才会把 GPG 作为兜底依赖检查：
 ```bash
 which gpg 2>/dev/null
 ```
 
-未安装时先安装 GPG：
+确认 GPG 未安装时，按系统安装：
 
 | 操作系统 | 安装命令 |
 |----------|----------|
-| macOS | `brew install gnupg`（或使用国内镜像源） |
+| macOS | 优先执行 `brew install gnupg`；失败或卡住时配置 Homebrew bottle 镜像后重试 |
 | Linux (Debian/Ubuntu) | `sudo apt-get install -y gnupg` |
 | Linux (CentOS/RHEL) | `sudo yum install -y gnupg2` |
 
-> ⚠️ macOS 如遇下载慢，可只切换 Homebrew bottle 下载源，并跳过自动更新。安装器不会阻塞等待 GPG 安装；只有在 `alipay-cli` 缺失、后台准备任务需要安装前置 GPG 时，才会按以下顺序自动重试：清华 → 阿里云 → 中科大 → 直连。
+> ⚠️ macOS 的 Homebrew 包名是 `gnupg`。安装器不会阻塞等待 GPG 安装；只有在 `alipay-cli` 缺失、首次安装失败且失败输出指向缺少 GPG/GnuPG 时，后台准备任务才会先使用 Homebrew 当前配置执行一次 `brew install gnupg`。如果默认安装失败或卡住，再并行探测清华、阿里云、中科大三个 bottle 镜像，选择最快可用镜像后用镜像重试一次。自动安装使用“无输出超时”：45 秒没有 stdout/stderr 输出才认为命令卡住；默认安装首轮最多 2 分钟，镜像兜底最多 8 分钟。
 >
 > 手动执行时可任选一个镜像源，例如清华：
 > ```bash
@@ -184,12 +186,12 @@ AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚
 │   ↓           │
 │  不存在       │
 │   │           │
-│   ↓           │
-│ 检测 GPG ────┼──无→ 后台尝试安装 GPG → 安装 CLI 到 ~/.local/bin
-│   ↓           │
-│ 有 GPG        │
-│   ↓           │
+│   ↓
 │ 设置 ALIPAY_CLI_BIN="$HOME/.local/bin" 后执行安装脚本
+│   ↓
+│ 安装失败且提示缺少 GPG? ─┼──是→ 检测 GPG ──无→ 后台尝试安装 GPG（macOS 配置 bottle 镜像）
+│   │           │
+│   │           └──GPG 就绪后重试安装 CLI 到 ~/.local/bin
 │   ↓           │
 │ 安装失败? ───┼──是→ 提示指定可写目录手动安装
 │   ↓           │

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

@@ -0,0 +1,59 @@
+# Skill 启动自更新检查
+
+本文件定义 `alipay-aipay` Skill 启动时的 best-effort 自更新检查。该检查用于降低用户继续使用旧版 Skill 的概率，但不得阻断支付集成或签约入驻主流程。
+
+## 执行原则
+
+- 每次触发本 Skill 时，先执行本检查。
+- 如果本轮对话中刚成功执行过 `npx -y @alipay/alipay-aipay@latest install`，或等价的 `@latest install --target ...` 命令，则视为自更新检查已完成，直接继续当前业务流程，不再查询 npm latest，也不再重复执行安装。
+- 本检查不作为业务阻塞确认点，不单独询问用户是否更新。
+- 若当前 Agent 环境要求联网或写入用户 Skill 目录授权，则按环境权限机制处理；不得在 Skill 内另设业务确认点。
+- 任何读取版本、查询 npm、执行更新失败的情况，都只输出简短提示并继续当前业务流程。
+- 更新命令必须使用 `--skip-tools`，只更新 Skill 文件，不重新检查或安装 GPG、alipay-cli、jq。
+
+## 版本读取
+
+1. 读取当前 `SKILL.md` 所在目录下的 `VERSION` 文件作为本地版本。
+2. 如果 `VERSION` 不存在，或内容不是合法 SemVer 版本号（例如 `1.0.6`），将当前安装视为“未知版本/旧版安装”，直接进入「未知版本更新规则」，不要再猜测其他安装记录文件。
+3. 如果成功读取本地版本，执行以下命令查询 npm latest：
+   ```bash
+   npm view @alipay/alipay-aipay version --json
+   ```
+4. 如果无法获取 npm latest，跳过更新并继续当前业务流程。
+
+## 更新规则
+
+如果本地版本低于 npm latest，自动执行 Skill 更新。
+
+更新命令必须覆盖当前正在使用的 Skill 目录。取当前 `SKILL.md` 所在目录的父目录作为 `<当前Skill父目录>`，执行：
+
+```bash
+ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
+```
+
+说明：
+- `ALIPAY_AIPAY_EXTRA_SKILL_DIRS` 确保当前正在使用的 Skill 父目录会被纳入更新目标，避免只更新当前项目目录下的 `.agents/.codex/.claude`。
+- `--target all` 继续覆盖安装器解析到的全部目标目录。
+- `--skip-tools` 避免在启动检查中触发 GPG、alipay-cli、jq 的检查或安装。
+
+## 未知版本更新规则
+
+如果当前 Skill 目录没有 `VERSION`，或 `VERSION` 内容不是合法 SemVer 版本号，不做不可靠的版本推断，直接执行同一条更新命令：
+
+```bash
+ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
+```
+
+说明：
+- 这是对旧版安装的确定性兼容路径；更新成功后，新安装器会写入 `VERSION`，后续启动即可走正常版本比较。
+- 如果该命令因网络、npm、权限或执行环境限制失败，输出简短提示并继续当前业务流程。
+
+## 输出要求
+
+- 已是最新：输出一句简短提示即可。
+- 发现新版本并开始更新：输出本地版本、npm latest 和更新目标摘要。
+- 未知版本并开始更新：输出“未检测到 VERSION，尝试安装 latest”及更新目标摘要。
+- 更新成功：提示更新已完成，并继续当前业务流程。
+- 更新失败或权限受限：提示本次自更新未完成，继续使用当前已加载版本执行流程。
+
+不得输出长篇安装日志；如需日志，以命令输出或工具环境记录为准。

package/skill/references/onboarding/flow.md

@@ -94,7 +94,7 @@
 **CLI 的 `login` 命令返回 `verification_url` 字段，此链接无法用于授权，禁止透出给用户！**
 ```
 ❌ 禁止透出：https://opengw.alipay.com/oauth/device（此链接无法授权）
-✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx&platform=xxx
+✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx（可选追加 platform=xxx）
 ✅ 必须：在授权链接后提示“无法跳链时，请复制链接到网页浏览器打开”
 ```
 > 详见 `modules/authorization.md`
@@ -176,6 +176,27 @@ Step 1: 环境检查 → Step 2: 方案规划 → Step 3: 登录授权
     → Step 5: 入驻推进 → Step 6: 流程结束
 ```
 
+### 启动前材料预告与分流
+
+在正式启动签约入驻流程前，必须先向用户预告后续签约资料要求，并确认是否具备材料：
+
+| 产品 | 后续资料要求 | 材料不足时的处理 |
+|------|--------------|------------------|
+| 按量付费 | 无需截图 | 可直接进入签约入驻流程 |
+| 网站支付 | 需要 3 张网站截图：网站首页、商品页、支付页 | 若没有现成支付页截图或尚未完成支付页面/支付能力集成，先引导进入 `references/integration/flow.md` 完成集成，再回到签约入驻 |
+| APP支付 | 需要 APP 名称和 3 张 APP 界面截图：首页、商品页、支付页 | 若没有现成支付页截图或尚未完成支付页面/支付能力集成，先引导进入 `references/integration/flow.md` 完成集成，再回到签约入驻 |
+
+**标准预告话术**：
+
+> "在正式开始签约入驻前，我先确认一下后续材料要求：按量付费无需截图；网站支付需要网站首页、商品页、支付页 3 张截图；APP支付需要 APP 名称，以及首页、商品页、支付页 3 张截图。请问您当前是否已经有这些页面和截图？如果还没有支付页或尚未完成支付能力集成，我建议先进入支付集成流程，完成后再提交签约材料。"
+
+**执行规则**：
+- 若用户尚未明确产品：先预告三类产品的材料差异，继续 Step 1 和 Step 2；Step 2 确认产品后，再按本规则做材料分流。
+- 用户已明确选择按量付费：无需截图预检，继续 Step 1。
+- 用户已明确选择网站支付或 APP支付，且明确已有材料：继续 Step 1。
+- 用户已明确选择网站支付或 APP支付，但没有支付页截图、尚未完成支付页面或支付能力集成：暂停签约流程，切换到集成流程。
+- 截图要求以“支付页”为准；不得自行改口为“支付成功页”或要求用户提供文档未定义的页面。
+
 ---
 
 ## 三、Step 详解
@@ -260,7 +281,10 @@ TaskCreate({ subject: "流程结束" })
 **⚠️ 授权信息展示规范**：
 - 必须展示：产品类型、经营类目(mccName+mccCode)、确认码、授权链接有效期
 - 禁止使用 CLI 返回的 verification_url
-- 正确链接：`https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx&platform=xxx`
+- 正确链接：`https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx`，可选追加 `platform=xxx`
+- 授权链接必须在输出前确认包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数；缺任一必需参数时阻断，不得展示半成品链接；`platform` 可选，不得因缺少 `platform` 阻断
+- 必须按 `modules/authorization.md` 的“🔐 支付宝授权登录”模板输出，不得简写为“授权确认”步骤列表或只输出裸链接
+- 确认码仅用于用户核对授权页面展示内容，禁止引导用户“输入验证码”
 
 #### Step 3.1: 签约状态查询（登录授权后置检查）
 

package/skill/references/onboarding/modules/authorization.md

@@ -85,7 +85,7 @@ whoami 原始返回格式：
 
 > 📎 已收口到脚本：`scripts/auth.sh init`（Step 2-4: login + 解析 + 校验）
 
-`auth.sh init` 自动执行 login、解析 device_code/verification_code/expires_in、三参数校验，无需手动执行。
+`auth.sh init` 自动执行 login、解析 device_code/verification_code/expires_in、三参数校验和最终授权链接完整性校验，无需手动执行。
 
 ### 4.2 解析返回结果
 
@@ -93,7 +93,7 @@ whoami 原始返回格式：
 
 ### 4.3 参数校验
 
-由 `auth.sh init` 自动校验 device_code、sales_code、mcc_code。
+由 `auth.sh init` 自动校验 device_code、sales_code、mcc_code，并在输出前确认最终授权链接至少包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。
 
 ---
 
@@ -102,7 +102,8 @@ whoami 原始返回格式：
 ### 5.1 链接格式
 
 ```
-✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx&platform=xxx
+✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx
+✅ 可选追加：platform=xxx
 
 ❌ 禁止使用：https://opengw.alipay.com/oauth/device （此链接无法授权）
 ```
@@ -113,10 +114,23 @@ whoami 原始返回格式：
 
 `auth.sh init` 自动构建正确的授权链接（`https://aipay.alipay.com/cli-auth?...`），禁止使用 CLI 返回的 `verification_url`。
 
+授权链接输出前必须完成完整性校验。缺少 `deviceCode`、`productCode`、`mccCode` 任一必需参数，或链接域名不是 `https://aipay.alipay.com/cli-auth` 时，必须阻断，不得把半成品链接展示给用户。`platform` 为可选参数，不得因缺少 `platform` 阻断。
+
 ### 5.3 ⚠️ 禁止透出 verification_url
 
 CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于授权，禁止透出给用户！**
 
+### 5.4 ⚠️ 授权链接与确认码红线
+
+```
+❌ 禁止：展示 https://opengw.alipay.com/oauth/device 或任何 CLI verification_url
+❌ 禁止：展示缺少 productCode 或 mccCode 的 https://aipay.alipay.com/cli-auth 半成品链接
+❌ 禁止：让用户“输入验证码”
+❌ 禁止：把确认码说成验证码、校验码或需要用户手动输入的内容
+✅ 必须：把 login 返回的 verification_code 展示为“确认码”
+✅ 必须：提示用户在授权页面核对确认码是否一致；确认码仅用于核对，不用于输入
+```
+
 ---
 
 ## 六、授权信息展示
@@ -151,6 +165,11 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 请在完成授权后告诉我"好了"继续后续流程。
 ```
 
+**输出红线：**
+- `auth.sh init` 的输出模板是唯一授权提示模板；Agent 不得自行简写、重排或改写为“授权确认/步骤/输入验证码”等其他格式。
+- 确认码只用于用户核对授权页面展示内容，绝不是让用户输入的验证码。
+- 授权链接必须使用完整 Markdown 链接 `[点击跳转进行授权]({BROWSER_URL})`，不得只输出裸链接替代模板。
+
 ---
 
 ## 七、授权确认
@@ -229,14 +248,14 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 
 ---
 
-## 九、重新授权三参数铁律
+## 九、授权链接参数铁律
 
-**三个强参数（deviceCode、productCode、mccCode）必须齐全，platform 为可选参数。**
+**最终展示给用户的授权链接必须包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。`platform` 为可选参数；脚本可由 `DEV_TOOL_NAME` 追加，缺失时不得阻断授权。**
 
-| 场景 | deviceCode 来源 | productCode 来源 | mccCode 来源 |
-|------|-----------------|------------------|--------------|
-| 首次授权 | login 返回 | Step 2 确认的 salesCode | Step 2 推荐的类目编码 |
-| 重新授权 | 新 login 返回 | 显式参数或状态文件 salesCode | 显式参数或状态文件 mccCode |
+| 场景 | deviceCode 来源 | productCode 来源 | mccCode 来源 | platform 来源 |
+|------|-----------------|------------------|--------------|-------------|
+| 首次授权 | login 返回 | Step 2 确认的 salesCode | Step 2 推荐的类目编码 | 可选，来自 `DEV_TOOL_NAME` |
+| 重新授权 | 新 login 返回 | 显式参数或状态文件 salesCode | 显式参数或状态文件 mccCode | 可选，来自 `DEV_TOOL_NAME` |
 
 > ⚠️ **显式参数和状态文件只包含授权链路恢复所需的非敏感上下文，不包含密钥、私钥或业务凭据。**
 
@@ -249,6 +268,8 @@ if [ -z "$DEVICE_CODE" ] || [ -z "$SALES_CODE" ] || [ -z "$MCC_CODE" ]; then
 fi
 ```
 
+授权链接由 `auth.sh init` 统一构建并做最终完整性校验；Agent 不得手写、简写或改写授权链接。
+
 ---
 
 ## 十、CLI 命令规范

package/skill/references/onboarding/modules/product-sign.md

@@ -209,8 +209,10 @@ bash scripts/ar_sign_apply.sh --product apppay --sales-code "I108030000100004131
 ✅ 网站支付未签约 → 需要 3 张网站截图（首页、商品页、支付页）
 ✅ APP支付未签约 → 需要 APP 名称和 3 张APP界面截图（首页、商品页、支付页），签约状态固定按 OFFLINE 提交
 ✅ 按量付费 未签约 → 无需截图，直接签约
+✅ 网站支付/APP支付材料不足 → 不提交签约；先进入/回到集成流程完成支付页/支付能力集成，再回来上传截图
 ❌ 禁止：按量付费 签约时传入 screenshot 字段
 ❌ 禁止：网站支付/APP支付 签约时省略 screenshot 字段
+❌ 禁止：将“支付页”自行改口为“支付成功页”或要求用户提供文档未定义的页面
 ❌ 禁止：APP支付签约 MCP payload 中使用 webAppDTO、appDTO、appName、appType、placeType=APP、placeType=ONLINE_WEBAPP、placeType=ONLINE_NATIVEAPP 或 appType=PC_WEB
 ```
 

package/skill/references/onboarding/modules/scripts/auth.sh

@@ -269,8 +269,21 @@ auth_init() {
     exit 1
   fi
 
-  # Step 5: 构建授权链接（禁止使用 CLI 返回的 verification_url）
-  BROWSER_URL="https://aipay.alipay.com/cli-auth?deviceCode=${DEVICE_CODE}&productCode=${SALES_CODE}&mccCode=${MCC_CODE}&platform=${DEV_TOOL_NAME}"
+  # Step 5: 构建并校验授权链接（禁止使用 CLI 返回的 verification_url）
+  BROWSER_URL="https://aipay.alipay.com/cli-auth?deviceCode=${DEVICE_CODE}&productCode=${SALES_CODE}&mccCode=${MCC_CODE}"
+  if [ -n "${DEV_TOOL_NAME:-}" ] && [ "$DEV_TOOL_NAME" != "unknown" ]; then
+    AUTH_PLATFORM=$(jq -nr --arg value "$DEV_TOOL_NAME" '$value|@uri')
+    BROWSER_URL="${BROWSER_URL}&platform=${AUTH_PLATFORM}"
+  fi
+  if [[ "$BROWSER_URL" != https://aipay.alipay.com/cli-auth\?* ]] ||
+     [[ "$BROWSER_URL" != *"deviceCode=${DEVICE_CODE}"* ]] ||
+     [[ "$BROWSER_URL" != *"productCode=${SALES_CODE}"* ]] ||
+     [[ "$BROWSER_URL" != *"mccCode=${MCC_CODE}"* ]] ||
+     [[ "$BROWSER_URL" == *"opengw.alipay.com/oauth/device"* ]]; then
+    echo "❌ 授权链接构建失败，缺少必要参数或误用了 CLI verification_url，已停止。"
+    echo "📋 正确格式: https://aipay.alipay.com/cli-auth?deviceCode=...&productCode=...&mccCode=..."
+    exit 1
+  fi
 
   # Step 6: 保存参数到状态文件（供 confirm/mismatch 使用）
   save_auth_state