1. 为什么我要认真写一份 WorkBuddy 实战笔记
WorkBuddy 这个腾讯 AI 工作台刚出来的时候，我其实是抱着"又一个套壳聊天框"的心态去装的。结果用了两周，我把自己日常写脚本、整理资料、跑数据处理的一堆零碎活儿全搬了进去，才发现这东西的定位跟普通对话式 AI 完全不是一回事——它更像是一个能挂载技能、能读写本地文件、能按规则长期干活的 AI Agent 工作台。网上关于它的教程要么只讲怎么点按钮，要么一上来就甩一堆概念，真正把"安装、配置、Skill 编写、避坑"串起来讲透的几乎没有。所以我把这段时间踩过的坑、调过的参数、写废又重写的 Skill 全部整理出来，写成这篇实战指南。
这篇内容适合三类人：第一类是刚听说 WorkBuddy、想搞清楚它和 CodeBuddy 到底啥关系的入门用户；第二类是已经装好但卡在 models.json 配置、Skill 不生效、缓存目录爆盘这些具体问题上的中级用户；第三类是想把 WorkBuddy 当成个人 AI Agent 中台、批量挂载 Skill 来干活的进阶玩家。我会从安装讲到 Skill 开发，再到并发和排查，尽量做到你看完就能照着复现。文中涉及的具体路径和参数，我会说明哪些是官方文档明确的、哪些是我基于常见实践补全的，避免你照抄踩雷。
先说结论性的判断：WorkBuddy 的核心价值不在"聊天"，而在Skill 机制 + 本地文件读写 + 规则持久化这三件事的组合。理解了这一点，后面所有的配置和避坑都会顺理成章。
2. WorkBuddy 到底是什么，和 CodeBuddy 什么关系
2.1 一句话拆解产品定位
WorkBuddy 是腾讯推出的一款 AI 工作台产品，官方把它定位成"AI Agent 工作台"，也就是让 AI 不只是回答问题，而是能真正"下地干活"——读写你本地的文件、调用你配置的模型、执行你写好的 Skill 脚本、按你设定的规则持续处理任务。它和单纯的网页版对话 AI 最大的区别在于：它是一个有本地运行环境、有文件系统权限、有可扩展技能体系的桌面级工具。
我自己的理解是，它把三样东西缝在了一起：一个本地 Agent 运行时、一个 Skill 插件系统、一个模型接入层。模型接入层负责"用哪个大脑"，Skill 系统负责"会哪些手艺"，本地运行时负责"在哪儿干活"。这三层任何一层配错，你都会觉得"这 AI 怎么这么笨"，但其实问题往往不在模型本身。
2.2 WorkBuddy 和 CodeBuddy 的区别，别再搞混
这是被问得最多的问题。简单说，CodeBuddy 更偏向代码场景的 AI 编程助手，围绕写代码、补全、重构、解释代码来设计；WorkBuddy 则是通用工作场景的 AI 工作台，它的野心更大，想覆盖文档处理、资料整理、脚本执行、批量任务等非纯代码的活儿。两者在底层可能共享部分模型能力和 Agent 框架，但面向的使用场景和交互形态不一样。
实际使用中我的感受是：如果你 90% 的时间在写代码，CodeBuddy 更顺手；如果你像我一样，一天里要在写脚本、整理表格、处理文本、查资料之间来回切换，WorkBuddy 的 Skill 机制会让你省很多事。热词里出现的"workbuddy和codebuddy"讨论，本质就是在纠结这个选择。我的建议是别二选一，两个都装，按任务类型切换。
2.3 国际版和国内版的差异要点
WorkBuddy 有国际版和国内版之分，热词里"workbuddy国际版"的搜索量不低。两者最核心的差异通常在可接入的模型来源、账号体系、以及部分 Skill 的可用性上。国内版一般对接国内合规的模型服务，国际版可能支持更多海外模型。这里我不展开具体渠道，只提醒一点：你下载的版本决定了你后面 models.json 能填什么、Skill 生态能用到哪些，所以安装前先想清楚自己的主要使用场景，别装完了才发现模型接不进来。
提示：版本选择没有绝对优劣，关键看你的模型资源和任务类型。选错了版本，后面配置阶段会反复折腾，不如一开始就定好。
3. 安装前的环境准备与版本选择
3.1 系统环境的最低要求
在动手装之前，先把环境盘清楚。根据我的实测和常见实践，WorkBuddy 这类桌面级 AI 工作台对系统的要求主要集中在三块：操作系统版本、可用磁盘空间、以及本地运行时的依赖。
- 操作系统：Windows 建议 Win10 1909 及以上，macOS 建议 12 以上。太老的系统可能在运行时依赖上出问题。
- 磁盘空间：至少预留 5GB 以上。别小看这个数字，模型缓存、Skill 依赖、日志文件加起来涨得很快，我第一周就吃掉了 3GB。
- 内存：建议 16GB 起步。如果你要同时挂多个 Skill 跑批量任务，8GB 会明显卡顿。
这里有个很多人忽略的点：WorkBuddy 的缓存目录默认在系统盘。如果你系统盘本来就紧张，装之前一定要先规划好缓存目录的位置，否则用不了几天 C 盘就红了。这个后面第 5 节会专门讲怎么改。
3.2 安装包获取与安装流程
安装流程本身不复杂，但有几个细节决定了你后面顺不顺。我按实际操作顺序说：
- 从官方渠道获取对应版本的安装包，注意区分国内版和国际版，别下错。
- 安装时如果安装程序允许自定义安装路径，强烈建议装到非系统盘。我装在 D 盘，后面迁移缓存时省了不少事。
- 首次启动会引导你登录账号，这一步按提示走即可。
- 登录后不要急着用，先进入设置检查默认的模型配置和缓存目录。
我第一次装的时候图快，一路默认下一步，结果缓存目录落在 C 盘用户目录下，用了三天 C 盘告急。后来重装才改到 D 盘。所以这一步的耐心是值得的。
3.3 首次启动后的必做检查清单
装完别急着开聊，先做这几项检查，能帮你避开后面 80% 的"莫名其妙不工作"：
| 检查项 | 检查内容 | 不通过的后果 |
|---|---|---|
| 模型配置 | models.json 是否已正确填写 | AI 无响应或报错 |
| 缓存目录 | 是否指向空间充足的盘 | 系统盘爆满、任务中断 |
| 网络连通 | 模型服务是否可正常访问 | 请求超时、反复重试 |
| 权限设置 | 文件读写权限是否开启 | Skill 无法读写本地文件 |
| 版本号 | 是否为最新稳定版 | 部分 Skill 不兼容 |
这张表是我自己每次重装或换机后都会过一遍的，尤其是模型配置和缓存目录这两项，出问题频率最高。
4. models.json 配置：整个工作台的命门
4.1 models.json 到底管什么
models.json 是 WorkBuddy 的模型接入配置文件，你可以把它理解成工作台的"大脑接线图"。它告诉 WorkBuddy：有哪些模型可用、每个模型怎么调用、默认用哪个、不同任务该路由到哪个模型。这个文件配错，整个工作台就是哑巴。
它的典型结构一般包含模型名称、接口地址、密钥字段、以及一些调用参数。不同版本字段名可能略有差异，但核心逻辑一致。我下面给的是一个基于常见实践的结构示例，具体字段请以你所用版本的官方说明为准：
{ "models": [ { "name": "default-chat", "provider": "your-provider", "endpoint": "https://your-endpoint/v1", "apiKey": "YOUR_KEY_HERE", "model": "your-model-name", "maxTokens": 4096, "temperature": 0.7 } ], "default": "default-chat" }4.2 参数怎么填，每个字段背后的逻辑
很多人配 models.json 就是照抄别人的，结果跑不通也不知道为什么。我把关键字段的逻辑讲清楚：
- name：这是你给模型起的内部代号，Skill 里引用模型时用的就是它。建议起有意义的名字，比如
fast-chat、deep-reason，别用model1、model2，后期维护会疯。 - endpoint：模型服务的接口地址。这里最容易出错的是结尾的斜杠和路径版本号，多一个少一个斜杠都可能导致 404。
- apiKey：密钥字段。注意这个文件如果被同步到云端或提交到代码仓库，密钥就泄露了，务必做好本地保护。
- maxTokens：单次响应的最大 token 数。设太小，长回答会被截断；设太大，成本和延迟都上去了。我一般对话类设 4096，长文处理类设 8192。
- temperature：随机性参数。写代码、做数据处理建议 0.2 到 0.3，创意类任务可以到 0.8。
注意：apiKey 属于敏感信息，不要截图发群、不要提交到公开仓库。我见过有人把带密钥的配置文件直接传到网盘求"帮忙看看"，这是大忌。
4.3 多模型路由的配置思路
当你配了多个模型后，就要考虑路由策略。我的做法是按任务类型分：
- 轻量对话、快速问答 → 路由到响应快的模型
- 长文档分析、复杂推理 → 路由到能力强的模型
- 批量脚本生成 → 路由到性价比高的模型
在 models.json 里通过default字段指定默认模型，然后在 Skill 里可以显式指定用哪个模型。这样既保证日常够快，又能在重活上不将就。热词里"ai agent 中台"的说法，其实说的就是这种把多个模型统一调度起来的玩法。
4.4 配置生效与验证方法
改完 models.json 后，一定要重启 WorkBuddy 或触发配置重载，很多配置不是热生效的。验证方法很简单：发一句测试对话，看是否有正常响应；如果报错，先看日志里的具体错误码，再对照下面第 8 节的排查表。
我踩过的一个坑是：改了配置没重启，然后对着旧配置调了半天，以为是密钥问题，其实是根本没加载新文件。这种低级错误浪费的时间最冤。
5. 缓存目录迁移：别让系统盘先倒下
5.1 为什么缓存目录必须改
WorkBuddy 运行过程中会产生大量缓存：模型响应缓存、Skill 运行中间产物、日志、临时文件。默认情况下这些都在系统盘的用户目录下。系统盘通常是 SSD 但容量有限，一旦缓存涨起来，轻则卡顿，重则任务写到一半失败。
热词里"workbuddy怎么更改系统缓存目录"搜索量高，说明这是普遍痛点。我的建议是：装完第一件事就是改缓存目录，别等爆盘了再补救。
5.2 更改缓存目录的实操步骤
不同版本的操作入口可能不同，但思路一致。常见做法有两种：
- 通过设置界面改：进入设置，找到缓存或存储相关选项，把路径改到你规划好的目录，比如
D:\WorkBuddyCache。 - 通过配置文件改：部分版本支持在配置里指定缓存路径，改完重启生效。
改完之后，把旧缓存目录里的内容迁移过去或直接清空，否则旧数据还占着系统盘。迁移时注意先关闭 WorkBuddy，避免文件占用导致迁移失败。
5.3 缓存清理的节奏与技巧
缓存不是改完目录就一劳永逸，还得定期清。我的节奏是：
- 每周清一次临时文件和日志
- 每月检查一次 Skill 依赖缓存，把不用的 Skill 依赖删掉
- 大任务跑完后顺手清一次中间产物
有个小技巧：给缓存目录单独设一个磁盘配额或者用脚本监控大小，超过阈值就提醒。我用一个简单的批处理脚本每周跑一次，省得自己记。
提示：清理缓存前确认没有正在运行的任务，否则可能删掉正在用的中间文件导致任务失败。
6. Skill 机制：WorkBuddy 真正的杀手锏
6.1 Skill 是什么，为什么它比聊天重要
如果说 models.json 是大脑，那 Skill 就是手脚。Skill 是一段可复用的能力封装，它定义了"当遇到某类任务时，AI 该按什么步骤、调用什么工具、产出什么结果"。有了 Skill，你就不用每次重复描述需求，AI 会按预设流程自动干活。
热词里"workbuddy skill""skill插件""skill开发指南""agent skill"扎堆出现，说明大家都意识到 Skill 才是这个工作台的核心竞争力。我自己的体验是：没有 Skill 的 WorkBuddy 是个聪明但健忘的助手，有了 Skill 它才变成能长期替你干活的员工。
6.2 Skill 的典型结构与编写要点
一个 Skill 通常包含几个部分：触发条件、执行步骤、依赖工具、输出格式。我写 Skill 的经验是抓住三个要点：
- 触发条件要明确：别写"处理文档"这种模糊描述，要写"当用户提供 Markdown 文件并要求提取标题层级时触发"。
- 步骤要可执行：每一步都要是 AI 能实际执行的动作，不能是"理解一下内容"这种虚的。
- 输出要结构化：规定好输出格式，比如固定返回 JSON 或固定表格，方便后续处理。
下面是一个 Skill 结构的示意（基于常见实践，非官方模板）：
name: extract-headings description: 从 Markdown 文件中提取所有标题层级 trigger: 用户提供 .md 文件并要求提取标题 steps: - 读取文件内容 - 按行扫描，识别以 # 开头的行 - 记录层级和文本 output: format: table fields: [level, text]6.3 从"book to skill"看 Skill 的复用思路
热词里有个很有意思的"book to skill"，我理解是把一本书或一套方法论转化成可执行的 Skill。这个思路很实用：你读了一本讲工作方法的书，可以把里面的流程拆成 Skill，让 AI 按书里的方法帮你干活。比如把"如何做竞品分析"拆成一个 Skill，以后每次分析都按这个框架走。
这种复用思路的价值在于：把一次性的知识沉淀成可反复调用的能力。我把自己常用的几个工作流都做成了 Skill，现在处理同类任务基本不用重新想步骤。
6.4 Skill 开发中容易踩的坑
写 Skill 我踩过的坑不少，挑几个典型的说：
- 依赖没声明：Skill 里用了某个工具但没在依赖里写，运行时直接报错。
- 触发条件太宽：结果 AI 在不该触发的时候也触发，干扰正常对话。
- 输出格式不固定：导致下游处理脚本解析失败。
- 没做异常处理：文件不存在、格式不对时直接崩，没有兜底。
注意：Skill 写完一定要用边界情况测一遍，比如空文件、超大文件、格式错误的文件，别只测正常情况。
7. 规则持久化：让 AI 记住你的偏好
7.1 为什么要给 WorkBuddy 定规则
热词里"给 workbuddy 定几条规则，后续对所有任务都生效"这个需求非常真实。默认情况下，AI 每次对话都是"失忆"的，你得反复交代偏好。规则持久化就是把你的一些长期要求写进去，让 AI 在所有任务里都遵守。
我给自己定的几条规则包括：输出默认用中文、代码块必须标注语言、涉及文件操作先确认路径、不确定的信息要明确标注"待核实"。这几条一设，日常沟通顺畅多了。
7.2 规则怎么写才有效
规则不是写得越多越好，写太多反而互相冲突。我的经验是：
- 规则要具体可执行，别写"回答要好"这种没法执行的。
- 规则数量控制在5 到 10 条，太多会稀释重点。
- 规则之间不能矛盾，比如既要求"简洁"又要求"详尽"就会打架。
7.3 规则与 Skill 的配合
规则是全局的，Skill 是局部的。规则管"一贯风格"，Skill 管"具体流程"。两者配合起来，AI 既保持你的个人风格，又能按专业流程干活。比如规则里定"输出用中文表格"，Skill 里定"提取标题的具体步骤"，组合起来就是既符合你习惯又专业的结果。
8. 常见问题与排查技巧实录
8.1 高频问题速查表
下面这张表是我和身边朋友实际遇到过的问题汇总，按出现频率排序：
| 问题现象 | 可能原因 | 排查方向 |
|---|---|---|
| AI 无响应 | models.json 配置错误 | 检查 endpoint 和密钥 |
| 请求超时 | 网络不通或模型服务异常 | 测试网络连通性 |
| Skill 不触发 | 触发条件不匹配 | 检查触发描述 |
| 缓存爆盘 | 缓存目录在系统盘 | 迁移缓存目录 |
| 输出被截断 | maxTokens 太小 | 调大 token 上限 |
| 文件读写失败 | 权限未开启 | 检查权限设置 |
| 配置不生效 | 未重启 | 重启后重试 |
8.2 排查的基本思路
排查问题的核心思路是分层定位：先确认是模型层、Skill 层还是运行时层的问题。方法很简单：
- 先发一句最简单的对话，确认模型层通不通。
- 模型通了再测 Skill，确认 Skill 层有没有问题。
- 都通了再看具体任务，定位到运行时层。
这样一层层排除，比一上来就瞎改配置高效得多。我见过太多人一遇到问题就重装，其实大部分问题改一个字段就解决了。
8.3 几个独家避坑技巧
- 配置改动前先备份：models.json 改之前复制一份，改坏了能秒回滚。
- 日志是最好的朋友：出问题先看日志，错误码比现象有用得多。
- 小步验证：一次只改一个配置项，改完立即验证，别一次改一堆然后不知道哪个出的问题。
- 版本升级前看更新说明：有些版本升级会改配置格式，不看说明直接升容易翻车。
9. 关于并发和性能的一点实战体会
热词里"ai agent 怎么扛并发"是个进阶话题。WorkBuddy 作为个人工作台，日常单任务居多，但如果你挂了很多 Skill 跑批量任务，就会遇到并发问题。我的体会是：
- 别盲目开高并发：模型服务通常有速率限制，开太高反而大量请求失败。
- 给任务排队：把批量任务拆成队列，一个个跑，稳定性远高于一拥而上。
- 监控资源占用：并发高的时候看内存和 CPU，别把机器跑死。
我试过同时跑 10 个 Skill 任务，结果一半超时，后来改成队列串行，虽然慢一点但全部成功。这个取舍在个人场景下，稳定性比速度重要。
10. 我个人的使用节奏和一些实在建议
用 WorkBuddy 这段时间，我最大的体会是：它不是一个装完就能用的工具，而是一个需要你持续调教的工作台。前期在 models.json、缓存目录、Skill 上花的功夫，后面都会以效率的形式还给你。
如果你刚开始用，我的建议是先把基础配置弄扎实，别急着堆 Skill。等模型通了、缓存稳了，再一个个加 Skill，每加一个就测透一个。我见过太多人一上来装一堆 Skill，结果互相干扰，最后弃用。
另外，Skill 这东西贵精不贵多。我现在常驻的就五六个，覆盖了资料整理、脚本生成、文本处理这几类高频任务，够用了。与其追求数量，不如把每个 Skill 打磨到真正顺手。
最后分享一个小习惯：我每周会花十分钟回顾一下这周 WorkBuddy 帮我干了哪些活、哪些地方还不顺，然后针对性优化一个 Skill 或一条规则。这种小步迭代，比一次性大改有效得多。工具是死的，用法是活的，把它调成适合你工作节奏的样子，它才真正算你的工作台。
