@alipay/alipay-aipay 1.0.2 → 1.2.2

package/skill/references/integration/modules/scripts/local_402_sandbox_pay.py

@@ -21,6 +21,7 @@ from urllib.parse import quote
 
 PAY_ENDPOINT = "http://aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay"
 PAY_URL_PREFIX = "https://render.alipay.com/p/yuyan/180020010001290755/pay.html?schema="
+A2M_SANDBOX_SERVICE_ID = "api_mock_service_id"
 DEFAULT_PAYMENT_NEEDED_FILE = "/tmp/402_needed_file.txt"
 DEFAULT_PAY_RETRIES = 3
 DEFAULT_PAY_RETRY_DELAY_SECONDS = 2.0
@@ -462,6 +463,12 @@ def command_run(args: argparse.Namespace) -> int:
         )
 
     decoded_bill = b64decode_json(payment_needed)
+    method_data = decoded_bill.get("method") if isinstance(decoded_bill.get("method"), dict) else {}
+    if method_data.get("service_id") != A2M_SANDBOX_SERVICE_ID:
+        raise RuntimeError(
+            f"沙箱联调 method.service_id 必须为 {A2M_SANDBOX_SERVICE_ID}，"
+            "请修正用户服务的沙箱运行配置后重试"
+        )
     cashier_payload = build_cashier_payload(decoded_bill, buyer_id, args.buyer_signature)
 
     (artifact_dir / "payment_needed.txt").write_text(payment_needed, encoding="utf-8")
@@ -514,12 +521,13 @@ def command_run(args: argparse.Namespace) -> int:
             "errorMessage": pay_response.get("errorMessage"),
         }
         write_json(artifact_dir / "state.json", state)
+        retry_mode = " --auto-complete" if args.auto_complete else ""
         raise RuntimeError(
             "收银接口未返回 payScheme，无法生成付款链接。"
             f"过程产物已保存：{artifact_dir}。"
             "如果是 PAY_SUBMIT_FAILED/系统繁忙，可稍后复用同一个 Payment-Needed 重试：\n"
             f"python3 {shell_quote(Path(__file__).resolve())} run "
-            f"--reuse-artifact {shell_quote(artifact_dir)}"
+            f"--reuse-artifact {shell_quote(artifact_dir)}{retry_mode}"
         )
 
     pay_url = pay_url_from_response(pay_response)
@@ -528,9 +536,24 @@ def command_run(args: argparse.Namespace) -> int:
     state["tradeNo"] = trade_no
     write_json(artifact_dir / "state.json", state)
 
+    print(f"\n过程产物目录：{artifact_dir}")
+
+    if args.auto_complete:
+        print("\n继续执行 Payment-Proof 服务端联调...")
+        complete_args = argparse.Namespace(
+            artifact_dir=str(artifact_dir),
+            payment_proof=args.payment_proof,
+            buyer_signature=args.buyer_signature,
+        )
+        result = command_complete(complete_args)
+        if result == 0:
+            print("\n按量付费沙箱服务端联调通过。")
+            print("\n沙箱付款体验链接（可选）：")
+            print(pay_url)
+        return result
+
     print("\n请在浏览器打开以下链接，并使用沙箱买家账号完成付款：")
     print(pay_url)
-    print(f"\n过程产物目录：{artifact_dir}")
     print("付款成功后运行：")
     print(f"python3 {Path(__file__).resolve()} complete --artifact-dir {artifact_dir}")
 
@@ -619,7 +642,10 @@ def build_parser() -> argparse.ArgumentParser:
     run_parser.add_argument("--reuse-artifact", help="复用上一轮 run 产物中的 url/method/body/content-type/payment_needed")
     run_parser.add_argument("--pay-endpoint", default=PAY_ENDPOINT)
     run_parser.add_argument("--artifact-dir", help="生成过程产物的目录")
-    run_parser.add_argument("--payment-proof", help="使用 --wait 时可选的最终 payment_proof 值")
+    run_parser.add_argument(
+        "--payment-proof",
+        help="使用 --auto-complete 或 --wait 时可选的最终 payment_proof 值",
+    )
     run_parser.add_argument("--pay-retries", type=int, default=DEFAULT_PAY_RETRIES, help="沙箱收银接口临时失败时的重试次数")
     run_parser.add_argument(
         "--pay-retry-delay",
@@ -628,12 +654,17 @@ def build_parser() -> argparse.ArgumentParser:
         help="沙箱收银接口重试间隔秒数",
     )
     run_parser.add_argument("--dry-run", action="store_true", help="调用收银接口前停止")
+    run_parser.add_argument(
+        "--auto-complete",
+        action="store_true",
+        help="生成付款链接后连续携带 Payment-Proof 重试原始服务",
+    )
     run_parser.add_argument("--wait", action="store_true", help="等待付款后立刻重试原始服务")
     run_parser.set_defaults(func=command_run)
 
     complete_parser = subparsers.add_parser("complete", help="携带 Payment-Proof 重试原始服务")
     complete_parser.add_argument("--artifact-dir", required=True, help="run 命令生成的过程产物目录")
-    complete_parser.add_argument("--payment-proof", help="可选 payment_proof；默认生成一个确定性的非空哈希")
+    complete_parser.add_argument("--payment-proof", help="可选 payment_proof；未传时由脚本按沙箱联调约定处理")
     complete_parser.add_argument("--buyer-signature", help="买家签名占位值")
     complete_parser.set_defaults(func=command_complete)
 

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

@@ -36,7 +36,7 @@ fi
 - `alipay-cli login`、`alipay-cli whoami`、`alipay-cli logout`
 - `alipay-cli mcp call ...`
 - `alipay-cli file upload ...`
-- `export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | bash`
+- `export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | ALIPAY_CLI_SKIP_PGP=true ALIPAY_CLI_SKIP_VERIFY=true bash`
 - 按量付费沙箱测试中会访问用户服务或沙箱收银接口的 `local_402_sandbox_pay.py`
 
 **执行要求：**
@@ -55,20 +55,22 @@ fi
 
 ## 3. 前置依赖：GPG 与 jq
 
-安装脚本需要 GPG 签名验证，先检查：
+`npx -y @alipay/alipay-aipay@latest install` 会优先保障 `alipay-cli` 可用；如果 `alipay-cli` 已安装或可直接安装成功，不需要额外安装 GPG。
+
+只有在 `alipay-cli` 首次安装失败，且失败输出指向缺少 GPG/GnuPG 时，后台准备任务才会把 GPG 作为兜底依赖检查：
 ```bash
 which gpg 2>/dev/null
 ```
 
-未安装时先安装 GPG：
+确认 GPG 未安装时，按系统安装：
 
 | 操作系统 | 安装命令 |
 |----------|----------|
-| macOS | `brew install gnupg`（或使用国内镜像源） |
+| macOS | 优先执行 `brew install gnupg`；失败或卡住时配置 Homebrew bottle 镜像后重试 |
 | Linux (Debian/Ubuntu) | `sudo apt-get install -y gnupg` |
 | Linux (CentOS/RHEL) | `sudo yum install -y gnupg2` |
 
-> ⚠️ macOS 如遇下载慢，可只切换 Homebrew bottle 下载源，并跳过自动更新。安装器不会阻塞等待 GPG 安装；只有在 `alipay-cli` 缺失、后台准备任务需要安装前置 GPG 时，才会按以下顺序自动重试：清华 → 阿里云 → 中科大 → 直连。
+> ⚠️ macOS 的 Homebrew 包名是 `gnupg`。安装器不会阻塞等待 GPG 安装；只有在 `alipay-cli` 缺失、首次安装失败且失败输出指向缺少 GPG/GnuPG 时，后台准备任务才会先使用 Homebrew 当前配置执行一次 `brew install gnupg`。如果默认安装失败或卡住，再并行探测清华、阿里云、中科大三个 bottle 镜像，选择最快可用镜像后用镜像重试一次。自动安装使用“无输出超时”：45 秒没有 stdout/stderr 输出才认为命令卡住；默认安装首轮最多 2 分钟，镜像兜底最多 8 分钟。
 >
 > 手动执行时可任选一个镜像源，例如清华：
 > ```bash
@@ -125,7 +127,7 @@ jq --version
 
 ```bash
 mkdir -p ~/.local/bin
-export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | bash
+export ALIPAY_CLI_BIN="$HOME/.local/bin" && curl -fsSL https://opengw.alipay.com/alipaycli/install | ALIPAY_CLI_SKIP_PGP=true ALIPAY_CLI_SKIP_VERIFY=true bash
 ```
 
 ### 4.2 PATH 处理
@@ -184,12 +186,12 @@ AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚
 │   ↓           │
 │  不存在       │
 │   │           │
-│   ↓           │
-│ 检测 GPG ────┼──无→ 后台尝试安装 GPG → 安装 CLI 到 ~/.local/bin
-│   ↓           │
-│ 有 GPG        │
-│   ↓           │
+│   ↓
 │ 设置 ALIPAY_CLI_BIN="$HOME/.local/bin" 后执行安装脚本
+│   ↓
+│ 安装失败且提示缺少 GPG? ─┼──是→ 检测 GPG ──无→ 后台尝试安装 GPG（macOS 配置 bottle 镜像）
+│   │           │
+│   │           └──GPG 就绪后重试安装 CLI 到 ~/.local/bin
 │   ↓           │
 │ 安装失败? ───┼──是→ 提示指定可写目录手动安装
 │   ↓           │

package/skill/references/normal/self-update.md

@@ -0,0 +1,59 @@
+# Skill 启动自更新检查
+
+本文件定义 `alipay-aipay` Skill 启动时的自更新检查。该检查用于降低用户继续使用旧版 Skill 的概率，但不得阻断支付集成或签约入驻主流程。
+
+## 执行原则
+
+- 每次触发本 Skill 时，先执行本检查。
+- 如果本轮对话中刚成功执行过 `npx -y @alipay/alipay-aipay@latest install`，或等价的 `@latest install --target ...` 命令，则视为自更新检查已完成，直接继续当前业务流程，不再查询 npm latest，也不再重复执行安装。
+- 本检查不作为业务阻塞确认点，不单独询问用户是否更新。
+- 若当前 Agent 环境要求联网或写入用户 Skill 目录授权，则按环境权限机制处理；不得在 Skill 内另设业务确认点。
+- 任何读取版本、查询 npm、执行更新失败的情况，都只输出简短提示并继续当前业务流程。
+- 更新命令必须使用 `--skip-tools`，只更新 Skill 文件，不重新检查或安装 GPG、alipay-cli、jq。
+
+## 版本读取
+
+1. 读取当前 `SKILL.md` 所在目录下的 `VERSION` 文件作为本地版本。
+2. 如果 `VERSION` 不存在，或内容不是合法 SemVer 版本号（例如 `latest` 或 `v1`），将当前安装视为“未知版本/旧版安装”，直接进入「未知版本更新规则」，不要再猜测其他安装记录文件。
+3. 如果成功读取本地版本，执行以下命令查询 npm latest：
+   ```bash
+   npm view @alipay/alipay-aipay version --json
+   ```
+4. 如果无法获取 npm latest，跳过更新并继续当前业务流程。
+
+## 更新规则
+
+如果本地版本低于 npm latest，自动执行 Skill 更新。
+
+更新命令必须覆盖当前正在使用的 Skill 目录。取当前 `SKILL.md` 所在目录的父目录作为 `<当前Skill父目录>`，执行：
+
+```bash
+ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
+```
+
+说明：
+- `ALIPAY_AIPAY_EXTRA_SKILL_DIRS` 确保当前正在使用的 Skill 父目录会被纳入更新目标，避免只更新当前项目目录下的 `.agents/.codex/.claude`。
+- `--target all` 继续覆盖安装器解析到的全部目标目录。
+- `--skip-tools` 避免在启动检查中触发 GPG、alipay-cli、jq 的检查或安装。
+
+## 未知版本更新规则
+
+如果当前 Skill 目录没有 `VERSION`，或 `VERSION` 内容不是合法 SemVer 版本号，不做不可靠的版本推断，直接执行同一条更新命令：
+
+```bash
+ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
+```
+
+说明：
+- 这是对旧版安装的确定性兼容路径；更新成功后，新安装器会写入 `VERSION`，后续启动即可走正常版本比较。
+- 如果该命令因网络、npm、权限或执行环境限制失败，输出简短提示并继续当前业务流程。
+
+## 输出要求
+
+- 已是最新：输出一句简短提示即可。
+- 发现新版本并开始更新：输出本地版本、npm latest 和更新目标摘要。
+- 未知版本并开始更新：输出“未检测到 VERSION，尝试安装 latest”及更新目标摘要。
+- 更新成功：提示更新已完成，并继续当前业务流程。
+- 更新失败或权限受限：提示本次自更新未完成，继续使用当前已加载版本执行流程。
+
+不得输出长篇安装日志；如需日志，以命令输出或工具环境记录为准。