WorkBuddy 实战指南：从 models.json 配置到 Skill 开发与团队中台搭建

1. 为什么我要认真写这篇 WorkBuddy 实战指南

WorkBuddy 这个腾讯出的 AI 工作台，我从它内测阶段就开始折腾，到现在团队里十几个人的日常任务流基本都跑在上面。说实话，第一次打开它的时候我是有点懵的——界面看着不复杂，但真要让它"下地干活"，中间踩的坑比我预想的多得多。网上那些"三分钟上手"的教程，基本只告诉你点哪个按钮，没人讲清楚 models.json 到底怎么配、Skill 的触发边界在哪里、缓存目录塞满 C 盘之后该怎么办。

这篇东西就是把我这段时间的实操经验完整倒出来。从安装、模型配置、Skill 编写、工作台搭建，到并发扛不住、Skill 不触发、缓存爆盘这些真实问题，我都会给到具体的排查路径和解决方案。适合两类人看：一类是刚接触 WorkBuddy、想把它当成日常生产力工具的个人用户；另一类是打算在团队里落地 AI Agent 工作流、需要搞清楚 Skill 机制和中台思路的技术同学。不管你是想让 AI 帮你写周报、做备课、跑数据分析，还是想搭一套能扛住多人并发的智能体中台，下面的内容应该都能直接抄作业。

我尽量不写那种"官方文档翻译"式的废话，每个结论背后我都会说清楚为什么这么做、不这么做会出什么问题。有些地方我会给出具体的配置片段和参数计算过程，你可以直接复制去改。

2. WorkBuddy 到底是什么，和 CodeBuddy 什么关系

2.1 一句话讲清 WorkBuddy 的定位

WorkBuddy 本质上是腾讯做的一个AI 工作台，核心能力是把大模型、工具调用（Tool Use）、Skill 插件、任务编排这几样东西打包成一个可视化的工作环境。你可以把它理解成一个"AI Agent 的操作系统"——模型是发动机，Skill 是各种功能模块，工作台就是仪表盘和方向盘。

它解决的问题很具体：以前你想让 AI 帮你干一件稍微复杂的事，比如"读一份 PDF 报告，提取关键数据，生成图表，再写一段分析发到群里"，你得自己写代码串 LangChain、调 API、处理各种异常。WorkBuddy 把这些编排能力做成了配置化的东西，你定义好 Skill，配好模型，剩下的流程它帮你跑。

和 CodeBuddy 的关系，很多人搞混。简单说，CodeBuddy 更偏向代码场景的 AI 助手，聚焦在写代码、改 bug、代码审查这条线上；WorkBuddy 则是通用工作场景，面向的是文档处理、数据分析、任务自动化、多步骤 Agent 编排这些更宽的需求。两者底层可能共享一些模型调度和 Skill 框架的能力，但定位不一样。你如果是纯写代码，CodeBuddy 更顺手；你要做的是"让 AI 处理各种杂活"，WorkBuddy 更合适。当然实际用下来，两者在 Skill 生态上有一些互通的地方，这个后面讲 Skill 的时候会提到。

2.2 为什么是"工作台"而不是"聊天框"

这是我觉得 WorkBuddy 最值得讲的设计思路。市面上的 AI 产品大部分是聊天框形态——你问一句它答一句。但真实工作里，很多事情不是一问一答能解决的，它需要多步骤、有状态、能调用外部工具。

举个例子，你要做一份竞品分析。聊天框模式下，你得手动把资料喂进去，问一轮，再追问一轮，来回好几次。工作台模式下，你可以定义一个 Skill：输入竞品名称，它自动去抓公开信息、整理成结构化表格、生成对比分析、最后输出一份带图表的文档。整个过程你只需要点一次。

这个差异背后是AI Agent的思路——Agent 不是被动应答，而是能自主规划步骤、调用工具、根据中间结果调整策略。WorkBuddy 的工作台形态，就是把这个 Agent 能力产品化了。你不需要懂 LangGraph 怎么画状态图，通过 Skill 配置就能实现类似的效果。

2.3 谁适合用，谁可以先观望

我观察下来，这几类人用 WorkBuddy 收益最明显：

• 内容工作者：需要批量处理文档、做资料整理、生成初稿的人。Skill 可以把重复的写作流程固化下来。
• 数据分析岗：经常要跑重复的数据清洗和报表生成，把流程做成 Skill 之后一键复用。
• 团队管理者：想把某些固定流程（比如周报汇总、项目进度追踪）自动化，WorkBuddy 的中台能力可以支撑多人共用。
• 技术爱好者：想研究 AI Agent 怎么落地，WorkBuddy 是个不错的实验场，比从零搭 LangChain 快得多。

如果你只是偶尔问 AI 几个问题，没有重复性的工作流，那聊天框产品可能更轻便。WorkBuddy 的价值在于流程固化和多步骤编排，用不上这两点的话，它的学习成本就不划算了。

3. 安装与初始配置：别一上来就踩缓存目录的坑

3.1 安装前的环境准备

WorkBuddy 目前有国内版和国际版两个分发渠道，功能上有些差异，国际版在部分模型接入上更灵活一些。安装包本身不大，但安装路径和缓存目录的选择非常关键，这是我踩过的第一个大坑。

默认安装会往系统盘写缓存，包括模型临时文件、Skill 运行日志、任务中间产物。如果你像我一样习惯把软件装 D 盘，但没改缓存目录，用不了几天 C 盘就会报警。我实测过一个中等强度的使用场景——每天跑二十来个任务，一周下来缓存能涨到 8 到 12 GB。所以安装前先规划好目录。

建议的目录规划：

3.2 更改系统缓存目录的正确姿势

很多人找不到改缓存目录的入口，因为它在设置里藏得比较深。路径大致是：设置 → 高级 → 存储 → 缓存位置。但光改这里还不够，有几个地方要一起改，否则缓存还是会往老地方写。

我整理了一个完整的修改清单：

1. 主缓存目录：设置里的缓存位置，改成你规划好的路径。
2. 模型缓存：如果单独有模型下载缓存的设置项，也要改。模型文件动辄几个 GB，这个最占地方。
3. 临时文件目录：部分版本会读取系统环境变量里的 TEMP，如果你不想动系统变量，就在 WorkBuddy 自己的设置里覆盖。
4. Skill 运行沙箱目录：Skill 执行时会产生临时文件，确认它的工作目录也在你规划的分区里。

改完之后一定要重启应用，然后跑一个任务验证缓存是不是写到了新位置。我见过有人改完没重启，以为生效了，结果缓存还是往 C 盘塞。

提示：改缓存目录之前，先把已有缓存迁移过去，或者直接清空重来。直接改路径不迁移的话，历史任务的中间产物会找不到，某些依赖缓存的任务会报错。

3.3 首次启动的必做配置

第一次打开 WorkBuddy，别急着建任务，先把这几项配好：

• 模型接入：这是核心。WorkBuddy 支持接入多种模型，你需要配置 models.json（下一节详细讲）。
• 默认工作区：设置一个你常用的项目目录，新建任务时默认在这里。
• 快捷键：工作台操作频繁，把常用功能绑上快捷键，效率提升明显。
• 自动更新策略：建议设为手动更新。自动更新有时候会在你跑长任务的时候触发重启，很烦。

4. models.json 配置详解：模型接入的核心

4.1 models.json 是什么，为什么重要

models.json 是 WorkBuddy 的模型配置文件，决定了你的工作台能用哪些模型、每个模型的参数怎么设、调用优先级如何。这个文件配不好，后面 Skill 跑起来各种报错，而且报错信息往往很隐晦，排查起来费劲。

它的基本结构是一个 JSON 数组，每个元素描述一个模型接入点。核心字段包括模型标识、接入方式、上下文长度、并发限制、适用场景标签等。我下面给一个我实际在用的配置模板，你可以照着改。

{ "models": [ { "id": "primary-chat", "provider": "your-provider", "model": "your-model-name", "contextWindow": 128000, "maxOutputTokens": 8192, "concurrency": 4, "tags": ["chat", "reasoning"], "priority": 1 }, { "id": "fast-task", "provider": "your-provider", "model": "your-fast-model", "contextWindow": 32000, "maxOutputTokens": 4096, "concurrency": 8, "tags": ["fast", "extraction"], "priority": 2 } ] }

4.2 关键字段的含义与设置逻辑

contextWindow（上下文窗口）：这个值必须和模型实际支持的一致，填大了会报错，填小了浪费能力。如果你不确定，查模型官方文档，别猜。我见过有人把 32K 的模型填成 128K，结果长文档任务跑到一半直接崩。

concurrency（并发数）：这是最容易被忽视但影响最大的字段。它决定了这个模型接入点同时能处理多少个请求。设太小，多任务排队等；设太大，触发上游限流，反而更慢。我的经验值是：先设一个保守值（比如 2 到 4），跑一段时间看日志里的限流报错，再逐步往上调。

tags（场景标签）：这个字段是给 Skill 用的。Skill 在定义时可以指定"我需要一个带 reasoning 标签的模型"，WorkBuddy 就会从匹配标签的模型里按 priority 选。合理打标签能让不同类型的任务自动路由到合适的模型，省钱又提速。

priority（优先级）：数字越小优先级越高。同类标签下，优先用高优先级的模型。

4.3 多模型路由的实战策略

我现在的配置是三层路由：

• 第一层：快速模型，处理简单的信息提取、格式转换、分类判断。这类任务量大但简单，用便宜快的模型。
• 第二层：主力模型，处理需要推理、写作、复杂分析的任务。这是日常用得最多的。
• 第三层：长上下文模型，专门处理超长文档、大代码库分析。平时不用，需要时才调。

这样分层的好处是成本可控。如果所有任务都走最强模型，账单会很难看。分层之后，大概 60% 的任务走快速模型，30% 走主力，10% 走长上下文，整体成本能降一半以上。

注意：改完 models.json 后，WorkBuddy 需要重新加载配置。有些版本是自动热加载，有些需要重启。改完先跑一个测试任务确认新配置生效，别直接上生产任务。

5. Skill 机制深度拆解：让 AI 真的下地干活

5.1 Skill 到底是什么

Skill 是 WorkBuddy 里最核心的概念，也是最能体现"AI Agent"思路的地方。简单说，Skill 就是一段可复用的能力封装——它定义了"当遇到某类任务时，AI 应该按什么步骤、调用什么工具、产出什么结果"。

你可以把 Skill 理解成给 AI 写的"操作手册"。没有 Skill 的时候，AI 每次都要从零理解你的需求；有了 Skill，它直接按预设的流程走，稳定性和效率都高得多。

Skill 的构成一般包括几个部分：触发条件（什么时候用这个 Skill）、执行步骤（具体做什么）、工具依赖（需要调用哪些外部能力）、输出格式（结果长什么样）。有些高级 Skill 还会包含条件分支和错误处理逻辑。

5.2 Skill 的触发机制与边界

这是很多人搞不明白的地方——为什么我写了 Skill，AI 有时候用有时候不用？

Skill 的触发靠的是语义匹配。WorkBuddy 会把你的输入和 Skill 的描述做匹配，判断该不该触发。所以 Skill 的描述写得越清晰、触发条件定义得越明确，命中率越高。

我踩过的坑：一开始我把 Skill 描述写得很宽泛，比如"处理文档相关任务"，结果它经常在不该触发的时候触发，该触发的时候又没反应。后来改成具体的触发短语和场景描述，命中率立刻上来了。

提高触发准确率的几个技巧：

• 在描述里写清楚典型输入：比如"当用户提到'生成周报''汇总本周工作'时触发"。
• 设置排除条件：明确什么情况下不触发，避免误伤。
• 用标签辅助：给 Skill 打上场景标签，和模型的 tags 对应起来。
• 测试用例：写几个典型输入，反复测试触发情况，根据结果调整描述。

5.3 从零写一个可用的 Skill

我拿一个实际例子来讲——"会议纪要整理 Skill"。需求是：输入一段会议录音转写文本，输出结构化的纪要，包含议题、结论、待办事项。

第一步，定义触发条件。描述写成："当用户提供会议记录、录音转写文本，或提到'整理纪要''会议总结'时触发。"

第二步，拆解执行步骤：

1. 识别会议的基本信息（时间、参与人、主题）。
2. 按议题分段，提取每个议题的讨论要点。
3. 识别结论性表述，归纳成结论列表。
4. 提取待办事项，标注负责人和时间节点（如果有）。
5. 按固定格式输出。

第三步，定义输出格式。我一般用 Markdown 模板，这样结果直接能用：

## 会议纪要 **时间**： **参与人**： **主题**： ### 议题一：[议题名称] - 讨论要点： - 结论： ### 待办事项 | 事项 | 负责人 | 截止时间 | |------|--------|---------| | | | |

第四步，测试和迭代。拿几段真实的会议记录跑，看输出质量，哪里不对就调整步骤描述。我大概迭代了四五版才稳定下来。

5.4 Skill 开发指南：几个提升质量的关键点

写多了 Skill 之后，我总结出几条经验：

步骤要原子化。一个步骤只做一件事，别把"提取信息并生成报告"揉成一步。拆得越细，AI 执行越稳定，出错也越好定位。

给例子。在 Skill 描述里放一两个输入输出的示例，AI 的模仿能力很强，有例子比纯文字描述效果好得多。

处理异常。想清楚"如果输入格式不对怎么办""如果某个字段缺失怎么办"，在 Skill 里写明兜底逻辑。

控制输出长度。不限制的话，AI 容易啰嗦。在 Skill 里明确输出格式和长度要求。

版本管理。Skill 是要迭代的，建议用 Git 管理 Skill 文件，每次改动都有记录，出问题能回滚。

6. 工作台搭建实战：从个人用到团队中台

6.1 个人工作台的最小可用配置

如果你是自己用，不用搞太复杂。我的建议是先搭一个"最小可用"的工作台，包含三五个高频 Skill，跑顺了再扩展。

我的个人工作台核心 Skill 清单：

这五个 Skill 覆盖了我 80% 的日常需求。先把这几个打磨好，比铺一堆半成品 Skill 有用得多。

6.2 团队中台的搭建思路

团队用的话，要考虑的东西就多了。核心问题是：怎么让多个人共用一套 Skill 和模型资源，又不互相干扰。

我的做法是分层：

• 基础层：统一的模型接入配置（models.json），由管理员维护，所有人共用。
• 公共 Skill 层：团队通用的 Skill，比如项目周报、代码审查、文档规范检查，放在共享目录。
• 个人 Skill 层：每个人自己的私有 Skill，放在各自的工作区。
• 任务队列：多人同时跑任务时，需要一个调度机制，避免资源抢占。

这个结构的关键是权限隔离和资源配额。公共 Skill 只读，个人 Skill 可写；模型调用按人头分配配额，防止一个人把资源占满。

6.3 AI Agent 怎么扛并发：实测有效的几个策略

"AI Agent 怎么扛并发"是个高频问题，我在团队落地时专门测过。结论是：并发瓶颈通常不在模型本身，而在任务编排层和工具调用层。

几个实测有效的策略：

任务分级。把任务按紧急程度和资源消耗分级，高优先级任务走独立队列，低优先级的排队等。这样关键任务不会被批量任务堵住。

结果缓存。很多任务是重复的，比如"查某个数据"，同样的输入没必要每次都调模型。加一层缓存，命中直接返回，能省掉大量并发压力。

异步化。长任务不要同步等结果，改成提交后异步执行，完成后通知。这样前端不会卡住，后端也能更灵活地调度。

限流与退避。给每个模型接入点设并发上限，超了就排队或退避重试。别硬扛，硬扛的结果是上游限流，所有任务一起变慢。

批处理。能合并的请求合并。比如十个文档摘要任务，可以合并成一次调用处理，比十次单独调用省资源。

我实测下来，加了缓存和任务分级之后，同样的硬件资源能支撑的并发量大概提升了三倍。

7. 常见问题与排查技巧实录

7.1 Skill 不触发怎么办

这是最高频的问题。排查顺序：

1. 检查 Skill 是否启用。有时候改配置后忘了启用，或者被其他操作禁用了。
2. 检查触发描述。用你的实际输入去比对 Skill 描述，看语义匹配度够不够。不够就改描述，把典型输入写进去。
3. 检查标签冲突。如果多个 Skill 标签重叠，可能互相抢触发。给它们加区分度。
4. 看日志。WorkBuddy 的日志里会记录 Skill 匹配过程，能看到为什么没触发。

7.2 缓存爆盘怎么处理

前面讲过改缓存目录，但如果已经爆了，处理步骤是：

1. 先停掉正在跑的任务。
2. 找到缓存目录，看哪些子目录占空间最大。
3. 模型缓存一般可以安全清理（下次用会重新下载）。
4. 任务中间产物看情况，已完成任务的可以清，未完成的别动。
5. 清理完改缓存目录到新位置，重启。

我建议设个定期清理的任务，每周自动清一次过期缓存，省得手动处理。

7.3 模型调用报错的常见原因

7.4 几个独家避坑技巧

技巧一：Skill 描述里加"反例"。除了写"什么时候触发"，再写一句"什么时候不触发"，能显著降低误触发。

技巧二：模型配置留一手。别把所有模型都配成最高优先级，留一个备用接入点，主接入点出问题时能快速切换。

技巧三：任务日志分级。把日志分成 debug、info、warn、error 四级，平时只看 warn 以上，排查问题时再开 debug。不然日志刷屏，真正的问题反而被淹没。

技巧四：Skill 先小范围测。新写的 Skill 别直接上生产，先拿几个测试用例跑，确认稳定了再放开。

技巧五：定期备份配置。models.json 和 Skill 目录定期备份，改坏了能快速恢复。我就吃过没备份的亏，一次误操作把配置清了，重建花了半天。

8. 我个人的一些使用体会

WorkBuddy 这类 AI 工作台，用得好不好，很大程度上取决于你愿不愿意花时间把流程固化下来。我见过很多人装完就用默认配置，跑几个任务觉得"也就那样"，然后就放着了。但真正把它用出价值的人，都是愿意花时间打磨 Skill、调优配置的。

我自己的转折点是给团队搭了一套周报自动汇总的 Skill。以前每周五下午要花一个多小时手动整理，现在点一下，五分钟出结果。就这一件事，让我觉得前面折腾配置的时间全值回来了。

另外提醒一句，别追求一步到位。我一开始想搭一个"全能工作台"，结果 Skill 写了一堆，每个都不精。后来砍到五个核心 Skill，反复打磨，反而好用得多。工具是为人服务的，够用就好，别为了折腾而折腾。

如果你也在用 WorkBuddy，或者正在考虑搭 AI Agent 工作流，欢迎交流踩坑经验。这东西迭代很快，今天的最佳实践可能下个月就过时了，保持折腾的心态最重要。