commit bacafa106465b70123a30dca638ab19e59dd7f85
Author: Axure Cloud <axure-cloud@local>
Date:   Thu Jun 25 02:27:48 2026 +0800

    Initial commit for agent-1yuan-purchase-skill

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4ea746c
--- /dev/null
+++ b/README.md
@@ -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 会自动帮你检查支付环境、搜索商品、创建订单，并生成支付二维码（或静默支付），完成付款后直接把网盘链接交给你！
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..4e1fc53
--- /dev/null
+++ b/SKILL.md
@@ -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` | 常见问题与解决方案 |
diff --git a/references/cli-setup.md b/references/cli-setup.md
new file mode 100644
index 0000000..96089ff
--- /dev/null
+++ b/references/cli-setup.md
@@ -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` → 未安装，需要执行安装流程
diff --git a/references/openapi.yaml b/references/openapi.yaml
new file mode 100644
index 0000000..edbba9e
--- /dev/null
+++ b/references/openapi.yaml
@@ -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 等交付信息
\ No newline at end of file
diff --git a/references/payment-flow.md b/references/payment-flow.md
new file mode 100644
index 0000000..38e1054
--- /dev/null
+++ b/references/payment-flow.md
@@ -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 执行任何后续命令
\ No newline at end of file
diff --git a/references/troubleshooting.md b/references/troubleshooting.md
new file mode 100644
index 0000000..85205b5
--- /dev/null
+++ b/references/troubleshooting.md
@@ -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
+**原因**：后台服务器未启动或端口被占用
+**解决**：确认服务器已启动，检查对应端口是否被其他程序占用
\ No newline at end of file