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

第一次打开 WorkBuddy 的时候，我的反应和大多数人一样：这不就是个套壳的对话工具吗？但真正用了一周之后，我发现自己错得离谱。它更像是一个把 AI Agent 能力、Skill 插件体系、工作流编排揉在一起的“工作台”，而不是单纯的聊天窗口。你可以在里面挂载不同的 Skill，让 AI 按照你预设的规则去处理文件、生成内容、调用外部能力，甚至把一整套流程固化下来反复使用。

这篇内容适合三类人：第一类是刚听说 WorkBuddy、想搞清楚它和普通 AI 对话工具有什么区别的新手；第二类是已经装了但卡在配置环节、不知道 models.json 和 Skill 怎么配合的进阶用户；第三类是想把 WorkBuddy 当成 AI Agent 练手项目、借此理解 Agent 搭建逻辑的开发爱好者。我会从安装讲到配置，从 Skill 机制讲到实际避坑，尽量把每个“为什么”都说清楚，而不是只丢一堆步骤让你照抄。

需要先说明一点：WorkBuddy 这类工具迭代很快，界面和配置项可能随时调整。我写的是截至我实操时的稳定路径和通用逻辑，具体按钮位置如果和你看到的不一样，优先看官方最新说明，但底层思路是相通的。

2. WorkBuddy 到底是什么：先搞懂它的定位再动手

2.1 它和普通 AI 对话工具的核心区别

普通 AI 对话工具的逻辑是“你问一句，它答一句”，每次对话都是独立的，它不会主动帮你干活。WorkBuddy 的逻辑是“你给它一个工作台，它在这个台子上按规则干活”。这个区别听起来不大，但实际使用中差异非常明显。

WorkBuddy 的核心能力体现在三个层面。第一层是工作台概念，你可以把它理解成一个专门用来处理某类任务的独立空间，里面可以预设规则、挂载工具、保存上下文。第二层是Skill 体系，Skill 相当于给 AI 装的“技能包”，每个 Skill 定义了一类特定任务的处理方式，比如文档处理、代码生成、数据分析等。第三层是Agent 调度，WorkBuddy 会根据你的指令自动判断该调用哪个 Skill、该按什么顺序执行，而不是每一步都等你手动指挥。

我举个实际例子你就明白了。普通对话工具里，你想让它帮你整理一份会议纪要，你得把内容贴进去，然后说“帮我总结成纪要格式”，它给你一段文字，你再复制出来。而在 WorkBuddy 里，你可以挂载一个“会议纪要”Skill，设定好输出格式模板，然后把原始记录丢进去，它直接按你的模板生成结构化纪要，甚至能自动提取待办事项并分配到对应负责人。这就是“工作台”和“聊天框”的本质差异。

2.2 谁适合用 WorkBuddy，谁可以先观望

不是所有人都需要 WorkBuddy。如果你只是偶尔问个问题、查个资料，普通对话工具完全够用，没必要折腾配置。但如果你符合以下任意一条，WorkBuddy 的价值就会非常明显：

• 你每天有大量重复性的文档处理、信息整理、格式转换工作
• 你想把某类任务的固定流程固化下来，不想每次都重新描述需求
• 你对 AI Agent 搭建感兴趣，想通过一个实际产品理解 Agent 的工作原理
• 你需要一个能长期保存规则和上下文的工作环境，而不是每次从零开始

反过来说，如果你对配置文件、JSON 格式、插件机制这些东西天然抵触，那 WorkBuddy 的上手成本会让你很痛苦。它不是一个“装完就能用”的纯图形化工具，前期需要你花时间理解它的配置逻辑。

2.3 关于国际版和国内版的差异

WorkBuddy 有国际版和国内版之分，两者在功能架构上基本一致，主要差异在于可访问的服务和部分 Skill 的默认配置。如果你只是做本地化的文档处理、代码辅助、内容生成，国内版完全够用。国际版在某些第三方服务的对接上可能更顺畅，但配置复杂度也相应更高。

我的建议是：先用国内版把核心流程跑通，理解 Skill 机制和 models.json 的配置逻辑，等你真正需要对接特定外部服务时再考虑切换。不要一上来就纠结版本选择，那会浪费你大量时间。

3. 安装与初始配置：把地基打牢

3.1 安装前的环境准备

WorkBuddy 支持 Windows、macOS 和 Linux 三个平台。安装包本身不大，但它在运行过程中会依赖一些基础环境，提前准备好能省掉很多报错。

Windows 用户需要确认系统版本在 Windows 10 1903 以上，并且已经安装了最新的 WebView2 运行时。很多安装后打不开的问题都是因为缺这个组件。macOS 用户需要 macOS 11 以上，Apple Silicon 和 Intel 芯片都有对应的安装包，下载时注意区分。Linux 用户的情况稍微复杂一些，WorkBuddy 在 Linux 上通常以 AppImage 或 deb 包形式分发，你需要确保系统有 FUSE 支持，否则 AppImage 无法运行。

注意：Linux 环境下如果遇到权限问题，不要直接 chmod 777，而是检查当前用户是否在正确的用户组里，以及安装目录的归属权限是否合理。

除了系统环境，你还需要准备一个可用的模型服务。WorkBuddy 本身不提供模型，它需要你配置外部模型接口。这就是 models.json 发挥作用的地方。

3.2 models.json 配置详解：别被 JSON 吓到

models.json 是 WorkBuddy 的核心配置文件之一，它决定了 WorkBuddy 能调用哪些模型、每个模型的参数是什么。很多人第一次看到这个文件就头大，其实它的结构非常清晰。

一个典型的 models.json 结构是这样的：

{ "models": [ { "name": "default-chat", "provider": "openai-compatible", "baseUrl": "https://your-api-endpoint/v1", "apiKey": "your-api-key-here", "model": "gpt-4o", "maxTokens": 4096, "temperature": 0.7 }, { "name": "code-model", "provider": "openai-compatible", "baseUrl": "https://your-api-endpoint/v1", "apiKey": "your-api-key-here", "model": "claude-sonnet-4-20250514", "maxTokens": 8192, "temperature": 0.3 } ] }

这里有几个关键点需要解释。name是你给这个模型配置起的别名，后面在 Skill 里引用时用的就是这个 name。provider指定接口协议类型，大多数兼容 OpenAI 接口的服务都填 openai-compatible。baseUrl是接口地址，注意结尾要不要带 /v1 取决于你的服务商要求，这个很容易填错。apiKey就是你的密钥，建议不要直接写在文件里，而是用环境变量引用。model是具体的模型标识符，不同服务商的命名规则不一样，填错了会直接报模型不存在。maxTokens和temperature是生成参数，前者控制最大输出长度，后者控制随机性。

我踩过的一个坑是：有些服务商的接口地址需要精确到 /v1/chat/completions，而 models.json 里只需要填到 /v1 就行，WorkBuddy 会自动补全后面的路径。如果你填多了，反而会报 404。这个细节官方文档里不一定写清楚，但实测下来是这样的逻辑。

另一个坑是 apiKey 的权限问题。如果你用的是子账号或受限密钥，要确保它有调用目标模型的权限。我遇到过配置完全正确但一直报 401 的情况，最后发现是密钥没有开通对应模型的访问权限。

3.3 首次启动后的必做设置

安装完成、models.json 配好之后，第一次启动 WorkBuddy 还有几件事必须做。

第一，在设置里确认模型连接状态。WorkBuddy 通常会提供一个“测试连接”的功能，点一下看能不能正常返回。如果报错，优先检查 baseUrl 和 apiKey，这两个是最容易出问题的地方。

第二，设置默认工作目录。WorkBuddy 在处理文件时需要知道去哪里找文件、把结果存到哪里。建议单独建一个工作目录，不要直接用桌面或下载文件夹，否则文件多了之后会很乱。

第三，配置 Skill 加载路径。WorkBuddy 的 Skill 通常以文件夹或压缩包形式存在，你需要告诉它去哪里扫描 Skill。默认路径一般够用，但如果你自己写了 Skill，就需要把自定义路径加进去。

第四，检查更新。WorkBuddy 迭代很快，新版本可能修复了旧版本的 bug 或增加了新功能。首次安装后先更新到最新版，能避免很多已知问题。

4. Skill 机制深度拆解：WorkBuddy 的真正威力所在

4.1 Skill 是什么，它和普通插件有什么区别

Skill 是 WorkBuddy 最核心的概念，也是最容易被误解的概念。很多人把它当成“插件”，但两者有本质区别。普通插件通常是给软件增加一个固定功能，比如给浏览器加个广告拦截。而 Skill 是给 AI 增加一种“做事的方法”，它包含的不仅是功能代码，还有提示词模板、执行逻辑、输出格式定义。

一个完整的 Skill 通常包含以下部分：

• 元信息：Skill 的名称、描述、版本、作者
• 触发条件：什么情况下 WorkBuddy 应该调用这个 Skill
• 提示词模板：告诉 AI 该怎么处理这类任务
• 输入输出定义：需要什么输入，产出什么格式
• 依赖声明：这个 Skill 需要哪些模型能力或外部工具

这意味着 Skill 不是简单的“功能开关”，而是一套完整的任务处理方案。你可以把 Skill 理解成一个“专家模板”，挂载之后，WorkBuddy 在处理对应任务时就会按照这个专家的方式来思考和输出。

4.2 内置 Skill 和自定义 Skill 的选择策略

WorkBuddy 自带了一批内置 Skill，覆盖了常见场景：文档总结、代码解释、翻译、格式转换、数据分析等。这些内置 Skill 的好处是开箱即用，不需要额外配置。但它们的通用性也意味着针对性不强，输出风格和格式可能不完全符合你的需求。

我的建议是：先用内置 Skill 跑一遍你的典型任务，观察它的输出哪里不符合预期。然后基于内置 Skill 的结构，改一个自定义版本出来。这样你既不需要从零开始写，又能得到完全贴合自己需求的 Skill。

自定义 Skill 的创建方式通常有两种。一种是在 WorkBuddy 的图形界面里直接新建，填写表单式的配置项。另一种是直接写 Skill 文件，通常是 Markdown 或 JSON 格式，放在 Skill 目录下。后者更灵活，适合需要复杂逻辑的场景。

提示：写自定义 Skill 时，提示词模板的质量直接决定输出质量。不要只写“帮我处理这个文档”，而要写清楚处理目标、输出格式、注意事项、示例。提示词越具体，AI 的表现越稳定。

4.3 Skill 编码与规则设定：让 AI 按你的规矩干活

WorkBuddy 有一个很实用的功能：你可以给工作台设定全局规则，这些规则会对后续所有任务生效。这相当于给 AI 定了一套“基本法”，不管它调用哪个 Skill，都要遵守这些规则。

规则设定的典型内容包括：

• 输出语言和风格（比如“始终用中文回答”“代码注释用英文”）
• 格式要求（比如“所有输出必须用 Markdown”“表格必须对齐”）
• 行为边界（比如“不要主动删除文件”“修改前必须先备份”）
• 上下文管理（比如“每次对话最多保留最近 10 轮”）

这些规则看起来简单，但实际使用中能极大提升稳定性。我试过不设规则直接让 WorkBuddy 处理一批文件，结果它有时候输出 JSON、有时候输出 YAML，格式完全不统一。后来加了“所有结构化输出统一用 JSON”的规则，问题就解决了。

规则设定的位置通常在设置或工作台配置里，不同版本可能叫法不同，但逻辑是一样的：找到“全局规则”或“系统提示词”相关的入口，把你的要求写进去。

4.4 从 Book to Skill：把知识变成可执行能力

“Book to Skill”是 WorkBuddy 社区里一个很火的概念，意思是把一本书、一份文档、一套方法论转化成 Skill，让 AI 按照这套知识体系来工作。

这个思路的价值在于：你不需要每次都在提示词里重复描述背景知识，而是把知识固化到 Skill 里，一次配置、反复使用。比如你读了一本关于写作的书，可以把书里的核心方法论提炼成 Skill，以后让 WorkBuddy 写东西时自动应用这套方法。

具体操作上，你需要做三件事。第一，把知识源整理成结构化的提示词，提取核心原则、步骤、检查清单。第二，定义触发条件，明确什么任务该用这个 Skill。第三，设计输出格式，让 AI 按照知识体系的要求来产出内容。

这个过程听起来抽象，但实际操作一次就明白了。我建议从你手头最熟悉的一个领域开始，把你知道的最佳实践写成 Skill，然后观察 WorkBuddy 的表现，再逐步迭代。

5. 完整实操流程：从零跑通一个 WorkBuddy 任务

5.1 场景设定：用 WorkBuddy 处理一批技术文档

为了让你有具体的参照，我用一个真实场景来演示完整流程：我手头有 20 篇技术文章，需要 WorkBuddy 帮我做三件事——提取每篇的核心观点、生成统一格式的摘要卡片、把摘要汇总成一份索引表。

这个任务涉及文件读取、内容理解、格式生成、结果汇总四个环节，能比较全面地展示 WorkBuddy 的工作方式。

5.2 第一步：配置模型和基础环境

先确认 models.json 里至少有一个可用的模型配置。对于这个任务，我建议用长上下文能力较强的模型，因为要处理多篇文档。temperature 设低一点，0.3 左右，保证输出稳定。

然后在 WorkBuddy 里新建一个工作台，命名为“技术文档处理”。在工作台设置里，把默认工作目录指向存放那 20 篇文章的文件夹。

5.3 第二步：挂载和配置 Skill

这个任务需要两个 Skill：一个负责内容提取和摘要生成，一个负责格式化和汇总。WorkBuddy 内置的“文档总结”Skill 可以满足第一个需求，但输出格式需要调整。我在内置 Skill 基础上复制了一份，修改了提示词模板，要求输出包含“核心观点”“关键论据”“适用场景”三个字段的 JSON。

第二个 Skill 我直接写了一个简单的格式化 Skill，输入是多个 JSON 摘要，输出是 Markdown 表格。

5.4 第三步：设定全局规则

在工作台的全局规则里，我写了三条：

1. 所有输出使用中文，技术术语保留英文原文
2. 结构化数据统一用 JSON 格式，字段名用英文
3. 处理文件时先读取再操作，不要修改原始文件

这三条规则确保了后续所有 Skill 的输出风格一致，不会出现中英文混杂或格式跳变的情况。

5.5 第四步：执行任务并观察过程

把 20 篇文章的路径告诉 WorkBuddy，让它按顺序处理。它会自动调用第一个 Skill 逐篇生成摘要，然后调用第二个 Skill 汇总。整个过程你可以在日志或执行记录里看到它每一步在做什么。

这里有个实用技巧：不要一次性丢 20 篇进去，先拿 2 篇试跑，确认输出格式符合预期后再批量处理。我一开始直接跑了 20 篇，结果发现摘要字段名不对，全部重跑了一遍，浪费了不少时间。

5.6 第五步：结果校验和迭代

跑完之后，检查输出结果。重点看三个地方：摘要是否准确、格式是否统一、有没有遗漏的文章。如果发现问题，回到 Skill 配置里调整提示词，然后重新跑有问题的部分。

这个迭代过程通常需要两到三轮才能达到满意效果。第一轮解决格式问题，第二轮解决准确性问题，第三轮微调输出风格。不要指望一次配置就完美。

6. 常见问题与避坑指南

6.1 安装和启动阶段的典型问题

6.2 Skill 不生效的排查思路

Skill 不生效是最常见的问题，排查顺序如下。先确认 Skill 是否被正确加载，在 WorkBuddy 的 Skill 管理界面看它是否显示为“已启用”。然后检查触发条件，有些 Skill 只在特定关键词或任务类型下才会被调用。接着看全局规则是否和 Skill 冲突，比如全局规则要求输出 JSON，但 Skill 模板要求输出 Markdown，AI 可能会困惑。最后检查模型能力，有些 Skill 依赖特定的模型能力，如果当前模型不支持，Skill 就无法正常工作。

6.3 输出质量不稳定的优化方法

AI 输出不稳定是常态，但可以通过以下方法改善。降低 temperature 到 0.2-0.4 之间，减少随机性。在提示词里加入具体示例，让 AI 有参照。把复杂任务拆成多个简单步骤，每一步只做一件事。增加输出格式的约束条件，越具体越好。如果还是不稳定，考虑换一个能力更强的模型。

6.4 性能和安全方面的注意事项

处理大量文件时，注意 WorkBuddy 的内存占用。如果一次处理几百个文件，建议分批进行。apiKey 不要明文写在 models.json 里，用环境变量或密钥管理工具。工作目录不要设在系统盘根目录，避免权限问题。定期清理不需要的 Skill 和缓存文件，保持工作台轻量。

注意：如果你在团队环境里使用 WorkBuddy，确保每个人的 apiKey 和模型配置是独立的，不要共用密钥，否则用量统计和权限管理会很混乱。

7. 我对 WorkBuddy 的实际使用体会

用了一个多月之后，我最大的感受是：WorkBuddy 的价值不在于它本身有多强，而在于它让你能把 AI 能力“固化”下来。普通对话工具每次都要重新描述需求，而 WorkBuddy 通过 Skill 和规则体系，让你配置一次就能反复使用。这个从“每次都要说”到“配置好就行”的转变，才是效率提升的关键。

另一个体会是：不要试图一次性配置完美。我一开始花了很多时间设计复杂的 Skill 和规则，结果实际跑起来发现很多假设不成立。后来改成“先跑通再优化”的思路，先用最简单的配置跑一个任务，根据实际输出逐步调整，效率反而高很多。

最后分享一个小技巧：把你最常用的三个任务分别做成 Skill，然后给每个 Skill 写清楚使用场景和输出示例。这样即使过了一段时间你忘了怎么用，打开 Skill 描述就能快速回忆起来。这个习惯帮我省了很多重新摸索的时间。