1. 先搞清楚 WorkBuddy 到底是个什么东西

1.1 它不是一个聊天窗口，而是一个能动手干活的 AI 工作台

很多人第一次听到 WorkBuddy 这个名字，下意识会觉得“又是一个套壳对话工具”。我一开始也这么想，直到真正把它跑起来、接上自己的项目目录、看着它自己去读文件、改配置、跑命令，才意识到这东西的定位跟普通对话式 AI 完全不是一回事。

WorkBuddy 是腾讯推出的一款 AI 工作台产品，核心形态是一个AI Agent 运行环境。你可以把它理解成一个“带手带脚的 AI”：普通对话模型只能给你建议，而 WorkBuddy 里的 Agent 能真正去操作你的工作目录、执行脚本、读写文件、调用外部工具，最后把结果交付给你。它面向的是那些希望把 AI 从“问答助手”升级成“执行助手”的人——开发者、运维、数据分析、内容生产、甚至做数学建模的学生，都能在里面找到自己的用法。

它解决的问题很具体：过去我们用 AI 写代码，得自己复制粘贴、自己建文件、自己跑命令，中间来回切换特别碎。WorkBuddy 把这些环节收进一个工作台里，Agent 直接在你的项目上下文里干活，你只需要给目标、定规则、看结果。适合谁来参考？我的判断是三类人最值得花时间：一是天天跟代码和命令行打交道的工程师；二是想把重复工作自动化的运营和办公人群；三是正在学习 AI Agent 到底怎么落地、想从 0 到 1 搭一个自己 Agent 的爱好者。

1.2 和 CodeBuddy 的区别，别搞混了

热词里反复出现“workbuddy 和 codebuddy 的区别”，这个问题确实值得单独说清楚，因为搞混了会导致你选错工具、走错路。

CodeBuddy 更偏向编码辅助这个垂直场景，它的强项是在你写代码的过程中做补全、解释、重构建议，形态上更接近一个深度集成在编辑器里的编程伙伴。而 WorkBuddy 的野心更大，它是一个通用 Agent 工作台，编码只是它能干的其中一类活。它强调的是“任务级”的自动化：你给它一个完整任务，它自己拆解、自己执行、自己验证。

打个比方，CodeBuddy 像坐在你旁边的结对程序员，你写一行它帮你看一行；WorkBuddy 更像你雇的一个能独立跑腿的助理，你说“把这个项目的配置文件整理一下并生成说明文档”，它自己就去干了。两者不是替代关系，而是场景不同。你要是只想在写代码时有个帮手，CodeBuddy 够用；你要是想让 AI 接管一整段工作流，那 WorkBuddy 才是对的方向。

1.3 核心概念先扫盲：Agent、Skill、models.json

在正式动手之前，有三个词必须先弄明白，否则后面看教程会一头雾水。

AI Agent是 WorkBuddy 里的执行主体。它不是一个模型，而是一套“模型 + 工具 + 记忆 + 规划”的组合。模型负责思考，工具负责动手，记忆负责记住上下文，规划负责把大任务拆成小步骤。WorkBuddy 帮你把这套东西封装好了，你不需要从零写 Agent 框架。

Skill是 WorkBuddy 的能力扩展单元，你可以把它理解成给 Agent 装的“技能插件”。一个 Skill 通常包含一段说明（告诉 Agent 什么时候用它）和一段可执行的逻辑（脚本、命令、API 调用等）。热词里出现的“skill 编码 247”“仓颉 skill”“数学建模 skill”“unity skill attack indicators”这些，本质上都是不同领域的人把自己的一套操作封装成了 Skill，让 Agent 能直接调用。Skill 是 WorkBuddy 生态里最有价值的部分，因为它把“专业经验”变成了“可复用能力”。

models.json是模型配置文件。WorkBuddy 支持接入不同的模型，你需要在这个文件里告诉它用哪个模型、走哪个接口、参数怎么设。这个文件配错了，Agent 要么跑不起来，要么跑起来但效果很差。后面我会专门讲这个文件的写法。

2. 安装部署：从下载到第一次跑通

2.1 安装前的环境准备与版本选择

WorkBuddy 目前有多个版本形态，热词里提到的“workbuddy 国际版”“workbuddy 网页版”“workbuddy linux”其实指向不同的使用方式。我的建议是按你的实际场景选：

• 桌面客户端版：适合本地开发、需要操作本地文件的场景，功能最完整。
• 网页版：适合快速体验、轻量任务，不用装东西，但操作本地文件的能力受限。
• Linux 版：适合服务器部署、跑自动化任务，是进阶玩法。

环境准备上，桌面版对系统要求不算高，但有几个点要注意。第一，确保你的磁盘有足够空间，因为 Agent 运行过程中会产生缓存和中间文件，热词里有人问“workbuddy 系统缓存目录能改到 d 盘吗”，这个问题很真实——默认缓存目录在系统盘，长期用下来会占不少空间，后面我会讲怎么改。第二，确保网络环境能正常访问你配置的模型接口。第三，如果你打算跑涉及命令行的 Skill，提前把常用的运行时装好，比如 Python、Node.js，省得 Agent 执行到一半报“命令找不到”。

提示：安装前先想清楚你主要用它干什么。如果只是体验，网页版足够；如果要长期用于项目，直接上桌面版，别在网页版上浪费时间。

2.2 安装步骤与首次启动配置

安装过程本身不复杂，下载对应平台的安装包，一路下一步即可。真正需要花心思的是首次启动后的配置，这一步决定了你后面用得顺不顺。

启动后第一件事是配置模型。WorkBuddy 需要你提供一个可用的模型接口，配置入口通常在设置里的“模型管理”或直接编辑 models.json。配置完成后，建议先做一个最小验证：让它执行一个简单任务，比如“在当前目录创建一个 test.txt 并写入 hello”。如果它能正确完成，说明模型、工具调用链路都通了。

第二件事是设置工作目录。WorkBuddy 的 Agent 是在你指定的目录里干活的，这个目录就是它的“活动范围”。我强烈建议不要一上来就把整个硬盘或者用户主目录设成工作目录，风险太大。正确做法是新建一个专门的项目文件夹，把工作目录指向它，让 Agent 在这个沙箱里折腾。等你熟悉了它的行为模式，再逐步放开。

第三件事是配置规则。热词里有一条“给 workbuddy 定几条规则，后续对所有任务都生效”，这个功能非常关键。你可以在配置里写一些全局规则，比如“删除文件前必须先确认”“不要修改 .env 文件”“所有生成的代码必须带注释”。这些规则会作为系统提示的一部分，约束 Agent 的行为。这是防止它“手滑”的第一道防线。

2.3 缓存目录迁移到非系统盘的正确姿势

“workbuddy 系统缓存目录能改到 d 盘吗”这个问题问的人特别多，我专门说一下。默认情况下，缓存目录在系统盘的用户目录下，随着使用会越来越大。迁移的思路是：找到配置文件里的缓存路径设置项，改成你想要的路径，然后把旧缓存迁移过去。

具体操作上，不同版本配置项名称可能略有差异，但逻辑一致：先关闭 WorkBuddy，找到配置目录（通常在用户目录下的隐藏文件夹里），编辑配置文件，把 cache 或 workspace 相关的路径改成目标盘符下的目录，保存后重启。重启后验证一下新目录里是否开始生成文件，如果生成了，说明迁移成功。

注意：迁移前一定要先关闭程序，否则文件被占用会导致迁移失败或数据损坏。迁移完成后，旧目录可以保留几天再删，确认没问题再清理。

3. models.json 配置：Agent 能不能跑起来全看它

3.1 models.json 的结构与关键字段

models.json 是 WorkBuddy 的模型配置文件，它的作用是告诉工作台“有哪些模型可用、每个模型怎么调用”。这个文件写错了，Agent 直接罢工。我见过太多人卡在这一步，所以把结构拆开讲。

一个典型的 models.json 包含一个模型列表，每个模型条目里有几个关键字段：模型标识（用来在界面里选择）、接口地址、认证信息、模型名称、以及一些生成参数（比如温度、最大 token 数）。这些字段里，最容易出错的是接口地址和模型名称的对应关系——地址对了但模型名写错，调用会直接报错。

我的经验是，配置完一个模型后，先用它跑一个最简单的任务验证，别急着配一堆模型。验证通过再复制结构去配下一个，这样出问题容易定位。

3.2 多模型切换与参数调优

WorkBuddy 支持配置多个模型，这在实际使用中很有价值。不同任务适合不同模型：需要强推理的任务用推理能力强的模型，需要快速响应的任务用轻量模型，涉及长文档处理的任务用上下文窗口大的模型。

参数调优上，温度（temperature）是最值得调的。做代码生成、配置修改这类需要确定性的任务，温度调低一点，让输出更稳定；做创意文案、方案发散这类任务，温度可以适当调高。最大 token 数也要注意，设太小会导致长任务被截断，设太大又可能浪费资源。

我个人的习惯是准备两套配置：一套“严谨模式”，低温度、明确约束，用于改代码和配置；一套“发散模式”，稍高温度，用于写方案和头脑风暴。切换的时候直接换模型条目，不用每次手动调参数。

3.3 配置出错的典型表现与快速定位

models.json 配错的表现很有规律，记住这几个就能快速定位：

这张表是我踩坑总结出来的，基本覆盖了 90% 的配置问题。遇到报错先对照这张表，比盲目搜索快得多。

4. Skill 机制：WorkBuddy 真正的杀手锏

4.1 Skill 是什么，为什么它比模型更重要

如果说模型是 Agent 的大脑，那 Skill 就是它的手脚和工具箱。一个没有 Skill 的 Agent，只能靠模型本身的能力回答问题；而一个装了丰富 Skill 的 Agent，能真正去执行专业操作。

Skill 的本质是把一套操作流程封装成 Agent 可调用的能力。比如“数学建模 skill”可能封装了数据预处理、模型拟合、结果可视化的整套流程；“unity skill attack indicators”可能封装了在 Unity 里生成攻击指示器的操作步骤。这些 Skill 让不懂具体技术细节的人，也能通过自然语言指挥 Agent 完成专业任务。

这也是为什么热词里“skill 开发指南”“skill 推荐”“skill 插件”出现频率这么高——大家逐渐意识到，WorkBuddy 的价值上限，取决于你能给它装多少好用的 Skill。

4.2 从零开发一个自己的 Skill

开发 Skill 没有想象中那么难，核心就三步：定义能力、编写逻辑、注册到工作台。

第一步，定义能力边界。你要想清楚这个 Skill 解决什么问题、输入是什么、输出是什么、什么时候该被调用。这一步最关键，边界不清的 Skill 会让 Agent 不知道该不该用它。

第二步，编写执行逻辑。逻辑可以是一段脚本（Python、Shell 等），也可以是一组命令，甚至是对某个 API 的封装。写的时候要注意：逻辑要健壮，要能处理异常输入，要有清晰的错误提示，因为 Agent 调用出错时，好的错误信息能帮它自我修正。

第三步，注册并测试。把 Skill 放到工作台能识别的目录，写好说明文件，然后在实际任务里测试它是否被正确调用。测试时建议先用简单任务验证，再逐步增加复杂度。

提示：写 Skill 说明时，用“当用户需要……时使用本 Skill”这种明确的触发条件描述，比模糊的描述有效得多。Agent 是靠说明来判断调用时机的。

4.3 Skill 组合与工作流编排

单个 Skill 能力有限，真正强大的是多个 Skill 组合成工作流。比如一个“网站生成”任务，可能涉及：读取需求文档的 Skill、生成页面代码的 Skill、本地预览的 Skill、部署发布的 Skill。这些 Skill 串起来，就形成了一条完整的自动化流水线。

编排工作流时，我的经验是让每个 Skill 职责单一，不要把太多逻辑塞进一个 Skill。职责单一的好处是：出问题容易定位、可以灵活重组、复用性高。一个“什么都能干”的巨型 Skill，维护起来是噩梦。

另外，Skill 之间的数据传递要设计好。前一个 Skill 的输出格式，要能被后一个 Skill 正确接收。这个衔接点是最容易出问题的地方，建议在开发时就明确定义好数据格式。

5. 实战场景：把 WorkBuddy 用起来

5.1 场景一：从零生成并发布一个网站

热词里“workbuddy 怎么生成网站发布”是个高频问题，我拿这个当第一个实战案例。

整体思路是：让 Agent 根据你的需求生成静态网站文件，本地预览确认效果，然后发布到托管平台。具体步骤上，先给 Agent 一个清晰的需求描述，包括网站类型、页面结构、风格要求。Agent 会生成 HTML、CSS、JS 文件到工作目录。生成后，让它启动一个本地预览服务，你在浏览器里看效果。不满意就提修改意见，让它迭代。确认没问题后，再让它执行发布流程。

这里的关键是需求描述要具体。你说“做个好看的网站”，Agent 只能瞎猜；你说“做一个三栏布局的产品介绍页，主色调用深蓝，顶部有导航栏，底部有联系方式”，它就能生成接近你想要的东西。需求越具体，返工越少。

5.2 场景二：用 Skill 处理专业领域任务

以数学建模为例，这类任务通常包含数据清洗、模型选择、参数拟合、结果可视化几个环节。如果每个环节都手动做，很费时间。用 Skill 的思路是：把每个环节封装成 Skill，然后让 Agent 按流程调用。

实际操作时，你可以先让 Agent 读取数据文件，调用数据清洗 Skill 处理缺失值和异常值；然后根据问题类型选择合适的模型，调用拟合 Skill；最后调用可视化 Skill 生成图表。整个过程你只需要在关键节点做决策，重复劳动交给 Agent。

这种用法的价值在于：把专家的经验固化成了可复用的能力。一个建模高手把自己的流程封装成 Skill 后，新手也能借助 Agent 完成类似任务。

5.3 场景三：给 Agent 定规则实现长期约束

“给 workbuddy 定几条规则，后续对所有任务都生效”这个功能，是我认为最被低估的能力。它的价值在于：你不用每次都在提示里重复同样的要求，规则一次设定，长期生效。

适合写成规则的内容包括：安全约束（删除前确认、不碰敏感文件）、风格约束（代码注释规范、命名规范）、流程约束（先备份再修改、改完要验证）。把这些写进全局规则，Agent 在执行任何任务时都会遵守。

我的建议是规则不要一次写太多，先写最关键的几条，用一段时间后根据实际遇到的问题再补充。规则太多会互相冲突，反而让 Agent 无所适从。

6. 避坑指南：那些教程里不会写的事

6.1 权限与安全：别让 Agent 碰它不该碰的

这是最重要的一条。Agent 有执行能力，就意味着它有破坏能力。我见过有人把工作目录设成整个用户目录，结果 Agent 在整理文件时误删了重要资料。

防护措施有三层：第一，工作目录隔离，只给它一个专门的项目文件夹；第二，全局规则约束，明确禁止删除、禁止修改特定类型文件；第三，重要数据提前备份，别把唯一副本放在 Agent 能碰到的地方。

注意：任何自动化工具都有出错的可能，WorkBuddy 也不例外。把安全边界设好，比事后补救重要得多。

6.2 常见报错速查与解决思路

除了前面 models.json 的报错表，实际使用中还会遇到其他问题。我整理了几个高频的：

这张表建议收藏，遇到问题先对照排查，能省下大量搜索时间。

6.3 性能与成本控制经验

Agent 跑任务是要消耗资源的，不管是模型调用成本还是本地计算资源。控制成本有几个实用技巧。

第一，任务拆分要合理。一个超大任务一次性丢给 Agent，容易中途出错且难以定位；拆成几个小任务，每个验证通过再继续，反而更快更省。

第二，善用轻量模型。不是所有任务都需要最强模型，简单的文件操作、格式转换用轻量模型就够，把强模型留给真正需要推理的任务。

第三，缓存和复用。重复性的任务可以做成 Skill，避免每次重新生成。已经验证过的配置和脚本保存下来，下次直接用。

第四，定期清理缓存。前面提到的缓存目录迁移，配合定期清理，能避免磁盘被占满影响性能。

6.4 学习路径建议：从入门到精通怎么走

最后说说学习路径。热词里“workbuddy 从入门到精通 pdf 下载”“workbuddy 教程”这类需求很多，但我想说的是，这类工具光看教程没用，必须动手。

我的建议路径是：第一周，装好、配好模型、跑通几个简单任务，熟悉基本操作；第二周，尝试开发第一个自己的 Skill，哪怕很简单；第三周，把 Skill 组合成工作流，解决一个实际的小项目；之后就是持续积累 Skill、优化规则、探索新场景。

这个过程中，最有价值的不是记住多少功能，而是建立起“什么任务适合交给 Agent、怎么描述需求、怎么设边界”的判断力。这种判断力，只能靠实际使用积累。

我在实际使用中最大的体会是：WorkBuddy 这类工具的上限，取决于使用者的想象力。你把它当聊天机器人，它就只是个聊天机器人；你把它当能干的助理，它就能帮你扛下一大摊子事。从安装到避坑，这篇讲的东西够你上手了，剩下的就靠你自己去折腾。踩坑不可怕，可怕的是不敢开始。