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

WorkBuddy 这个产品刚出来的时候，我其实没太当回事。腾讯系的产品，名字里带个 Buddy，听起来像是又一个套壳的对话助手。直到有次团队里一个非技术岗的同事，用它在半小时内把一份三十多页的会议纪要整理成了带行动项、负责人、截止时间的结构化表格，我才意识到这东西跟我想的不一样。它不是那种你问一句它答一句的聊天机器人，而是一个能真正“下地干活”的 AI 工作台。

这篇内容我打算把 WorkBuddy 从安装到日常使用、从 Skill 配置到踩坑排查，完整地讲一遍。核心关键词会围绕WorkBuddy、腾讯 AI 工作台、AI Agent、models.json、Skill这几个展开。不管你是刚听说这个产品想试试水，还是已经装上了但不知道怎么把它用出价值，或者你正在做 AI Agent 相关的开发想参考它的设计思路，这篇都能给你一些直接能抄的东西。

我自己的使用场景比较杂：日常写技术方案、整理会议记录、做竞品调研、偶尔写点脚本处理重复性工作。WorkBuddy 在这些场景里帮我省下来的时间，保守估计每周有五到八个小时。但前提是你得把它配好、用对，否则它就是一个占内存的聊天窗口。

下面我按“整体设计思路 → 核心细节与实操 → 完整落地流程 → 常见问题排查”这个顺序来讲，中间会穿插我自己踩过的坑和总结出来的技巧。内容比较长，建议先收藏，遇到具体问题的时候按章节翻。

2. WorkBuddy 的整体设计与核心思路拆解

2.1 它到底是个什么东西：AI 工作台和普通对话助手的本质区别

很多人第一次打开 WorkBuddy 会觉得“这不就是个聊天框吗”。确实，界面主体是一个对话区域，但它的底层逻辑跟普通对话助手有本质区别。普通对话助手是“你问我答”，每次对话都是独立的，它不记得你之前让它干过什么，也不会主动去调用工具。WorkBuddy 的核心定位是AI 工作台，它把对话、任务、工具调用、文件处理这几件事整合到了一个界面里。

我打个比方：普通对话助手像是一个坐在你对面的人，你问什么他答什么，但他手边没有电脑、没有文件、没有工具。WorkBuddy 像是一个坐在你旁边工位上的人，他不仅有脑子，还有你的文件权限、能打开你的表格、能调用你配置好的工具、能记住你之前交代过的规则。这个区别在简单问答场景里不明显，但一旦涉及多步骤任务，差距就出来了。

它的架构大致可以分成三层：最上面是交互层，就是你看到的对话界面和任务面板；中间是调度层，负责理解你的意图、拆解任务、决定调用哪个 Skill；最下面是执行层，包括模型调用、文件读写、外部工具连接。这个分层设计的好处是，你可以在不改动交互层的情况下，通过配置 Skill 来扩展它的能力边界。

2.2 为什么是 Skill 机制而不是插件市场

WorkBuddy 扩展能力的方式是Skill，而不是像很多产品那样搞一个插件市场。这个选择我觉得挺有意思。插件市场的问题是，插件质量参差不齐，安装之后你不知道它到底干了什么，权限控制也很模糊。Skill 机制更像是“你告诉它怎么做”，而不是“你装一个别人写好的东西”。

Skill 本质上是一组指令和工具调用的封装。你可以把它理解成给 WorkBuddy 写的一份“操作手册”：当遇到某类任务时，按照这个手册里的步骤去执行。比如你写一个“会议纪要整理”的 Skill，里面定义好输入格式、处理步骤、输出模板，之后每次丢给它一份会议记录，它就会按这个流程走。

这种设计的好处是透明和可控。你知道它每一步在干什么，出了问题也能定位到具体环节。坏处是上手门槛比插件市场高一点，你得花点时间理解 Skill 的结构。但一旦理解了，你会发现它的灵活性远超插件市场那种“装了就完事”的模式。

2.3 models.json 在整个体系里扮演什么角色

models.json是 WorkBuddy 的模型配置文件。你可以把它理解成工作台的“大脑设置”。它决定了 WorkBuddy 在什么场景下调用哪个模型、用什么样的参数、走什么样的接口。

为什么需要这么一个配置文件？因为不同任务对模型的要求不一样。有些任务需要强推理能力，有些任务需要快速响应，有些任务需要处理长文本。如果所有任务都走同一个模型，要么浪费资源，要么效果不好。models.json 让你可以按场景配置不同的模型，比如日常对话走一个轻量模型，复杂分析走一个推理能力更强的模型。

这个文件通常放在 WorkBuddy 的配置目录下，格式是标准的 JSON。里面会定义模型名称、接口地址、API Key、超时时间、最大 token 数这些参数。我后面会给出一个具体的配置示例，你可以直接参考。

2.4 跟 CodeBuddy 的关系：名字像但定位不同

热词里有人问“workbuddy 和 codebuddy”的区别。简单说，CodeBuddy 更偏向代码场景，它的强项是代码补全、代码审查、技术文档生成这类任务。WorkBuddy 的覆盖面更广，它不局限于代码，而是面向通用办公和业务场景。两者在底层可能共享一些模型能力，但产品定位和交互设计是分开的。

如果你主要是写代码，CodeBuddy 可能更顺手。如果你需要处理文档、表格、调研、会议记录这些杂事，WorkBuddy 更合适。当然，WorkBuddy 也能处理代码相关的任务，只是它的交互方式不是围绕代码编辑器设计的。

3. 核心细节解析与实操要点

3.1 安装与初始配置：从零到能用的完整步骤

WorkBuddy 的安装本身不复杂，但初始配置有几个关键点容易卡住人。我按顺序说。

第一步是获取安装包。目前它主要通过官方渠道分发，你需要在官网或者官方指定的应用商店里下载。注意区分版本，热词里提到的“workbuddy 国际版”和国内版在功能上有些差异，国际版可能在某些模型接入上有区别。如果你只是日常办公用，国内版就够。

第二步是安装。Windows 和 macOS 都有对应的安装包，安装过程跟普通软件一样，一路下一步就行。安装完成后首次启动会要求登录，用你的账号登录即可。

第三步是初始配置。这里有几个关键设置：

• 工作目录设置：WorkBuddy 需要一个默认的工作目录，用来存放它生成的文件、缓存、日志。默认路径通常在用户目录下，但如果你 C 盘空间紧张，建议改到其他盘。热词里有人问“workbuddy 怎么更改系统缓存目录”，就是在这一步或者后续设置里改。
• 模型配置：如果你用的是官方提供的模型服务，登录后会自动配置好。如果你要接入自己的模型接口，就需要编辑 models.json。
• Skill 目录：Skill 文件存放的位置，默认在配置目录下的 skills 文件夹里。你可以手动往里放 Skill 文件，也可以通过界面导入。

注意：安装路径和工作目录尽量不要包含中文和空格，虽然现在大部分软件都支持，但偶尔会遇到路径解析问题，排查起来很烦。

3.2 models.json 配置详解：参数含义与常见配置模板

models.json 是 WorkBuddy 模型调用的核心配置文件。我给出一个典型的配置结构，然后逐项解释。

{ "default_model": "general", "models": { "general": { "provider": "official", "model_name": "workbuddy-general", "api_base": "https://api.example.com/v1", "api_key": "your-api-key-here", "max_tokens": 4096, "temperature": 0.7, "timeout": 30 }, "reasoning": { "provider": "official", "model_name": "workbuddy-reasoning", "api_base": "https://api.example.com/v1", "api_key": "your-api-key-here", "max_tokens": 8192, "temperature": 0.3, "timeout": 60 } }, "routing": { "chat": "general", "analysis": "reasoning", "code": "general" } }

逐项解释一下：

• default_model：默认使用的模型，当 routing 里没有匹配到具体场景时走这个。
• models：模型定义列表，每个模型有自己的配置。
• provider：模型提供方，官方服务填 official，自定义接口填 custom。
• model_name：模型名称，这个要跟提供方要求的名称一致。
• api_base：接口地址，如果你用的是官方服务，通常不需要改。
• api_key：认证密钥，这个不要泄露，也不要在截图里暴露。
• max_tokens：单次请求的最大 token 数，根据任务复杂度调整。日常对话 4096 够用，长文档分析建议 8192 以上。
• temperature：温度参数，控制输出的随机性。0.7 适合创意类任务，0.3 适合分析类任务。
• timeout：超时时间，单位秒。推理类任务建议设长一点，避免还没出结果就超时了。
• routing：场景路由，定义不同场景走哪个模型。

提示：修改 models.json 后需要重启 WorkBuddy 才能生效。如果你改了配置但发现没起作用，先检查是不是忘了重启。

3.3 Skill 的编写与导入：从理解结构到写出第一个可用 Skill

Skill 是 WorkBuddy 最核心的扩展机制。一个 Skill 文件通常包含以下几个部分：

• 名称和描述：告诉 WorkBuddy 这个 Skill 是干什么的。
• 触发条件：什么情况下应该调用这个 Skill。
• 输入定义：这个 Skill 需要什么输入。
• 执行步骤：具体怎么处理。
• 输出格式：结果以什么形式返回。

我拿一个实际例子来说明。假设我要写一个“会议纪要整理”的 Skill，结构大概是这样：

name: meeting-notes-organizer description: 将会议记录整理成结构化纪要，包含行动项、负责人、截止时间 trigger: - "整理会议纪要" - "会议记录整理" - "meeting notes" input: - name: raw_notes type: text description: 原始会议记录文本 steps: - 提取会议主题和参会人员 - 识别讨论要点和决议事项 - 提取行动项，包括负责人和截止时间 - 按模板格式化输出 output: format: markdown template: | ## 会议主题 {topic} ## 参会人员 {attendees} ## 讨论要点 {discussion_points} ## 行动项 {action_items}

这个 Skill 写好后，放到 skills 目录下，重启 WorkBuddy 就能用了。之后你在对话里说“帮我整理这份会议纪要”，它就会自动调用这个 Skill。

热词里提到的“skill 编码247”“skill 脚本”“skill 开发指南”这些，本质上都是在讨论 Skill 的编写方法。我的经验是，Skill 不用写得太复杂，一个 Skill 解决一类问题就行。写得太宽泛反而不好用。

3.4 工作目录与缓存管理：别让 C 盘爆掉

WorkBuddy 在运行过程中会产生缓存文件、日志文件、临时文件。默认情况下这些都在用户目录下，时间长了 C 盘空间会被吃掉不少。我自己的做法是安装完成后第一件事就是改工作目录。

改的方法是在设置里找到“工作目录”或“缓存目录”选项，改到一个空间充足的盘。如果你找不到这个选项，也可以直接编辑配置文件，通常在 config 目录下的 settings.json 里，有一个 work_dir 字段。

改完之后把原来的缓存文件迁移过去，或者直接删掉让 WorkBuddy 重新生成。缓存文件删掉不影响使用，只是第一次加载会慢一点。

注意：迁移工作目录后，之前生成的 Skill 如果引用了绝对路径，可能需要同步修改。建议 Skill 里尽量用相对路径。

4. 完整实操流程：从安装到跑通第一个任务

4.1 环境准备与安装实操记录

我最近一次安装是在一台 Windows 机器上，系统版本是 Windows 11。整个过程大概花了十分钟，其中大部分时间在下载安装包。

安装包大小在几百兆左右，下载速度取决于网络。安装过程没什么好说的，双击、下一步、选择安装路径、完成。安装完成后桌面会出现快捷方式。

首次启动会有一个引导流程，让你登录账号、选择工作目录、配置模型。如果你用的是官方模型服务，登录后会自动配置好，不需要手动改 models.json。如果你要用自己的模型接口，就在这一步选择“自定义配置”，然后填入接口地址和密钥。

引导流程走完后，建议先跑一个简单任务测试一下。比如在对话框里输入“帮我写一个周报模板”，看看它能不能正常响应。如果能正常返回结果，说明基础配置没问题。

4.2 配置 models.json 并验证模型可用性

如果你需要用自定义模型，这一步比较关键。我以接入一个兼容接口的模型为例。

首先找到 models.json 文件的位置。通常在 WorkBuddy 安装目录下的 config 文件夹里，或者在用户目录下的 .workbuddy 文件夹里。具体位置可以在设置里查看。

打开 models.json，按照我前面给的模板填入你的模型信息。关键参数是 api_base、api_key、model_name，这三个必须跟你的模型服务商提供的一致。

填好后保存，重启 WorkBuddy。然后在对话框里输入一个测试问题，比如“1+1 等于几”。如果它能正常回答，说明模型配置成功。如果报错，检查 api_key 是否正确、api_base 是否可达、model_name 是否拼写正确。

提示：有些模型服务商要求 api_base 以 /v1 结尾，有些不要求。如果你不确定，先试试带 /v1 的，不行再去掉。

4.3 编写并导入第一个 Skill：以“日报生成”为例

我拿“日报生成”这个场景来演示 Skill 的完整编写和导入过程。

首先创建一个 YAML 文件，命名为 daily-report.yaml，内容如下：

name: daily-report-generator description: 根据当天工作内容生成结构化日报 trigger: - "生成日报" - "写日报" - "daily report" input: - name: work_items type: text description: 当天完成的工作项，每行一个 steps: - 解析工作项列表 - 按项目分类整理 - 标注每项的完成状态 - 生成明日计划建议 output: format: markdown template: | # 工作日报 ## 今日完成 {completed_items} ## 进行中 {in_progress_items} ## 明日计划 {tomorrow_plan}

写好后，把这个文件放到 skills 目录下。然后在 WorkBuddy 界面里找到 Skill 管理，点击“重新加载”或“导入 Skill”。加载成功后，在对话框里输入“生成日报”，它就会调用这个 Skill。

我第一次写 Skill 的时候犯过一个错误：trigger 写得太宽泛，比如只写了“日报”，结果每次对话里出现“日报”两个字都会触发，很烦。后来改成“生成日报”“写日报”这种更具体的短语，就正常了。

4.4 跑通一个完整任务：从输入到输出的全流程

我拿一个实际任务来演示完整流程。任务是：把一份产品需求文档整理成开发任务列表。

第一步，把需求文档内容粘贴到对话框，或者用文件上传功能上传。

第二步，输入指令：“帮我把这份需求文档整理成开发任务列表，每个任务包含任务描述、优先级、预估工时。”

第三步，WorkBuddy 会调用相应的 Skill（如果你配置了的话），或者直接走默认处理流程。它会先解析文档内容，提取功能点，然后按模板生成任务列表。

第四步，检查输出结果。如果格式不对或者遗漏了内容，可以直接在对话里让它调整，比如“优先级用 P0/P1/P2 表示”“工时按人天估算”。

第五步，把结果导出。WorkBuddy 支持导出为 Markdown、表格等格式，你可以直接复制或者保存到文件。

整个流程走下来，一份中等复杂度的需求文档大概两三分钟就能整理完。手动做的话至少半小时。

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

5.1 安装与启动类问题

问题一：安装后启动闪退。

这个我遇到过，原因是工作目录路径包含特殊字符。解决办法是把工作目录改成一个纯英文、无空格的路径。如果改完还是闪退，检查一下系统日志，看看有没有具体的错误信息。

问题二：登录后一直转圈，进不去主界面。

通常是网络问题。检查一下网络连接是否正常，如果用了代理，确认代理配置是否正确。另外，有些安全软件会拦截 WorkBuddy 的网络请求，临时关闭安全软件试试。

问题三：界面显示不全或者字体异常。

这个跟系统缩放设置有关。如果你用的是高分辨率屏幕，把系统缩放调到 100% 或者 125% 试试。WorkBuddy 对高 DPI 的支持还在完善中，某些缩放比例下可能会有显示问题。

5.2 模型配置类问题

问题一：配置了自定义模型但调用失败。

排查顺序：先检查 api_key 是否正确，再检查 api_base 是否可达（可以用 curl 测试），然后检查 model_name 是否跟服务商要求的一致。如果都正确，看看是不是触发了频率限制。

问题二：模型响应特别慢。

可能是 max_tokens 设得太大，或者 timeout 设得太短导致频繁重试。调整一下这两个参数。另外，如果你用的是推理型模型，响应慢是正常的，可以换一个轻量模型处理简单任务。

问题三：models.json 改了不生效。

确认是否重启了 WorkBuddy。如果重启后还是不生效，检查文件格式是否正确，JSON 格式对括号和逗号很敏感，多一个少一个都会导致解析失败。

5.3 Skill 使用类问题

问题一：Skill 加载失败。

检查 YAML 格式是否正确。YAML 对缩进要求严格，建议用支持 YAML 语法高亮的编辑器编写。另外检查文件编码，确保是 UTF-8。

问题二：Skill 触发了但结果不对。

可能是 steps 定义得太模糊，模型理解有偏差。把步骤写得更具体一些，比如不要写“整理内容”，而是写“按时间顺序排列，提取每个时间点的事件”。

问题三：多个 Skill 冲突。

如果两个 Skill 的 trigger 有重叠，可能会同时触发。解决办法是让 trigger 更具体，或者在 Skill 里加优先级设置。

5.4 性能与资源占用类问题

问题一：WorkBuddy 占用内存越来越高。

长时间运行后内存占用上升是正常的，但如果涨到几个 G 就不正常了。检查是不是加载了太多 Skill，或者缓存文件太多。清理一下缓存，重启一下。

问题二：同时处理多个任务时卡顿。

WorkBuddy 的任务处理是串行的，同时提交多个任务会排队。如果你需要并行处理，可以开多个窗口，但注意资源占用。

问题三：磁盘空间被缓存占满。

定期清理缓存目录。可以在设置里找到缓存管理，手动清理。也可以写一个定时任务，定期删除超过一定时间的缓存文件。

5.5 常见问题速查表

6. 我个人的使用心得与几个实用技巧

6.1 怎么让 WorkBuddy 真正融入日常工作流

我试过很多种用法，最后稳定下来的工作流是这样的：每天早上打开 WorkBuddy，先让它帮我整理当天的待办事项，把前一天遗留的任务和今天新增的任务合并成一个列表。然后处理具体任务时，遇到需要整理、分析、生成的内容，直接丢给它。下午下班前，让它根据当天的工作记录生成日报。

这个流程跑顺了之后，我基本上不需要手动整理文档了。但前提是你得把 Skill 配好，把常用任务的模板定义清楚。一开始可能要花一两个小时配置，后面每天省下来的时间很可观。

6.2 几个我踩过坑之后总结的避坑技巧

第一个技巧：Skill 的 trigger 一定要具体。我一开始写 trigger 只写“整理”，结果每次对话里出现“整理”两个字都会触发，烦得不行。后来改成“整理会议纪要”“整理需求文档”这种具体短语，就正常了。

第二个技巧：models.json 改之前先备份。我有次改配置改错了，导致 WorkBuddy 启动不了，又找不到原始文件，最后只能重装。从那以后我改任何配置文件之前都会先复制一份。

第三个技巧：工作目录不要放在系统盘。缓存文件日积月累能占好几个 G，放系统盘迟早爆掉。我现在的做法是专门建一个目录放 WorkBuddy 的工作文件，定期清理。

第四个技巧：Skill 不要贪多。我一开始装了十几个 Skill，结果加载慢、冲突多。后来精简到五六个常用的，体验好很多。Skill 在精不在多。

6.3 关于 WorkBuddy 后续可以怎么扩展

如果你对 AI Agent 开发感兴趣，WorkBuddy 的 Skill 机制其实是一个很好的学习样本。你可以通过写 Skill 来理解 Agent 的任务拆解、工具调用、结果格式化这些核心概念。热词里提到的“ai agent 搭建”“ai agent 开发”“spring ai agent”这些，本质上都是在讨论怎么让 AI 从“能聊天”变成“能干活”。WorkBuddy 的 Skill 就是一个具体的落地案例。

另外，WorkBuddy 的 models.json 配置方式也可以参考到其他 AI 应用里。按场景路由不同模型这个思路，在很多需要平衡成本和效果的场景下都适用。

最后再分享一个小技巧：如果你经常处理同类文档，可以写一个 Skill 专门处理这类文档，把处理步骤固化下来。比如你每周都要整理周报，就写一个“周报整理”Skill，把格式、分类方式、输出模板都定义好。之后每周只需要把原始内容丢进去，几秒钟就能出结果。这个效率提升是实打实的。