如何发布 Skill Pay(X402 改造完整指南)
这是什么
把已有付费服务封装为 SkillHub 上可被 AI Agent 调用、按次计费的 Pay Skill。涵盖微信支付商户号接入、SkillHub 开发者密钥、后端服务改造、5 行签名串精确实现、HTTP 402 响应处理、payment_code 有效期管理、test_refund 测试退款等完整链路。
这是 3 周踩坑沉淀的实战经验,帮你避开"未进行 X402 协议改造"、"file type not allowed"、"签名失败"等 8 大常见报错。
适用场景
- 想把已有付费 API/服务封装为 Pay Skill 的开发者
- 想让 AI Agent 通过微信支付调用你的服务
- 想做 Skill 商业化(知识付费 / API 代理 / 报告生成)
- 想理解 X402 协议底层机制
- 想做 WeixinPay / SkillHub 集成的商户
业务输出
调用本 skill 后,你将获得:
- X402 协议全貌:4 段架构、5 行签名串、L1/L2 两层结构
- 微信支付商户接入:Native 下单、查单、退款、回调
- SkillHub 开发者密钥:生成、签名、验签
- 后端服务模板:基于 mch-demo 的 Go/Java 双语言示例
- SKILL.md 改造模板:pay_skill / x402_compliant 字段、4 步工作流
- 8 大报错速查:从 file type not allowed 到签名失败
改造 5 步(从 0 到 1)
Step 1:申请商户号
- 微信支付商户平台(pay.weixin.qq.com)申请
- 准备营业执照、对公账户、法人身份证
- 开通 Native 支付(扫码支付)
Step 2:生成 SkillHub 开发者密钥
- SkillHub 商户中心 -> 开发者密钥
- 生成后保存:
SKILLHUB_DEVELOPER_ID+SKILLHUB_PUB_KEY_ID+ 私钥
Step 3:改造后端服务
- 基于 mch-demo(Go/Java 双语言)起步
- 改 2 处:
amount金额 +executeBusiness业务函数 - 其他(SDK 集成、签名、AI 预下单)100% 复用 demo
Step 4:改造 SKILL.md
- frontmatter 加
pay_skill: true+x402_compliant: true - 写 4 步工作流:请求资源 -> 处理 402 -> 触发支付 -> 重试获取内容
- value_intro 放最前(平台抓取 description)
Step 5:部署 + 上传
- HTTPS + systemd 部署后端(微信支付强制 HTTPS)
- 微信支付商户平台填回调地址
- SkillHub 平台上传 zip + 升级为 Pay Skill
- 等待审核(1-3 工作日)
关键避坑(8 大常见报错)
| 报错 | 原因 | 解决 |
|---|---|---|
未进行 X402 协议改造 |
勾了"升级为 Pay Skill"但没真改造 | 取消勾选 OR 完成改造 |
file type not allowed: xxx.service |
zip 含 .service/.sh/.env 等 | 只放 SKILL.md + icon.png + references/ |
签名失败 |
5 行签名串的换行错了 | 每行结尾 \n(含最后一行) |
payment_code 已过期 |
超过 15 分钟 | 重新下单 + AI 预下单 |
微信支付回调 401 |
证书验证失败 | 重新下载平台证书 |
退款失败 |
APIv3 密钥错 | 检查 MCH_APIV3_KEY |
L1 验证失败 |
pub_key_id 不匹配 | 检查私钥和 pub_key_id 配对 |
测试退款不触发 |
query 不是 "trigger_refund" | 严格用这个字符串 |
推荐实施路径
- 1-2 天:申请商户号 + 生成 SkillHub 密钥
- 3-5 天:改造后端服务(基于 mch-demo)+ 本地测试
- 1 天:部署到 HTTPS 服务器 + 配置回调
- 1-3 天:SkillHub 审核
- 总计 1-2 周:从 0 到上线
不适合做 Pay Skill 的场景
- 纯 LLM 工作流(没有真实后端)
- 命令合集类(如 git 命令)
- 配置类(如 Hermes profile)
- 免费知识分享
这些场景应该走普通 skill(免费发布)而不是 Pay Skill。
详细文档(见 references/)
x402-protocol.md:X402 协议详细说明wechat-pay-integration.md:微信支付接入步骤backend-template.md:后端服务模板(Go/Java/Python)skill-md-template.md:SKILL.md 改造模板troubleshooting.md:8 大报错 + 调试技巧deployment.md:部署到 HTTPS 服务器
