技能介绍

要解决的问题

Playable 的专家包存放在内部 CNB 仓库 playable/workbuddy/playable-skill 的 experts/<slug>/ 下，本机的落盘位置却是 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<slug>/。手工安装意味着要自行处理鉴权、拉取归档、剥掉解压时的路径前缀，最后还要把包登记进 marketplace.json。前几步出错只是没装上，最后一步漏掉则包明明躺在目录里、专家中心却完全看不到，而且不会有任何报错。

这个技能把整条链路收进一次调用，并与同族的技能安装器保持相同的下载语义，只在落盘位置和是否注册上做出区分。

核心能力

鉴权双通道：优先复用 CNB 连接器（cnb-api / cnb-woa）提供的归档读取能力，连接器自带凭证；无连接器时回退到本地登录态，读取 ~/.cnb/token 或环境变量 CNB_TOKEN。
实时归档拉取：直接请求 https://api.cnb.cool/<repo>/-/git/archive/<ref>/<path>，由平台在请求时按需打包，仓库里不需要预生成 tarball。
落盘加注册一步到位：解压后自动执行 register_expert.py，校验 plugin.json 完整性并写入 marketplace.json，专家立刻出现在「我的专家」。

执行流程

从语句中解析专家 slug，分支缺省为 main。
检测连接器可用性，命中则拉取归档字节并写入临时 .tgz。
无连接器时调用脚本走登录态回退路径。
校验 gzip 魔数 1f 8b，解压到临时目录后再移动 experts/<slug>/，避免多套一层目录。
注册并确认目标路径下的 plugin.json 已登记。

适用边界与注意点

归档接口强制 Bearer：即使是公开仓库也必须携带 Authorization: Bearer，匿名请求拿不到内容。
路径不存在返回 500 加 JSON，不是 404。必须先验 gzip 魔数再解压，否则会把错误响应当成归档写进磁盘。
不要直接解压到插件目录：tar 包内保留 experts/ 前缀，一步到位的解压会产出 plugins/experts/<slug>。
cnb get-archive 不可用：它强制 Accept JSON，会把二进制内容吞掉。
包内不要放密钥：访问内部 API 时走环境变量。
本机无 Python 时，脚本会提示手动完成注册步骤。
默认仓库可用 CNB_EXPERT_REPO、CNB_EXPERT_BRANCH、CNB_API_ENDPOINT、CNB_EXPERT_DIR 覆盖，便于指向其它仓库。