9 月 2 日，腾讯 WorkBuddy 开放平台（open.WorkBuddy.cn）正式上线：国内首个同时打通硬件、应用、开发者三层生态的 AI Agent 平台。首批引入超 100 家生态伙伴，Skill（技能）、Expert（专家）、Connector（连接器）三大能力向开发者开放。
如果你有现成的 API 或 MCP 服务，正打算接入 Connector 能力，这篇文章回答一个问题：规范文档里最容易被忽略、一旦出错会导致连接器被拒的坑，具体是什么样的。三个坑全部来自接入真实产品（JoyRead English）时手工打包的踩坑记录，日期就是这两天。
坑一：minWorkbuddyVersion 算错——多特性要取最高版本号
WorkBuddy 连接器配置里，不同字段/能力有各自的最低支持版本。比如某个连接器同时用 auth_mode: token（要求客户端版本 ≥4.23.0）和 examples_zh/en 双语示例字段（要求 ≥4.24.0）。
规范规则：minWorkbuddyVersion 取所用全部特性里的最高版本号。手工打包容易犯的错：只想起第一个用到的特性，写了 4.23.0，漏掉后面追加的 4.24.0 特性。结果：版本号低于 4.24.0 的客户端会拉到一份声称兼容、实际不兼容的配置。
这个错误不会在你自己测试时暴露（你的客户端版本通常是最新的），只会在低版本用户那里出问题——排查成本高，因为"配置本身没写错内容"，只是版本声明撒了个不自知的小谎。
坑二：默认 description 字段的语言——官方模板约定英文，中文团队最容易顺手写反
WorkBuddy 的展示回退链是 description_zh > description_en > description——也就是说，description 这个默认字段，官方模板的约定是填英文，中文版本走专门的 description_zh。
对中文开发团队来说，这个约定反直觉：顺手把主字段填成中文，理由是"反正是给中文用户看的"。结果：客户端语言环境命中回退链末端（没有对应语言的 description_zh/description_en）时，展示出来的是一段本该是英文却混进中文的内容，或者顺序整体错位。
这类问题不会报错，只会"看起来有点奇怪"——审核人工看一眼多半能发现，这恰好说明它是自动化流程里最容易被放过的类型。
坑三：SKILL.md frontmatter 缺字段——按 Claude 的习惯写，会被 WorkBuddy 拒
熟悉 Claude Skill 规范的开发者，会习惯 SKILL.md 的 frontmatter 只写 name + description 两个字段。WorkBuddy 的要求更严格：display_name×2、description×3，再加 category（必须落在白名单内）、version、author。
×2、×3 不是笔误——WorkBuddy 要求同一语义的字段按不同语言/用途各写多份（例如 display_name 和 display_name_en、description/description_zh/description_en 这类组合）。按 Claude 生态的经验直接迁移过来，大概率缺字段被拒。
三个坑的共同点
三个坑没有一个是"逻辑写错了"，全部是规范里隐性的约束条件：版本号取多特性最高值、默认字段语言约定、frontmatter 字段数量比想象中多。规范文档写清楚了这些规则，但规则分散在 3000 多字的文档不同段落里，人工打包靠"记住所有细节"本身是一件反人类的事。
现在能做什么
上面三个坑，我们做成了永久的回归测试用例——不是它们特别难，而是它们特别容易被忽略。基于这些真实经验，我们做了 Connector Studio 连接器工坊：粘贴 MCP 端点地址，工具自动探测服务能力（initialize/tools/list/resources/list/prompts/list，只读不写，零副作用），9 步向导起草配置，14 条规则实时校验（含上面三个坑对应的检查项），产出可直接提交审核的 zip 包。
不要求提供源码——远程 MCP 服务本身自描述，工具靠标准协议方法完成探测，不需要读你的代码。探测过程只调用标准 JSON-RPC 方法，从不调用任何工具，不对被探测的服务产生任何副作用。
工具免费，无账号体系，草稿只存浏览器本地（JSON 导入导出）。官网：connector.smartbid.site/
写在最后
WorkBuddy 开放平台上线首日就有 100+ 生态伙伴入场，Connector 能力预计成为大量第三方开发者接入的第一站。规范本身没有问题，问题是"规范细节太多，人工核对成本太高"——这正是工具该出场的场景：机械的、规则明确的核对工作交给工具，你的精力留给真正需要判断的部分（服务设计、鉴权逻辑、错误处理）。
作者：Connector Studio 连接器工坊团队（智多心教育） 本文技术细节以撰写时（2026 年 9 月）验证过的 WorkBuddy 连接器规范版本为准，规范后续可能演进，请以官方文档为最终依据。
原始 Markdown（正文，不含元数据注释）
