WorkBuddy 数据导入

导入范围

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

skills/ 下的独立 Skills；
experts/ 中 expertType=agent 的单专家，以及专家引用的 Skills。
experts/ 中 expertType=team 的专家团、主控与成员提示词，以及成员引用的 Skills。

专家团会转换为 Poco 的不可变团队快照，运行时由 Agent 定义完成主控调度。团队声明的 Connector 会按连接器键映射到当前系统中已发布的定义，并在用户安装团队时绑定该用户唯一或默认的连接器账号。无法映射的 Connector、WorkBuddy 专属 Hooks、内嵌 MCP 或平台命令会将资源标记为 blocked，不会发布到目录。

WorkBuddy 目录只作为导入来源，不直接成为运行时格式。导入器会把团队转换为 Poco 当前支持的 V1 团队协议，并与后台手动创建的团队共用同一套校验、规范化和内容摘要逻辑。V1 固定使用主控协调模式；无法识别的协议版本、编排模式或执行字段会在调度前被拒绝，避免被静默忽略。

团队定义、用户安装配置和执行时解析结果彼此分离。不可变团队快照保存成员及能力声明，用户安装配置保存其 Skill 映射和 Connector 账号绑定。Executor Manager 在每次执行前解析能力引用，Executor 再统一转换为 Claude Agent SDK 的 Agent 定义。重新绑定 Connector 不会改变团队定义，也不会丢失安装时的 Skill 映射。

审计会递归识别结构化的环境变量声明，并检查运行时命令和本地配置要求。当前 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/app/poco-agent/workbuddyskills-main
export WORKBUDDY_REPORT_DIR=/opt/app/poco-agent/import-reports
export WORKBUDDY_ADMIN_USER_ID=<管理员用户ID>
export WORKBUDDY_DISTRIBUTION_POLICY=shareable

创建持久目录并设置权限

sudo mkdir -p /opt/app/poco-agent/import-reports
sudo chown 1000:1000 /opt/app/poco-agent/import-reports
sudo chmod 755 /opt/app/poco-agent/import-reports

确认数据目录存在

ls -ld \
  "$WORKBUDDY_DIR" \
  "$WORKBUDDY_DIR/skills" \
  "$WORKBUDDY_DIR/experts"

验证容器访问权限

docker compose run --rm --no-deps \
  -v "$WORKBUDDY_DIR:/imports/workbuddy:ro" \
  -v "$WORKBUDDY_REPORT_DIR:/reports" \
  backend \
  sh -c 'test -r /imports/workbuddy &&
         test -x /imports/workbuddy &&
         test -w /reports &&
         echo "目录权限正常"'

执行数据审计

# 不写入数据但会生成报告
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"

审计并写入

# 再将兼容资源写入数据库和对象存储，但不会发布专家。
REPORT_NAME="workbuddy-import-$(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 \
  --apply \
  --admin-user-id "$WORKBUDDY_ADMIN_USER_ID" \
  --distribution-policy "$WORKBUDDY_DISTRIBUTION_POLICY" \
  --workers 4 \
  --report "/reports/$REPORT_NAME"

下架专家模板

REPORT_NAME="workbuddy-unpublish-$(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 \
  --apply \
  --unpublish \
  --admin-user-id "$WORKBUDDY_ADMIN_USER_ID" \
  --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.agent_teams：可转换的专家团数量；
summary.excluded_teams：结构不完整、无法形成迁移计划的团队数量；
blocked_skill_items、blocked_expert_items、blocked_team_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 或分发策略，也不删除模板或用户已经安装的专家。已安装专家继续使用安装时冻结的指令、依赖和内容哈希；如果依赖缺失、被停用或内容漂移，运行前校验会阻断执行并返回明确原因。

如需回退数据库迁移，应先确认不存在专家模板、模板关联和已安装来源引用，再核对当前 revision、依赖链和明确的 downgrade 目标执行迁移；不能用 -1 假设最近迁移就是目录导入功能。生产环境不要直接删除目录表或系统 Skills。

更新规则

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

验收清单

审计报告数量与来源包一致，且所有 blocked 项都有原因；
重复执行 --apply 不产生重复 Skill、模板、团队版本或关联；
团队主控不能调用成员专属能力，成员不能继续派生 Agent 或直接互发消息；
需要 Connector 的团队在安装时能绑定当前用户的默认或唯一账号，缺少账号时阻断安装；
独立 Skills 均具有真实分类、展示标签和可用图标；
只有 ready 或可完成配置的专家出现在办公模式专家目录；
安装专家后，对应专家出现在“我的专家”，依赖 Skills 已启用；
缺少环境变量时，详情页阻止安装并引导到环境变量页面；
下架目录后，未安装用户无法继续发现模板，已安装专家不被破坏；
桌面端、标准移动端和更窄移动端均无横向溢出，详情弹窗可完整滚动和操作。

On this page