WorkBuddy 实战笔记：Skill 机制与 models.json 配置全解析

1. 为什么我要认真写一份 WorkBuddy 实战笔记WorkBuddy 这个产品最近在 AI 工作台圈子里被讨论得非常多。我最早注意到它是因为身边好几个做开发、做运营、做内容的朋友都在问同一个问题这东西到底和 CodeBuddy 有什么区别值不值得花时间折腾。我自己从安装、配置、写 Skill、调 models.json到后面踩了一堆坑前后折腾了差不多两周中间重装过三次改崩过两次配置文件也遇到过 Skill 加载不出来的情况。所以这篇东西不是产品说明书也不是官方文档的复述而是一个真实用过的人把从零到能跑通、再到能稳定用的全过程拆开来讲。如果你刚听说 WorkBuddy或者已经装上了但不知道怎么让它真正干活又或者你正在纠结它和 CodeBuddy 到底该用哪个那这篇内容应该能帮你省掉不少试错时间。我会从整体设计思路讲起然后拆核心配置、Skill 机制、models.json 的写法、实操流程最后把我遇到过的典型问题和排查方法整理出来。全程不绕弯子能直接抄的地方我会把配置和步骤写清楚需要判断的地方我会把判断依据讲明白。2. WorkBuddy 的整体设计与核心思路拆解2.1 它到底解决的是什么问题很多人第一次打开 WorkBuddy 会有点懵因为它的界面看起来像一个聊天窗口但又不完全是聊天。我的理解是它本质上是一个AI 工作台核心目标不是陪你聊天而是让 AI 真的能“下地干活”。这句话听起来有点虚但拆开看就很具体你可以在里面挂载不同的 Skill每个 Skill 对应一类具体任务比如读文件、写代码、查资料、整理表格、生成报告。AI 负责理解你的意图然后调用对应的 Skill 去执行。这和普通对话式 AI 最大的区别在于普通对话是你问一句它答一句输出的是文本WorkBuddy 是你给一个任务它可能调用多个 Skill中间产生文件、修改配置、执行命令最后给你一个可交付的结果。所以它更像一个“调度中心”而不是一个“问答机器人”。那为什么是腾讯做这件事我的观察是腾讯内部有大量工具链和业务场景CodeBuddy 已经在代码辅助这个方向跑了一段时间WorkBuddy 更像是把能力从“写代码”扩展到“做工作”。你可以理解为 CodeBuddy 聚焦在开发者写代码这个环节WorkBuddy 想覆盖更广的办公和创作场景。两者底层可能有共用的模型和调度能力但产品定位不一样。2.2 为什么是 Skill 机制而不是插件市场WorkBuddy 选择 Skill 作为核心扩展方式这个决策我觉得挺关键。插件市场的问题是插件质量参差不齐安装多了容易冲突而且插件往往是黑盒出了问题不好排查。Skill 不一样它更像是一段可读、可改、可版本管理的配置或脚本。你可以自己写也可以改别人的出了问题能直接看内容。从实际使用体验看Skill 机制的好处有三个。第一是可控你知道它要做什么因为它就是一段描述加执行逻辑。第二是可组合一个任务可以拆成多个 Skill 串起来跑。第三是可迁移Skill 写好了可以分享给别人别人导入就能用。这也是为什么热词里会出现“skill 编码247”“book to skill”“去 AI 味的 skill”这些说法因为大家已经在把 Skill 当成一种可复用的资产在讨论了。但 Skill 机制也有代价。它要求你对任务本身有比较清晰的理解不然写出来的 Skill 要么太泛要么太碎。我一开始就犯过这个错写了一个“帮我整理文件”的 Skill结果它什么都想干最后什么都干不好。后面拆成“按类型归档”“按日期重命名”“提取文档摘要”三个独立 Skill反而好用很多。2.3 models.json 为什么是绕不过去的坎models.json 是 WorkBuddy 里配置模型的地方。你可以把它理解成一个“模型清单”告诉 WorkBuddy 有哪些模型可以用、怎么调用、参数是什么。这个文件看起来简单但实际写起来坑不少。比如字段名写错、模型标识符不对、参数类型不对都会导致模型加载失败。我为什么说它是绕不过去的坎因为 WorkBuddy 的能力上限很大程度上取决于你挂了什么模型。不同模型在理解能力、生成速度、上下文长度上差异很大。如果你只用一个默认模型很多任务效果会打折扣。但如果你乱挂一堆模型又可能遇到调用混乱、响应变慢的问题。所以 models.json 的配置本质上是在做模型选型和路由。我的建议是刚开始不要贪多先配一两个主力模型把基本流程跑通。等你知道自己主要用 WorkBuddy 做什么类型的任务再针对性地加模型。比如你主要做代码相关的事就侧重代码能力强的模型主要做内容整理就侧重长文本理解和生成质量好的模型。3. 核心细节解析与实操要点3.1 安装前的环境准备与检查清单安装 WorkBuddy 本身不复杂但环境没准备好后面会各种报错。我整理了一个检查清单按这个顺序过一遍能避开大部分低级问题。检查项要求为什么重要操作系统Windows 10 及以上 / macOS 12 及以上低版本系统可能缺少运行库磁盘空间至少预留 5GB模型缓存和日志会占空间网络环境能正常访问所需服务部分功能依赖在线服务权限有当前用户目录的读写权限Skill 和配置需要写文件杀毒软件提前加白名单避免误杀执行进程我重点说两个容易忽略的点。第一是磁盘空间很多人觉得装个软件几百兆就够了但 WorkBuddy 在运行过程中会产生缓存、日志、临时文件尤其是你挂载多个 Skill 之后空间消耗比想象中大。第二是杀毒软件我遇到过 Skill 执行到一半被拦截的情况排查了半天才发现是安全软件把某个脚本当成了可疑行为。提前把 WorkBuddy 的安装目录和用户数据目录加白名单能省很多事。提示安装路径尽量不要选中文目录或带空格的路径。虽然现在很多软件已经支持了但 Skill 执行和模型加载环节路径问题仍然是最常见的报错来源之一。3.2 安装过程中的关键选择与理由安装的时候会有几个选项我逐个说下我的选择和理由。第一个是安装位置。默认是装在系统盘我建议改到非系统盘。原因很简单WorkBuddy 后续会下载模型缓存、生成日志、存 Skill 文件这些数据会越来越大。放系统盘时间久了容易把系统盘撑满影响整机性能。我一般会专门建一个目录比如D:\Tools\WorkBuddy所有相关数据都放里面方便管理和备份。第二个是是否创建桌面快捷方式。这个看个人习惯我建议创建因为 WorkBuddy 不是那种装完就忘的软件你会经常打开它调 Skill、看日志、改配置。有个快捷方式省得每次去开始菜单找。第三个是是否开机自启。我的建议是不要。WorkBuddy 在后台运行时会占用一定资源如果你不是每天都在高频使用开机自启只会拖慢开机速度。需要的时候手动打开就行。安装完成后第一次启动会引导你做初始配置。这里会让你选择工作目录、日志级别、默认模型等。工作目录我建议单独建一个不要和系统目录混在一起。日志级别刚开始可以选详细一点方便排查问题等稳定了再调回正常级别。3.3 Skill 的加载机制与编写要点Skill 是 WorkBuddy 的核心理解它的加载机制很重要。简单说WorkBuddy 启动时会扫描指定目录下的 Skill 文件解析里面的描述和执行逻辑然后注册到可用 Skill 列表里。当你给一个任务时它会根据任务描述匹配最合适的 Skill然后调用执行。这里有几个关键点。第一是Skill 的命名。名字要能准确反映功能不要用“工具1”“助手2”这种模糊名字。因为匹配环节会参考名字名字越清晰匹配越准。第二是Skill 的描述。描述要写清楚这个 Skill 能做什么、需要什么输入、输出什么结果。描述写得好AI 匹配的准确率会明显提高。第三是执行逻辑。这部分可以是脚本也可以是配置化的步骤。我的经验是能配置化就不要写脚本因为脚本调试成本高而且容易受环境影响。我写 Skill 的时候会遵循一个原则一个 Skill 只做一件事。比如“读取 Excel 并提取指定列”是一个 Skill“把提取的数据生成图表”是另一个 Skill。这样组合起来灵活单个 Skill 也容易测试和维护。如果硬塞到一个 Skill 里后面改一处可能影响全部得不偿失。注意Skill 文件修改后需要重启 WorkBuddy 或者手动触发重新加载才能生效。我一开始不知道改完 Skill 直接测试发现没变化还以为写错了白白折腾了半天。3.4 models.json 的字段含义与配置逻辑models.json 的结构不复杂但每个字段都有实际作用写错了就会出问题。我按我实际用到的字段逐个解释。{ models: [ { name: 主力模型, provider: 对应服务商, model_id: 模型标识符, api_key: 你的密钥, max_tokens: 4096, temperature: 0.7, timeout: 30 } ] }name是你自己起的名字方便在界面里识别。provider是服务商标识不同服务商写法不同要按文档来。model_id是模型的具体标识符这个最容易写错一定要从服务商那边复制不要手打。api_key是你的调用密钥注意不要泄露也不要把这个文件传到公开仓库。max_tokens是单次生成的最大长度根据任务类型调整太短可能截断太长浪费资源。temperature控制随机性做代码和整理类任务建议低一点做创意类可以高一点。timeout是超时时间网络不稳定的时候可以适当调大。我踩过的坑是model_id写错了一个字符结果模型一直加载失败报错信息又不明显查了很久才发现。所以我的建议是配置完先做一次连通性测试确认模型能正常调用再去做其他配置。4. 实操过程与核心环节实现4.1 从零跑通第一个 Skill 的完整流程我拿一个实际例子来讲就是“读取指定目录下的文档并生成摘要”这个 Skill。这个任务不复杂但涵盖了 Skill 编写、模型调用、结果输出几个关键环节适合用来跑通流程。第一步确定工作目录。我在 WorkBuddy 里建了一个workspace目录里面放了一个docs子目录用来放待处理的文档。这样做的好处是路径固定Skill 里可以直接写相对路径不用每次改。第二步写 Skill 描述。我写的是“读取 docs 目录下的所有文本文件逐个生成摘要汇总输出到一个结果文件。”描述里明确了输入位置、处理对象、输出形式这样匹配和执行都有依据。第三步配置执行逻辑。我选择用配置化方式定义了几个步骤扫描目录、过滤文本文件、逐个读取内容、调用模型生成摘要、写入结果文件。每一步都有明确的参数比如扫描目录时指定docs过滤时指定扩展名.txt和.md。第四步关联模型。在 Skill 配置里指定使用哪个模型来生成摘要。这里要注意摘要任务对模型的理解能力要求比较高我选了一个长文本处理能力较好的模型temperature设成 0.3让输出更稳定。第五步测试运行。我先在docs里放了三个短文档运行 Skill看输出结果。第一次跑的时候结果文件是空的排查发现是过滤条件写成了.txt但我的文档是.md改过来就正常了。这个流程跑通之后后面做更复杂的 Skill 就有底了。我的体会是先用小数据量跑通再上真实数据这样出问题容易定位。4.2 多 Skill 组合完成复杂任务的配置方法单个 Skill 能做的事有限真正体现 WorkBuddy 价值的是多 Skill 组合。我举一个实际场景从一堆会议记录里提取待办事项然后按负责人分类最后生成一个汇总表。这个任务我拆成了三个 Skill。第一个是“提取待办”负责读会议记录识别出所有待办事项。第二个是“识别负责人”从待办事项里提取人名或角色。第三个是“生成汇总表”把待办和负责人对应起来输出成表格。组合的方式是在 WorkBuddy 里定义一个任务流指定这三个 Skill 的执行顺序以及数据怎么传递。第一个 Skill 的输出作为第二个的输入第二个的输出作为第三个的输入。这里的关键是数据格式要统一我一开始第一个 Skill 输出的是纯文本第二个 Skill 期望的是结构化数据结果对不上。后面改成第一个 Skill 输出 JSON 格式后面就顺畅了。提示多 Skill 组合时建议在每个环节都加一个简单的校验确认输入数据符合预期再往下走。不然错误会一直传递到最后排查起来很麻烦。4.3 更改系统缓存目录的操作步骤热词里有人问“workbuddy 怎么更改系统缓存目录”我实际改过步骤不复杂但有几个细节要注意。默认情况下WorkBuddy 的缓存目录在用户目录下路径大概是用户目录/.workbuddy/cache。这个目录会随着使用不断变大如果系统盘空间紧张就需要改到其他盘。操作步骤是这样的。先关闭 WorkBuddy确保进程完全退出。然后找到配置文件一般在安装目录的config文件夹下文件名可能是settings.json或类似名称。打开后找到cache_dir字段把值改成你想要的新路径比如D:\WorkBuddyData\cache。保存后重新启动 WorkBuddy。这里有两个坑。第一是新目录必须提前建好并且有读写权限不然启动会报错。第二是旧缓存不会自动迁移如果你之前已经积累了很多缓存需要手动把旧目录里的内容复制到新目录否则之前的缓存就白费了。我改的时候没注意第二点结果之前下载的模型缓存全没了重新下了一遍。4.4 给 WorkBuddy 定规则让后续任务都生效热词里有一条是“给 workbuddy 定几条规则后续对所有任务都生效”。这个功能我研究过本质上是设置全局约束。比如你可以规定所有输出都用中文、所有文件都保存到指定目录、所有任务都要先确认再执行。设置的位置一般在设置页面的“全局规则”或“偏好”里。我实际配了几条分享下我的配置思路。第一条是输出语言我设成中文因为我的任务基本都是中文场景。第二条是文件保存位置我指定了一个固定目录这样所有生成的文件都在一个地方方便管理。第三条是执行确认对于会修改文件或执行命令的 Skill我设成需要确认避免误操作。这几条规则设好之后确实省心很多。但要注意规则不要设太多太细不然会限制 Skill 的灵活性。我的原则是只设那些跨任务通用的约束任务特有的要求还是在 Skill 里定义。5. 常见问题与排查技巧实录5.1 Skill 加载失败的原因与排查顺序Skill 加载失败是我遇到最多的问题原因有好几种我按排查顺序列一下。先看文件格式。Skill 文件如果是 JSON 或 YAML格式错误是最常见的。比如少了个逗号、多了个括号、缩进不对。我建议用编辑器的格式化功能先格式化一遍很多格式问题会自动暴露。再看字段完整性。Skill 需要哪些字段文档里一般有说明。缺字段会直接导致加载失败。我遇到过一次是漏了description字段补上就好了。然后看路径引用。如果 Skill 里引用了外部文件或目录路径不对也会加载失败。相对路径和绝对路径要分清楚我建议统一用绝对路径虽然写起来麻烦但不容易出错。最后看权限。Skill 文件所在目录如果没有读权限或者 Skill 要写入的目录没有写权限也会失败。这个在 Windows 上尤其常见因为权限管理比较细。问题现象可能原因解决方法加载时直接报错文件格式错误用格式化工具检查加载成功但不可用字段缺失或值不对对照文档补全字段执行时报路径错误路径引用不对改用绝对路径执行到一半失败权限不足检查目录读写权限5.2 模型调用超时与响应异常的解决思路模型调用超时也很常见尤其是网络不稳定或者模型服务端负载高的时候。我的解决思路分三步。第一步确认是不是网络问题。可以先用其他方式测试网络连通性如果网络本身有问题先解决网络。第二步调整超时时间。在 models.json 里把timeout调大比如从 30 秒调到 60 秒给模型更多响应时间。第三步换模型。如果某个模型一直超时可能是服务端问题换个模型试试。响应异常还包括返回内容为空、返回内容截断、返回内容格式不对。返回为空可能是max_tokens设得太小或者提示词有问题。返回截断就是max_tokens不够调大就行。返回格式不对一般是提示词里没有明确要求输出格式需要在 Skill 里把格式要求写清楚。5.3 配置文件改崩后的恢复方法我改崩过两次配置文件一次是 models.json一次是全局设置。恢复方法其实很简单就是提前备份。我现在改任何配置文件之前都会先复制一份命名成xxx.backup。改崩了直接把备份改回来就行。如果没有备份也有办法。WorkBuddy 一般会在用户目录下保留配置的历史版本或默认配置。可以找找有没有config.bak或default.config之类的文件。实在不行卸载重装但这样会丢失之前的 Skill 和缓存所以备份真的很重要。注意改配置文件时建议一次只改一个地方改完就测试。不要一次性改一堆出了问题不知道是哪个改动导致的。5.4 性能优化的几个实用技巧用了一段时间之后我总结了几条性能优化的经验。第一控制同时运行的 Skill 数量。WorkBuddy 可以并行跑多个 Skill但并行太多会抢资源反而变慢。我一般同时跑不超过三个。第二定期清理缓存和日志。缓存和日志积累多了会拖慢启动速度和运行效率。我设了一个每月清理一次的习惯把不需要的缓存和旧日志删掉。第三模型按需加载。如果 models.json 里配了很多模型但常用的就一两个可以把不常用的先注释掉减少启动时的加载负担。第四Skill 尽量轻量化。Skill 里的逻辑不要太复杂复杂任务拆成多个 Skill 组合比一个大 Skill 跑到底要稳定。6. 一些实际使用中的体会WorkBuddy 这个工具我的整体感受是上手不难用好需要花点心思。它的核心价值在于把 AI 能力从“对话”变成了“执行”但这个转变需要你重新思考怎么描述任务、怎么拆解步骤、怎么配置环境。我刚开始用的时候总想着一步到位写一个大而全的 Skill 解决所有问题结果反复失败。后面改成小步快跑一个 Skill 解决一个小问题再组合起来反而顺利很多。另外models.json 和 Skill 这两个东西建议花时间认真学一下。它们看起来是配置实际上是 WorkBuddy 的能力边界。你配了什么模型决定了它能理解多复杂的任务你写了什么 Skill决定了它能执行多具体的操作。这两块搞明白了WorkBuddy 才真正算用起来了。最后分享一个小技巧如果你不确定一个 Skill 该怎么写可以先手动做一遍任务把每一步记下来然后按步骤拆成 Skill。这样写出来的 Skill 逻辑清晰也容易测试。我现在写新 Skill 都是这个流程基本一次就能跑通。