Skill 出厂质检员
把「上传 → 报错 → 猜原因 → 改 → 再传」这个循环，压缩成一次本地检查。
这个 Skill 解决什么
技能市场对上架包的校验规则是硬的，但报错信息通常只有一句
不允许的文件类型 或 400 Bad Request，不说哪个文件。
本 Skill 在本地把平台规则跑一遍，在传之前告诉你哪一条会挂、怎么改。
触发场景
- 「我要把这个 Skill 传上 SkillPay / SkillHub，帮我检查一下」
- 「上传时报『不允许的文件类型』/『名称已被占用』/『解析失败』」
- 「审核被驳回了，看看哪里不合规」
- 「批量发布十几个 Skill，想先做一遍预检」
怎么用
# 检查一个目录
python3 scripts/preflight.py ./my-skill
# 检查待上传的 zip（会顺带验证中文名 UTF-8 标志）
python3 scripts/preflight.py ./my-skill.zip
# 输出机器可读结果，接 CI
python3 scripts/preflight.py ./my-skill --json
# 只跑 SkillPay 专项（买断/订阅、计费口径、云端保护相关）
python3 scripts/preflight.py ./my-skill --platform skillpay
退出码：0 可传 · 1 有风险（能传，但大概率被驳回或影响转化）· 2 会被拒（别传）。
12 项检查
| # | 检查项 | 不合格后果 |
|---|---|---|
| P1 | SKILL.md 位于包根，不多套一层目录 |
平台解析失败，技能进不去索引 |
| P2 | frontmatter 六个必需字段在顶层 | 写在 metadata: 缩进里等于没有 |
| P3 | name 与包目录名完全一致 |
slug 撞车、后台找不到对应商品 |
| P4 | 无独立 LICENSE 文件 |
平台直接 400「不允许的文件类型」 |
| P5 | 无任何位图（png/jpg/gif/webp） | 一律拒绝，压缩到 50KB 也一样拒 |
| P6 | 无 .env、私钥、.DS_Store、__pycache__ |
安全扫描不通过 |
| P7 | 无个人绝对路径、手机号、密钥 | 隐私泄露 + 审核风险 |
| P8 | zip 内中文名带 UTF-8 标志 | Windows 用户解压全是乱码 |
| P9 | 解压后体积 < 20MB | 上传被拒 |
| P10 | description 写清「谁用 / 解决什么 / 拿到什么」 | 能上架但没人买 |
| P11 | 有脚本则写明依赖与运行方式 | 用户装完跑不起来 → 差评退款 |
| P12 | 未混入平台注入文件（.skillpay/、skillpay-onboarding 等） |
干扰内容指纹与数字签名 |
六个必需字段
---
name: my-skill # 必须等于目录名
description: "..." # 至少 40 字，写明触发场景
version: 1.0.0
display_name: "中文名"
display_name_en: "English Name"
visibility: "public"
---
再补 description_zh / description_en / category / tags，检索命中率会明显更好。
三个最容易踩的坑（都是实测）
- 许可信息写进 frontmatter，不要单独放 LICENSE 文件。 独立许可证文件会被当成「不允许的文件类型」直接 400。
- 任何位图都不行，不是体积问题。 500×500、压缩到 0.5MB 的 PNG 照样拒。要配图只能用 SVG。
publish不等于立刻可见。 状态先是pending（内容审核 + 安全扫描），转approved才进搜索索引。这期间在列表里看不到自己，不是失败。
依赖
仅需 Python 3.8+ 标准库（zipfile / re / pathlib / json / argparse），无第三方依赖。
脚本内不发起任何网络请求，不读取包外文件。
边界
- 只做「格式与合规」检查，不判断 Skill 本身好不好用、值不值这个价。
- 不代替平台审核。平台规则会变，以登录后台当期的页面提示为准。
- 不修改被检查的包（
--json只读；不加--fix时全程零写入）。
