1. 先搞清楚 WorkBuddy 到底是个什么东西

很多人第一次听到 WorkBuddy 这个名字，会下意识把它归类成"又一个套壳聊天窗口"。我一开始也这么想，直到真正把它装到工作机上、配好 models.json、跑通第一个 Skill 之后，才发现它和普通对话式工具完全不是一回事。WorkBuddy 是腾讯推出的 AI 工作台，核心定位是把大模型能力、本地文件系统、可复用的 Skill 脚本、以及多模型接入配置整合到一个桌面端环境里，让你不是"跟 AI 聊天"，而是"让 AI 在你的机器上干活"。

这个区别非常关键。聊天窗口里的 AI 只能给你建议，WorkBuddy 里的 AI Agent 能读你的文件、改你的配置、按你定义的 Skill 流程一步步执行任务。它更像是一个"可编程的助手运行时"，而不是一个问答机器人。关键词里反复出现的 AI Agent、Skill、models.json，其实就是这个工作台的三根支柱：Agent 负责决策和调度，Skill 负责把重复劳动固化成可调用单元，models.json 负责告诉它用哪个模型、走哪条通道。

适合谁来用？我观察下来大致分三类。第一类是每天要处理大量重复文本、表格、代码的职场人，比如运营、产品、研发，他们最需要的是"把一件事描述一次，以后自动跑"。第二类是想入门 AI Agent 开发但不想一上来就啃框架文档的开发者，WorkBuddy 的 Skill 机制是一个很好的过渡，你写的是接近自然语言加少量结构化配置的东西，但背后跑的是真正的 Agent 调度逻辑。第三类是把 WorkBuddy 当个人工作台来搭的人，比如用它管理笔记、整理资料、批量处理文件，甚至有人研究能不能接行情数据做辅助分析——这类需求能不能成，后面我会专门讲边界。

需要先泼一盆冷水：WorkBuddy 不是装上就自动变聪明的魔法盒。它的能力上限取决于三件事——你接的模型够不够强、你写的 Skill 够不够清晰、你给的上下文够不够准。我见过太多人装完之后随便问两句觉得"也就那样"，然后卸载。问题不在工具，在于他们没跨过"配置"和"Skill 编写"这两道门槛。这篇就把这两道门槛连同中间所有的坑，一次讲透。

2. 安装与首次配置：那些文档不会告诉你的细节

2.1 安装前的环境自查清单

安装本身不复杂，但装之前的准备工作决定了你后面会不会反复重装。我踩过的第一个坑就是没检查磁盘和权限，装到一半失败，残留文件又没清干净，第二次装直接报冲突。

先确认三件事。第一，系统盘剩余空间。WorkBuddy 本体加上模型缓存、日志、Skill 运行产生的临时文件，实际占用会比你预期的大不少，建议至少留出 20GB 以上。第二，当前账户是否有对安装目录和目标工作目录的读写权限。如果你在公司电脑上、账户是受限权限，安装到系统目录大概率会失败，这种情况直接装到用户目录下。第三，网络环境是否稳定。首次启动往往需要拉取一些基础资源，网络抖动会导致初始化不完整，表现就是界面能打开但功能报错。

提示：安装路径尽量不要带中文和空格。这不是 WorkBuddy 独有的问题，但它在处理本地文件路径时对特殊字符比较敏感，带中文路径出现过 Skill 读取文件失败的情况。

2.2 首次启动后的三件事

装完第一次打开，别急着聊天。按顺序做这三件事，能省掉后面 80% 的困惑。

第一件，找到并理解 models.json。这个文件是 WorkBuddy 的模型接入配置中心，它决定了你的 Agent 用哪个模型、走什么接口、带什么参数。文件结构通常是 JSON 格式，里面会有模型名称、接口地址、密钥字段、以及一些可选参数比如温度、最大输出长度。你要做的是把可用的模型信息填进去，保存后重启或重新加载配置。很多人卡在这一步，是因为不知道字段含义，随便填导致调用失败。

第二件，确认默认工作目录。WorkBuddy 的 Agent 读写文件是相对于某个工作目录的，这个目录如果没设对，你会遇到"AI 说它改了文件但你在别处找不到"的诡异现象。建议单独建一个干净的目录作为工作区，不要直接指向整个用户目录或桌面，避免 Agent 误操作波及重要文件。

第三件，跑一个最小验证。新建一个文本文件，写一句话，然后让 Agent 读取并总结。这一步能同时验证模型接入是否正常、文件权限是否正常、Agent 调度是否正常。三个都通过，说明基础环境没问题，可以进入下一步。

2.3 models.json 的字段逻辑与常见填错

models.json 是新手最容易翻车的地方，我把它拆开讲。一个典型的配置里，每个模型条目大致包含这几类信息：标识名（你给这个模型起的内部名字）、接口地址（请求发到哪里）、认证信息（密钥或令牌）、模型标识（对方服务认识的模型 ID）、以及可选的生成参数。

填错的高频点有三个。一是把"你起的名字"和"对方认识的模型 ID"搞混，前者随便起，后者必须和服务商文档一致，填错就是 404 或模型不存在。二是认证信息格式，有的要求带特定前缀，有的直接填原始密钥，多一个空格都会失败。三是接口地址结尾的斜杠，有的服务对结尾斜杠敏感，多一个少一个行为不同。

我的建议是：第一次配置只填一个模型，跑通之后再加第二个。一次填五个然后全部报错，你根本不知道是哪个的问题。跑通一个之后，复制它的结构改字段，出错概率大幅下降。

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

热搜里有人问"WorkBuddy 怎么更改系统缓存目录"，这确实是个真实痛点，因为默认缓存目录往往在系统盘，用久了会把 C 盘吃满。正确做法不是直接剪切文件夹，那样会导致索引失效。

稳妥的流程是：先在设置或配置文件里找到缓存路径配置项，把它改成你想要的目录，保存。然后重启 WorkBuddy，让它在新位置重建缓存结构。最后再手动清理旧目录里的残留。顺序反了就会出现"改了路径但程序还在读旧缓存"或者"新旧缓存打架"的情况。改完之后建议观察一两天，确认新目录确实在增长、旧目录不再变化，再彻底删除旧的。

3. Skill 机制：WorkBuddy 真正的生产力所在

3.1 Skill 到底是什么，为什么它比提示词重要

如果说 Agent 是大脑，Skill 就是肌肉记忆。提示词是你每次都要重新说一遍的话，Skill 是你把这段话固化下来、起个名字、以后一句话就能调用。这是 WorkBuddy 区别于普通对话工具的核心。

举个具体例子。你每天都要把一批会议记录整理成固定格式的纪要：提取参会人、列出决议、标注待办。如果每次都用提示词，你得把格式要求重复粘贴一遍，还容易漏。写成 Skill 之后，你只需要说"用纪要 Skill 处理这个文件"，Agent 就会按你预设的流程走：读文件、按规则提取、按模板输出。省的不只是打字时间，更是"每次都要重新交代一遍"的心智负担。

Skill 的本质是一段结构化的指令加可选的脚本逻辑。它可以是纯提示词封装，也可以带实际执行的脚本，比如调用某个命令、处理某类文件。关键词里出现的 skill 脚本、skill 开发指南、skill 插件，说的都是这个体系的不同侧面。

3.2 一个 Skill 的解剖结构

虽然不同版本的 WorkBuddy 在 Skill 的具体写法上可能有差异，但一个完整 Skill 通常包含这几个部分，理解了它们你就能自己写。

• 名称与描述：名称是调用时的标识，描述是给 Agent 判断"什么时候该用这个 Skill"的依据。描述写得越清楚，Agent 越不容易用错或用漏。
• 触发条件：什么情况下启用。可以是关键词触发，也可以是 Agent 根据任务语义自主判断。
• 执行步骤：核心部分，一步步说明要做什么。这里要写得像给一个新同事交代任务，具体、无歧义。
• 输入输出约定：输入是什么格式，输出是什么格式。这一步很多人偷懒不写，结果 Skill 跑出来的东西格式飘忽，没法直接用。
• 异常处理：文件不存在怎么办、格式不对怎么办。写上这一条，Skill 的健壮性会明显提升。

我个人的经验是，写 Skill 最忌讳"我以为它懂"。你觉得"整理一下"这三个字很清楚，但 Agent 不知道你要整理成什么。把"整理"拆成"删除空行、统一标点、按时间排序、输出为 Markdown 表格"，效果立刻不一样。

3.3 从零写第一个 Skill 的完整过程

假设我们要做一个"日报汇总 Skill"，把一天里散落在多个文件里的工作记录合并成一份日报。步骤如下。

第一步，明确输入。假设输入是工作目录下若干以日期命名的 txt 文件。第二步，明确输出。输出是一份 Markdown 格式的日报，包含日期标题、按类别分组的条目、以及一个总结段落。第三步，写执行步骤：扫描目录、筛选当天文件、逐个读取、按预设类别归类、合并去重、生成总结、写入输出文件。第四步，写异常处理：如果没有当天文件，输出提示而不是报错；如果文件编码异常，跳过并记录。

写完之后一定要测试，而且要用"边界情况"测试：空目录、只有一个文件、文件内容超长、文件里有特殊字符。我第一版 Skill 就是没测空目录，结果某天没记录时它直接报错中断，体验很差。

3.4 哪些 Skill 最值得先做

热搜里问"WorkBuddy 哪些 Skill 最好用"，这个问题没有标准答案，但有一个判断原则：优先做你每周都要重复三次以上、且步骤固定的事。

按这个原则，我推荐几个通用性强的方向。文本处理类，比如格式统一、批量替换、提取关键信息。文件管理类，比如按规则重命名、分类归档、批量转换格式。信息汇总类，比如把多个来源的内容合并成一份结构化文档。代码辅助类，比如按规范生成注释、检查命名、生成提交说明。

不建议一上来就做特别复杂的 Skill，比如涉及多步外部调用、复杂条件分支的。先把简单的做顺，建立对 Skill 运行逻辑的直觉，再往上叠复杂度。我见过有人第一个 Skill 就想做全自动工作流，结果调试到崩溃，最后放弃。循序渐进不是保守，是效率。

4. 把 WorkBuddy 用成真正的工作台：Agent 调度与规则设定

4.1 给 WorkBuddy 定规则，让后续任务自动生效

热搜里有一条"给 workbuddy 定几条规则，后续对所有任务都生效"，这其实点到了 Agent 使用的一个高级技巧：全局规则。你可以在配置里设定一些长期有效的约束，比如"输出一律用中文""涉及文件修改前先备份""不确定时先询问而不是直接执行"。这些规则一旦设定，后续所有任务都会遵守，不用每次重复交代。

这个功能的价值在于一致性。人交代任务会累、会漏，规则不会。我给自己定的几条规则里，最有用的是"修改任何文件前，先在旁边生成一个 .bak 备份"。就这一条，帮我挽回了好几次误操作。另一条是"输出结构化内容时优先用表格"，因为我后续要拿这些内容做二次处理，表格比散文好解析。

设定规则要注意别过度。规则太多太细，Agent 每次都要花精力去满足，反而影响主任务。我的建议是控制在五条以内，只放那些"违反了会很麻烦"的硬约束。

4.2 Agent 怎么扛并发：一个被问烂但很重要的问题

"AI Agent 怎么扛并发"是热搜里的高频问题。放到 WorkBuddy 的场景下，这个问题要分两层看。

第一层是模型接口层面的并发。如果你接的模型服务对并发请求有限制，同时发起太多任务会被限流或排队。WorkBuddy 作为客户端，能做的是控制同时运行的任务数量。实操上，如果你要批量处理几十个文件，不要一次性全丢进去，分批处理，每批控制在合理数量，观察是否有失败。

第二层是任务编排层面的并发。多个 Skill 同时读写同一批文件，会出现竞争。比如两个任务同时改一个文件，后写的覆盖先写的。解决办法是让任务之间尽量不共享文件，或者串行执行有依赖关系的任务。

我的实际做法是：批量任务先小规模试跑，确认稳定再放大；有文件依赖的任务一律串行；纯读取、无副作用的任务可以并行。这套原则不复杂，但能避开绝大多数并发问题。

4.3 多模型接入的取舍逻辑

WorkBuddy 支持接入多个模型，这带来一个现实问题：什么任务用什么模型。我的取舍逻辑是这样的。

需要强推理、复杂规划的任务，用能力最强的模型，哪怕慢一点、贵一点。这类任务数量少但价值高，值得投入。格式转换、简单提取、批量处理这类任务，用快而便宜的模型，因为量大，成本敏感。涉及代码的任务，优先选代码能力强的模型。涉及长文档理解的任务，优先选上下文窗口大的模型。

配置上，你可以在 models.json 里把多个模型都配好，然后在具体任务或 Skill 里指定用哪个。不要所有任务都用同一个模型，那是浪费。也不要频繁切换，切换本身有认知成本。找到两三个"主力模型"覆盖大部分场景就够了。

4.4 国际版与国内版的差异认知

热搜里"workbuddy 国际版"出现多次，说明有人关心版本差异。从使用角度看，不同版本在可接入的模型、界面语言、部分功能可用性上可能有区别。我的建议是：以你实际能稳定访问、能正常配置模型的那个版本为准，不要为了追求某个版本而折腾到无法使用。工具的价值在于用起来，不在于版本号。

如果你在两个版本之间犹豫，判断标准很简单：哪个版本能让你顺利跑通 models.json 配置、能正常调用 Skill，就用哪个。配置跑不通的版本，功能再多也和你无关。

5. 避坑实录：我踩过的那些坑和排查链路

5.1 配置改了不生效：缓存与重启的坑

这是最高频的坑。你改了 models.json，保存，然后发现行为没变。原因通常是配置被缓存了，程序还在用旧配置。

排查链路是这样的：先确认你改的是程序实际读取的那个文件，有时候存在多个同名文件在不同目录，你改的不是生效的那个。确认文件位置后，检查保存是否成功、格式是否合法，JSON 多一个逗号都会导致解析失败，而有些程序解析失败时会静默回退到默认配置，表现就是"改了没用"。最后，改完配置要重启或触发重新加载，很多配置不是热生效的。

我的习惯是：改配置前先备份，改完用工具校验 JSON 格式，然后完整重启一次，再验证行为。这套流程走下来，基本不会再遇到"改了不生效"。

5.2 Skill 调用错乱：描述不清导致的误触发

有一段时间我发现 Agent 老是调用错误的 Skill。排查后发现根因是 Skill 的描述写得太模糊，两个 Skill 的描述有重叠，Agent 分不清该用哪个。

解决办法是让每个 Skill 的描述具备排他性。不要写"处理文档"，要写"把多个 txt 文件合并成一份 Markdown 日报"。描述里带上具体的输入类型和输出类型，Agent 判断时就有明确依据。如果两个 Skill 确实功能相近，就在描述里写清楚各自的适用场景，比如一个用于"短文本快速处理"，一个用于"长文档深度整理"。

这个问题给我的教训是：Skill 的描述不是写给人看的备注，是写给 Agent 看的判断依据。你怎么写，它就怎么理解。

5.3 文件操作翻车：路径与权限的连环坑

Agent 操作文件时翻车，通常不是 Agent 笨，是路径和权限没理清。常见表现有三种：找不到文件、改了但找不到改在哪、没权限改。

排查顺序：先确认工作目录设置是否正确，Agent 的相对路径是相对于工作目录的。再确认文件是否真的存在、文件名是否完全匹配（大小写、扩展名）。然后确认权限，受限账户对某些目录没有写权限。最后确认是否有其他程序占用文件。

预防措施比排查更重要。我现在的做法是：所有 Agent 操作都在专门的工作目录里进行，不碰系统目录和个人重要目录；重要文件操作前自动备份；批量操作前先用一两个文件试跑。这三条让我后来几乎没再因为文件操作丢过东西。

5.4 输出格式飘忽：输入输出约定缺失的后果

Skill 跑出来的结果格式不稳定，今天这样明天那样，根因几乎都是没写清楚输入输出约定。Agent 每次都在"自由发挥"，结果自然不一致。

修复方法是在 Skill 里明确写死输出格式。不要写"输出一份报告"，要写"输出 Markdown，一级标题是日期，下面用无序列表列出条目，每条不超过 50 字"。越具体越稳定。如果输出要用于后续处理，最好给出一个示例，Agent 照着示例的格式走，一致性会好很多。

我现在的习惯是，凡是输出要进入下一步流程的 Skill，一律附一个格式示例。这个习惯让我的自动化流程稳定了不止一个档次。

6. 进阶玩法与边界认知

6.1 把 Skill 组合成工作流

单个 Skill 解决单点问题，多个 Skill 串起来就是工作流。比如"收集素材 Skill"加"整理 Skill"加"生成初稿 Skill"，三步串起来，你丢进去一堆原始材料，出来一份初稿。这才是 WorkBuddy 作为工作台的完整形态。

组合的关键是接口对齐。前一个 Skill 的输出格式，必须正好是后一个 Skill 能接受的输入格式。所以前面强调的输入输出约定，在组合场景下更重要。我建议组合之前，先把每个 Skill 单独跑稳，确认输出格式符合预期，再串起来。串起来之后先跑一次完整流程，观察每一步的中间产物，有问题好定位。

6.2 关于"用 AI Agent 做交易"这类需求的边界

热搜里有个问题问"个人使用 AI Agent 可以做期货交易吗"。我必须明确说：这类涉及真实资金、高风险决策的场景，不适合交给 AI Agent 自动执行。原因很直接，Agent 会出错，而这类场景出错的代价是真金白银，且往往不可逆。模型可能产生看似合理实则错误的判断，接口可能延迟，逻辑可能有边界漏洞。

Agent 在这类场景里能扮演的合理角色，是辅助信息整理和资料汇总，比如把公开信息归类、把历史数据整理成表格，供人自己做判断。决策和执行必须由人来做。这不是技术能力问题，是风险控制问题。任何声称能让 Agent 自动交易还稳赚的说法，都要保持警惕。

6.3 学习路线的建议

如果你想系统掌握 WorkBuddy 和 AI Agent，我的建议路线是这样的。先用起来，把基础配置跑通，用现成 Skill 处理真实任务，建立手感。然后开始改 Skill，在别人的基础上调整，理解每一处改动的影响。接着从零写 Skill，从最简单的开始，逐步加复杂度。最后学组合和规则设定，把单点能力串成工作流。

整个过程不要脱离真实任务。为了学而学，很快就没动力。带着一个你真正想解决的问题去学，每一步都有反馈，进步最快。我见过学得最快的人，都是有一堆重复劳动等着被自动化的人。

6.4 一些长期使用的心得

用了一段时间之后，我最大的体会是：WorkBuddy 的价值不在于它多聪明，而在于它把"重复劳动"这件事变得可管理。你把一件事想清楚、写成 Skill、跑通，它就永远替你做了。这个过程本身也在逼你把工作流程想清楚，很多以前模糊的环节，写 Skill 的时候被迫明确下来，反而提升了工作质量。

另一个体会是，不要追求一步到位。我最早的几个 Skill 都很粗糙，但能用。用着用着发现哪里不顺，再改。迭代出来的 Skill 比一次性设计出来的更贴合实际。工具是长出来的，不是设计出来的。

最后分享一个小技巧：定期回顾你的 Skill 库，把不再用的删掉，把常用的优化一下。Skill 多了之后，管理本身也是成本。保持精简，每个 Skill 都有明确用途，用起来才顺手。