@alipay/alipay-aipay 1.2.2 → 1.5.0

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

@@ -1,296 +1,40 @@
-# 登录授权流程规范
+# 登录授权业务语义
 
-> 本文档定义支付宝登录授权的完整流程。
-> 被引用：`flow.md` Step 3 登录授权
-> 本文档位于 `references/onboarding/modules/`，文中的 `scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/onboarding/modules/scripts/...`。
+本模块只解释授权业务语义。运行时命令、确认、终态和失败分支以 `../flow.md` 为准；参数校验、URL 构造、状态保护和解析由 `scripts/auth.sh` 实现。正常路径不预读本模块。
 
----
+## 产品授权范围
 
-## 一、Scope 定义
+| 产品 | salesCode | scope |
+| --- | --- | --- |
+| AI 按量付费 | `I1080300001000160457` | `app:all,machine_pay:write,agmnt:write` |
+| AI 网页应用收款 | `I1080300001000041203` | `app:all,fast_instant_trade_pay:write` |
+| AI 移动应用收款 | `I1080300001000041313` | `app:all,auth_alipay_apppay:write` |
 
-| 产品 | salesCode | Scope（固定值，禁止修改） |
-|------|-----------|--------------------------|
-| 按量付费 | I1080300001000160457 | `app:all,machine_pay:write,agmnt:write` |
-| 网站支付 | I1080300001000041203 | `app:all,fast_instant_trade_pay:write` |
-| APP支付 | I1080300001000041313 | `app:all,auth_alipay_apppay:write` |
+产品名称、salesCode、scope、MCC 名称和编码必须属于同一固定上下文。`auth.sh` 在任何 `whoami`、`login`、`login --complete`、`logout` 或 opener 前完成机器校验；参数冲突返回 `AUTH_FLOW:CONTEXT_MISMATCH`，不执行外部动作。
 
-> ⚠️ **禁止自行修改 scope 值**
+固定上下文通过后，`auth.sh` 按 salesCode 将 CLI `PRODUCT` 设置为 `AIPAY|WEBPAY|APPPAY`；该值只作为 CLI 上报上下文，不进入授权或签约 MCP 请求 JSON。
 
----
+## 授权状态语义
 
-## 二、登录状态检查
+- `AUTH_FLOW:SKIP|AUTH_SUCCESS`：当前本机登录态、scope 和当前 MCC 上下文均已通过脚本校验。
+- `AUTH_FLOW:READY_TO_OPEN`：当前授权页已生成并完成白名单及上下文校验，可以交付页面后调用受控 opener。
+- `AUTH_FLOW:PENDING`：有限轮询耗尽或单次恢复查询尚未得到有效本机登录态；不等于失败，也不证明用户未扫码。
+- `AUTH_FLOW:EXPIRED`：当前页面实际返回过期，旧页面和旧回复失效，重新执行 flow 登记的 init。
+- `AUTH_FLOW:SCOPE_MISMATCH|MCC_MISMATCH`：只能走 `auth.sh mismatch`；logout 未确认成功前不得重新授权。
+- `AUTH_FLOW:RETRY_WITH_NETWORK`：当前 Agent 环境无法确认结果，申请联网权限后原样重试同一命令；不得解释为用户本机登录失败。
 
-### 2.1 检查命令
+CLI `login --complete` 成功只表示页面侧确认完成，不代表本机已取得可用登录态。脚本仍需复核 `whoami`、scope，并以固定授权 URL 绑定 MCC；当前后端查询没有权威 MCC 返回字段，禁止声称做了响应 MCC 等值比较。
 
-> 📎 已收口到脚本 `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`，禁止进入状态查询。
+## 页面与恢复
 
-whoami 原始返回格式：
+授权页只允许 `https://aipay.alipay.com/cli-auth`，必含唯一 `deviceCode/productCode/mccCode`，只允许可选 `platform`；禁止 CLI `verification_url`、额外参数、重复参数和 fragment。页面 stdout 必须先作为独立对客消息送达，再执行 `auth.sh open` 和 `auth.sh wait`，后续 pending 或收口不得合并进同一回复。
 
-### 2.2 返回格式
+`wait` 生产最多查询 12 次，未成功的相邻查询间隔 5 秒，成功或过期立即停止。耗尽后把用户原始回复交给 `../../normal/scripts/onboarding_recovery_runner.mjs auth-confirm`；runner 复用统一肯定语义判定器，接受 `继续`、`好了`、`已完成`、`确认`、`OK` 和兼容输入 `1`，每次接受只执行一次 `auth.sh confirm`，不重启自动轮询。否定、疑问、取消、修改意见或含糊输入不查询。
 
-```json
-// 已登录且未过期
-{ "success": true, "data": { "logged_in": true, "is_expired": false, "expires_at": "2026-04-20T15:37:42+08:00" } }
+授权对客正文只由 `auth.sh` 调用消息目录生成。初始页面不得提前要求回复完成；pending 的自然语言提示、允许回复和授权页返回提示都不在本模块维护副本。
 
-// 未登录或已过期
-{ "success": true, "data": { "logged_in": false, "is_expired": true } }
-```
+## 状态保护
 
-### 2.3 判断方式
+短时授权上下文使用当前用户私有临时目录和 `0600` 原子文件，拒绝符号链接。状态可见时显式参数必须逐项一致；状态不可见时仅允许完整显式上下文降级。新 init 只有先通过固定上下文校验才可替换旧状态；上下文改变且 CLI 仍登录时必须进入 mismatch，不得复用旧 deviceCode。
 
-**检查 `.data.logged_in` 字段（不是外层的 `.success`）**
-
-当前约定的 `whoami` 返回只用于校验登录是否有效、是否过期和授权 scope，不包含可依赖的账号主体标识。外部写操作摘要不得从该返回中编造主体名称；按 `../flow.md` Step 5 展示当前有效登录会话，有其他已验证查询返回非敏感主体标识时再脱敏展示，否则要求用户确认当前登录账号就是操作目标。
-
-| 返回值 | 状态 | 处理 |
-|--------|------|------|
-| `logged_in: true` + `is_expired: false` | 登录有效 | 继续校验目标产品 scope 和 MCC；均通过后才可进入后续步骤 |
-| `logged_in: false` 或 `is_expired: true` | 未登录/已过期 | 进入登录授权流程 |
-
----
-
-## 三、授权前用户确认（强制）
-
-**在执行 `login` 命令前，必须先让用户确认产品类型和经营类目！**
-
-该确认由 `../flow.md` Step 2 的一次性方案确认满足，但必须是用户对同一产品、经营类目和授权范围作出的明确确认。`full_process` 的项目状态回答、integration 产品确认或服务声明确认均不能替代本确认。复用确认只减少 onboarding 内部的重复询问，不降低本节要求；找不到有效确认记录、确认范围不同或信息发生变化时，必须按本节模板重新等待用户确认。
-
-### 3.1 输出格式（Markdown）
-
-```markdown
----
-
-### 📋 请确认您的授权信息
-
----
-
-- **产品类型**: {PRODUCT_NAME}
-- **类目编码**: {MCC_CODE}
-
----
-
-确认信息无误后，将为您生成授权链接。
-是否确认？(是/否)
-```
-
-### 3.2 禁止行为
-
-```
-❌ 禁止：未经用户确认直接执行登录命令
-❌ 禁止：跳过产品类型和经营类目的展示
-❌ 禁止：条件性隐藏产品或类目信息
-```
-
----
-
-## 四、执行登录
-
-### 4.1 登录命令
-
-> 📎 已收口到脚本：`scripts/auth.sh init`（Step 2-4: login + 解析 + 校验）
-
-`auth.sh init` 自动执行 login、解析 device_code/verification_code/expires_in、三参数校验和最终授权链接完整性校验，无需手动执行。
-
-### 4.2 解析返回结果
-
-由 `auth.sh init` 自动处理。
-
-### 4.3 参数校验
-
-由 `auth.sh init` 自动校验 device_code、sales_code、mcc_code，并在输出前确认最终授权链接至少包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。
-
----
-
-## 五、生成授权链接
-
-### 5.1 链接格式
-
-```
-✅ 正确链接：https://aipay.alipay.com/cli-auth?deviceCode=xxx&productCode=xxx&mccCode=xxx
-✅ 可选追加：platform=xxx
-
-❌ 禁止使用：https://opengw.alipay.com/oauth/device （此链接无法授权）
-```
-
-### 5.2 构建命令
-
-> 📎 已收口到脚本：`scripts/auth.sh init`（Step 5: 构建授权链接）
-
-`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 展示为“确认码”
-✅ 必须：提示用户在授权页面核对确认码是否一致；确认码仅用于核对，不用于输入
-```
-
----
-
-## 六、授权信息展示
-
-### 6.1 必须展示的 4 项信息
-
-```
-1. 产品类型（productName）— 如：网站支付、按量付费
-2. 经营类目（mccName + mccCode）— 如：零售批发 > 互联网综合电商平台 (A0002_B0114)
-3. 确认码（verificationCode）— login 返回的 verification_code
-4. 授权链接有效期（从 expires_in 计算）
-```
-
-### 6.2 输出格式（Markdown）
-
-```markdown
-🔐 支付宝授权登录
-
-📋 授权信息
-
-| 项目 | 信息 |
-|------|------|
-| 产品类型 | {PRODUCT_NAME} |
-| 经营类目 | {MCC_NAME} ({MCC_CODE}) |
-| 确认码 | {VERIFICATION_CODE} |
-| 授权链接有效期 | {EXPIRES_DISPLAY} |
-
-⚠️ 安全提示：请核对授权页面显示的确认码是否与上方一致，如不一致，请勿授权，立即停止操作！
-
-提示：无法跳链时，请复制下方链接到网页浏览器打开。
-🌐 授权链接：[点击跳转进行授权]({BROWSER_URL})
-
-请在完成授权后告诉我"好了"继续后续流程。
-```
-
-**输出红线：**
-- `auth.sh init` 的输出模板是唯一授权提示模板；Agent 不得自行简写、重排或改写为“授权确认/步骤/输入验证码”等其他格式。
-- 确认码只用于用户核对授权页面展示内容，绝不是让用户输入的验证码。
-- 授权链接必须使用完整 Markdown 链接 `[点击跳转进行授权]({BROWSER_URL})`，不得只输出裸链接替代模板。
-- 授权链接必须独占一行并放在“无法跳链”提示之后；禁止将提示文案拼接到 Markdown 链接或 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）。
-
-脚本内部执行 `login --complete` + scope 校验 + MCC 校验。授权上下文处理规则：
-
-> `confirm` / `mismatch` 优先使用显式传入的 `salesCode`、`mccCode`、`scope`、`productName`、`mccName` 等非敏感授权上下文。`auth.sh init` 仍会短期保存本地状态文件，仅用于独立执行子命令时兜底恢复参数。授权成功、过期或失败后脚本会清理该状态文件。
-
-### 7.2 返回格式与判断
-
-| 脚本输出 | 含义 | 处理 |
-|----------|------|------|
-| `AUTH_FLOW:AUTH_SUCCESS` | 授权成功，scope + MCC 校验通过 | 继续 Step 3.1 状态与资源查询 |
-| `AUTH_FLOW:PENDING` | 用户尚未完成授权 | 继续等待 |
-| `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:FAILED` | 授权确认返回未知错误 | 检查返回信息，联系技术支持 |
-
-### 7.3 ⚠️ 禁止轮询
-
-```
-❌ 禁止：自动轮询检查授权状态
-❌ 禁止：循环调用 login --complete
-```
-
-### 7.4 登录成功后的 scope 权限校验和 MCC 一致性校验
-
-> 📎 已收口到脚本：`scripts/auth.sh confirm`（Step 3-6: scope + MCC 校验）
-
-`auth.sh init` 对已有有效登录、`auth.sh 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 后重新授权 |
-
-#### 7.4.1 校验实现
-
-由 `auth.sh init`（已有有效登录）和 `auth.sh confirm`（本次授权完成）自动完成，无需手动执行。
-
-**为什么需要这两个校验**：
-- `login --complete` 只确认用户完成了扫码，不代表授权范围满足业务需求
-- **Scope 权限校验**：确保授权包含产品所需的操作权限（如 `machine_pay:write`、`fast_instant_trade_pay:write` 或 `auth_alipay_apppay:write`）
-- **MCC 一致性校验**：确保当前登录的经营类目与用户选择的 MCC 一致
-- 如果不匹配，应该立即退出并重新授权，而不是等到后续 MCP 调用时才发现问题
-
----
-
-## 八、权限检查与重新授权
-
-### 8.1 授权范围不满足处理
-
-**当检测到授权范围不满足时，必须执行 logout 然后重新授权。**
-
-触发条件：
-1. `auth.sh init` 或 `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 重新授权。
-
-### 8.2 禁止行为
-
-```
-❌ 禁止：检测到授权范围不满足后继续执行后续操作
-❌ 禁止：不执行 logout 直接重新登录
-❌ 禁止：忽略权限错误继续调用 MCP
-```
-
----
-
-## 九、授权链接参数铁律
-
-**最终展示给用户的授权链接必须包含 `deviceCode`、`productCode`、`mccCode` 三个必需参数。`platform` 为可选参数；脚本可由 `DEV_TOOL_NAME` 追加，缺失时不得阻断授权。**
-
-| 场景 | deviceCode 来源 | productCode 来源 | mccCode 来源 | platform 来源 |
-|------|-----------------|------------------|--------------|-------------|
-| 首次授权 | login 返回 | Step 2 确认的 salesCode | Step 2 推荐的类目编码 | 可选，来自 `DEV_TOOL_NAME` |
-| 重新授权 | 新 login 返回 | 显式参数或状态文件 salesCode | 显式参数或状态文件 mccCode | 可选，来自 `DEV_TOOL_NAME` |
-
-> ⚠️ **显式参数和状态文件只包含授权链路恢复所需的非敏感上下文，不包含密钥、私钥或业务凭据。**
-
-参数校验：
-
-```bash
-if [ -z "$DEVICE_CODE" ] || [ -z "$SALES_CODE" ] || [ -z "$MCC_CODE" ]; then
-  echo "❌ 授权链接参数不完整，无法生成授权链接"
-  exit 1
-fi
-```
-
-授权链接由 `auth.sh init` 统一构建并做最终完整性校验；Agent 不得手写、简写或改写授权链接。
-
----
-
-## 十、CLI 命令规范
-
-### 10.1 禁止行为
-
-```
-❌ 禁止：不带 --scope 参数执行 login
-❌ 禁止：自行修改 scope 格式或值
-❌ 禁止：自行创造 CLI 参数
-❌ 禁止：修改授权链接格式
-```
-
-### 10.2 检测工具设置
-
-> 📎 所有签约 `.sh` 脚本都会通过 `error_handler.sh` 间接初始化 `DEV_TOOL_NAME` 并设置 `PLATFORM`，无需手动设置。
-
-签约脚本通过 `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=...` 前缀。
+任何授权 token、deviceCode、未脱敏 CLI/MCP 输出和临时 URL 都不得进入普通日志、对话摘要、跨会话状态或宽权限临时文件。只有经过脚本白名单和当前上下文校验、且当前动作必须交付的授权 URL 可以进入该动作唯一对客正文。

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

@@ -1,256 +1,50 @@
-# 错误处理规范
+# 错误处理业务语义
 
-> ⚠️ **全流程错误参考文档**：本文档涵盖签约全流程（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 调用后执行错误处理。**本文档为说明参考，实际执行以脚本为准。**
+只在 Onboarding 脚本报错、需要解释登记分类或用户要求排障细节时读取本模块。运行时 Agent 只执行 flow 中的脚本入口；`../../normal/scripts/common.sh` 初始化 CLI 上下文，`scripts/network_retry.sh` 保持原 argv 执行有限重试，`scripts/error_handler.sh` 负责解包、分类、脱敏和登记输出。不得在脚本外追加 MCP 调用、`handle_error`、`unwrap_mcp` 或临时解析命令。
 
----
+## 分类与恢复
 
-## 错误检测函数索引
+| 内部分类 | 已验证触发 | 恢复边界 |
+| --- | --- | --- |
+| `MCP_AUTH_ERROR` | HTTP 401、`Authorization is empty`、非法认证信息 | 停止当前及剩余发现查询；校验 logout 成功后重新授权。合法失败阻断；结果不可唯一解析或当前 Agent 无法联网时，只申请联网权限并重试同一动作，不解释为用户本机或支付宝业务失败 |
+| `AUTH_MISMATCH` | `mccCode is not auth`、`salesProductCodes is not auth`、`scope is not auth` | 停止当前动作，只进入 `auth.sh mismatch`；logout 未确认成功前禁止重新授权 |
+| `MCP_SERVICE_ERROR` / `SERVICE_UNSTABLE` | 已识别连接、网络或服务异常 | 按下方有限重试规则处理；耗尽后记录受影响分支，依赖允许时继续其他独立分支，最终统一收口 |
+| `ERROR:<code>` | 当前响应中存在可识别业务错误 | 展示登记且脱敏的业务错误，修正业务条件前不重试 |
+| `CLI_ERROR:<message>` | CLI 失败、异常结构或结果不可唯一解析 | 隐藏原始输出，停止并按登记 CLI 错误恢复，不猜成功或空结果 |
+| `SUCCESS` | 唯一合法成功结构 | 才允许进入当前脚本的业务字段解析 |
 
-> ⚠️ `require_command` / `init_dev_tool_name` 定义于 `normal/scripts/common.sh`；`error_handler.sh` 会在加载公共函数后显式调用 `init_dev_tool_name`。以下错误处理函数定义于 `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_auth_mismatch` | 识别授权不匹配（MCC/产品/scope），停止当前操作并引导调用 `auth.sh mismatch` | - |
-| `handle_service_unstable` | 处理 MCP 服务不稳定，提示稍后重试 | - |
-| `handle_backend_error` | 处理后端业务错误（errorCode），展示错误信息、bizTips、checkedError | - |
+## 解包与业务错误
 
----
+`unwrap_mcp` 兼容纯业务 JSON、唯一 MCP `content[0].text` 信封和混合日志。混合输出只从完整闭合结构形成候选；多个信封或 JSON 候选冲突时不选择、不回显原始响应，并由错误检测阻断。每次 MCP 调用先把原 stdout 交给 `handle_error`，返回成功后才调用 `unwrap_mcp` 和当前脚本的业务解析；不得统一假定成功字段位于 `.success`。
 
-## 一、MCP 认证错误
+业务错误对象可能位于顶层、`data.response` 或 `errorContext.errorStack[]`。保留脚本当前字段优先级：读取 `errorCode` 的字符串或对象形式、`errorMessage|errorMsg`、`bizTips`、`checkedError`、`errorScene` 和 `errorSpecific`；只有已验证的服务写入协议 `data.success=false` 才优先使用 `data.subMsg|data.msg`，并忽略只表示外层调用成功的顶层 `msg="Success"`。`APP_MAX_ERROR` 只说明应用数量达到上限，引导复用已有上线应用或前往支付宝开放平台处理配额，不推断其他审核规则。
 
-### 识别关键词
-`HTTP 401`、`Authorization is empty`、`非法的认证信息`、`MCP 调用失败`
+`needRetry=true` 仍是业务提示，不构成自动重试授权。不得丢弃实际业务错误后改称“未知错误”，也不得把现有服务写入协议扩展到其他响应结构。
 
-### 错误码表格
-| 错误码 | 错误信息 | 说明 |
-|--------|----------|------|
-| `api_error` | `HTTP 401` + `Authorization is empty` | 未登录或授权已过期 |
-| `api_error` | `非法的认证信息` | 认证信息无效 |
-| `-32602` | `Authorization is empty` | MCP 请求缺少认证头 |
+## 网络重试与写后核验
 
-### 处理原则
-```
-✅ 检测到 HTTP 401 → 执行并校验 logout → 仅退出成功后引导用户重新授权
-❌ logout 失败 → 明确报错并停止重新授权，禁止宣称已退出登录
-✅ 清理对话上下文中的授权相关数据
-✅ 提供清晰的错误说明和下一步操作指引
-❌ 禁止自动重试 MCP 调用（会导致相同的认证错误）
-❌ 禁止静默忽略错误
-❌ 禁止跳过登录流程直接继续
-```
+- `MCP_SERVICE_ERROR`、`SERVICE_UNSTABLE` 和已识别本地网络错误：初次调用后最多重试 2 次，每次间隔 3 秒，始终复用完全相同的 argv、请求 JSON、业务请求号、资源名和动态字段。
+- 认证、授权不匹配、参数、业务错误和结构歧义不进入网络重试。stderr 不拼入待解析 JSON。
+- 只读调用可使用完整重试预算。非幂等写操作只有明确 `NOT_SENT` 才自动重试；DNS 失败、connection refused 或宿主在连接前明确拒绝网络访问可归为 `NOT_SENT`。
+- timeout、连接中断、发送阶段不明和 `SERVICE_UNSTABLE` 一律归为 `MAYBE_SENT`，停止写重试并使用现有只读能力核验；无法确认输出 `UNKNOWN`。
+- 签约提交用签约查询核验；服务修改只有列表按完整 `serviceId` 和五项资料精确匹配才算成功；服务新建和应用创建不得按同名候选猜测；应用提审只看现有应用信息状态。没有登记核验能力的公钥确认页不得凭页面或同名结果推断成功。
 
-### 错误示例
-```json
-{
-  "success": false,
-  "error": {
-    "code": "api_error",
-    "message": "MCP 调用失败: MCP 请求失败: HTTP 401 - {\"jsonrpc\":\"2.0\",\"error\":{\"code\":-32602,\"message\":\"非法的认证信息, Authorization is empty\"}}",
-    "action": "重新执行登录授权"
-  }
-}
-```
+`MESSAGE_RENDER_ERROR` 不是写操作是否发出的证据，不得据此自动重写。
 
-> 📎 处理脚本：见 `error_handler.sh` → `handle_mcp_auth_error()`
+## 授权轮询恢复
 
----
+`authorization_pending` 或自动轮询中 `whoami` 尚未形成有效本机登录态时，只由 `auth.sh wait` 在固定最多 12 次、未成功相邻查询间隔 5 秒内继续。耗尽后输出一次 `auth.pending`，等待用户明确表示页面操作已完成；登记表达只执行一次 `auth.sh confirm`，不得重启 `wait` 或自行循环 `login --complete`。`auth_expired` 才重新执行登录流程。
 
-## 二、MCP 服务不可用（网络/服务错误）
+公钥轮询次数、单次恢复和页面失效判断以 application phase 与 `app.sh` 为准，本模块不维护第二份状态机。
 
-### 识别关键词
-`MCP 调用失败`、`connection refused`、`timeout`、`network error`
+## 对客错误边界
 
-### 错误码表格
-| 错误码 | 错误信息 | 说明 |
-|--------|----------|------|
-| `api_error` | `MCP 调用失败` 非 401 | 网络或服务异常 |
-| `api_error` | `connection refused` | 无法连接服务器 |
-| `api_error` | `timeout` | 请求超时 |
+后端和 CLI 错误必须经 `sanitize_customer_error_text` 与登记 renderer 输出。`{{`、`}}`、`<INTERNAL_`、临时 URL、deviceCode、Authorization、`Payment-Proof`、token、password、secret、key、证书头以及未脱敏响应只能变为受控隐藏文案；普通业务错误应保留可操作内容。禁止向用户输出 trace、原始 MCP/CLI 文本、内部 marker 或技术栈。
 
-### 处理原则
-```
-✅ 检测到网络错误 → 沙箱化 Agent 环境提示申请可联网权限重试同一命令，其他环境提示用户检查网络
-✅ 提供网络排查指引
-❌ 禁止自动重试多次（会加剧服务器压力）
-❌ 禁止静默忽略错误
-```
+错误正文必须说明受影响分支和确定下一步；网络预算耗尽不立即增加“重试/退出”确认，而是在其他可推进分支完成后统一收口。脚本 stdout 是登记的唯一对客正文，内部事实行按 flow 剔除。
 
-> 📎 处理脚本：见 `error_handler.sh` → `handle_mcp_service_error()`、`handle_service_unstable()`
+## 维护边界
 
----
-
-## 三、授权信息不匹配
-
-### 识别关键词
-`mccCode is not auth`、`salesProductCodes is not auth`、`scope is not auth`
-
-### 错误类型
-| 错误码 | 错误信息 | 说明 | 处理方式 |
-|--------|----------|------|----------|
-| `AE05010000001200` | `mccCode is not auth` | 经营类目未授权 | logout → 重新授权 |
-| `AE05010000001200` | `salesProductCodes is not auth` | 产品未授权 | logout → 重新授权 |
-| - | `scope is not auth` | 授权 scope 不满足 | logout → 重新授权 |
-
-### 处理原则
-```
-✅ 检测到授权不匹配 → 停止当前操作 → 调用 auth.sh mismatch → 由 mismatch 执行 logout 后重新授权
-✅ 重新授权时使用正确的 scope（根据当前 salesCode 确定）
-✅ 多查询流程中检测到认证失败或授权不匹配 → 立即停止剩余查询；重新授权后只恢复未执行查询，主体无法确认一致时重新查询全部适用状态
-❌ 禁止：检测到授权范围不满足后继续执行后续操作
-❌ 禁止：不执行 logout 直接重新登录
-```
-
-> 📎 处理脚本：见 `error_handler.sh` → `handle_auth_mismatch()`，以及 `scripts/auth.sh mismatch`
-
----
-
-## 四、登录授权错误
-
-### 识别关键词
-`authorization_pending`、`auth_expired`
-
-### 错误码表格
-| 错误码 | 说明 | 处理方式 |
-|--------|------|----------|
-| `authorization_pending` | 用户尚未扫码或未确认授权 | 继续等待或提示用户 |
-| `auth_expired` | 授权已过期（10分钟） | 重新执行登录流程 |
-
-### 处理原则
-```
-✅ 检测到 authorization_pending → 提示用户继续扫码
-✅ 检测到 auth_expired → 重新执行登录流程
-❌ 禁止：自动轮询检查授权状态
-❌ 禁止：循环调用 login --complete
-```
-
-> 📎 处理脚本：授权确认逻辑见 `scripts/auth.sh confirm`
-
----
-
-## 五、后端业务错误
-
-### 响应格式
-```json
-{
-  "errorCode": "xxx",
-  "errorMessage": "错误描述",
-  "bizTips": "业务提示（可展示给用户）",
-  "needRetry": true,
-  "resultObj": {
-    "checkedError": [
-      { "errorDesc": "字段级校验错误描述" }
-    ]
-  }
-}
-```
-
-> ⚠️ 有些 MCP 返回会把真实业务响应包在 `data.response` 或 `errorContext.errorStack[]` 下。错误检测必须优先定位业务错误对象：既要兼容 `errorCode: "xxx"`，也要兼容 `errorCode: { "code": "xxx", "desc": "...", "message": "...", "errorScene": "...", "errorSpecific": "..." }`。常规错误继续按 `errorMessage` / `errorMsg` / `errorCode.desc` / `errorCode.message` 等既有字段处理；只有已验证的当前服务写入协议 `data.success=false` 才优先读取 `data.subMsg` / `data.msg`，并忽略仅表示外层调用成功的顶层 `msg="Success"`。不得把该优先级扩展到其他响应结构，也不得丢弃真实业务错误后兜底为“未知错误”。
-
-### 处理原则
-```
-✅ errorCode 存在 → 展示 errorMessage
-✅ data.success=false → 优先展示 data.subMsg / data.msg，不把顶层 msg="Success" 当作业务错误
-✅ 如有 bizTips → 一并展示给用户
-✅ 如有 checkedError → 逐条展示字段级校验错误描述
-✅ 如有 errorScene / errorSpecific → 一并展示，便于技术支持定位
-✅ createApplication 返回 APP_MAX_ERROR → 告知用户应用数量达到上限，引导复用已有上线应用或前往支付宝开放平台处理配额
-✅ needRetry=true → 告知用户可以重试
-❌ 禁止：忽略 errorCode 继续执行
-❌ 禁止：向用户暴露技术性内部错误
-❌ 禁止：只输出"未知错误"而丢弃 errorCode / bizTips / checkedError
-```
-
-> 📎 处理脚本：见 `error_handler.sh` → `handle_backend_error()`
-
----
-
-## 六、快速集成用法
-
-> ⚠️ 各 `.sh` 脚本已内置错误检测（source `error_handler.sh` + 调用 `handle_error`）和 MCP 信封解包（`unwrap_mcp`），Agent 执行脚本时无需额外处理。
-
-在**直接执行 MCP 调用**（非通过脚本）的场景，需注意 `alipay-cli mcp call` 返回 MCP 协议信封，业务 JSON 被包在 `content[0].text` 里，必须先解包。CLI stdout 混有日志时，`unwrap_mcp` 只提取唯一可确定的信封或 JSON；存在多个候选时不猜测，保留原文并增加歧义标记，后续 `handle_error` 将按非 JSON 异常阻断：
-
-```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 信封解包（unwrap_mcp）                                    │
-│   所有 mcp call 返回 {content:[{text:"<业务JSON>"}]}            │
-│   必须先 unwrap_mcp 解包，再按当前模块契约解析业务字段          │
-├─────────────────────────────────────────────────────────────────┤
-│ 🔐 MCP_AUTH_ERROR                                               │
-│   关键词：HTTP 401 / Authorization is empty / 非法的认证信息     │
-│   动作：引导用户重新登录授权                                     │
-├─────────────────────────────────────────────────────────────────┤
-│ 🌐 MCP_SERVICE_ERROR                                            │
-│   关键词：MCP 调用失败 / connection refused / timeout            │
-│   动作：沙箱化 Agent 环境申请可联网权限重试；其他环境提示检查网络连接 │
-├─────────────────────────────────────────────────────────────────┤
-│ 🔄 AUTH_MISMATCH                                                │
-│   关键词：mccCode is not auth / salesProductCodes is not auth    │
-│   动作：退出登录 → 重新授权                                      │
-├─────────────────────────────────────────────────────────────────┤
-│ 📋 BUSINESS_ERROR                                               │
-│   关键词：errorCode 字段存在（含 data.response 或 errorStack）    │
-│   动作：展示错误信息 + bizTips + checkedError + errorScene       │
-├─────────────────────────────────────────────────────────────────┤
-│ ⚠️ CLI_ERROR                                                    │
-│   关键词：success=false 但无 errorCode                           │
-│   动作：展示错误信息 + bizTips（如有）+ checkedError（如有）     │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 八、调用位置索引
-
-| Step | MCP 调用位置 | 建议使用的检测函数 |
-|------|---------------|-------------------|
-| Step 1 环境检查 | alipay-cli 可用性与安装检查 | 由 `../../normal/alipay-cli-env.md` 处理，不执行登录状态预检 |
-| 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 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） |
-
----
-
-## 九、注意事项
-
-```
-✅ 必须：任何 MCP 调用后都必须进行错误检测
-✅ 必须：给用户友好的错误提示
-✅ 必须：提供下一步操作指引
-❌ 禁止：忽略错误继续执行
-❌ 禁止：给用户显示技术性错误信息（如 traceId、内部错误码等）
-```
+修改错误处理时至少覆盖：合法 JSON、唯一 MCP 信封、混合输出、多个候选、认证错误、授权不匹配、业务错误、网络错误、空列表和异常结构。新增未封装 MCP 调用必须先取得确定 schema，并同步脚本、业务模块、flow、MCP 契约 fixture 和测试；禁止用占位方法或通用 JSON 模板临场试调。