SkillHub付费技能收款专家·个人版

概述

SkillHub付费技能收款专家

技能写好了，你的用户一直免费用，你收不到钱——这个技能把「按次收费」从头接好：你说清 6 个参数，拿到的是一套填好参数、能直接跑起来的收款工程。你的用户付款前看不到任何内容；付款后自动核对到账、自动交付；重复请求不会重复扣费。

付费说明

这个技能按次收费：一次 19.90 元，由平台经微信支付代收。一次付费换一次生成——得到一个 Skill 的整套收款工程；同一套参数想重新生成，不再收费。

动手之前，按这个顺序来（顺序别调）：

1. 先默默确认能不能付款（见「第一步」；这一步不用告诉用户）；
2. 先讲价格，再要参数：一句话说清「这次生成 19.90 元，用微信支付」，用户点头再往下；
3. 收集并核对 6 项参数（见「三、收集参数」），确认无误再下单；
4. 拿到 402 → 用户付款 → 带两个 Header 重试解锁（见下方第一~四步）；
5. 解锁之后，才把工程和文档交出去。

后面「第一~第四步」只讲第 4 段。没报价、参数没确认时别去请求 402——那样要么拿到 400，要么给用户一个没头没尾的付款码。

支付段（第 4 段）的执行顺序

第一步：前置检查——当前智能体能否完成本技能的微信支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 weixinpay_pay、weixinpay_register、weixinpay_retry_pay；工具名带前缀也算；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：静默继续本 Skill 的后续流程，不向用户提及本检查。
• 不支持：终止流程且不要发起下单。只向用户说明结论与解决办法（无需解释你如何检查、不要出现具体工具名），按智能体类型提示：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请按 https://skillhub.cn/install/skillhub.md 安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体，或安装微信支付 AI 支付插件后重试。

第二步：请求资源，处理 402 响应

node scripts/pay_gateway.mjs probe --tools <你确认可用的支付工具名>

若返回 HTTP 402，从响应头和响应体中提取两个值，两者都必须保存：

发起支付前再确认一次金额（首次报价已在收集参数前做过），不要静默扣款。402 响应体形如：

{
  "code": "PAYMENT_REQUIRED",
  "message": "本次「SkillHub付费技能收款专家」单次生成需支付 ¥19.90",
  "WeixinPay": {
    "WeixinPay-Required": "xxxxx",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20261026153012a9f3c7e21b4",
  "amount": "19.90",
  "currency": "CNY"
}

probe 已自动把这两个值和本次实际发出的 body 字节落盘（状态目录下的 latest_order.json 与 request_body.json），第四步的「body 与第一次完全一致」由脚本保证。

第三步：发起支付

把 WeixinPay-Required 的值作为 paymentCode，调用 weixinpay_pay 向用户申请支付授权。

也可以先跑 node scripts/pay_gateway.mjs pay --tools <工具名>，它不发起支付，只输出下一步动作指令，由你执行：

{"next_action":"call_tool","tool":"weixinpay_pay","args":{"paymentCode":"xxxxx"}}

• 用户取消支付：如实告知「本次生成未开始，未产生费用」，提示可随时重试。不要自己重试下单。
• 支付失败：按返回的错误如实告知，引导稍后重试。
• 支付结果不明：先查支付状态，不要提示用户重复付款。

第四步：支付成功后重新请求（⚠️ 最容易遗漏的一步）

必须重新请求第二步的同一个地址，body 与第一次完全一致，只在 Header 里加上第二步保存的两个值：

POST https://skills.bendijia.com/payexpert-x402/api/call/skillhub-pay-expert
Content-Type: application/json
WeixinPay-Required: {第二步保存的值}
X-Out-Trade-No: {第二步保存的订单号}

{与第一次完全一致的 body}

不带 X-Out-Trade-No 重试就永远拿不到结果。不要用支付返回的字段自己拼结果，也不要在没有重试的情况下告诉用户「已支付，稍后出结果」。更不要重新发起一次首次请求——那会变成第二笔订单、第二次扣费。

用脚本执行就是：

node scripts/pay_gateway.mjs complete

脚本会自动带上两个 Header，并用 request_body.json 原样回放第一次的 body 字节（--data-binary @request_body.json），不依赖你手工复制 body。

成功时返回 HTTP 200 + 交付物（11 个文件，files 数组）。拿到 200 之后才可以开始生成工程。

未取得解锁响应前，不得输出任何代码、配置或部署命令。 可以先解释「这个工具能做什么、怎么收费」，但不能给出 gateway.py 的任何片段——那是付费交付物。

支付组件缺失时怎么处理

脚本会以明确错误码退出，不同错误码的处置不同：

支付红线

• 全程不向用户展示支付码原文、支付链接原文、二维码链接原文、交易号、订单号。
• 不向用户展示 WeixinPay-Required 的值。
• Agent 不代付、不垫付，只编排流程。
• 支付结果不明时不得要求用户重复付款，先查单。
• 不在日志、回复中记录支付凭证。
• probe 返回 200 表示已解锁（有效期内可复用），此时不需要再走支付流程。

一、先做配置体检（这里最容易卡死，且不报错）

先说结论：代码不是门槛，代码可以让 AI 写；支付宝后台的配置才是门槛。因为配置错了不会报错——页面显示「配置成功」，服务跑起来 /health 也正常，就是收不到钱。你会回头怀疑签名逻辑，改半天代码，而错的地方根本不在这。

带用户过这张表，定位他卡在哪一层：

任何一项答「不确定」，先解决它，再碰代码。 顺序反了至少浪费一天。每一项的具体操作步骤见 references/onboarding.md，报错怎么修见付费后的 SETUP-ERRORS.md。

二、再判断：这个 Skill 该不该收费

过了配置体检，再判断值不值得做。任何一道答「否」就劝退——不为了成交硬推，这是信誉底线：

定价区间参考（SkillPay 只支持按次，0.01–50 元/次）：

不要用低价刷量：平台账单价必须等于服务市场注册价，改价要重新签约审核，反复调价会打断你的转化数据。

三、收集参数（6 项，缺一不可）

一次性问完，不要逐条挤牙膏。用下面这段原样问：

要生成付费闸工程，需要你确认 6 项参数：

1. 技能展示名（中文，你的用户在 SkillHub 看到的名字）
2. slug（英文小写 + 连字符，必须与你在 SkillHub 后台填的 Slug 完全一致）
3. 定价（元/次，0.01–50，必须等于你在支付宝服务市场注册的价格）
4. 商品名（账单上显示，建议「<技能名>-单次」，不超过 32 字）
5. 网关端口（默认 8022，若已被占用请换一个）
6. 公网路径（你自己的域名，如 https://你的域名/alipay，末尾不带斜杠）

另外确认：支付宝 A2M 的 app_id 和 service_id 是否已拿到？
（若还没有，先走 references/onboarding.md 完成入驻，拿到再回来）

参数校验规则（收到后自行校验，不合规当场退回，不要带病生成）

参数存盘

校验通过后立即落盘——probe 会读它，并与订单绑定（中途改参数会导致渲染错位）：

node scripts/scaffold.mjs plan 
  --slug my-skill --name "我的技能" --price 4.90 
  --goods "我的技能-单次" --port 8022 --base https://你的域名/alipay

不带参数运行 plan 会打印当前已存参数与校验结果，用于复核。

四、生成脚手架

用户付款后：

node scripts/scaffold.mjs write ./paygate-<slug>

脚本会读取解锁响应、校验文件完整性、写出整套工程，并在最后打印一份落地清单（文件数、总字节、下一步命令）。

生成内容包含：

其中 SETUP-ERRORS.md 是本工具真正的核心交付——它能解决的事，网上检索不到，官方文档也不会写：官方只说「应该怎么配」，不说「配错了长什么样」。

密钥一律不生成、不代填、不代转格式。 .env 里只出现 ALIPAY_PRIVATE_KEY= 这样的空赋值，让用户自己粘贴。这不是偷懒：私钥经第三方转手即等于泄露，且支付宝密钥工具生成的格式（PKCS#1 裸 Base64 / PKCS#8）各有适配差异，代转必错。

五、落地后必做的三件事

按顺序，不可跳：

1. 跑自检：python server/selfcheck_402.py——13 项全过才算协议对了。它验的是账单能被你的公钥验通，能提前抓出「用了支付宝公钥当应用公钥」这类致命错。
2. 跑 env 对账：python server/env_audit.py——它会列出「配了但代码不读」的变量。这类静默失效在付费链路上等于收不到钱还查不出原因。
3. 沙箱试一笔：把 .env 指向沙箱（ALIPAY_GATEWAY 用沙箱地址、ALIPAY_SERVICE_ID=api_mock_service_id），完整走一遍首次请求→支付→重试取件。沙箱账单价固定 0.01，写别的会被 SERVICE_PRICE_MISMATCH 拒掉，这是沙箱与生产唯一的价差陷阱。

六、部署

DEPLOY.md 里有完整命令，关键三点：

• Python 用 3.10+（alipay-sdk-python 与 pycryptodome 都要），系统 Python 太老就别硬扛，用独立 venv；
• systemd 单元里的 WorkingDirectory 必须指向 server/，否则 SQLite 订单库会建到根目录；
• nginx location ^~ /alipay/ 的 proxy_pass 必须带尾斜杠，否则前缀不会被剥掉，网关收到 /alipay/api/call/xxx 与注册的 /api/call/xxx 不匹配，直接 404。

证书是独立问题：如果你的域名裸域有 301 跳转，ACME 的 http-01 验证会被打断，证书续期会静默失败。开证书前先 curl -I https://你的域名 确认当前证书到期日，别等过期当天才发现。

七、回填你自己的 SKILL.md

生成的工程不包含你技能的 SKILL.md——你的业务逻辑只有你有。把你自己的付费说明整段抄进你的 SKILL.md，然后改三处：技能名、单价、RESOURCE_ID。

必须保留：前置检查、退出码表、支付红线三段。这三段是审核最容易挑毛病的地方，也是你的用户投诉时你的免责依据。

审核前自查：

• 包顶层只有一层目录，且目录名 = slug；
• 包内不得含任何真实密钥、真实手机号、真实订单号；
• 简介里的价格与后台填的价格、支付宝注册价三者一致；
• 不出现「保证收益」「稳定月入」这类承诺（广告法风险）；
• references/ 里的示例数据必须自洽——声明的错因要能推导出那个错误结果，不自洽是审核员最爱抓的破绽。

八、边界

• 本工具提供工程脚手架与踩坑指引，不代办支付宝入驻、不代提交审核、不承诺审核通过；
• 支付宝入驻涉及实名、经营类目与签约，须由你本人完成，AI 不代替你签署任何协议；
• 不提供规避平台规则、刷单、自买自卖等做法的任何指导；
• 定价、类目、发票与退款规则以支付宝与 SkillHub 官方口径为准，本工具的建议仅供参考；
• 本工具只对接支付宝的按次付费（A2M/402）：不做微信支付商户号接入、海外支付渠道（Stripe 等），也不生成单纯的收款码。

九、隐私

• 你输入的 6 项参数（slug、名称、价格、端口、路径）会发到本工具的网关用于渲染，不含任何密钥、服务器密码或用户数据；
• 生成的工程完全在你的本机，工具不上传、不留存你的代码；
• 网关侧只记录订单事实（单号、金额、时间、履约状态），不记录参数明细内容。

十、退款与凭证

• 支付由微信支付按官方规则处理，可在微信支付账单中发起咨询或退款；
• 支付成功但生成失败：先重跑 complete；仍失败则记录交易号告知用户稍后重试，不要求重复付款；
• 因参数不合规退回修改的，同一次支付内可反复生成，不额外收费。

附：本工具收款链路（微信支付 X402）的排查资料

排查「为什么付了钱还是 402」时对照：

• references/x402-contract.md —— X402 接口契约：端点、402 响应、200 响应、错误码表、幂等与重试语义。
• references/x402-pitfalls.md —— X402 链路的 12 个高频坑（症状与根因）。
• references/pitfall-headlines.md —— 12 条 A2M 坑的症状速查 + 本工具收款通道的高频坑。
• references/pricing.md —— 定价规则与四处价格一致性。