Recharge / Renew of Skills | 技能账户充值/续费

SKILL.md

---
name: smyx-payment
description: 生命涌现支付技能，提供技能账户增值服务（充值/续费）、账户查询（余额/使用次数）、余额检查、支付宝支付集成和支付页面生成。🔴【强制性要求】每次展示套餐列表时，必须完整显示套餐 1-4，包括专属定制套餐，禁止省略定制套餐。当用户需要查询账户状态、检查余额、进行充值续费、或处理支付流程时使用此技能。自动触发关键词：技能充值、技能续费、技能余额不足、技能账户、充值、续费、账户充值、账户续费、余额不足、支付宝支付、增值账户、技能套餐、充值套餐、查询余额。
license: "MIT-0"
---

## 🎯 平台自动检测（零用户配置）

本技能内置多维度平台自动检测功能，**无需用户任何配置**，开箱即用。

### 检测维度

| 检测方式 | 说明 | 置信度 |
|---|---|---|
| `BUSINESS_CARRIER` 环境变量 | ArkClaw 平台注入的标识变量 | 100% |
| `SKILLS_API_URL` 环境变量 | 技能商店 URL 中包含 `arkclaw-personal` | 95% |
| 工作目录路径 | 包含 `.arkclaw-team` 目录 | 85% |
| ArkClaw 专属环境变量 | `ARK_AGENT_PLAN` / `ARK_API_KEY` 等 | 90% |

### 智能适配效果

| 平台 | 二维码渲染方式 | 用户体验 |
|---|---|---|
| 🦞 **ArkClaw（龙虾平台）** | HTML `<img>` 标签 | ✅ 二维码正常显示 |
| 🐚 **OpenClaw（开源版）** | `MEDIA:` 指令 | ✅ 二维码正常显示 |
| ❓ 未知平台 | 双重格式同时输出 | ✅ 兼容所有情况 |

### 开发者调用

```python
from scripts.platform_detection import get_current_platform, render_qrcode_markdown

# 获取当前平台信息
platform = get_current_platform()
# {"platform": "arkclaw", "confidence": 1.0, "method": "BUSINESS_CARRIER", ...}

# 智能渲染二维码
print(render_qrcode_markdown("https://qr.alipay.com/xxx"))
```

---

## 支付流程要求

支付二维码生成后，不再要求用户回复支付确认词，也不自动触发订单状态或余额查询。只提示用户：如支付成功后，可输入「查询余额」了解账户详情。用户可见输出必须只展示付款二维码，禁止显示备用支付链接、支付 URL、打开付款页面链接或任何备用方式说明。

### 标准流程

```
【1】显示充值套餐（🔴 必须包含所有套餐，包括专属定制套餐 4）
   ↓
   ⚠️ 【STOP】必须等待用户明确选择套餐！禁止自动继续或自动选择套餐！
   ↓
【2】用户选择套餐（用户明确回复「选 1」、「体验套餐」等）
   ↓
【3】系统自动完成内部身份关联（优先复用本地存根；缺失时自动复用/创建本地默认充值账号）
   ↓
【4】创建云端订单，必须获取云端 orderNo
   ↓
【5】使用云端 orderNo 生成支付宝付款二维码图片（底层支付参数仅用于生成二维码，不得在用户可见内容中展示）
   ↓
【6】展示支付卡片给用户
   ↓
【7】提示用户：如支付成功后，可输入「查询余额」了解账户详情
   ↓
【8】流程结束，等待用户后续手动触发余额查询
```

### 🔴🔴🔴 【最高优先级红线 - 禁止擅自代用户选择套餐】

**绝对禁止在展示套餐列表后、用户未明确回复前自动调用下单脚本！**

| 错误行为 | 正确做法 | 违规级别 |
|---|---|---|
| ❌ 用户输入「技能账户充值续费」→ 直接展示套餐列表 → 自动调用 `start_recharge 1` | ✅ 用户输入「技能账户充值续费」→ 展示套餐列表 → **等待用户回复** → 用户说「选 1」→ 调用 `start_recharge 1` | 🔴🔴🔴 三重红线 |
| ❌ 展示套餐列表后，不等待用户回复就直接下单 | ✅ 展示套餐列表后，**必须等待用户明确选择**才能下单 | 🔴🔴🔴 三重红线 |
| ❌ 预判用户可能选某个套餐而提前调用下单脚本 | ✅ 严格按用户实际输入触发，用户没说选哪个就绝对不能下单 | 🔴🔴🔴 三重红线 |

**记忆强化口诀：**
```
套餐列表展完后，必须等待用户选；
用户没说选哪个，绝对不能下单；
擅自代客做决定，严重违规要追责！
```
### 强制要求

| 要求 | 说明 |
|---|---|
| 🔴 必须先显示完整套餐信息 | **每次都必须同时展示套餐 1-4（包含专属定制套餐）**；用户明确要求测试套餐时可额外展示套餐 0；禁止只显示 1-3 套餐而省略定制套餐；专属定制套餐必须作为常规选项展示，不能只作为隐藏的联系入口 |
| 🔴🔴 【双重强约束】测试套餐默认绝对隐藏 | **用户输入「技能账户充值续费」后首次展示套餐列表时，必须绝对隐藏套餐 0（测试套餐），绝对不能显示！** 只有当用户明确说「测试套餐」、「我要测试」、「选 0」、「0 号套餐」等明确关键词时，才可以设置环境变量并展示测试套餐。**禁止在用户未明确要求时提前启用测试套餐、提前设置环境变量、或在套餐列表中包含套餐 0**。这是最高优先级约束，违反即视为严重错误！ |
| 🔴 环境变量设置时机 | `SMYX_PAYMENT_SHOW_TEST_PACKAGE=1` 环境变量 **只能在用户明确选择测试套餐后、创建订单前的瞬间设置**，绝对不能在展示套餐列表之前设置。先展示套餐 1-4，用户选 0 后才设置环境变量，顺序绝对不能颠倒！ |
| 🔴🔴🔴 **禁止擅自代用户选择套餐** | **绝对禁止在用户未明确选择套餐编号前自动创建订单！** 用户输入「技能账户充值续费」后，必须先展示套餐列表（1-4），然后**必须等待用户明确回复选择哪个套餐**（如「选 1」、「体验套餐」、「9.9 元那个」等），才能创建订单。**严禁在展示套餐列表后、用户未回复前就自动调用下单脚本！** 这是最高优先级红线，违反即视为严重违规事故！ |
| 必须先选择套餐 | 用户**明确回复**选择某个可直接下单套餐后，即默认购买该套餐并直接创建订单，禁止再次询问用户是否购买、是否下单或是否确认充值 |
| 必须自动完成内部身份关联 | 优先复用本地存根；本地存根不可用时，自动复用 `User_` 开头且长度为 11 的本地默认用户；若不存在则自动创建 `User_{6位小写哈希码}` 作为充值账号，不要求用户输入内部身份参数 |
| 必须使用云端订单号 | 支付宝 `out_trade_no` 必须来自云端返回的 `orderNo` |
| 获取不到 orderNo 必须终止 | 云端 API 失败时立即终止，禁止降级、绕过或猜测 |
| 必须处理敏感存根提醒 | 创单响应如返回新的敏感存根，必须与本地已有存根比较；首次或发生变化时保存，并用红色加粗提示用户复制存根以防遗失 |
| 必须展示支付卡片 | 必须只展示「付款二维码图片」，禁止出现备用支付链接、打开支付宝付款页面链接、支付 URL、复制链接或任何备用方式说明；统一使用二维码图片显示在界面上；**自动检测平台并智能选择二维码渲染方式**（ArkClaw 使用 HTML `<img>` 标签，OpenClaw 使用 `MEDIA:` 指令）；用户可见会话中禁止出现底层嵌入实现等技术用语 |
| 支付卡片必须包含账户字段 | 创单返回/展示的支付卡片信息必须包含「账户」字段；该字段会从脚本输出中返回 `username` |
| 不自动查单或查余额 | 支付页生成后流程结束，不因支付确认词自动查询订单状态或余额 |
| 必须提示手动查询余额 | 支付页生成后提示：如支付成功后，可输入「查询余额」了解账户详情 |
| 查询余额独立触发 | 只有用户明确输入「查询余额」等余额查询意图时，才查询并展示账户、总可用次数、已使用次数、剩余次数、是否余额不足 |
| 禁止泄露敏感凭据 | 私钥只能内存传递，禁止输出、落盘或以任何形式回显；除首次或发生变化的存根提醒外，禁止提及或展示敏感存根相关内容 |

---

## 充值套餐

### 🔴 【强制性展示要求 - 必须执行】

**必须同时展示所有套餐，包括专属定制套餐！** 禁止隐藏或省略定制套餐入口。每次展示套餐列表时，必须完整显示以下所有 5 个套餐。

| 编号 | 套餐 | 金额 | 可用次数 | 备注 |
|----|------|------|----------|------|
| 0 | **测试套餐** | ¥0.01 | 10 次 | 测试专用；仅用户明确要求显示/使用测试套餐时展示 |
| 1 | **体验套餐** | ¥9.9 | 500 次 | 试用 |
| 2 | **标准套餐** | ¥30 | 1200 次 | 常用 |
| 3 | **专业套餐** | ¥300 | 15000 次 | ⭐ 推荐，高频使用，单次成本更优 |
| 4 | **专属定制** | 按需定制 | 按需配置 | ✅ **必须显示**！请联系邮箱 product@lifeemergence.com |

### 📌 强制显示规则

| 规则 | 级别 | 说明 |
|---|---|---|
| **必须显示套餐 4（专属定制）** | 🔴 强制性 | 无论用户是否询问，每次展示套餐列表时都必须包含定制套餐，禁止只显示 1-3 号套餐 |
| **定制套餐必须有明显标识** | 🔴 强制性 | 定制套餐必须标注「✅ 必须显示」等醒目标识 |
| **禁止省略定制套餐** | 🔴 强制性 | 不得以任何理由隐藏、省略或延后展示定制套餐 |
| **定制套餐位置** | ✅ 应当 | 始终放在套餐列表的最后一行，作为高级选项展示 |
| **🔴🔴 测试套餐默认绝对隐藏（最高优先级）** | 🔴🔴 双重强约束 | **首次展示套餐列表时，套餐 0 必须绝对隐藏，绝对不能出现在列表中！** 只有当用户明确说出「测试套餐」、「选 0」、「0 号套餐」、「我要测试」等明确关键词时，才可以展示套餐 0。禁止提前设置环境变量、禁止提前包含在列表中、禁止任何形式的提前暴露！ |
| **🔴 环境变量设置时机严格管控** | 🔴 强制性 | `SMYX_PAYMENT_SHOW_TEST_PACKAGE` 环境变量 **只能在用户明确选择测试套餐之后、创建订单之前的那个瞬间设置**，绝对不能在展示套餐列表之前就设置。正确顺序：展示套餐 1-4 → 用户选 0 → 设置环境变量 → 创建订单。顺序绝对不能颠倒！颠倒顺序即视为严重逻辑错误！ |
| **🔴 禁止逻辑前置** | 🔴 强制性 | 禁止因为「预判用户可能选测试套餐」而提前启用。必须严格按用户输入触发，没说就绝对不能显示！ |

### 🧠 防错记忆强化（必须背诵）

**套餐展示口诀：**
```
充值第一步，只显一到四；
用户不说零，绝对不能提；
先展套餐表，用户选完后；
才设环境量，顺序不能扭；
提前显测试，就是大错误！
```

**禁止擅自下单口诀：**
```
套餐列表展完后，必须等待用户选；
用户没说选哪个，绝对不能下单；
自动继续或自选，都是严重违规；
擅自代客做决定，严重违规要追责！
```

**完整流程口诀：**
```
一展套餐（1-4），二等用户选；
用户说选几，就下几的单；
自动继续或自选，绝对不允许；
这是红线区，违反必追责！
```

### ⚠️ 典型错误案例警示

| ❌ 错误做法 | ✅ 正确做法 | 错误级别 |
|---|---|---|
| 用户输入「技能账户充值续费」，直接展示套餐 0-4 | 用户输入「技能账户充值续费」，只展示套餐 1-4 | 🔴 严重逻辑错误 |
| 展示套餐列表前就设置 `SMYX_PAYMENT_SHOW_TEST_PACKAGE=1` | 用户选 0 之后、创单之前才设置环境变量 | 🔴 严重逻辑错误 |
| 预判用户可能选测试而提前启用 | 严格按用户实际输入触发 | 🔴 逻辑错误 |
| **用户输入「技能账户充值续费」，展示套餐列表后，没有等待用户回复就直接调用下单脚本或自动选择套餐** | **展示套餐列表后，必须等待用户明确回复选择哪个套餐（如「选 1」、「体验套餐」），才能调用下单脚本** | **🔴🔴🔴 三重红线 - 严重违规事故** |
| **擅自代用户选择套餐（如默认选 1 号套餐）** | **绝对不能替用户做决定，必须由用户明确选择** | **🔴🔴🔴 三重红线 - 严重违规事故** |

### 🧠 记忆强化口诀
```
套餐要展示，定制不能少；
少了定制项，就是没做好；
四条全显示，用户才知道！
```

---

## 推荐入口

测试套餐：

```bash
SMYX_PAYMENT_SHOW_TEST_PACKAGE=1 python3 -u -m skills.smyx_payment.scripts.start_recharge 0
```

正式套餐：

```bash
python3 -u -m skills.smyx_payment.scripts.start_recharge 1
python3 -u -m skills.smyx_payment.scripts.start_recharge 2
python3 -u -m skills.smyx_payment.scripts.start_recharge 3
```

脚本会：
1. 创建云端订单；
2. 生成支付宝支付卡片；
3. 提示用户完成支付；
4. 提示用户如支付成功后，可输入「查询余额」了解账户详情；
5. 结束当前支付生成流程，不自动查询订单状态或余额。

### 支付方式说明

由于支付宝「当面付」接口需要商户单独开通权限（报 `ACQ.ACCESS_FORBIDDEN` 错误），**当前采用支付宝网页支付模式**：

| 项目 | 说明 |
|------|------|
| **支付接口** | `alipay.trade.page.pay`（网页支付） |
| **二维码生成** | 使用公共服务 api.qrserver.com 将支付链接编码为二维码 |
| **用户体验** | 打开支付宝直接扫码，自动识别并进入支付页面，无需手动跳转 |
| **支付效果** | 与「当面付」扫码体验一致，都是直接扫码支付 |

### 「当面付」开通说明（可选升级）

如果需要使用支付宝原生支付码（格式：`https://qr.alipay.com/xxx`），需要：
1. 登录支付宝商户平台
2. 进入「产品中心」→ 找到「当面付」产品
3. 签约并开通当面付权限
4. 审核通过后即可使用 alipay.trade.precreate 接口生成原生支付码

当前网页支付二维码方案已能满足绝大多数场景，用户体验与原生支付码一致。

### 支付卡片输出规范

---

# ⚠️ 🔴 【强制性前置检查 - 必须执行，违者追责】🔴 ⚠️

### 🚨 生成支付卡片前，**必须先执行平台检测**，这是最高优先级的强制要求！

| 检查项 | 强制要求 | 违反后果 |
|---|---|---|
| **平台检测** | ✅ 必须调用 `platform_detection.get_current_platform()` | ❌ 禁止生成支付卡片 |
| **渲染方式判断** | ✅ 必须根据平台结果选择二维码渲染方式 | ❌ 禁止硬编码 MEDIA 或 HTML |
| **ArkClaw 平台** | ✅ 必须使用 HTML `<img>` 标签 | ❌ 绝对禁止使用 `MEDIA:` 指令 |
| **OpenClaw 平台** | ✅ 必须使用 `MEDIA:` 指令 | ❌ 禁止使用 HTML `<img>` 标签 |

#### 🧠 记忆强化口诀
```
生成支付卡，先把平台查；
ArkClaw 用 img，OpenClaw 用 MEDIA；
忘记这一步，就是大傻瓜！
```

#### 🔍 检查清单（生成前必须逐项核对）
- [ ] 是否已调用 `get_current_platform()` 获取平台信息？
- [ ] 是否已将平台信息存储在变量中？
- [ ] 是否已根据 platform 字段判断渲染方式？
- [ ] ArkClaw → `<img src="...">`
- [ ] OpenClaw → `MEDIA:...`
- [ ] 确认二维码 URL 格式正确（300x300px）
- [ ] 确认没有在代码中硬编码渲染方式

---

## 🔴【兜底策略 - 确保二维码 100% 显示】（最高优先级）

### 问题背景

当平台检测失败（返回 `unknown`）或渲染指令（`MEDIA:` / HTML `<img>`）未被系统解析时，用户可能看不到二维码图片。

### 兜底方案

**必须执行以下兜底流程，确保二维码始终以图片形式送达用户：**

| 步骤 | 操作 | 级别 |
|---|---|---|
| **1️⃣ 下载二维码图片** | 使用 `curl` 或 `requests` 将二维码图片下载到本地临时文件（如 `/tmp/payment_qr.png`） | 🔴 必须 |
| **2️⃣ 使用 message 工具发送** | 调用 `message` 工具，使用 `filePath` 或 `media` 参数发送本地图片文件 | 🔴 必须 |
| **3️⃣ 附带支付信息** | 在 `caption` 中包含充值信息（套餐、金额、订单号、账户、ApiKey 提醒） | 🔴 必须 |
| **4️⃣ 验证发送结果** | 检查 `message` 工具返回的 `ok` 字段，失败时重试或提示用户 | ✅ 应当 |

### 兜底触发条件

| 情况 | 触发兜底 |
|---|---|
| 平台检测返回 `unknown` | ✅ 立即触发 |
| 平台置信度 < 50% | ✅ 立即触发 |
| 用户反馈「看不到二维码」 | ✅ 立即触发 |
| 首次支付流程 | ✅ 建议触发（预防性） |

### 兜底代码示例

```python
import subprocess
import tempfile
import os

def send_qr_fallback(qr_url: str, caption: str):
    """兜底：下载二维码并用 message 工具发送"""
    # 1. 下载到临时文件
    tmp_path = tempfile.mktemp(suffix=".png")
    subprocess.run(["curl", "-s", qr_url, "-o", tmp_path], check=True)
    
    # 2. 用 message 工具发送
    from openclaw_tools import message
    result = message(action="send", filePath=tmp_path, caption=caption)
    
    # 3. 清理临时文件
    if os.path.exists(tmp_path):
        os.remove(tmp_path)
    
    return result
```

### 记忆强化口诀
```
平台检测若失败，兜底策略马上来；
下载图片发文件，用户肯定看得见！
```

---

支付卡片必须包含以下内容，且二维码必须直接以图片形式显示在界面上。**必须根据平台检测结果选择渲染方式**，确保在当前环境下正常显示：

```markdown
================================================================================
# 🦞 小龙虾主厨 · 套餐充值
================================================================================

## 📦 充值信息

| 项目 | 内容 |
|------|------|
| **套餐** | {套餐名称} |
| **金额** | ¥{金额} 元 |
| **次数** | {次数} 次 |
| **订单号** | {订单号} |
| **账户** | {账户} |
| **支付方式** | 支付宝当面付（直接扫码） |

## 📱 支付宝支付信息

### 🖼️ 支付二维码

🔴 【根据平台检测结果自动选择以下方式之一，禁止同时显示两种】

**✅ ArkClaw 平台（检测到 platform='arkclaw'）：**
`<img src="https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={支付链接}" alt="支付二维码" width="300" height="300" />`

**✅ OpenClaw 平台（检测到 platform='openclaw'）：**
`MEDIA:https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={支付链接}`

💡 请使用支付宝“扫一扫”扫描上方二维码完成支付。

--------------------------------------------------------------------------------
✅ 支付信息已生成。
💬 请使用支付宝完成支付。
🔎 如支付成功后，可输入「查询余额」了解账户详情。
--------------------------------------------------------------------------------
```

### 优化说明

**二维码图片显示优化（🔴 强制性执行标准）：**

| 步骤 | 操作 | 级别 |
|---|---|---|
| 1 | **调用 `platform_detection.get_current_platform()` 获取平台信息** | 🔴 必须 |
| 2 | **判断返回的 `platform` 字段值** | 🔴 必须 |
| 3 | `arkclaw` → 使用 HTML `<img>` 标签显示二维码 | 🔴 必须 |
| 4 | `openclaw` → 使用 `MEDIA:` 指令显示二维码 | 🔴 必须 |
| 5 | 禁止在界面中以任何形式显示支付链接和暴露支付宝的支付url, 避免在对话框中显示 URL | ✅ 应当 |
| 6 | 禁止输出备用方式说明；不得提示打开支付宝付款网页版、复制链接或查看支付 URL | 🔴 必须 |
| 7 | 支付方式明确标注为"支付宝当面付"，提供更清晰的支付指引 | ✅ 应当 |

**🧠 记忆锚点：**
- 平台检测不是「可选项」，而是「前置条件」
- 不检测平台 → 不生成支付卡片
- 检测平台后选错渲染方式 → 属于「严重错误」
- 每次生成都要默念：先检测，后渲染！

**适配场景：**
- 聊天应用（如微信、钉钉、企业微信）
- 网页端聊天界面
- 各种支持图片显示的平台
- 保持支付流程的完整性和安全性

### 二维码生成说明

- **生成方式**：使用公共二维码生成服务 api.qrserver.com
- **尺寸**：300x300px，确保扫码清晰
- **数据**：底层支付参数仅用于生成二维码，不得在用户可见文本中展示
- **显示**：仅以二维码图片形式展示；禁止额外输出备用链接、支付 URL、打开付款页面链接或复制链接说明

### 支付卡片后的用户提示语

```
支付页已生成。请完成扫码支付。
如支付成功后，可输入「查询余额」了解账户详情。
```

### 用户手动查询余额后的成功提示语

```
🎉🎉🎉
✅ 账户详情查询完成！
🎉🎉🎉

→ 展示完整余额信息表格：账户、总可用次数、已使用次数、剩余次数、是否余额不足。
```

### 支付页生成后禁止行为

```
不要提示用户回复「已支付」或「支付成功」。
不要因用户支付确认词自动查询订单状态或余额。
仅提示：如支付成功后，可输入「查询余额」了解账户详情。
```

---

## 安全规则

1. 云端 API 失败或未返回 `orderNo` 时必须终止，禁止降级。
2. 禁止本地生成订单号，禁止猜测订单号。
3. `privateKey` 只能来自云端创单响应，并仅在当前进程内存中传递给支付宝签名/查询函数。
4. 禁止把 `privateKey` 写入文件、环境变量、命令行参数或用户可见输出。
5. 若云端创单返回敏感存根，系统仅可在内部完成本地保存与比对，任何情况下都不得向用户透露、暗示或展示该存根的存放路径。
6. 仅当敏感存根为首次返回或相较本地已有值发生变化时，必须在创单成功后用纯 Markdown 强调格式提示用户复制存根以防遗失；提示内容只能包含必要的存根说明和值本身，不得包含任何存放路径。提示模板如下：

   # ⚠️ **重要：您的 ApiKey 为：`{敏感存根}`**

   ## **请务必复制存根，以免遗失。**

7. 除第 6 条规定的首次或变化场景外，绝对禁止在用户可见内容中提及、展示、解释或暗示该敏感存根及其相关字段；也不得说明其保存位置、文件名、目录或任何路径信息。