SkillHub 版本同步
铁律
在 ~/.workbuddy/skills/ 下每修改完一个 skill，就要往 SkillHub 发一个新版本。 不发布 = 本次修改没有版本记录 = 任务没做完。
前置条件（缺一不可）
- CLI 已安装：
~/.local/bin/skillhub（v2026.8.5+） - 已登录：
skillhub auth whoami能输出 userId/handle/role
- 未登录则skillhub login --key skh_xxx --host https://api.skillhub.cn
- Token 只出现一次，务必先存好；不要把 Token 写进 SKILL.md 或任何会被打包上传的文件 - 账号已实名认证（否则发布返回 403）
- ⚠️ 必须是
skh_个人 Token，sk-ent-企业密钥发不了（见下方「两套密钥」） - slug 前缀：用
--prefix <你的handle>或环境变量SKILLHUB_SLUG_PREFIX，保证全网唯一
两套密钥别搞混（已实测确认）
| 前缀 | 写入位置 | 能做什么 | 不能做什么 |
|---|---|---|---|
sk-ent- |
credentials.json::orgs |
搜/装企业私有源的技能 | 不能 publish |
skh_ |
credentials.json::user |
publish 到社区源、comment、run |
— |
skillhub login --key sk-ent-xxx 会打印 ✓ Logged in to <组织名> (@org-xxx)，看起来像登录成功——但那是企业源登录，whoami 仍报未登录。发布走 resolve_user_token，只认 skh_：
- 直接发布 →
Error: 未登录。请先执行: skillhub login --key skh_xxx - 用
SKILLHUB_TOKEN环境变量传企业密钥 →Error: token 必须以 skh_ 开头（早期 sh_pat_ 体系已下线）
要发布，必须另外拿一把 skh_ 个人 Token：skillhub.cn → 头像 → 个人中心 → API keys → 创建 API key（需先完成实名认证）。拿到后：
skillhub login --key skh_xxx --host https://api.skillhub.cn
skillhub auth whoami # 输出 userId/handle/role 才算真的登上了
已穷尽验证，别再试了
2026-09-14 实测，四条路全堵死：
| 尝试 | 结果 |
|---|---|
企业密钥 + CLI publish |
Error: 未登录（resolve_user_token 硬校验 skh_ 前缀） |
SKILLHUB_TOKEN=sk-ent-... 绕过 |
token 必须以 skh_ 开头 |
curl 直打 /api/v1/community/skills/publish |
HTTP 401 {"error":"unauthorized"} |
探测企业发布端点 /api/v1/orgs/{id}/registry/publish |
404 page not found（不存在） |
补充证据（扒了官方前端 JS skill-hub.*.js，3.6MB）：全站只有 /api/v1/community/skills/publish 一个发布端点，没有任何 org/enterprise 发布路径。里面还写死了发布守卫文案：
unauthorized: "请先登录"
realname_required: "请先完成实名认证"
即 登录 + 实名认证 是硬性前置，且都绑定个人账号，与企业密钥无关。
⚠️ 另外：/api/v1/enterprise/* 下任意路径（含不存在的）都返回 405，这是网关兜底，不是端点存在。别被误导。
企业密钥唯一能用的两个端点只有 search 和 download。它其实工作正常——/api/v1/orgs/3457/registry/search 返回 400 {"error":"q is required"}，说明鉴权已通过，只是缺必填参数。
发布必填三件套
CLI 源码 _validate_metadata 只强制这三个字段，缺一个直接拒绝：
| 字段 | 规则 |
|---|---|
slug |
kebab-case，2-128 字符，全网唯一 |
version |
合法 SemVer，如 1.0.0 |
displayName |
非空 |
summary / description / tags / license / homepage 建议有，但不作为阻断项。
⚠️ 现有技能（multi-angle-v7、camera-editing 等）frontmatter 里只有 name 和 description，三个必填字段全都没有，直接用 skillhub publish 会失败。必须先补齐——下面的脚本会自动补。
标准流程（用脚本，别手敲）
python3 ~/.workbuddy/skills/skillhub-version-sync/scripts/sync_skill.py \
<skill目录> \
--prefix <你的handle> \
--bump patch \
--changelog "本次改了什么"
脚本会依次做：
- 读取 SKILL.md frontmatter，缺
slug/version/displayName就补上（只动字段，不碰正文） - 按 SemVer 递增版本（默认 patch；破坏性改动用
--bump major，新功能用--bump minor；首次发布想保留 1.0.0 就用--bump none） - 调用
skillhub publish - 成功写入登记表
~/.skillhub/publish_registry.json（记录 slug、版本、changelog、时间）
首次发布建议先预检：
python3 .../sync_skill.py <skill目录> --prefix <handle> --dry-run
看到 ✓ Dry-run passed: <slug>@<version> 再去掉 --dry-run 正式发布。
脚本参数
| 参数 | 说明 |
|---|---|
--bump patch\|minor\|major\|none |
版本递增方式，默认 patch |
--changelog "..." |
变更说明，必填语义清晰的一句话 |
--slug SLUG |
覆盖 slug（一般只在首次发布时指定） |
--prefix PREFIX |
slug 前缀，建议用 handle |
--display-name NAME |
覆盖 displayName |
--dry-run |
只预检不发布，也不写登记表 |
--json |
JSON 输出，便于程序解析 |
备选路径：没有 skh_ 时，打包 → 网页上传
用户暂时拿不到 skh_ 个人 Token 时，走这条路：CLI 打包成 zip，用户自己在网页端上传。功能等价，只是发布动作由人完成。
python3 ~/.workbuddy/skills/skillhub-version-sync/scripts/pack_skill.py \
<skill目录> --out ~/skillhub-dist
脚本会：
- 校验 frontmatter 三件套（缺了直接报错，并提示先跑
sync_skill.py补齐） - 按 CLI 同款规则打包：排除
.git/.idea/.vscode/node_modules/__pycache__，排除.pyc/.DS_Store/Thumbs.db，跳过软链接，create_system=3 - 输出
<slug>-<version>.zip
然后把 zip 路径报给用户，让他到 <https://skillhub.cn> 网页端上传。上传成功后，把实际发布的 slug 和版本号回报给你，你再手动补记 ~/.skillhub/publish_registry.json，保证后续版本递增有据可依。
注意：网页上传同样要求登录 + 实名认证，只是不要求 CLI 登录态。
发布后
输出 ✓ Published: skillId=xxx status=pending_review 即进入审核。可选校验：
skillhub verify <slug>@<version>
然后回报给用户：slug、版本号、发布状态、详情页 URL。
排错
| 报错 | 处理 |
|---|---|
command not found: skillhub |
export PATH="$HOME/.local/bin:$PATH" |
未登录。请先执行 skillhub login |
用 --token 或 SKILLHUB_TOKEN 环境变量传入 |
401 invalid api key |
Token 被撤销，去个人中心重建一把 |
403 请先完成实名认证 |
回 skillhub.cn 完成人脸核身 |
409 slug 已被占用 |
换 slug，加上 handle 前缀 |
429 请求过于频繁 |
等约 1 分钟重试 |
| 详情页显示"未找到" | 审核中，去个人中心 → 我的 Skill 看实时状态 |
边界
- 只发布我们自己创建或修改过的 skill。别人写的原样技能不要挂自己名下发布。
- 打包会自动排除
.git、node_modules、__pycache__、.DS_Store，并跳过所有软链接——不要把关键文件做成软链。 - 发布前扫一眼技能目录，别把密钥、Token、个人隐私文件打进去。
