SkillHub 自动发布流水线
Overview
把本地 Skill 目录一键打包发布到 SkillHub（skillhub.cn）技能商店。基于官方 skillhub CLI（cli/skills_store_cli.py，仅标准库、无第三方依赖），覆盖：元数据校验 → dry-run → 版本冲突处理 → 正式发布 → 可见性验证。
前置条件
- SKILL.md frontmatter 必须包含发布契约字段（否则 dry-run 直接报错）：
-slug：kebab-case，2-128 字符（如my-skill）
-version：SemVer（如1.0.2）
-displayName：展示名
- 可选：summary/tags(数组) /license/homepage - 发布认证：需要
skh_开头的 PAT（skillhub.cn 个人中心生成）。token 传递优先级：--token>SKILLHUB_TOKEN环境变量 >~/.skillhub/credentials.json（skillhub login --key skh_xxx写入）。token 只走环境变量，绝不写入任何本地文件。 - CLI 定位：
scripts/publish_to_skillhub.py自动按序查找：环境变量SKILLHUB_CLI>~/.skillhub/安装的 CLI > 本工作区G:/AI工具/.workbuddy/_skillhub_kit/cli/skills_store_cli.py（可随时用官方 latest.tar.gz 刷新：https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/latest.tar.gz）。
Workflow
Step 1：校验元数据（免 token）
python scripts/publish_to_skillhub.py 技能目录 --dry-run
# 通过 → {"dryRun": true, "slug": "...", "version": "..."}
dry-run 在 token 解析之前执行，不需要 token。任何 frontmatter 缺失（slug/version/displayName）都会在此暴露。
Step 2：查询线上版本（冲突预判）
python scripts/publish_to_skillhub.py 技能目录 --search
# 显示该 slug 在 SkillHub 上的最新版本与归属 namespace
判断：@你的handle/技能slug 且内容一致 → 是你自己的技能 → 用更高版本号升级发布；slug 被他人占用 → 需要换 slug。
Step 3：正式发布（需要 token）
SKILLHUB_TOKEN=skh_xxx python scripts/publish_to_skillhub.py 技能目录 \
--version 1.0.2 --changelog "v1.0.2 更新内容..."
成功返回：{"ok":true, "skillId":..., "versionId":..., "slug":..., "version":...}，平台进入审核（contentAudit/securityScan/review = pending），通过后公开可见。
Step 4：版本冲突自动处理（409 VERSION_EXISTS）
若 status 409 / code VERSION_EXISTS：该 slug 下版本号已被占用。处理规则：
- 同 slug 升级：仅 bump 版本号（如 1.0.0 → 1.0.1 → 1.0.2），changelog 注明本次变更——这是给"自己的技能"发新版的标准姿势；
- 内容变化大：bump minor（1.1.0）；破坏性变化：bump major（2.0.0）；
- 换内容才考虑换 slug（slug 是技能的身份标识，换 slug = 发布全新技能）。
脚本检测到 409 时会提示建议版本号（自动解析 SKILL.md 当前版本 minor+1），由执行者确认后重发。
Step 5：发布后验证
python scripts/publish_to_skillhub.py 技能目录 --search
# latest 指向刚发布的版本即成功；也可 skillhub search 技能slug / skillhub install 技能slug 验证
关键知识点
- 发布接口：POST /api/v1/community/skills/publish（multipart：
payloadJSON + 每个文件一个filespart，filename=相对路径）；单 zip ≤ 10MB。 - 认证验证：GET /api/v1/auth/me（
skillhub auth whoami可验 token 归属：handle/id/role）。 - token 格式：必须
skh_前缀（旧sh_pat_体系已下线）。 - 收集规则：自动排除 .git/.idea/.vscode/node_modules/pycache 与 .pyc/.DS_Store/Thumbs.db。
- 发布频率：平台对发布有频控（按 token/IP），连续发版可能命中 429 频控，需等待。
- 元数据来源：version 可从 SKILL.md frontmatter 读，也可
--version覆盖（推荐用 --version 显式指定，避免改文件）。
Resources
scripts/publish_to_skillhub.py— 一键发布脚本（定位 CLI / dry-run / search / 发布 / 409 自动提示 bump）。references/skillhub-api-contract.md— 发布契约细节：frontmatter 字段校验规则、payload 结构、错误码表（VERSION_EXISTS/SLUG_TAKEN/429 等）。
