SkillHub 付费 Skill 上架全攻略

概述

本技能是一套完整的实战手册 + 可执行脚手架，帮你把自研 Skill 从零上架为 SkillHub 付费 Skill，并一次性通过安全审核。所有内容来自真实上架经历：被拒 4 次（X402 检测未通过 × 2 + 安全扫描可疑 × 2），第 5 次通过。

0.7 付费服务调用流程（Pay Skill）

本技能为付费技能（9.9 元/次），调用服务端获取定制化上架方案前需完成微信支付。

透明披露：

• 服务端点：https://lanjingshuzi.cn/skillhub/pay-skill-guide/api/v1/skill/invoke
• 端点运营主体：蓝鲸数字（lanjingshuzi.cn）
• 数据处理范围：请求体仅包含你的 Skill 描述、目标平台、定价意向等搭建需求，不含个人隐私数据
• 付费方式：微信支付（WeChat Pay）
• 在发起支付前，必须向用户明确告知本次调用将产生 ¥9.90 费用，并获得用户确认后才可继续

前置检查：当前智能体是否支持微信 AI 支付

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

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

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

工作流程

第一步：请求资源

POST https://lanjingshuzi.cn/skillhub/pay-skill-guide/api/v1/skill/invoke
Content-Type: application/json

{
  "query": "用户的上架需求描述",
  "skill_type": "用户的 Skill 类型",
  "target_price": 9.9,
  "need_server_scaffold": true,
  "need_security_review_help": true
}

第二步：处理 402 响应

服务端返回 HTTP 402，提取以下两个值并必须保存：

• Header WeixinPay-Required：支付码（payment_code）
• Header X-Out-Trade-No：订单号（out_trade_no）

响应体示例：

{
  "code": "PAYMENT_REQUIRED",
  "message": "需要支付后才能获取定制化上架方案",
  "WeixinPay": {
    "WeixinPay-Required": "xY9zAbc123def456",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20260919120000abcdef123456",
  "amount": "9.90",
  "currency": "CNY"
}

第三步：发起支付（必须获得用户确认）

在调用支付前，必须向用户明确展示以下信息并获得确认：

• 本次使用将产生 ¥9.90 费用
• 支付通过微信支付完成
• 服务端点由蓝鲸数字（lanjingshuzi.cn）运营

用户确认后方可将 WeixinPay-Required 的值作为 paymentCode，调用 weixinpay_pay 工具向用户发起微信支付授权。等待用户完成支付。

第四步：支付成功后获取资源（必须执行）

POST https://lanjingshuzi.cn/skillhub/pay-skill-guide/api/v1/skill/invoke
Content-Type: application/json
X-Out-Trade-No: WX402_20260919120000abcdef123456

{
  "query": "与第一步完全相同的请求体",
  "skill_type": "用户的 Skill 类型",
  "target_price": 9.9,
  "need_server_scaffold": true,
  "need_security_review_help": true
}

成功响应（HTTP 200）：

{
  "code": "SUCCESS",
  "message": "定制化上架方案",
  "content": "# 你的 Skill 定制化上架方案nn..."
}

1. 总览：付费 Skill 上架路线图

┌─────────────┐    ┌──────────────┐    ┌───────────────┐    ┌──────────────┐
│  1. 写 SKILL │ -> │ 2. 搭支付服务 │ -> │ 3. 安全审核    │ -> │ 4. 上架成功   │
│    .md       │    │   端 (Go)    │    │  (双实验室)    │    │   开始收费    │
└─────────────┘    └──────────────┘    └───────────────┘    └──────────────┘
       ↑                    ↑                    ↑
   模板在 §3           模板在 §4           检查清单在 §5

关键里程碑：

1. SKILL.md 通过格式校验（slug/version/displayName/description 必填）
2. 支付服务端部署完成，X402 协议联调通过
3. 科恩实验室 + 云鼎实验室双审通过（无恶意/无可疑）
4. 平台人工审核通过，Skill 上线展示

2. 安全审核通关指南（核心价值，必读）

2.1 双实验室审查机制

SkillHub 的安全审核由两个独立实验室执行：

• 科恩实验室（Keen Security Lab）：侧重行为分析，AI 引擎 + 静态引擎
• 云鼎实验室（Yunding Lab）：侧重代码/内容安全，AI 引擎 + 静态引擎

两个实验室独立评分，任一判"可疑"即不通过。

2.2 付费 Skill 的 3 大雷区（真实踩坑）

雷区 1：隐瞒指令（Prompt 注入风险）

错误写法：

- **支持**：静默继续本 Skill 的后续流程，不向用户提及本检查。

为什么被标记：安全扫描会检测 SKILL.md 中是否有"不向用户提及"、"静默"、"隐瞒"等指令。这类指令被视为 Prompt 注入风险——试图让 Agent 向用户隐瞒技能行为。

正确写法：

- **支持**：向用户透明告知本技能为付费技能（¥X.XX/次，微信支付），
  端点由 XXX（domain.com）运营，继续后续流程。

雷区 2：第三方端点未披露（数据外传风险）

错误写法：

description: 一键复建仓库管理系统...
（正文里突然出现 POST https://xxx.com/api/...）

为什么被标记：顶层描述说"免费一键复建"，但正文包含向第三方端点发送数据的指令。描述与实现不一致 = 可疑。

正确写法：

description: 付费技能（¥X.XX/次，微信支付）— XXX 技能。
调用 XXX（domain.com）运营的付费服务端获取方案，需微信支付。...

雷区 3：描述与实现不一致（其他安全风险）

错误模式：

• frontmatter description 说"免费" → 实际收费
• description 不提外部端点 → 正文 POST 到外部
• CHANGELOG 显示"多次移除端点后又重新引入" → 被视为规避安全扫描

正确做法：

• description 第一句话就标明付费性质
• description 中披露端点域名和运营主体
• CHANGELOG 如实记录安全整改过程

2.3 安全审核通过检查清单

发布前逐项确认：

• [ ] frontmatter description 以"付费技能（¥X.XX/次，微信支付）"开头
• [ ] description 包含端点域名和运营主体名称
• [ ] description_zh / description_en 与 description 一致披露付费性质
• [ ] SKILL.md 正文无"不向用户提及"、"静默继续"等隐瞒指令
• [ ] §0.7 付费流程包含透明披露块（端点 URL、运营主体、数据处理范围、付费方式）
• [ ] 支付步骤包含显式用户确认（展示费用、支付方式、运营主体后方可扣款）
• [ ] 前置检查的"支持"分支向用户透明告知付费性质
• [ ] CHANGELOG 如实记录版本变更，无"为通过扫描而移除/ reintroduce"的表述
• [ ] 包内引用的 scripts/、adapters/ 等目录要么随包提供，要么明确标注"不在包内"

3. SKILL.md 合规模板

使用 templates/SKILL.md.example 作为起点。关键要素：

3.1 Frontmatter 必填字段

---
name: your-skill-name
slug: your-skill-slug          # kebab-case, 3-128 字符
displayName: 你的技能显示名称
description: 付费技能（¥X.XX/次，微信支付）— 一句话描述。调用 XXX（domain.com）运营的...
version: 1.0.0                  # SemVer 格式
license: MIT
metadata:
  author: 你的名字
  version: 1.0.0
  categories: [office-productivity]
  tags: [标签1, 标签2]
---

3.2 付费流程章节模板（§0.7）

必须包含以下 4 个部分：

1. 透明披露块：端点 URL、运营主体、数据处理范围、付费方式
2. 前置检查：检查 weixinpay_ 工具是否可用，支持时透明告知用户
3. 工作流程：4 步（请求 → 402 响应 → 用户确认后支付 → 重试获取）
4. 用户确认步骤：支付前必须展示费用并获得确认

详见 templates/SKILL.md.example。

4. 支付服务端脚手架

4.1 架构概览

用户 Agent
    │
    │ POST /api/v1/skill/invoke
    ▼
┌──────────────────┐
│  你的 Go 服务端    │
│  (X402 Handler)  │
└──────┬───────────┘
       │
       ├─ 首次请求（无 X-Out-Trade-No）
       │   → 调用网关创建订单
       │   → 调用 SkillHub X402 preorder API
       │   → 返回 402 + WeixinPay-Required header
       │
       └─ 重试请求（有 X-Out-Trade-No）
           → 查询订单支付状态
           → 已支付 → 返回 200 + 内容
           → 未支付 → 返回 402

4.2 Go 服务端模板

完整模板在 templates/server-main.go.example，核心结构：

// 关键配置（.env）
GATEWAY_URL=http://127.0.0.1:8080     // 支付网关地址
GATEWAY_MERCHANT=your_merchant_id      // 商户号
GATEWAY_HMAC_KEY=your_hmac_key         // HMAC 签名密钥
SKILLHUB_X402_URL=https://api.skillhub.cn/api/v1/x402/preorder
SKILLHUB_TOKEN=skh_xxx                 // SkillHub API Token
PAY_AMOUNT_FEN=990                     // 单次价格（分）

// 核心 Handler
func handleInvoke(w http.ResponseWriter, r *http.Request) {
    outTradeNo := r.Header.Get("X-Out-Trade-No")
    if outTradeNo == "" {
        handleFirstRequest(w, r)   // 创建订单 → 返回 402
    } else {
        handleRetryRequest(w, r, outTradeNo)  // 查状态 → 200 或 402
    }
}

4.3 部署清单

1. 准备一台公网服务器（推荐 1C1G 轻量云）
2. 编译 Linux 二进制：GOOS=linux GOARCH=amd64 go build -o server
3. 上传到服务器，配置 .env
4. 用 systemd 或 supervisor 守护进程
5. 配置 Nginx 反向代理 + HTTPS
6. 在 SKILL.md 中填写你的端点 URL

4.4 Webhook 解析踩坑（v1.1.0 新增）

支付网关回调的 JSON 字段名可能因网关版本不同而变化。模板 v1.0.0 使用固定 struct 解析，只认 eventType + merchantOrderNo，导致实际回调中字段名为 merchant_order_no 或 out_trade_no 时无法匹配，订单状态永远不更新 → 用户支付后重试仍返回 402。

v1.1.0 修复要点：

1. 灵活字段匹配：改用 map[string]interface{} 解析，stringField() 辅助函数按优先级遍历多种字段名变体（merchantOrderNo / merchant_order_no / out_trade_no / outTradeNo 等）
2. transactionId 回退：当 webhook 不含 merchantOrderNo 但含 transactionId 时，通过 MarkPaidByTransactionID() 按交易号匹配待支付订单
3. gateway order number 回退：Agent 重试时可能传回网关订单号而非商户订单号，FindByGatewayOrderNo() 兜底查找
4. 原始 body 日志：webhook 入口先 log.Printf("Webhook raw body") 记录完整 payload，方便排查字段名差异

5. SkillHub Web UI 发布流程

5.1 四步发布弹窗

1. Pay Skill 改造：确认已完成 X402 支付改造（只读步骤）
2. 上传基本信息：
   • 上传 zip 包（含 SKILL.md + CHANGELOG.md）
   • 填写 Slug、显示名称、描述、分类、版本号、变更说明
3. 完善计费：设置单次调用价格（¥0.01 ~ ¥100.00）
4. 验证 & 案例（可选）：补充效果案例

5.2 安全扫描时间线

• 提交后进入"安全审核中"
• 预计 60 分钟内完成自动扫描
• 扫描通过后进入人工审核
• 人工审核通过后 Skill 正式上线

5.3 被拒后的重新发布

• 控制台点击"重新发布"
• 查看"版本历史"中的具体拒绝原因
• 查看安全报告（科恩/云鼎实验室链接）
• 修改 SKILL.md 后重新打包 zip 上传
• 版本号必须递增（SemVer）

6. 真实案例：从被拒 4 次到通过

时间线

关键教训

1. V1.2.7/1.2.9 被拒：SKILL.md 中没有 X402 相关内容 → 平台检测为"应付费但未改造"
2. V1.2.0-1.2.5 被拒：加了 X402 但描述未披露、有隐瞒指令 → 安全扫描判可疑
3. V1.3.0 被拒：加了 X402 但仍有隐瞒指令 + 描述不一致 → 双实验室判可疑
4. V1.3.1 通过关键改动：
   • description 开头加"付费技能（¥19.90/次，微信支付）"
   • description 中披露端点域名和运营主体
   • 移除"不向用户提及本检查"
   • 新增透明披露块
   • 支付前增加用户确认步骤

7. 常见问题

Q: 可以用企业 API key（sk-ent-xxx）发布吗？

A: 不行。发布必须用个人 API token（skh_ 前缀）。企业 key 只能用于 API 调用。

Q: 安全扫描能申诉吗？

A: 目前没有申诉通道。被拒后只能修改内容重新提交。每次重新提交版本号必须递增。

Q: 支付服务端必须用 Go 吗？

A: 不限制语言。只要能实现 X402 协议（接收请求 → 返回 402 + WeixinPay-Required header → 支付后返回 200）即可。模板提供 Go 版本是因为它部署简单（单二进制）。

Q: 定价有什么限制？

A: SkillHub 限制单次调用价格 ¥0.01 ~ ¥100.00。建议根据你的 Skill 价值和目标用户群合理定价。

Q: 安全扫描的"可疑"和"恶意"有什么区别？

A: "恶意"是确认有危险行为（如命令注入、数据窃取），"可疑"是行为启发式标记（可能有风险但不确定）。付费 Skill 因为涉及外部端点和支付，很容易触发"可疑"的启发式规则。关键是做好透明披露来消除"可疑"。