1. 为什么我要认真写一份 WorkBuddy 实战笔记WorkBuddy 这个腾讯 AI 工作台刚出来的时候我其实没太当回事。市面上挂着“AI 工作台”名头的产品太多了大多是把聊天框换个皮再塞几个预设提示词就敢叫 Agent。真正让我改变看法是看到它能通过models.json配置模型、用 Skill 机制把能力拆成可复用的模块还能挂 MCP Server 打通外部工具——这套组合拳下来它已经不是一个聊天工具而是一个能“下地干活”的 AI Agent 运行环境。我前后在自己的主力机上装了三次帮朋友配过两次中间踩过的坑包括但不限于缓存目录默认塞在系统盘把 C 盘撑爆、Skill 加载顺序搞错导致规则不生效、模型配置写错一个字段整个工作台起不来。这些坑官方文档里要么一笔带过要么根本没提。所以这篇东西不是产品说明书是我自己从安装到日常使用攒下来的实战记录重点讲清楚三件事怎么装得干净、怎么配得明白、怎么用得顺手。适合谁看如果你是第一次接触 WorkBuddy想少走弯路快速跑起来这篇能帮你省下至少两三个小时的折腾时间。如果你已经在用但总觉得 Skill 规则时灵时不灵、模型切换不顺手那第 3 节和第 4 节应该能解决你的困惑。我不打算把它写成从入门到精通的 PDF 那种大而全的东西只讲我实际验证过、确实有用的部分。2. 安装前的准备工作与目录规划2.1 系统环境的最低要求与实测建议官方给的配置要求不算高但“能跑”和“跑得舒服”是两回事。我分别在 Windows 11、macOS Sonoma 和一台 Ubuntu 22.04 的机器上装过实测下来的感受是内存 16GB 是底线8GB 的机器开两个 Skill 再加一个模型推理就开始频繁换页体验很差。硬盘空间方面安装包本身不大但缓存和模型文件会持续增长建议至少预留 20GB 的可用空间。操作系统层面Windows 用户要注意一件事默认安装路径会往C:\Users\你的用户名\AppData下面塞东西这个目录在系统盘上用久了很容易把 C 盘吃满。macOS 相对好一些但~/Library/Application Support同样在系统盘。Linux 用户最自由可以完全自定义路径。所以不管哪个平台安装前第一件事就是规划好数据目录的位置。我自己的做法是在非系统盘建一个专门的工作目录比如D:\WorkBuddy或者/data/workbuddy把所有跟 WorkBuddy 相关的数据都往这里放。这样做的另一个好处是备份和迁移方便——哪天换机器整个目录拷过去就行不用去系统盘的犄角旮旯里翻文件。2.2 安装包获取与校验的实操细节安装包从官方渠道获取这一步没什么好说的。但我要提醒一点下载完之后最好校验一下文件完整性。我有一次下载过程中网络抖动安装包少了几个字节装到一半报错排查了半天才发现是安装包本身的问题。Windows 上用certutil -hashfile 文件名 SHA256macOS 和 Linux 上用shasum -a 256 文件名跟官方公布的哈希值对一下几秒钟的事能省掉后面一堆麻烦。安装过程本身是图形化向导一路下一步就行。但有一个选项要注意安装向导里会问你是“标准安装”还是“自定义安装”。如果你打算把数据目录放到非系统盘这里必须选自定义然后在下一步里把数据目录改掉。如果选了标准安装后面再改缓存目录就要手动编辑配置文件多一道工序。提示安装完成后先别急着启动。如果你改了数据目录先去确认一下目录权限。Windows 上一般没问题Linux 和 macOS 上如果目录属主不对WorkBuddy 启动时会因为写不了缓存而静默失败界面上什么都不显示很容易误以为是安装包坏了。2.3 首次启动前的目录结构预判WorkBuddy 首次启动时会在数据目录下生成一套子目录我观察到的结构大致是这样的models放模型相关配置和缓存skills放 Skill 模块logs放运行日志cache放临时文件config放主配置文件。提前知道这个结构有个好处当你遇到问题需要排查时能快速定位到该看哪个目录。比如 Skill 不生效先去skills目录看模块是不是真的加载进去了模型调用报错先去logs目录看错误堆栈界面卡顿或者行为异常先清cache目录试试。这套排查思路后面第 5 节还会展开讲这里先有个印象就行。3. models.json 配置让模型按你的意图工作3.1 models.json 的核心字段逐个拆解models.json是整个 WorkBuddy 的模型调度中枢它决定了工作台能用哪些模型、每个模型怎么调用、参数怎么设。这个文件的结构不算复杂但字段之间的依赖关系容易搞混。我把它拆成几个关键部分来讲。最外层是一个模型列表每个模型对象里最核心的字段是name、provider、model、apiKey和baseUrl。name是你自己起的别名在 Skill 里引用模型时用的就是这个别名所以起名要有辨识度别用model1、model2这种过两天自己都忘了哪个是哪个。provider指定服务商类型不同服务商的请求格式和鉴权方式不一样填错了会直接报鉴权失败。model是具体的模型标识符这个必须跟服务商文档里给的完全一致大小写都不能错。apiKey和baseUrl这两个字段有个坑有些服务商要求baseUrl必须带版本路径有些则不能带。我遇到过填了带/v1的地址反而 404 的情况也遇到过不填/v1就连不上的。这个没有统一规律只能以服务商文档为准。我的经验是先把baseUrl填成文档里给的示例值跑通了再考虑要不要改。3.2 多模型配置的策略与优先级设计WorkBuddy 支持同时配置多个模型这就带来一个策略问题什么任务用什么模型。我的做法是按“能力档位”来分而不是按服务商来分。比如配三个档位一个高能力档用于复杂推理和长文本处理一个均衡档用于日常对话和 Skill 执行一个快速档用于简单的格式转换和关键词提取。这样分的好处是在 Skill 里指定模型时我只需要考虑“这个任务需要多强的模型”而不用去记具体哪个服务商的哪个型号。档位和具体模型的映射关系在models.json里维护换模型时只改这一个文件所有 Skill 自动跟着变。优先级方面WorkBuddy 的默认行为是Skill 里显式指定的模型优先没指定就用全局默认模型。全局默认模型在config目录的主配置文件里设不在models.json里。这个设计容易让人混淆我第一次配的时候在models.json里找默认模型设置找了半天没找到后来才发现是在另一个文件里。3.3 配置写完后的验证方法配置写完别急着关编辑器先做两步验证。第一步是语法校验models.json是标准 JSON 格式用任何 JSON 校验工具过一遍确保没有多余的逗号、引号不匹配这类低级错误。第二步是实际调用测试WorkBuddy 启动后一般会有一个模型连通性检测的功能或者你可以建一个最简单的 Skill 让它调用指定模型回一句话看能不能正常返回。我踩过的一个坑是apiKey里不小心带了一个换行符JSON 语法上没问题但请求发出去服务端返回 401。这种错误看日志能看出来但如果不看日志只看到“模型调用失败”的提示很容易往错的方向排查。所以验证时一定要看日志日志里会打印实际的请求地址和返回码比界面上的提示信息有用得多。注意如果你在团队环境里共用models.json千万不要把真实的apiKey提交到版本控制里。我的做法是models.json里只写占位符实际密钥通过环境变量注入WorkBuddy 支持在字段值里引用环境变量。这样配置文件可以放心共享密钥也不会泄露。4. Skill 机制把重复劳动变成可复用模块4.1 Skill 到底是什么为什么它比提示词更重要很多人第一次接触 Skill 会把它理解成“高级一点的提示词”这个理解不算错但低估了它的价值。提示词是一次性的写在对话框里关掉就没了。Skill 是持久化的、可组合的、能带逻辑的模块。一个 Skill 可以包含触发条件、执行步骤、依赖的模型、调用的外部工具甚至可以有条件分支——根据上一步的结果决定下一步做什么。这就意味着你可以把“每周一早上汇总上周的销售数据并生成周报”这件事做成一个 Skill之后每周一它自动执行不需要你重新描述一遍需求。你也可以把“收到客户邮件后先分类再起草回复”做成 Skill让它按固定流程处理。Skill 的核心价值在于把“人告诉 AI 怎么做”变成“AI 按既定流程自己做”。WorkBuddy 的 Skill 还有一个我特别喜欢的特性支持规则继承。你可以定义一组全局规则比如“所有输出都用中文”“涉及金额的数字保留两位小数”“不确定的信息要标注出来”然后让所有 Skill 自动继承这些规则。这样就不用每个 Skill 都重复写一遍通用要求维护起来清爽很多。4.2 写一个 Skill 的完整流程与关键决策点写 Skill 的第一步是明确它的边界这个 Skill 负责什么、不负责什么。我见过太多 Skill 失败的原因是边界太模糊比如“帮我处理邮件”这种 Skill范围太大AI 不知道从哪下手。好的 Skill 边界应该是“把收件箱里未读邮件按紧急程度分类并给每封邮件生成一句话摘要”。边界定清楚之后接下来是定义输入和输出。输入是什么格式、包含哪些字段输出是什么结构、用什么格式呈现。这一步决定了 Skill 能不能被其他 Skill 复用。如果输入输出定义得清晰一个 Skill 的输出可以直接作为另一个 Skill 的输入形成流水线。然后是执行步骤的设计。WorkBuddy 的 Skill 支持多步骤执行每一步可以调用模型、调用工具、或者做条件判断。设计步骤时要注意每一步的输出要能被下一步直接使用不要出现“上一步给了一段自然语言下一步需要结构化数据”这种断层。如果确实需要转换中间加一个格式化的步骤。最后是异常处理。Skill 执行过程中可能遇到各种意外模型调用超时、外部工具返回错误、输入数据格式不对。好的 Skill 应该对这些情况有预案至少要在出错时给出明确的错误信息而不是默默失败。我一般会在 Skill 的最后加一个“如果前面任何一步失败输出失败原因和已完成的步骤”的逻辑方便排查。4.3 Skill 的加载顺序与规则覆盖问题这是我最想强调的一个点因为我在这个问题上浪费了最多时间。WorkBuddy 加载 Skill 是有顺序的后加载的 Skill 里的规则会覆盖先加载的同名规则。如果你有两个 Skill 都定义了“输出语言”这个规则一个说中文一个说英文最终生效的是后加载的那个。这个机制本身没问题问题在于加载顺序不直观。我一开始以为按字母顺序后来发现是按文件修改时间再后来发现好像跟目录结构也有关。实测下来比较可靠的做法是给 Skill 文件加数字前缀比如01_基础规则.skill、02_数据处理.skill、03_报告生成.skill这样加载顺序一目了然也方便调整。另一个相关的问题是规则的作用域。全局规则对所有 Skill 生效但 Skill 内部的规则只对该 Skill 生效。如果你发现某条规则“时灵时不灵”先检查它是不是被定义在了错误的层级。我遇到过把全局规则写进了某个具体 Skill 里结果只有那个 Skill 生效其他 Skill 完全不受影响排查了半天才反应过来。4.4 几个我实际在用的 Skill 示例思路说几个我日常用得最多的 Skill不是让你照抄是给你找找感觉。第一个是“会议纪要整理”。输入是一段会议录音转写的文字输出是结构化的纪要包含议题、结论、待办事项、负责人。这个 Skill 的关键在于待办事项的提取我给它加了一条规则只有明确说了“谁在什么时间之前做什么”的才算待办模糊的表述归到“待讨论”里。这条规则让输出质量提升了一大截。第二个是“代码审查辅助”。输入是一段代码 diff输出是潜在问题列表按严重程度排序。这个 Skill 我配了高能力档的模型因为代码理解对模型能力要求比较高。同时加了一条规则只报确定的问题不确定的标注为“建议关注”而不是“问题”避免误报太多导致我忽略真正重要的。第三个是“周报生成”。输入是我这一周在任务管理工具里的操作记录输出是周报草稿。这个 Skill 的难点在于把零散的操作记录归纳成有逻辑的几条工作线我给它加了一个“先聚类再总结”的步骤效果比直接总结好很多。5. 实操全流程从零搭一个能干活的工作台5.1 第一步把基础环境跑通假设你刚下载完安装包数据目录规划在D:\WorkBuddy。安装时选自定义路径指向这个目录。装完之后先别配模型直接启动一次看看能不能正常打开界面。这一步的目的是确认基础运行环境没问题把安装问题和配置问题分开排查。如果启动失败先看logs目录下的日志文件。常见的启动失败原因有三个数据目录没有写权限、端口被占用、依赖的运行库缺失。前两个看日志能直接看出来第三个在 Windows 上比较常见装一下对应的运行库就行。启动成功后先别急着关。在界面里随便发一句话看看默认行为是什么。这时候模型还没配它可能会提示你配置模型也可能用一个内置的默认模型回复。不管哪种记下它的行为后面配好模型后对比一下能帮你确认配置是否真的生效了。5.2 第二步配置模型并验证连通性打开config目录下的主配置文件找到默认模型设置先随便填一个你在models.json里配好的模型别名。然后编辑models.json按第 3 节讲的字段填一个模型进去。填完之后重启 WorkBuddy再发一句话看回复是不是来自你配的模型。验证连通性有个小技巧在models.json里把baseUrl故意写错一个字符重启后发消息看报错信息里有没有出现你写的那个错误地址。如果有说明配置确实被读取了如果没有说明配置文件根本没被加载问题出在文件路径或格式上。这个技巧能快速区分“配置写错了”和“配置没生效”两种情况。5.3 第三步写第一个 Skill 并让它跑起来第一个 Skill 建议从最简单的开始比如“把输入的文字翻译成英文”。这个 Skill 只有一个步骤调用模型翻译。写完之后保存到skills目录重启 WorkBuddy然后在对话里触发它。触发方式取决于 Skill 的定义。有的 Skill 是自动触发的根据输入内容判断有的是手动触发的需要显式调用。我建议第一个 Skill 用手动触发这样你能明确知道它有没有被执行。触发之后看输出如果输出是翻译结果说明 Skill 跑通了如果输出是原始文字或者报错说明 Skill 没被加载或者执行出错。排查 Skill 不生效的思路先确认文件在skills目录下且扩展名正确再确认文件内容格式符合规范然后看日志里有没有加载该 Skill 的记录。这三步能覆盖 90% 的 Skill 加载问题。5.4 第四步组合多个 Skill 形成工作流单个 Skill 跑通之后就可以尝试组合了。比如把“提取关键词”和“根据关键词搜索”两个 Skill 串起来形成一个“输入一段文字自动搜索相关信息”的工作流。组合的关键在于前一个 Skill 的输出格式要匹配后一个 Skill 的输入格式。WorkBuddy 里组合 Skill 的方式有两种一种是在一个 Skill 里按顺序调用多个子 Skill另一种是定义工作流把多个 Skill 编排起来。前者适合步骤固定的场景后者适合需要条件分支的场景。我一般先用第一种简单直接等流程复杂到需要根据中间结果决定下一步做什么时再换成第二种。组合之后要重点测试异常情况如果第一个 Skill 失败了第二个 Skill 会收到什么是空值还是错误信息这个行为要在设计时就考虑到否则一个环节出错会导致整个工作流输出莫名其妙的结果。6. 常见问题排查与避坑经验实录6.1 缓存目录把系统盘撑爆怎么办这是我最开始遇到的问题。WorkBuddy 默认把缓存放在系统盘的用户目录下用了一周之后 C 盘少了十几个 G。解决办法是在主配置文件里把缓存目录改到非系统盘。改完之后要把旧缓存目录里的内容迁移过去或者直接删掉让 WorkBuddy 重新生成。迁移时注意一点如果 WorkBuddy 正在运行先退出再操作。我有一次没退出就直接改配置结果新旧两个缓存目录同时存在WorkBuddy 不知道该用哪个行为变得很奇怪。退出、改配置、迁移文件、重启这个顺序不能乱。改完之后验证一下在 WorkBuddy 里执行一个会产生缓存的操作然后去看新目录下有没有生成对应的文件。如果有说明改成功了。另外建议定期清理缓存目录我一般一个月清一次能释放不少空间。6.2 Skill 规则不生效的排查清单规则不生效是最高频的问题我整理了一个排查顺序按这个顺序走基本能定位到原因。排查步骤检查内容常见问题1Skill 文件是否在 skills 目录下放错目录或扩展名不对2文件格式是否符合规范JSON 语法错误或字段名拼写错误3日志里是否有加载记录加载失败会有错误信息4规则是否被其他 Skill 覆盖后加载的同名规则会覆盖先加载的5规则作用域是否正确全局规则写成了 Skill 内部规则6触发条件是否满足自动触发的 Skill 可能没匹配到输入按这个顺序走大部分问题在前三步就能发现。如果前三步都没问题那大概率是第四步或第五步的规则覆盖问题这时候就要去检查 Skill 的加载顺序和作用域定义了。6.3 模型调用超时或返回异常的应对模型调用超时通常有两个原因网络问题和服务端限流。网络问题看日志里的请求地址能不能通服务端限流看返回码是不是 429。如果是限流解决办法要么是降低调用频率要么是配多个模型做负载均衡。返回异常的情况更复杂一些。我遇到过返回内容被截断、返回格式不符合预期、返回了空值这几种。截断一般是输出长度限制导致的调大maxTokens参数能解决。格式不符合预期通常是提示词没写清楚在 Skill 里明确指定输出格式能改善。返回空值最麻烦可能是模型本身的问题也可能是输入触发了某种过滤机制需要看日志里的原始请求和响应来定位。我的经验是给每个模型调用都加上重试逻辑失败后自动重试一到两次。很多偶发的超时和空值在重试后就能正常返回不用人工干预。但重试次数不要太多否则一个持续失败的任务会卡很久。6.4 几个我踩过的坑和对应的解法第一个坑在models.json里配了多个模型但 Skill 里引用的模型别名写错了导致 Skill 执行时找不到模型。这个问题的表现是 Skill 静默失败没有任何输出。解法是在 Skill 里加一个启动检查确认引用的模型别名在models.json里存在。第二个坑Skill 的输出格式不稳定有时候是 JSON 有时候是纯文本。原因是提示词里没有强制指定格式模型自由发挥。解法是在 Skill 的输出步骤里明确要求“以 JSON 格式输出包含以下字段”并加一个格式校验步骤不符合就重新生成。第三个坑多个 Skill 同时运行时互相干扰一个 Skill 的输出被另一个 Skill 截获了。原因是触发条件定义得太宽泛两个 Skill 都匹配到了同一个输入。解法是给触发条件加上更具体的约束或者改成手动触发避免自动匹配的歧义。第四个坑改了models.json之后忘记重启 WorkBuddy以为配置没生效反复改了好几遍。这个坑很蠢但很常见解法是养成习惯改完配置文件先重启再验证。7. 关于 WorkBuddy 使用的一些个人体会用了一段时间之后我最大的感受是WorkBuddy 这类 AI 工作台的价值不在于模型本身有多强而在于它把“调用模型”这件事工程化了。以前用聊天框每次都要重新描述需求、重新给上下文、重新纠正格式。现在把这些都固化到 Skill 里每次执行都是标准化的输出质量稳定了很多。另一个体会是Skill 的设计比模型的选择更重要。我试过用同一个模型跑不同的 Skill效果差异非常大。好的 Skill 能把一个中等能力的模型用出很好的效果差的 Skill 就算配了最强的模型也输出一堆废话。所以如果你刚开始用别在选模型上纠结太久先把 Skill 写好。最后说一个我觉得很实用的技巧给 WorkBuddy 定几条全局规则让它们对所有任务生效。我目前定的规则有三条所有输出用中文、不确定的信息必须标注、涉及数字的计算要展示过程。这三条规则让我省了很多事后检查的功夫尤其是第二条能有效减少 AI 一本正经胡说八道的情况。你可以根据自己的使用场景调整这几条规则但建议不要超过五条太多了反而会互相冲突。 腾讯 WorkBuddy 实战笔记：models.json 配置与 Skill 机制避坑指南
1. 为什么我要认真写一份 WorkBuddy 实战笔记WorkBuddy 这个腾讯 AI 工作台刚出来的时候我其实没太当回事。市面上挂着“AI 工作台”名头的产品太多了大多是把聊天框换个皮再塞几个预设提示词就敢叫 Agent。真正让我改变看法是看到它能通过models.json配置模型、用 Skill 机制把能力拆成可复用的模块还能挂 MCP Server 打通外部工具——这套组合拳下来它已经不是一个聊天工具而是一个能“下地干活”的 AI Agent 运行环境。我前后在自己的主力机上装了三次帮朋友配过两次中间踩过的坑包括但不限于缓存目录默认塞在系统盘把 C 盘撑爆、Skill 加载顺序搞错导致规则不生效、模型配置写错一个字段整个工作台起不来。这些坑官方文档里要么一笔带过要么根本没提。所以这篇东西不是产品说明书是我自己从安装到日常使用攒下来的实战记录重点讲清楚三件事怎么装得干净、怎么配得明白、怎么用得顺手。适合谁看如果你是第一次接触 WorkBuddy想少走弯路快速跑起来这篇能帮你省下至少两三个小时的折腾时间。如果你已经在用但总觉得 Skill 规则时灵时不灵、模型切换不顺手那第 3 节和第 4 节应该能解决你的困惑。我不打算把它写成从入门到精通的 PDF 那种大而全的东西只讲我实际验证过、确实有用的部分。2. 安装前的准备工作与目录规划2.1 系统环境的最低要求与实测建议官方给的配置要求不算高但“能跑”和“跑得舒服”是两回事。我分别在 Windows 11、macOS Sonoma 和一台 Ubuntu 22.04 的机器上装过实测下来的感受是内存 16GB 是底线8GB 的机器开两个 Skill 再加一个模型推理就开始频繁换页体验很差。硬盘空间方面安装包本身不大但缓存和模型文件会持续增长建议至少预留 20GB 的可用空间。操作系统层面Windows 用户要注意一件事默认安装路径会往C:\Users\你的用户名\AppData下面塞东西这个目录在系统盘上用久了很容易把 C 盘吃满。macOS 相对好一些但~/Library/Application Support同样在系统盘。Linux 用户最自由可以完全自定义路径。所以不管哪个平台安装前第一件事就是规划好数据目录的位置。我自己的做法是在非系统盘建一个专门的工作目录比如D:\WorkBuddy或者/data/workbuddy把所有跟 WorkBuddy 相关的数据都往这里放。这样做的另一个好处是备份和迁移方便——哪天换机器整个目录拷过去就行不用去系统盘的犄角旮旯里翻文件。2.2 安装包获取与校验的实操细节安装包从官方渠道获取这一步没什么好说的。但我要提醒一点下载完之后最好校验一下文件完整性。我有一次下载过程中网络抖动安装包少了几个字节装到一半报错排查了半天才发现是安装包本身的问题。Windows 上用certutil -hashfile 文件名 SHA256macOS 和 Linux 上用shasum -a 256 文件名跟官方公布的哈希值对一下几秒钟的事能省掉后面一堆麻烦。安装过程本身是图形化向导一路下一步就行。但有一个选项要注意安装向导里会问你是“标准安装”还是“自定义安装”。如果你打算把数据目录放到非系统盘这里必须选自定义然后在下一步里把数据目录改掉。如果选了标准安装后面再改缓存目录就要手动编辑配置文件多一道工序。提示安装完成后先别急着启动。如果你改了数据目录先去确认一下目录权限。Windows 上一般没问题Linux 和 macOS 上如果目录属主不对WorkBuddy 启动时会因为写不了缓存而静默失败界面上什么都不显示很容易误以为是安装包坏了。2.3 首次启动前的目录结构预判WorkBuddy 首次启动时会在数据目录下生成一套子目录我观察到的结构大致是这样的models放模型相关配置和缓存skills放 Skill 模块logs放运行日志cache放临时文件config放主配置文件。提前知道这个结构有个好处当你遇到问题需要排查时能快速定位到该看哪个目录。比如 Skill 不生效先去skills目录看模块是不是真的加载进去了模型调用报错先去logs目录看错误堆栈界面卡顿或者行为异常先清cache目录试试。这套排查思路后面第 5 节还会展开讲这里先有个印象就行。3. models.json 配置让模型按你的意图工作3.1 models.json 的核心字段逐个拆解models.json是整个 WorkBuddy 的模型调度中枢它决定了工作台能用哪些模型、每个模型怎么调用、参数怎么设。这个文件的结构不算复杂但字段之间的依赖关系容易搞混。我把它拆成几个关键部分来讲。最外层是一个模型列表每个模型对象里最核心的字段是name、provider、model、apiKey和baseUrl。name是你自己起的别名在 Skill 里引用模型时用的就是这个别名所以起名要有辨识度别用model1、model2这种过两天自己都忘了哪个是哪个。provider指定服务商类型不同服务商的请求格式和鉴权方式不一样填错了会直接报鉴权失败。model是具体的模型标识符这个必须跟服务商文档里给的完全一致大小写都不能错。apiKey和baseUrl这两个字段有个坑有些服务商要求baseUrl必须带版本路径有些则不能带。我遇到过填了带/v1的地址反而 404 的情况也遇到过不填/v1就连不上的。这个没有统一规律只能以服务商文档为准。我的经验是先把baseUrl填成文档里给的示例值跑通了再考虑要不要改。3.2 多模型配置的策略与优先级设计WorkBuddy 支持同时配置多个模型这就带来一个策略问题什么任务用什么模型。我的做法是按“能力档位”来分而不是按服务商来分。比如配三个档位一个高能力档用于复杂推理和长文本处理一个均衡档用于日常对话和 Skill 执行一个快速档用于简单的格式转换和关键词提取。这样分的好处是在 Skill 里指定模型时我只需要考虑“这个任务需要多强的模型”而不用去记具体哪个服务商的哪个型号。档位和具体模型的映射关系在models.json里维护换模型时只改这一个文件所有 Skill 自动跟着变。优先级方面WorkBuddy 的默认行为是Skill 里显式指定的模型优先没指定就用全局默认模型。全局默认模型在config目录的主配置文件里设不在models.json里。这个设计容易让人混淆我第一次配的时候在models.json里找默认模型设置找了半天没找到后来才发现是在另一个文件里。3.3 配置写完后的验证方法配置写完别急着关编辑器先做两步验证。第一步是语法校验models.json是标准 JSON 格式用任何 JSON 校验工具过一遍确保没有多余的逗号、引号不匹配这类低级错误。第二步是实际调用测试WorkBuddy 启动后一般会有一个模型连通性检测的功能或者你可以建一个最简单的 Skill 让它调用指定模型回一句话看能不能正常返回。我踩过的一个坑是apiKey里不小心带了一个换行符JSON 语法上没问题但请求发出去服务端返回 401。这种错误看日志能看出来但如果不看日志只看到“模型调用失败”的提示很容易往错的方向排查。所以验证时一定要看日志日志里会打印实际的请求地址和返回码比界面上的提示信息有用得多。注意如果你在团队环境里共用models.json千万不要把真实的apiKey提交到版本控制里。我的做法是models.json里只写占位符实际密钥通过环境变量注入WorkBuddy 支持在字段值里引用环境变量。这样配置文件可以放心共享密钥也不会泄露。4. Skill 机制把重复劳动变成可复用模块4.1 Skill 到底是什么为什么它比提示词更重要很多人第一次接触 Skill 会把它理解成“高级一点的提示词”这个理解不算错但低估了它的价值。提示词是一次性的写在对话框里关掉就没了。Skill 是持久化的、可组合的、能带逻辑的模块。一个 Skill 可以包含触发条件、执行步骤、依赖的模型、调用的外部工具甚至可以有条件分支——根据上一步的结果决定下一步做什么。这就意味着你可以把“每周一早上汇总上周的销售数据并生成周报”这件事做成一个 Skill之后每周一它自动执行不需要你重新描述一遍需求。你也可以把“收到客户邮件后先分类再起草回复”做成 Skill让它按固定流程处理。Skill 的核心价值在于把“人告诉 AI 怎么做”变成“AI 按既定流程自己做”。WorkBuddy 的 Skill 还有一个我特别喜欢的特性支持规则继承。你可以定义一组全局规则比如“所有输出都用中文”“涉及金额的数字保留两位小数”“不确定的信息要标注出来”然后让所有 Skill 自动继承这些规则。这样就不用每个 Skill 都重复写一遍通用要求维护起来清爽很多。4.2 写一个 Skill 的完整流程与关键决策点写 Skill 的第一步是明确它的边界这个 Skill 负责什么、不负责什么。我见过太多 Skill 失败的原因是边界太模糊比如“帮我处理邮件”这种 Skill范围太大AI 不知道从哪下手。好的 Skill 边界应该是“把收件箱里未读邮件按紧急程度分类并给每封邮件生成一句话摘要”。边界定清楚之后接下来是定义输入和输出。输入是什么格式、包含哪些字段输出是什么结构、用什么格式呈现。这一步决定了 Skill 能不能被其他 Skill 复用。如果输入输出定义得清晰一个 Skill 的输出可以直接作为另一个 Skill 的输入形成流水线。然后是执行步骤的设计。WorkBuddy 的 Skill 支持多步骤执行每一步可以调用模型、调用工具、或者做条件判断。设计步骤时要注意每一步的输出要能被下一步直接使用不要出现“上一步给了一段自然语言下一步需要结构化数据”这种断层。如果确实需要转换中间加一个格式化的步骤。最后是异常处理。Skill 执行过程中可能遇到各种意外模型调用超时、外部工具返回错误、输入数据格式不对。好的 Skill 应该对这些情况有预案至少要在出错时给出明确的错误信息而不是默默失败。我一般会在 Skill 的最后加一个“如果前面任何一步失败输出失败原因和已完成的步骤”的逻辑方便排查。4.3 Skill 的加载顺序与规则覆盖问题这是我最想强调的一个点因为我在这个问题上浪费了最多时间。WorkBuddy 加载 Skill 是有顺序的后加载的 Skill 里的规则会覆盖先加载的同名规则。如果你有两个 Skill 都定义了“输出语言”这个规则一个说中文一个说英文最终生效的是后加载的那个。这个机制本身没问题问题在于加载顺序不直观。我一开始以为按字母顺序后来发现是按文件修改时间再后来发现好像跟目录结构也有关。实测下来比较可靠的做法是给 Skill 文件加数字前缀比如01_基础规则.skill、02_数据处理.skill、03_报告生成.skill这样加载顺序一目了然也方便调整。另一个相关的问题是规则的作用域。全局规则对所有 Skill 生效但 Skill 内部的规则只对该 Skill 生效。如果你发现某条规则“时灵时不灵”先检查它是不是被定义在了错误的层级。我遇到过把全局规则写进了某个具体 Skill 里结果只有那个 Skill 生效其他 Skill 完全不受影响排查了半天才反应过来。4.4 几个我实际在用的 Skill 示例思路说几个我日常用得最多的 Skill不是让你照抄是给你找找感觉。第一个是“会议纪要整理”。输入是一段会议录音转写的文字输出是结构化的纪要包含议题、结论、待办事项、负责人。这个 Skill 的关键在于待办事项的提取我给它加了一条规则只有明确说了“谁在什么时间之前做什么”的才算待办模糊的表述归到“待讨论”里。这条规则让输出质量提升了一大截。第二个是“代码审查辅助”。输入是一段代码 diff输出是潜在问题列表按严重程度排序。这个 Skill 我配了高能力档的模型因为代码理解对模型能力要求比较高。同时加了一条规则只报确定的问题不确定的标注为“建议关注”而不是“问题”避免误报太多导致我忽略真正重要的。第三个是“周报生成”。输入是我这一周在任务管理工具里的操作记录输出是周报草稿。这个 Skill 的难点在于把零散的操作记录归纳成有逻辑的几条工作线我给它加了一个“先聚类再总结”的步骤效果比直接总结好很多。5. 实操全流程从零搭一个能干活的工作台5.1 第一步把基础环境跑通假设你刚下载完安装包数据目录规划在D:\WorkBuddy。安装时选自定义路径指向这个目录。装完之后先别配模型直接启动一次看看能不能正常打开界面。这一步的目的是确认基础运行环境没问题把安装问题和配置问题分开排查。如果启动失败先看logs目录下的日志文件。常见的启动失败原因有三个数据目录没有写权限、端口被占用、依赖的运行库缺失。前两个看日志能直接看出来第三个在 Windows 上比较常见装一下对应的运行库就行。启动成功后先别急着关。在界面里随便发一句话看看默认行为是什么。这时候模型还没配它可能会提示你配置模型也可能用一个内置的默认模型回复。不管哪种记下它的行为后面配好模型后对比一下能帮你确认配置是否真的生效了。5.2 第二步配置模型并验证连通性打开config目录下的主配置文件找到默认模型设置先随便填一个你在models.json里配好的模型别名。然后编辑models.json按第 3 节讲的字段填一个模型进去。填完之后重启 WorkBuddy再发一句话看回复是不是来自你配的模型。验证连通性有个小技巧在models.json里把baseUrl故意写错一个字符重启后发消息看报错信息里有没有出现你写的那个错误地址。如果有说明配置确实被读取了如果没有说明配置文件根本没被加载问题出在文件路径或格式上。这个技巧能快速区分“配置写错了”和“配置没生效”两种情况。5.3 第三步写第一个 Skill 并让它跑起来第一个 Skill 建议从最简单的开始比如“把输入的文字翻译成英文”。这个 Skill 只有一个步骤调用模型翻译。写完之后保存到skills目录重启 WorkBuddy然后在对话里触发它。触发方式取决于 Skill 的定义。有的 Skill 是自动触发的根据输入内容判断有的是手动触发的需要显式调用。我建议第一个 Skill 用手动触发这样你能明确知道它有没有被执行。触发之后看输出如果输出是翻译结果说明 Skill 跑通了如果输出是原始文字或者报错说明 Skill 没被加载或者执行出错。排查 Skill 不生效的思路先确认文件在skills目录下且扩展名正确再确认文件内容格式符合规范然后看日志里有没有加载该 Skill 的记录。这三步能覆盖 90% 的 Skill 加载问题。5.4 第四步组合多个 Skill 形成工作流单个 Skill 跑通之后就可以尝试组合了。比如把“提取关键词”和“根据关键词搜索”两个 Skill 串起来形成一个“输入一段文字自动搜索相关信息”的工作流。组合的关键在于前一个 Skill 的输出格式要匹配后一个 Skill 的输入格式。WorkBuddy 里组合 Skill 的方式有两种一种是在一个 Skill 里按顺序调用多个子 Skill另一种是定义工作流把多个 Skill 编排起来。前者适合步骤固定的场景后者适合需要条件分支的场景。我一般先用第一种简单直接等流程复杂到需要根据中间结果决定下一步做什么时再换成第二种。组合之后要重点测试异常情况如果第一个 Skill 失败了第二个 Skill 会收到什么是空值还是错误信息这个行为要在设计时就考虑到否则一个环节出错会导致整个工作流输出莫名其妙的结果。6. 常见问题排查与避坑经验实录6.1 缓存目录把系统盘撑爆怎么办这是我最开始遇到的问题。WorkBuddy 默认把缓存放在系统盘的用户目录下用了一周之后 C 盘少了十几个 G。解决办法是在主配置文件里把缓存目录改到非系统盘。改完之后要把旧缓存目录里的内容迁移过去或者直接删掉让 WorkBuddy 重新生成。迁移时注意一点如果 WorkBuddy 正在运行先退出再操作。我有一次没退出就直接改配置结果新旧两个缓存目录同时存在WorkBuddy 不知道该用哪个行为变得很奇怪。退出、改配置、迁移文件、重启这个顺序不能乱。改完之后验证一下在 WorkBuddy 里执行一个会产生缓存的操作然后去看新目录下有没有生成对应的文件。如果有说明改成功了。另外建议定期清理缓存目录我一般一个月清一次能释放不少空间。6.2 Skill 规则不生效的排查清单规则不生效是最高频的问题我整理了一个排查顺序按这个顺序走基本能定位到原因。排查步骤检查内容常见问题1Skill 文件是否在 skills 目录下放错目录或扩展名不对2文件格式是否符合规范JSON 语法错误或字段名拼写错误3日志里是否有加载记录加载失败会有错误信息4规则是否被其他 Skill 覆盖后加载的同名规则会覆盖先加载的5规则作用域是否正确全局规则写成了 Skill 内部规则6触发条件是否满足自动触发的 Skill 可能没匹配到输入按这个顺序走大部分问题在前三步就能发现。如果前三步都没问题那大概率是第四步或第五步的规则覆盖问题这时候就要去检查 Skill 的加载顺序和作用域定义了。6.3 模型调用超时或返回异常的应对模型调用超时通常有两个原因网络问题和服务端限流。网络问题看日志里的请求地址能不能通服务端限流看返回码是不是 429。如果是限流解决办法要么是降低调用频率要么是配多个模型做负载均衡。返回异常的情况更复杂一些。我遇到过返回内容被截断、返回格式不符合预期、返回了空值这几种。截断一般是输出长度限制导致的调大maxTokens参数能解决。格式不符合预期通常是提示词没写清楚在 Skill 里明确指定输出格式能改善。返回空值最麻烦可能是模型本身的问题也可能是输入触发了某种过滤机制需要看日志里的原始请求和响应来定位。我的经验是给每个模型调用都加上重试逻辑失败后自动重试一到两次。很多偶发的超时和空值在重试后就能正常返回不用人工干预。但重试次数不要太多否则一个持续失败的任务会卡很久。6.4 几个我踩过的坑和对应的解法第一个坑在models.json里配了多个模型但 Skill 里引用的模型别名写错了导致 Skill 执行时找不到模型。这个问题的表现是 Skill 静默失败没有任何输出。解法是在 Skill 里加一个启动检查确认引用的模型别名在models.json里存在。第二个坑Skill 的输出格式不稳定有时候是 JSON 有时候是纯文本。原因是提示词里没有强制指定格式模型自由发挥。解法是在 Skill 的输出步骤里明确要求“以 JSON 格式输出包含以下字段”并加一个格式校验步骤不符合就重新生成。第三个坑多个 Skill 同时运行时互相干扰一个 Skill 的输出被另一个 Skill 截获了。原因是触发条件定义得太宽泛两个 Skill 都匹配到了同一个输入。解法是给触发条件加上更具体的约束或者改成手动触发避免自动匹配的歧义。第四个坑改了models.json之后忘记重启 WorkBuddy以为配置没生效反复改了好几遍。这个坑很蠢但很常见解法是养成习惯改完配置文件先重启再验证。7. 关于 WorkBuddy 使用的一些个人体会用了一段时间之后我最大的感受是WorkBuddy 这类 AI 工作台的价值不在于模型本身有多强而在于它把“调用模型”这件事工程化了。以前用聊天框每次都要重新描述需求、重新给上下文、重新纠正格式。现在把这些都固化到 Skill 里每次执行都是标准化的输出质量稳定了很多。另一个体会是Skill 的设计比模型的选择更重要。我试过用同一个模型跑不同的 Skill效果差异非常大。好的 Skill 能把一个中等能力的模型用出很好的效果差的 Skill 就算配了最强的模型也输出一堆废话。所以如果你刚开始用别在选模型上纠结太久先把 Skill 写好。最后说一个我觉得很实用的技巧给 WorkBuddy 定几条全局规则让它们对所有任务生效。我目前定的规则有三条所有输出用中文、不确定的信息必须标注、涉及数字的计算要展示过程。这三条规则让我省了很多事后检查的功夫尤其是第二条能有效减少 AI 一本正经胡说八道的情况。你可以根据自己的使用场景调整这几条规则但建议不要超过五条太多了反而会互相冲突。