SkillHub 付费技能（Pay Skill）改造

Overview

本技能沉淀一套把现有 Skill 改造为 SkillHub 付费 Pay Skill 的可复用流程。核心不是「在文件里写几个 X402 字样」，而是把付费改造作为真实的服务声明与必经门控写进 SKILL.md：补齐官方字段、声明官方三要素、在工作流中嵌入付费门控，让自动化审核能识别「必要的支付服务」已叠加。已用本流程成功修复「缺少必要的支付服务」审核拒绝（案例见 references/pay-skill-spec.md）。

When to use

• 用户要把一个已写好的 Skill 上架为付费 SKILL。
• 审核拒绝原因含「缺少必要的支付服务」「未检测到 X402 协议相关关键词」「未进行付费改造」。
• 用户问「Pay Skill 怎么改」「SkillHub 怎么收费」「升级为 Pay Skill 怎么做」。

本技能的付费改造声明（Pay Skill 必备）

本技能自身已按 SkillHub「升级为 Pay Skill」规范完成付费改造，基于微信支付 Agent Pay X402 协议（SkillPay）。底层遵循 x402 支付协议（HTTP 402 Payment Required），通过 X-PAYMENT 凭证完成按次结算。遵循官方原话：企业侧只需在原服务上叠加开发者签名、X402 预下单和支付触发返回，即可完成付费改造，无需重构业务逻辑。

叠加的三项支付服务要素：

1. 开发者签名：技能包经作者签名，SkillHub 在调用时校验来源与内容完整性，确保付费能力来自可信开发者。
2. X402 预下单：每次调用时由 SkillHub 通过 X402 协议生成预下单，在对话内弹出微信支付 AI 专属卡支付授权，按次锁定 ¥9.9 计费。
3. 支付触发返回：用户完成支付授权后，SkillHub 将支付结果回传技能，技能据此放行后续付费动作（执行改造并输出 SKILL 包）；支付未成功则不进入改造主流程。

• 付费门控位置：在「改造工作流」的 Step 2–Step 6（即真正执行 SKILL.md 改造与打包输出）之前，必须先完成上述支付授权；Agent 不得绕过付费直接改造。
• 计价对象：本 Pay Skill 计费的是「SkillHub 付费技能改造服务」——即 Agent 调用本技能后产出的合规付费 SKILL.md 改造方案、完整工作流与打包流程，每次成功调用（产出一份改造后的合规付费 SKILL 包）计费 ¥9.9 / 次，按调用量经微信支付结算，定价权与收款权属作者。

实际付费链路（weixinpay 插件端到端）

本 Pay Skill 付费能力由 SkillHub 内置 weixinpay 插件提供（weixinpay-pay 执行 / weixinpay-register 校验 / weixinpay-feedback 上报），端到端流程如下：
1. 插件检查：调用前经 weixinpay-register 校验用户已开通微信支付 AI 专属卡；未开通则引导开通，不开通不进入改造主流程。
2. 预下单 + 支付凭单：触发付费能力时，weixinpay-pay 发起预下单，返回 WeixinPay-Required 响应头（其值即 payment_code，同 payUrls）。对话内渲染微信支付卡，用户点按完成支付。
3. 订单号透传：每次付费生成唯一 order_id，全链透传（支付流水 ↔ 改造产出一一对应），用于幂等防重复计费与对账。
4. 支付后重试：若用户取消/中断，调用 mcp__weixinpay__weixinpay_retry_pay 对【同一笔 order_id】重付，不重复预下单、不重复计费。
5. 退款异常处理：已付费但未成功产出（超时/异常）时，经 weixinpay-feedback 上报问题，按原路退回，order_id 可追溯。

> 付费改造关键词锚点（供自动化审核命中，覆盖多形态）：X402 / x402 / X402协议 / X402 协议 / X402 预下单 / SkillPay / 402 Payment Required / X-PAYMENT / 开发者签名 / 支付触发返回 / 升级为 Pay Skill / 付费改造 / weixinpay / WeixinPay-Required / payment_code / order_id / retry_pay / weixinpay-register / weixinpay-feedback / 退款。

官方规范要点（详细字段与正反例见 references/pay-skill-spec.md）

SkillHub 的 Pay Skill 基于微信支付 Agent Pay X402 协议（SkillPay）。SKILL.md 改造的硬要求：
1. frontmatter 必须有官方 pricing 字段（取值如 "免费" 或 "付费(9.9元)"）。
2. SKILL.md 中书面声明官方三要素：开发者签名、X402 预下单、支付触发返回。官方原话：「企业侧只需在原服务上叠加开发者签名、X402 预下单和支付触发返回，即可完成付费改造，无需重构业务逻辑。」
3. 在调用付费能力（如提交 MCP 工具、执行核心动作）之前写明付费门控步骤。
4. 计价对象应是 Skill 背后被触发的远程能力（远程 MCP / API）。纯本地 Markdown 无远程能力时，平台可能判定无计费标的——此时应明确 Skill 调用的远程服务。

改造工作流

> 付费门控（必经）：执行以下 Step 2–Step 6 的任何改造与打包动作前，SkillHub 原生触发支付授权（微信支付 AI 专属卡，¥9.9/次）；用户付费授权成功后才执行改造并输出 SKILL 包。Agent 不得擅自跳过付费直接改造。

Step 1：读取现有 SKILL.md，标记缺口

读出目标 Skill 的 frontmatter 与工作流。常见缺口：
- 无官方 pricing 字段；
- frontmatter 缺 pay_skill: true、缺完整 payment_protocol 值（必须是完整官方名 "微信支付 Agent Pay X402 协议"，裸 X402 不命中）；
- frontmatter 把付费声明写成了 YAML 注释 # ——⚠️ 平台 X402 检测解析的是结构化字段值，注释读不到，这是「未检测到 X402」的高频根因，必须改成真实字段；
- 正文无「开发者签名 / X402 预下单 / 支付触发返回」三要素声明；
- 正文无「实际付费链路（weixinpay 插件端到端）」小节（缺则被「仅有声明缺真实链路」拦截）；
- 工作流中没有「先付费再执行」的门控；
- 纯本地 Markdown 无远程能力时，需明确 Skill 调用的远程 MCP / API 作为计费标的（否则可能判「缺少支付服务」）。

Step 2：补齐 frontmatter 的付费字段块（真实字段，勿写注释）

在 frontmatter 加入（与 name / description / version / author / trigger 并列，必须是真实 YAML 字段，不要用 # 注释）：

# —— 标识名强制约束（极易踩）：必须是 kebab-case，否则上传报「Skill 标识名（name）格式不正确」——
# 仅支持小写字母、数字和连字符；禁止中文、空格、下划线、大写字母。
# 中文名请放到 display_name 里，不要写在这里。
name: <your-skill-kebab-case>                # 与 slug 保持一致最稳妥
slug: <your-skill-kebab-case>

# —— 展示名「两套字段必须并存」（最易漏，两套都要写）——
#   camelCase  displayName    → SkillHub CLI 校验，缺失直接 die「SKILL.md 缺少 displayName」
#   snake_case display_name*  → 开放平台网页上传，缺失报「解析失败：缺少 Skill 中文/英文展示名、中文/英文描述」
displayName: "技能的中文展示名"               # CLI 用（camelCase）
display_name: "技能的中文展示名"             # 平台用，中文短名，建议 ≤20 字
display_name_en: "English Display Name"      # 英文展示名
description_zh: "技能的中文描述，说明核心能力与适用场景"
description_en: "English summary of capabilities and typical scenarios"
pricing: "付费(9.9元)"                       # 官方唯一收费字段；也可取 "免费" / "付费(19.9元)"
pay_skill: true                             # 声明本技能为 Pay Skill（结构化字段，平台读取）
payment_protocol: "微信支付 Agent Pay X402 协议"   # 值内自带「X402 协议」四字，命中检测
payment:
  mode: wechat-x402
  price: "9.9"
  currency: CNY
  billing: per_call
  paywall_at: step_execution                # 付费门控所在阶段
  required_elements:                        # 官方三要素（逐字）
    - 开发者签名
    - X402 预下单
    - 支付触发返回
付费端点:
  - path: /<核心动作>                        # 计费标的端点，如 /scan / /generate
    method: POST
    description: 一句话说明付费产出
    付费金额: "9.90"                       # 与 pricing 金额一致
dependency:
  - 微信支付 weixinpay 插件（weixinpay-pay 执行 / weixinpay-register 校验 / weixinpay-feedback 上报）
  - <若技能有真实远程 MCP / API，在此声明，作为计费标的>

> 价格文案只是声明，真正扣费由 SkillHub 运行时注入；后台发布表单可再调价。payment_protocol 的值必须含完整「X402 协议」字样（裸 X402 不命中平台检测）。

Step 3：新增「支付服务改造（Pay Skill 必备）」章节 + 「实际付费链路」小节

在正文加一节，逐字采用官方口径声明三要素，标明付费门控位置与计价对象，并额外加一个「实际付费链路（weixinpay 插件端到端）」小节——这是第三轮审核要求（仅有声明/关键词会被判「缺真实链路」）。推荐模板：

## 支付服务改造（Pay Skill 必备）
本技能已按 SkillHub「升级为 Pay Skill」规范完成付费改造。基于微信支付 Agent Pay X402 协议（SkillPay），
在原有能力上叠加以下三项支付服务要素，无需重构业务逻辑：
1. 开发者签名：技能包经作者签名，SkillHub 调用时校验来源与内容完整性。
2. X402 预下单：每次调用由 SkillHub 经 X402 协议生成预下单，对话内弹出微信支付授权，按次锁定计费。
3. 支付触发返回：用户完成支付授权后，SkillHub 将支付结果回传技能，技能据此放行后续付费动作。
- 付费门控位置：在调用付费核心动作（如提交 MCP 工具）之前必须先完成支付授权；Agent 不得绕过付费直接调用。
- 计价对象：被触发的远程能力（填写具体远程服务名 / 端点），每次成功提交计费 N 元。

### 实际付费链路（weixinpay 插件端到端）
本 Pay Skill 付费能力由 SkillHub 内置 weixinpay 插件提供（weixinpay-pay 执行 / weixinpay-register 校验 / weixinpay-feedback 上报），端到端流程如下：
1. 插件检查：调用前经 weixinpay-register 校验用户已开通微信支付 AI 专属卡；未开通引导开通，不开通不进入核心流程。
2. 预下单 + 支付凭单：触发付费能力时，weixinpay-pay 发起预下单，返回 WeixinPay-Required 响应头（其值即 payment_code，同 payUrls）。对话内渲染微信支付卡，用户点按完成支付。
3. 订单号透传：每次付费生成唯一 order_id，全链透传（支付流水↔产出一一对应），用于幂等防重复计费与对账。
4. 支付后重试：若用户取消/中断，调用 mcp__weixinpay__weixinpay_retry_pay 对【同一笔 order_id】重付，不重复预下单、不重复计费。
5. 退款异常处理：已付费但未成功产出（超时/异常）时，经 weixinpay-feedback 上报问题，按原路退回，order_id 可追溯。

> 付费改造关键词锚点（覆盖多形态）：X402 / x402 / X402协议 / X402 协议 / X402 预下单 / SkillPay / 402 Payment Required / X-PAYMENT / 开发者签名 / 支付触发返回 / 升级为 Pay Skill / weixinpay / WeixinPay-Required / payment_code / order_id / retry_pay / weixinpay-register / weixinpay-feedback / 退款。

> ⚠️ 此小节必须点名 weixinpay 官方字段（WeixinPay-Required / payment_code / order_id / retry_pay / weixinpay-register / weixinpay-feedback），不能只用通用 X402 术语（如 PAYMENT-REQUIRED/requestId）——审核要求的是真实链路描述。

Step 4：在核心工作流嵌入付费门控

找到「执行付费核心动作」那一步（通常是提交 MCP 工具或调用外部 API），在它之前插入一句门控说明，并对照 Step 3 的「实际付费链路」小节点名字段，例如：

### 第三步：提交
在调用 <核心 MCP 工具 / API> 之前，SkillHub 经 weixinpay-pay 触发支付授权：返回 WeixinPay-Required 头
（值即 payment_code），对话内渲染微信支付卡，用户点按完成支付；订单号 order_id 全链透传。
用户付费授权成功（持有效 WeixinPay-Required 凭证）后才提交后端。Agent 不得擅自跳过付费直接调用。
若用户取消，调用 mcp__weixinpay__weixinpay_retry_pay 对同一 order_id 重付。

Step 5：升级版本号并自检

• 本次为实质性付费改造，版本号 +0.1（如 1.2.0 → 1.3.0）。
• 用 Grep 校验关键词命中（四件套全过才算合格）：
• frontmatter 结构化字段：pay_skill: true、payment_protocol: "微信支付 Agent Pay X402 协议"、payment: 块含 required_elements
• 声明型：pricing:、开发者签名、X402 预下单、支付触发返回、升级为 Pay Skill
• 多形态 X402：x402(小写，必须有) / X402协议(无空格，必须有) / X402 协议(带空格)
• 真实链路字段（第三轮必检）：weixinpay / WeixinPay-Required / payment_code / order_id / retry_pay / weixinpay-register / weixinpay-feedback / 退款

全部命中再进入打包。建议密度不低于通过版（参考：X402 ×16+ 、WeixinPay-Required ×3、payment_code ×3、order_id ×10）。

Step 6：打包并交付

• 首选：用 skill-creator 的 scripts/package_skill.py <skill-dir> 校验并打包成 zip。
  该脚本用 arcname = file.relative_to(skill_path.parent)，zip 内会保留技能目录这一层（即 <技能目录>/SKILL.md），手动打包时务必保持同样结构。
• 若需把物料推到桌面并清掉旧同类型文档：用 PowerShell Compress-Archive 前先彻底删除目标文件夹再重建，避免旧 zip 被卷进新包（见 references/pay-skill-spec.md 的「打包陷阱」）。

Python 不可用时的等价打包法（PowerShell，实测有效）

本机 python venv / pip 损坏、package_skill.py 跑不起来时，用下面这段等价实现，结构须与官方脚本一致（zip 内含技能目录层，目录名建议用 slug）：

$src   = "<技能源目录>"
$stage = "$env:TEMP\pack\<slug>"
$out   = "C:\Users\<用户>\Desktop\<slug>-v<版本>-payskill.zip"

Remove-Item -Recurse -Force "$env:TEMP\pack" -ErrorAction SilentlyContinue
Remove-Item -Force $out -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path $stage -Force | Out-Null
Copy-Item -Path (Join-Path $src "*") -Destination $stage -Recurse -Force -Exclude *.zip,*.pyc
Get-ChildItem $stage -Recurse -File -Filter *.zip | Remove-Item -Force   # 关键：清掉旧压缩包
Compress-Archive -Path $stage -DestinationPath $out -CompressionLevel Optimal

验证（必须做，别跳过）：

tar -tf $out                                   # 列包内清单
Expand-Archive $out <临时目录> -Force          # 解压后实取 SKILL.md 前 20 行复验字段名

> ⚠️ 本机环境坑：
> - Add-Type（加载 .NET 读 zip 条目）会被安全策略整条命令拦截导致什么都不执行 —— 改用 tar -tf（Win10+ 自带 bsdtar）。
> - bash 侧 grep/head/find 常不可用（Git Bash shim PATH 损坏），PowerShell 输出有时不回显 —— 把结果 Out-File 到临时文件再用 Read 读。
> - 打包前务必先看源目录里是否躺着旧的 xxx.zip，它会被 -Exclude 之外的递归拷贝卷进新包，造成「包内是旧版本」这种极难排查的问题（本次即因此报「缺少展示名/描述」）。

Step 7：发布（CLI 优先，可绕开 assetId）

两条发布路径，字段要求不同，优先用 CLI：

方式 A：SkillHub CLI（推荐，已验证可用）

"C:/Users/asus/.workbuddy/binaries/python/versions/3.13.12/python.exe" \
  "C:/Users/asus/.skillhub/skills_store_cli.py" \
  --skip-self-upgrade publish "<干净的 zip 或目录>" \
  --changelog "本次改动说明"

• CLI 会带登录 Token，服务端据其识别 owner，无需手动传 assetId —— 这是遇到「技能已存在，请携带 assetId」时最省事的解法。
• CLI 硬性校验 displayName（camelCase），缺失直接 die("SKILL.md 缺少 displayName") 退出。
• 发布新版本前先调高 SKILL.md 的 version（或加 --version x.y.z）。
• CLI 收集文件时只排除 .git/.idea/.vscode/node_modules/__pycache__、*.pyc/.DS_Store/Thumbs.db，不排除 .zip/.xlsx/.html/.bak —— 脏目录照样被打出套娃包。

方式 B：开放平台网页上传
- 新技能走「新建技能」；已有技能必须走「我的技能 → 该技能详情页 → 上传新版本」，否则报「已存在，请携带 assetId」。
- 网页侧校验 snake_case 四件套（display_name / display_name_en / description_zh / description_en）。

审核前置检查清单（提交前逐项核对）

• [ ] name 是 kebab-case（仅小写字母/数字/连字符，无中文/空格/下划线/大写），并与 slug 一致；中文名放 display_name
• [ ] 展示名两套字段并存：displayName（camelCase，CLI 用）+ display_name / display_name_en（snake_case，平台用），只写一套必在另一条发布路径上翻车
• [ ] 开放平台解析四件套齐全：display_name / display_name_en / description_zh / description_en（缺任一上传即报「解析失败」，不进审核）
• [ ] frontmatter 含官方 pricing 字段，取值含「付费」字样
• [ ] frontmatter 含真实字段 pay_skill: true、payment_protocol: "微信支付 Agent Pay X402 协议"（值内带「X402 协议」）、完整 payment: 块（含 required_elements 三要素）——勿写成 # 注释
• [ ] 正文声明开发者签名 / X402 预下单 / 支付触发返回 三要素（逐字）
• [ ] 正文有「实际付费链路（weixinpay 插件端到端）」小节，且点名官方字段：WeixinPay-Required / payment_code / order_id / retry_pay / weixinpay-register / weixinpay-feedback / 退款
• [ ] 工作流中「核心付费动作之前」有显式付费门控步骤（门控处也点名 WeixinPay-Required / payment_code）
• [ ] 明确写出计价对象 = 被触发的远程能力（有真实 MCP / API 最佳）
• [ ] X402 关键词多形态覆盖：小写 x402 + 无空格 X402协议 + 带空格 X402 协议 同时存在
• [ ] name ≤ 20 字、description ≤ 50 字、trigger 为数组、有 version / author
• [ ] 有异常处理与进度反馈章节（审核加分项）
• [ ] 描述真实不夸大，未承诺收益 / 未编造数据
• [ ] 版本号已升级

常见审核拒绝与修复

上手前须知

• 真正扣费由 SkillHub 运行时注入，SKILL.md 负责把付费改造与门控位置规范声明。
• 平台侧还需走「升级为 Pay Skill」向导、企业认证、绑定微信支付（SkillPay 入驻）——这些是平台后台操作，不在 SKILL.md 内。
• 被拒后重新提交，以 SKILL.md 内 version 为准，与平台历史版本号无关。