接入指南
在 WorkBuddy 中使用数据专家
WorkBuddy 可导入完整单专家包、完整专家团包，也可上传通用技能包。以下步骤按当前公开规范整理，界面名称与位置可能随版本变化，以客户端实际显示为准。
一、导入完整专家包 / 专家团包（推荐）
- 1打开「专家 · 技能 · 连接器」在 WorkBuddy 客户端左侧找到该入口，它同时管理专家、技能与连接器。
- 2导入专家包或专家团包进入「我的专家 / 我的专家团」，点击创建或安装入口，选择下载好的 ZIP 文件。
- 3等待安全校验与自动配置客户端会解析包结构、校验插件清单并自动完成配置，过程中不要关闭窗口。
- 4运行验证问法在对话中使用页面给出的验证问法，确认能力被正确加载、边界被正确声明。
二、导入通用技能包
- 1打开「专家 · 技能 · 连接器」切换到「技能」页签。
- 2点击「添加技能」→「上传技能」选择页面提供的通用技能 ZIP 文件。
- 3等待自动配置完成确认技能出现在技能列表中并被启用。
- 4在对话中启用并验证发送验证问法，检查技能是否被正确触发。
三、失败原因与回退
| 现象 | 可能原因 | 回退方式 |
|---|---|---|
| 找不到 SKILL.md | ZIP 根目录层级错误（多了一层外壳目录） | 改用平台专用兼容包；通用技能包解压后应只有一个根目录，SKILL.md 直接位于根目录内。 |
| YAML 解析失败 | frontmatter 冒号、引号或编码（BOM）问题 | 使用本站提供的 UTF-8 无 BOM 重新打包版本，不自行修改原包后再上传。 |
| 名称冲突 | 已安装同名旧版本 | 先在目标平台完成升级或替换；本站不指导删除任何本地数据。 |
| 安全扫描失败 | 包含可执行脚本或高风险权限声明 | 使用无脚本的 Lite 版本（本站在知识型专家中默认提供无脚本包）。 |
| 专家团只运行成单角色 | 平台不支持团队包导入 | 改用编排型技能包，或按伙伴蓝图手工创建小队并明确降级点。 |
| 深链未唤起 | 客户端未安装、版本过旧或协议未注册 | 使用 ZIP 下载路径；深链能力在取得官方确认前一律关闭。 |
四、安装后请运行一次验证问法
每个专家的详情页与接入向导都会给出一条最小验证问法。期望行为是： 专家自报身份与边界；不在信息不足时直接下结论；能列出正确的 SOP 或团队成员路由。 如果行为与预期不符，请通过问题反馈告诉我们，并附上客户端版本与报错截图描述。
五、包的结构（可自行核对）
每个发行物都按下列结构打包，你可以解压后逐条核对；详情页同时提供文件名、体积与 SHA-256，下载后可自行比对：
- 插件清单位于包根目录的
.codebuddy-plugin/plugin.json，一个包只有一个清单文件； - 清单中的
name / version / description均为字符串，agents指向真实存在的agents/*.md； - 每个
agents/*.md的 frontmatter 都带name（客户端据此确定 agent 名）； - 每个技能目录下的
SKILL.mdfrontmatter 同时包含name与description， 这正是客户端校验的两个必需字段； - 头像文件按清单中的相对路径真实存在，且包内不含任何可执行脚本。
- 专家团包额外带
expertType: team与成员列表，客户端据此按多 Agent 结构装载。
已观察到的客户端版本：5.6.2。 界面名称与位置可能随版本变化，以客户端实际显示为准。