全部教程
本页目录
它是什么,以及它的边界#
WorkBuddy 是腾讯的桌面 AI 助手。和纯聊天框比,它的价值在三件事:
- 能读你本地的文件和文档,不是只聊空气;
- 有技能(Skills)和 MCP,能接外部工具;
- 有工作区,多个任务的上下文和文件不互相打架。
它不适合什么:不适合当服务器常驻、不适合跑长时间定时任务、不适合当 API 网关。那些交给 DSH 或 Hermes。
这篇的写法
菜单名、字段名、配置文件路径都按 5.6.2 的实际界面核对过。版本更新后可能有微调,但关键词不会变:设置 → 模型 → 添加模型。
第一步:确认版本和状态#
打开 WorkBuddy,左下角设置齿轮 → 关于,确认版本。低于 5.6 的,菜单可能有差异,先升级。
然后做一件事:先不接任何东西,用内置模型聊一句。这一步是为了确认「软件本身是好的」。如果内置模型都不能回话,问题在网络或登录,不在你的 key。
验收:内置模型能正常回复一句话。
第二步:加一个自定义模型#
路径是固定的:
设置 → 模型(Models)→ 自定义模型 → 添加模型弹出的表单里只有四个必填项:
| 字段 | 填什么 | 说明 |
|---|---|---|
| Provider | 自定义 / Custom | 表示用 OpenAI 兼容接口 |
| 模型名称 | 你的模型 ID | 从诸葛的模型广场复制,不是产品名 |
| Endpoint | https://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,最接近真实使用。
测试连接报错对照#
| 提示 | 真实原因 |
|---|---|
UNAUTHORIZED | key 无效、复制时带了空格或全角字符 |
NOT_FOUND | Endpoint 路径错,或模型名不存在 |
RATE_LIMITED | 限流或余额不足 |
UNREACHABLE | 网络到不了,检查代理/DNS |
INVALID_RESPONSE | 地址指向了一个不返回 OpenAI 格式的服务 |
验收:测试连接显示成功,模型出现在对话框顶部的模型选择器里(在「自定义」分组下)。
它存在哪#
自定义模型会写进本机文件:
~/.codebuddy/models.json这个文件里有你的 key 明文。所以:不要把它同步到网盘、不要随手发给别人、不要在截图里露出。要备份就放进加密盘。
第三步:高级项,只在需要时动#
展开「高级设置」才看得到,默认值一般够用。三个值得知道的:
| 项 | 什么时候改 |
|---|---|
| 最大输入 / 输出 Tokens | 模型报「上下文超限」时,按厂商文档填小一点 |
| 推理强度(reasoning effort) | 用了推理模型才出现;日常对话选低,复杂任务再拉高 |
| 能力开关(工具调用 / 图片输入) | 模型实际不支持却开了,会报莫名其妙的错。不确定就全关,跑通再逐个开 |
工具调用(Tool Calling) 这个开关值得单独说:不开,它就不能用 MCP 和技能;开了但模型不支持,会一直失败。判断方法很简单——先在对话里问一句需要联网或读文件的话,能正常调用就是支持。
第四步:把技能用起来#
技能(Skills)是 WorkBuddy 里最被低估的部分。位置在设置 → 技能,分「已安装 / 技能市场 / 插件」。
三个实用动作:
- 装一个官方技能先试水。技能市场里挑安装量高的,别一上来装十个。
- 自己写一个。技能就是一个带
SKILL.md的文件夹,SKILL.md头部写 YAML(名称 + 描述),正文写「什么时候用、怎么做、验收标准」。 - 控制自动触发。每个技能都能开关「自动触发」。全开会互相抢活,建议只留两三个常用的。
---
name: weekly-report
description: 把一周的零散记录整理成周报,输出 Markdown。
---
## 什么时候用
用户说「写周报」「整理这周」时。
## 步骤
1. 找到工作区里的记录文件
2. 按「做完的 / 卡住的 / 下周要做的」归类
3. 输出三段,每段不超过 5 条
## 验收
- 没有编造不存在的事项
- 每条都有来源验收:在对话里输入 / 能看到技能列表,或者直接说触发词,它开始按技能步骤执行。
技能的安全边界
第三方技能本质是「让 AI 按别人的指令操作你的文件」。装之前看一眼 SKILL.md,尤其注意有没有让你把文件内容发到外部地址的步骤。WorkBuddy 有安装前安全扫描,但它不是万能的。
第五步:MCP,把外部工具接进来#
MCP 是模型和外部服务之间的标准接口。位置:设置 → 连接器 / MCP → 配置 MCP,本质是填一段 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。