SkillHub付费技能收款专家·企业版

概述

你已经有微信支付商户号，技能也想按次收钱，但收款工程本身没人写：下单、扫码、查单、解锁、回调、幂等，每一环出错的表现都是「用户付了钱却拿不到东西」。这个技能把整套网关做完：你说清 6 个参数，拿到的是一套填好参数、能直接跑的微信支付网关工程，离线自检全部通过后再上线。

和个人版的区别：个人版走支付宝 A2M（不需要营业执照，但不能接微信支付）；企业版走你自己的微信支付商户号，价格自己定、钱直接进你的商户号，不依赖第三方计费通道。

付费说明

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

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

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

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

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

发起下单前，先检查你的可用工具列表中是否存在名称包含 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付费技能收款专家·企业版」单次生成需支付 ¥99.00",
  "WeixinPay": {
    "WeixinPay-Required": "xxxxx",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20261028093012a9f3c7e21b4",
  "amount": "99.00",
  "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-ent-x402/api/call/skillhub-pay-expert-enterprise
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 + 交付物（12 个文件，files 数组）。拿到 200 之后才可以开始生成工程。

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

支付组件缺失时怎么处理

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

支付红线

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

一、先做配置体检（微信支付这一侧最容易卡死，且不报错）

先说结论：代码可以让 AI 写，微信支付商户侧的配置才是门槛。因为配错了大多不会报「配置错误」，只会报一些与真实原因无关的错——签名失败、appid 与商户号不匹配、回调收不到。你会回头怀疑代码，而错的地方根本不在代码。

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

任何一项答「不确定」，先解决它，再碰代码。 顺序反了至少浪费一天。每一项的具体操作与报错对照见 references/wechat-merchant-checklist.md。

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

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

自建网关没有平台的单次价格上限，定价只受你的用户接受度约束。起步建议：

改价只改一处：网关的 .env 里 PRICE_FEN（单位分）是唯一计费来源。请求体里的价格只是渲染变量，改它不影响扣款金额——这条是防止「前端改价」类漏洞的硬约束。

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

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

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

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

另外确认：微信支付商户号与 appid 是否已拿到、已绑定？
（若还没有，先走 references/wechat-merchant-checklist.md 完成开通，拿到再回来）

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

参数存盘

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

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

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

四、生成脚手架

用户付款后：

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

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

生成内容包含：

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

密钥一律不生成、不代填、不代转格式。 .env 里只出现 WX_PRIVATE_KEY_PATH= 这样的空赋值，让用户自己填路径或粘贴。这不是偷懒：私钥经第三方转手即等于泄露；另外 systemd 的 EnvironmentFile 会吞掉 PEM 里的换行，推荐用文件路径而不是内联。

五、落地后必做的三件事

按顺序，不可跳：

1. 跑自检：python server/selfcheck_402.py——全部通过才算协议对了。它不联网、不产生真实订单，但会把签名串、回调解密、402→付款→解锁状态机、金额篡改、超时补付逐项演一遍，能提前抓出「签名串少一行」「APIv3 密钥填成证书」这类致命错。
2. 跑 env 对账：python server/env_audit.py——它会列出「配了但代码不读」的变量。这类静默失效在付费链路上等于收不到钱还查不出原因。
3. 真付一分钱：把 .env 的 PRICE_FEN 临时改成 1，用正式域名完整走一遍首次请求→扫码→重试取件，确认拿到 200 与交付内容，再改回正式价重启。这一步不可跳过——离线自检证明不了你的证书、appid、回调地址在微信侧是对的。

六、部署

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

• Python 用 3.10+（cryptography 与 qrcode 都要），系统 Python 太老就别硬扛，用独立 venv；
• systemd 单元里的 WorkingDirectory 必须指向 server/，否则 SQLite 订单库会建到别处，重装后订单状态全丢；
• uvicorn 必须 --workers 1：订单库是 SQLite，多进程会在并发查单时写冲突；
• nginx location ^~ /pay/ 的 proxy_pass 必须带尾斜杠，否则前缀不会被剥掉，网关收到 /pay/api/call/xxx 与登记的资源路径不匹配，直接 404。

证书是独立问题：如果域名裸域有 301 跳转，ACME 的 http-01 验证会被打断，证书续期会静默失败；微信回调也要求证书链完整。上线前先 curl -I https://你的域名 确认当前证书到期日。

七、回填你自己的 SKILL.md

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

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

审核前自查：

• 包顶层只有一层目录，且目录名 = slug；
• 包内不得含任何真实密钥、真实手机号、真实订单号、真实商户号；
• 简介里的价格与实际 PRICE_FEN、你的收款页展示一致；
• 不出现「保证收益」「稳定月入」这类承诺（广告法风险）；
• references/ 里的示例数据必须自洽——声明的错因要能推导出那个错误结果。

八、边界

• 本工具交付工程脚手架、部署清单与自检脚本，不做远程代部署：不登录你的服务器、不代你操作 systemd/nginx、不接管线上环境；
• 微信支付商户号的申请、主体认证、证书与密钥管理须由你本人完成，AI 不代替你签署任何协议；
• 不代办营业执照等资质，不承诺审核通过、不承诺支付额度；
• 不提供规避平台规则、刷单、自买自卖等做法的任何指导；
• 定价、类目、发票与退款规则以微信支付与 SkillHub 官方口径为准，本工具的建议仅供参考；
• 本工具只对接微信支付 Native（扫码）按次收费：不做支付宝/海外支付渠道（Stripe 等），也不生成单纯的收款码图片。

九、隐私

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

十、退款与凭证

• 本次生成费用由微信支付按官方规则处理，可在微信支付账单中发起咨询或退款；
• 支付成功但生成失败：先重跑 complete；仍失败则记录交易号告知用户稍后重试，不要求重复付款；
• 因参数不合规退回修改的，同一次支付内可反复生成，不额外收费；
• 注意区分两笔钱：这笔是本工具的服务费；你的用户付给你的钱进你自己的商户号，退款也在你自己的商户后台操作。

附：排查资料

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

• references/x402-contract.md —— 本工具收款通道的 X402 接口契约：端点、402 响应、200 响应、错误码表、幂等与重试语义。
• references/x402-pitfalls.md —— 本工具收款链路的 12 个高频坑（症状与根因）。
• references/wechat-merchant-checklist.md —— 微信商户侧开通与配置清单：每一步配错会报什么、真实原因、怎么改。
• references/gateway-pitfalls.md —— 交付网关上线后的高频故障：签名、回调、重复扣费、晚到支付、代理前缀。
• references/pricing.md —— 自建网关的定价规则与四处价格一致性。