它是什么,以及它的边界#

WorkBuddy 是腾讯的桌面 AI 助手。和纯聊天框比,它的价值在三件事:

  1. 能读你本地的文件和文档,不是只聊空气;
  2. 有技能(Skills)和 MCP,能接外部工具;
  3. 有工作区,多个任务的上下文和文件不互相打架。

它不适合什么:不适合当服务器常驻、不适合跑长时间定时任务、不适合当 API 网关。那些交给 DSH 或 Hermes。

这篇的写法

菜单名、字段名、配置文件路径都按 5.6.2 的实际界面核对过。版本更新后可能有微调,但关键词不会变:设置 → 模型 → 添加模型。

第一步:确认版本和状态#

打开 WorkBuddy,左下角设置齿轮 → 关于,确认版本。低于 5.6 的,菜单可能有差异,先升级。

然后做一件事:先不接任何东西,用内置模型聊一句。这一步是为了确认「软件本身是好的」。如果内置模型都不能回话,问题在网络或登录,不在你的 key。

验收:内置模型能正常回复一句话。

第二步:加一个自定义模型#

路径是固定的:

text
设置 → 模型(Models)→ 自定义模型 → 添加模型

弹出的表单里只有四个必填项:

字段填什么说明
Provider自定义 / Custom表示用 OpenAI 兼容接口
模型名称你的模型 ID从诸葛的模型广场复制,不是产品名
Endpointhttps://zhugeai.cn/v1/chat/completions必须以 /chat/completions 结尾
API Key你的 key只存在本机

最容易错的两个地方

一、Endpoint 少写 /chat/completions。 WorkBuddy 的校验会直接拦下来,提示「Must end with /chat/completions」。它不会帮你自动补。 二、模型名称填成产品名。 「DeepSeek」是产品名,「你在模型广场看到的那串 ID」才是模型名。填错会报 NOT_FOUND。

填完点「测试连接」。这一步是 WorkBuddy 直接打你的 Endpoint,最接近真实使用。

测试连接报错对照#

提示真实原因
UNAUTHORIZEDkey 无效、复制时带了空格或全角字符
NOT_FOUNDEndpoint 路径错,或模型名不存在
RATE_LIMITED限流或余额不足
UNREACHABLE网络到不了,检查代理/DNS
INVALID_RESPONSE地址指向了一个不返回 OpenAI 格式的服务

验收:测试连接显示成功,模型出现在对话框顶部的模型选择器里(在「自定义」分组下)。

它存在哪#

自定义模型会写进本机文件:

text
~/.codebuddy/models.json

这个文件里有你的 key 明文。所以:不要把它同步到网盘、不要随手发给别人、不要在截图里露出。要备份就放进加密盘。

第三步:高级项,只在需要时动#

展开「高级设置」才看得到,默认值一般够用。三个值得知道的:

项什么时候改
最大输入 / 输出 Tokens模型报「上下文超限」时,按厂商文档填小一点
推理强度(reasoning effort)用了推理模型才出现;日常对话选低,复杂任务再拉高
能力开关(工具调用 / 图片输入)模型实际不支持却开了,会报莫名其妙的错。不确定就全关,跑通再逐个开

工具调用(Tool Calling) 这个开关值得单独说:不开,它就不能用 MCP 和技能;开了但模型不支持,会一直失败。判断方法很简单——先在对话里问一句需要联网或读文件的话,能正常调用就是支持。

第四步:把技能用起来#

技能(Skills)是 WorkBuddy 里最被低估的部分。位置在设置 → 技能,分「已安装 / 技能市场 / 插件」。

三个实用动作:

  1. 装一个官方技能先试水。技能市场里挑安装量高的,别一上来装十个。
  2. 自己写一个。技能就是一个带 SKILL.md 的文件夹,SKILL.md 头部写 YAML(名称 + 描述),正文写「什么时候用、怎么做、验收标准」。
  3. 控制自动触发。每个技能都能开关「自动触发」。全开会互相抢活,建议只留两三个常用的。
markdown
---
name: weekly-report
description: 把一周的零散记录整理成周报,输出 Markdown。
---

## 什么时候用
用户说「写周报」「整理这周」时。

## 步骤
1. 找到工作区里的记录文件
2. 按「做完的 / 卡住的 / 下周要做的」归类
3. 输出三段,每段不超过 5 条

## 验收
- 没有编造不存在的事项
- 每条都有来源

验收:在对话里输入 / 能看到技能列表,或者直接说触发词,它开始按技能步骤执行。

技能的安全边界

第三方技能本质是「让 AI 按别人的指令操作你的文件」。装之前看一眼 SKILL.md,尤其注意有没有让你把文件内容发到外部地址的步骤。WorkBuddy 有安装前安全扫描,但它不是万能的。

第五步:MCP,把外部工具接进来#

MCP 是模型和外部服务之间的标准接口。位置:设置 → 连接器 / MCP → 配置 MCP,本质是填一段 JSON:

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你/Documents/notes"]
    }
  }
}

三个经验:

  • 一次只加一个,通了再加下一个。一次加五个,报错时你不知道是谁的错。
  • 路径写绝对路径,别用 ~,有些实现不展开。
  • 工具数量别贪多。WorkBuddy 自己会提示「启用超过 N 个工具可能影响回复质量」——它说的是真的。

验收:MCP 列表里状态是「已启用」,对话里让它读一下那个目录里的文件,能读出来。

第六步:工作区怎么划#

「保存到工作区」是把一次任务的文件和上下文打包存下来,下次能接着聊。划法建议:

做法好处
一个项目一个工作区上下文不串,AI 不会把 A 项目的资料用到 B 项目
名字带日期或版本周报-2026-10 比「新建工作区 3」强
大文件不要塞进去它会把内容读进上下文,又慢又费 token

什么时候该换工具#

说句实话:WorkBuddy 适合人在电脑前、要处理本地文件的场景。以下三种情况它不合适:

  • 要 7×24 常驻、定时跑:用 Hermes 的 cron 或系统计划任务
  • 要接 QQ/微信当机器人:用 DSH 的 qqbot profile 或 Hermes gateway
  • 要批量调 API 出内容:写脚本,别用 GUI

验收清单#

全部打勾,你就算把 WorkBuddy 配明白了。下一篇是更硬的:DSH。