1. 为什么我要认真写一份 WorkBuddy 实战笔记第一次接触 WorkBuddy 的时候我其实是带着一点怀疑的。市面上叫“AI 工作台”的产品太多了大多数用起来就是套壳对话加几个预设按钮真正能落到日常任务流里的没几个。但 WorkBuddy 不太一样它背后是腾讯的 AI 工作台思路核心不是“陪你聊天”而是把 AI Agent 当成一个能接活、能调工具、能按规则持续干活的协作单元。换句话说它更像是一个可以配置的工作伙伴而不是一个更聪明的搜索框。这篇内容适合三类人看第一类是刚听说 WorkBuddy想搞清楚它和普通 AI 助手到底差在哪第二类是已经装上了但卡在 models.json、Skill 配置、缓存目录这些细节上第三类是想把 WorkBuddy 当成 AI Agent 练手项目从 0 到 1 搭一个能真正跑起来的小智能体。我会从安装讲到避坑重点放在那些官方文档里一笔带过、但实际操作中一定会踩的地方。先给一个最直白的定位WorkBuddy 是一个 AI Agent 工作台它把模型接入、Skill 插件、任务规则、文件操作这些能力整合到一个界面里。你可以把它理解成一个“AI 员工的操作系统”——模型是大脑Skill 是技能包models.json 是神经接口配置而工作台本身负责调度和记忆。搞懂这四个东西的关系后面所有操作都会顺很多。2. 安装前的准备与版本选择思路2.1 WorkBuddy 和 CodeBuddy 到底是不是一回事很多人搜“workbuddy和codebuddy的区别”其实这两个名字经常被混着用。我的理解是CodeBuddy 更偏向代码场景的助手能力而 WorkBuddy 是把它扩展成了一个通用工作台。你可以简单记CodeBuddy 是“写代码的那个”WorkBuddy 是“什么活都能接的那个台子”。在实际安装包里你可能会看到两者共享一些底层组件但入口和配置侧重点不同。如果你只是想让 AI 帮你写代码、补全函数CodeBuddy 的轻量模式就够了。但如果你想让它读文件、调 Skill、按规则批量处理任务那就必须上 WorkBuddy 的工作台模式。这个判断很重要因为选错版本会导致你后面配了半天 Skill发现根本没有触发入口。2.2 安装包获取与系统兼容性判断WorkBuddy 目前主流是 Windows 和 macOS 桌面端Linux 用户搜“workbuddy linux”也能找到一些社区方案但官方支持度不如前两者。我的建议是如果你主力机是 Linux先别急着折腾可以在虚拟机里跑 Windows 版做验证等熟悉了 Skill 机制再考虑迁移。安装包大小通常在几百 MB 级别下载的时候注意看版本号。搜“workbuddy国际版”的人不少这里要提醒一句国际版和国内版在模型接入策略上可能有差异如果你只是做本地文件处理和 Skill 练手国内版完全够用没必要为了“国际版”三个字去折腾额外配置。提示下载后先别双击安装右键看属性里的数字签名确认发布者信息再继续。这不是小题大做AI 工作台类工具权限较高来源不明的包风险很大。2.3 安装路径与缓存目录的提前规划这是我最想强调的一点安装前就把缓存目录规划好。很多人搜“workbuddy 系统缓存目录能改到d盘吗”答案是可以但如果你装完再改会遇到索引重建、Skill 缓存失效、模型文件路径错乱一堆问题。我的做法是安装时直接选非系统盘作为主目录比如D:\WorkBuddy。然后在首次启动前手动创建D:\WorkBuddy\cache和D:\WorkBuddy\models两个文件夹。这样做的原因是WorkBuddy 运行时会频繁读写缓存和模型配置放在系统盘不仅占空间还可能因为权限问题导致 Skill 加载失败。具体操作上安装向导里如果有“自定义安装位置”一定要点进去改。如果没有装完后第一时间去设置里找“存储”或“缓存路径”选项改完重启一次。重启后检查models.json是否还在原位置如果被重置了说明你的修改没生效需要手动迁移配置文件。3. models.json 与 Skill 机制的核心逻辑3.1 models.json 不是普通配置文件它是模型路由表很多人第一次打开models.json会懵觉得就是一个 JSON 文件随便填填就行。但实际上这个文件决定了 WorkBuddy 怎么调用模型、用哪个模型处理哪类任务、超时和重试怎么算。它更像是一张路由表而不是简单的键值对。一个典型的models.json结构大概长这样{ default: main-model, models: { main-model: { provider: tencent, endpoint: https://api.example.com/v1, max_tokens: 4096, timeout: 30 }, fast-model: { provider: local, path: D:/WorkBuddy/models/fast.bin, max_tokens: 2048, timeout: 10 } }, routing: { code: main-model, summary: fast-model, default: main-model } }这里的关键是routing字段。你可以让代码类任务走能力强的模型摘要类任务走速度快的模型。这样配置的好处是既保证关键任务质量又不会让所有请求都挤在一个模型上导致响应变慢。注意timeout不要设得太短。我试过设 10 秒结果长文本任务频繁中断后来改成 30 秒才稳定。如果你用的是本地模型还要考虑首次加载时间建议单独给本地模型设 60 秒。3.2 Skill 到底是什么为什么它比提示词更重要搜“workbuddy skill”和“skill插件”的人很多但很多人没搞明白 Skill 和普通提示词的区别。我的理解是提示词是“你告诉 AI 怎么做”Skill 是“你给 AI 装了一个会自动执行的能力包”。前者每次都要说后者配一次就能反复用。WorkBuddy 的 Skill 机制通常包含三个部分触发条件、执行逻辑、输出格式。触发条件可以是关键词、文件类型、或者手动调用执行逻辑可以是一段脚本、一个 API 调用、或者一组预设操作输出格式决定了结果怎么呈现给你。举个例子你搜“数学建模skill”可能想的是让 AI 帮你解方程。但真正的 Skill 应该是检测到.m或.py文件时自动提取方程、调用求解器、把结果写回文件并生成报告。这才是 Skill 的价值——它不是一次性的问答而是可复用的工作流。3.3 Skill 编码 247 和常见 Skill 类型盘点“skill编码247”这个说法我查了一下大概率是指某种 Skill 编号规范或者社区约定。我的建议是别太纠结编号重点看 Skill 的功能分类。目前常见的 Skill 类型大概有这么几类Skill 类型典型用途配置难度推荐指数文件处理类批量重命名、格式转换、内容提取低高代码辅助类代码审查、注释生成、单元测试中高数据查询类本地数据库查询、表格分析中中网络请求类API 调用、网页内容抓取高中系统操作类定时任务、文件监控高低新手建议从文件处理类开始因为触发条件简单、结果直观、不容易搞崩系统。等你熟悉了 Skill 的加载和调试流程再往代码辅助和数据查询方向扩展。4. 从零搭建一个可用的 AI Agent 工作流4.1 第一步给 WorkBuddy 定几条全局规则搜“给 workbuddy 定几条规则 后续对所有任务都生效”的人说明已经意识到规则的重要性了。WorkBuddy 通常支持在设置里配置全局指令这些指令会附加到每次任务请求里。我的建议是规则不要多三到五条就够但每条都要具体。我自己的全局规则是这样的所有输出优先使用中文代码注释可以用英文。涉及文件操作时先备份原文件到backup目录。不确定的信息必须标注“待确认”不允许编造。长任务分步执行每步完成后输出进度。这四条规则覆盖了语言、安全、准确性和可追踪性。你可以根据自己的场景调整但核心思路是规则要能约束行为而不是描述愿望。像“请认真回答”这种规则写了等于没写。4.2 第二步配置第一个 Skill 并验证触发假设我们要做一个最简单的 Skill当输入包含“总结”关键词时自动读取当前目录下的notes.txt并生成摘要。配置流程大概是在 Skill 管理界面新建 Skill命名为summary-skill。触发条件设置为关键词匹配关键词填“总结”。执行逻辑选择“读取文件”路径填./notes.txt。后处理选择“调用模型生成摘要”模型选fast-model。输出格式选“追加到summary.md”。保存后在对话框输入“帮我总结一下”看它是否自动读取文件并生成摘要。如果没反应先检查 Skill 是否启用再检查关键词是否被其他规则拦截。实操心得Skill 调试最怕的是“静默失败”。建议在 Skill 里加一个调试输出比如执行时先在控制台打印“summary-skill triggered”。这样你能快速判断是触发没成功还是执行出错了。4.3 第三步用 models.json 做任务分流当你有了多个 Skill 之后任务分流就很重要了。比如文件处理类 Skill 不需要强模型用本地小模型就行代码审查类 Skill 需要强模型走主模型。这时候models.json的routing字段就派上用场了。我的配置思路是file-*开头的 Skill 走fast-model超时 15 秒。code-*开头的 Skill 走main-model超时 60 秒。没有匹配规则的走default超时 30 秒。这样配置之后简单任务响应快复杂任务也不会因为超时被截断。实测下来整体任务成功率能提升不少尤其是批量处理文件的时候不会因为一个慢请求卡住整个队列。4.4 第四步验证 Agent 是否真的“从 0 到 1”跑通了搜“从0到1搭建ai agent”的人最关心的就是怎么判断自己搭成功了。我的标准是三个能自动触发、能正确执行、能稳定复现。自动触发看日志正确执行看输出稳定复现看连续跑十次的结果是否一致。如果你连续跑十次有三次失败那说明配置还有问题。常见原因包括文件路径用了相对路径但工作目录变了、模型超时设置太短、Skill 之间有冲突。排查的时候先把其他 Skill 禁用只留一个跑通后再逐个加回来。5. 常见问题与避坑经验实录5.1 安装后打不开或闪退怎么办这是最高频的问题。我的排查顺序是先看系统日志再看安装目录下的logs文件夹最后看models.json是否格式错误。很多时候闪退是因为models.json里多了一个逗号或者少了一个引号JSON 解析失败导致整个工作台起不来。如果你改过缓存目录还要检查新目录是否有写入权限。Windows 下有时候需要手动给文件夹加“完全控制”权限。macOS 下检查是否被系统隐私设置拦截了文件访问。5.2 Skill 不触发或触发后没反应这个问题通常有三个原因触发条件写得太宽泛被其他 Skill 抢先、执行逻辑里的路径不对、后处理模型不可用。我的建议是每个 Skill 都加一个唯一的调试关键词比如debug-summary手动输入这个关键词看是否能强制触发。如果能触发但没输出那就是执行逻辑的问题如果连强制触发都不行那就是 Skill 本身没加载成功。5.3 缓存目录改到 D 盘后模型加载变慢搜“workbuddy 系统缓存目录能改到d盘吗”的人改完之后可能会发现模型加载变慢了。这通常是因为 D 盘是机械硬盘而原来系统盘是固态。AI 工作台对磁盘随机读写要求比较高如果你 D 盘是机械盘建议还是把模型文件留在固态盘只把日志和临时缓存放到 D 盘。5.4 WorkBuddy 和 CodeBuddy 配置冲突如果你两个都装了可能会遇到配置文件互相覆盖的问题。我的做法是给它们分别指定不同的配置目录。WorkBuddy 用D:\WorkBuddy\configCodeBuddy 用D:\CodeBuddy\config。安装时如果没得选装完后手动改快捷方式的启动参数加上--config-dir指定路径。5.5 常见问题速查表问题现象可能原因排查动作解决方式启动闪退models.json 格式错误用 JSON 校验工具检查修复语法错误Skill 不触发关键词被拦截查看触发日志调整关键词或优先级模型超时timeout 设置过短检查 models.json增大 timeout 值缓存目录无效权限不足检查文件夹权限手动授予完全控制输出乱码编码不一致检查文件编码统一用 UTF-8任务队列卡住某个 Skill 死循环禁用可疑 Skill修复执行逻辑6. 进阶玩法把 WorkBuddy 当成 AI Agent 中台6.1 多 Skill 编排与任务流水线当你熟悉了单个 Skill 之后可以尝试把多个 Skill 串起来。比如文件监控 Skill 检测到新文件触发内容提取 Skill提取结果再触发摘要 Skill最后触发通知 Skill。这就形成了一个简单的任务流水线。WorkBuddy 的工作台模式通常支持这种编排但要注意每个环节的输出格式要统一。我的经验是中间结果统一用 JSON 格式传递这样下游 Skill 解析起来最稳定。6.2 用 Skill 做数学建模和数据分析搜“数学建模skill”的人可能是学生或者做数据分析的。我的建议是不要指望一个 Skill 解决所有建模问题。更好的做法是拆成三个 Skill数据预处理 Skill、模型求解 Skill、结果可视化 Skill。每个 Skill 只做一件事组合起来反而更灵活。6.3 把 WorkBuddy 接入日常办公流如果你每天要处理大量邮件、文档、表格可以给 WorkBuddy 配一套办公 Skill。比如邮件分类 Skill、文档摘要 Skill、表格清洗 Skill。配置好之后每天早上让它自动跑一遍你只需要看结果就行。提示办公类 Skill 涉及隐私数据建议在本地模型上跑或者确保网络请求走的是可信通道。不要随便把敏感文件路径写进 Skill 配置里。6.4 2026 年 AI Agent 工作台的选择思路搜“2026年 国内 ai agent 智能体 产品盘点”的人可能是在选型。我的看法是选工作台重点看三件事Skill 生态是否开放、模型接入是否灵活、缓存和配置是否可控。WorkBuddy 在这三点上做得比较均衡尤其是 Skill 机制给了足够的自定义空间。如果你只是轻度使用网页版就够了。但如果你想做自动化、批量处理、本地文件操作桌面版加自定义 Skill 才是正确打开方式。7. 我踩过的坑和最后几条实用建议第一个坑是过早追求复杂 Skill。我一开始就想做一个能自动写代码、自动测试、自动提交的 Skill结果配了三天没跑通。后来退回来先做一个“读取文件并输出行数”的 Skill五分钟就跑通了。这个正反馈很重要它让你理解整个链路然后再逐步加复杂度。第二个坑是忽略日志。WorkBuddy 的日志文件里其实写得很清楚哪个 Skill 加载失败、哪个模型请求超时、哪个文件路径不存在。我一开始不看日志全靠猜浪费了很多时间。后来养成习惯每次出问题先看日志解决效率翻倍。第三个坑是缓存目录和模型目录混在一起。我试过把模型文件和缓存放同一个文件夹结果清理缓存的时候不小心把模型删了重新下载花了很久。后来严格分开models放模型cache放缓存backup放备份互不干扰。最后分享一个小技巧给 WorkBuddy 配一个“健康检查”Skill每天启动时自动跑一遍检查模型是否可用、Skill 是否加载、缓存目录是否可写。这样你每天开工前就知道环境是否正常不用等到任务跑到一半才发现问题。这个 Skill 配置很简单但省下来的时间远超配置成本。