付费 Skill 三步开通
把「一个能用的 Skill」变成「一个能真实收钱、并且在 SkillHub 上买得到的 Pay Skill」。这份手册来自一次完整实战：从 SkillHub 审核提示「无付费改造迹象」，一路做到真人扫码付 ¥0.99、服务端交付完整报告并回履约确认，最后用 skillhub CLI 一版版发出去。
核心判断先立住：付费 Skill 不是把 SKILL.md 写上「本技能收费 ¥0.99」就完事。平台审核和支付宝都只认真实可调用的收单链路——没付款必须返回 402，付款后必须服务端验付、交付真实内容、回履约回执，同一笔订单重放不能二次扣款。文案只是入口，服务端才是本体；而 skillhub publish 只是把这套本体放到平台上，不能替代它。
流程总览：三步开通 + 一步上架
| 步骤 | 目标 | 产出 | 没做完会怎样 |
|---|---|---|---|
| 第 0 步 · 环境体检 | 摸清本机有哪些命令行工具、缺哪些、谁能代装、哪些必须用户本人操作 | 一张依赖清单 + 安装/降级方案 | 后面每一步都会卡在 command not found 或权限上 |
| 第一步 · 改造 Skill 过审 | 文案、付费章节、买家侧编排脚本写齐，通过平台付费预检 | 能发布、带付费标记的 Skill 包 | 发布时被提示「未发现付费改造迹象」 |
| 第二步 · 收单服务端 | 公网可访问的 402 账单 + 验付 + 真实交付 + 履约 + 幂等 | 一个能独立收钱的 HTTPS 服务 | 用户付了钱拿不到东西，或没付也能白嫖 |
| 第三步 · 支付宝开通与验收 | 入驻签约、应用上线、服务注册、买家钱包、真人付款闭环 | 真正收到钱、能查到履约回执 | 服务是死的，BIZ_ORDER_NOT_FOUND / 自买自卖被拦 |
| 第四步 · skillhub-cli 上架 | metadata 校验、官方预检、包内清单、dry-run、正式发布与核验 | 平台可搜索、可安装的版本 + versionId | 服务跑通了但用户搜不到；或包里混进密钥/订单 |
详细操作分别见 第 0 步：工具链与权限边界、第一步：改造 Skill 并通过付费预检、第二步：收单服务端、第三步：支付宝开通与真人验收、第四步：用 skillhub-cli 上架。
第 0 步 · 环境体检（每次开工第一件事）
默认假设：目标机器一个相关命令行工具都没有。 本机装过 skillhub、alipay-cli、alipay-bot、gh、aliyun，不代表用户的机器有；docker 甚至常常只在远端服务器上才有。所以不要一上来就敲 skillhub publish，先在本 Skill 目录下跑：
node scripts/doctor.mjs # 只体检本机
node scripts/doctor.mjs /path/to/target-skill # 顺带体检目标 skill 目录
体检把工具分成四组，逐组给「安装命令 / 验证命令 / 缺了怎么绕」：
- 平台侧：
skillhub（登录、发布、dry-run、付费预检、签名核验、查评估报告） - 卖家集成侧：
alipay-cli（由官方alipay-aipay集成 Skill 带入）、npx（安装入口） - 买家侧：
alipay-bot（由@alipay/agent-payment安装，负责 402 付款与查单） - 部署侧：
ssh/rsync/git/gh/aliyun/openssl/curl/ 远端docker
> 安装与降级方案、以及「哪些事 Agent 永远不能代做」写在 00-toolchain.md。任何 curl | bash、要账号、要实名、要扫码、要密钥、要花钱、要对外发布的动作，先向用户说明并取得确认。
开工前需要向用户收齐这六项（缺一项就先问，别猜）：
| 项 | 说明 | 例子 |
|---|---|---|
| 目标 Skill 目录 | 新建还是改造已有 skill | ~/.workbuddy/skills/my-skill |
| 服务名 / 描述 | 注册到支付宝市场时用 | 「Skill评估 / 付费精选榜」 |
| 公网 HTTPS 地址 | 收单端点，必须能被支付宝回调访问 | https://example.com/api/evaluate |
| 单价 | 与支付宝注册价、402 账单金额必须一致 | ¥0.99 / 次 |
| 卖家支付宝账号 | 已实名，用于入驻签约 | 商户 PID 之后由接口查回 |
| 另一个实名支付宝账号 | 真人付款验收用，不能和卖家是同一个 | 见第三步 |
第一步 · 改造 Skill 并通过付费预检
一句话：让平台看得出「这个 Skill 会真的发起收款」，并且代码里真的有这条链路。
必做的四件事：
- 付费章节写进
SKILL.md：计费口径、402 Payment Required/Payment-Needed/Payment-Proof、probe → pay → complete → ack四步、验付与履约接口名（alipay.aipay.agent.payment.verify、alipay.aipay.agent.fulfillment.confirm）、支付宝依赖包、幂等与不重复扣款说明。关键词不是凑字数，是平台预检的实际口径，缺了就会退回。 - 买家侧编排脚本
scripts/<name>-paid.mjs：probe请求资源端点并保存 402 账单；pay把Payment-Needed交给alipay-bot 402-buyer-pay；complete用alipay-bot 402-query-payment-status查单 + 带凭证取资源 + 自动履约回执。状态写在--state-dir，不要把支付凭证打印进日志。 - 开账单之前校验输入：请求体不合规（缺内容、含私钥、超大小）直接 400，绝不先收钱再说。
- 发布前自检与升版（发布动作本身在第四步，别在这里顺手发）：
python3 scripts/l0_precheck.py . --compact # 若目标 skill 自带；检查结构与悬挂引用
node <本skill目录>/scripts/precheck-pay-skill.mjs . # 付费关键字 + 密钥泄漏 + 运行时产物 + 悬挂引用
node <本skill目录>/scripts/publish-skillhub.mjs . --precheck --json # 上架只读预演：包内清单 + 官方预检 + CLI dry-run
官方付费预检可以自己先跑一遍（比等审核退回快得多）：
TOKEN=$(skillhub auth token 2>/dev/null | tail -1)
curl -s -m 40 -X POST "https://api.skillhub.cn/api/v1/community/skills/precheck-alipay" \
-H "Authorization: Bearer $TOKEN" -F "file=@SKILL.md"
# 期望：compliance=pass / score=100 / missing_features 为空
打包前把 .pay_state/、__pycache__/、.env、secrets/ 移出目录，别把测试订单和密钥发出去。skillhub publish --dry-run 只校验 metadata，不列文件、不扫密钥，包内清单必须自己看或交给上架脚本。详细字段表、常见审核提示与修法见 01-step1-skill.md，可直接抄的付费章节见 付费章节模板，买家侧脚本骨架见 买家编排骨架，最小可发布头部见 元数据模板。
> 硬规则：每次修改交付物都要同步升版本号，并在版本记录里补一行说明改了什么。小改递增末位，功能调整递增中位。版本真相源以项目里已有的为准（如 SKILL.md 的 version、package.json 的 version），所有副本（lock、README、文档）一起改。
> 自检脚本是给目标付费 Skill 用的：本手册自身是指导型 Skill、scripts/ 里没有买家编排脚本，检查自己时加 --no-script-check 跳过该项；检查目标 Skill 时用默认模式。
第二步 · 收单服务端（真正收钱的地方）
别自己从零发明协议，先装官方集成 Skill，让它生成验付与履约代码，再填业务逻辑：
npx -y @alipay/alipay-aipay@latest install --target auto
# 然后加载 alipay-aipay 技能，按它的引导为本项目的业务 API 接入按量付费
服务端必须实现这条状态机（完整契约与字段表）：
POST /api/<resource>
├─ 输入不合规 → 400（不生成账单、不收钱）
├─ 无 Payment-Proof → 402 + Payment-Needed（Base64URL 账单，含价格/商户/有效期/RSA2 签名）
├─ 凭证无效 → 重新下发 402（绝不交付）
├─ 验付通过 → 生成真实交付内容 → 返回 200 → 发履约确认
└─ 同一凭证 24h 内重放 → 幂等回放已存结果（already_fulfilled），不二次扣款、不重算
四个最容易翻车的点：
- 交付内容必须真实。返回个 "这是报告占位" 的 JSON，钱收了但商品没给，是这套链路最没意义的状态。把 Skill 原来的核心能力迁到服务端，或让服务端调用真实引擎；报告类商品建议同时给 Markdown + 自包含 HTML（可离线看、带图表）。
- 账单有分层。402 的账单解开后常在
protocol/method子对象里，out_trade_no、amount别在顶层找。 - 沙箱和生产要硬隔离。沙箱账单金额常是 ¥0.01、
service_id带 mock 字样；切生产时配置文件、环境变量、私钥、seller_id全部换掉，并在启动断言里拦住残留的 mock 值。 - 私钥只在服务端。用文件只读挂载或环境变量注入，容器非 root 运行；订单目录属主要和容器用户一致（uid 1000 的容器读 root:600 的文件会直接 EACCES 打挂进程）。
部署可以很轻：一台有公网 IP 的 ECS + Docker Compose + 现成的 nginx 反代 + Let's Encrypt 证书。DNS 加 A 记录、80/443 若已被容器占用就把站点配置放进那个 nginx 容器、证书做自动同步与 reload。冒烟至少覆盖：/health = 200、无凭证 POST = 402、伪造 Proof = 402、非法输入 = 400、免费额度只能用一次。
第三步 · 支付宝开通与真人验收
这步 CLI 能干大部分，但有四件事只能用户本人干：实名与签约、生成密钥对并提供应用公钥、点公钥确认页 / 扫码、用另一个支付宝账号真实付款。先讲清楚，别让用户在中途才发现要切账号。
CLI 侧的典型顺序（命令与返回值详解）：
# 能力探查：不要猜方法名
alipay-cli mcp list apprelease --json
# 入驻签约 → 状态 SIGNED_EFFECTIVE
# 创建应用 → 绑公钥 → 用户点确认 → 提审 → ON_LINE
alipay-cli mcp call apprelease.createApplication -d '{"request":{"applicationType":"WEBAPP", ...}}' --json
alipay-cli mcp call apprelease.createKeyConfirmPage -d '{"request":{"appId":"...","publicKey":"...","identityContext":"..."}}' --json
alipay-cli mcp call apprelease.submitApplicationAudit -d '{"request":{"appId":"...","identityContext":"..."}}' --json
alipay-cli mcp call apprelease.queryApplicationInfo -d '{"request":{"appId":"..."}}' --json
# 注册服务（地址、单价与 402 账单保持一致）→ ACTIVE
alipay-cli mcp call a2a-pay-service.saveBazaarServiceForMcp -d '{"request":{...}}' --json
# 买家侧钱包
alipay-bot check-wallet
alipay-bot apply-wallet --agent-name "<服务名>" --json # 出开通二维码/短链
# 用户扫码后再次 check-wallet → status: bound（新版通常扫码即绑定，不会再给 6 位授权码）
alipay-bot close-wallet # 换号时才用
真人验收这一步的钱不能省，它是唯一能证明「真能收钱」的动作：
probe下一张新的 402 账单 →pay拉起收银台 → 用户用非卖家账号扫码付款；complete查单时用支付宝交易号-t/--trade-no，不要用商户out_trade_no走--out-shake-no（那是签约/代扣查询号，必然BIZ_ORDER_NOT_FOUND）；- 核对交付内容是真实结果、履约回执已发送；再查一次单确认
already_fulfilled: true，不二次扣款。
如果付款时报「买家和卖家不能相同」，不是代码问题：本机钱包绑的就是商户自己的账号，必须换一个实名账号（先 close-wallet 解绑再重新 apply-wallet）。全部踩坑对照表见 错误速查，上线勾选清单见 验收清单。
第四步 · 用 skillhub-cli 上架（收尾）
前三步让 Skill 能收钱，这一步让它在 SkillHub 上被买得到。完整命令、metadata 契约、错误码与无 CLI 降级见 07-publish-skillhub.md，可直接执行的流水线是 scripts/publish-skillhub.mjs。
先确认 CLI 与登录态（默认机器没有，按第 0 步体检后再装）：
skillhub --version
skillhub login --key skh_xxx # token 从「个人中心 → API keys」取，别写进文件
skillhub auth whoami
发布前必须过的四关，一条命令跑完只读预演（不会发布）：
node <本skill目录>/scripts/publish-skillhub.mjs . --precheck --json
| 关 | 查什么 |
|---|---|
| metadata | slug kebab-case、version SemVer x.y.z、displayName 非空；description 必须单行（CLI 的简易 frontmatter 解析不支持多行/嵌套） |
| 包内清单 | CLI 只自动排除 .git / node_modules / __pycache__ 等；.env、secrets/、订单、缓存、私钥、二维码都会照传。脚本按 CLI 规则列清单并扫敏感内容 |
| 官方预检 | compliance=pass / score=100 / missing_features 空；顺带跑 skillhub publish . --dry-run --json 确认元数据 |
| 升版 | version 递增、版本记录补一行，--changelog 写同一句说明 |
> --dry-run 是假绿高发区：它只回 {"dryRun":true,"slug":"...","version":"..."}，不列文件、不扫密钥、不联网、不上传。别拿它当「包干净」的证明。
取得用户明确同意后才真正发布，并记下 versionId 与审核状态：
skillhub publish . --changelog "一句话说明改了什么" --json
# 或让脚本一次做完（--publish --yes 缺一不可，缺 --yes 一律只预演）
node <本skill目录>/scripts/publish-skillhub.mjs . --precheck --bump minor \
--changelog "补充上架流程" --publish --yes
发布后核验签名与包内容：skillhub verify <slug>@<version> --json、skillhub install <slug> --dir /tmp/sh-verify --force --json、skillhub skill evaluation <slug> --json。reviewStatus: pending 是常态，别反复重发同一版本；已过审的付费 Skill 带 pricing_type: alipay 标签，那是审核结果，不是自己往 frontmatter 里写的字段。
红线（别踩）
- 私钥、支付链接、二维码、交易号、SkillHub token 不要写进 Skill 包、日志、Git 仓库或对外文档；案例值也不能复用。
- 用户没明确同意，不代装工具、不代签约、不代生成密钥、不代付款、不主动花真钱、不擅自
skillhub publish；金额再小也要先说。 - 验付结果不明先查单，不要让用户再付一次。
- 免费额度、幂等回放、无效凭证拒付三条路径都要实测，不能只测「付款成功」。
- 服务地址、注册单价、402 账单金额、SKILL.md 标价四处必须一致；改价要一起改并升版重发。
- 改动交付物就升版并补版本记录，发布后记
versionId；别让线上版本失联。
附：一次真实实战的完整复盘
这次会话把上面四步完整跑了一遍，含所有中途翻车与修法：实战复盘。第一次做建议按复盘的时间线对照着走，能少踩一半坑。
版本记录
- 1.1.0 — 新增「第四步 · 用 skillhub-cli 上架」：
references/07-publish-skillhub.md（CLI 安装/登录、metadata 契约、打包排除规则、官方预检、发布参数与返回字段、发布后核验、改版重发、无 CLI 降级、错误速查）、scripts/publish-skillhub.mjs（零依赖只读流水线，默认绝不发布，--publish --yes才上架，可自动升版补版本记录）、templates/skill-metadata.md（最小可发布头部）；修正「dry-run 会列包内文件清单」的错误认知；环境体检新增 CLI 上架必填字段检查；静态自检忽略代码块/行内代码里的正则，不再误判为悬挂引用，并按官方实测口径放宽支付宝依赖检查（至少一个包名即通过，缺另一个只 WARN，对已过审 Skill 不再误报）；工具链、第一步、错误速查、复盘、验收清单同步补上架条目。 - 1.0.1 — 交付前打磨：环境体检修正不认
--version的 CLI 版本显示；静态自检新增--no-script-check（指导型手册用）；买家编排模板补齐402-buyer-pay的资源地址与方法参数、修正交易号解析与 Base64URL 解码；模板经本地 mock 402 服务端 + 假买家 CLI 端到端演练通过（账单解析、交易号写入、md/html 落盘一致、中文零乱码）。 - 1.0.0 — 首版。从一次完整 Pay Skill 上线实战沉淀出「环境体检 + 三步开通」方法论：工具链缺失与降级、SkillHub 付费预检口径、A402 服务端契约、支付宝入驻/应用/服务注册/买家钱包、真人付款验收、错误速查与验收清单；附环境体检脚本、付费静态自检脚本、章节与编排模板。
