连接器

选择接入方式

连接器是 WorkBuddy 的能力扩展接口。用户安装连接器后，即可通过自然语言调用第三方服务。WorkBuddy 支持两种接入方式：

如果服务可以通过网络 API 提供能力，优先选择 MCP + Skill；只有在已有稳定、跨平台 CLI 的情况下，才选择 CLI + Skill。一个连接器只能选择一种方案，二者不可混用。

若服务要求用户自行填写 Access Token 或 API Key 等长期凭证，而非走 OAuth，请使用 MCP 方案的用户自填 Token 模式，详见下文「用户自填 Token 模式」。

MCP + Skill 接入

基础结构

your-connector/
├── connector-meta.json          # 连接器元信息（必须）
├── mcp.json                     # MCP Server 连接配置（必须）
├── icon.svg                     # 市场图标（必须）
└── skills/                      # AI 使用说明（可选）
    └── {skill-name}/
        └── SKILL.md

MCP Server 要求

• 遵循 MCP 稳定协议版本；
• 远程服务使用 HTTPS，支持 SSE 或 streamableHttp；本地进程可使用 stdio；
• 工具名称、描述、参数和返回值应清晰、稳定，便于 AI 正确选择和调用；
• 返回可读错误信息，并设置合理超时，单次请求建议在 30 秒内响应；
• 服务保持稳定可达，建议可用性不低于 99.9%；
• 涉及用户数据时必须提供认证鉴权，并遵循最小权限原则；
• 一个连接器只配置一个 MCP Server。

开发资源：

• MCP 协议规范：https://modelcontextprotocol.io/
• Python SDK：https://github.com/modelcontextprotocol/python-sdk
• TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk

mcp.json

远程 MCP 示例：

{
  "mcpServers": {
    "your-service": {
      "type": "streamableHttp",
      "url": "https://mcptokenSchema 字段.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      },
      "timeout": 30000
    }
  }
}

stdio MCP 示例：

{
  "mcpServers": {
    "your-service": {
      "type": "stdio",
      "command": "npx",
      "args": ["your-mcp-package"],
      "runtime": {
        "type": "node",
        "version": "20"
      },
      "npmRegistry": "https://registry.npmmirror.com"
    }
  }
}

常用字段：

「最低版本」标注该字段自哪个 WorkBuddy 版本起生效，标「基础」表示长期支持。使用带版本号的字段时，须在 connector-meta.json 中声明对应的 minWorkbuddyVersion。

CLI + Skill 接入

基础结构

your-cli-connector/
├── connector-meta.json          # 连接器元信息（必须，type 为 cli）
├── cli.json                     # CLI 安装与认证配置（必须）
├── icon.svg                     # 市场图标（必须）
└── skills/
    └── {skill-name}/
        └── SKILL.md             # CLI 使用说明（强烈推荐）

CLI 工具没有标准的工具描述协议，AI 需要依赖 Skill 了解可用命令和参数，因此本方案强烈推荐提供 Skill 文件。

CLI 开发要求

• 至少支持 macOS 和 Linux，建议同时支持 Windows；
• 提供非交互式安装方式，以及明确的 auth、status、unAuth 命令；
• auth 成功后由 CLI 自行持久化登录态，status 只检查状态且不产生副作用，unAuth 负责撤销或清理登录态；
• 命令应返回明确退出码和可读错误信息，业务结果优先使用 JSON；
• 不要依赖用户机器预装的 Node.js、Python 或全局包；依赖运行时时应在 cli.json 中声明 runtime；
• 凭证与 CLI 安装目录分离，不得把密钥写入安装包、Skill 或配置样例。

cli.json

{
  "runtime": {
    "type": "node",
    "version": "20"
  },
  "init": {
    "darwin": "npm install -g your-cli",
    "linux": "npm install -g your-cli",
    "win32": "npm install -g your-cli"
  },
  "auth": {
    "darwin": "your-cli auth login",
    "linux": "your-cli auth login",
    "win32": "your-cli.cmd auth login"
  },
  "unAuth": {
    "darwin": "your-cli auth logout",
    "linux": "your-cli auth logout",
    "win32": "your-cli.cmd auth logout"
  },
  "status": {
    "darwin": "your-cli auth status",
    "linux": "your-cli auth status",
    "win32": "your-cli.cmd auth status"
  },
  "statusMatch": "Logged in",
  "authUrlDomain": "example.com"
}

常用字段：

运行时托管与安装位置

对于依赖 Node.js 或 Python 的 CLI，建议在 cli.json 中声明 runtime。WorkBuddy 会准备对应运行时并注入命令环境，用户无需预先安装；同时 npm 与 pip 的安装位置和缓存会隔离到 WorkBuddy 管理目录，不会污染用户系统环境。

安装路径由 WorkBuddy 管理，开发者不应在命令中写死绝对路径。凭证与授权文件则完全由 CLI 自行管理：WorkBuddy 只负责调度 auth、status、unAuth，不会迁移或清理 CLI 的凭证文件，因此凭证应与运行时安装目录分离存放。

认证流程与关键约束

用户点击「连接」后，WorkBuddy 依次执行：检查安装（未安装则执行 init）、执行 status 判断登录态；未登录时执行 auth，从命令输出中提取认证 URL 并打开浏览器，随后每 3 秒轮询一次 status，最长等待 5 分钟。

关键约束：WorkBuddy 在提取到认证 URL 后会立即终止 auth 子进程，因此 auth 子进程本身不能作为 OAuth 回调的接收方。可选用以下任一方案：

auth 命令输出要求：

• 在 stdout 或 stderr 中输出完整的 https:// 认证 URL，并在 10 秒内输出；
• URL 前后需有空白字符分隔，不能被引号或尖括号包裹，否则会被截断；
• 不得进入交互式输入等待（执行环境没有 TTY），也不应自行打开浏览器而不输出 URL。

各命令超时与判定规则：

WorkBuddy 重启后会自动执行 status 恢复连接，但不会重新执行 auth，因此 CLI 的登录态必须跨进程重启有效。

连接器元信息

connector-meta.json 用于注册连接器，并在市场中展示名称、描述和使用示例。

{
  "name": "任务管理",
  "name_zh": "任务管理",
  "name_en": "Task Manager",
  "description": "Create and manage tasks in WorkBuddy.",
  "description_zh": "通过自然语言创建、查询和更新任务。",
  "description_en": "Create, query, and update tasks with natural language.",
  "source": "task-manager",
  "type": "mcp",
  "version": "1.0.0",
  "examples_zh": [
    "创建一个明天下午到期的评审任务",
    "列出本周尚未完成的任务"
  ],
  "examples_en": [
    "Create a review task due tomorrow afternoon",
    "List unfinished tasks for this week"
  ]
}

名称应简明、可识别，描述应直接说明用户能完成什么任务，示例应使用用户真实会说的自然语言。

展示优先级：名称为 name_map（命中环境）> name_zh > name_en > name，描述同理回退到 description_zh、description_en、description。

版本兼容性

不同 WorkBuddy 客户端支持的配置字段不同。使用较新字段时必须声明 minWorkbuddyVersion，否则低版本客户端可能拉取到不兼容的配置。若同时使用多个新特性，取其中最高版本作为声明值。

低于所声明版本的客户端：从未启用过该连接器时不展示；已启用或曾连接过则降级置灰并提示升级。

Skill 文件

Skill 用于指导 AI 正确使用连接器。MCP 已提供标准工具描述时可选；CLI 方案强烈推荐提供。

Skill 的目录和 SKILL.md 格式参见本页「开发—技能」。能力较多时可拆分为多个 Skill，每个放置在独立子目录下，WorkBuddy 会全部加载。编写时重点说明：

• 每个 MCP Tool 或 CLI 命令的用途；
• 参数名称、类型、是否必填和默认值；
• 典型调用示例及返回格式；
• 认证前置条件、错误场景和恢复方式；
• 高风险操作需要的确认规则。

认证与凭证

安全要求：

• 不得在 connector-meta.json、mcp.json、cli.json、Skill 或示例中硬编码真实 Token、密钥；
• 仅申请完成业务所需的最小权限；
• 远程 MCP 使用 HTTPS；
• 敏感凭证字段应使用密码类型，日志和错误信息中不得输出完整凭证；
• 授权失效时应返回可识别错误，并引导用户重新连接。

MCP OAuth 流程

当 MCP Server 需要访问用户私有数据并采用 OAuth 时，WorkBuddy 内置的 OAuth 管理器会自动完成客户端侧流程，采用 OAuth 2.1 + PKCE，并以公共客户端身份接入（不持有 client_secret）。开发者只需实现服务端端点。

整体流程：首次请求未携带 Token 返回 401 → 发现元数据 → 动态客户端注册 → 打开浏览器授权 → 校验 state 并交换 Token → 携带 Bearer Token 正常调用。

服务端行为要求：

• 必须支持 PKCE（S256），授权码一次性使用且有效期约 10 分钟；
• redirect_uri 需按字符串精确匹配，优先支持 WorkBuddy 私有协议回调 workbuddy://workbuddy/mcp/connector%3A<source>/oauth/callback；
• 若平台仅允许 HTTP/HTTPS 回调，则应允许本机回环地址 http://127.0.0.1:{动态端口}/oauth/callback，WorkBuddy 会在私有协议被拒绝时自动回退一次；
• 动态注册响应除 client_id 外必须回显 redirect_uris，否则后续流程无法继续；
• access_token 建议有效期 1 小时，refresh_token 建议不少于 30 天，过期后 WorkBuddy 会引导用户重新授权；
• 所有 OAuth 服务端端点强制使用 HTTPS，并遵循 OAuth 2.1 标准错误格式。

access_token 过期时，WorkBuddy 会自动使用 refresh_token 续期并重试原请求，此过程对用户透明。

用户自填 Token 模式

当第三方服务不提供 OAuth，仅提供 Personal Access Token、API Key，或需要用户指定私有部署地址时，使用 auth_mode: "token"。WorkBuddy 会弹出表单收集凭证，凭证仅保存在用户本机并在连接时注入，不经过云端，整个过程不打开浏览器。该模式需声明 minWorkbuddyVersion 不低于 4.23.0。

本模式需额外提供 token-schema.json 描述表单字段，并在 mcp.json 中用 ${VAR} 占位引用。占位符名称必须与表单字段的 key 完全一致（区分大小写）：

token-schema.json 示例：

{
  "title": "服务对接配置",
  "title_en": "Service Configuration",
  "description": "连接您的账号以调用服务。凭证仅存储在本机 ~/.workbuddy 目录下。",
  "description_en": "Connect your account. Credentials are stored locally only.",
  "docUrl": "https://example.com/docs/api-token",
  "docLabel": "如何获取 Access Token？",
  "fields": [
    {
      "key": "API_KEY",
      "label": "Access Token",
      "type": "password",
      "required": true,
      "placeholder": "在个人中心 → 开放平台 → API 中生成",
      "description": "用于访问服务 OpenAPI 的个人访问令牌。"
    },
    {
      "key": "API_BASE_URL",
      "label": "API 基础地址",
      "label_en": "API Base URL",
      "type": "text",
      "required": true,
      "defaultValue": "https://api.example.com",
      "description": "私有部署可改为内网地址。"
    }
  ]
}

多语言文案通过新增 _en 后缀的平行字段实现，例如 title_en、label_en。原字段必须保持字符串类型，不可改为对象，否则低版本客户端将无法渲染。

同一服务若需同时提供 OAuth 与 Token 两种方式，必须使用两个不同的 source 分别提交，作为两个独立的连接器。

图标规范

提交前检查

• 已选择 MCP 或 CLI 接入方案，目录结构符合规范；
• source 使用 kebab-case 且保持全局唯一；
• 连接器名称、说明和中英文示例填写完整；
• MCP 仅配置一个 Server，远程地址使用 HTTPS；
• 或 CLI 已验证安装、认证、状态检查、登出和跨平台行为；
• CLI 方案已验证登录态跨重启有效，且 unAuth 能正确清理授权；
• 涉及 OAuth 时已实现元数据发现、动态注册与 PKCE 校验，并接受约定的回调地址；
• 使用自填 Token 模式时，${VAR} 占位符与表单字段 key 一一对应，敏感字段为 password 类型；
• Skill 能准确指导 AI 调用全部核心能力；
• 未在任何文件中写入真实凭证；
• 图标清晰可辨，版本号和最低 WorkBuddy 版本声明正确；
• 已覆盖超时、授权失效、参数错误等常见异常。

准备完成后，将连接器目录打包并提交 WorkBuddy 团队审核。审核通过后，连接器将进入连接器市场；后续更新重新提交审核即可，通常在 10～15 分钟内同步生效。