WorkBuddy 实战指南：models.json 配置、Skill 开发与并发调优

1. 为什么我最终把 WorkBuddy 当成了主力工作台第一次接触 WorkBuddy 是在一个项目排期最紧的时候。当时团队里同时在跑三四个自动化任务有的要抓数据、有的要生成周报、有的要定时整理会议纪要工具换来换去配置散落在各个角落维护成本高得离谱。后来有人提了一句你试试 WorkBuddy我抱着试试看的心态装了一次结果这一装就再也没换回去。WorkBuddy 是腾讯推出的 AI 工作台产品核心定位不是再做一个聊天框而是把 AI Agent 的能力真正落到日常工作任务上。它通过Skill技能机制把一个个具体能力拆成可复用、可组合的模块再通过models.json这样的配置文件把模型接入、参数调优、任务编排统一管理起来。简单说它解决的是AI 能聊天但干不了活这个老问题——让 AI 真的能下地干活而不是停留在对话框里陪你唠嗑。这篇内容适合几类人看一是刚听说 WorkBuddy、想搞清楚它到底能干什么的新手二是已经装上了但卡在配置、Skill 编写、缓存目录这些细节上的中级用户三是想把它当成团队 AI Agent 中台来用的技术负责人。我会从安装讲起一路讲到 Skill 开发、models.json 配置、并发处理、避坑经验尽量把每个为什么都讲透而不是只丢一堆步骤让你照抄。需要先说明一点WorkBuddy 和 CodeBuddy 经常被放在一起讨论两者定位不同。CodeBuddy 更偏向编码辅助场景而 WorkBuddy 是面向通用工作任务的 AI 工作台Skill 体系是它的核心差异点。搞清楚这个区别后面的很多设计选择就顺了。2. 安装前的环境判断与版本选择2.1 先想清楚你要的是国内版还是国际版WorkBuddy 有国内版和国际版两个分发渠道这不是简单的语言不同而是涉及账号体系、可用模型、Skill 生态、网络环境适配等一整套差异。我的建议很直接如果你主要处理中文工作任务、团队都在国内协作环境里优先用国内版模型接入和 Skill 商店的匹配度更高如果你有跨境协作需求、需要对接某些海外服务再考虑国际版。很多人一上来就问哪个版本更强这其实是个伪命题。版本选择的核心依据是你的任务场景和协作对象而不是版本本身的绝对优劣。我见过有人为了尝鲜装了国际版结果发现常用的几个 Skill 在国内版生态里更新更勤又折腾着换回来白白浪费半天。2.2 安装过程中最容易忽略的三个细节安装本身不复杂下载、运行、登录三步走。但真正决定你后续顺不顺手的是安装阶段这几个容易被跳过的设置第一安装路径不要带中文和空格。这是老生常谈但每年都有人踩的坑。WorkBuddy 底层会调用一些命令行工具和脚本执行环境路径里有中文或空格时某些 Skill 的调用会莫名其妙失败报错信息还特别隐晦你根本想不到是路径问题。我一般直接装在D:\WorkBuddy或~/workbuddy这种干净路径下。第二首次启动时留意默认的工作目录和缓存目录。WorkBuddy 默认会把缓存、日志、临时文件放在系统盘的用户目录下。如果你像我一样系统盘空间紧张或者习惯把工作数据集中管理一定要在第一次启动后就去设置里改掉。缓存目录堆积起来非常快尤其是频繁跑 Skill 的时候几周就能吃掉好几个 G。第三登录后先别急着装 Skill先把模型配置跑通。很多人装完就冲进 Skill 商店一顿下载结果发现模型没配好Skill 全都跑不起来。正确的顺序是登录 → 配置模型models.json→ 测试一次基础对话 → 再装 Skill。2.3 更改系统缓存目录的完整操作缓存目录这个问题值得单独说因为问的人太多了。默认路径通常在系统盘改的时候要注意几点新目录必须是已存在的空目录不要指向一个已经有其他程序在用的文件夹否则可能互相覆盖。改完之后建议重启一次 WorkBuddy让配置生效。如果你之前已经跑过一段时间旧缓存目录里的内容可以手动迁移过去也可以直接删掉让它重新生成——但删之前确认里面没有你需要的日志。我自己的做法是专门建一个workbuddy-data目录下面再分cache、logs、skills三个子目录这样备份和清理都很清晰。这个习惯是从踩过缓存和日志混在一起、出问题时找不到关键日志的坑之后养成的。3. models.json 配置整个工作台的神经中枢3.1 models.json 到底管什么如果把 WorkBuddy 比作一台机器Skill 是各种功能模块那models.json就是决定这台机器用哪个大脑运转的控制文件。它主要管三件事接入哪些模型、每个模型的调用参数、以及不同任务场景下默认用哪个模型。很多人对 models.json 有误解以为它只是个简单的模型列表。实际上它承担的是路由和调优的职责。比如你可以配置一个快速模型处理日常问答一个强推理模型处理复杂任务再通过规则让 WorkBuddy 根据任务类型自动选择。这个设计的好处是成本和效果能平衡——不是所有任务都需要最强模型杀鸡用牛刀既慢又贵。3.2 一份可参考的配置结构下面这份结构是我在实际使用中整理出来的字段命名以官方文档为准这里重点讲每个字段的作用和配置思路{ models: [ { name: fast-model, provider: your-provider, model: model-id, temperature: 0.3, maxTokens: 2048, timeout: 30 }, { name: reasoning-model, provider: your-provider, model: model-id, temperature: 0.7, maxTokens: 8192, timeout: 120 } ], defaultModel: fast-model, taskRouting: { chat: fast-model, code: reasoning-model, analysis: reasoning-model } }几个关键点解释一下temperature 的取值逻辑。日常对话、信息提取这类任务temperature 设低一点0.2~0.4输出更稳定、更可控创意生成、头脑风暴类任务可以设高一点0.7~0.9让输出更多样。我见过有人所有任务都用默认值结果要么太死板要么太飘其实就是没根据场景调。maxTokens 和 timeout 要配套。如果你把 maxTokens 设得很大但 timeout 很短长任务会在生成到一半时被掐断报错还不好定位。经验值是maxTokens 每 1000 token 大约需要 10~15 秒的生成时间timeout 要留足余量。复杂分析任务我一般给到 120 秒以上。taskRouting 是提效的关键。配好路由之后你不需要每次手动选模型WorkBuddy 会根据任务类型自动匹配。这个功能在团队协作场景下尤其有用能避免每个人都用最强模型跑简单任务造成的资源浪费。3.3 配置改完不生效先查这三个地方models.json 改完没反应是最常见的求助问题之一。按我的排查顺序JSON 格式是否合法。多一个逗号、少一个引号整个文件就废了。建议用编辑器的 JSON 校验功能先过一遍。是否重启了 WorkBuddy。部分配置是启动时加载的热更新不一定覆盖所有字段。字段名是否拼写正确。大小写敏感maxTokens写成maxtokens就是无效配置而且不会报错只会静默忽略。提示改 models.json 之前先备份一份。我吃过一次亏改错了一个字段导致整个工作台起不来又没有备份只能重装。4. Skill 机制WorkBuddy 真正的战斗力来源4.1 Skill 是什么为什么它比提示词更值得投入Skill 可以理解成封装好的能力单元。一个 Skill 通常包含触发条件、执行逻辑、依赖的工具或接口、输出格式。它和普通提示词的本质区别在于——提示词是一次性的Skill 是可复用、可组合、可版本管理的。举个例子你让 AI帮我整理今天的会议纪要用提示词你得每次把格式要求、输出结构重新说一遍做成 Skill 之后你只要触发它格式、逻辑、输出全都固定好了而且可以分享给团队其他人用。这就是为什么我说 Skill 才是 WorkBuddy 的核心价值值得花时间投入。从热词里能看到很多相关概念agent skill、skill 插件、skill 脚本、skill 开发指南、book to skill、去 AI 味的 skill……这些其实都指向同一个方向——把重复性的工作沉淀成 Skill。我个人的判断是未来衡量一个人 AI 工作台用得好不好很大程度上看他积累了多少高质量 Skill。4.2 一个 Skill 的典型结构拆解虽然不同版本的 Skill 定义格式略有差异但核心结构是相通的。一个完整的 Skill 一般包含这几部分组成部分作用编写要点元信息名称、描述、版本、作者描述要写清楚什么时候该用它这是被正确触发的关键触发条件什么情况下激活这个 Skill写得太宽会误触发太窄会漏触发执行逻辑具体做什么、分几步步骤要原子化每步职责单一依赖声明需要哪些工具、接口、模型依赖缺失是 Skill 跑失败的头号原因输出规范结果以什么格式返回固定格式便于后续 Skill 串联我特别想强调元信息里的描述。很多人写 Skill 描述就写一句处理文档结果这个 Skill 要么从不被触发要么在不该触发的时候乱触发。好的描述应该像这样当用户需要把会议录音转写文本整理成结构化纪要时使用输入为纯文本输出为带议题、结论、待办的 Markdown。这样 AI 才能准确判断调用时机。4.3 从零写一个 Skill 的实操思路写 Skill 不要一上来就追求复杂。我的建议是从你每天重复做的一件小事开始。比如我写的第一个 Skill 是把零散的需求描述整理成标准任务卡逻辑很简单接收一段自由文本 → 提取关键信息 → 按固定模板输出。就这么个简单东西帮我省了大量重复劳动。写的时候注意几个原则单一职责。一个 Skill 只干一件事。想干多件事就拆成多个 Skill 再串联这样每个都可独立测试和复用。输入输出明确。输入是什么格式、输出是什么格式写死在 Skill 里不要依赖AI 自己理解。可测试。写完先用几个典型输入跑一遍看看输出是否符合预期再拿去实际用。留好错误处理。输入不符合预期时Skill 应该给出清晰提示而不是直接崩掉。关于去 AI 味的 skill这个热词我的理解是很多 Skill 生成的内容一眼就能看出是 AI 写的套话多、结构僵。解决办法是在 Skill 里加入风格约束比如指定语气、禁用某些模板化表达、要求用具体案例代替泛泛而谈。这个思路和我写这篇内容的原则其实是一样的。4.4 Skill 组合从单点能力到工作流单个 Skill 解决单点问题多个 Skill 串联起来才能形成完整工作流。WorkBuddy 支持把 Skill 按顺序编排前一个的输出作为后一个的输入。这个能力用好了能搭出相当复杂的自动化流程。举个我实际搭过的例子一个周报生成工作流由四个 Skill 串联——第一个抓取本周的任务记录第二个提取完成项和阻塞项第三个按团队模板组织内容第四个做语言润色。整个过程一键触发几分钟出结果以前手动整理要花小半个小时。组合的时候最容易出问题的地方是数据格式衔接。前一个 Skill 输出的是 JSON后一个 Skill 期望的是纯文本中间就会断。所以我在写每个 Skill 时都会明确标注输入输出格式组合前先确认能对上。5. 并发与稳定性AI Agent 扛并发的真实经验5.1 为什么并发是绕不开的坎AI Agent 怎么扛并发是个高频问题。当你把 WorkBuddy 用在团队场景多个任务同时触发、多个 Skill 并行执行时问题就来了模型调用被限流、任务排队、部分任务超时失败。这个问题的本质是资源竞争。模型接口有速率限制本地执行环境有 CPU 和内存上限Skill 依赖的外部服务也有各自的承载能力。并发上不去通常不是某一个环节的问题而是整条链路上最慢的那一环在拖后腿。5.2 我踩过的并发坑和解决思路坑一无脑并发导致大面积超时。一开始我让所有任务同时发起结果模型接口直接限流一半任务失败。后来改成分批 队列控制同时执行的任务数稳定性立刻上来了。坑二长任务阻塞短任务。一个耗时两分钟的分析任务占着资源后面一堆几秒钟的小任务干等着。解决办法是按任务类型分队列快任务和慢任务走不同的通道互不阻塞。坑三失败重试没有退避。任务失败后立刻重试结果越重试越堵。正确的做法是指数退避——第一次失败等 1 秒第二次等 2 秒第三次等 4 秒给系统喘息的空间。下面这张表是我总结的并发调优对照问题现象根本原因调整方向大面积超时并发数超过接口限流降低并发、加队列短任务被拖慢长短任务混跑分队列隔离重试雪崩无退避的立即重试指数退避 上限内存飙升并发任务缓存未释放限制单任务内存、及时清理5.3 稳定性比峰值性能更重要做 AI Agent 有个心态上的转变很重要别追求能同时跑多少要追求跑多久不出错。峰值性能好看但生产环境里稳定才是王道。我现在的配置原则是并发数留 30% 余量宁可慢一点也不要因为打满资源导致整批任务失败。另外日志一定要开全。并发场景下出问题没有详细日志根本没法定位是哪个任务、哪个 Skill、哪一步出的错。我专门配了一个日志目录按天切分出问题时能快速回溯。6. 那些没人告诉你但一定会踩的坑6.1 规则设置让 WorkBuddy 记住你的偏好WorkBuddy 支持设置全局规则让某些要求对所有任务生效。这个功能用好了能省很多重复沟通。比如我设了几条所有输出默认用中文除非明确要求其他语言。生成的内容避免使用综上所述随着……的发展这类模板化表达。涉及数据的结论必须标注来源或计算过程。这几条规则一设后面所有任务都自动遵守不用每次重复交代。热词里给 workbuddy 定几条规则后续对所有任务都生效说的就是这个。我的经验是规则不要设太多5 条以内聚焦最高频的偏好设多了反而互相冲突。6.2 Skill 装了却用不起来按这个顺序查Skill 装了不生效排查顺序建议是模型是否配置正确。Skill 依赖模型模型没配好一切白搭。依赖是否齐全。有些 Skill 需要额外的工具或接口权限缺了就跑不起来。触发条件是否匹配。你的输入没命中 Skill 的触发条件它自然不会启动。版本是否兼容。老版本 Skill 在新版本 WorkBuddy 上可能不兼容去商店看看有没有更新。6.3 关于哪些 Skill 最好用的实话经常有人问 WorkBuddy 哪些 Skill 最好用。我的看法是没有普适的最好用只有最适合你场景的。别人推荐的文档处理 Skill如果你不做文档工作装了也是吃灰。我的建议是先从自己的高频任务出发缺什么补什么。用一段时间后你会发现真正天天用的可能就那么三五个 Skill但每一个都深度嵌入了你的工作流。与其装一堆用不上的不如把几个核心的用透。6.4 数据安全和备份最后说个容易被忽略的点备份。你的 models.json、自定义 Skill、规则配置这些都是心血一旦丢失重来很痛苦。我现在的做法是定期把配置目录打包备份改配置前先存一份。这个习惯帮我躲过好几次改崩了想回滚的窘境。7. 我个人的使用体会用 WorkBuddy 这段时间最大的感受是它的价值不在于AI 多聪明而在于你把多少重复劳动沉淀成了可复用的能力。刚开始我也只是拿它当个高级聊天工具直到开始认真写 Skill、配 models.json、设全局规则才真正体会到工作台和聊天框的区别。如果你刚上手我的建议是别贪多。先把模型配通写一两个解决自己实际痛点的 Skill用顺了再逐步扩展。AI Agent 这东西用起来容易用好需要积累而积累的核心就是那些你亲手打磨的 Skill 和规则。后续我还会继续折腾 Skill 组合和并发调优有新发现再分享。如果你在配置或 Skill 编写上卡住了大概率是上面提到的某几个坑按顺序排查一遍基本都能解决。