@alipay/alipay-aipay 1.2.2 → 1.4.9

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

@@ -1,5 +1,7 @@
 # 登录授权流程规范
 
+> 只在 onboarding Step 3 读取本模块。授权只能执行本文列出的 `auth.sh init|open|wait|confirm|mismatch`；禁止 Agent 直接调用 `alipay-cli login`、解析其原始输出或展示 `verification_url`。
+>
 > 本文档定义支付宝登录授权的完整流程。
 > 被引用：`flow.md` Step 3 登录授权
 > 本文档位于 `references/onboarding/modules/`，文中的 `scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/onboarding/modules/scripts/...`。
@@ -12,7 +14,7 @@
 |------|-----------|--------------------------|
 | 按量付费 | I1080300001000160457 | `app:all,machine_pay:write,agmnt:write` |
 | 网站支付 | I1080300001000041203 | `app:all,fast_instant_trade_pay:write` |
-| APP支付 | I1080300001000041313 | `app:all,auth_alipay_apppay:write` |
+| APP 支付 | I1080300001000041313 | `app:all,auth_alipay_apppay:write` |
 
 > ⚠️ **禁止自行修改 scope 值**
 
@@ -22,7 +24,7 @@
 
 ### 2.1 检查命令
 
-> 📎 已收口到脚本 `scripts/auth.sh init`。Agent 执行流程时调用 `bash scripts/auth.sh init`（见 flow.md Step 3）；脚本只有在登录有效且目标产品 scope、MCC 均校验通过后才返回 `AUTH_FLOW:SKIP`，需要新授权时返回 `AUTH_FLOW:READY`。校验不匹配时脚本返回对应信号并停止当前操作，不自行 logout；检查或校验无法完成时返回 `AUTH_FLOW:FAILED`，禁止进入状态查询。
+> 📎 已收口到脚本 `scripts/auth.sh init`。Agent 执行流程时调用 `bash scripts/auth.sh init --defer-open`（见 flow.md Step 3）；脚本只有在登录有效且目标产品 scope、MCC 均校验通过后才返回 `AUTH_FLOW:SKIP`，需要新授权时返回 `AUTH_FLOW:READY_TO_OPEN`。Agent 先发出 init stdout，再执行 `bash scripts/auth.sh open` 打开同一授权页。校验不匹配时脚本返回对应信号并停止当前操作，不自行 logout；当前 Agent 执行环境没有取得可确认 CLI 结果时返回 `AUTH_FLOW:RETRY_WITH_NETWORK`，Agent 必须申请联网权限后重试同一条完整命令；检查或校验返回可识别业务失败时返回 `AUTH_FLOW:FAILED`，禁止进入状态查询。
 
 whoami 原始返回格式：
 
@@ -55,23 +57,9 @@ whoami 原始返回格式：
 
 该确认由 `../flow.md` Step 2 的一次性方案确认满足，但必须是用户对同一产品、经营类目和授权范围作出的明确确认。`full_process` 的项目状态回答、integration 产品确认或服务声明确认均不能替代本确认。复用确认只减少 onboarding 内部的重复询问，不降低本节要求；找不到有效确认记录、确认范围不同或信息发生变化时，必须按本节模板重新等待用户确认。
 
-### 3.1 输出格式（Markdown）
+### 3.1 对客输出
 
-```markdown
----
-
-### 📋 请确认您的授权信息
-
----
-
-- **产品类型**: {PRODUCT_NAME}
-- **类目编码**: {MCC_CODE}
-
----
-
-确认信息无误后，将为您生成授权链接。
-是否确认？(是/否)
-```
+本确认只使用 `../flow.md` Step 2 的 `onboarding.plan.confirm`，只有输入 `1` 表示确认；其他输入按问题、修改或补充处理。本模块不维护第二份 Markdown 模板或“是/否”近似问法。
 
 ### 3.2 禁止行为
 
@@ -89,7 +77,7 @@ whoami 原始返回格式：
 
 > 📎 已收口到脚本：`scripts/auth.sh init`（Step 2-4: login + 解析 + 校验）
 
-`auth.sh init` 自动执行 login、解析 device_code/verification_code/expires_in、三参数校验和最终授权链接完整性校验，无需手动执行。
+`auth.sh init` 先校验产品名称、salesCode、scope、MCC 名称和编码属于当前固定规则，再执行 login、解析 device_code/verification_code/expires_in，并构造和校验最终授权链接，无需手动执行。上下文校验失败时必须在 `whoami/login` 和 opener 之前停止。
 
 ### 4.2 解析返回结果
 
@@ -97,7 +85,7 @@ whoami 原始返回格式：
 
 ### 4.3 参数校验
 
-由 `auth.sh init` 自动校验 device_code、sales_code、mcc_code，并在输出前确认最终授权链接至少包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。
+由 `auth.sh init` 自动校验固定产品映射、MCC 参考表和 device_code，并在打开或输出前确认最终授权链接的 `deviceCode`、`productCode`、`mccCode` 与本次上下文逐项一致。
 
 ---
 
@@ -116,9 +104,9 @@ whoami 原始返回格式：
 
 > 📎 已收口到脚本：`scripts/auth.sh init`（Step 5: 构建授权链接）
 
-`auth.sh init` 自动构建正确的授权链接（`https://aipay.alipay.com/cli-auth?...`），禁止使用 CLI 返回的 `verification_url`。
+`auth.sh init` 使用结构化 URL 编码自动构建正确的授权链接（`https://aipay.alipay.com/cli-auth?...`），禁止字符串拼接其他域名、路径或 CLI 返回的 `verification_url`。
 
-授权链接输出前必须完成完整性校验。缺少 `deviceCode`、`productCode`、`mccCode` 任一必需参数，或链接域名不是 `https://aipay.alipay.com/cli-auth` 时，必须阻断，不得把半成品链接展示给用户。`platform` 为可选参数，不得因缺少 `platform` 阻断。
+授权链接在 renderer 和 opener 前必须完成完整校验：协议、域名和路径固定；只允许各一个 `deviceCode`、`productCode`、`mccCode` 及至多一个可选 `platform`；禁止额外参数、重复参数和 fragment；产品码必须属于三个支持产品；三项必填值必须与本次 login 返回值和已确认产品/MCC 逐项一致。任一条件不满足时必须阻断，不得展示或打开。`platform` 缺失时不阻断。
 
 ### 5.3 ⚠️ 禁止透出 verification_url
 
@@ -128,6 +116,7 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 
 ```
 ❌ 禁止：展示 https://opengw.alipay.com/oauth/device 或任何 CLI verification_url
+❌ 禁止：打开或展示其他域名、其他路径、额外/重复参数或带 fragment 的授权 URL
 ❌ 禁止：展示缺少 productCode 或 mccCode 的 https://aipay.alipay.com/cli-auth 半成品链接
 ❌ 禁止：让用户“输入验证码”
 ❌ 禁止：把确认码说成验证码、校验码或需要用户手动输入的内容
@@ -148,33 +137,16 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 4. 授权链接有效期（从 expires_in 计算）
 ```
 
-### 6.2 输出格式（Markdown）
-
-```markdown
-🔐 支付宝授权登录
+### 6.2 标准消息
 
-📋 授权信息
-
-| 项目 | 信息 |
-|------|------|
-| 产品类型 | {PRODUCT_NAME} |
-| 经营类目 | {MCC_NAME} ({MCC_CODE}) |
-| 确认码 | {VERIFICATION_CODE} |
-| 授权链接有效期 | {EXPIRES_DISPLAY} |
-
-⚠️ 安全提示：请核对授权页面显示的确认码是否与上方一致，如不一致，请勿授权，立即停止操作！
-
-提示：无法跳链时，请复制下方链接到网页浏览器打开。
-🌐 授权链接：[点击跳转进行授权]({BROWSER_URL})
-
-请在完成授权后告诉我"好了"继续后续流程。
-```
+授权对客消息统一使用 `../../normal/json/customer-messages.json`：`auth.sh init --defer-open` 渲染非阻塞 `auth.page` 的 `READY` 变体，Agent 原文送达 stdout 后立即执行 `auth.sh open` 受控打开；`auth.sh wait|confirm` 渲染 `auth.pending` / `auth.expired`，scope 或 MCC 不匹配时渲染 `auth.mismatch`。renderer 在渲染授权页前再次校验 URL 中的 `deviceCode/productCode/mccCode` 与本次 CLI 返回值、固定产品映射和 MCC 展示上下文逐项一致。`auth.sh open` 只读取同一次 init 保存的授权 URL 和上下文，校验通过后打开；无论 opener 返回 `OPENED`、`OPEN_FAILED`、`GUI_UNAVAILABLE` 还是 `LINK_ONLY`，都不新增对客正文，不向用户区分底层打开结果。初始模板必须包含产品、经营类目、确认码、有效期、安全核对、完整裸 URL、复制访问兜底，并统一追加“扫码完成后请回到 Agent 对话页面”；不得提前要求输入 `1`。`auth.page` 是页面交付屏障，必须作为独立对客消息送达后再进入 opener 和有限轮询，不得与后续 `auth.pending` 合并在同一条回复。只有有限轮询耗尽后，`auth.pending` 才要求用户完成扫码并输入 `1`；其他输入按问题、修改或补充处理。完整模板只在消息目录维护，脚本负责确定性渲染，禁止在本模块维护第二份文本；Agent 不得在脚本后再次调用 renderer 或重复转述。
 
 **输出红线：**
-- `auth.sh init` 的输出模板是唯一授权提示模板；Agent 不得自行简写、重排或改写为“授权确认/步骤/输入验证码”等其他格式。
+- `auth.sh init --defer-open` 调用 renderer 的结果是唯一授权提示模板；Agent 不得自行简写、重排或改写为“授权确认/步骤/输入验证码”等其他格式。
+- `auth.sh wait|confirm` 和授权校验分支已托管 `auth.pending`、`auth.expired`、`auth.mismatch`；脚本 stdout 只作为对客正文，带 `ALIPAY_AIPAY_INTERNAL:` 前缀的 `AUTH_FLOW:*`、签约状态与查询复用标记只用于转移，严禁对客或补写第二份提示。
 - 确认码只用于用户核对授权页面展示内容，绝不是让用户输入的验证码。
-- 授权链接必须使用完整 Markdown 链接 `[点击跳转进行授权]({BROWSER_URL})`，不得只输出裸链接替代模板。
-- 授权链接必须独占一行并放在“无法跳链”提示之后；禁止将提示文案拼接到 Markdown 链接或 URL 后。
+- 授权链接必须使用消息目录渲染出的完整裸 URL，不得使用 Agent 自行拼写、缩写或重排的链接。
+- 授权链接必须独占一行并放在“无法跳链”提示之后；禁止将提示文案拼接到 URL 后。
 
 ---
 
@@ -182,51 +154,68 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 
 ### 7.1 命令
 
-> 📎 已收口到脚本 `scripts/auth.sh confirm`。Agent 在用户回复"好了"后调用 `bash scripts/auth.sh confirm --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`（见 flow.md Step 3）。
+> 📎 初始 `auth.page` 作为独立对客消息送达后立即调用 `bash scripts/auth.sh open --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`，随后调用 `bash scripts/auth.sh wait --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`。脚本最多查询 12 次，未成功的相邻查询间隔 5 秒；成功或过期立即停止。只有 wait 耗尽并输出 `auth.pending` 后，Agent 才在收到精确输入 `1` 时调用一次 `bash scripts/auth.sh confirm --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`；其他输入不得调用 `confirm`，也不得重启 `wait`。
 
-脚本内部执行 `login --complete` + scope 校验 + MCC 校验。授权上下文处理规则：
+脚本内部执行 `login --complete` + 本机 CLI 登录态复核 + scope 校验 + MCC 校验。`login --complete` 的完成态只表示支付宝页面侧授权确认完成，不等于本机 CLI 已取得有效登录态；随后 `whoami` 返回合法 JSON 但 `logged_in=false` 或 `is_expired=true` 时，脚本最多 3 次、间隔 2 秒复核同一登录态。复核后仍无效时按 PENDING 处理：自动 wait 阶段继续消耗剩余轮询预算，耗尽后输出 `auth.pending` 等待用户扫码完成后输入 `1`；单次 confirm 阶段直接输出 `auth.pending` 并等待用户稍后再次输入 `1`。未取得有效本机登录态前不进入 Step 3.1，也不得宣称授权成功。
 
-> `confirm` / `mismatch` 优先使用显式传入的 `salesCode`、`mccCode`、`scope`、`productName`、`mccName` 等非敏感授权上下文。`auth.sh init` 仍会短期保存本地状态文件，仅用于独立执行子命令时兜底恢复参数。授权成功、过期或失败后脚本会清理该状态文件。
+授权上下文处理规则：
+
+> `confirm` / `mismatch` 优先使用显式传入的 `salesCode`、`mccCode`、`scope`、`productName`、`mccName` 等授权上下文。`auth.sh init` 仍会短期保存本地状态文件，用于独立执行子命令时兜底恢复参数；默认状态使用当前用户独立的 `0700` 临时目录和 `0600` 原子写入文件，目录或文件为符号链接、非普通文件或权限无法收紧时立即停止。状态文件可见时，显式参数必须与同一次 `init` 保存的产品、scope 和 MCC 逐项一致，不一致时在 `login --complete/logout` 前停止并返回 `AUTH_FLOW:CONTEXT_MISMATCH`，不输出对客正文。Agent 必须使用当前 Step 2 已确认的完整上下文重新执行 `auth.sh init --defer-open`；新 init 只有先通过固定产品/MCC 机器校验，才安全替换旧短时状态。CLI 仍登录时，因现有签约查询没有权威 MCC 字段，新 init 必须返回对应 `SCOPE_MISMATCH/MCC_MISMATCH`，再由 `auth.sh mismatch` 统一 logout 并生成当前上下文授权页，禁止返回 `SKIP`；CLI 未登录时直接生成新授权页。两种分支都不得复用旧 deviceCode 或新增用户确认。状态文件因执行环境切换不可见时，继续使用通过固定规则校验的完整显式上下文。授权成功、授权过期和可识别的授权确认失败会清理该状态文件；`PENDING`、命令执行失败、`whoami` 失败、scope/MCC 校验失败和 logout 失败等路径可能保留状态，以便恢复同一授权链路。状态文件存在不代表授权成功，也不得扩展为业务进度。CLI JSON 解析失败时禁止打印原始 stdout/stderr，避免透出 `verification_url`、deviceCode 或未脱敏响应。
+>
+> `AUTH_FLOW:RETRY_WITH_NETWORK` 只表示当前 Agent 执行环境未取得可确认结果，不能解释为用户本机网络故障、支付宝业务失败、logout 失败或 login 失败。Agent 必须申请联网权限后重试同一条完整 `auth.sh` 命令，不得要求用户手动 logout/login 代替本轮脚本事实。
 
 ### 7.2 返回格式与判断
 
 | 脚本输出 | 含义 | 处理 |
 |----------|------|------|
-| `AUTH_FLOW:AUTH_SUCCESS` | 授权成功，scope + MCC 校验通过 | 继续 Step 3.1 状态与资源查询 |
-| `AUTH_FLOW:PENDING` | 用户尚未完成授权 | 继续等待 |
+| `AUTH_FLOW:READY_TO_OPEN` | 授权页已生成且 stdout 已包含完整裸 URL | Agent 先原文发出 stdout，再调用 `auth.sh open` 后进入 `auth.sh wait` |
+| `AUTH_FLOW:AUTH_SUCCESS` | 本机 CLI 登录态、scope 与 MCC 授权有效性检查均通过 | 继续 Step 3.1 状态与资源查询 |
+| `AUTH_FLOW:PENDING` | 有限轮询耗尽，或用户输入 `1` 后仍未取得可推进的有效本机登录态 | 继续等待用户完成扫码后输入 `1`；每次输入只执行一次 confirm |
 | `AUTH_FLOW:EXPIRED` | 授权链接已过期 | 重新执行 auth.sh init |
 | `AUTH_FLOW:SCOPE_MISMATCH` | scope 权限不满足 | 调用 `auth.sh mismatch`，由其 logout 后重新授权 |
 | `AUTH_FLOW:MCC_MISMATCH` | 经营类目未授权 | 调用 `auth.sh mismatch`，由其 logout 后重新授权 |
+| `AUTH_FLOW:CONTEXT_MISMATCH` | 显式上下文与同一次 init 的短时状态不一致，且当前动作未执行 `login --complete/logout` | 使用当前已确认的完整上下文重新执行 `auth.sh init --defer-open` |
+| `AUTH_FLOW:RETRY_WITH_NETWORK` | 当前 Agent 执行环境未取得可确认结果 | 申请联网权限后重试同一条完整命令 |
 | `AUTH_FLOW:FAILED` | 授权确认返回未知错误 | 检查返回信息，联系技术支持 |
 
-### 7.3 ⚠️ 禁止轮询
+### 7.3 有限轮询边界
 
 ```
-❌ 禁止：自动轮询检查授权状态
-❌ 禁止：循环调用 login --complete
+✅ 仅允许：auth.sh wait 内最多查询 12 次，未成功的相邻查询间隔 5 秒
+✅ 必须：成功、过期、授权不匹配、查询错误时立即停止
+✅ 必须：12 次均未取得有效本机登录态后只输出一次 auth.pending
+❌ 禁止：Agent 自行循环调用 auth.sh confirm 或 login --complete
+❌ 禁止：用户输入 1 后再次启动 auth.sh wait
 ```
 
-### 7.4 登录成功后的 scope 权限校验和 MCC 一致性校验
+### 7.4 登录成功后的 scope 权限与 MCC 授权有效性校验
 
-> 📎 已收口到脚本：`scripts/auth.sh confirm`（Step 3-6: scope + MCC 校验）
+> 📎 已收口到脚本：`scripts/auth.sh wait|confirm`（Step 3-6: scope + MCC 授权有效性校验）
 
-`auth.sh init` 对已有有效登录、`auth.sh confirm` 对本次完成的授权都自动执行同一套 scope 和 MCC 校验；不匹配时返回信号并停止当前操作。Agent 只需根据脚本返回值判断结果：
+`auth.sh init` 对已有有效登录、`auth.sh wait|confirm` 对本次完成的授权都自动执行同一套 scope 和 MCC 授权有效性校验；不匹配时返回信号并停止当前操作。Agent 只需根据脚本返回值判断结果：
 
 | 脚本输出 | 后续操作 |
 |----------|----------|
 | `AUTH_FLOW:SKIP` / `AUTH_FLOW:AUTH_SUCCESS` | 进入 Step 3.1 状态与资源查询 |
 | `AUTH_FLOW:SCOPE_MISMATCH` / `AUTH_FLOW:MCC_MISMATCH` | 调用 `auth.sh mismatch`，由其 logout 后重新授权 |
+| `AUTH_FLOW:RETRY_WITH_NETWORK` | 申请联网权限后重试同一条完整 `auth.sh` 命令 |
+
+只有本次实际执行 `auth.sh` 的内部事实中唯一出现 `ALIPAY_AIPAY_INTERNAL:AUTH_FLOW:SKIP` 或 `ALIPAY_AIPAY_INTERNAL:AUTH_FLOW:AUTH_SUCCESS`，才能认为登录、scope 和现有 MCC 授权有效性检查通过。`login --complete` 完成态、脚本中间复核标记、`READY`、`READY_TO_OPEN`、`PENDING`、`EXPIRED`、`CONTEXT_MISMATCH`、其他不匹配、`RETRY_WITH_NETWORK`、`FAILED`、多标记或无标记均不得解释为授权成功；禁止用 Agent 自报状态或历史输出替代。
 
 #### 7.4.1 校验实现
 
-由 `auth.sh init`（已有有效登录）和 `auth.sh confirm`（本次授权完成）自动完成，无需手动执行。
+由 `auth.sh init`（已有有效登录）和 `auth.sh wait|confirm`（本次授权完成）自动完成，无需手动执行。
 
 **为什么需要这两个校验**：
 - `login --complete` 只确认用户完成了扫码，不代表授权范围满足业务需求
 - **Scope 权限校验**：确保授权包含产品所需的操作权限（如 `machine_pay:write`、`fast_instant_trade_pay:write` 或 `auth_alipay_apppay:write`）
-- **MCC 一致性校验**：确保当前登录的经营类目与用户选择的 MCC 一致
+- **MCC 绑定与授权有效性校验**：新授权先由固定 URL 将用户确认的 MCC 精确绑定到本次 deviceCode；登录完成后再使用现有签约查询识别后端明确返回的 `mccCode is not auth` / 产品未授权
 - 如果不匹配，应该立即退出并重新授权，而不是等到后续 MCP 调用时才发现问题
 
+当前冻结的 `ar-query.queryArInfosBySalesProd` 请求只包含 `salesProductCodes`，已验证响应中也没有可依赖的 MCC 字段。因此脚本不得声称从该响应“读取并等值比较了 MCC”；它证明的是本次 URL 已绑定目标 MCC，且当前授权上下文执行既有查询时没有被后端判定为 MCC/产品未授权。若后续取得真实响应中的权威 MCC 字段或其他已验证只读 schema，才能在不改现有请求契约的前提下增加服务端 MCC 等值比较。
+
+该请求与 Step 3.1 签约查询完全相同。只有响应含合法 `resultObj.arInfoList` 且共享解析器成功输出唯一 `AUTH_SIGN_QUERY_REUSABLE=true`、`SIGN_STATUS` 和产品匹配 `FLOW:*` 时，flow 才复用本次签约事实；否则必须独立执行 `query_sign_status.sh`。复用不表示从响应验证了 MCC 字段，也不保存原始响应。
+
 ---
 
 ## 八、权限检查与重新授权
@@ -236,13 +225,13 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 **当检测到授权范围不满足时，必须执行 logout 然后重新授权。**
 
 触发条件：
-1. `auth.sh init` 或 `auth.sh confirm` 返回 `AUTH_FLOW:SCOPE_MISMATCH` / `AUTH_FLOW:MCC_MISMATCH`
+1. `auth.sh init`、`auth.sh wait` 或 `auth.sh confirm` 返回 `AUTH_FLOW:SCOPE_MISMATCH` / `AUTH_FLOW:MCC_MISMATCH`
 2. MCP 调用返回 `mccCode is not auth` 错误
 3. MCP 调用返回 `scope is not auth` 错误
 
 处理流程：
 
-> 📎 `scripts/auth.sh init` / `confirm` 和 `error_handler.sh` 只返回或提示授权不匹配并停止当前操作，不执行 logout。Agent 随后调用 `bash scripts/auth.sh mismatch --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`（见 flow.md Step 3）；该子命令是此恢复路径唯一的 logout 入口，退出成功后再调用 auth init 重新授权。
+> 📎 `scripts/auth.sh init` / `confirm` 和 `error_handler.sh` 只返回或提示授权不匹配并停止当前操作，不执行 logout。Agent 随后调用 `bash scripts/auth.sh mismatch --defer-open --scope "$SCOPE" --sales-code "$SALES_CODE" --mcc-code "$MCC_CODE" --product-name "$PRODUCT_NAME" --mcc-name "$MCC_NAME"`（见 flow.md Step 3）；该子命令是此恢复路径唯一的 logout 入口，退出成功后再生成授权页，Agent 将页面 stdout 独立送达后执行 `auth.sh open`。若 mismatch 返回 `AUTH_FLOW:RETRY_WITH_NETWORK`，表示当前 Agent 执行环境无法确认 logout/login 结果，必须申请联网权限后重试同一条 mismatch 命令，不得改为让用户手动退出登录。
 
 ### 8.2 禁止行为
 
@@ -256,14 +245,14 @@ CLI 返回的 JSON 中包含 `verification_url` 字段，**此链接无法用于
 
 ## 九、授权链接参数铁律
 
-**最终展示给用户的授权链接必须包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。`platform` 为可选参数；脚本可由 `DEV_TOOL_NAME` 追加，缺失时不得阻断授权。**
+**最终打开和展示的授权链接只允许固定 `https://aipay.alipay.com/cli-auth`，并且必须各包含一个与本次上下文完全一致的 `deviceCode`、`productCode`、`mccCode`。`platform` 为唯一可选参数；脚本可由 `DEV_TOOL_NAME` 追加，缺失时不得阻断授权。其他参数、重复参数和 fragment 一律拒绝。**
 
 | 场景 | deviceCode 来源 | productCode 来源 | mccCode 来源 | platform 来源 |
 |------|-----------------|------------------|--------------|-------------|
 | 首次授权 | login 返回 | Step 2 确认的 salesCode | Step 2 推荐的类目编码 | 可选，来自 `DEV_TOOL_NAME` |
 | 重新授权 | 新 login 返回 | 显式参数或状态文件 salesCode | 显式参数或状态文件 mccCode | 可选，来自 `DEV_TOOL_NAME` |
 
-> ⚠️ **显式参数和状态文件只包含授权链路恢复所需的非敏感上下文，不包含密钥、私钥或业务凭据。**
+> ⚠️ **显式参数和状态文件只包含授权链路恢复所需的受限上下文，不包含密钥、私钥或业务凭据；其中 deviceCode 仍按临时敏感值保护，禁止通过错误日志或普通对话额外输出。**
 
 参数校验：
 
@@ -291,6 +280,6 @@ fi
 
 ### 10.2 检测工具设置
 
-> 📎 所有签约 `.sh` 脚本都会通过 `error_handler.sh` 间接初始化 `DEV_TOOL_NAME` 并设置 `PLATFORM`，无需手动设置。
+> 📎 所有签约 `.sh` 脚本都会通过 `error_handler.sh` 间接初始化 `DEV_TOOL_NAME`、`PLATFORM` 和当前 `run_id` 对应的 `PLATFORM_ID`，无需手动设置。
 
-签约脚本通过 `scripts/error_handler.sh` 加载 `../../../normal/scripts/common.sh`，再由 `init_dev_tool_name` 调用 `detect_dev_tool.sh` 初始化 `DEV_TOOL_NAME`；Step 1 的环境检查只负责确认工具可用，不要求 Agent 手动添加 `DEV_TOOL_NAME=...` 前缀。
+签约脚本通过 `scripts/error_handler.sh` 加载 `../../normal/scripts/common.sh`，再由 `init_alipay_cli_context` 初始化 `DEV_TOOL_NAME`、`PLATFORM` 和 `PLATFORM_ID`；Step 1 的环境检查只负责确认工具可用，不要求 Agent 手动添加 `DEV_TOOL_NAME=...`、`PLATFORM=...` 或 `PLATFORM_ID=...` 前缀。

package/skill/references/onboarding/modules/error-handling.md

@@ -3,23 +3,23 @@
 > ⚠️ **全流程错误参考文档**：本文档涵盖签约全流程（Step 1~Step 6）各步骤可能出现的错误及处理方式。**当任何 Step 执行过程中遇到错误时，均可查阅本文档进行问题排查**。
 > 本文档位于 `references/onboarding/modules/`，文中的 `scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/onboarding/modules/scripts/...`。
 >
-> 📎 **可执行版本**：shell 公共函数位于 `../../../normal/scripts/common.sh`，错误检测和处理函数位于 `scripts/error_handler.sh`。各签约 `.sh` 脚本通过 `source scripts/error_handler.sh` 间接完成 `DEV_TOOL_NAME` 初始化，并在每次 MCP 调用后执行错误处理。**本文档为说明参考，实际执行以脚本为准。**
+> 📎 **可执行版本**：shell 公共函数位于 `../../normal/scripts/common.sh`，错误检测和处理函数位于 `scripts/error_handler.sh`。`scripts/network_retry.sh` 只在原命令外围处理网络尝试、stdout/stderr 分离和写后核验信号；各签约 `.sh` 脚本仍在每次 MCP 调用后使用原错误处理和业务解析。**本文档为说明参考，实际执行以脚本为准。**
 
 ---
 
 ## 错误检测函数索引
 
-> ⚠️ `require_command` / `init_dev_tool_name` 定义于 `normal/scripts/common.sh`；`error_handler.sh` 会在加载公共函数后显式调用 `init_dev_tool_name`。以下错误处理函数定义于 `error_handler.sh`，本文档仅说明其用途和触发条件。
+> ⚠️ `require_command` / `init_alipay_cli_context` 定义于 `normal/scripts/common.sh`；`error_handler.sh` 会在加载公共函数后显式调用 `init_alipay_cli_context`，统一初始化 `DEV_TOOL_NAME`、`PLATFORM` 和当前 `run_id` 对应的 `PLATFORM_ID`。以下错误处理函数定义于 `error_handler.sh`，本文档仅说明其用途和触发条件。
 
 | 函数 | 说明 | 返回 |
 |------|------|------|
 | `unwrap_mcp` | MCP 信封解包，通过单次状态扫描提取 `content[0].text` 中的业务 JSON；混合输出只从完整闭合结构形成候选，并只接受唯一可确定的 MCP 信封或 JSON，候选不唯一时不猜测结果，由错误检测阻断 | 解包后的 JSON 字符串或无法唯一解析的原始文本 |
 | `detect_error` | 统一错误检测入口，自动解包 MCP 信封后按优先级匹配所有错误类型 | `MCP_AUTH_ERROR` / `MCP_SERVICE_ERROR` / `AUTH_MISMATCH` / `SERVICE_UNSTABLE` / `ERROR:xxx` / `CLI_ERROR:xxx` / `SUCCESS` |
 | `handle_error` | 统一错误处理入口，调用 `detect_error` 后路由到对应 handler（内含 `unwrap_mcp` 自动解包信封） | `0`=成功, `1`=需用户干预 |
-| `handle_mcp_auth_error` | 处理 MCP 认证错误（HTTP 401），校验 logout 成功后再引导重新授权；logout 失败时阻断 | - |
-| `handle_mcp_service_error` | 处理 MCP 服务不可用（网络/连接错误）；沙箱化 Agent 环境提示申请可联网权限重试同一命令，其他环境提示检查网络 | - |
+| `handle_mcp_auth_error` | 处理 MCP 认证错误（HTTP 401），校验 logout 成功后再引导重新授权；logout 返回合法失败时阻断；当前 Agent 执行环境无法确认 logout 结果时要求联网重试同一动作 | - |
+| `handle_mcp_service_error` | 处理 MCP 服务不可用（网络/连接错误）；网络重试预算耗尽后记录受影响分支，独立分支继续，最终统一收口 | - |
 | `handle_auth_mismatch` | 识别授权不匹配（MCC/产品/scope），停止当前操作并引导调用 `auth.sh mismatch` | - |
-| `handle_service_unstable` | 处理 MCP 服务不稳定，提示稍后重试 | - |
+| `handle_service_unstable` | 处理 MCP 服务不稳定；停止当前动作并交由主流程最终统一收口 | - |
 | `handle_backend_error` | 处理后端业务错误（errorCode），展示错误信息、bizTips、checkedError | - |
 
 ---
@@ -39,7 +39,8 @@
 ### 处理原则
 ```
 ✅ 检测到 HTTP 401 → 执行并校验 logout → 仅退出成功后引导用户重新授权
-❌ logout 失败 → 明确报错并停止重新授权，禁止宣称已退出登录
+❌ logout 返回合法失败 → 明确报错并停止重新授权，禁止宣称已退出登录
+✅ logout 输出不可唯一解析或疑似 Agent 环境无联网权限 → 表述为“无法确认退出登录结果”，要求 Agent 申请联网权限后重试同一动作；禁止解释为用户本机 logout 失败或支付宝业务失败
 ✅ 清理对话上下文中的授权相关数据
 ✅ 提供清晰的错误说明和下一步操作指引
 ❌ 禁止自动重试 MCP 调用（会导致相同的认证错误）
@@ -77,14 +78,23 @@
 
 ### 处理原则
 ```
-✅ 检测到网络错误 → 沙箱化 Agent 环境提示申请可联网权限重试同一命令，其他环境提示用户检查网络
-✅ 提供网络排查指引
-❌ 禁止自动重试多次（会加剧服务器压力）
+✅ 只读调用检测到 MCP_SERVICE_ERROR / SERVICE_UNSTABLE → 同一参数最多自动重试 2 次，每次等待 3 秒
+✅ 写调用只有明确 NOT_SENT 时直接使用相同预算；MAYBE_SENT 先走现有只读核验，无法确认时标记 UNKNOWN
+✅ 重试预算耗尽 → 停止当前动作并记录失败事实；依赖允许时继续其他独立分支；全部可推进动作结束后，在 Step 6 逐分支结果中一次说明失败动作和恢复方式
+✅ 沙箱化 Agent 的宿主网络授权仍按环境权限机制处理，不能伪装成业务确认
+❌ 禁止因重试重新生成 REQUEST_JSON、bizRequestNo、资源名称或其他动态字段
+❌ 禁止业务错误、认证错误、授权不匹配、参数错误或结构歧义进入网络重试
 ❌ 禁止静默忽略错误
 ```
 
 > 📎 处理脚本：见 `error_handler.sh` → `handle_mcp_service_error()`、`handle_service_unstable()`
 
+`MCP_SERVICE_ERROR` 和 `SERVICE_UNSTABLE` 是现有错误处理脚本的内部分类，不是支付宝外部业务错误码。执行器保持 `detect_error`、`unwrap_mcp`、`handle_error` 和业务字段解析不变，只重复同一组已分词 CLI argv；stdout 仍单独交给原解析，stderr 不拼入 MCP JSON。
+
+写操作的保守判定固定为：DNS 解析失败、connection refused、宿主在连接前明确拒绝网络访问可记为 `NOT_SENT`；timeout、连接中断、`SERVICE_UNSTABLE` 或发送阶段不明一律为 `MAYBE_SENT`。签约提交使用现有签约查询核验；服务修改只有列表按 `serviceId` 精确匹配完整五项资料才算成功；服务新建和应用创建不能按同名候选猜测；公钥确认页没有可用核验查询；应用提审只使用现有应用信息状态。无法证明成功或未生效时禁止重复写入。
+
+后端错误文案进入 renderer 前必须先经过 `sanitize_customer_error_text`。该脱敏入口必须覆盖 renderer 禁止内容和可复用敏感内容：`{{` / `}}`、`<INTERNAL_`、临时 URL、deviceCode、Authorization、Payment-Proof、token、password、secret、key 和证书头等只能输出受控隐藏文案；普通业务错误（如“服务名称已存在，请修改”）必须保留原文。`MESSAGE_RENDER_ERROR` 不构成写操作 `MAYBE_SENT` 依据，Agent 不得据此推断服务已创建或自动重复创建。
+
 ---
 
 ## 三、授权信息不匹配
@@ -120,18 +130,19 @@
 ### 错误码表格
 | 错误码 | 说明 | 处理方式 |
 |--------|------|----------|
-| `authorization_pending` | 用户尚未扫码或未确认授权 | 继续等待或提示用户 |
+| `authorization_pending` | 用户尚未扫码或未确认授权 | `auth.sh wait` 在限定预算内继续；耗尽后提示用户 |
 | `auth_expired` | 授权已过期（10分钟） | 重新执行登录流程 |
 
 ### 处理原则
 ```
-✅ 检测到 authorization_pending → 提示用户继续扫码
+✅ 检测到 authorization_pending 或自动轮询阶段 whoami 尚未生效 → 仅由 auth.sh wait 在最多 12 次、未成功的相邻查询间隔 5 秒内继续查询
+✅ 12 次均未取得有效本机登录态 → 输出一次 auth.pending 并等待用户输入 1；输入后只执行一次 confirm
 ✅ 检测到 auth_expired → 重新执行登录流程
-❌ 禁止：自动轮询检查授权状态
-❌ 禁止：循环调用 login --complete
+❌ 禁止：Agent 自行循环调用 auth.sh confirm 或 login --complete
+❌ 禁止：有限轮询耗尽后自动重启 wait
 ```
 
-> 📎 处理脚本：授权确认逻辑见 `scripts/auth.sh confirm`
+> 📎 处理脚本：有限轮询见 `scripts/auth.sh wait`，超时后单次恢复查询见 `scripts/auth.sh confirm`
 
 ---
 
@@ -162,7 +173,7 @@
 ✅ 如有 checkedError → 逐条展示字段级校验错误描述
 ✅ 如有 errorScene / errorSpecific → 一并展示，便于技术支持定位
 ✅ createApplication 返回 APP_MAX_ERROR → 告知用户应用数量达到上限，引导复用已有上线应用或前往支付宝开放平台处理配额
-✅ needRetry=true → 告知用户可以重试
+✅ needRetry=true 仍属于业务错误提示 → 展示实际错误与 bizTips，但不自动重试、不立即询问“重试/退出”；业务条件修正后才能重新执行受影响动作
 ❌ 禁止：忽略 errorCode 继续执行
 ❌ 禁止：向用户暴露技术性内部错误
 ❌ 禁止：只输出"未知错误"而丢弃 errorCode / bizTips / checkedError
@@ -172,27 +183,13 @@
 
 ---
 
-## 六、快速集成用法
+## 六、脚本内错误处理契约
 
-> ⚠️ 各 `.sh` 脚本已内置错误检测（source `error_handler.sh` + 调用 `handle_error`）和 MCP 信封解包（`unwrap_mcp`），Agent 执行脚本时无需额外处理。
+当前 onboarding 主流程的 MCP 调用全部由已登记 `.sh` 脚本封装。运行时 Agent 只执行 flow 中的脚本入口，不直调 MCP、不追加 `handle_error` / `unwrap_mcp` 命令，也不在脚本成功后重新解析 stdout。
 
-在**直接执行 MCP 调用**（非通过脚本）的场景，需注意 `alipay-cli mcp call` 返回 MCP 协议信封，业务 JSON 被包在 `content[0].text` 里，必须先解包。CLI stdout 混有日志时，`unwrap_mcp` 只提取唯一可确定的信封或 JSON；存在多个候选时不猜测，保留原文并增加歧义标记，后续 `handle_error` 将按非 JSON 异常阻断：
+维护脚本时保持既有顺序：每次 MCP 调用先把原始 stdout 交给 `handle_error`；只有返回 0 才调用 `unwrap_mcp`，然后按当前模块已经确认的响应契约解析业务字段。CLI stdout 混有日志时，`unwrap_mcp` 只接受唯一可确定的 MCP 信封或 JSON；存在多个候选时不猜测、不回显原始响应，并由错误检测阻断。不得统一假定成功字段位于 `.success`；例如服务写入的当前协议使用 `code="10000"`、`data.success=true`，并从 `data.serviceId` 读取服务 ID。
 
-```bash
-# ① 执行 MCP 调用
-RESULT=$(export PLATFORM=${DEV_TOOL_NAME} && alipay-cli mcp call <METHOD> -d '<JSON>' --json 2>/dev/null)
-
-# ② 调用 handle_error 自动处理（内含信封解包）
-if ! handle_error "$RESULT"; then
-  # handle_error 已输出用户提示，返回 1 表示需要用户干预
-  return 1
-fi
-
-# ③ 如果返回 0，解包信封后按当前模块已确认的响应契约处理业务字段
-BUSINESS=$(unwrap_mcp "$RESULT")
-# 不得统一假定成功字段位于 .success；例如服务写入的当前协议使用
-# code="10000"、data.success=true，并从 data.serviceId 读取服务 ID。
-```
+新增尚未封装的 MCP 调用不属于运行时排障动作。必须先取得确定 schema，并同步脚本、模块、flow 和契约测试后才能进入主流程；禁止用占位方法名或通用 JSON 模板临场试调。
 
 ---
 
@@ -238,7 +235,7 @@ BUSINESS=$(unwrap_mcp "$RESULT")
 | Step 3 登录授权 | whoami / login / login --complete / logout | 由 `auth.sh` 内置处理 |
 | Step 3.1 状态与资源查询（签约状态） | ar-query.queryArInfosBySalesProd | 由 `query_sign_status.sh` 内置（source error_handler.sh；建议设置 PRODUCT_TYPE 做产品码一致性校验） |
 | Step 3.1 应用/服务资源查询 | apprelease.queryApplicationList / a2a-pay-service.discoverBazaarServicesForMcp | 分别由 `app.sh list` / `service.sh list` 内置，禁止将失败结果当作空列表 |
-| Step 4 一次性资料与资源决策 | file upload | 由 `upload_screenshots.sh` 内置（source error_handler.sh + unwrap_mcp 解包信封） |
+| Step 4 签约材料类别 | file upload | 由 `upload_screenshots.sh` 内置（source error_handler.sh + unwrap_mcp 解包信封） |
 | Step 5.1 产品签约 | ar-sign.apply | 由 `ar_sign_apply.sh` 内置（source error_handler.sh） |
 | Step 5.2 服务注册 | a2a-pay-service.* | 由 `service.sh` 内置（source error_handler.sh） |
 | Step 5.3 应用发布 | apprelease.* | 由 `app.sh` 内置（source error_handler.sh） |