1. 为什么我要认真写这篇 WorkBuddy 实战指南第一次听说 WorkBuddy 是在一个技术群里有人甩了张截图说腾讯出了个 AI 工作台能把日常那些重复性的活儿全接过去。当时我的反应跟大多数人一样又一个套壳产品吧直到我自己装了一遍、配了一遍、踩了一遍坑才发现这东西跟市面上那些“对话式 AI 助手”完全不是一个物种。WorkBuddy 的核心定位是AI Agent 工作台不是聊天机器人。它通过Skill技能机制让 AI 真正“下地干活”——读写文件、执行脚本、调用 API、处理数据、生成报告这些操作它都能在本地环境里完成。你可以把它理解成一个“AI 调度中心”你告诉它要做什么它自己规划步骤、调用工具、执行任务、返回结果。跟 CodeBuddy 那种偏代码补全的工具不同WorkBuddy 的覆盖面更广从文档处理到数据分析到自动化流程都能插一脚。这篇文章适合哪些人看如果你是开发者想搞清楚 AI Agent 到底怎么落地WorkBuddy 是个很好的切入点如果你是普通办公用户想用 AI 替自己干掉那些枯燥的重复劳动这篇也能帮你少走弯路如果你已经在用类似产品但总觉得“差点意思”那大概率是 Skill 配置和 models.json 没调对。我会从安装部署讲到 Skill 开发从 models.json 配置讲到常见坑的排查尽量把每个环节的“为什么”都说清楚。注意本文基于 WorkBuddy 国内版的实际使用经验撰写国际版在部分功能入口和模型选择上有差异但核心逻辑相通。2. WorkBuddy 安装部署从零到能跑起来2.1 安装前的环境准备与版本选择WorkBuddy 的安装本身不复杂但环境准备阶段有几个容易忽略的点。首先说操作系统Windows 10 以上、macOS 12 以上都能跑Linux 桌面版支持也在逐步完善。我的建议是优先用 macOS 或 WindowsLinux 下某些 Skill 的兼容性还不够稳定尤其是涉及系统级文件操作的场景。硬件方面官方给的最低配置是 8GB 内存但实测下来如果你打算同时跑多个 Skill 或者处理大文件16GB 内存是起步线。CPU 倒不是瓶颈因为大部分计算负载都在云端模型侧本地主要跑的是调度和文件 IO。硬盘空间留够 5GB 就行主要是缓存和日志。安装包获取渠道这里不展开只说一点认准官方渠道。网上有些第三方打包的版本夹带了修改过的 models.json用着用着发现请求被转发到不明地址这种事不是没发生过。安装过程中有一个选项值得注意是否更改默认缓存目录。默认情况下 WorkBuddy 会把缓存放在系统盘的用户目录下Windows 是C:\Users\你的用户名\.workbuddymacOS 是~/.workbuddy。如果你系统盘空间紧张或者想让缓存和项目文件放在一起方便管理这一步就要改。具体怎么改后面会讲。2.2 首次启动与基础配置流程装完之后第一次启动WorkBuddy 会引导你走一个初始化流程。这个流程里最关键的一步是模型接入配置。WorkBuddy 本身不绑定特定模型它通过 models.json 来管理模型接入信息。你可以用官方推荐的模型也可以接自己的 API。初始化界面会让你选择“快速开始”还是“手动配置”。强烈建议选手动配置因为快速开始会帮你填一堆默认值后面改起来反而麻烦。手动配置里你需要填模型提供方的 API 地址API Key模型名称比如某个具体的模型标识可选的代理设置如果你在公司内网环境填完之后点测试连接能通就说明配置没问题。这里有个小细节API 地址末尾不要多加斜杠有些模型服务对 URL 格式很敏感多一个斜杠就报 404。我在这上面浪费了半小时后来看日志才发现。初始化完成后WorkBuddy 会问你“是否导入示例 Skill”。建议选是因为示例 Skill 能帮你快速理解 Skill 的结构和运行方式后面自己写的时候有参照。2.3 更改缓存目录与数据迁移的正确姿势缓存目录这事值得单独说因为问的人太多了。WorkBuddy 的缓存分三类模型响应缓存、Skill 运行日志、临时文件。默认都在系统盘时间一长可能占几个 GB。改缓存目录的方法完全退出 WorkBuddy不是最小化到托盘是彻底退出找到配置文件Windows 在%APPDATA%\WorkBuddy\config.jsonmacOS 在~/Library/Application Support/WorkBuddy/config.json编辑cacheDir字段改成你想要的路径比如D:\WorkBuddyCache或/Users/你的用户名/workbuddy-cache把原缓存目录下的内容手动复制到新目录重新启动 WorkBuddy注意改完路径后如果启动报错大概率是权限问题。Windows 下确保新目录不在需要管理员权限的位置macOS 下确保当前用户有读写权限。另外路径中不要包含中文或特殊字符虽然理论上支持但实测偶尔出问题。数据迁移这块如果你之前已经用了一段时间缓存里有历史对话和 Skill 运行记录直接复制过去就行。但有一种情况例外如果你换了模型提供方建议清空模型响应缓存因为不同模型的响应格式可能有差异旧缓存可能导致解析错误。3. models.json 深度解析WorkBuddy 的模型调度中枢3.1 models.json 的结构与字段含义models.json 是 WorkBuddy 最核心的配置文件没有之一。它决定了 WorkBuddy 能用哪些模型、怎么调用、优先级如何。很多人装完 WorkBuddy 觉得“不好用”十有八九是 models.json 没配对。一个典型的 models.json 结构长这样{ models: [ { name: 主力模型, provider: custom, apiBase: https://api.example.com/v1, apiKey: sk-xxxxxxxx, model: model-name-here, maxTokens: 4096, temperature: 0.7, priority: 1, capabilities: [chat, function_call] } ], defaultModel: 主力模型, fallbackModel: 备用模型 }逐个字段解释name模型在 WorkBuddy 界面里显示的名字随便起但建议起个能看懂的provider提供方类型一般填custom就行除非你用官方预置的apiBaseAPI 地址注意要包含版本路径比如/v1apiKey你的密钥model模型的实际标识符这个必须跟提供方文档一致maxTokens单次响应的最大 token 数根据模型能力填temperature温度参数0 到 1 之间越低越确定越高越随机priority优先级数字越小越优先多个模型时 WorkBuddy 会按这个顺序尝试capabilities模型支持的能力列表比如chat、function_call、vision等defaultModel是默认使用的模型fallbackModel是默认模型调用失败时的备选。这两个字段在稳定性要求高的场景下很重要。3.2 多模型配置与优先级策略WorkBuddy 支持同时配置多个模型这在实战中非常有用。比如你可以配一个“快模型”处理简单任务一个“强模型”处理复杂推理一个“便宜模型”做批量处理。多模型配置的关键是priority 和 capabilities 的配合。举个例子{ models: [ { name: 快速模型, priority: 1, capabilities: [chat], model: fast-model }, { name: 推理模型, priority: 2, capabilities: [chat, function_call], model: reasoning-model }, { name: 备用模型, priority: 3, capabilities: [chat], model: backup-model } ] }当 WorkBuddy 需要执行一个需要 function_call 能力的 Skill 时它会跳过“快速模型”因为不支持 function_call直接选“推理模型”。如果推理模型调用失败再降级到备用模型。这个机制的好处是你不需要手动切换模型WorkBuddy 会根据任务需求自动选择。但前提是你的 capabilities 字段填对了。我见过有人把所有模型的 capabilities 都写成[chat]结果 Skill 死活跑不起来排查半天才发现是这里的问题。3.3 常见配置错误与修复方法models.json 的配置错误五花八门我整理了几个高频问题错误现象可能原因修复方法启动报 JSON 解析错误文件格式不对比如多了逗号、少了引号用 JSON 校验工具检查模型列表为空models 数组为空或字段名拼错检查models拼写确保是数组调用返回 401apiKey 错误或过期重新生成密钥并更新调用返回 404apiBase 路径不对确认是否包含/v1等版本路径Skill 无法执行capabilities 缺少 function_call补充 capabilities 字段响应超时maxTokens 设置过大或网络问题降低 maxTokens检查网络还有一个隐蔽的坑JSON 文件编码。如果你在 Windows 上用记事本编辑 models.json保存时可能变成 GBK 编码WorkBuddy 读的时候按 UTF-8 解析就会乱码。务必用 VS Code 或 Notepad 这类编辑器保存时选 UTF-8。实操心得改完 models.json 后不要急着重启 WorkBuddy。先在界面里点“重新加载配置”如果加载成功再重启。这样能快速定位是配置问题还是其他问题。4. Skill 机制全解让 AI 真正“下地干活”4.1 Skill 是什么从概念到实际作用Skill 是 WorkBuddy 的灵魂。没有 Skill 的 WorkBuddy 就是个普通聊天窗口有了 Skill 它才能读写文件、执行命令、调用接口、处理数据。用大白话说Skill 就是一段告诉 WorkBuddy“遇到什么情况该怎么做”的指令集。它包含三部分触发条件什么情况下用这个 Skill执行逻辑具体做什么分几步输出格式结果怎么返回给用户举个例子一个“整理桌面文件”的 Skill触发条件是用户说“帮我整理桌面”执行逻辑是“扫描桌面目录 → 按文件类型分类 → 创建对应文件夹 → 移动文件”输出格式是“已整理 X 个文件分类如下...”。Skill 的本质是一段结构化文本WorkBuddy 把它注入到模型的上下文里模型根据 Skill 的描述来决定调用哪些工具、按什么顺序执行。所以Skill 写得好不好直接决定了 AI 干活的质量。4.2 Skill 的编写规范与最佳实践写 Skill 有几个核心原则第一触发条件要明确。不要写“当用户需要处理文件时”太模糊了。要写“当用户输入包含‘整理’、‘分类’、‘归档’且涉及文件路径时”。越具体模型判断越准。第二执行步骤要可操作。每一步都应该是模型能理解并执行的动作。比如“读取文件内容”可以“理解文件含义”就不行因为后者太抽象。第三输出格式要固定。模型返回结果时格式固定能让后续处理更顺畅。比如统一用 JSON 返回或者统一用 Markdown 表格。一个 Skill 的基本结构# Skill: 文件整理 ## 触发条件 用户要求整理指定目录下的文件 ## 执行步骤 1. 确认目标目录路径 2. 扫描目录下所有文件 3. 按扩展名分类 4. 创建分类文件夹 5. 移动文件到对应文件夹 6. 返回整理结果 ## 输出格式 已整理 [数量] 个文件 - 文档类[数量] 个 - 图片类[数量] 个 - 其他[数量] 个这个结构看起来简单但实际写的时候有很多细节要注意。比如“扫描目录”这一步要说明是否包含子目录“移动文件”要说明是否覆盖同名文件。这些细节不写清楚模型就会按自己的理解来结果往往不是你想要的。4.3 热门 Skill 类型与适用场景盘点根据我的使用经验WorkBuddy 上最实用的 Skill 大概分这几类文件处理类批量重命名、格式转换、内容提取、目录整理。这类 Skill 门槛低、见效快适合刚上手的人。数据类CSV 解析、Excel 处理、数据清洗、报表生成。这类 Skill 对格式要求高写的时候要把输入输出格式定死。网络类API 调用、网页内容抓取、数据同步。这类 Skill 要注意错误处理和超时设置。开发辅助类代码格式化、日志分析、配置生成。这类 Skill 适合开发者能省不少重复劳动。办公自动化类邮件草稿生成、会议纪要整理、文档模板填充。这类 Skill 对文本处理能力要求高。有个热词叫“book to skill”意思是把一本书的内容转化成 Skill。这个思路挺有意思比如你把一本写作指南转化成 SkillWorkBuddy 就能按指南里的方法帮你改文章。但实际操作中一本书的内容太多直接塞进 Skill 会超出上下文限制需要做摘要和结构化处理。4.4 Skill 调试与迭代的实战技巧Skill 写完不是终点调试才是重头戏。我的调试流程一般是先用简单输入测试比如文件整理 Skill先拿一个只有三五个文件的目录试看日志WorkBuddy 的 Skill 运行日志会记录每一步的执行情况哪里卡住了一目了然逐步增加复杂度简单场景跑通了再试复杂场景比如嵌套目录、特殊文件名记录失败案例每次失败都记下来分析是 Skill 描述问题还是模型理解问题有个技巧很管用在 Skill 里加“如果...则...”的分支逻辑。比如“如果目录为空则返回‘目录为空无需整理’”。这样能避免模型在边界情况下瞎猜。还有一点Skill 不是越详细越好。太详细会占用大量上下文反而影响模型对其他信息的处理。一般来说一个 Skill 控制在 500 到 1500 字之间比较合适。超过这个范围就要考虑拆成多个 Skill。5. 实操全流程从零搭建一个文件整理工作台5.1 需求分析与方案设计假设你每天都要处理大量下载文件桌面乱成一锅粥。你想让 WorkBuddy 帮你自动整理按文件类型分到不同文件夹。需求拆解输入一个目录路径处理扫描文件 → 识别类型 → 创建分类文件夹 → 移动文件输出整理结果摘要方案设计时考虑几个问题文件类型怎么判断按扩展名最靠谱分类粒度多细太细了文件夹太多太粗了没意义。建议按“文档、图片、视频、音频、压缩包、其他”六类同名文件怎么处理加时间戳后缀子目录要不要处理默认不处理避免误操作5.2 Skill 编写与配置落地根据上面的设计Skill 可以这样写# Skill: 下载目录整理 ## 触发条件 用户要求整理下载目录或指定目录下的文件 ## 执行步骤 1. 获取用户指定的目录路径如果未指定则使用默认下载目录 2. 列出目录下所有文件不包含子目录 3. 按扩展名分类 - 文档doc, docx, pdf, txt, md, xlsx, pptx - 图片jpg, jpeg, png, gif, webp, svg - 视频mp4, avi, mkv, mov - 音频mp3, wav, flac, aac - 压缩包zip, rar, 7z, tar, gz - 其他不在上述范围内的 4. 在目标目录下创建对应分类文件夹如果不存在 5. 移动文件到对应文件夹同名文件加时间戳后缀 6. 返回整理结果 ## 输出格式 整理完成共处理 [总数] 个文件 - 文档[数量] 个 - 图片[数量] 个 - 视频[数量] 个 - 音频[数量] 个 - 压缩包[数量] 个 - 其他[数量] 个把这个 Skill 保存为organize-downloads.md放到 WorkBuddy 的 Skill 目录下。Skill 目录的位置在设置里能看到一般是~/.workbuddy/skills/。然后在 WorkBuddy 界面里刷新 Skill 列表应该就能看到这个新 Skill 了。5.3 运行验证与效果调优第一次运行我建议拿一个测试目录试别直接上真实下载目录。测试目录里放几个不同类型的文件然后对 WorkBuddy 说“帮我整理测试目录”。观察运行日志看每一步是否按预期执行。常见问题文件没被移动可能是路径不对或者权限不够分类不对检查扩展名列表是否覆盖了实际文件类型同名文件被覆盖Skill 里要明确写“加时间戳后缀”跑通之后可以逐步增加复杂度。比如加入“跳过隐藏文件”、“跳过正在使用的文件”等逻辑。每次修改 Skill 后都要重新测试确保没有引入新问题。实操心得Skill 的迭代不要一次改太多。每次只改一个点测试通过后再改下一个。这样出问题时容易定位。6. 常见问题与排查技巧实录6.1 安装与启动类问题问题安装后启动闪退排查思路先看日志。WorkBuddy 的日志在缓存目录下的logs文件夹里。常见原因是 models.json 格式错误导致启动时解析失败。把 models.json 临时改名如果启动正常就说明是配置问题。问题界面显示“无可用模型”检查 models.json 里的models数组是否为空以及defaultModel是否指向了一个存在的模型名称。另外确认 API Key 没有过期。问题更改缓存目录后启动报错大概率是权限问题。Windows 下试试把目录设在用户目录下macOS 下用chmod确保权限。路径中不要有中文。6.2 Skill 运行类问题问题Skill 不触发检查触发条件是否太窄或太宽。太窄了模型匹配不到太宽了会误触发。建议在触发条件里加入具体的动词和名词组合。问题Skill 执行到一半卡住看日志里最后执行到哪一步。常见原因是某一步需要调用的工具不可用比如文件路径不存在、API 超时。在 Skill 里加入错误处理逻辑比如“如果文件不存在则跳过并记录”。问题Skill 输出格式不对模型有时候会“自由发挥”不按你定义的格式返回。解决办法是在 Skill 里强调“必须严格按照以下格式输出”并在输出格式部分给出具体示例。6.3 模型调用类问题问题调用返回 429请求过多说明触发了速率限制。解决办法降低并发或者在 models.json 里配置多个模型做负载均衡。问题响应内容被截断检查 maxTokens 设置。如果任务需要长输出把 maxTokens 调大。但注意不要超过模型本身的上限。问题模型不理解中文指令有些模型对中文支持不好。解决办法在 Skill 里用中英双语写关键指令或者在 models.json 里优先选择中文能力强的模型。6.4 性能与稳定性优化建议缓存策略WorkBuddy 默认会缓存模型响应。如果任务对实时性要求高可以在配置里关闭缓存。并发控制同时跑多个 Skill 时注意模型 API 的并发限制。建议在 models.json 里设置合理的超时和重试参数。日志管理日志文件会越来越大建议定期清理。可以在配置里设置日志保留天数。Skill 加载优化Skill 太多会影响启动速度。不常用的 Skill 可以移到备份目录需要时再放回来。7. 关于 WorkBuddy 和 CodeBuddy 的选择以及一些个人体会经常有人问 WorkBuddy 和 CodeBuddy 到底啥区别该用哪个。我的理解是CodeBuddy 偏代码场景WorkBuddy 偏通用办公场景。如果你主要写代码CodeBuddy 的代码补全和重构能力更顺手如果你要处理文档、数据、自动化流程WorkBuddy 的 Skill 机制更灵活。两者不是替代关系是互补关系。我自己的做法是两个都装按任务类型切换。关于“AI Agent 怎么扛并发”这个问题我的经验是别指望单个 Agent 扛高并发。正确的做法是把任务拆解用多个 Agent 实例并行处理每个实例负责一部分。WorkBuddy 支持多模型配置本质上就是为了做负载分流。如果你的场景真的需要高并发建议在 WorkBuddy 外面再套一层任务队列把任务分发到多个 WorkBuddy 实例上。最后说个我踩过的坑不要把所有任务都交给一个 Skill。我一开始图省事写了个“万能 Skill”结果模型经常搞混步骤该整理文件的时候去调 API该调 API 的时候去读文件。后来拆成五个独立 Skill每个只干一件事稳定性立马就上来了。Skill 的设计哲学跟微服务有点像——单一职责组合使用。还有一个体会是WorkBuddy 的 Skill 生态还在早期很多场景需要自己动手写。但这恰恰是它的价值所在——你写的每一个 Skill 都是在积累自己的自动化资产。今天写个文件整理明天写个数据清洗攒上二三十个 Skill你的工作台就真的成型了。到那时候WorkBuddy 才真正成为你的“工作伙伴”而不是一个“聊天工具”。
WorkBuddy AI Agent工作台实战：Skill机制与models.json配置指南
1. 为什么我要认真写这篇 WorkBuddy 实战指南第一次听说 WorkBuddy 是在一个技术群里有人甩了张截图说腾讯出了个 AI 工作台能把日常那些重复性的活儿全接过去。当时我的反应跟大多数人一样又一个套壳产品吧直到我自己装了一遍、配了一遍、踩了一遍坑才发现这东西跟市面上那些“对话式 AI 助手”完全不是一个物种。WorkBuddy 的核心定位是AI Agent 工作台不是聊天机器人。它通过Skill技能机制让 AI 真正“下地干活”——读写文件、执行脚本、调用 API、处理数据、生成报告这些操作它都能在本地环境里完成。你可以把它理解成一个“AI 调度中心”你告诉它要做什么它自己规划步骤、调用工具、执行任务、返回结果。跟 CodeBuddy 那种偏代码补全的工具不同WorkBuddy 的覆盖面更广从文档处理到数据分析到自动化流程都能插一脚。这篇文章适合哪些人看如果你是开发者想搞清楚 AI Agent 到底怎么落地WorkBuddy 是个很好的切入点如果你是普通办公用户想用 AI 替自己干掉那些枯燥的重复劳动这篇也能帮你少走弯路如果你已经在用类似产品但总觉得“差点意思”那大概率是 Skill 配置和 models.json 没调对。我会从安装部署讲到 Skill 开发从 models.json 配置讲到常见坑的排查尽量把每个环节的“为什么”都说清楚。注意本文基于 WorkBuddy 国内版的实际使用经验撰写国际版在部分功能入口和模型选择上有差异但核心逻辑相通。2. WorkBuddy 安装部署从零到能跑起来2.1 安装前的环境准备与版本选择WorkBuddy 的安装本身不复杂但环境准备阶段有几个容易忽略的点。首先说操作系统Windows 10 以上、macOS 12 以上都能跑Linux 桌面版支持也在逐步完善。我的建议是优先用 macOS 或 WindowsLinux 下某些 Skill 的兼容性还不够稳定尤其是涉及系统级文件操作的场景。硬件方面官方给的最低配置是 8GB 内存但实测下来如果你打算同时跑多个 Skill 或者处理大文件16GB 内存是起步线。CPU 倒不是瓶颈因为大部分计算负载都在云端模型侧本地主要跑的是调度和文件 IO。硬盘空间留够 5GB 就行主要是缓存和日志。安装包获取渠道这里不展开只说一点认准官方渠道。网上有些第三方打包的版本夹带了修改过的 models.json用着用着发现请求被转发到不明地址这种事不是没发生过。安装过程中有一个选项值得注意是否更改默认缓存目录。默认情况下 WorkBuddy 会把缓存放在系统盘的用户目录下Windows 是C:\Users\你的用户名\.workbuddymacOS 是~/.workbuddy。如果你系统盘空间紧张或者想让缓存和项目文件放在一起方便管理这一步就要改。具体怎么改后面会讲。2.2 首次启动与基础配置流程装完之后第一次启动WorkBuddy 会引导你走一个初始化流程。这个流程里最关键的一步是模型接入配置。WorkBuddy 本身不绑定特定模型它通过 models.json 来管理模型接入信息。你可以用官方推荐的模型也可以接自己的 API。初始化界面会让你选择“快速开始”还是“手动配置”。强烈建议选手动配置因为快速开始会帮你填一堆默认值后面改起来反而麻烦。手动配置里你需要填模型提供方的 API 地址API Key模型名称比如某个具体的模型标识可选的代理设置如果你在公司内网环境填完之后点测试连接能通就说明配置没问题。这里有个小细节API 地址末尾不要多加斜杠有些模型服务对 URL 格式很敏感多一个斜杠就报 404。我在这上面浪费了半小时后来看日志才发现。初始化完成后WorkBuddy 会问你“是否导入示例 Skill”。建议选是因为示例 Skill 能帮你快速理解 Skill 的结构和运行方式后面自己写的时候有参照。2.3 更改缓存目录与数据迁移的正确姿势缓存目录这事值得单独说因为问的人太多了。WorkBuddy 的缓存分三类模型响应缓存、Skill 运行日志、临时文件。默认都在系统盘时间一长可能占几个 GB。改缓存目录的方法完全退出 WorkBuddy不是最小化到托盘是彻底退出找到配置文件Windows 在%APPDATA%\WorkBuddy\config.jsonmacOS 在~/Library/Application Support/WorkBuddy/config.json编辑cacheDir字段改成你想要的路径比如D:\WorkBuddyCache或/Users/你的用户名/workbuddy-cache把原缓存目录下的内容手动复制到新目录重新启动 WorkBuddy注意改完路径后如果启动报错大概率是权限问题。Windows 下确保新目录不在需要管理员权限的位置macOS 下确保当前用户有读写权限。另外路径中不要包含中文或特殊字符虽然理论上支持但实测偶尔出问题。数据迁移这块如果你之前已经用了一段时间缓存里有历史对话和 Skill 运行记录直接复制过去就行。但有一种情况例外如果你换了模型提供方建议清空模型响应缓存因为不同模型的响应格式可能有差异旧缓存可能导致解析错误。3. models.json 深度解析WorkBuddy 的模型调度中枢3.1 models.json 的结构与字段含义models.json 是 WorkBuddy 最核心的配置文件没有之一。它决定了 WorkBuddy 能用哪些模型、怎么调用、优先级如何。很多人装完 WorkBuddy 觉得“不好用”十有八九是 models.json 没配对。一个典型的 models.json 结构长这样{ models: [ { name: 主力模型, provider: custom, apiBase: https://api.example.com/v1, apiKey: sk-xxxxxxxx, model: model-name-here, maxTokens: 4096, temperature: 0.7, priority: 1, capabilities: [chat, function_call] } ], defaultModel: 主力模型, fallbackModel: 备用模型 }逐个字段解释name模型在 WorkBuddy 界面里显示的名字随便起但建议起个能看懂的provider提供方类型一般填custom就行除非你用官方预置的apiBaseAPI 地址注意要包含版本路径比如/v1apiKey你的密钥model模型的实际标识符这个必须跟提供方文档一致maxTokens单次响应的最大 token 数根据模型能力填temperature温度参数0 到 1 之间越低越确定越高越随机priority优先级数字越小越优先多个模型时 WorkBuddy 会按这个顺序尝试capabilities模型支持的能力列表比如chat、function_call、vision等defaultModel是默认使用的模型fallbackModel是默认模型调用失败时的备选。这两个字段在稳定性要求高的场景下很重要。3.2 多模型配置与优先级策略WorkBuddy 支持同时配置多个模型这在实战中非常有用。比如你可以配一个“快模型”处理简单任务一个“强模型”处理复杂推理一个“便宜模型”做批量处理。多模型配置的关键是priority 和 capabilities 的配合。举个例子{ models: [ { name: 快速模型, priority: 1, capabilities: [chat], model: fast-model }, { name: 推理模型, priority: 2, capabilities: [chat, function_call], model: reasoning-model }, { name: 备用模型, priority: 3, capabilities: [chat], model: backup-model } ] }当 WorkBuddy 需要执行一个需要 function_call 能力的 Skill 时它会跳过“快速模型”因为不支持 function_call直接选“推理模型”。如果推理模型调用失败再降级到备用模型。这个机制的好处是你不需要手动切换模型WorkBuddy 会根据任务需求自动选择。但前提是你的 capabilities 字段填对了。我见过有人把所有模型的 capabilities 都写成[chat]结果 Skill 死活跑不起来排查半天才发现是这里的问题。3.3 常见配置错误与修复方法models.json 的配置错误五花八门我整理了几个高频问题错误现象可能原因修复方法启动报 JSON 解析错误文件格式不对比如多了逗号、少了引号用 JSON 校验工具检查模型列表为空models 数组为空或字段名拼错检查models拼写确保是数组调用返回 401apiKey 错误或过期重新生成密钥并更新调用返回 404apiBase 路径不对确认是否包含/v1等版本路径Skill 无法执行capabilities 缺少 function_call补充 capabilities 字段响应超时maxTokens 设置过大或网络问题降低 maxTokens检查网络还有一个隐蔽的坑JSON 文件编码。如果你在 Windows 上用记事本编辑 models.json保存时可能变成 GBK 编码WorkBuddy 读的时候按 UTF-8 解析就会乱码。务必用 VS Code 或 Notepad 这类编辑器保存时选 UTF-8。实操心得改完 models.json 后不要急着重启 WorkBuddy。先在界面里点“重新加载配置”如果加载成功再重启。这样能快速定位是配置问题还是其他问题。4. Skill 机制全解让 AI 真正“下地干活”4.1 Skill 是什么从概念到实际作用Skill 是 WorkBuddy 的灵魂。没有 Skill 的 WorkBuddy 就是个普通聊天窗口有了 Skill 它才能读写文件、执行命令、调用接口、处理数据。用大白话说Skill 就是一段告诉 WorkBuddy“遇到什么情况该怎么做”的指令集。它包含三部分触发条件什么情况下用这个 Skill执行逻辑具体做什么分几步输出格式结果怎么返回给用户举个例子一个“整理桌面文件”的 Skill触发条件是用户说“帮我整理桌面”执行逻辑是“扫描桌面目录 → 按文件类型分类 → 创建对应文件夹 → 移动文件”输出格式是“已整理 X 个文件分类如下...”。Skill 的本质是一段结构化文本WorkBuddy 把它注入到模型的上下文里模型根据 Skill 的描述来决定调用哪些工具、按什么顺序执行。所以Skill 写得好不好直接决定了 AI 干活的质量。4.2 Skill 的编写规范与最佳实践写 Skill 有几个核心原则第一触发条件要明确。不要写“当用户需要处理文件时”太模糊了。要写“当用户输入包含‘整理’、‘分类’、‘归档’且涉及文件路径时”。越具体模型判断越准。第二执行步骤要可操作。每一步都应该是模型能理解并执行的动作。比如“读取文件内容”可以“理解文件含义”就不行因为后者太抽象。第三输出格式要固定。模型返回结果时格式固定能让后续处理更顺畅。比如统一用 JSON 返回或者统一用 Markdown 表格。一个 Skill 的基本结构# Skill: 文件整理 ## 触发条件 用户要求整理指定目录下的文件 ## 执行步骤 1. 确认目标目录路径 2. 扫描目录下所有文件 3. 按扩展名分类 4. 创建分类文件夹 5. 移动文件到对应文件夹 6. 返回整理结果 ## 输出格式 已整理 [数量] 个文件 - 文档类[数量] 个 - 图片类[数量] 个 - 其他[数量] 个这个结构看起来简单但实际写的时候有很多细节要注意。比如“扫描目录”这一步要说明是否包含子目录“移动文件”要说明是否覆盖同名文件。这些细节不写清楚模型就会按自己的理解来结果往往不是你想要的。4.3 热门 Skill 类型与适用场景盘点根据我的使用经验WorkBuddy 上最实用的 Skill 大概分这几类文件处理类批量重命名、格式转换、内容提取、目录整理。这类 Skill 门槛低、见效快适合刚上手的人。数据类CSV 解析、Excel 处理、数据清洗、报表生成。这类 Skill 对格式要求高写的时候要把输入输出格式定死。网络类API 调用、网页内容抓取、数据同步。这类 Skill 要注意错误处理和超时设置。开发辅助类代码格式化、日志分析、配置生成。这类 Skill 适合开发者能省不少重复劳动。办公自动化类邮件草稿生成、会议纪要整理、文档模板填充。这类 Skill 对文本处理能力要求高。有个热词叫“book to skill”意思是把一本书的内容转化成 Skill。这个思路挺有意思比如你把一本写作指南转化成 SkillWorkBuddy 就能按指南里的方法帮你改文章。但实际操作中一本书的内容太多直接塞进 Skill 会超出上下文限制需要做摘要和结构化处理。4.4 Skill 调试与迭代的实战技巧Skill 写完不是终点调试才是重头戏。我的调试流程一般是先用简单输入测试比如文件整理 Skill先拿一个只有三五个文件的目录试看日志WorkBuddy 的 Skill 运行日志会记录每一步的执行情况哪里卡住了一目了然逐步增加复杂度简单场景跑通了再试复杂场景比如嵌套目录、特殊文件名记录失败案例每次失败都记下来分析是 Skill 描述问题还是模型理解问题有个技巧很管用在 Skill 里加“如果...则...”的分支逻辑。比如“如果目录为空则返回‘目录为空无需整理’”。这样能避免模型在边界情况下瞎猜。还有一点Skill 不是越详细越好。太详细会占用大量上下文反而影响模型对其他信息的处理。一般来说一个 Skill 控制在 500 到 1500 字之间比较合适。超过这个范围就要考虑拆成多个 Skill。5. 实操全流程从零搭建一个文件整理工作台5.1 需求分析与方案设计假设你每天都要处理大量下载文件桌面乱成一锅粥。你想让 WorkBuddy 帮你自动整理按文件类型分到不同文件夹。需求拆解输入一个目录路径处理扫描文件 → 识别类型 → 创建分类文件夹 → 移动文件输出整理结果摘要方案设计时考虑几个问题文件类型怎么判断按扩展名最靠谱分类粒度多细太细了文件夹太多太粗了没意义。建议按“文档、图片、视频、音频、压缩包、其他”六类同名文件怎么处理加时间戳后缀子目录要不要处理默认不处理避免误操作5.2 Skill 编写与配置落地根据上面的设计Skill 可以这样写# Skill: 下载目录整理 ## 触发条件 用户要求整理下载目录或指定目录下的文件 ## 执行步骤 1. 获取用户指定的目录路径如果未指定则使用默认下载目录 2. 列出目录下所有文件不包含子目录 3. 按扩展名分类 - 文档doc, docx, pdf, txt, md, xlsx, pptx - 图片jpg, jpeg, png, gif, webp, svg - 视频mp4, avi, mkv, mov - 音频mp3, wav, flac, aac - 压缩包zip, rar, 7z, tar, gz - 其他不在上述范围内的 4. 在目标目录下创建对应分类文件夹如果不存在 5. 移动文件到对应文件夹同名文件加时间戳后缀 6. 返回整理结果 ## 输出格式 整理完成共处理 [总数] 个文件 - 文档[数量] 个 - 图片[数量] 个 - 视频[数量] 个 - 音频[数量] 个 - 压缩包[数量] 个 - 其他[数量] 个把这个 Skill 保存为organize-downloads.md放到 WorkBuddy 的 Skill 目录下。Skill 目录的位置在设置里能看到一般是~/.workbuddy/skills/。然后在 WorkBuddy 界面里刷新 Skill 列表应该就能看到这个新 Skill 了。5.3 运行验证与效果调优第一次运行我建议拿一个测试目录试别直接上真实下载目录。测试目录里放几个不同类型的文件然后对 WorkBuddy 说“帮我整理测试目录”。观察运行日志看每一步是否按预期执行。常见问题文件没被移动可能是路径不对或者权限不够分类不对检查扩展名列表是否覆盖了实际文件类型同名文件被覆盖Skill 里要明确写“加时间戳后缀”跑通之后可以逐步增加复杂度。比如加入“跳过隐藏文件”、“跳过正在使用的文件”等逻辑。每次修改 Skill 后都要重新测试确保没有引入新问题。实操心得Skill 的迭代不要一次改太多。每次只改一个点测试通过后再改下一个。这样出问题时容易定位。6. 常见问题与排查技巧实录6.1 安装与启动类问题问题安装后启动闪退排查思路先看日志。WorkBuddy 的日志在缓存目录下的logs文件夹里。常见原因是 models.json 格式错误导致启动时解析失败。把 models.json 临时改名如果启动正常就说明是配置问题。问题界面显示“无可用模型”检查 models.json 里的models数组是否为空以及defaultModel是否指向了一个存在的模型名称。另外确认 API Key 没有过期。问题更改缓存目录后启动报错大概率是权限问题。Windows 下试试把目录设在用户目录下macOS 下用chmod确保权限。路径中不要有中文。6.2 Skill 运行类问题问题Skill 不触发检查触发条件是否太窄或太宽。太窄了模型匹配不到太宽了会误触发。建议在触发条件里加入具体的动词和名词组合。问题Skill 执行到一半卡住看日志里最后执行到哪一步。常见原因是某一步需要调用的工具不可用比如文件路径不存在、API 超时。在 Skill 里加入错误处理逻辑比如“如果文件不存在则跳过并记录”。问题Skill 输出格式不对模型有时候会“自由发挥”不按你定义的格式返回。解决办法是在 Skill 里强调“必须严格按照以下格式输出”并在输出格式部分给出具体示例。6.3 模型调用类问题问题调用返回 429请求过多说明触发了速率限制。解决办法降低并发或者在 models.json 里配置多个模型做负载均衡。问题响应内容被截断检查 maxTokens 设置。如果任务需要长输出把 maxTokens 调大。但注意不要超过模型本身的上限。问题模型不理解中文指令有些模型对中文支持不好。解决办法在 Skill 里用中英双语写关键指令或者在 models.json 里优先选择中文能力强的模型。6.4 性能与稳定性优化建议缓存策略WorkBuddy 默认会缓存模型响应。如果任务对实时性要求高可以在配置里关闭缓存。并发控制同时跑多个 Skill 时注意模型 API 的并发限制。建议在 models.json 里设置合理的超时和重试参数。日志管理日志文件会越来越大建议定期清理。可以在配置里设置日志保留天数。Skill 加载优化Skill 太多会影响启动速度。不常用的 Skill 可以移到备份目录需要时再放回来。7. 关于 WorkBuddy 和 CodeBuddy 的选择以及一些个人体会经常有人问 WorkBuddy 和 CodeBuddy 到底啥区别该用哪个。我的理解是CodeBuddy 偏代码场景WorkBuddy 偏通用办公场景。如果你主要写代码CodeBuddy 的代码补全和重构能力更顺手如果你要处理文档、数据、自动化流程WorkBuddy 的 Skill 机制更灵活。两者不是替代关系是互补关系。我自己的做法是两个都装按任务类型切换。关于“AI Agent 怎么扛并发”这个问题我的经验是别指望单个 Agent 扛高并发。正确的做法是把任务拆解用多个 Agent 实例并行处理每个实例负责一部分。WorkBuddy 支持多模型配置本质上就是为了做负载分流。如果你的场景真的需要高并发建议在 WorkBuddy 外面再套一层任务队列把任务分发到多个 WorkBuddy 实例上。最后说个我踩过的坑不要把所有任务都交给一个 Skill。我一开始图省事写了个“万能 Skill”结果模型经常搞混步骤该整理文件的时候去调 API该调 API 的时候去读文件。后来拆成五个独立 Skill每个只干一件事稳定性立马就上来了。Skill 的设计哲学跟微服务有点像——单一职责组合使用。还有一个体会是WorkBuddy 的 Skill 生态还在早期很多场景需要自己动手写。但这恰恰是它的价值所在——你写的每一个 Skill 都是在积累自己的自动化资产。今天写个文件整理明天写个数据清洗攒上二三十个 Skill你的工作台就真的成型了。到那时候WorkBuddy 才真正成为你的“工作伙伴”而不是一个“聊天工具”。
