@alipay/alipay-aipay 1.7.0 → 1.7.2

package/skill-pre/references/onboarding/modules/app-release.md

@@ -0,0 +1,90 @@
+# 应用发布业务语义
+
+本模块解释应用类型、候选复用、创建、公钥与提审边界。运行时命令以 `../flow.md` 为准；参数、MCP payload、轮询、解析和终态由 `scripts/app.sh` 实现。正常路径不从本模块复制命令或构造 MCP。
+
+## 当前主流程 MCP 调用
+
+| MCP 方法 | 用途 |
+| --- | --- |
+| `apprelease.queryApplicationList` | 查询应用列表 |
+| `apprelease.createApplication` | 创建应用 |
+| `apprelease.queryApplicationInfo` | 查询应用详情 |
+| `apprelease.createKeyConfirmPage` | 创建应用公钥确认页 |
+| `apprelease.queryApplicationSecurityKey` | 查询 RSA2 应用公钥和支付宝公钥 |
+| `apprelease.submitApplicationAudit` | 提交应用审核 |
+
+应用与服务方法统一使用 `{"request":{...}}`，不得混入签约的 `ctx`。完整请求只在脚本维护。
+
+### 参数结构对照表
+
+| MCP 方法 | 脚本约束 |
+| --- | --- |
+| `apprelease.queryApplicationList` | 只传 `request.appTypes` |
+| `apprelease.createApplication` | 由产品上下文绑定应用类型和移动平台字段 |
+| `apprelease.queryApplicationInfo` | 传当前完整 `appId` |
+| `apprelease.createKeyConfirmPage` | 传当前 `appId`、`RSA2` 和用户公钥 |
+| `apprelease.queryApplicationSecurityKey` | 传当前 `appId`，可带同一用户公钥 |
+| `apprelease.submitApplicationAudit` | 传当前完整 `appId` |
+
+## 类型与候选
+
+- AI 按量付费、AI 网页应用收款：`WEBAPP`。
+- AI 移动应用收款：`MOBILEAPP`；通过 Skill 创建只支持 `IOS|ANDROID|ALL`，`ALL` 仅表示 iOS + Android。
+- 应用列表请求只按 `appTypes` 查询；返回项只能称为同类型候选，不得声称已绑定当前支付产品。
+- `bundle_id` 映射为脚本 `--bundle-id` 和 MCP `bundleId`。`appSign` 只表示用户已有的 Android 应用签名摘要，不是应用公钥、私钥或支付签名串；不得用应用公钥密钥工具获取，也不得用包名、Bundle ID 或占位值推断。
+- HarmonyOS 代码开发受支持，但 HarmonyOS 移动应用不通过 Skill 创建，也不得向脚本或 MCP 传 `HARMONY`。固定输出：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message application-harmony-manual-create --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+HarmonyOS 用户完成平台操作后只重查下方列表，不跑全量 discovery；仅实际 `ON_LINE` 可复用，用户表达不证明创建、配置或上线。
+
+`ON_LINE` 才可复用。空候选收材料；非空先按 flow Step 4 识别公钥获取方式回复，再接受当前 appId 或 `新建+材料`；仅未上线时可 `暂不新建`；无效选择不写。材料齐后由固定组合入口轻量查询并比较快照：`UNCHANGED` 创建并生成公钥页；`CHANGED_EMPTY` 零写入送达空事实后，以新快照和原材料同回合重跑，不等待回复；`CHANGED_NONEMPTY` 零写入送达新候选后重选：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" app create-from-snapshot --product-type "$PRODUCT_TYPE" --sales-code "$SALES_CODE" --previous-candidates-json "$APP_CANDIDATES_JSON" [移动平台参数] --defer-open "<用户明确提供的完整publicKey>" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+组合入口只编排既有 `list -> comparator -> create -> key`。写入前 `CONTRACT_ERROR|PREWRITE_FAILED` 自动恢复一次，`SNAPSHOT_REFRESH_REQUIRED` 刷新候选；耗尽按 flow 收口并继续其他分支。子步骤只转发登记终态，技术正文和 marker 禁止对客。权限/授权按 flow 恢复；写入前恢复后可继续，写入后禁止重放。创建 `UNKNOWN` 只重查列表，公钥页 `FAILED|UNKNOWN` 只查公钥状态；核验后仍不明则输出业务待办并收口，禁止重建应用/页面。独立 `app key` 只用于复用缺钥应用，或新建成功后公钥页调用前权限阻断；`app create` 仅由组合入口调用。HarmonyOS 仍独立 `app list`。
+
+材料齐或非空明确新建即确认创建；`新建/我要新建` 只是示例，不要求逐字回复，等价明确意图均接受；之后只补缺项。`WEBAPP` 需公钥；`MOBILEAPP` 需平台资料和公钥。Agent 按明确语义归一化：仅 iOS→`IOS`，仅 Android→`ANDROID`，两类→`ALL`；原枚举兼容，含糊/矛盾时不猜。脚本只传这三个枚举。`APP_WEB_INITIAL` 仅限 `aipay|webpay`，`APP_MOBILE_INITIAL` 仅限 `apppay`：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message material-collect --category application --state APP_WEB_INITIAL --product-type "$PRODUCT_TYPE" --input-id "$USER_INPUT_ID" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message material-collect --category application --state APP_MOBILE_INITIAL --product-type "$PRODUCT_TYPE" --input-id "$USER_INPUT_ID" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+预发版应用列表成功查询后，discovery 在摘要后立即展示 `application.key.methods`：自备合规密钥、手动下载安装官方密钥工具、打开随包本地离线页面。候选选择、空候选和首次应用资料消息复用同一目录正文，恢复时不丢失获取方式；查询失败不进入本分支。在当前方式选择上下文中，`1/2/3`、`方式一/二/三` 均为合法的公钥准备选择，不按无效 appId 或通用确认处理；获取方式不是必经步骤，直接提供公钥或完整 appId 仍按当前材料和候选处理；具体输入分流和动作只按 flow Step 4 与 5.3。移动应用仍须补齐所选平台资料。
+
+预发版不自动下载密钥工具；`key-tool` 和旧下载脚本兼容入口只提供手动下载安装引导。用户明确选择方案3后，flow 登记的 `preview open-keygen` 只尝试打开一次固定静态 HTML；用户自行点击生成并下载保存，Agent 不操作生成按钮、不读取页面密钥或下载文件。打开失败、无 GUI 或用户反馈页面无法使用，进入固定官方工具手动安装降级；不建本地服务、不联网生成、不循环 opener。选择获取方式不替代创建/复用意图或后续公钥确认。
+
+官方工具引导保留 PKCS#8 / PKCS#1 格式说明；本地页面沿用用户提供的单文件实现，在浏览器内用 Web Crypto 生成 RSA-2048 密钥、公私钥配对校验，提供应用公钥与两种私钥格式的本机下载。页面不联网、不使用浏览器持久化存储、不自动回传任何密钥；Agent 只接收用户主动提供的应用公钥。HTML 能力不改变现有应用类型、MCP 参数、写前快照、设钥确认及提审条件。
+
+## 公钥边界
+
+应用公钥必须由用户自行生成并明确提供。Agent 禁止代为生成密钥对、请求或处理私钥、补全/改写公钥、添加 PEM 头尾，或在缺少公钥时调用 `createKeyConfirmPage`。公钥的业务使用仅限当前 `app.sh key|verify-key|verify-key-and-audit`，不得在回复、摘要、普通日志、跨会话业务状态或宽权限临时文件中复述或保存。预发版另在用户明确同意会话采集时按 `normal/conversation-telemetry.md` 记录其主动发送的消息，公钥不属于私钥脱敏对象；不得为采集读取页面、剪贴板或密钥文件。
+
+CLI 子命令均传 `--product-type` 并由脚本上报 `PRODUCT`；`appId/publicKey` 保持位置参数。正常新建由 `create-from-snapshot` 输出公钥页；仅上述独立设钥场景执行 `runtime.mjs app key --product-type "$PRODUCT_TYPE" --defer-open`。两者都先独立送达 stdout，再执行 `app open-key-page`；不得手写消息。opener 失败时可用宿主浏览器打开已交付 URL 一次，仍失败保留复制兜底再查询；禁止搜索、改写、填写或代扫码。自动打开/轮询不能替代 URL 交付，pending 不得与 `application.key.page` 合并。
+
+只展示校验后的实际 `confirmPageUrl` 裸 URL，禁二维码链接和 `alipays://`。不推定有效期；仅用户反馈页面/扫码问题时重建。
+
+`app.sh key` 成功须输出 `KEY_PAGE_RESULT=READY_TO_OPEN` 和 `KEY_PAGE:READY_TO_OPEN`；响应不明、URL 非法或消息失败为 `UNKNOWN`，禁生成第二页。页面已交付但状态保存失败输出 `KEY_PAGE_STATE:SAVE_FAILED`，`open-key-page` 降级 `KEY_OPEN:LINK_ONLY`，显式参数仍可查询。
+
+RSA2 状态只看应用公钥字段，支付宝公钥不能反证。`verify-key|verify-key-and-audit` 最多 20 次、间隔 2 秒；耗尽后明确完成表达交给 `onboarding_recovery_runner.mjs application-key`，每次只查一次。
+
+## 提审与结果
+
+新建确认后用 `verify-key-and-audit` 复用最终密钥响应完成双公钥 guard 并提审；复用缺钥时 `verify-key` 后再 `reuse`。公钥未确认或 guard 失败禁提审。
+
+`APPLICATION_CREATE_RESULT=SUCCESS|FAILED|UNKNOWN` 区分创建；未知只刷新列表事实，不归因候选差异。`KEY_PAGE_RESULT=FAILED|UNKNOWN` 在调用后都只用同一公钥执行一次 `reconcile-key`，不生成第二页；`CONFIRMED` 才提审。权限/授权恢复后只做阶段允许的最新只读动作。`APPLICATION_AUDIT_RESULT=SUBMITTED|FAILED|UNKNOWN` 区分提审，未知不重提；`FLOW:AUDIT_SUBMITTED` 仅来自成功或只读核验。config 探针失败输出 `APP_FLOW:RETRY_WITH_LOCAL_CONFIG_PERMISSION` 和 `ALIPAY_PUBLIC_KEY_EXPORT_STATUS=RETRY_WITH_LOCAL_CONFIG_PERMISSION`，取权重试一次且不重开页面；仍失败输出 `ALIPAY_PUBLIC_KEY_EXPORT_STATUS=MANUAL_CONFIGURATION_REQUIRED`，由 `customer-messages.json` 的应用人工配置目录文案引导。
+
+三个产品在 `onboarding_only` 和 `full_process` 中，应用分支取得本轮可收口结果后均先独立交付应用结果，再进入总收口；紧邻总收口也不合并，同一结果已交付则不重复。总收口仅保留应用发布状态和待办，不重复应用详情。仍在等待材料、公钥或恢复时沿用原分支；未取得实际 appId 的失败/未知不得编造 appId，保留错误和待办收口。应用分支对客结果只使用：
+
+```bash
+node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message application-result --app-id "$APP_ID" --actual-status "$ACTUAL_STATUS" [--next-action "$NEXT_ACTION"] [--app-key-save-path "$APP_KEY_SAVE_PATH"] --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
+```
+
+执行该命令时，只要 stdout 非空，必须同时取得唯一 `ALIPAY_AIPAY_INTERNAL:CUSTOMER_MESSAGE_DELIVERY_REQUIRED=application.operation.result`，并在下一步先将 stdout 原文作为独立用户可见消息送达；送达前禁止执行 closeout 或把应用结果并入总收口。送达后同一工作回合继续，不等待用户确认，不以最终答复结束当前回合。`需人工配置` 分支同样必须交付，但禁止传公钥保存路径。
+
+输出实际 appId、状态和下一步；若本轮 `ALIPAY_PUBLIC_KEY_EXPORT_STATUS=EXPORTED`，必须把该路径原样作为 `APP_KEY_SAVE_PATH` 传入，runner 会对客展示“当前 appId: xxx 对应的支付宝公钥保存在:xxx”。只展示路径，禁止复述支付宝公钥内容。待审核、待设钥、需人工配置、失败或未知不得称发布完成。`APP_FLOW:RETRY_WITH_LOCAL_CONFIG_PERMISSION` 不渲染结果；`MANUAL_CONFIGURATION_REQUIRED` 固定传“需人工配置”且省略 `--next-action` 和 `--app-key-save-path`，由目录派生。写操作仅 `NOT_SENT` 自动重试；`MAYBE_SENT` 查询核验，无法确认进入 `UNKNOWN`，禁止同名猜测或重复创建/提审。

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

@@ -0,0 +1,43 @@
+# 登录授权业务语义
+
+本模块只解释授权业务语义。运行时命令、确认、终态和失败分支以 `../flow.md` 为准；参数校验、URL 构造、状态保护和解析由 `scripts/auth.sh` 实现。正常路径不预读本模块。
+
+## 产品授权范围
+
+| 产品 | 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 和 MCC 必须属于同一本轮动态上下文。MCC 必须携带 `mcc.sh resolve-plan` 输出且绑定当前 run 的 `MCC_CONTEXT_RECEIPT`，回执内产品、salesCode、MCC 编码和名称须与授权参数逐项一致；跨 run 或缺失回执都在任何 `whoami`、`login`、`login --complete`、`logout` 或 opener 前停止，不读取静态 MCC 表兜底。
+
+固定上下文通过后，`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_STATE:SAVE_FAILED`：授权页 stdout 已经安全生成并交付，但本地短时状态文件未能保存；不得重新生成页面，后续 opener 只能降级为 `AUTH_OPEN:LINK_ONLY`，`wait|confirm` 仍使用 flow 登记命令的显式上下文。
+- `AUTH_FLOW:PENDING`：有限轮询耗尽或单次恢复查询尚未得到有效本机登录态；不等于失败，也不证明用户未扫码。
+- `AUTH_FLOW:EXPIRED`：当前页面实际返回过期，旧页面和旧回复失效，重新执行 flow 登记的 init。
+- `AUTH_FLOW:SCOPE_MISMATCH|MCC_MISMATCH`：只能走 `auth.sh mismatch`。统一 runtime 的 `auth init` 在底层 init 唯一返回 mismatch 且 stdout 为空时，会在同一命令内自动调用既有 `auth.sh mismatch`，抑制中间 mismatch 终态并只透传最终结果；`wait|confirm` 返回 mismatch 时仍按 flow 显式调用 mismatch。logout 后置条件未成立前不得重授权；仍登录返回 `AUTH_FLOW:LOGOUT_STILL_LOGGED_IN`。
+- `AUTH_FLOW:AUTH_REQUIRED`：`whoami` 或已认证资源校验已证明当前 CLI 会话失效，且脚本已完成既有 logout 后置条件处理；按 flow 原样重新执行当前上下文的 `auth init` 一次，旧授权页不再作为恢复依据，再次命中时停止循环。
+- `AUTH_FLOW:RETRY_WITH_NETWORK`：当前 Agent 环境无法确认结果，申请联网权限后原样重试同一命令；不得解释为用户本机登录失败。
+- `AUTH_FLOW:RETRY_WITH_LOCAL_FS_PERMISSION`：授权状态命令 preflight 失败，或实际输出命中 CLI 私有状态写失败证据。可恢复阶段 stdout 为空；仅允许当前受控 runtime 命令访问 CLI 私有状态目录后原样重试一次；`wait|confirm` 保留短时授权状态，不重建授权页。Agent 禁止读取、列举、打印或复制已有凭据与日志；拒绝、不支持或重试仍命中同一 marker 时才输出最小失败说明。
+
+CLI `login --complete` 成功只表示页面侧确认完成，不代表本机已取得可用登录态。返回成功但状态字段不在白名单时，脚本先用 `whoami` 复核：有效登录继续 scope/MCC 校验，仍未形成登录态则保持 `PENDING`，不可确认则 `RETRY_WITH_NETWORK`。脚本仍需复核 `whoami`、scope，并以固定授权 URL 绑定 MCC；动态 MCC 还需复核 `MCC_CONTEXT_RECEIPT`。当前后端查询没有权威 MCC 返回字段，禁止声称做了响应 MCC 等值比较。
+
+## 页面与恢复
+
+授权页只允许 `https://aipay.alipay.com/cli-auth`，必含唯一 `deviceCode/productCode/mccCode`，只允许可选 `platform`；`mccContextReceipt` 只用于本地上下文校验和短时状态，不进入授权 URL。禁止 CLI `verification_url`、额外参数、重复参数和 fragment。页面 stdout 必须先作为独立对客消息送达，再执行 `auth.sh open` 和 `auth.sh wait`，后续 pending 或收口不得合并进同一回复。
+
+`wait` 生产最多查询 12 次，未成功的相邻查询间隔 5 秒，成功或过期立即停止。耗尽后按 flow 登记命令把用户原始回复和当前 `USER_INPUT_ID` 交给统一 runtime 的 `onboarding-recovery auth-confirm`；runner 复用统一肯定语义判定器并对该用户消息幂等计数，接受 `继续`、`好了`、`已完成`、`确认`、`OK` 和兼容输入 `1`，每次接受只执行一次 `auth.sh confirm`，不重启自动轮询。否定、疑问、取消、修改意见或含糊输入不查询。
+
+授权对客正文只由 `auth.sh` 调用消息目录生成。初始页面不得提前要求回复完成；pending 的自然语言提示、允许回复和授权页返回提示都不在本模块维护副本。
+
+## 状态保护
+
+短时授权上下文使用当前用户私有临时目录和 `0600` 原子文件，拒绝符号链接。状态可见时显式参数必须逐项一致；状态不可见时仅允许完整显式上下文降级。新 init 只有先通过固定上下文校验才可替换旧状态；上下文改变且 CLI 仍登录时必须进入 mismatch，不得复用旧 deviceCode。
+
+任何授权 token、deviceCode、未脱敏 CLI/MCP 输出和临时 URL 都不得进入普通日志、对话摘要、跨会话状态或宽权限临时文件。只有经过脚本白名单和当前上下文校验、且当前动作必须交付的授权 URL 可以进入该动作唯一对客正文。

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

@@ -0,0 +1,62 @@
+# 错误处理业务语义
+
+只在 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` | 非 JSON 传输错误中的 HTTP 401/认证强证据；JSON 顶层或登记 error/response 层中的数字/字符串 `401`、`unauthorized`、`Authorization is empty`、非法认证信息、`用户未登录`、`not_logged_in` 等明确登录失效证据；已认证资源动作顶层或 `data.logged_in=false` | 停止查询组；logout 后置条件成立后重授权。仍登录则阻断；不可确认或无网络时只重试同一动作，不解释为用户本机或支付宝业务失败。成功候选、说明或请求示例中的相同文本不构成认证错误 |
+| `AUTH_MISMATCH` | `mccCode is not auth`、`salesProductCodes is not auth`、`scope is not auth` | 停止当前动作，只进 `auth.sh mismatch`；logout 后置条件未成立前禁重授权 |
+| `MCP_SERVICE_ERROR` / `SERVICE_UNSTABLE` | 已识别连接、网络或服务异常 | 按下方有限重试规则处理；耗尽后记录受影响分支，依赖允许时继续其他独立分支，最终统一收口 |
+| `DISCOVERY_FLOW:RETRY_WITH_NETWORK` | discovery 子查询重试耗尽，且原始输出包含 DNS、连接、timeout、socket/TLS、`fetch failed`、`network_error`、`网络连接失败` 或连接前沙箱禁网强证据 | 只在无授权阻断时输出一次；暂存首次 stdout，申请联网权限后原样重试同一 discovery 命令一次。拒绝、不支持或再次命中时停止申请，只送达最新一次既有 stdout |
+| `DISCOVERY_FLOW:RETRY_WITH_LOCAL_FS_PERMISSION` | discovery 任一子查询在 CLI 调用前探测失败，或只读调用后命中 CLI 私有状态权限证据 | 授权阻断优先；本次不渲染 discovery 摘要，取得两个 CLI 私有状态目录权限后原样重试同一 discovery 命令一次，不改产品、salesCode 或签约复用回执 |
+| `CLI_LOCAL_FS_PERMISSION` | 受控 CLI 动作 preflight 失败；或原始 stdout+stderr 命中私有状态写失败强证据，或私有状态路径与权限错误组合 | auth 使用唯一 `AUTH_FLOW:RETRY_WITH_LOCAL_FS_PERMISSION`；其他未发送或只读动作使用唯一 `CLI_FLOW:RETRY_WITH_LOCAL_FS_PERMISSION`。取得目录权限后原样重试一次；写动作已执行则保持 `MAYBE_SENT` 并只核验/标记 `UNKNOWN`，不得重放 |
+| `APP_LOCAL_CONFIG_PERMISSION` | 已取 RSA2 支付宝公钥但 config 探针失败 | stdout 空；输出两个本地权限 marker，取权后原样重试当前 app 命令一次，不重开公钥页 |
+| `OPEN_ERROR_KIND` | URL 已交付但 opener 失败 | 保留 URL 兜底；诊断不对客，不改写为业务、网络或授权失败 |
+| `ERROR:<code>` | 当前响应中存在可识别业务错误 | 展示登记且脱敏的业务错误，修正业务条件前不重试 |
+| `CLI_ERROR:<message>` | CLI 失败、异常结构或结果不可唯一解析 | 隐藏原始输出，停止并按登记 CLI 错误恢复，不猜成功或空结果 |
+| `SUCCESS` | 唯一合法成功结构 | 才允许进入当前脚本的业务字段解析 |
+
+发现阶段的单分支失败不得伪装为空列表，也不得回滚其他已成功分支；认证失效或授权不匹配属于查询组全局阻断，重新授权后恢复尚未执行的查询，主体一致性无法确认时重新查询全部适用状态。`logged_in=false` 只在已认证的签约、服务、应用和上传等资源动作中属于认证失效；`auth.sh whoami` 的成功未登录结果仍是正常登录入口，失败响应即使携带该字段也不能证明已退出。discovery 的恢复优先级固定为真实认证/授权阻断、本地 CLI 状态权限、网络权限、普通分支失败；`AUTH_FLOW:RETRY_WITH_NETWORK|RETRY_WITH_LOCAL_FS_PERMISSION|LOGOUT_STILL_LOGGED_IN` 不是 discovery 子查询的认证失效证据，不得映射为 `AUTHORIZATION_INVALID`。
+
+discovery runner 的并发子查询不得让每个子进程各自 logout。三张截图固定串行上传，禁止多个 `alipay-cli file upload` 进程并发读取认证态；截图和 discovery 子脚本在受抑制环境下只上报一次认证失效事实，不渲染“正在退出当前登录”，由 flow 登记的唯一授权恢复入口处理。
+
+## 解包与业务错误
+
+`unwrap_mcp` 兼容纯业务 JSON、唯一 MCP `content[0].text` 信封和混合日志。所有受控 CLI 捕获先合并 stdout/stderr 检查 `写入临时文件失败|删除凭据文件失败|can't rename log file` 强证据，或 `poll_state.enc.tmp|session.enc|.alipay-cli/credentials|alipay-cli/logs` 与 `permission denied|operation not permitted|EACCES|EPERM` 组合；命中时不得按成功 JSON 或 `network_error` 处理，裸后端 `permission denied` 不算本地权限。其他 CLI 捕获再执行唯一性解析：单个 JSON 加普通日志可接受，相同 JSON 重复可去重，多个不同 JSON 或成功/失败冲突不得选择任一路，也不得回显原始响应。每次 MCP 调用先把唯一原始结果交给 `handle_error`，返回成功后才调用 `unwrap_mcp` 和当前脚本的业务解析；不得统一假定成功字段位于 `.success`。认证分类只扫描真实响应错误层，禁止递归扫描成功候选、业务说明或请求示例中的错误样例。
+
+每次 logout 失败后只执行一次 `whoami` 后置核验；logout 明确成功时无需额外核验，最多尝试 3 次 logout。`whoami` 后置核验必须先满足唯一 JSON、退出码为 0 且 `detect_error=SUCCESS`，再读取类型正确的 `logged_in/is_expired`；业务失败响应即使携带 `logged_in=false` 也不能证明已退出。logout 网络/服务异常、冲突输出或结果无法确认时，即使 `whoami` 仍显示已登录，也只能转 `AUTH_FLOW:RETRY_WITH_NETWORK` 并重试同一动作。logout 是可由 `whoami` 验证最终状态的幂等恢复动作：明确业务失败且仍登录时，脚本内部使用“初次 + 2 次”固定预算、间隔 3 秒重试完全相同的 logout；任一次确认已退出即继续，全部耗尽且仍登录才转 `AUTH_FLOW:LOGOUT_STILL_LOGGED_IN`。所有失败分支都不得执行 login。每个 auth 动作只允许产生一个最终 `AUTH_FLOW:*`，具体恢复 marker 已由错误处理器输出时，调用方不得追加 `AUTH_FLOW:FAILED`。
+
+业务错误对象可能位于顶层、`data.response` 或 `errorContext.errorStack[]`。保留脚本当前字段优先级：读取 `errorCode` 的字符串或对象形式、`errorMessage|errorMsg`、`bizTips`、`checkedError`、`errorScene` 和 `errorSpecific`；只有已验证的服务写入协议 `data.success=false` 才优先使用 `data.subMsg|data.msg`，并忽略只表示外层调用成功的顶层 `msg="Success"`。`APP_MAX_ERROR` 只说明应用数量达到上限，引导复用已有上线应用或前往支付宝开放平台处理配额，不推断其他审核规则。
+
+`needRetry=true` 仍是业务提示，不构成自动重试授权。不得丢弃实际业务错误后改称“未知错误”，也不得把现有服务写入协议扩展到其他响应结构。
+
+## 网络重试与写后核验
+
+- `MCP_SERVICE_ERROR`、`SERVICE_UNSTABLE` 和已识别本地网络错误：初次调用后最多重试 2 次，每次间隔 3 秒，始终复用完全相同的 argv、请求 JSON、业务请求号、资源名和动态字段。连接前沙箱明确拒绝联网时立即结束子脚本预算，由 discovery 的单次权限恢复处理，不额外等待两次 3 秒。
+- discovery 只有强网络证据才输出 `DISCOVERY_FLOW:RETRY_WITH_NETWORK`；远端服务异常、业务错误、裸 `permission denied` 和响应结构异常仍保留既有失败分类。授权阻断优先且不得同时输出网络恢复 marker。
+- 认证、授权不匹配、参数、业务错误和结构歧义不进入通用网络重试。唯一例外是上述可验证最终状态的幂等 logout 恢复，它使用同一三次总预算且不经通用 `network_retry.sh`。stderr 不拼入待解析 JSON。
+- 只读调用可使用完整重试预算。非幂等写操作只有明确 `NOT_SENT` 才自动重试；DNS 失败、connection refused 或宿主在连接前明确拒绝网络访问可归为 `NOT_SENT`。
+- timeout、连接中断、发送阶段不明和 `SERVICE_UNSTABLE` 一律归为 `MAYBE_SENT`，停止写重试并使用现有只读能力核验；无法确认输出 `UNKNOWN`。
+- 签约提交用签约查询核验；服务修改只有列表按完整 `serviceId` 和五项资料精确匹配才算成功；服务新建和应用创建不得按同名候选猜测；应用提审只看现有应用信息状态。没有登记核验能力的公钥确认页不得凭页面或同名结果推断成功。
+
+`MESSAGE_RENDER_ERROR` 不是写操作是否发出的证据，不得据此自动重写。
+
+写动作除既有成功 marker 外，还必须输出动作级结果事实：签约 `SIGN_APPLY_RESULT=SUCCESS|FAILED|UNKNOWN`，服务保存 `SERVICE_SAVE_RESULT=SUCCESS|FAILED|UNKNOWN`，应用创建 `APPLICATION_CREATE_RESULT=SUCCESS|FAILED|UNKNOWN`，公钥确认页 `KEY_PAGE_RESULT=READY_TO_OPEN|FAILED|UNKNOWN`，应用提审 `APPLICATION_AUDIT_RESULT=SUBMITTED|FAILED|UNKNOWN`。`UNKNOWN` 表示禁止自动重复同一写动作，只能按 flow 进入当前分支待办或最终收口。
+
+## 授权轮询恢复
+
+`authorization_pending` 或自动轮询中 `whoami` 尚未形成有效本机登录态时，只由 `auth.sh wait` 在固定最多 12 次、未成功相邻查询间隔 5 秒内继续。耗尽后输出一次 `auth.pending`，等待用户明确表示页面操作已完成；登记表达只执行一次 `auth.sh confirm`，不得重启 `wait` 或自行循环 `login --complete`。`auth_expired` 才重新执行登录流程。
+
+公钥轮询次数、单次恢复和页面失效判断以 application phase 与 `app.sh` 为准，本模块不维护第二份状态机。
+
+## 对客错误边界
+
+后端和 CLI 错误必须经 `sanitize_customer_error_text` 与登记 renderer 输出。`{{`、`}}`、`<INTERNAL_`、临时 URL、deviceCode、Authorization、`Payment-Proof`、token、password、secret、key、证书头以及未脱敏响应只能变为受控隐藏文案；普通业务错误应保留可操作内容。禁止向用户输出 trace、原始 MCP/CLI 文本、内部 marker 或技术栈。
+
+错误正文必须说明受影响分支和确定下一步；网络预算耗尽不立即增加“重试/退出”确认，而是在其他可推进分支完成后统一收口。脚本 stdout 是登记的唯一对客正文，内部事实行按 flow 剔除。
+
+## 维护边界
+
+修改错误处理时至少覆盖：合法 JSON、唯一 MCP 信封、混合输出、多个候选、认证错误、授权不匹配、业务错误、网络错误、空列表和异常结构。新增未封装 MCP 调用必须先取得确定 schema，并同步脚本、业务模块、flow、MCP 契约 fixture 和测试；禁止用占位方法或通用 JSON 模板临场试调。

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

@@ -0,0 +1,49 @@
+# 产品签约业务语义
+
+本模块说明签约状态、材料和写操作边界。运行时命令与分支以 `../flow.md` 为准；请求参数、错误检测和解析由 `scripts/query_sign_status.sh`、`scripts/sign_status_parser.sh` 与 `scripts/ar_sign_apply.sh` 实现。
+
+## 当前主流程 MCP 能力
+
+| MCP 方法 | 用途 |
+| --- | --- |
+| `ar-sign.apply` | 提交当前产品签约申请 |
+| `ar-query.queryArInfosBySalesProd` | 查询当前 salesCode 的签约状态 |
+| `ar-support.queryMcc` | 查询当前产品支持的 MCC 类目树 |
+| `mccsearchservice.batchQueryMcc` | 查询命中且 `needSpecialQual=true` 的二级 MCC 特殊资质项 |
+
+`queryMcc`、签约查询和签约提交使用 `{"request":{...},"ctx":{}}`；`batchQueryMcc` 使用 `{"request":{"mccCodes":[...]}}`。完整 payload 只在脚本中维护；Agent 不从本模块自行构造 MCP 调用。
+
+`queryMcc` 成功树按同一 run、产品短时缓存，并逐项提供二级 MCC 编码、名称、描述和布尔型 `needSpecialQual`；任一必需字段缺失、为空或类型异常均失败关闭，不从其他字段回退。非精确编码时，Agent 应先理解用户原话，并在行业俗称或场景表达与目录用词可能不同时于首次调用一并提供有原话依据的行业概念或同义表达；本地词面结果为 `NONE`、候选冲突或低置信时，runner 可发出一次目录复核 marker，携带同一次 `queryMcc` 返回的当前产品 MCC 名称、描述和稳定引用；Agent 只返回该 marker 中的目录引用，runner 映射并校验为当前动态目录中的候选，不接受自由提交 MCC code。稳定引用由完整动态目录生成，并随候选裁剪和资格详情合并原样携带；最终方案 runner 不得按缩减后的候选数组重新编号。目录复核不新增 MCP/网络调用，语义扩充仍按 flow 最多完成两次。候选确定后，仅把其中 `needSpecialQual=true` 的编码集中交给一次 `batchQueryMcc` 获取特殊资质项；没有此类候选时不调用。多候选的完整树事实和资格详情按 run、产品、原查询、规范化语义词和选择回执缓存，用户选择时携带同一语义词且有效命中则两种 MCC 方法都不重调。缓存默认 1800 秒、无有效 run 不落盘；过期、损坏、符号链接、跨 run、语义词变化或事实哈希不一致时忽略并从完整当前产品目录重查，不修补缓存事实，不做产品级全量预取。
+
+## 签约状态
+
+`scripts/sign_status_parser.sh` 是授权内查询与独立签约查询的唯一解析实现。只有实际响应包含合法 `resultObj.arInfoList`，并唯一输出匹配的 `SIGN_STATUS`、`FLOW:*`、`AUTH_SIGN_QUERY_REUSABLE=true` 和 `AUTH_SIGN_REUSE_RECEIPT`，授权结果才优先通过回执复用；结构缺失、冲突或不可唯一解析时必须独立查询。兼容窗口内旧 `SIGN_STATUS + FLOW:*` 双参数仍可复用，`FLOW:` 前缀可带可不带，但 runner 必须重新校验产品、salesCode、状态和 flow 一致。
+
+| 状态 | 业务处理 |
+| --- | --- |
+| `NOT_SIGNED` | 按当前产品收集并校验材料，完整后直接提交 |
+| `SIGN_SUBMITTED` | 已提交等待生效，禁止重复签约 |
+| `SIGNED_EFFECTIVE` | 已生效，禁止重复签约 |
+| `OTHER_STATUS` | 展示实际状态并待核验，禁止提交 |
+| `QUERY_FAILED` | 只阻断签约分支，不推断为空或未签约 |
+
+合法复用组合固定为：`NOT_SIGNED + 当前产品未签约 FLOW`、`SIGNED_EFFECTIVE|SIGN_SUBMITTED + 当前产品已签约 FLOW`、`OTHER_STATUS + FLOW:OTHER_STATUS`。不得把 `OTHER_STATUS` 映射为已签约或未签约。
+
+现有查询请求不含 MCC，已验证响应也没有权威 MCC 字段。授权链路只能表述为授权 URL 精确绑定目标 MCC；没有新证据时不得增加响应 MCC 比较或修改 MCP payload。
+
+## 材料与提交
+
+- AI 按量付费：无需截图。
+- AI 网页应用收款：首页、商品页、支付页三张截图，支付页必须展示支付宝付款方式并等待用户付款，不得替换为支付成功页。
+- AI 移动应用收款：APP 名称和首页、商品页、支付页三张截图；签约状态参数固定按脚本的 `OFFLINE`。
+- 当前 MCC 返回 `needSpecialQual=true` 时，还需按本轮 `qualificationGroups` 选择一个资质组合。多个 group 是 OR 关系；同一 group 内多个 qualifications 是 AND 关系。`attaType` 为空或 null 的 qualification 只展示 `qualName` 作为文字条件，不上传、不进入 `specialLicense`；`attaType` 非空的 qualification 必须上传对应材料。
+
+材料缺失或校验失败时使用 flow 登记的 `materials.category.collect`，不得提交。完整通过后直接执行签约脚本，不增加确认。截图只走 `upload_screenshots.sh`。特殊资质上传和签约都必须携带本轮 run 的 `MCC_CONTEXT_RECEIPT` 与用户所选组合序号；脚本按回执精确校验 `licenseType` 顺序，纯文字组合不上传并在签约校验中使用空数组。
+
+特殊资质图片上传与首页/商品页/支付页截图上传一致，均调用 `alipay-cli file upload -s payMerchantcodeSkill --json` 并使用返回的图片引用值；三张页面截图固定串行上传，避免多个 CLI 进程并发读取认证态。`scripts/upload_special_license.sh` 按所选组合的材料顺序接收文件，从已校验回执派生内部 `licenseType`，再转换为 `[{licenseType,licensePic}]`；Agent 和用户不提供或看到类型码，`licensePic` 使用上传返回值，不要求 HTTPS URL。提交签约时，非空 `specialLicense` 作为 `businessProperty` 中与 `mccCode` 并列的字段传给 `ar-sign.apply`。
+
+提交成功只表示申请已受理，不等于签约生效；服务和应用分支按各自前置条件继续，不依赖本次签约写成功。写操作仅明确 `NOT_SENT` 时可自动重试；`MAYBE_SENT` 必须先用现有签约查询核验，无法确认进入 `UNKNOWN`，禁止重复提交。
+
+提交脚本必须输出动作级结果事实：`SIGN_APPLY_RESULT=SUCCESS` 表示提交已受理并继续；`SIGN_APPLY_RESULT=UNKNOWN` 表示响应不明且查询无法核验，签约分支进入未知待办；`SIGN_APPLY_RESULT=FAILED` 表示明确失败或明确未发送重试耗尽。三者不改变 MCP payload，也不能阻断服务和应用的独立前置分支。
+
+签约结果只通过消息目录的 `signing.operation.result` 输出。不得展示未登记审核规则、费率承诺、可收款时间或原始响应；费率、额度和生效问题引导用户在支付宝商家平台查询。