@alipay/alipay-aipay 1.5.2-beta → 1.5.3

package/README.md

@@ -1,5 +1,5 @@
 # 支付宝 AI 付 Skill
 
-支持按量付费、网站支付、APP 支付的代码开发与产品开通。
+支持 AI 按量付费、AI 网页应用收款、AI 移动应用收款的代码开发与产品开通。
 
 支付宝 AI 付站点：https://aipay.alipay.com/?from=alipay-aipay-skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alipay/alipay-aipay",
-  "version": "1.5.2-beta",
+  "version": "1.5.3",
   "description": "支付宝 AI 付 Skill 安装包 - 安装 Agent Skill，并检测/后台准备 alipay-cli；jq 可通过 --with-jq 尝试准备",
   "type": "module",
   "bin": {
@@ -14,8 +14,9 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "node scripts/run-tests.mjs",
     "test:windows-integration": "node --test test/windows-integration-contract.test.mjs test/integration-message-runner.test.mjs test/alipay-cli-env.test.mjs",
-    "prepublishOnly": "node scripts/validate-maintenance-alignment.mjs --release && node scripts/validate-process-optimization.mjs && npm run build"
+    "prepublishOnly": "npm test && node scripts/validate-maintenance-alignment.mjs --release && node scripts/validate-process-optimization.mjs && npm run build"
   },
   "keywords": [
     "alipay",

package/skill/VERSION

@@ -1 +1 @@
-1.5.2-beta
+1.5.3

package/skill/references/integration/flow.md

@@ -185,7 +185,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message win
 node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message start-confirm --product-type "$PRODUCT_TYPE" --product-name "$PRODUCT_NAME" --project-path "$PROJECT_PATH" --project-selection "$PROJECT_SELECTION" --language "$SERVER_LANGUAGE" --framework "$FRAMEWORK"
 ```
 
-runner 失败时不得展示手写方案或进入步骤 3。成功时必须同时取得唯一 `ALIPAY_AIPAY_INTERNAL:PROJECT_CONFIRM_RECEIPT=<receipt>`；缺失、重复或不可解析都视为失败。stdout 是步骤 2 唯一对客消息；Agent 必须把 stdout 原文作为非阻塞消息发给用户，不能用命令面板里的 stdout、折叠输出或“已渲染/已展示”说明替代。禁止添加 `<...>` 标签、“已输出完整方案”“服务声明已打印”、重复摘要或任何前后缀。发送后不停止、不等待回复，立即执行统一 runtime 的 `flow integration development --product-type "$PRODUCT_TYPE" --project-confirm-receipt "$PROJECT_CONFIRM_RECEIPT"`。loader 返回 `PROJECT_CONFIRMATION=VALID` 才能进入步骤 3；返回 `STALE` 时 stdout 已重新渲染当前标准方案并给出新 receipt，必须原文发送后使用新 receipt 立即重试一次；连续变化说明项目事实不稳定，停在步骤 2 核对，不要求用户输入确认口令。
+runner 失败时不得展示手写方案或进入步骤 3。成功时必须同时取得唯一 `ALIPAY_AIPAY_INTERNAL:PROJECT_CONFIRM_RECEIPT=<receipt>`；缺失、重复或不可解析都视为失败。stdout 是步骤 2 唯一对客消息；Agent 必须把 stdout 原文作为非阻塞消息发给用户，不能用命令面板里的 stdout、折叠输出或“已渲染/已展示”说明替代。禁止添加 `<...>` 标签、“已输出完整方案”“服务声明已打印”、重复摘要或任何前后缀。发送后不停止、不等待回复，立即执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" flow integration development --product-type "$PRODUCT_TYPE" --project-confirm-receipt "$PROJECT_CONFIRM_RECEIPT"`。loader 返回 `PROJECT_CONFIRMATION=VALID` 才能进入步骤 3；返回 `STALE` 时 stdout 已重新渲染当前标准方案并给出新 receipt，必须原文发送后使用新 receipt 立即重试一次；连续变化说明项目事实不稳定，停在步骤 2 核对，不要求用户输入确认口令。
 
 - `full_process`：`../normal/full-process-routing.md` 已使用同一个 `integration.start.confirm`，在同一方案中绑定检查器产生的项目来源、代码状态和其他产品，以及产品、项目路径、语言/框架和服务声明；消息送达后已经直接通过 receipt 进入本步骤，禁止再次渲染或要求确认。该消息不展示步骤清单，也不缩减执行范围；后续仍必须按当前产品完成本 flow 的全部适用接口、完成条件和 checklist。任一方案字段变化时必须返回完整接入 router 重新扫描、渲染并自动校验新的单条方案。该方案仍禁止提前展示 MCC、授权范围、产品开通材料或 onboarding 待办。
 
@@ -426,7 +426,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message a2m
 node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message a2m-execution-guard --project-path "$PROJECT_PATH" --service-url "$SERVICE_URL" --http-method POST --request-body-file "$POST_BODY_FILE" [--prior-receipt "$A2M_EXECUTION_RECEIPT"]
 ```
 
-只接受唯一 `ALIPAY_AIPAY_INTERNAL:A2M_EXECUTION=<json>`。`decision=RUN` 时保存新 receipt 并继续；`REUSE_PASSED` 复用同一项目和输入的本轮通过证据，不重复联调；`BLOCK_UNCHANGED` 表示失败后代码、配置和输入均未变化，禁止重跑；`UNKNOWN_PREVIOUS_EXECUTION` 表示上次命令可能已发出但未登记终态，禁止自动重跑，先核对实际结果。项目、服务 URL、方法或 POST body 变化时 runner 才会产生新的 `RUN` receipt。receipt 只保留在当前会话，不写跨会话业务进度。
+只接受唯一 `ALIPAY_AIPAY_INTERNAL:A2M_EXECUTION=<json>`。`decision=RUN` 时保存新 receipt 并继续；`REUSE_PASSED` 复用同一项目和输入的本轮通过证据，不重复联调；`BLOCK_UNCHANGED` 表示失败后代码、配置和输入均未变化，禁止重跑，将本轮 A2M 联调记录为失败并继续步骤 7/8；`UNKNOWN_PREVIOUS_EXECUTION` 表示上次命令可能已发出但未登记终态，当前没有登记的结果查询入口，禁止自动重跑或临时探测，固定记录联调结果未知并继续步骤 7/8。项目、服务 URL、方法或 POST body 变化时 runner 才会产生新的 `RUN` receipt。receipt 只保留在当前会话，不写跨会话业务进度。
 
 4. 仅 `decision=RUN` 时执行下列固定 runner 命令，输出固定联调说明后立即继续，不等待用户确认；禁止另写开始话术。服务地址和 HTTP 方法只用于后续实际命令，不在本消息中展示：
 
@@ -464,7 +464,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE
 node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE_URL" --method POST --body "@$POST_BODY_FILE" --buyer-id "$BUYER_2088" --auto-complete --require-payment-validation
 ```
 
-只传已确认的本机服务 URL、GET/POST、实际沙箱买家 userId 和项目内 POST body 文件；禁止传入自定义收银端点、`Payment-Proof` 或 attestation。只有同一次命令退出码为 0，且输出包含实际资源交付校验通过和敏感产物已清理，才能记录联调通过；204、空响应、空资源、明确验付/履约失败或异常 `Payment-Validation` 均不得通过。命令结束后立即执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message a2m-execution-result --receipt "$A2M_EXECUTION_RECEIPT" --outcome <PASSED|FAILED>` 并保存返回的新 receipt；进程被中断且无法登记时保留原 receipt，由下次 guard 返回 `UNKNOWN_PREVIOUS_EXECUTION`。失败后只有项目代码、配置或执行输入实际变化并取得新 `RUN` receipt 才能重新联调。
+只传已确认的本机服务 URL、GET/POST、实际沙箱买家 userId 和项目内 POST body 文件；禁止传入自定义收银端点、`Payment-Proof` 或 attestation。只有同一次命令退出码为 0，且输出包含实际资源交付校验通过和敏感产物已清理，才能记录联调通过；204、空响应、空资源、明确验付/履约失败或异常 `Payment-Validation` 均不得通过。命令结束后立即执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message a2m-execution-result --receipt "$A2M_EXECUTION_RECEIPT" --outcome <PASSED|FAILED>` 并保存返回的新 receipt；进程被中断且无法登记时保留原 receipt，由下次 guard 返回 `UNKNOWN_PREVIOUS_EXECUTION`。失败、阻断重复或结果未知都必须进入步骤 7 和最终 checklist 的失败/人工待验证项；只有项目代码、配置或执行输入实际变化并取得新 `RUN` receipt 才能重新联调。
 
 服务未就绪时固定使用 `integration.service.not_ready` 输出实际缺口和恢复动作；必须执行下列命令。不得运行测试、登记 `INT.A2M.SERVICE_READY=PASS` 或临场改写近似话术。
 

package/skill/references/integration/modules/sandbox/alipay-sandbox-tool.md

@@ -39,7 +39,7 @@ alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox \
 | 变量 | 来源 | 取值规则 |
 |------|------|----------|
 | `PLATFORM` | AI 编程工具识别结果 | 参考通用脚本 `../../../normal/scripts/detect_dev_tool.sh` 识别当前工具后使用其输出值；缺失时使用 `unknown`。例如 Codex 环境检测结果为 `codex` |
-| `PLATFORM_ID` | 当前流程 `run_id` | 由 `sandbox_config.sh` 通过 `common.sh` 从当前 telemetry run 读取；若宿主提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，新建 run 时 `run_id` 与该项目 ID 一致；缺失时不阻断沙箱创建 |
+| `PLATFORM_ID` | 当前流程 `run_id` | 由 `sandbox_config.sh` 通过 `common.sh` 从当前流程 run context 读取，遥测开启或关闭都不影响该值；若宿主提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，新建 run 时优先以该项目 ID 为 `run_id`；缺失时不阻断沙箱创建 |
 | `PRODUCT` | 不再传入 | 该 MCP 方法当前不需要产品上下文；不得把产品名写入 `--data` 或 CLI 环境变量 |
 
 **Codex 环境示例：**

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

@@ -166,7 +166,7 @@ source ~/.bashrc  # Linux/bash
 
 > ⚠️ **强制规范：检测结果仅供内部使用，禁止向用户输出！**
 
-AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚本通过 `scripts/common.sh` 提供的 `init_alipay_cli_context` 初始化 `DEV_TOOL_NAME`、`PLATFORM` 和 `PLATFORM_ID`；其中 `PLATFORM_ID` 取当前 telemetry `run_id`，用于把同一流程的 Skill 时间戳事件和 alipay-cli 上报关联起来。Onboarding 在产品确认后还通过同一公共脚本把 `aipay|webpay|apppay` 严格映射为 CLI 环境变量 `PRODUCT=AIPAY|WEBPAY|APPPAY`，所有环境检查、登录、查询、写入和文件上传调用都必须携带当前值；该字段不进入 MCP 请求 JSON。Integration 的产品确定前环境检查和快速沙箱仍不传 `PRODUCT`。若宿主环境提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，telemetry 新建 run 时直接使用该项目 ID 作为 `run_id`，脚本也会将同一值作为 `PLATFORM_ID`。文档示例或非 shell 流程可直接参考 `detect_dev_tool.sh` 的输出。
+AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚本通过 `scripts/common.sh` 提供的 `init_alipay_cli_context` 初始化 `DEV_TOOL_NAME`、`PLATFORM` 和 `PLATFORM_ID`；其中 `PLATFORM_ID` 取当前流程 `run_id`，用于关联同一流程，遥测开启或关闭都不影响该值。Onboarding 在产品确认后还通过同一公共脚本把 `aipay|webpay|apppay` 严格映射为 CLI 环境变量 `PRODUCT=AIPAY|WEBPAY|APPPAY`，所有环境检查、登录、查询、写入和文件上传调用都必须携带当前值；该字段不进入 MCP 请求 JSON。Integration 的产品确定前环境检查和快速沙箱仍不传 `PRODUCT`。若宿主环境提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，新建 run 时优先使用该项目 ID 作为 `run_id`，脚本也会将同一值作为 `PLATFORM_ID`。文档示例或非 shell 流程可直接参考 `detect_dev_tool.sh` 的输出。
 
 ```
 ❌ 禁止：向用户输出"环境检查完成，检测到您正在使用 Claude Code 环境"等检测结果

package/skill/references/normal/full-process-routing.md

@@ -68,7 +68,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message sta
 
 上面命令失败时不得展示手写确认或进入子流程。成功时必须同时保存唯一 `ALIPAY_AIPAY_INTERNAL:PROJECT_CONFIRM_RECEIPT=<receipt>`；缺失、重复或不可解析视为失败。参数必须是当前确定值，禁止直接拼用户输入。runner 校验产品 variant 并固定服务声明；实际范围仍取当前 Integration flow 和 checklist。
 
-分流、展示和交接事实必须来自 runner 内同一次 `scan` 对象；禁止用描述、Agent 自报或历史分类代替。`evidence` 仅内部校验，不进 renderer；Onboarding Step 1 前禁止传/猜 `mccCode`。方案同时满足 `INT.START.PLAN_DELIVERED` 与 `INT.SERVICE_STATEMENT.DELIVERED` 后，执行统一 runtime 的 `flow integration development --product-type "$PRODUCT_TYPE" --project-confirm-receipt "$PROJECT_CONFIRM_RECEIPT"`。只有内部 `PROJECT_CONFIRMATION=VALID` 才进入步骤 3；`STALE` 时 loader stdout 已重新渲染当前标准方案，必须原文发送并用新 receipt 立即重试一次，连续变化则停止核对。loader 在原位置记录兼容 stage 和预开发阅读 stage，禁止手工执行 telemetry；receipt 有效时禁止再次渲染 `integration.start.confirm`。
+分流、展示和交接事实必须来自 runner 内同一次 `scan` 对象；禁止用描述、Agent 自报或历史分类代替。`evidence` 仅内部校验，不进 renderer；Onboarding Step 1 前禁止传/猜 `mccCode`。方案同时满足 `INT.START.PLAN_DELIVERED` 与 `INT.SERVICE_STATEMENT.DELIVERED` 后，执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" flow integration development --product-type "$PRODUCT_TYPE" --project-confirm-receipt "$PROJECT_CONFIRM_RECEIPT"`。只有内部 `PROJECT_CONFIRMATION=VALID` 才进入步骤 3；`STALE` 时 loader stdout 已重新渲染当前标准方案，必须原文发送并用新 receipt 立即重试一次，连续变化则停止核对。loader 在原位置记录兼容 stage 和预开发阅读 stage，禁止手工执行 telemetry；receipt 有效时禁止再次渲染 `integration.start.confirm`。
 
 合法组合必须确定产品、路径/来源、代码状态、语言/框架、服务声明和顺序；发现其他产品时保留。零散信息、`新建` 选择、未选候选或新项目未准备均不能替代完整机器校验。方案送达并通过 receipt 校验后仍完整执行 Integration 和 checklist。
 

package/skill/references/normal/scripts/onboarding_discovery_runner.mjs

@@ -22,10 +22,11 @@ const productSalesCodes = Object.freeze({
   apppay: 'I1080300001000041313'
 });
 const signStatuses = new Set(['NOT_SIGNED', 'SIGN_SUBMITTED', 'SIGNED_EFFECTIVE', 'OTHER_STATUS']);
-const signFlows = Object.freeze({
-  aipay: new Set(['FLOW:AI_PAY_NOT_SIGNED', 'FLOW:AI_PAY_SIGNED']),
-  webpay: new Set(['FLOW:PC_WEB_NOT_SIGNED', 'FLOW:PC_WEB_SIGNED']),
-  apppay: new Set(['FLOW:APP_NOT_SIGNED', 'FLOW:APP_SIGNED'])
+const authSignReuseReceiptPrefix = 'AIPAY_SIGN_REUSE_V1.';
+const signFlowByProduct = Object.freeze({
+  aipay: Object.freeze({ notSigned: 'FLOW:AI_PAY_NOT_SIGNED', signed: 'FLOW:AI_PAY_SIGNED' }),
+  webpay: Object.freeze({ notSigned: 'FLOW:PC_WEB_NOT_SIGNED', signed: 'FLOW:PC_WEB_SIGNED' }),
+  apppay: Object.freeze({ notSigned: 'FLOW:APP_NOT_SIGNED', signed: 'FLOW:APP_SIGNED' })
 });
 const serviceFlows = new Set(['FLOW:CREATE_NEW', 'FLOW:SELECT']);
 const applicationFlows = new Set(['FLOW:CREATE_NEW', 'FLOW:SELECT', 'FLOW:PENDING_APPLICATIONS']);
@@ -69,6 +70,92 @@ function uniqueFlow(lines, allowed) {
   return values.length === 1 ? values[0] : '';
 }
 
+function allowedSignFlowValues(productType) {
+  const flows = signFlowByProduct[productType];
+  return new Set([flows.notSigned, flows.signed, 'FLOW:OTHER_STATUS']);
+}
+
+function normalizeSignFlow(value) {
+  if (typeof value !== 'string' || value.length === 0) return '';
+  return value.startsWith('FLOW:') ? value : `FLOW:${value}`;
+}
+
+function legalSignReuseDescription(productType) {
+  const flows = signFlowByProduct[productType];
+  return [
+    `NOT_SIGNED + ${flows.notSigned}`,
+    `SIGNED_EFFECTIVE + ${flows.signed}`,
+    `SIGN_SUBMITTED + ${flows.signed}`,
+    'OTHER_STATUS + FLOW:OTHER_STATUS'
+  ].join('；');
+}
+
+function assertValidSignReuse({ productType, salesCode, signStatus, flow }) {
+  if (!productSalesCodes[productType]) {
+    throw new Error('签约复用 productType 非法，仅支持 aipay、webpay、apppay');
+  }
+  if (salesCode !== productSalesCodes[productType]) {
+    throw new Error(`签约复用 salesCode 与 productType 不匹配；${productType} 必须使用 ${productSalesCodes[productType]}`);
+  }
+  const normalizedFlow = normalizeSignFlow(flow);
+  if (!signStatuses.has(signStatus) || !allowedSignFlowValues(productType).has(normalizedFlow)) {
+    throw new Error(`签约复用状态或 flow 非法；允许组合：${legalSignReuseDescription(productType)}`);
+  }
+  const flows = signFlowByProduct[productType];
+  const validPair =
+    (signStatus === 'NOT_SIGNED' && normalizedFlow === flows.notSigned)
+    || ((signStatus === 'SIGNED_EFFECTIVE' || signStatus === 'SIGN_SUBMITTED') && normalizedFlow === flows.signed)
+    || (signStatus === 'OTHER_STATUS' && normalizedFlow === 'FLOW:OTHER_STATUS');
+  if (!validPair) {
+    throw new Error(`签约复用 status/flow 组合矛盾；允许组合：${legalSignReuseDescription(productType)}`);
+  }
+  return { signStatus, flow: normalizedFlow };
+}
+
+function decodeBase64UrlJson(value) {
+  const normalized = value.replace(/-/gu, '+').replace(/_/gu, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  return JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));
+}
+
+function parseSignReuseReceipt(receipt, productType, salesCode) {
+  if (typeof receipt !== 'string' || !receipt.startsWith(authSignReuseReceiptPrefix)) {
+    throw new Error('签约复用回执格式非法；必须使用 AUTH_SIGN_REUSE_RECEIPT 原值');
+  }
+  let parsed;
+  try {
+    parsed = decodeBase64UrlJson(receipt.slice(authSignReuseReceiptPrefix.length));
+  } catch {
+    throw new Error('签约复用回执无法解析；必须使用 AUTH_SIGN_REUSE_RECEIPT 原值');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('签约复用回执内容非法');
+  }
+  const unknownKeys = Object.keys(parsed).filter((key) => ![
+    'schema_ver',
+    'product_type',
+    'sales_code',
+    'sign_status',
+    'flow'
+  ].includes(key));
+  if (unknownKeys.length > 0) throw new Error(`签约复用回执包含未知字段：${unknownKeys.join('、')}`);
+  if (parsed.schema_ver !== 1) throw new Error('签约复用回执版本非法；当前仅支持 schema_ver=1');
+  if (parsed.product_type !== productType) throw new Error('签约复用回执与当前 product-type 不匹配');
+  if (parsed.sales_code !== salesCode) throw new Error('签约复用回执与当前 sales-code 不匹配');
+  const validated = assertValidSignReuse({
+    productType,
+    salesCode,
+    signStatus: parsed.sign_status,
+    flow: parsed.flow
+  });
+  return {
+    query_status: 'SUCCESS',
+    source: 'AUTH_REUSE',
+    sign_status: validated.signStatus,
+    flow: validated.flow
+  };
+}
+
 function parseArray(value) {
   if (!value) return null;
   try {
@@ -83,7 +170,7 @@ function runScript(script, args) {
   return new Promise((resolve) => {
     const child = spawn('bash', [script, ...args], {
       cwd: onboardingScriptsDir,
-      env: process.env,
+      env: { ...process.env, ALIPAY_AIPAY_SUPPRESS_AUTH_LOGOUT: '1' },
       stdio: ['ignore', 'pipe', 'pipe']
     });
     let stdout = '';
@@ -108,19 +195,45 @@ function failedBranch(result, extra = {}) {
 function signingBranch(result, productType) {
   const lines = internalLines(result.stderr);
   const signStatus = uniqueValue(lines, 'SIGN_STATUS=');
-  const flow = uniqueFlow(lines, signFlows[productType]);
+  const flow = uniqueFlow(lines, allowedSignFlowValues(productType));
   if (result.status !== 0 || !signStatuses.has(signStatus) || !flow) return failedBranch(result);
-  return { query_status: 'SUCCESS', source: 'QUERY', sign_status: signStatus, flow };
+  try {
+    const validated = assertValidSignReuse({
+      productType,
+      salesCode: productSalesCodes[productType],
+      signStatus,
+      flow
+    });
+    return { query_status: 'SUCCESS', source: 'QUERY', sign_status: validated.signStatus, flow: validated.flow };
+  } catch {
+    return failedBranch(result);
+  }
 }
 
 function reusedSigningBranch(args, productType) {
+  const salesCode = productSalesCodes[productType];
+  const receipt = args['reuse-sign-receipt'];
   const signStatus = args['reuse-sign-status'];
   const flow = args['reuse-sign-flow'];
-  if (signStatus === undefined && flow === undefined) return null;
-  if (!signStatuses.has(signStatus) || !signFlows[productType].has(flow)) {
-    throw new Error('授权签约复用标记不完整或与当前产品不匹配');
+  if (receipt === undefined && signStatus === undefined && flow === undefined) return null;
+  if (receipt !== undefined) {
+    const fromReceipt = parseSignReuseReceipt(receipt, productType, salesCode);
+    if (signStatus !== undefined || flow !== undefined) {
+      if (signStatus === undefined || flow === undefined) {
+        throw new Error('签约复用旧双参数必须同时提供 --reuse-sign-status 与 --reuse-sign-flow');
+      }
+      const fromLegacy = assertValidSignReuse({ productType, salesCode, signStatus, flow });
+      if (fromLegacy.signStatus !== fromReceipt.sign_status || fromLegacy.flow !== fromReceipt.flow) {
+        throw new Error('签约复用回执与旧双参数冲突，禁止降级复用');
+      }
+    }
+    return fromReceipt;
+  }
+  if (signStatus === undefined || flow === undefined) {
+    throw new Error('签约复用旧双参数必须同时提供 --reuse-sign-status 与 --reuse-sign-flow');
   }
-  return { query_status: 'SUCCESS', source: 'AUTH_REUSE', sign_status: signStatus, flow };
+  const validated = assertValidSignReuse({ productType, salesCode, signStatus, flow });
+  return { query_status: 'SUCCESS', source: 'AUTH_REUSE', sign_status: validated.signStatus, flow: validated.flow };
 }
 
 function serviceBranch(result) {
@@ -146,7 +259,9 @@ function hasAuthBlocker(result) {
   return internalLines(result.stderr).some((line) => [
     'AUTH_FLOW:AUTH_REQUIRED',
     'AUTH_FLOW:SCOPE_MISMATCH',
-    'AUTH_FLOW:MCC_MISMATCH'
+    'AUTH_FLOW:MCC_MISMATCH',
+    'AUTH_FLOW:RETRY_WITH_NETWORK',
+    'AUTH_FLOW:LOGOUT_STILL_LOGGED_IN'
   ].includes(line));
 }
 
@@ -211,7 +326,7 @@ async function runDiscovery(args) {
 export async function runOnboardingDiscoveryCli(argv = process.argv) {
   const { command, args } = parseArgs(argv);
   if (command !== 'run') {
-    throw new Error('用法: onboarding_discovery_runner.mjs run --product-type <aipay|webpay|apppay> --sales-code <code> [--reuse-sign-status <status> --reuse-sign-flow <flow>]');
+    throw new Error('用法: onboarding_discovery_runner.mjs run --product-type <aipay|webpay|apppay> --sales-code <code> [--reuse-sign-receipt <AUTH_SIGN_REUSE_RECEIPT> | --reuse-sign-status <status> --reuse-sign-flow <flow>]');
   }
   process.exitCode = await runDiscovery(args);
 }

package/skill/references/normal/scripts/onboarding_message_runner.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -93,7 +94,9 @@ function parseArgs(argv) {
     if (!key.startsWith('--')) throw new Error(`未知参数 ${key}`);
     const value = argv[index + 1];
     if (value === undefined || value.startsWith('--')) throw new Error(`参数 ${key} 缺少取值`);
-    args[key.slice(2)] = value;
+    const name = key.slice(2);
+    if (Object.prototype.hasOwnProperty.call(args, name)) throw new Error(`参数 ${key} 重复`);
+    args[name] = value;
     index += 1;
   }
   return { command, args };
@@ -183,8 +186,34 @@ const mccAliasRules = [
     targetTerms: ['电商', '网上商城', '线上商城']
   }
 ];
+const agentMccStatuses = new Set(['MATCHED', 'INSUFFICIENT', 'UNSUPPORTED']);
 
-function mccSearchResult(query) {
+function mccCandidateFromRecord(record) {
+  return {
+    mccCode: record.code,
+    mccName: record.name,
+    applicableBusinesses: record.applicableBusinesses,
+    qualification: record.qualification
+  };
+}
+
+function mccTableSummary(records = loadMccRecords()) {
+  const entries = [...records.values()]
+    .map((record) => [record.code, record.name, record.applicableBusinesses, record.qualification].join('\t'))
+    .sort()
+    .join('\n');
+  return {
+    recordCount: records.size,
+    sha256: createHash('sha256').update(entries).digest('hex')
+  };
+}
+
+function directMccCode(query) {
+  const raw = query.trim().toUpperCase();
+  return /^A\d{4}_B\d{4}$/u.test(raw) ? raw : '';
+}
+
+function deterministicMccMatches(query, { limit = 8 } = {}) {
   const normalizedQuery = assertMccQuery(query);
   const scored = [];
   for (const record of loadMccRecords().values()) {
@@ -201,43 +230,112 @@ function mccSearchResult(query) {
         score = Math.max(score, 50);
       }
     }
-    if (score > 0) scored.push({ record, score });
+    if (score > 0) scored.push({ record, score, strength: score >= 70 ? 'STRONG' : 'WEAK' });
   }
   const strongMatches = scored.filter(({ score }) => score >= 70);
   const ranked = strongMatches.length > 0 ? strongMatches : scored;
-  const candidates = ranked
+  return ranked
     .sort((left, right) => right.score - left.score || left.record.code.localeCompare(right.record.code))
-    .slice(0, 8)
-    .map(({ record }) => ({
-      mccCode: record.code,
-      mccName: record.name,
-      applicableBusinesses: record.applicableBusinesses,
-      qualification: record.qualification
-    }));
+    .slice(0, limit);
+}
+
+function parseAgentMccCodes(args) {
+  const raw = optional(args, 'agent-mcc-codes') || '';
+  const codes = raw.trim()
+    ? raw.split(/[,，、\s]+/u).map((code) => code.trim().toUpperCase()).filter(Boolean)
+    : [];
+  if (codes.length > 3) throw new Error('agent-mcc-codes 最多允许 3 个编码');
+  if (new Set(codes).size !== codes.length) throw new Error('agent-mcc-codes 包含重复 MCC 编码');
+  return codes;
+}
+
+function agentMccInput(args, query, records) {
+  const exactCode = directMccCode(query);
+  if (exactCode && records.has(exactCode) && args['agent-mcc-status'] === undefined && args['agent-mcc-codes'] === undefined) {
+    return {
+      semanticStatus: 'NOT_REQUIRED_DIRECT_CODE',
+      codes: [],
+      directCode: exactCode
+    };
+  }
+
+  const semanticStatus = required(args, 'agent-mcc-status');
+  if (!agentMccStatuses.has(semanticStatus)) {
+    throw new Error('agent-mcc-status 非法，仅支持 MATCHED、INSUFFICIENT、UNSUPPORTED');
+  }
+  const codes = parseAgentMccCodes(args);
+  if (semanticStatus === 'MATCHED' && codes.length === 0) throw new Error('agent-mcc-status=MATCHED 时必须提供 1 到 3 个 agent-mcc-codes');
+  if (semanticStatus !== 'MATCHED' && codes.length > 0) throw new Error('agent-mcc-status=INSUFFICIENT|UNSUPPORTED 时不得提供 agent-mcc-codes');
+  for (const code of codes) {
+    if (!/^A\d{4}_B\d{4}$/u.test(code)) throw new Error(`agent-mcc-codes 包含非法 MCC 编码：${code}`);
+    if (!records.has(code)) throw new Error(`agent-mcc-codes 包含当前 MCC 表不存在的编码：${code}`);
+  }
+  return { semanticStatus, codes, directCode: '' };
+}
+
+function resolveMccResult(query, args) {
+  const records = loadMccRecords();
+  const agent = agentMccInput(args, query, records);
+  if (agent.directCode) {
+    const candidate = mccCandidateFromRecord(records.get(agent.directCode));
+    return {
+      matchType: 'UNIQUE',
+      semanticStatus: agent.semanticStatus,
+      deterministicCandidateCodes: [agent.directCode],
+      deterministicStrongCandidateCodes: [agent.directCode],
+      deterministicWeakCandidateCodes: [],
+      agentCandidateCodes: [],
+      mergedCandidateCodes: [agent.directCode],
+      mccTableSummary: mccTableSummary(records),
+      candidates: [candidate]
+    };
+  }
+
+  const deterministicMatches = deterministicMccMatches(query, { limit: 5 });
+  const deterministicStrongCodes = deterministicMatches.filter(({ strength }) => strength === 'STRONG').map(({ record }) => record.code);
+  const deterministicWeakCodes = deterministicMatches.filter(({ strength }) => strength === 'WEAK').map(({ record }) => record.code);
+  const deterministicCodes = deterministicMatches.map(({ record }) => record.code);
+  const agentCodes = agent.codes;
+  if (agent.semanticStatus !== 'MATCHED') {
+    return {
+      matchType: 'NONE',
+      semanticStatus: agent.semanticStatus,
+      deterministicCandidateCodes: deterministicCodes,
+      deterministicStrongCandidateCodes: deterministicStrongCodes,
+      deterministicWeakCandidateCodes: deterministicWeakCodes,
+      agentCandidateCodes: agentCodes,
+      mergedCandidateCodes: [],
+      mccTableSummary: mccTableSummary(records),
+      candidates: []
+    };
+  }
+  const deterministicCodeSet = new Set(deterministicCodes);
+  const agentCodeSet = new Set(agentCodes);
+  const appendUnique = (target, codes) => {
+    for (const code of codes) {
+      if (!target.includes(code)) target.push(code);
+    }
+  };
+  const mergedCodes = [];
+  appendUnique(mergedCodes, deterministicCodes.filter((code) => agentCodeSet.has(code)));
+  appendUnique(mergedCodes, deterministicStrongCodes.filter((code) => !agentCodeSet.has(code)));
+  appendUnique(mergedCodes, agentCodes.filter((code) => !deterministicCodeSet.has(code)));
+  appendUnique(mergedCodes, deterministicWeakCodes.filter((code) => !agentCodeSet.has(code)));
+  const finalCodes = mergedCodes.slice(0, 8);
+  const candidates = finalCodes.map((code) => mccCandidateFromRecord(records.get(code)));
   return {
     matchType: candidates.length === 1 ? 'UNIQUE' : candidates.length === 0 ? 'NONE' : 'MULTIPLE',
+    semanticStatus: agent.semanticStatus,
+    deterministicCandidateCodes: deterministicCodes,
+    deterministicStrongCandidateCodes: deterministicStrongCodes,
+    deterministicWeakCandidateCodes: deterministicWeakCodes,
+    agentCandidateCodes: agentCodes,
+    mergedCandidateCodes: finalCodes,
+    mccTableSummary: mccTableSummary(records),
     candidates
   };
 }
 
-async function runMccSearch(args) {
-  const productType = args['product-type'];
-  if (productType !== undefined) productFor({ ...args, 'product-type': productType });
-  emitStageMetricAsync('onboarding.mcc_prepare.start', { productType });
-  const query = required(args, 'query');
-  return JSON.stringify(mccSearchResult(query));
-}
-
-async function runMccCandidates(args) {
-  const productType = required(args, 'product-type');
-  productFor({ ...args, 'product-type': productType });
-  const result = mccSearchResult(required(args, 'query'));
-  if (result.candidates.length === 0) return renderMessage('onboarding.mcc.no_match', 'DEFAULT', {}, { productType });
-  return renderMessage('onboarding.mcc.candidates', 'DEFAULT', {
-    mccCandidates: result.candidates
-  }, { productType });
-}
-
 function renderPlanConfirm(productType, mccCandidate) {
   const product = productFor({ 'product-type': productType });
   return renderMessage('onboarding.plan.confirm', product.variant, {
@@ -257,14 +355,14 @@ async function runPlanConfirm(args) {
   });
 }
 
-async function runMccResolve(args, { renderPlan = false } = {}) {
+async function runMccResolvePlan(args) {
   const productType = required(args, 'product-type');
   productFor({ ...args, 'product-type': productType });
   emitStageMetricAsync('onboarding.mcc_prepare.start', { productType });
-  const result = mccSearchResult(required(args, 'query'));
+  const result = resolveMccResult(required(args, 'query'), args);
   process.stderr.write(`ALIPAY_AIPAY_INTERNAL:MCC_RESOLUTION=${JSON.stringify(result)}\n`);
   if (result.matchType === 'UNIQUE') {
-    return renderPlan ? renderPlanConfirm(productType, result.candidates[0]) : '';
+    return renderPlanConfirm(productType, result.candidates[0]);
   }
   if (result.matchType === 'NONE') {
     return renderMessage('onboarding.mcc.no_match', 'DEFAULT', {}, { productType });
@@ -561,21 +659,8 @@ export async function runOnboardingMessageCli(argv = process.argv) {
     console.log(await runMccClarify(args));
     return;
   }
-  if (command === 'mcc-search') {
-    console.log(await runMccSearch(args));
-    return;
-  }
-  if (command === 'mcc-candidates') {
-    console.log(await runMccCandidates(args));
-    return;
-  }
-  if (command === 'mcc-resolve') {
-    const message = await runMccResolve(args);
-    if (message) console.log(message);
-    return;
-  }
   if (command === 'mcc-resolve-plan') {
-    const message = await runMccResolve(args, { renderPlan: true });
+    const message = await runMccResolvePlan(args);
     if (message) console.log(message);
     return;
   }
@@ -632,7 +717,7 @@ export async function runOnboardingMessageCli(argv = process.argv) {
     console.log(runApplicationResult(args));
     return;
   }
-  throw new Error('用法: onboarding_message_runner.mjs <platform-entry|product-clarify|enterprise-unsupported|mcc-resolve|mcc-resolve-plan|plan-confirm|mcc-search|mcc-clarify|mcc-candidates|material-collect|application-candidates|service-candidates|application-recheck|closeout|service-create-summary|service-update-confirm|application-harmony-manual-create|application-reuse-no-key|signing-result|service-result|application-result> ...');
+  throw new Error('用法: onboarding_message_runner.mjs <platform-entry|product-clarify|enterprise-unsupported|mcc-resolve-plan|plan-confirm|mcc-clarify|material-collect|application-candidates|service-candidates|application-recheck|closeout|service-create-summary|service-update-confirm|application-harmony-manual-create|application-reuse-no-key|signing-result|service-result|application-result> ...');
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/skill/references/normal/scripts/render_customer_message.mjs

@@ -586,11 +586,11 @@ const managedEntrypoints = {
     reason: '产品已明确但用户尚未提供 MCC/经营描述时由 runner 绑定产品名称，禁止手写经营类目补问；检索无匹配时不得回到本消息。'
   },
   'onboarding.mcc.no_match': {
-    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-candidates --query <business-description> --product-type <aipay|webpay|apppay>',
+    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-resolve-plan --query <business-description> --product-type <aipay|webpay|apppay> --agent-mcc-status <MATCHED|INSUFFICIENT|UNSUPPORTED> [--agent-mcc-codes <Axxxx_Bxxxx,...>]',
     reason: '用户已经提供经营描述但当前 MCC 表无确定匹配时，由 runner 输出独立恢复路径，禁止重新渲染初始 mcc-clarify 形成循环。'
   },
   'onboarding.mcc.candidates': {
-    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-candidates --query <business-description> --product-type <aipay|webpay|apppay>',
+    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-resolve-plan --query <business-description> --product-type <aipay|webpay|apppay> --agent-mcc-status <MATCHED|INSUFFICIENT|UNSUPPORTED> [--agent-mcc-codes <Axxxx_Bxxxx,...>]',
     reason: '产品已明确且 MCC 存在多个相似候选时由 runner 绑定本地 MCC 表生成候选事实，禁止手写候选表。'
   },
   'onboarding.discovery.summary': {
@@ -598,7 +598,7 @@ const managedEntrypoints = {
     reason: '该 runner 执行本轮适用查询、校验原始脚本事实、输出唯一 DISCOVERY_RESULT envelope，并在同一次 stdout 生成摘要；禁止单独重放摘要。'
   },
   'onboarding.plan.confirm': {
-    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-resolve-plan --query <经营描述|MCC编码|MCC名称> --product-type <aipay|webpay|apppay>，或已持有唯一 MCC 事实时使用同一入口执行 onboarding-message plan-confirm --product-type <...> --mcc-code <...> --mcc-name <...> --mcc-qualification <...>',
+    command: 'node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" onboarding-message mcc-resolve-plan --query <经营描述|MCC编码> --product-type <aipay|webpay|apppay> [--agent-mcc-status <MATCHED|INSUFFICIENT|UNSUPPORTED> --agent-mcc-codes <Axxxx_Bxxxx,...>]，或已持有唯一 MCC 事实时使用同一入口执行 onboarding-message plan-confirm --product-type <...> --mcc-code <...> --mcc-name <...> --mcc-qualification <...>',
     reason: '方案展示必须由 runner 绑定本轮唯一 MCC 事实和产品变体生成，避免 Agent 用 jq/printf/管道手写 renderer 输入。'
   },
   'materials.category.collect': {

package/skill/references/normal/scripts/runtime.mjs

@@ -36,6 +36,8 @@ const nodeEntrypoints = Object.freeze({
 
 export const runtimeDomains = Object.freeze([
   'self-update',
+  'onboarding-bootstrap',
+  'onboarding-execute-ready',
   ...Object.keys(nodeEntrypoints),
   'env',
   ...Object.keys(shellEntrypoints),
@@ -84,7 +86,74 @@ function runtimeError(domain, error) {
   process.stderr.write(`${prefixes[domain] || 'ALIPAY_AIPAY_INTERNAL:RUNTIME_ERROR='}${message}\n`);
 }
 
+function parseRuntimeArgs(args) {
+  const parsed = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith('--')) throw new Error(`未知参数 ${token}`);
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`参数 ${token} 缺少取值`);
+    const name = token.slice(2);
+    if (Object.prototype.hasOwnProperty.call(parsed, name)) throw new Error(`参数 ${token} 重复`);
+    parsed[name] = value;
+    index += 1;
+  }
+  return parsed;
+}
+
+function requiredOption(options, name) {
+  const value = options[name];
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`缺少参数 --${name}`);
+  return value;
+}
+
+function assertOnlyOptions(options, allowedNames) {
+  const allowed = new Set(allowedNames);
+  const unknown = Object.keys(options).filter((name) => !allowed.has(name));
+  if (unknown.length > 0) throw new Error(`未知参数 --${unknown[0]}`);
+}
+
+function assertEnumOption(options, name, allowedValues, { required = true } = {}) {
+  if (!Object.prototype.hasOwnProperty.call(options, name)) {
+    if (required) throw new Error(`缺少参数 --${name}`);
+    return '';
+  }
+  const value = requiredOption(options, name);
+  if (!allowedValues.includes(value)) {
+    throw new Error(`参数 --${name} 非法，仅支持 ${allowedValues.join('、')}`);
+  }
+  return value;
+}
+
+async function runOnboardingBootstrap(args) {
+  const options = parseRuntimeArgs(args);
+  assertOnlyOptions(options, ['root-intent', 'product-type']);
+  const rootIntent = assertEnumOption(options, 'root-intent', ['onboarding_only']);
+  const productType = assertEnumOption(options, 'product-type', ['aipay', 'webpay', 'apppay'], { required: false });
+  const telemetryArgs = ['start-run', '--root-intent', rootIntent];
+  if (productType) telemetryArgs.push('--product-type', productType);
+  const { runTelemetryCli } = await import('./telemetry.mjs');
+  await runTelemetryCli(cliArgv(telemetryArgs));
+  const { runOnboardingMessageCli } = await import('./onboarding_message_runner.mjs');
+  await runOnboardingMessageCli(cliArgv(['platform-entry']));
+  const { isWindowsPlatform } = await import('./platform_compat.mjs');
+  if (isWindowsPlatform()) return;
+  const { runFlowCli } = await import('./flow_loader.mjs');
+  runFlowCli(cliArgv(['onboarding', 'entry']));
+}
+
+async function runOnboardingExecuteReady(args) {
+  const options = parseRuntimeArgs(args);
+  assertOnlyOptions(options, ['product-type']);
+  const productType = assertEnumOption(options, 'product-type', ['aipay', 'webpay', 'apppay']);
+  const { runFlowCli } = await import('./flow_loader.mjs');
+  runFlowCli(cliArgv(['onboarding', 'execute', '--product-type', productType]));
+  return dispatch('env', ['check', '--product-type', productType]);
+}
+
 async function dispatch(domain, args) {
+  if (domain === 'onboarding-bootstrap') return runOnboardingBootstrap(args);
+  if (domain === 'onboarding-execute-ready') return runOnboardingExecuteReady(args);
   if (shellEntrypoints[domain]) {
     const [script, cwd] = shellPath(domain);
     return runShell(script, cwd, args);