playable专家安装器

概述

playable-expert-installer

从内部 CNB 仓库 playable/workbuddy/playable-skill 的 experts/<slug>/ 目录，把指定专家包（agent 单体专家或 team 专家团）安装到本机 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<slug>/，并自动调用内置的 register_expert.py 注册到 marketplace.json，使其立刻出现在「我的专家」中。

这是 playable-skill-installer 的姊妹技能：下载机制完全复用（CNB 实时归档接口 + 连接器优先 / 登录态回退），唯一差别是落盘位置和多一步注册——专家包必须登记进 marketplace.json 才会被专家中心发现，而技能包丢进目录即自动加载。

鉴权策略：连接器优先、登录态回退。

• 连接器优先：若 WorkBuddy 已连接 CNB 连接器（cnb-api / cnb-woa），优先用其提供的仓库归档 / 原始内容读取能力拉取 experts/<slug>（连接器自动携带鉴权，用户无需关心 token）。
• 登录态回退：若无可用连接器，运行本技能自带的 scripts/install.sh <slug> [branch]（macOS/Linux）或 scripts/install.ps1 <slug> [branch]（Windows），它读取本地 cnb login 的 ~/.cnb/token（取其 access_token），或环境变量 CNB_TOKEN。

触发词

• “安装 playable 专家 <slug>” / “装一下 <slug> 专家”
• “从 CNB 装专家 <slug>” / “从 playable-skill 仓库安装专家 <slug>”
• 用户给出 playable/workbuddy/playable-skill 与某个专家 slug，要求安装

执行步骤

1. 解析参数：从用户语句中提取必填的 <slug>（专家包名）；可选 <branch>，默认 main。
2. 连接器优先：检查当前是否有可用的 CNB 连接器工具（如 cnb-api / cnb-woa 连接器提供的仓库归档 / 文件内容读取工具）。若有，调用它拉取

playable/workbuddy/playable-skill 在 <branch> 分支下 experts/<slug> 路径的归档/原始内容，落盘为临时 .tgz，跳到第 4 步。

1. 登录态回退：若无连接器，执行（macOS/Linux）：

bash "<skill_dir>/scripts/install.sh" "<slug>" ["<branch>"]（Windows 用 pwsh "<skill_dir>/scripts/install.ps1" "<slug>" ["<branch>"]）。脚本会自动取 token、下载、落盘到 my-experts/plugins/<slug>、并注册，成功则直接跳到第 5 步；若报“未找到 CNB 凭证”，提示用户先 cnb login 或连接 CNB 连接器。

1. （仅连接器路径）解包：若第 2 步拿到的是原始归档字节，将其写入临时 .tgz，校验 gzip 魔数（前 2 字节 1f 8b），然后解压到临时目录，再把内层 experts/<slug> 移动到 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<slug>（见下方“重要约束”）。
2. 注册：无论哪条路径，落盘后都必须运行内置脚本完成注册（这是专家包与技能包的关键区别——技能丢进目录即被自动发现，专家必须登记到 marketplace.json 才可见）：

python3 "<skill_dir>/scripts/register_expert.py" "<dest>" --marketplace-dir "$HOME/.workbuddy/plugins/marketplaces/my-experts"register_expert.py 会校验 plugin.json 完整性，写入 my-experts/.codebuddy-plugin/marketplace.json。

1. 校验与反馈：确认 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<slug>/.codebuddy-plugin/plugin.json 存在且已登记；告知用户「打开 WorkBuddy 专家中心 → 我的专家，即可看到并使用该专家」。

重要约束（已实测，必须遵守）

• CNB 归档实时生成、无需手工打包：https://api.cnb.cool/<org>/<repo>/-/git/archive/<branch>/<path> 在请求时由平台实时把该路径子树打成 gzip(tar.gz) 返回。你只需把专家目录（含 .codebuddy-plugin/）作为普通文件提交到仓库 experts/<slug>/ 即可，无需 package_expert.py 预打包。
• tar 包保留路径前缀：解压后顶层是 experts/<slug>/（不是 <slug>/）。切勿直接 tar -xzf ... -C ~/.workbuddy/.../plugins/（会多套一层 experts/）。正确做法：先解到临时目录，再 mv <tmp>/experts/<slug> ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<slug>。
• 路径不存在 → 500 + JSON（非 404）：请求 experts/<slug> 但该路径在仓库中不存在时，CNB 返回 HTTP 500 且 body 是 JSON，不是 gzip。安装前必须用 gzip 魔数 校验返回体，非 gzip 即报错退出，避免把错误 JSON 当归档解压。
• 公开仓库也要 Bearer：CNB 归档接口即使是公开仓库也必须带 Authorization: Bearer <token>，无法匿名下载。token 由连接器或 cnb login 集中托管即可。
• cnb CLI 的 get-archive 不可用：该命令强制 Accept: application/vnd.cnb.api+json，会把归档二进制吞掉。请走上面的直连 HTTP（连接器或 install 脚本内已处理）。
• 必须注册：技能包放到目录即生效；专家包必须执行注册步骤才会出现在「我的专家」。本技能已内置 register_expert.py 并在脚本中自动调用；若本机无 Python，install 脚本会提示你手动运行注册命令。
• 机密勿入包：专家包内不要放密钥；调用内部 API 时走环境变量。

自定义仓库（可选）

默认仓库固定为 playable/workbuddy/playable-skill。如需指向其他仓库，可用环境变量覆盖：CNB_EXPERT_REPO（默认 playable/workbuddy/playable-skill）、CNB_EXPERT_BRANCH（默认 main）、CNB_API_ENDPOINT（默认 https://api.cnb.cool）、CNB_EXPERT_DIR（默认 experts，即仓库内专家包所在子目录前缀）。