万象-付费技能自检
把一个技能包在交上去之前先过一遍：它是不是一个合格的 Pay Skill（支付宝 AI 按量付费技能）。
一、为什么需要它
平台对「Pay Skill」的检测不在提交那一刻定论。三条实测得来的边界：
| 说法 | 事实 |
|---|---|
| 「预检通过 = 能过审」 | ❌ 官方原文：预检查提示与最终审核结果不同 |
| 「提交成功 = 已上架」 | ❌ 官方原文：提交成功或预检查通过不代表已上架 |
| 「写了付费文案 = 有付费能力」 | ❌ 官方原文：不能仅凭文案声明替代真实可用的服务 |
⇒ 能在本地先判的，就别留给平台拒。本技能把官方要求拆成可逐项判的清单。
二、免费层：官方交付判据（直接读）
2.1 交付树（包内该有什么）
<技能名>/
├── SKILL.md # 必需
├── scripts/<技能名>-paid.mjs # 必需 —— 买家侧支付编排入口
└── references/ # 可选
反向清单（包内不该有什么）：
- ❌ 私钥 / 令牌 / .env
- ❌ 测试状态文件（订单号、实验数据）
- ❌ 依赖目录（node_modules/ 等）
- ❌ 服务端源码（a2m/ 之类 —— 服务端部署在服务器，不随包发）
2.2 提交前自查五项
| # | 检查项 | 本地怎么看 |
|---|---|---|
| 1 | 402 账单 | probe 能拿到 HTTP 402 ＋ Payment-Needed 头 |
| 2 | 携凭证重试 | 付款后重放原请求，服务端认账放行 |
| 3 | 服务端验付 | 交付前由服务端核验，不在客户端自证 |
| 4 | 商家履约 | 付款成功 → 签发交付物（凭证 / 资源） |
| 5 | 订单与幂等 | 同一订单重复请求不重复扣款、不重复交付 |
2.3 三种合法形态（任选其一，不必自带后端）
| 形态 | 特征 | 说明 |
|---|---|---|
| A | scripts/*_paid.py ＋ 授权凭证 |
自建编排 + 离线验签 |
| B | pricing: 头字段 ＋ pay_client.py |
走官方客户端 |
| C | 仅 dependencies: [alipay-payment-skill] |
零脚本，声明式 |
> 实测：市场上正在收费的技能三种形态都有。不存在"必须自带后端"这回事。
三、付费层：整库批量自检 + 合规报告
对整个技能目录做一遍自检，输出：
- 每个包的通过 / 不通过逐项判定（交付树 / 反向清单 / 五项自查 / 字段齐备）
- 差距清单：缺哪一件、在哪一层
- 可交付的合规报告（Markdown，可直接作为上架材料附件）
单价：¥0.25 一次，付款后 3 天内不限次使用。
付费链路（本技能的实现）
本技能自身就是一个 Pay Skill，付费路径如下：
- 探价：调
scripts/omni-payskill-selfcheck-paid.mjs probe
→ 服务端返回HTTP 402＋Payment-Needed头（含out_trade_no、单价、币种） - 付款：
pay子命令把账单交给支付宝官方 CLI，由使用者本人扫码/授权
—— 本技能不自行实现付款或签名，不接触任何密钥 - 取件：
complete携订单号回查服务端，取回授权凭证，本机离线验签后放行 - 履约：服务端签发凭证，凭证有效期 3 天（到期需重新付款）
金额以服务端账单为准，本技能不硬编码断言。
四、怎么用
# 免费层：列出判据
python scripts/payskill_selfcheck.py --rules
# 免费层：单个包体检
python scripts/payskill_selfcheck.py --pkg <技能目录>
# 付费层：整库批量自检 + 出报告（需先完成付费）
python scripts/payskill_selfcheck.py --root <技能库根目录> --report 合规报告.md --license <凭证文件>
退出码：0 全部通过 ｜ 1 有差距 ｜ 2 未付款（需先走付费流程） ｜ 3 路径/参数错误
五、判据来源
- SkillHub 官方《使用指南 · 升级为 Pay Skill》章节
- 官方示例脚本（
scripts/<name>-paid.mjs的 probe / pay / complete 三动作约定） - 对市场上正在收费的个人技能包的实地对照
凡官方未明文、由实测得出的判据，正文均标注「实测」。
六、边界与纪律
- 本技能只做静态检查，不访问网络、不修改被检技能包。
- 免费层永远可读；付费层只解锁批量与报告导出。
- 服务端地址与单价以账单为唯一来源；账单不可解码时原样落盘、不猜测。
