WorkBuddy / CodeBuddy

Why this agent

WorkBuddy(中国大陆品牌)/ CodeBuddy(国际品牌)是腾讯出品的 AI 编程助手 —— 同一产品两个品牌,以桌面应用 + VS Code 扩展两种形态分发。原生支持自定义 OpenAI 兼容模型(见 awesome-deepseek-agent 指南) 和 MCP 服务,通过 codebuddy mcp CLI 或配置文件管理。

CodeBuddy 是闭源产品 —— 腾讯没有公开 product 仓库。本页 MCP schema 是从第三方适配器逆推出来的 (iOfficeAI/AionCore、 Chat2AnyLLM/code-assistant-manager、 git-men/agentstudio、 iOfficeAI/AionUi), 四份独立实现的文件路径 + CLI 语法完全一致。

Prerequisites

WorkBuddy / CodeBuddy 已安装并登录。
至少打开过一次项目文件夹,让 app 创建 .codebuddy/ 目录。
codebuddy CLI 在 $PATH 上(随桌面版安装一起带)。
espctl 已安装在磁盘上某个稳定位置。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

方式 A —— CLI(推荐;让 CodeBuddy 自己挑 scope):

codebuddy mcp add -s user espctl /path/to/espctl -- mcp serve \
  -e CONTROL_BASE_URL=https://esphome.cloud \
  -e MCP_AUTH_SECRET=your-access-key

scope:user(全局)、local(当前目录)、project(项目根)。立即生效,不用重启。

方式 B —— 直接改文件 ~/.codebuddy/mcp.json(Windows: C:\Users\<username>\.codebuddy\mcp.json):

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

保存成 UTF-8 不带 BOM(跟 models.json 一样 —— 某些桌面版读不了带 BOM 的 JSON)。

替换:

/path/to/espctl —— 你电脑上 espctl 的完整路径。
CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

或者 —— 拿到预填好的代码片段:

读取 install://workbuddy 资源。

First-run verification

在 WorkBuddy / CodeBuddy 聊天里:

你有哪些 espctl 工具?

预期:列出约 40 个 espctl 工具。MCP 面板(CLI:codebuddy mcp list) 里 espctl 应该显示 Connected。

Troubleshooting

codebuddy: command not found —— 桌面版没把 CLI 加到 $PATH。 macOS 上 CLI 在 .app bundle 里;Windows 上在 %LOCALAPPDATA%\CodeBuddy\bin\。要么自己加 $PATH,要么用方式 B 改文件。
mcp.json 解析错 —— 大概率是 BOM。另存为 UTF-8 不带 BOM。 (跟 models.json 同一个坑。)
工具列出来了但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
想用 HTTP 传输? codebuddy mcp add-json -s user espctl '{"url":"https://esphome.cloud/mcp/esp-idf","transportType":"http", "headers":{"Authorization":"Bearer your-access-key"}}'。
想删掉? codebuddy mcp remove -s user espctl(user 找不到时试 local / project scope)。

Tested as-of 2026-05-19

WorkBuddy / CodeBuddy 特有注意事项

WorkBuddy 和 CodeBuddy 是同一个产品两个品牌 —— 大陆叫 WorkBuddy,国际叫 CodeBuddy。配置路径都用 .codebuddy,与品牌无关。
models.json 文档说 ${DEEPSEEK_API_KEY} 环境变量替换语法可用; mcp.json 的 env: 块里是否同样支持没文档化 —— 如果遇到 ${...} 字面显示问题,直接把值粘进去。
三 scope 模型(user / local / project)允许把 MCP 服务紧紧绑到一个仓库 —— 用 project scope 把本套 MCP 只暴露给 ESP-IDF 项目就挺合适。

Keyboard shortcuts

ESP-IDF MCP 用户手册