连接器

选择接入方式

WorkBuddy 支持两种连接器接入方式：

方案	适用场景	说明
MCP + Skill（推荐）	已有 API 服务，或可以开发 MCP Server	基于 MCP 协议暴露工具；远程服务优先采用 HTTPS 的 SSE 或 streamableHttp
CLI + Skill	已有成熟的命令行工具	WorkBuddy 负责安装和调度 CLI；CLI 自行管理登录态和凭证

如果服务可以通过网络 API 提供能力，优先选择 MCP + Skill；只有在已有稳定、跨平台 CLI 的情况下，才选择 CLI + Skill。

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 秒内响应；
涉及用户数据时必须提供认证鉴权，并遵循最小权限原则；
一个连接器只配置一个 MCP Server。

开发资源：

mcp.json

远程 MCP 示例：

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

stdio MCP 示例：

{
  "mcpServers": {
    "your-service": {
      "command": "npx",
      "args": ["your-mcp-package"],
      "runtime": {
        "type": "node",
        "version": "20"
      }
    }
  }
}

常用字段：

字段	必填条件	说明
mcpServers	必填	顶层配置；仅配置一个 Server
type	远程服务必填	sse、streamableHttp 或 stdio
url	SSE/streamableHttp 必填	生产环境必须使用 HTTPS
command	stdio 必填	启动命令，如 npx、uvx、node
args	可选	启动参数数组
headers / env	可选	支持 `${VAR_NAME}` 变量引用，不得写入真实凭证
timeout	可选	连接超时，默认 30000 毫秒
runtime	可选	stdio 所需运行时声明，目前支持 Node.js
disabledTools	可选	不向 AI 暴露的工具列表

CLI + Skill 接入

基础结构

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

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"
}

常用字段：

字段	必填	说明
init.{platform}	是	各平台安装命令，平台名为 darwin、linux、win32
auth	按需	登录命令；支持单步或多步认证
unAuth.{platform}	有认证时必填	登出或清理授权命令
status.{platform}	有认证时必填	无副作用的认证状态检查命令
statusMatch / statusMatchJson	二选一	判断已登录状态的文本正则或 JSON 条件
authUrlDomain	浏览器授权时建议	限定 WorkBuddy 可提取并打开的认证域名
env	可选	向命令注入固定环境变量，可使用 `$HOME` 或 `${HOME}`
runtime	依赖运行时时建议	声明 Node.js 或 Python 运行时及版本
versionCheck	可选	检查 CLI 最低版本，版本过低时重新执行安装

对于浏览器授权、多步认证或 Device Flow，需确保认证命令在 WorkBuddy 中可以稳定完成，并验证重启后 status 仍能正确识别登录态。

Connector 元信息

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 / name_en	是	默认名称和英文名称；可补充 name_zh
description / description_zh / description_en	是	简明说明核心能力和适用场景
source	是	全局唯一标识，只能使用小写字母、数字和连字符
type	可选	mcp（默认）、cli 或 skill-only；CLI 方案必须设为 cli
version	建议	语义化版本号，每次更新递增
examples_zh / examples_en	是	中英文使用示例，建议各 2～5 条
minWorkbuddyVersion	使用新字段时必填	连接器要求的最低 WorkBuddy 版本
auth_mode	MCP 按需	省略、server-side、gateway 或 token

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

Skill 文件

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

Skill 的目录和 SKILL.md 格式参见本页「开发—技能」。编写时重点说明：

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

认证与凭证

场景	接入方式
MCP Server 自带 OAuth 或无需认证	`auth_mode` 省略，按标准 MCP 流程连接
WorkBuddy 云端托管 OAuth	使用 server-side 或 gateway，接入前与 WorkBuddy 团队确认
用户自行填写 Access Token / API Key	使用 `auth_mode: "token"`，并提供 token-schema.json 描述表单
CLI 登录	通过 cli.json 的 auth、status、unAuth 管理，凭证由 CLI 自行安全存储

安全要求：

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

图标规范

项目	要求
格式	SVG（推荐）、PNG 或 JPG
文件名	icon.svg、icon.png 或 icon.jpg
尺寸	PNG/JPG 建议 64×64 px
背景	建议透明
风格	简洁清晰，小尺寸下可辨识

提交前检查

已选择 MCP 或 CLI 接入方案，目录结构符合规范；
source 使用 kebab-case 且保持全局唯一；
连接器名称、说明和中英文示例填写完整；
MCP 仅配置一个 Server，远程地址使用 HTTPS；
或 CLI 已验证安装、认证、状态检查、登出和跨平台行为；
Skill 能准确指导 AI 调用全部核心能力；
未在任何文件中写入真实凭证；
图标清晰可辨，版本号和最低 WorkBuddy 版本声明正确；
已覆盖超时、授权失效、参数错误等常见异常。