---
name: install-payment-skills
description: "安装聚合支付 skill（双端：收款端商家侧 payment-merchant + 付款端用户侧 payment-client）。当需要在本机 agent 上安装收款端（商家：下单/退款/查单/扫码收款/异步通知/402 收款）或付款端（用户：付款/钱包/402 买家）skill 时使用：从 GitHub Release 下载对应平台安装包、解压、运行 install 脚本、配置、验证。"
metadata:
  version: "0.2.0"
---

# 安装聚合支付 Skill（payctl · 双端）

一个 CLI（`payctl`）两种角色。按需选择安装：

- **① 收款端 / 商家侧 `payment-merchant`**：持有商家凭证，聚合支付宝收款（下单 / 扫码收款 / 退款 / 查单 / 关单 / 异步通知验签 / 402 收款挑战）。
- **② 付款端 / 用户侧 `payment-client`**：消费 PaymentIntent 完成付款（选择支付方式 → 拉起支付 → 追踪结果；402 / 收银台包装官方支付引擎）。本端不持有商家凭证。

服务器（收款端服务器）无 CLI，是 REST API；direct 模式下服务器零商户私钥，资金直达商户。

安装包由 GitHub Release 分发。下载地址（`<file>` 替换为下表文件名）：

`https://github.com/eccstartup/ztf-binaries/releases/latest/download/<file>`

## ① 安装 payment-merchant（收款端 / 商家侧）

### 安装步骤

1. 判断本机平台，下载对应安装包：
   | 平台 | 安装包 |
   |---|---|
   | macOS Apple Silicon | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-merchant-darwin-arm64.tar.gz` |
   | macOS Intel | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-merchant-darwin-x64.tar.gz` |
   | Linux x64 | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-merchant-linux-x64.tar.gz` |
   | Windows x64 | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-merchant-windows-x64.zip` |
   | 仅需文档（无二进制） | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-merchant-skill.tar.gz` |

2. 解压安装包到临时目录。

3. 运行一键安装脚本：
   - macOS / Linux：`bash <临时目录>/install.sh --dir ~/.claude/skills/payment-merchant`
   - Windows：`powershell -ExecutionPolicy Bypass -File <临时目录>\install.ps1`

4. 配置商家凭证：
   - `cp <skill目录>/.env.example .env`
   - 填入 `ALIPAY_APP_ID` / `ALIPAY_PRIVATE_KEY` / `ALIPAY_PUBLIC_KEY`
   - 生产环境把 `PAYCTL_ENV` 改为 `production`；私钥建议用内联 PEM（`_PATH` 在 Docker/rsync 下不可靠）
   - 若走收款端服务器（REST 模式）：再填 `PAYMERCHANT_BASE_URL` + `PAYMERCHANT_API_KEY`

5. 验证：`~/.local/bin/payctl config`

6. 安装完成后，读取该 skill 的 `SKILL.md`，按其生命周期下单 / 退款 / 查单 / 处理 402 收款。

### 安全约束

- 动钱操作（`create-order` / `refund` / `close`）必须先经用户确认「渠道 / 金额 / 商品」，确认后必须带 `--yes`。
- 绝不读取、打印、提交私钥内容。

## ② 安装 payment-client（付款端 / 用户侧）

### 安装步骤

1. 判断本机平台，下载对应安装包：
   | 平台 | 安装包 |
   |---|---|
   | macOS Apple Silicon | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-client-darwin-arm64.tar.gz` |
   | macOS Intel | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-client-darwin-x64.tar.gz` |
   | Linux x64 | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-client-linux-x64.tar.gz` |
   | Windows x64 | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-client-windows-x64.zip` |
   | 仅需文档（无二进制） | `https://github.com/eccstartup/ztf-binaries/releases/latest/download/payment-client-skill.tar.gz` |

2. 解压安装包到临时目录。

3. 运行一键安装脚本：
   - macOS / Linux：`bash <临时目录>/install.sh --dir ~/.claude/skills/payment-client`
   - Windows：`powershell -ExecutionPolicy Bypass -File <临时目录>\install.ps1`

4. 验证：`~/.local/bin/payctl --help`

5. 首次使用按 skill 阶段① 一次性开通付款环境：安装支付宝支付引擎 `alipay-bot` + 开通钱包（本端无需任何商家密钥；涉及安装外部代码先经用户确认）。

6. 安装完成后，读取该 skill 的 `SKILL.md`，按其生命周期消费 PaymentIntent 完成支付。

### 安全约束

- 付款前必须经用户确认「金额 / 支付方式 / 商品」。
- 本端不持有商家凭证。
- 支付结果以服务端回执 / 渠道异步通知为准。