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 skillskill插件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 或一条规则。这种小步迭代比一次性大改有效得多。工具是死的用法是活的把它调成适合你工作节奏的样子它才真正算你的工作台。
腾讯WorkBuddy实战指南：从安装配置到Skill开发与避坑全解析
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 skillskill插件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 或一条规则。这种小步迭代比一次性大改有效得多。工具是死的用法是活的把它调成适合你工作节奏的样子它才真正算你的工作台。
