@alipay/alipay-aipay 1.2.2 → 1.5.0

package/skill/references/integration/modules/scripts/sandbox_config.sh

@@ -0,0 +1,299 @@
+#!/bin/bash
+
+set -u
+
+MODE="${1:-}"
+PRODUCT_TYPE=""
+PROJECT_PATH=""
+LANGUAGE=""
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NORMAL_SCRIPTS="${SCRIPT_DIR}/../../../normal/scripts"
+RENDERER="${NORMAL_SCRIPTS}/render_customer_message.mjs"
+DETECTOR="${NORMAL_SCRIPTS}/detect_dev_tool.sh"
+COMMON_SCRIPT="${NORMAL_SCRIPTS}/common.sh"
+
+if [ -f "$COMMON_SCRIPT" ]; then
+  # shellcheck source=/dev/null
+  source "$COMMON_SCRIPT"
+else
+  echo "SANDBOX_ERROR:缺少公共脚本 $COMMON_SCRIPT" >&2
+  exit 1
+fi
+
+case "$MODE" in
+  create|verify|ensure|reverify)
+    if [ "${2:-}" = "aipay" ] || [ "${2:-}" = "webpay" ] || [ "${2:-}" = "apppay" ]; then
+      echo "SANDBOX_ERROR:${MODE} 不接受 productType 参数；用法 sandbox_config.sh ${MODE} <projectPath> <language>" >&2
+      exit 2
+    fi
+    PROJECT_PATH="${2:-}"
+    LANGUAGE="${3:-}"
+    ;;
+  summary)
+    PRODUCT_TYPE="${2:-}"
+    PROJECT_PATH="${3:-}"
+    LANGUAGE="${4:-}"
+    ;;
+  *)
+    echo "SANDBOX_ERROR:用法 sandbox_config.sh <ensure|reverify|create|verify> <projectPath> <language> 或 sandbox_config.sh summary <productType> <projectPath> <language>" >&2
+    exit 2
+    ;;
+esac
+
+normalize_language() {
+  local value compact
+  value="${1:-}"
+  compact=$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]' | sed 's/[ ._-]//g')
+  case "$compact" in
+    java) printf '%s\n' "Java" ;;
+    python|python3|py) printf '%s\n' "Python" ;;
+    nodejs|node|javascript|js) printf '%s\n' "Node.js" ;;
+    c#|csharp|dotnet|net) printf '%s\n' "C#" ;;
+    php) printf '%s\n' "PHP" ;;
+    *) return 1 ;;
+  esac
+}
+
+LANGUAGE="$(normalize_language "$LANGUAGE")" || {
+  echo "SANDBOX_ERROR:语言非法，仅支持 Java|Python|Node.js|C#|PHP；Node.js 请使用 Node.js 或 nodejs" >&2
+  exit 2
+}
+
+CONFIG_PATH="${PROJECT_PATH}/.alipay-sandbox.json"
+GITIGNORE_PATH="${PROJECT_PATH}/.gitignore"
+
+if [ "$MODE" = "summary" ]; then
+  case "$PRODUCT_TYPE" in aipay) PRODUCT_NAME="AI 按量付费" ;; webpay) PRODUCT_NAME="AI 网页应用收款" ;; apppay) PRODUCT_NAME="AI 移动应用收款" ;; *) echo "SANDBOX_ERROR:产品非法，仅支持 aipay|webpay|apppay" >&2; exit 2 ;; esac
+fi
+case "$PROJECT_PATH" in /*) ;; *) echo "SANDBOX_ERROR:项目路径必须为绝对路径" >&2; exit 2 ;; esac
+[ -d "$PROJECT_PATH" ] && [ ! -L "$PROJECT_PATH" ] || { echo "SANDBOX_ERROR:项目目录不可访问或不安全" >&2; exit 2; }
+detected=()
+find "$PROJECT_PATH" -maxdepth 4 -type f \( -name pom.xml -o -name build.gradle -o -name build.gradle.kts \) -print -quit | grep -q . && detected+=(Java)
+find "$PROJECT_PATH" -maxdepth 4 -type f -name package.json -print -quit | grep -q . && detected+=(Node.js)
+find "$PROJECT_PATH" -maxdepth 4 -type f \( -name requirements.txt -o -name pyproject.toml \) -print -quit | grep -q . && detected+=(Python)
+find "$PROJECT_PATH" -maxdepth 4 -type f -name '*.csproj' -print -quit | grep -q . && detected+=(C#)
+find "$PROJECT_PATH" -maxdepth 4 -type f -name composer.json -print -quit | grep -q . && detected+=(PHP)
+language_detected=false
+for detected_language in "${detected[@]}"; do
+  [ "$detected_language" = "$LANGUAGE" ] && language_detected=true
+done
+[ "$language_detected" = true ] || { echo "SANDBOX_ERROR:未发现与已确认语言一致的项目构建标识" >&2; exit 2; }
+
+if [ "$MODE" = "ensure" ] || [ "$MODE" = "reverify" ]; then
+  if [ "$MODE" = "reverify" ] || [ -e "$CONFIG_PATH" ] || [ -L "$CONFIG_PATH" ]; then
+    ENSURE_MODE="verify"
+    ENSURE_ACTION="VERIFIED"
+    PENDING_VARIANT="VERIFY"
+    PENDING_MARKER="FLOW:SANDBOX_CONFIG_PENDING_VERIFY"
+  else
+    ENSURE_MODE="create"
+    ENSURE_ACTION="CREATED"
+    PENDING_VARIANT="CREATE"
+    PENDING_MARKER="FLOW:SANDBOX_CONFIG_PENDING_CREATE"
+  fi
+
+  attempt=1
+  while true; do
+    ensure_output=$(bash "$0" "$ENSURE_MODE" "$PROJECT_PATH" "$LANGUAGE" 2>&1)
+    ensure_rc=$?
+    if [ "$ensure_rc" -eq 0 ] &&
+       [ "$(printf '%s\n' "$ensure_output" | grep -Fxc "ALIPAY_AIPAY_INTERNAL:SANDBOX_CONFIG_PATH=$CONFIG_PATH")" -eq 1 ] &&
+       [ "$(printf '%s\n' "$ensure_output" | grep -Fxc 'ALIPAY_AIPAY_INTERNAL:FLOW:SANDBOX_CONFIG_READY')" -eq 1 ] &&
+       ! printf '%s\n' "$ensure_output" | grep -q '^SANDBOX_ERROR:'; then
+      emit_control_field "SANDBOX_ENSURE_ACTION" "$ENSURE_ACTION" || exit 1
+      emit_control_field "SANDBOX_CONFIG_PATH" "$CONFIG_PATH" || exit 1
+      emit_control "FLOW:SANDBOX_CONFIG_READY"
+      exit 0
+    fi
+
+    if [ "$attempt" -lt 3 ] && printf '%s\n' "$ensure_output" | grep -qE \
+      'SANDBOX_ERROR:(候选 data 缺少|配置缺少)当前语言或测试账号必含字段'; then
+      attempt=$((attempt + 1))
+      sleep 3
+      continue
+    fi
+    break
+  done
+
+  printf '%s' '{}' | node "$RENDERER" sandbox.configuration.pending --variant "$PENDING_VARIANT" || {
+    echo "SANDBOX_ERROR:沙箱待配置消息渲染失败" >&2
+    exit 1
+  }
+  emit_control_field "SANDBOX_PENDING_PATH" "$CONFIG_PATH" || exit 1
+  emit_control "$PENDING_MARKER"
+  exit 0
+fi
+
+extract_json_payload() {
+  local raw="$1" line_count span start end candidate normalized selected="" match_count=0
+  if normalized=$(printf '%s' "$raw" | jq -sce 'if length == 1 and (.[0] | type == "object") then .[0] else empty end' 2>/dev/null); then
+    printf '%s' "$normalized"
+    return 0
+  fi
+
+  line_count=$(printf '%s\n' "$raw" | awk 'END { print NR }')
+  span="$line_count"
+  while [ "$span" -ge 1 ]; do
+    start=1
+    while [ $((start + span - 1)) -le "$line_count" ]; do
+      end=$((start + span - 1))
+      candidate=$(printf '%s\n' "$raw" | sed -n "${start},${end}p")
+      if normalized=$(printf '%s' "$candidate" | jq -sce 'if length == 1 and (.[0] | type == "object") then .[0] else empty end' 2>/dev/null) &&
+         printf '%s' "$normalized" | jq -e 'has("success") or ((.result.content[0].text? // .content[0].text?) | type == "string")' >/dev/null 2>&1; then
+        if [ "$normalized" != "$selected" ]; then
+          selected="$normalized"
+          match_count=$((match_count + 1))
+        fi
+      fi
+      start=$((start + 1))
+    done
+    span=$((span - 1))
+  done
+  [ "$match_count" -eq 1 ] || return 1
+  printf '%s' "$selected"
+}
+
+ensure_gitignore_protection() {
+  if [ -L "$GITIGNORE_PATH" ] || { [ -e "$GITIGNORE_PATH" ] && [ ! -f "$GITIGNORE_PATH" ]; }; then
+    echo "SANDBOX_ERROR:.gitignore 不是安全的普通文件" >&2
+    return 1
+  fi
+  if [ -f "$GITIGNORE_PATH" ] && grep -Fxq '/.alipay-sandbox.json' "$GITIGNORE_PATH"; then
+    return 0
+  fi
+  if [ -s "$GITIGNORE_PATH" ] && [ -n "$(tail -c 1 "$GITIGNORE_PATH" 2>/dev/null)" ]; then
+    printf '\n' >>"$GITIGNORE_PATH" || return 1
+  fi
+  printf '/.alipay-sandbox.json\n' >>"$GITIGNORE_PATH" || return 1
+}
+
+ensure_config_not_tracked() {
+  command -v git >/dev/null 2>&1 || return 0
+  git -C "$PROJECT_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+  if git -C "$PROJECT_PATH" ls-files --error-unmatch -- '.alipay-sandbox.json' >/dev/null 2>&1; then
+    return 1
+  fi
+  return 0
+}
+
+ensure_config_permissions() {
+  local mode
+  chmod 600 "$CONFIG_PATH" 2>/dev/null || return 1
+  if mode=$(stat -f '%Lp' "$CONFIG_PATH" 2>/dev/null); then
+    :
+  elif mode=$(stat -c '%a' "$CONFIG_PATH" 2>/dev/null); then
+    :
+  else
+    return 1
+  fi
+  [ "$mode" = "600" ]
+}
+
+validate_data() {
+  local data="$1"
+  echo "$data" | jq -e --arg language "$LANGUAGE" '
+    (.appIds|type)=="array" and (.appIds|length)>0 and .appIds[0] as $app |
+    ($app.appId|type)=="string" and ($app.appId|length)>0 and
+    ($app.alipayPublicKey|type)=="string" and ($app.alipayPublicKey|length)>0 and
+    ($app.appPublicKey|type)=="string" and ($app.appPublicKey|length)>0 and
+    (if $language=="Java" then ($app.appPrivateKey|type)=="string" and ($app.appPrivateKey|length)>0
+     else ($app.appPrivatePkcsKey|type)=="string" and ($app.appPrivatePkcsKey|length)>0 end) and
+    (.sandboxAccounts.partner.userId|type)=="string" and (.sandboxAccounts.partner.userId|length)>0 and
+    (.sandboxAccounts.user.userId|type)=="string" and (.sandboxAccounts.user.userId|length)>0 and
+    (.sandboxAccounts.user.email|type)=="string" and (.sandboxAccounts.user.email|length)>0 and
+    (.sandboxAccounts.user.logonPassword|type)=="string" and (.sandboxAccounts.user.logonPassword|length)>0 and
+    (.sandboxAccounts.user.payPassword|type)=="string" and (.sandboxAccounts.user.payPassword|length)>0
+  ' >/dev/null 2>&1
+}
+
+render_summary() {
+  local data="$1" rows input
+  rows=$(echo "$data" | jq -r '
+    def safe: tostring|gsub("[|\\r\\n]";" ");
+    .appIds[0] as $app |
+    ["| 应用 | appId="+($app.appId|safe)+", pid="+(($app.pid//"未返回")|safe)+" |",
+     "| 商家账号 | userId="+(.sandboxAccounts.partner.userId|safe)+" |",
+     "| 买家账号 | userId="+(.sandboxAccounts.user.userId|safe)+", 登录账号="+(.sandboxAccounts.user.email|safe)+", 登录密码="+(.sandboxAccounts.user.logonPassword|safe)+", 支付密码="+(.sandboxAccounts.user.payPassword|safe)+" |",
+     "| 沙箱 | sandboxId="+((.sandboxId//"未返回")|safe)+" |"] | join("\n")
+  ') || return 1
+  input=$(jq -cn --arg productName "$PRODUCT_NAME" --arg configPath "$CONFIG_PATH" --arg environmentRows "$rows" '{productName:$productName,configPath:$configPath,environmentRows:$environmentRows}') || return 1
+  printf '%s' "$input" | node "$RENDERER" sandbox.environment.summary --variant DEFAULT || return 1
+  printf '%s' '{}' | node "$RENDERER" sandbox.environment.reminder --variant DEFAULT || return 1
+}
+
+if [ "$MODE" = "create" ]; then
+  command -v alipay-cli >/dev/null 2>&1 || { echo "SANDBOX_ERROR:缺少 alipay-cli" >&2; exit 1; }
+  { [ ! -e "$CONFIG_PATH" ] && [ ! -L "$CONFIG_PATH" ]; } || { echo "SANDBOX_ERROR:配置文件已存在或为不安全符号链接，禁止重复创建或覆盖" >&2; exit 1; }
+  ensure_config_not_tracked || { echo "SANDBOX_ERROR:沙箱配置路径已被 Git 跟踪，必须先从版本控制中移除" >&2; exit 1; }
+  ensure_gitignore_protection || { echo "SANDBOX_ERROR:无法为沙箱配置建立 Git 忽略保护" >&2; exit 1; }
+  PLATFORM=$(bash "$DETECTOR") || PLATFORM="unknown"
+  init_platform_id
+  attempt=1
+  while true; do
+    raw=$(env -u PRODUCT PLATFORM="$PLATFORM" PLATFORM_ID="${PLATFORM_ID:-}" alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox --data '{"request":{"appType":"PUBLICAPP"}}' --json 2>&1)
+    rc=$?
+    [ "$rc" -eq 0 ] && break
+    if printf '%s' "$raw" | grep -qiE '版本过旧|version.*old'; then break; fi
+    if [ "$attempt" -lt 3 ] && printf '%s' "$raw" | grep -qiE 'MCP_SERVICE_ERROR|SERVICE_UNSTABLE|timeout|timed out|connection|network|ECONN|socket|temporar'; then
+      attempt=$((attempt + 1))
+      sleep 3
+      continue
+    fi
+    break
+  done
+  [ "$rc" -eq 0 ] || { echo "SANDBOX_ERROR:快速沙箱 CLI 调用失败" >&2; exit 1; }
+  outer=$(extract_json_payload "$raw") || { echo "SANDBOX_ERROR:CLI 输出中未找到唯一合法 JSON 对象" >&2; exit 1; }
+  text=$(echo "$outer" | jq -r '.result.content[0].text // .content[0].text // empty')
+  if [ -n "$text" ]; then
+    business=$(printf '%s' "$text" | jq -c . 2>/dev/null) || { echo "SANDBOX_ERROR:content[0].text 不是合法 JSON" >&2; exit 1; }
+  else
+    business="$outer"
+  fi
+  if [ "$(echo "$business" | jq -r '.success // false')" != "true" ] && echo "$business" | jq -r '.msg // .resultMsg // ""' | grep -q '证书密钥'; then
+    sleep 2
+    raw=$(env -u PRODUCT PLATFORM="$PLATFORM" PLATFORM_ID="${PLATFORM_ID:-}" alipay-cli mcp call alipay-anonymous-sandbox.createAnonymousSandbox --data '{"request":{"appType":"PUBLICAPP"}}' --json 2>&1)
+    rc=$?
+    [ "$rc" -eq 0 ] || { echo "SANDBOX_ERROR:证书密钥临时错误重试后 CLI 调用失败" >&2; exit 1; }
+    outer=$(extract_json_payload "$raw") || { echo "SANDBOX_ERROR:重试输出中未找到唯一合法 JSON 对象" >&2; exit 1; }
+    text=$(echo "$outer" | jq -r '.result.content[0].text // .content[0].text // empty')
+    if [ -n "$text" ]; then business=$(printf '%s' "$text" | jq -c . 2>/dev/null) || { echo "SANDBOX_ERROR:重试 content[0].text 非法" >&2; exit 1; }; else business="$outer"; fi
+  fi
+  [ "$(echo "$business" | jq -r '.success // false')" = "true" ] || {
+    echo "$business" | jq -r '"SANDBOX_ERROR:"+(.errorCode//"UNKNOWN"|tostring)+" "+(.msg//.resultMsg//"快速沙箱创建失败")+" traceId="+(.traceId//"未返回"|tostring)' >&2
+    exit 1
+  }
+  data=$(echo "$business" | jq -c '.data // null') || exit 1
+  validate_data "$data" || { echo "SANDBOX_ERROR:候选 data 缺少当前语言或测试账号必含字段" >&2; exit 1; }
+  temp=$(mktemp "${PROJECT_PATH}/.alipay-sandbox.XXXXXX") || exit 1
+  chmod 600 "$temp" 2>/dev/null || true
+  printf '%s\n' "$data" >"$temp" || { rm -f "$temp"; exit 1; }
+  mv "$temp" "$CONFIG_PATH" || { rm -f "$temp"; exit 1; }
+  ensure_config_permissions || { echo "SANDBOX_ERROR:无法确认配置权限为 0600" >&2; exit 1; }
+elif [ "$MODE" = "verify" ]; then
+  [ -f "$CONFIG_PATH" ] && [ ! -L "$CONFIG_PATH" ] || { echo "SANDBOX_ERROR:配置文件不存在或不安全" >&2; exit 1; }
+  ensure_config_not_tracked || { echo "SANDBOX_ERROR:沙箱配置已被 Git 跟踪，必须先从版本控制中移除" >&2; exit 1; }
+  ensure_gitignore_protection || { echo "SANDBOX_ERROR:无法为沙箱配置建立 Git 忽略保护" >&2; exit 1; }
+  data=$(jq -c . "$CONFIG_PATH" 2>/dev/null) || { echo "SANDBOX_ERROR:配置不是合法 JSON" >&2; exit 1; }
+  validate_data "$data" || { echo "SANDBOX_ERROR:配置缺少当前语言或测试账号必含字段" >&2; exit 1; }
+  ensure_config_permissions || { echo "SANDBOX_ERROR:无法确认配置权限为 0600" >&2; exit 1; }
+elif [ "$MODE" = "summary" ]; then
+  [ -f "$CONFIG_PATH" ] && [ ! -L "$CONFIG_PATH" ] || { echo "SANDBOX_ERROR:配置文件不存在或不安全" >&2; exit 1; }
+  ensure_config_not_tracked || { echo "SANDBOX_ERROR:沙箱配置已被 Git 跟踪，必须先从版本控制中移除" >&2; exit 1; }
+  ensure_gitignore_protection || { echo "SANDBOX_ERROR:无法为沙箱配置建立 Git 忽略保护" >&2; exit 1; }
+  data=$(jq -c . "$CONFIG_PATH" 2>/dev/null) || { echo "SANDBOX_ERROR:配置不是合法 JSON" >&2; exit 1; }
+  validate_data "$data" || { echo "SANDBOX_ERROR:配置缺少当前语言或测试账号必含字段" >&2; exit 1; }
+  ensure_config_permissions || { echo "SANDBOX_ERROR:无法确认配置权限为 0600" >&2; exit 1; }
+else
+  echo "SANDBOX_ERROR:用法 sandbox_config.sh <ensure|reverify|create|verify> <projectPath> <language> 或 sandbox_config.sh summary <productType> <projectPath> <language>" >&2
+  exit 2
+fi
+
+if [ "$MODE" = "summary" ]; then
+  render_summary "$data" || exit 1
+  emit_control_field "SANDBOX_CONFIG_PATH" "$CONFIG_PATH" || exit 1
+  emit_control "FLOW:SANDBOX_CONFIGURED"
+  exit 0
+fi
+
+emit_control_field "SANDBOX_CONFIG_PATH" "$CONFIG_PATH" || exit 1
+emit_control "FLOW:SANDBOX_CONFIG_READY"

package/skill/references/integration/modules/troubleshooting-flow.md

@@ -0,0 +1,28 @@
+# 支付集成问题排查
+
+仅在用户报告集成报错、错误码、问题、排查、调试或异常时读取。先确认当前支付产品；错误码查询还必须确认报错接口，缺少时暂停排查并请用户补充。
+
+## 分流
+
+1. `invalid-signature` 或验签失败：优先进入验签专项。
+2. 有明确错误码：先查[公共错误码说明](https://ideservice.alipay.com/cms/site/02km9f)，无匹配时再按已确认产品和接口查业务接口文档。
+3. 无明确错误码：查当前产品常见问题文档。
+
+| 产品 | 常见问题文档 |
+|---|---|
+| AI 按量付费 | [AI 按量付费常见问题](https://ideservice.alipay.com/cms/site/0j7uos) |
+| AI 网页应用收款 | [AI 网页应用收款常见问题](https://ideservice.alipay.com/cms/site/0j3kh1) |
+| AI 移动应用收款 | [AI 移动应用收款常见问题](https://ideservice.alipay.com/cms/site/0j3pih) |
+
+没有确定依据时明确说明无法确认，禁止编造；引导用户查阅[支付宝开放平台](https://open.alipay.com?form=payskill)或咨询[支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill)。
+
+## 验签失败专项
+
+严禁在没有实际请求证据时把 `invalid-signature`、`ERR_OSSL_UNSUPPORTED` 或验签失败归因于私钥格式，也不得添加 PEM 头尾或擅自转换密钥。按以下顺序核对：
+
+1. 实际发送、参与签名和服务端验签的参数集是否完全一致。
+2. 私钥字段是否正确：Java 使用 `appPrivateKey`，其他语言使用 `appPrivatePkcsKey`。
+3. `signType` 是否为 `RSA2`。
+4. 网关地址是否与当前环境一致。
+
+线上环境确认公私钥不匹配时，建议用户登录支付宝开放平台重新上传应用公钥，并在应用配置中重新配置应用公私钥对。更完整原则见 `alipay-sdk-reminder.md` 的验签失败排查章节。

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

@@ -42,11 +42,12 @@ fi
 **执行要求：**
 - 对已知需要联网的命令，如果当前 Agent 环境网络受限且支持显式授权，应首次执行即申请可联网权限，不要先在受限沙箱内试跑。
 - 若命令已经因网络失败，重试时必须复用同一条命令并申请可联网权限；不要把该失败解释为用户网络故障。
+- `auth.sh init|confirm|mismatch` 返回 `AUTH_FLOW:RETRY_WITH_NETWORK` 时，表示当前 Agent 执行环境没有取得可确认 CLI 结果；必须申请联网权限后重试同一条完整脚本命令，不得解释为支付宝业务失败、logout 失败或 login 失败，也不得要求用户手动 logout/login 代替本轮脚本事实。
 - 本地纯解析、文件检查、`bash -n`、`jq` 校验等不联网命令仍可在默认沙箱内执行。
 
 **减少重复授权：**
-- 优先执行 Skill 内置脚本，例如 `bash modules/scripts/auth.sh ...`、`bash modules/scripts/app.sh ...`、`bash modules/scripts/service.sh ...`，不要把每次 `alipay-cli mcp call` 都展开成新的长命令。
-- 在支持前缀持久授权的工具中，申请可联网权限时使用稳定命令前缀作为授权范围，例如 `bash modules/scripts/auth.sh` 或 `bash modules/scripts/app.sh`。同一脚本后续不同参数更容易复用授权。
+- 优先执行 Skill 内置脚本；从本文件所在的 `references/normal/` 目录调用 onboarding 脚本时，使用 `bash ../onboarding/modules/scripts/auth.sh ...`、`bash ../onboarding/modules/scripts/app.sh ...`、`bash ../onboarding/modules/scripts/service.sh ...`，不要把每次 `alipay-cli mcp call` 都展开成新的长命令。
+- 在支持前缀持久授权的工具中，申请可联网权限时使用当前实际脚本绝对路径对应的稳定命令前缀作为授权范围。同一脚本后续不同参数更容易复用授权；不得为了复用授权改调另一份 Skill 副本。
 - 避免用 `DEV_TOOL_NAME=<tool> bash ...`、`PLATFORM=<tool> alipay-cli ...` 作为常规调用形态；这类环境变量前缀会让授权规则更难复用。签约脚本会通过公共初始化设置 `DEV_TOOL_NAME`，直接执行脚本即可。
 - 产品上下文优先通过脚本参数传入，例如 `--sales-code`、`--mcc-code`、`--product-type`；不要用 `PRODUCT_TYPE=... SALES_CODE=... bash ...` 作为常规调用形态。
 - 只有脚本未覆盖的临时排查命令，才直接调用 `alipay-cli`；这类命令需要按具体前缀单独授权。
@@ -87,7 +88,7 @@ which gpg 2>/dev/null
 >
 > 不要额外设置 `HOMEBREW_API_DOMAIN`；formula 索引保持使用 Homebrew 默认 API，避免镜像索引不完整导致安装失败。
 
-签约脚本需要 jq 解析 JSON，先检查：
+签约脚本和 Unix/macOS/Linux 快速沙箱脚本需要 jq 解析 JSON，先检查：
 ```bash
 jq --version
 ```
@@ -117,6 +118,8 @@ jq --version
 >
 > 不要额外设置 `HOMEBREW_API_DOMAIN`；formula 索引保持使用 Homebrew 默认 API，避免镜像索引不完整导致安装失败。
 
+Windows Integration 代码开发路径通过 Node runner 完成项目解析、项目扫描和标准消息渲染，只要求当前 Node 运行时，不把 Bash、jq 或该路径不会调用的 alipay-cli 作为 Step 1 阻断项；进入产品开通或执行既有 shell/CLI 脚本时仍按对应 flow 补齐依赖。Unix/macOS/Linux 和 Onboarding 的既有检查边界不变。
+
 ---
 
 ## 4. CLI 安装
@@ -163,15 +166,22 @@ source ~/.bashrc  # Linux/bash
 
 > ⚠️ **强制规范：检测结果仅供内部使用，禁止向用户输出！**
 
-AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚本通过 `scripts/common.sh` 提供的 `init_dev_tool_name` 初始化 `DEV_TOOL_NAME`，再用于设置 `PLATFORM` 上下文；文档示例或非 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` 取当前 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` 的输出。
 
 ```
 ❌ 禁止：向用户输出"环境检查完成，检测到您正在使用 Claude Code 环境"等检测结果
 ❌ 禁止：向用户透出任何关于 AI 编程工具检测的信息
-✅ 正确：检测结果仅供内部使用，只用于设置 PLATFORM 环境变量
+✅ 正确：检测结果仅供内部使用，只用于脚本设置 `PLATFORM`；`PLATFORM_ID` 由脚本从当前 `run_id` 派生，Onboarding 的 `PRODUCT` 由已确认产品映射
 ✅ 正确：静默完成检测，直接进入下一步流程
 ```
 
+### 5.1 页面打开与下载能力降级
+
+- 授权页或公钥确认页由 `scripts/open_official_url.sh` 在精确 HTTPS 主机、路径、查询参数和当前上下文校验通过后默认调用 macOS `open`、Linux `xdg-open` 或可用的 Windows PowerShell；只返回 `OPENED` / `OPEN_FAILED` / `GUI_UNAVAILABLE` / `LINK_ONLY`，不输出临时 URL。Skill 不另询问是否打开。
+- 宿主缺少 GUI、opener 不存在或当前权限不允许打开时，不安装桌面工具、不绕过宿主审批，直接由标准消息保留同一裸 URL 和复制访问兜底。
+- 目标应用缺少用户已准备的应用公钥时，macOS/Windows 直接执行 onboarding 的 `download_key_tool.sh`，默认保存到用户 `Downloads` 目录并展示实际安装包路径；Linux、缺少 `curl`/`node`、目录不可用、下载源不可达或下载校验失败均回退 `https://opendocs.alipay.com/isv/02kipk`。脚本 stdout 直接输出标准对客文案，不输出 `DOWNLOADED`、`PATH=`、`DOWNLOAD_FAILED` 或 `DOWNLOAD_REASON` 机器标记。下载不安装、不启动、不生成密钥，Skill 不另询问是否下载。
+- 页面打开和下载能力检测不改变 alipay-cli、MCP、业务确认或网络重试契约；宿主权限提示不是 Skill 业务确认。
+
 ---
 
 ## 6. 检测与安装流程图

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

@@ -0,0 +1,82 @@
+# 完整接入编排
+
+本文件是 `full_process` 唯一入口。启动确认前只复用 Integration 步骤 1 的项目、语言、当前系统分支环境和沙箱准备；不得开发代码、进入 Onboarding 或读取开通信息。
+
+目标项目和技术栈可确定后，从本文件目录执行 `node scripts/flow_loader.mjs integration entry`，只加载 Integration 当前入口阶段并按其步骤 1/2 准备和确认；禁止整份读取 `../integration/flow.md`。loader bundle 中的命令仍以源文件目录 `references/integration/` 为 workdir。代码开发满足衔接条件后执行 `node scripts/flow_loader.mjs onboarding entry`，其 bundle 命令以 `references/onboarding/` 为 workdir；禁止整份读取 `../onboarding/flow.md`。
+
+本文 Skill 命令以 `references/normal/` 为 workdir。项目选择时的 `PROJECT_INPUT` 保留用户原始表达；明确“新建/创建”项目、网站、商城、应用或同类新产物时固定使用 `--intent new`，不得因当前目录已有项目改写为 `--intent existing`。新建项目使用空路径或 runner 安全默认目录；复用项目须选定具体项目根，未知位置先定位候选。“当前目录”仅在 runner 识别为项目根时接受。扫描和后续脚本只使用解析后的规范化绝对路径。
+
+## 边界
+
+- 只编排 Integration 与 Onboarding，不复制其状态、完成条件和红线。完整接入复用 Integration 步骤 2 的唯一 `integration.start.confirm`、同一检查器事实和模板，本轮只渲染一次。
+- 先确定项目、语言和创建方式。`NEW_PROJECT` 空路径检查后初始化最小骨架，再执行 Integration 步骤 1；沙箱不依赖产品、不传 `PRODUCT`、不展示摘要，待配置仍继续。确认前禁止读取/展示 MCC、授权范围和开通材料/待办。
+- 项目事实只来自 runner 与实际文件。未知位置用 `locate-projects --search-input "$SEARCH_INPUT" --format message` 查标记并等待选择；不得扫描上层大目录。完整性仍以 Integration 全部适用项和 checklist 为准。
+
+## 新项目准备与路由分类
+
+项目来源互斥：`CURRENT_PROJECT` 为当前目录内项目根，`OTHER_PROJECT` 为用户以绝对路径提供的目录外项目；未选定/不可访问/不可识别则为 `PROJECT_UNRESOLVED`，禁止凭描述生成状态。
+
+`NEW_PROJECT` 只用于初始化前：
+
+```bash
+node scripts/integration_message_runner.mjs resolve-project --project-input "$PROJECT_INPUT" --base-path "$USER_WORKSPACE_ROOT" --intent new
+```
+
+未指定位置时使用用户目录下 `alipay-aipay-projects/pay-demo`，非空占用则加安全后缀。只有 `preparationStatus=READY` 才初始化；其他结果不得清空/覆盖。初始化且沙箱终态确定后单向成为当前会话的 `PREPARED_NEW_PROJECT`；不持久化，重入重扫。`NEW_PROJECT` 不扫描代码，`PREPARED_NEW_PROJECT` 不恢复为空目录状态。
+
+### 固定检查器与 runner 终态协议
+
+- `resolve-project --intent new` 只接受退出码 0、唯一 JSON、规范化绝对 `projectPath`、`projectSelection/projectOrigin=NEW_PROJECT`、`projectOriginLabel=本轮新建项目` 和 `preparationStatus=READY`；否则保持 `PROJECT_UNRESOLVED`。
+- `resolve-project --intent existing` 只接受退出码 0、唯一 JSON、规范化绝对路径、`CURRENT_PROJECT|OTHER_PROJECT` 和 `EXISTING_PROJECT/现有项目`。相对路径限 `--base-path` 内，目录外由用户提供绝对路径；失败不得以描述/cwd 代替。
+- `locate-projects` 用于未知位置/多候选，缺省搜索词为 `当前目录`。stdout 是唯一候选消息；选择后仍执行 `resolve-project --intent existing`。
+- `start-confirm` 内部只执行一次项目扫描，校验后将同一对象交给 renderer；失败为 `STATUS_UNKNOWN`。禁止改写命令、另跑扫描、抽取代码，或追加 `find`、`ls`、`stat`、额外 `jq` 和临时脚本复核同一结果。
+
+## 维度二：目标产品集成状态
+
+项目和沙箱取得确定终态后再确定产品并扫描合法项目分类。已有描述能唯一映射时直接复用；否则只执行下列消息并等待，仍不唯一时重复同一消息。目标产品明确前不得执行 `scan`。
+
+```bash
+node scripts/integration_message_runner.mjs product-clarify
+```
+
+- `TARGET_PARTIAL`：发现目标代码/配置，仍完整验证；并存时优先。
+- `OTHER_PRODUCT_ONLY`：仅有其他产品，保留。
+- `NO_PAYMENT`：无支付能力。
+- `STATUS_UNKNOWN`：不可访问、证据冲突/不足或产品不明，停止。
+
+合法项目分类与前三种代码状态确认后进入 Integration；`PROJECT_UNRESOLVED/STATUS_UNKNOWN` 继续澄清。Unix/macOS/Linux 的 `CREATE_PENDING|VERIFY_PENDING` 和 Windows 的 `VERIFY_PENDING` 都不阻止扫描/开发。新项目保留 `projectOriginLabel=本轮新建项目`；已有项目“新建”只能新增能力或使用空路径。这些分类只用于本轮分流，不持久化。
+
+## 完整接入启动确认
+
+合法项目分类、前三种代码状态、产品、语言和框架全部确定后才能发起 `integration.start.confirm`。缺项目/技术栈时执行下列 `integration.context.required`；只缺新项目位置用 `integration.project_path.required`。禁止使用 AskUserQuestion、request_user_input、宿主超时默认值、Agent 自创选项或自由话术替代；不得先输出扫描摘要或方案。
+
+```bash
+node scripts/integration_message_runner.mjs context-required --missing-items "$MISSING_ITEMS"
+```
+
+`MISSING_ITEMS` 只由 `项目路径`、`技术栈` 组成；产品不明确仍用 `product.clarify`。stdout 原文发出后等待，未补齐前不得初始化、安装或修改。路径输入均先 `resolve-project`；未知位置或需候选时执行：
+
+```bash
+node scripts/integration_message_runner.mjs locate-projects --base-path "$USER_WORKSPACE_ROOT" --search-input "$SEARCH_INPUT" --format message
+```
+
+字段齐备后执行唯一 runner；禁止拆开执行项目扫描、`jq` 或 `render_customer_message.mjs`，也不得附加解析。runner stdout 是本动作唯一对客消息，必须把 stdout 原文作为当前回复正文发给用户；发出 stdout 原文后立即停止本轮并等待当前摘要的明确肯定回复。收到回复后执行 `node scripts/interaction_reply.mjs confirm --reply "$USER_REPLY"`，只有唯一 `REPLY_DECISION=CONFIRMED` 才推进；摘要变化后旧回复失效。该内部判定不新增用户操作点；静态扫描只决定进入验证，不证明完成。
+
+```bash
+node scripts/integration_message_runner.mjs start-confirm --product-type "$PRODUCT_TYPE" --product-name "$PRODUCT_NAME" --project-path "$PROJECT_PATH" --project-selection "$PROJECT_SELECTION" --language "$SERVER_LANGUAGE" --framework "$FRAMEWORK"
+```
+
+上面命令失败时不得展示手写确认或进入子流程。成功时必须同时保存唯一 `ALIPAY_AIPAY_INTERNAL:PROJECT_CONFIRM_RECEIPT=<receipt>`；缺失、重复或不可解析视为失败。参数必须是当前确定值，禁止直接拼用户输入。runner 校验产品 variant 并固定服务声明；实际范围仍取当前 Integration flow 和 checklist。
+
+分流、展示和交接事实必须来自 runner 内同一次 `scan` 对象；禁止用描述、Agent 自报或历史分类代替。`evidence` 仅内部校验，不进 renderer；Onboarding Step 1 前禁止传/猜 `mccCode`。确认同时满足 `INT.START.CONFIRMED` 与 `INT.SERVICE_STATEMENT.CONFIRMED` 后，执行 `node scripts/flow_loader.mjs integration development --product-type "$PRODUCT_TYPE" --project-confirm-receipt "$PROJECT_CONFIRM_RECEIPT"`。只有内部 `PROJECT_CONFIRMATION=VALID` 才进入步骤 3；`STALE` 时 loader stdout 已重新渲染当前标准确认，必须原文发送并等待新的明确肯定回复。loader 自动记录确认和预开发阅读 stage，禁止手工执行 telemetry；确认有效时禁止再次渲染 `integration.start.confirm`。
+
+合法组合必须确认产品、路径/来源、代码状态、语言/框架、服务声明和顺序；发现其他产品时确认保留。当前完整摘要展示前的零散信息、`新建` 选择、未选候选或新项目未准备均不能替代；当前完整摘要展示后的 `继续` 属于有效肯定回复。确认后仍完整执行 Integration 和 checklist。
+
+## 子流程衔接规则
+
+- 启动确认后直接进入 Integration 步骤 3；项目、产品、语言或框架变化使确认失效，重新扫描并确认。
+- Integration 先完整执行和校验。只有沙箱待配置，或 READY 且仅剩非阻塞人工待验证项时，保持“部分通过”进入 Onboarding；其他代码、安全或依据缺口停在 Integration，不提前登录或收集开通材料。
+- 阶段间只复用有效的产品、项目、代码产物和 CLI 检查，不再询问是否进入 Onboarding；保留方案确认。
+- 授权后分别查询签约、应用和适用服务；分支独立，单分支失败不回滚其他成功，认证/授权不匹配或主体变化全局阻断。一次只收集一个类别，提前材料直接校验且不重复索取。
+- 签约材料通过后直接提交；服务创建摘要后直接创建，修改仍确认；当前候选列表选择“新建”且重查未变化后直接创建，用户公钥直接生成官方确认页，校验成功后直接提审。均不增加额外确认点；按量付费沙箱测试仍属 Integration 默认动作。
+- 当前终点汇总代码、沙箱、签约、服务、应用和待办；人工待验证项带入 Onboarding Step 6，不增加确认。有待生效/审核/验证或配置缺口时不得宣称生产就绪。