@alipay/alipay-aipay 0.1.1-beta.1

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

@@ -0,0 +1,211 @@
+# Alipay CLI 环境准备
+
+> 本文档定义 alipay-cli 的检测、安装、验证规范，供集成流程和签约流程统一引用。
+
+---
+
+## 1. CLI 检测
+
+### 1.1 检测命令
+
+```bash
+# 推荐：一步检测
+which alipay-cli 2>/dev/null && alipay-cli version
+
+# 或：分步检测
+if ! alipay-cli version &>/dev/null; then
+  echo "⚠️ alipay-cli 未安装"
+fi
+```
+
+### 1.2 检测时机
+
+**必须在以下操作前执行 CLI 检测：**
+- 执行 `whoami` 检查登录状态前
+- 执行 `login` 登录授权前
+- 执行任何 MCP 调用前
+- 执行沙箱创建操作前
+
+---
+
+## 2. 沙箱化 Agent 网络权限规则
+
+在存在网络沙箱或命令审批机制的 Agent 环境中，默认命令可能运行在无外网的受限沙箱内。`alipay-cli` 访问支付宝服务必须联网，若先在受限沙箱内执行，容易出现“网络连接失败”后再重试的差体验。
+
+**应按联网命令处理的命令：**
+- `alipay-cli login`、`alipay-cli whoami`、`alipay-cli logout`
+- `alipay-cli mcp call ...`
+- `alipay-cli file upload ...`
+- `curl -fsSL https://opengw.alipay.com/alipaycli/install | bash`
+- 按量付费沙箱测试中会访问用户服务或沙箱收银接口的 `local_402_sandbox_pay.py`
+
+**执行要求：**
+- 对已知需要联网的命令，如果当前 Agent 环境网络受限且支持显式授权，应首次执行即申请可联网权限，不要先在受限沙箱内试跑。
+- 若命令已经因网络失败，重试时必须复用同一条命令并申请可联网权限；不要把该失败解释为用户网络故障。
+- 本地纯解析、文件检查、`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`。同一脚本后续不同参数更容易复用授权。
+- 避免用 `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`；这类命令需要按具体前缀单独授权。
+
+---
+
+## 3. 前置依赖：GPG 与 jq
+
+安装脚本需要 GPG 签名验证，先检查：
+```bash
+which gpg 2>/dev/null
+```
+
+未安装时先安装 GPG：
+
+| 操作系统 | 安装命令 |
+|----------|----------|
+| macOS | `brew install gnupg`（或使用国内镜像源） |
+| Linux (Debian/Ubuntu) | `sudo apt-get install -y gnupg` |
+| Linux (CentOS/RHEL) | `sudo yum install -y gnupg2` |
+
+> ⚠️ macOS 如遇下载慢，可只切换 Homebrew bottle 下载源，并跳过自动更新。`npx -y @alipay/alipay-aipay@latest install` 会按以下顺序自动重试：清华 → 阿里云 → 中科大 → 直连。
+>
+> 手动执行时可任选一个镜像源，例如清华：
+> ```bash
+> export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
+> export HOMEBREW_NO_AUTO_UPDATE=1
+> export HOMEBREW_NO_INSTALL_CLEANUP=1
+> brew install gnupg
+> ```
+>
+> 可替换的 bottle 镜像源：
+> - 清华：`https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles`
+> - 阿里云：`https://mirrors.aliyun.com/homebrew-bottles`
+> - 中科大：`https://mirrors.ustc.edu.cn/homebrew-bottles`
+>
+> 不要额外设置 `HOMEBREW_API_DOMAIN`；formula 索引保持使用 Homebrew 默认 API，避免镜像索引不完整导致安装失败。
+
+签约脚本需要 jq 解析 JSON，先检查：
+```bash
+jq --version
+```
+
+未安装时先安装 jq：
+
+| 操作系统 | 安装命令 |
+|----------|----------|
+| macOS | `brew install jq` |
+| Linux (Debian/Ubuntu) | `sudo apt-get install -y jq` |
+| Linux (CentOS/RHEL) | `sudo yum install -y jq` |
+
+> ⚠️ macOS 如遇下载慢，可与 GPG 使用同一套 Homebrew bottle 下载源配置。`npx -y @alipay/alipay-aipay@latest install` 会按以下顺序自动重试：清华 → 阿里云 → 中科大 → 直连。
+>
+> 手动执行时可任选一个镜像源，例如清华：
+> ```bash
+> export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
+> export HOMEBREW_NO_AUTO_UPDATE=1
+> export HOMEBREW_NO_INSTALL_CLEANUP=1
+> brew install jq
+> ```
+>
+> 可替换的 bottle 镜像源：
+> - 清华：`https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles`
+> - 阿里云：`https://mirrors.aliyun.com/homebrew-bottles`
+> - 中科大：`https://mirrors.ustc.edu.cn/homebrew-bottles`
+>
+> 不要额外设置 `HOMEBREW_API_DOMAIN`；formula 索引保持使用 Homebrew 默认 API，避免镜像索引不完整导致安装失败。
+
+---
+
+## 4. CLI 安装
+
+### 4.1 自动安装
+
+```bash
+curl -fsSL https://opengw.alipay.com/alipaycli/install | bash
+```
+
+### 4.2 权限问题处理
+
+安装脚本默认写入 `/usr/local/bin`，可能需要 sudo 权限。若提示权限不足：
+```bash
+# 方案一：使用 sudo
+sudo curl -fsSL https://opengw.alipay.com/alipaycli/install | bash
+
+# 方案二：修复目录权限
+sudo chown -R $(whoami) /usr/local/bin
+```
+
+### 4.3 安装验证
+
+安装后执行以下命令确认安装成功：
+```bash
+alipay-cli version
+```
+
+若提示 `command not found`，尝试以下方案：
+```bash
+# 方案一：刷新 PATH
+source ~/.zshrc   # macOS zsh
+source ~/.bashrc  # Linux/bash
+
+# 方案二：使用绝对路径
+~/.local/bin/alipay-cli version
+/usr/local/bin/alipay-cli version
+```
+
+---
+
+## 5. 环境检测结果不透出规范
+
+> ⚠️ **强制规范：检测结果仅供内部使用，禁止向用户输出！**
+
+AI 编程工具检测使用通用脚本 `scripts/detect_dev_tool.sh`。shell 脚本通过 `scripts/common.sh` 提供的 `init_dev_tool_name` 初始化 `DEV_TOOL_NAME`，再用于设置 `PLATFORM` 上下文；文档示例或非 shell 流程可直接参考 `detect_dev_tool.sh` 的输出。
+
+```
+❌ 禁止：向用户输出"环境检查完成，检测到您正在使用 Claude Code 环境"等检测结果
+❌ 禁止：向用户透出任何关于 AI 编程工具检测的信息
+✅ 正确：检测结果仅供内部使用，只用于设置 PLATFORM 环境变量
+✅ 正确：静默完成检测，直接进入下一步流程
+```
+
+---
+
+## 6. 检测与安装流程图
+
+```
+开始
+  ↓
+检测 alipay-cli 是否存在
+  ↓
+┌───┐ 是否存在? ├──是→ 验证版本 → 继续下一步
+│   │           │
+│   ↓           │
+│  不存在       │
+│   │           │
+│   ↓           │
+│ 检测 GPG ────┼──无→ 安装 GPG → 安装 CLI
+│   ↓           │
+│ 有 GPG        │
+│   ↓           │
+│ 执行安装脚本  │
+│   ↓           │
+│ 安装失败? ───┼──是→ 尝试 sudo 或 提示手动安装
+│   ↓           │
+│  成功         │
+│   ↓           │
+│ 验证安装结果  │
+  ↓
+继续下一步
+```
+
+---
+
+## 7. 错误处理
+
+| 错误场景 | 处理方式 |
+|----------|----------|
+| CLI 不存在 | 自动安装 |
+| 安装失败（权限） | 提示使用 sudo 或手动安装 |
+| 安装后找不到命令 | 提示刷新 PATH 或使用绝对路径 |
+| 版本过旧 | 提示更新 CLI |

package/skill/references/normal/rejection-guide.md

@@ -0,0 +1,37 @@
+# 拒绝引导话术
+
+> 本文件定义当用户咨询本 Skill 不支持的支付产品时的标准引导话术。
+
+---
+
+## 标准拒绝引导
+
+当用户提及以下不支持的产品时，必须使用以下统一话术：
+
+> 抱歉，本 Skill 仅支持按量付费、网站支付、APP支付三种产品。
+> - 如需了解其他支付产品，请查阅 [支付宝开放平台在线文档](https://open.alipay.com?form=payskill)
+> - 如需集成传统支付产品（JSAPI、当面付、订单码、预授权、商家扣款等），可下载 [alipay-payment-integration Skill](https://github.com/alipay/ai/tree/main/skills) 进行接入
+
+---
+
+## 适用场景
+
+| 用户提及的产品 | 引导方式 |
+|---------------|----------|
+| 预授权支付 | 使用标准引导 |
+| 商家扣款 | 使用标准引导 |
+| 订单码支付 | 使用标准引导 |
+| 当面付 | 使用标准引导 |
+| JSAPI支付 | 使用标准引导 |
+
+> “手机网站支付”“H5支付”只是用户对手机浏览器网页场景的叫法，在本 Skill 中统一归为**网站支付**，不作为独立产品处理，也不使用拒绝话术。
+
+---
+
+## 调用位置
+
+本话术在以下位置被引用：
+- `SKILL.md` → 意图识别 → 拒绝处理
+- `../integration/modules/product-decision.md` → 不支持的产品
+
+**重要**：如需修改引导内容，**仅需修改本文件**，其他引用位置会自动生效。

package/skill/references/normal/scripts/common.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+#=============================================================================
+# 脚本名称: common.sh
+# 功能描述: 集成流程和签约流程共用的 shell 基础函数
+# 调用前置: 无
+#=============================================================================
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "❌ 缺少依赖命令: $1"
+    return 1
+  fi
+}
+
+init_dev_tool_name() {
+  if [ -n "${DEV_TOOL_NAME:-}" ] && [ "$DEV_TOOL_NAME" != "unknown" ]; then
+    export DEV_TOOL_NAME
+    return
+  fi
+
+  local COMMON_DIR
+  COMMON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local DETECT_SCRIPT="${COMMON_DIR}/detect_dev_tool.sh"
+
+  if [ -f "$DETECT_SCRIPT" ]; then
+    # shellcheck source=/dev/null
+    source "$DETECT_SCRIPT"
+    DEV_TOOL_NAME="$(detect_dev_tool 2>/dev/null || echo unknown)"
+  fi
+
+  export DEV_TOOL_NAME="${DEV_TOOL_NAME:-unknown}"
+}

package/skill/references/normal/scripts/detect_dev_tool.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+#=============================================================================
+# 脚本名称: detect_dev_tool.sh
+# 功能描述: 智能识别 AI 编程工具，返回工具名称
+# 调用位置: 集成流程和签约流程的环境检查
+# 调用前置: 无
+# 返回值: coze | meoo | claudeCode | codex | traeSolo | cursor | qoder | unknown
+#=============================================================================
+
+detect_dev_tool() {
+    if [ -n "$COZE_PROJECT_ID" ]; then
+        echo "coze"
+        return
+    fi
+    if [ -n "$MEOO_PROJECT_ID" ]; then
+        echo "meoo"
+        return
+    fi
+    if [ -n "$CLAUDECODE" ] || [ -n "$CLAUDE_CODE_ENTRYPOINT" ]; then
+        echo "claudeCode"
+        return
+    fi
+    if [ -n "$CODEX_CI" ] || [ -n "$CODEX_THREAD_ID" ]; then
+        echo "codex"
+        return
+    fi
+    if [ -n "$TRAE_BRAND_NAME" ]; then
+        echo "traeSolo"
+        return
+    fi
+    if [ -n "$CURSOR_AGENT" ] || [ -n "$CURSOR_LAYOUT" ]; then
+        echo "cursor"
+        return
+    fi
+    if [ -n "$QODER_CLI" ]; then
+        echo "qoder"
+        return
+    fi
+    echo "unknown"
+}
+
+# 仅在直接执行时输出，被 source 时不执行
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    DEV_TOOL_NAME=$(detect_dev_tool)
+    echo "$DEV_TOOL_NAME"
+fi