bushrose/agent-1yuan-purchase-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit for agent-1yuan-purchase-skill

Browse Source
This commit is contained in:
Axure Cloud 2026-06-25 02:27:48 +08:00
commit bacafa1064
6 changed files with 532 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md Normal file
View File

@ -0,0 +1,25 @@
# 🛒 Agent 壹元软仓 - 自动购买技能 (AI Skill)
这是一个赋予 AI Agent（如 Cursor, Trae, Claude Code）全自动购物能力的技能包。安装后，你的 Agent 将能够自动浏览商品、下单，并通过 A2Apay 协议完成支付，最后自动获取网盘下载链接。
## 📦 如何安装技能
不同的 AI 工具安装方式略有不同，请选择适合你的方式：
### 方式一：一键网络加载（推荐 Cursor / Trae 用户）
直接在你的 AI 对话框中输入以下指令，让 Agent 自己去学习：
> "请阅读并学习这个技能文档：https://gitea.bushrose.cn/bushrose/agent-1yuan-purchase-skill/raw/branch/master/SKILL.md ，掌握后告诉我。"
### 方式二：克隆到本地项目（推荐 Claude Code 等终端 Agent）
1. 将本仓库克隆到你的工作目录：
`git clone https://gitea.bushrose.cn/bushrose/agent-1yuan-purchase-skill.git .agent-skills/1yuan-store`
2. 在对话框中告诉 Agent：
> "请读取 `.agent-skills/1yuan-store/SKILL.md`，你现在是我的软件采购助手了。"
## 🚀 如何使用
技能加载成功后，你只需要对 Agent 说：
- "帮我买 [软件名称]"
- "逛逛壹元软仓，看看有什么好东西"
Agent 会自动帮你检查支付环境、搜索商品、创建订单，并生成支付二维码（或静默支付），完成付款后直接把网盘链接交给你！

135
SKILL.md Normal file
View File

@ -0,0 +1,135 @@
# AI 软件购买 Skill
一站式AI驱动的软件购买体验：环境检查 → 发现商品 → 下单 → 自动支付 → 获取网盘交付链接。
## 触发词
"帮我买xxx"、"购买xxx"、"下载xxx"、"逛商城"、"看看有什么软件"
## 环境变量与配置
- **STORE_BASE_URL**：`https://store.bushrose.cn` *(注：投产时仅需修改此处这一处地址即可)*
- 所有的 OpenAPI 接口调用及页面访问请以 `STORE_BASE_URL` 作为基础地址。
## 执行流程总览
```
用户发起购买请求
↓
Step 0：前置检查（alipay-bot 是否已安装）
├─ 已安装 → 进入 Step 1
└─ 未安装 → 引导安装 alipay-bot → 进入 Step 1
↓
Step 1：环境检查（check-wallet）
├─ 已授权 → 进入 Step 2
├─ 未授权/未开通 → 引导用户完成支付宝钱包绑定/授权 → 进入 Step 2
└─ 检查失败 → 提示网络问题，终止
↓
Step 2：产品发现与下单
├─ 调用 getSoftwareList 接口搜索商品
└─ 用户确认后，调用 createOrder 接口创建订单，获取 orderNo
↓
Step 3：获取支付参数
└─ 调用 getPaymentNeeded 接口，提取返回的 Payment-Needed 头信息并保存
↓
Step 4：发起支付与自动轮询
├─ 使用 alipay-bot 402-buyer-pay 提交支付
└─ 自动轮询 alipay-bot 402-query-payment-status 等待支付成功
↓
Step 5：验证与交付
├─ 支付成功后，提取交易号生成 Payment-Proof
├─ 调用 verifyPayment 接口验证并获取网盘交付链接
├─ 发送履约回执（alipay-bot 402-buyer-fulfillment-ack）
└─ 将网盘链接和提取码优雅地展示给用户
```
---
## 详细执行步骤
### Step 0：前置检查（alipay-bot 是否已安装）
**检查命令：**
```bash
alipay-bot --version 2>&1
```
- 返回版本号（如 `alipay-bot-cli 0.3.19`）→ 已安装 → 进入 Step 1
- 返回 `command not found` 或错误 → 未安装 → 请引导用户安装：
> "我当前未配置支付能力，无法完成付款。请安装并授权支付宝官方 npm 包：`npm install @alipay/agent-payment@1.0.12 && npx @alipay/agent-payment@1.0.12 install-cli`，然后再重新尝试购买。"
**Windows 环境注意：**
- `alipay-bot` 可能安装在 `~/.openclaw-autoclaw/alipay-bot-cli/bin/alipay-bot.cmd`
- 如果 `alipay-bot` 命令不可用，尝试使用完整路径
### Step 1：环境检查
**执行命令：**
```bash
alipay-bot check-wallet
```
- 若 JSON 返回 `code: 200` 且不包含"等待授权" → 已授权，进入 Step 2。
- 若提示"等待授权"或未开通 → 提示用户："首次使用需要绑定支付宝钱包，请先调用相关技能完成钱包授权。" 等待用户授权完成后再继续。
### Step 2：产品发现与下单
1. **搜索商品**：调用 `getSoftwareList` 查询商品（`GET {STORE_BASE_URL}/api/software`）。向用户展示结果并确认购买意向。
2. **创建订单**：调用 `createOrder`（`POST {STORE_BASE_URL}/api/orders`），传入 `softwareId`。接口返回成功后，提取 `orderNo`。
### Step 3：获取支付参数
1. **获取参数**：调用 `getPaymentNeeded`（`POST {STORE_BASE_URL}/api/orders/{orderNo}/payment-needed`）。
2. **保存参数**：此接口会返回 402 状态码，你需要提取响应中的 `Payment-Needed` 头的 base64 字符串，并将其写入本地文件 `402_needed_file.txt` 中。
```bash
# 示例：从402响应中提取 Payment-Needed 头并保存
curl -s -D - -X POST "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
-H "Accept: application/json" \
| grep -i "^Payment-Needed:" \
| sed "s/^[Pp]ayment-[Nn]eeded: //" \
| tr -d "\r\n" \
> 402_needed_file.txt
```
### Step 4：发起支付与自动轮询
1. **提交支付**：
```bash
alipay-bot 402-buyer-pay \
--session-id "<你的会话ID>" \
-f "402_needed_file.txt" \
-r "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
--intent-summary "原始请求：用户购买软件订单：{orderNo}" \
-m POST
```
*注意：`session-id` 需为 UUID 格式。将 `{STORE_BASE_URL}` 和 `{orderNo}` 替换为实际值。若输出包含 `✓ 支付待确认` 及二维码，请向用户展示二维码。*
2. **自动轮询等待支付**：
使用 `alipay-bot 402-query-payment-status -t '<trade_no>' -r '<resource_url>' -m POST` 每 5 秒轮询一次，最多等待 3 分钟。若返回 `success=true`，进入 Step 5。
### Step 5：验证与交付
1. **构造 Payment-Proof**：
```python
import json, base64
proof = {
'protocol': {'payment_proof': 'verified', 'trade_no': '<trade_no>'},
'method': {'client_session': base64.b64encode(b'agent-session').decode()},
}
proof_b64 = base64.urlsafe_b64encode(json.dumps(proof).encode()).decode()
print(proof_b64)
```
2. **验证并获取交付物**：调用 `verifyPayment`（`POST {STORE_BASE_URL}/api/orders/{orderNo}/verify`），将生成的 base64 字符串作为 `Payment-Proof` 请求头传入。接口验证成功后，将返回包含网盘交付物信息的 `downloadUrl`（以及可能包含的提取码）。
3. **履约回执**：
```bash
alipay-bot 402-buyer-fulfillment-ack -t '<trade_no>'
```
4. **通知用户**：告知用户支付成功，输出交易号，并**直接将获取到的 `downloadUrl`（网盘链接）展示给用户，提醒用户注意下载次数与有效期限制**。不需要在本地下载任何文件。
## 安全与约束
1. 必须按顺序严格执行。
2. 禁止伪造 `trade_no` 或跳过轮询直接验证。
3. 交付物是网盘链接，**禁止尝试使用 curl 去下载该链接的内容**。
4. 如果中途遇到任何命令失败或接口返回报错，需原样告知用户并停止流程。
---
## 参考文件
| 文件 | 内容 |
|------|------|
| `references/openapi.yaml` | 商城 API 接口定义（OpenAPI 3.1） |
| `references/cli-setup.md` | alipay-bot 安装与完整性校验 |
| `references/payment-flow.md` | 支付+轮询+交付详细流程 |
| `references/troubleshooting.md` | 常见问题与解决方案 |

65
references/cli-setup.md Normal file
View File

@ -0,0 +1,65 @@
# CLI 安装与校验
## 前置条件
- `npm` 命令可用
- `npm config set registry https://registry.npmjs.org/`
## 来源说明
`@alipay` 是 npm 上由 Ant Group（支付宝母公司）持有的 scoped package 命名空间。源代码托管于 [github.com/alipay](https://github.com/alipay)。
## 安装流程
### 1. 用户确认（安装前必须执行）
- 即将安装的外部包：`@alipay/agent-payment@1.0.12`（支付宝官方 npm 包）
- 安装后会执行 `install-cli` 命令，将 `alipay-bot` CLI 工具安装到系统 PATH
- 如用户不同意，终止流程并提示用户可手动安装
### 2. 完整性校验（必须先于安装执行）
```bash
npm view @alipay/agent-payment@1.0.12 dist.integrity
```
预期值：`sha512-WpJNa5rK6pXaLqKbvfHNI6iG0n0/+dX/ETmtWqH2SWeS2hDnpGbjFiLaZDyZHXqPlGNTEzrPWnP4p4Ruy+DOTg==`
校验失败处理：如果哈希值不匹配或 `npm view` 命令失败，**立即终止安装**，向用户报告"包完整性校验失败，禁止安装"。
### 3. 安装（仅在校验通过后执行）
```bash
npm install @alipay/agent-payment@1.0.12 && npx @alipay/agent-payment@1.0.12 install-cli
```
必须安装固定版本 `@1.0.12`，禁止使用 `@latest` 或其他非锁定版本标签。
### 4. 验证安装
```bash
alipay-bot --version
```
返回版本号（如 `alipay-bot-cli 0.3.19`）→ 安装成功
### 5. Windows 环境特殊处理
如果 `alipay-bot` 命令不可用，尝试使用完整路径：
```bash
# 常见安装位置
~/.openclaw-autoclaw/alipay-bot-cli/bin/alipay-bot.cmd
# 验证
<用户目录>/.openclaw-autoclaw/alipay-bot-cli/bin/alipay-bot.cmd --version
```
## 已安装检测
```bash
which alipay-bot 2>/dev/null || echo "NOT_FOUND"
```
返回路径 → 已安装
返回 `NOT_FOUND` → 未安装，需要执行安装流程

82
references/openapi.yaml Normal file
View File

@ -0,0 +1,82 @@
openapi: 3.1.0
info:
title: AI 软件商城 Agent API
description: 面向 Agent 提供的数字化商品商城接口，支持商品搜索、下单、HTTP 402 A2Apay 支付及交付验证。
version: 1.0.0
servers:
- url: https://store.bushrose.cn # 部署后请替换为您的真实域名
paths:
/api/software:
get:
summary: 搜索软件商品
operationId: getSoftwareList
parameters:
- name: keyword
in: query
description: 搜索关键词
required: false
schema:
type: string
- name: page
in: query
schema:
type: integer
default: 1
responses:
"200":
description: 成功返回商品列表
/api/orders:
post:
summary: 创建订单
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [softwareId]
properties:
softwareId:
type: integer
description: 要购买的软件ID
responses:
"200":
description: 订单创建成功，返回 orderNo
/api/orders/{orderNo}/payment-needed:
post:
summary: 获取支付参数 (402 Payment Needed)
operationId: getPaymentNeeded
parameters:
- name: orderNo
in: path
required: true
schema:
type: string
responses:
"402":
description: 需要支付，返回 payment parameters
/api/orders/{orderNo}/verify:
post:
summary: 提交支付凭证并获取下载链接
operationId: verifyPayment
parameters:
- name: orderNo
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [paymentProof]
properties:
paymentProof:
type: string
description: 支付插件返回的 base64 格式的 Payment-Proof
responses:
"200":
description: 验证成功，返回 delivery.downloadUrl 等交付信息

143
references/payment-flow.md Normal file
View File

@ -0,0 +1,143 @@
# 支付+轮询+交付详细流程
## 3.1 获取 Payment-Needed
在创建订单后，调用获取支付参数接口：
```bash
curl -s -X POST "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
-H "Accept: application/json" \
| grep -i "^Payment-Needed:" \
| sed "s/^[Pp]ayment-[Nn]eeded: //" \
| tr -d "\r\n" \
> 402_needed_file.txt
```
失败处理：
- 返回非 402 状态码或不包含 Payment-Needed 头 → 提示"获取支付参数失败" → 终止流程
## 3.2 提交支付
```bash
alipay-bot 402-buyer-pay \
--session-id "<session-uuid>" \
-f "402_needed_file.txt" \
-r "{STORE_BASE_URL}/api/orders/{orderNo}/payment-needed" \
--intent-summary "原始请求：用户购买软件订单：{orderNo}" \
-m POST
```
输出判断：
| CLI 输出 | 动作 |
|---------|------|
| 含 `✓ 支付待确认` + 二维码 | 展示给用户 → 进入 3.3 轮询 |
| 含 `✓ 支付成功并获取资源` | 跳过轮询 → 直接进入 Step 4 |
| 含 `✗ 支付失败` | 原样输出 → 终止 |
| 其他错误 JSON | 原样输出 errorMsg → 终止 |
可重试错误（最多3次）：
- SERVER_TIMEOUT / CLIENT_TIMEOUT / SYSTEM_ERROR / SYSTEM_ERR
- POLL_INTERRUPTED / PAY_SUBMIT_FAILED / PAY_STATUS_UNKNOWN
不可重试错误（直接终止）：
- SERVICE_SELLER_ID_MISMATCH（卖家ID不匹配）
- BUYER_SELLER_SAME（买家和卖家相同）
- REQUEST_EXPIRED（请求过期）
- 其他未识别错误码
## 3.3 自动轮询
支付发起后自动轮询，**不需要用户手动通知"已支付"**：
```python
import time, subprocess, json
def poll_payment_status(trade_no, resource_url, max_wait=180, interval=5):
"""自动轮询支付状态"""
elapsed = 0
while elapsed < max_wait:
time.sleep(interval)
elapsed += interval
# 执行查询命令
result = subprocess.run([
"alipay-bot", "402-query-payment-status",
"-t", trade_no,
"-r", resource_url,
"-m", "POST"
], capture_output=True, text=True)
try:
data = json.loads(result.stdout)
if data.get("success") == True:
return {"status": "success", "data": data}
except (json.JSONDecodeError, KeyError):
pass
# 每30秒输出进度
if elapsed % 30 == 0:
print(f"⏳ 正在等待支付确认...（已等待{elapsed}秒）")
return {"status": "timeout"}
```
轮询结果处理：
- success=true → 进入 Step 4 交付
- 超时 → 提示"支付等待超时，请稍后重试"
- 命令失败 → 重试1次，仍失败则终止
## Step 4：交付文件
### 4.1 获取交付链接（网盘链接）
```bash
# 构造 Payment-Proof
PROOF=$(python -c "
import json, base64
proof = {
'protocol': {'payment_proof': 'verified', 'trade_no': '<trade_no>'},
'method': {'client_session': base64.b64encode(b'agent-session').decode()},
}
print(base64.urlsafe_b64encode(json.dumps(proof).encode()).decode())
")
# 调用验证接口获取网盘链接
curl -s -X POST "{STORE_BASE_URL}/api/orders/{orderNo}/verify" \
-H "Content-Type: application/json" \
-H "Payment-Proof: $PROOF" \
-d "{\"paymentProof\": \"$PROOF\"}"
```
### 4.2 履约回执
```bash
alipay-bot 402-buyer-fulfillment-ack -t '<trade_no>'
```
可重试错误（最多3次同 trade_no 重试）：
- TR_FULFILLMENT_FAILED / FULFILLMENT_FAILED / SYSTEM_ERROR / SYSTEM_ERR
不可重试错误：
- 原样输出 errorMsg + trade_no → 终止
### 4.3 通知用户
```
✅ 支付成功！
订单号：{orderNo}
交易号：{trade_no}
🎉 您的软件提取信息如下：
🔗 网盘地址：{返回的 downloadUrl}
🔑 提取码：{若有提取码则展示}
⚠️ 注意：请在有效期内尽快保存或下载，不要分享给他人。
```
## 交易号校验
- 必须恰好 32 位纯数字
- 校验不通过 → 输出"交易号格式异常" → 立即终止
- 禁止对非32位 trade_no 执行任何后续命令

82
references/troubleshooting.md Normal file
View File

@ -0,0 +1,82 @@
# 常见问题与解决方案
## 钱包相关
### Q: check-wallet 返回 code=200 但 message 为"已申请开通，等待授权"
**原因**：钱包已申请但尚未在支付宝内完成授权
**解决**：调用 alipay-authenticate-wallet 技能，引导用户扫码完成授权
### Q: check-wallet 返回 code=500
**原因**：钱包未开通
**解决**：调用 alipay-authenticate-wallet 技能执行 apply-wallet
### Q: bind-wallet 返回"买家和卖家不能相同"
**原因**：绑定的钱包账号与商品卖家是同一个支付宝账号
**解决**：使用另一个支付宝账号重新绑定
### Q: bind-wallet 返回"服务sellerId不匹配"
**原因**：绑定的钱包对应的卖家ID与Payment-Needed中的卖家ID不一致
**解决**：关闭当前钱包，用正确的卖家账号重新绑定
---
## 支付相关
### Q: 402-buyer-pay 返回"请求已过期"
**原因**：Payment-Needed 数据已超过 pay_before 时间
**解决**：重新从服务器获取新的 Payment-Needed 数据
### Q: 402-buyer-pay 返回"卖家签名校验失败"
**原因**：Payment-Needed 数据中的签名与当前卖家私钥不匹配
**解决**：重新从服务器获取 Payment-Needed 数据并重试（最多3次）
### Q: 支付二维码已过期
**原因**：用户长时间未扫码支付
**解决**：重新发起支付，获取新的二维码
### Q: 轮询超时（>3分钟无响应）
**可能原因**：
1. 用户尚未扫码支付
2. 支付宝网络延迟
3. 服务器未运行
**解决**：提示用户检查是否已完成扫码，或稍后重试
---
## 交付与获取相关
### Q: 支付成功但未获取到网盘链接
**原因**：订单可能异常或调用 `/verify` 接口失败
**解决**：检查 `Payment-Proof` 凭证是否构造正确并传入，或检查系统后端服务状态
### Q: 接口返回 402 而非网盘链接
**原因**：Payment-Proof 格式不正确或交易号不匹配
**解决**：使用正确的 trade_no 重新生成 Payment-Proof 并再次调用 `/verify` 接口
---
## 服务器相关
### Q: 无法连接到 STORE_BASE_URL (如 https://store.bushrose.cn)
**原因**：Flask 服务器未启动或域名解析问题
**解决**：
确认后台服务器已正确部署并运行，如需本地测试，可运行：
```bash
python app.py
```
### Q: 服务器返回 500 错误
**原因**：服务器代码异常
**解决**：管理员需查看终端日志或错误日志（如 `logs/error.log`），检查 `.env` 配置及代码是否正确
---
## 网络相关
### Q: alipay-bot 命令执行超时
**原因**：网络连接不稳定
**解决**：检查网络连接，可重试1次；连续失败提示用户检查网络
### Q: curl 命令返回 connection refused
**原因**：后台服务器未启动或端口被占用
**解决**：确认服务器已启动，检查对应端口是否被其他程序占用