十元云铺万元利

概述

普通人的云端小批发部：一句话或一张图，立刻拥有专属卖货档口页。

什么时候用本 Skill

用户上传产品图片，或用文字描述「我有什么货」，想要一个能发给客户、发朋友圈/抖音/微信群的展示页时。

不适用：需要在线支付/下单系统（本产品不参与交易）、需要企业官网级定制。

使用流程

第 1 步：了解货品

用户发图（可选，最多 3 张）或文字描述（产品名 + 特点 + 价格 + 联系方式更好）。信息不全时只追问一次缺的关键项（价格、联系方式），不要反复盘问。

第 2 步：免费预览（付费前必做，不下单、不扣费）

在提到付款之前，先让用户看到成品大概长什么样。 这一步不调用建店接口，不产生任何费用。

1. 给样板档口链接，让用户点开看真实效果（档口页、AI 示意图角标、口播字幕视频、联系老板卡片）：

• 云铺目录（全部样板档口）：https://ruancyai.com/cloud/
• 样板档口 1（AI 示意图 + 口播字幕视频）：https://ruancyai.com/cloud/shop/s-MTSW3ty-（爱媛果冻橙直供）
• 样板档口 2：https://ruancyai.com/cloud/shop/s-FXzvh2o-（大连海参直供）

样板档口为演示用，页面上的电话为占位号，转述时如实说明「这是样板店」。

1. 根据用户描述，由你（Agent）当场写一份文案草稿给用户看：
   • 店名 1 个 + 一句标语
   • 3 条卖点（只用用户提供的事实，不得夸大、不得添加功效宣称）
   • 口播稿约 80–120 字（价格、联系方式按用户原文）
   • 一段朋友圈分享文案

明确告诉用户：「这是预览草稿。正式生成时后端 AI 会参考你确认过的要点重新生成，措辞会有些不同；另外会配上产品图（没有实拍图时为 AI 示意图）、口播音频和口播字幕视频，生成一个可以直接转发的独立链接。」

1. 问用户要不要改：可以改要点、价格、联系方式，改草稿不收费，可以改到满意为止。
2. 用户满意后再说明价格：「生成正式档口 ¥9.9 一次，付款后约 1 分钟出链接。」等用户明确说要生成，才进入第 3 步。

第 3 步：前置检查与付款建店（用户明确确认后）

前置检查：确认 weixinpay 支付插件已安装（下单前必做）

下单前先检查当前环境能否调用微信支付工具 weixinpay_pay（WorkBuddy 中通常为 mcp__weixinpay__weixinpay_retry_pay，由 SkillHub 的微信支付插件 weixinpay-pay 提供）。

• 已安装、可调用 → 继续下面的下单步骤。
• 未安装或无法调用 → 停止，不下单，如实告诉用户：

生成正式档口需要微信支付，你这边还没有安装微信支付插件（weixinpay-pay）。请先在 SkillHub / WorkBuddy 安装它，装好后跟我说一声，刚才确认的文案我都记着，直接帮你生成。

不得绕过支付免费建店（fail closed），也不得编造档口链接。免费预览（第 2 步）不涉及支付，未安装插件也照常进行。

下单与建店

1. 调用 POST /cloud/api/shops（契约见 references/api.md）。description 写入用户在第 2 步确认过的要点（产品名、规格、价格、产地、卖点、电话/微信，按用户原文），图片放 images。
2. 首次请求返回 HTTP 402 + WeixinPay-Required 头。拿到 402 后立即调 weixinpay_pay 触发支付卡片（传 paymentCode），中间不要插入文字确认提问——用户已在第 2 步确认过，支付卡片本身就是最终确认：在卡片上取消不扣费；不付则订单 15 分钟后自动过期，无任何损失。
3. 支付完成后，带 X-PAYMENT 头重试同一请求，并重新上传同样的图片（402 时服务端已清理首次上传的图片，重试不带图会变成无实拍图、改走 AI 示意图）。
4. 记住这次的 payment_code：后续给这家档口换微信二维码要用它（见第 5 步）。

第 4 步：交付

把返回的店名、档口链接、分享文案、口播音频/视频地址交给用户，引导直接转发。图片如为 AI 示意图（isAiGenerated: true），必须说明「示意图」。

• 返回 409：同一笔付款的档口正在生成，等 10–20 秒后用同一 X-PAYMENT 再请求一次，不要重新下单。
• 同一 X-PAYMENT 再次请求会直接返回原档口（不新建、不再扣费）。想开第二家店需要重新付款。
• 付款后建店报错（5xx）：用同一 X-PAYMENT 重试，不会再扣费；多次仍失败，如实告诉用户「已付款但生成失败，请联系服务方人工核实退款」，不得编造链接。

第 5 步：挂微信二维码（可选，不收费）

用户提供微信二维码时，调用 POST /cloud/api/shops/{shopId}/qrcode，必须带 X-PAYMENT 头，值为建这家店时的那笔 payment_code。没有凭证或凭证不属于这家店会返回 403——这是为了防止别人替换店主的收款码。凭证丢失时如实告知用户，请其联系服务方处理，不得尝试其他办法绕过。

关键约束（必须遵守）

• 实拍与示意要如实转达：返回中 isAiGenerated: true 的图是 AI 示意图，转述给用户时必须说明「示意图」，不得说成实拍。口播视频由 AI 示意图（或首张实拍图）+ 口播音频合成，转述时同样如实说明。
• 不承诺交易能力：本产品只做展示导流，不得向用户承诺在线支付、担保、代收货款。
• 联系方式如实传递：电话/微信号按用户提供的原文填入，不得代拟。
• 后端未部署时的降级：若 https://ruancyai.com/cloud 不可达，如实告知用户「云铺服务尚未上线」，不得编造链接。
• 付费前必须先给免费预览：未展示样板档口与文案草稿、未得到用户明确确认前，不得调用建店接口触发 402。
• 下单前必须做前置检查：确认 weixinpay 支付插件（weixinpay-pay，工具 weixinpay_pay）已安装；未安装或无法调用时停止并提示安装，不下单、不放行。
• 不得承诺自动退款：本服务不提供自动退款与公开自助退款；只能如实说明「异常订单由服务方人工核实后处理」。
• 价格与承诺归用户：生成内容中的价格、产地、卖点均来自用户描述，Agent 不得自行加价、夸大或补充未经用户确认的功效宣称（尤其食品、酒类不得宣传保健疗效）。

后端服务

• 线上地址：https://ruancyai.com/cloud
• 档口页：https://ruancyai.com/cloud/shop/{shopId}
• 接口契约：references/api.md（创建档口 / 上传二维码 / 获取分享素材 / videoUrl 字段）

视频与 AI 示意图（v0.3.3+，动态镜头 v0.3.4，字幕 v0.3.5）

建店时后端自动生成两类媒体，均失败不阻断（生成不了就无图/无视频，建店照常成功）：

• 建店响应新增 videoUrl 字段（绝对地址；无视频为 null）
• 运维坑（重要）：生图模型必须是 gpt-image-1。若后端 src/ai.ts 误配 dall-e-3，线上接口返回 400 The model 'dall-e-3' does not exist，AI 示意图永远失败 → 无图 → 视频生成条件（必须有图）不满足 → videoUrl 恒为 null（2026-08-19 线上事故根因，已修复）
• 服务器需安装 ffmpeg（/usr/local/bin/ffmpeg，实测 7.0.2）
• 后端版本对应关系见 CHANGELOG.md

版本

• 当前版本：0.3.6（付费前免费预览：样板档口链接 + 店名/卖点/口播稿草稿，满意再付款；下单前检查微信支付插件；计费与退款说明改为与后端实际一致：先付后建、一笔付款一家店、建店出错同一笔付款重试不再扣费、二维码需建店付款凭证、退款由服务方人工核实）
• 上一版：0.3.5（Ken Burns 动态口播字幕视频：在 v0.3.4 动态镜头基础上叠加白字黑底字幕，价格 / 电话 / 微信自动高亮，适配静音浏览场景）
• 0.3.5 上一版：0.3.4（Ken Burns 动态镜头口播视频：缓慢推近 + 平移 + 淡入淡出，替代 v0.3.3 的静态定格画面；视频能力随 v0.3.3 引入）
• v0.3.3 上一版：0.3.2（Pay Skill 收费版：¥9.9/次 = 990 分；后端新增 src/pay.ts X402 支付模块，微信 Native 下单 → X402 AI 预下单 → HTTP 402 支付触发 → 回调验签 → 退款 全链路）
• v0.3.2 上一版：缩略图墙、备案号、OG 分享卡片、上传白名单 + 魔数校验 + 限流

Pay Skill 改造（X402 协议 — 代码级实现）

本 Skill 已按 SkillHub 官方《升级为 Pay Skill》教程完成 代码级 X402 协议集成。后端 src/pay.ts 模块实现了完整的微信支付 Agent Pay X402 流程，src/server.ts 在建店接口中集成了支付闸门。

整体架构（4 步）

Agent 调用 POST /cloud/api/shops
  → 后端创建微信 Native 订单（拿 code_url）
  → 后端用 SkillHub 开发者密钥签名，调 X402 AI 预下单（拿 payment_code）
  → 后端返回 HTTP 402 + WeixinPay-Required 头
  → Agent 前置检查：weixinpay 支付插件（weixinpay-pay / weixinpay_pay）已安装？未安装 → 停止并提示安装
  → Agent 调 weixinpay_pay 触发用户支付授权
  → 用户支付成功后 Agent 重试原请求（带 X-PAYMENT 头）
  → 后端验签放行，原子认领这笔付款（一笔付款只建一家店），执行业务逻辑（AI 识别 → TTS → 落库），落库后把付款绑定到该档口

Step 1：开发者密钥（RSA-2048）

在 SkillHub 商户中心「开发者密钥」页面生成 RSA-2048 密钥对：

• pub_key_id：形如 PUB_KEY_ + 32 位大写 HEX，填入 X402 预下单请求
• private_key_pem：RSA-2048 私钥（PEM 格式），用于 SHA256withRSA 签名
• 存储在服务器 .env 的 SKILLHUB_PRIVATE_KEY_PEM 中

Step 2：微信 Native 下单

后端 createNativeOrder() 调用微信支付 Native 下单接口获取 code_url：

POST https://api.mch.weixin.qq.com/v3/pay/transactions/native
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="...",signature="..."
Body: { appid, mchid, description, out_trade_no, notify_url, amount: { total: 990, currency: "CNY" } }
→ { "code_url": "weixin://wxpay/bizpayurl?pr=..." }

使用微信商户 API v3 证书私钥签名（WECHAT_PRIVATE_KEY_PEM + WECHAT_SERIAL_NO）。

Step 3：X402 AI 预下单

后端 x402Preorder() 用 SkillHub 开发者密钥签名，调 X402 预下单接口换取 payment_code：

3.1 构造 L2 业务 JSON → Base64 编码 → payment_required

{
  "skill_info": { "skill_id": "tenyuan-cloud-shop", "skill_version": "0.3.6" },
  "pay_type": "SKILL_PAY",
  "pay_mode": "AUTH_AND_PAY",
  "pay_items": [{ "product_id": "SP...", "pay_data": { "type": "code_url", "value": "<code_url>" } }],
  "expires_at": "<unix_ts + 15min>"
}

3.2 构造 5 行签名串（每行以 n 结尾，包括最后一行）：

POSTn/palmpayminiapp/clawagentpay/preordern{timestamp}n{nonce_str}n{payment_required}n

3.3 SHA256withRSA 签名（PKCS#1 v1.5，用 SkillHub 开发者私钥）→ Base64 → signature

3.4 组装 L1 请求体并发送：

POST https://payapp.weixin.qq.com/palmpayminiapp/clawagentpay/preorder
Content-Type: application/json
Body: { signature_type: "SKILLHUB-SHA256-RSA2048", developer_platform: "SKILLHUB",
        developer_id, pub_key_id, nonce_str, timestamp, signature, payment_required }
→ { "payment_code": "xY9zAbc123def456" }

Step 4：返回支付触发标识（HTTP 402）

后端 buildPayment402() 构建标准 X402 响应：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
Content-Type: application/json

{
  "data": { "message": "本次创建档口需要付费", "out_trade_no": "cloud_...", "amount_fen": 990 },
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

重试机制

支付成功后，Agent 携带 X-PAYMENT 请求头（值为 payment_code）重试原业务请求：

POST /cloud/api/shops
Headers:
  X-PAYMENT: <payment_code>

后端收到 X-PAYMENT 后执行前置检查：

1. 查 payments 表确认 payment_code 对应订单状态
2. 若 DB 未标记已付 → 主动调微信支付查询 API（GET /v3/pay/transactions/out-trade-no/{out_trade_no}）确认
3. 已付 → 原子认领这笔付款：
   • 未绑定档口 → 放行执行业务逻辑，落库后绑定 shop_id；建店异常则释放认领，允许同一笔付款重试
   • 已绑定档口 → 直接返回原档口（不新建、不再调用任何 AI、不再扣费）
   • 另一请求正在建店 → 返回 409（认领超过 10 分钟视为失效，可重新认领）
4. 未付 → 再次返回 402

微信支付回调

后端 decryptNotify() 处理微信支付异步通知（POST /cloud/api/pay/notify）：

• 使用 API v3 密钥（AES-256-GCM）解密 resource.ciphertext
• 解密成功且 trade_state=SUCCESS → 更新 payments 表 status='paid'
• 返回 {"code":"SUCCESS"} 停止微信重试

退款

本版本不提供自动退款，也不开放公开自助退款端点。后端 POST /cloud/api/pay/refund/{out_trade_no} 仅供服务方管理员使用（需管理员凭证，无凭证一律 404），由服务方人工核实后发起微信支付 refund：

• 调用 POST /v3/refund/domestic/refunds（微信商户私钥签名）
• 退款成功 → 更新 payments 表 status='refunded'
• 人工核实的情形：重复支付、金额不符、已付款但建店反复失败等订单异常
• Agent 不得调用退款端点，不得向用户承诺「自动退款」或「多少小时内全额退」

异常处理与配置检查

• 配置检查：后端 isPayConfigured() 在服务启动时检查 8 个环境变量是否全部就位；未就位时自动降级为免费模式（建店不收 402），就位后自动激活付费模式
• 订单号传递：从微信 Native 下单 → X402 预下单 → 回调验签 → 退款，全程以 out_trade_no（order_id）作为唯一订单号传递
• 支付超时：payment_code 15 分钟后自动过期，用户需重新发起建店请求
• 重复支付：out_trade_no 唯一约束 + DB 状态校验防止重复扣费；同一 payment_code 只能绑定 1 个档口，重复建店请求返回原档口
• 状态查询：GET /cloud/api/pay/status/{outTradeNo} 只返回状态、金额、支付时间，不返回 payment_code
• 回调丢失：若微信异步通知未到达，重试时主动调微信查询 API 补偿（queryPaymentStatus()）

环境变量清单

# 微信支付商户 API v3
WECHAT_APPID=wx...
WECHAT_MCHID=1733356762
WECHAT_APIV3_KEY=<32位APIv3密钥>
WECHAT_SERIAL_NO=<商户证书序列号>
WECHAT_PRIVATE_KEY_PEM=<商户API证书私钥PEM>

# SkillHub 开发者密钥
SKILLHUB_DEVELOPER_ID=sh-XXXXXXXX
SKILLHUB_PUB_KEY_ID=PUB_KEY_XXXXXXXXXXXXXXXX
SKILLHUB_PRIVATE_KEY_PEM=<SkillHub开发者RSA私钥PEM>

# 支付配置
PAY_AMOUNT_FEN=990
PAY_NOTIFY_URL=https://ruancyai.com/cloud/api/pay/notify

数据库

payments 表记录每笔支付订单：

关键词索引（供 SkillHub 改造检查器识别）

X402、402 Payment、X-PAYMENT、WeixinPay-Required、WeixinPay、facilitator、payment challenge、payment_code、out_trade_no、order_id、code_url、preorder、palmpayminiapp/clawagentpay/preorder、SHA256withRSA、SKILLHUB-SHA256-RSA2048、developer_id、pub_key_id、AUTH_AND_PAY、SKILL_PAY、payment_required、nonce_str、refund、notify_url、quota、proof、前置检查、订单号传递、异常处理、decryptNotify、isPayConfigured

计费边界

成功创建 1 个云铺档口页计 1 次 ¥9.9：用户确认后先付款，付款确认后才建店；同一笔付款只对应 1 个档口。不算付费的项：

• 免费预览：样板档口链接、店名/卖点/口播稿/分享文案草稿及其修改
• 调用 POST /cloud/api/shops/{shopId}/qrcode 上传微信二维码
• 调用 GET /cloud/api/shops/{shopId}/share 获取分享素材
• 调用 GET /cloud/api/pay/status/{outTradeNo} 查询支付状态
• 付款后建店出错，用同一笔付款重试（不再扣费）
• 同一笔付款重复提交建店（返回原档口）
• 用户取消支付（X402 协议保证 payment_code 过期不扣）