WorkBuddy 专家与 Skills 目录导入

一阶段范围

当前导入链路只处理两类资源：

skills/ 下的独立 Skills；
experts/ 中 expertType=agent 的单专家，以及专家引用的 Skills。

专家团、团队编排、WorkBuddy 专属 Hooks、MCP、Connector 和平台命令不在一阶段范围内。转换器会跳过专家团，并将无法安全转换的资源标记为 blocked，不会发布到专家目录。

审计会递归识别结构化的环境变量声明，并检查运行时命令和本地配置要求。当前 Poco 执行镜像无法保证提供的外部 CLI、缺少映射的本地配置，以及包含密钥、原生二进制或越界符号链接的资源都会被标记为 blocked，避免导入后才在执行阶段失败。

准备工作

确认数据包的使用和再分发授权，并选择合适的 distribution-policy。
配置 Backend 使用的 PostgreSQL 和 S3/兼容对象存储。
确认 --admin-user-id 对应现有管理员，该用户将成为导入系统 Skills 的所有者；后续重试和更新应继续使用同一所有者。
同步依赖并执行数据库迁移：

cd backend
uv sync
uv run alembic upgrade heads

可以从 RipperTs/workbuddyskills 挑选数据，也可以使用其他结构兼容且已获得授权的数据包。使用前应检查来源仓库及具体资源目录中的许可说明。

完整的本地与 Docker 导入命令、运行约束和状态码说明统一维护在 backend/scripts/README.md。

Docker 部署

Backend 镜像包含 WorkBuddy 导入器。生产环境通过复用 Backend 镜像的一次性容器执行，不要在常驻 API 容器内复制或运行数据包。

数据包从宿主机只读挂载，报告写入独立持久目录：

export WORKBUDDY_DIR=/opt/poco/imports/workbuddy
export WORKBUDDY_REPORT_DIR=/opt/poco/import-reports

REPORT_NAME="workbuddy-audit-$(date +%Y%m%d-%H%M%S).json"
docker compose run --rm --no-deps \
  --name poco-workbuddy-import \
  -v "$WORKBUDDY_DIR:/imports/workbuddy:ro" \
  -v "$WORKBUDDY_REPORT_DIR:/reports" \
  backend \
  /app/.venv/bin/python /app/scripts/import_workbuddy_catalog.py \
  /imports/workbuddy \
  --report "/reports/$REPORT_NAME"

审计通过后，使用相同的一次性容器命令增加 --apply、管理员、分发策略和可选的 --publish 参数。生产环境应先导入但不发布专家，检查报告后再执行发布。

先审计，不写入

审计命令只读取数据包，不修改数据库和对象存储：

cd backend
uv run python scripts/import_workbuddy_catalog.py \
  /absolute/path/to/workbuddyskills-main \
  --report /tmp/workbuddy-audit.json

命令会将审计阶段、耗时和资源数量输出到 stderr，最终 JSON 报告仍单独输出到 stdout，因此可以继续通过 jq 或重定向处理报告。

报告重点字段：

summary.standalone_skills：独立 Skills 数量；
summary.dependency_skills：去重后的专家依赖 Skills 数量；
summary.single_experts：单专家数量；
summary.excluded_teams：被明确排除的专家团数量；
blocked_skill_items、blocked_expert_items：不兼容资源和具体原因。

ready 表示资源通过了格式、路径、安全文件、声明式环境变量和运行命令等静态兼容检查，不代表外部 API 或第三方服务一定可用。生产发布前仍应按业务分类抽样执行，并重点验证需要网络、账号和外部数据源的资源。

在 CI 或严格门禁中可增加 --fail-on-blocked。只要报告存在 blocked 资源，命令就会以状态码 2 退出。

分阶段导入与发布

先写入数据但不公开专家目录：

uv run python scripts/import_workbuddy_catalog.py \
  /absolute/path/to/workbuddyskills-main \
  --apply \
  --admin-user-id <admin-user-id> \
  --distribution-policy shareable \
  --report /tmp/workbuddy-import.json

确认导入报告中的 apply.errors 为空后，再执行发布：

uv run python scripts/import_workbuddy_catalog.py \
  /absolute/path/to/workbuddyskills-main \
  --apply \
  --publish \
  --admin-user-id <admin-user-id> \
  --distribution-policy shareable \
  --report /tmp/workbuddy-publish.json

导入期间每处理 10 条资源会输出一次 Skills 或专家进度，并显示新增、更新、未变化和失败数量；单条失败会立即输出。按 Ctrl+C 中断时会显示已完成数量，已经提交的数据会保留，之后可直接重新执行相同命令。

导入默认使用 4 个工作线程。Skills 会先并发完成，随后再并发导入依赖它们的专家。可通过 --workers 1 切回串行模式，或在数据库和对象存储资源充足时提高到最多 16 个线程，例如：

uv run python scripts/import_workbuddy_catalog.py \
  /absolute/path/to/workbuddyskills-main \
  --apply \
  --admin-user-id <admin-user-id> \
  --distribution-policy shareable \
  --workers 8

建议先使用默认值。继续增加线程数不一定能提升重复导入速度，并可能提高数据库和对象存储压力。

若授权不允许再分发，将策略改为 restricted。导入操作按来源标识和内容哈希保持幂等，可使用同一数据包安全重试；导入被中断后，重新执行相同命令会更新已有记录并继续处理，不会创建重复资源。

下架与回退

下架本数据包中的专家模板：

uv run python scripts/import_workbuddy_catalog.py \
  /absolute/path/to/workbuddyskills-main \
  --apply \
  --unpublish \
  --admin-user-id <admin-user-id>

下架只按来源标识关闭专家目录入口，不访问对象存储、不更新 Skill 或分发策略，也不删除模板或用户已经安装的专家。已安装专家继续使用安装时冻结的指令、依赖和内容哈希；如果依赖缺失、被停用或内容漂移，运行前校验会阻断执行并返回明确原因。

如需回退数据库迁移，应先确认不存在专家模板、模板关联和已安装来源引用，再按常规迁移流程执行 uv run alembic downgrade -1。生产环境不要直接删除目录表或系统 Skills。

更新规则

重新导入新版数据包会更新目录模板，但不会静默升级用户已经安装的专家。
专家安装会在一个事务内自动安装或启用所需 Skills，并保存不可变依赖快照。
专家专用依赖未安装时不会进入普通技能目录；随专家安装后可在“已安装”中查看。
启用中的目录专家会保护其依赖 Skills，防止被停用、卸载或删除。
修改已安装专家的能力配置、重新启用专家或升级其依赖 Skill 时会重新校验冻结依赖，避免保存后才在执行阶段失败。
独立 Skills 使用标准 SKILL.md 目录格式，沿用 Poco 现有 Skill 安装与执行链路。
独立 Skill 的运行目录名以来源目录为准，不直接采用可重复的展示名称；专家私有依赖会追加内容哈希，避免不同来源在工作区发生目录冲突。
独立 Skill 优先使用数据包根目录 CATALOG.md 中的真实分类；来源元数据中的标签会被规范化，缺少标签时使用分类名称作为回退标签。
Skill 没有本地图标时使用分类对应的 Poco 内置语义图标，来源中的远程图标地址只保留在审计元数据中，不作为前端热链。
专家头像和数据包内的本地 Skill 图标存储在对象存储中，前端通过短期签名 URL 展示。
技能和专家页面的分类筛选项均来自当前用户可见的数据库记录，不依赖前端硬编码分类。

一阶段验收清单

审计报告数量与来源包一致，且所有 blocked 项都有原因；
重复执行 --apply 不产生重复 Skill、模板或关联；
独立 Skills 均具有真实分类、展示标签和可用图标；
只有 ready 或可完成配置的专家出现在办公场景专家目录；
安装专家后，对应专家出现在“我的专家”，依赖 Skills 已启用；
缺少环境变量时，详情页阻止安装并引导到环境变量页面；
下架目录后，未安装用户无法继续发现模板，已安装专家不被破坏；
桌面端、标准移动端和更窄移动端均无横向溢出，详情弹窗可完整滚动和操作。

WorkBuddy 专家与 Skills 目录导入

On this page