WorkBuddy从0到1搭建指南：models.json配置与Skill开发实战

1. 先搞清楚 WorkBuddy 到底解决的是什么问题

很多人第一次听到 WorkBuddy 这个名字，第一反应是"又一个套壳聊天工具"。我一开始也这么想，直到真正把它接进日常工作流之后才发现，它和普通对话式 AI 的定位完全不在一个层面。普通对话工具是你问一句它答一句，关掉窗口什么都不剩；而 WorkBuddy 这类 AI 工作台的核心价值在于把一次性的对话变成可复用、可编排、可沉淀的能力单元。这个差别听起来抽象，但用起来是天壤之别。

举个我自己的例子。我每周要做一次竞品动态汇总，以前的做法是打开对话工具，把上周收集的链接一条条贴进去，让它总结，然后手动整理成表格。每次都要重复这套动作，提示词还得重新调。用 WorkBuddy 之后，我把"抓取内容—结构化提取—生成对比表—输出周报"这一整套流程固化成一个可调用的任务，下次只需要把新素材丢进去，剩下的它自己跑完。这就是工作台和聊天框的本质区别：前者是流水线，后者是问答机。

从关键词里能看到几个高频词：AI Agent、Skill、models.json、从0到1搭建。这几个词其实勾勒出了 WorkBuddy 的能力骨架。AI Agent 是它的运行主体，Skill 是它可调用的技能插件，models.json 是模型配置的入口文件。理解了这三者的关系，你就理解了整个工作台的运转逻辑。简单说，Agent 是"人"，Skill 是"工具箱"，models.json 是"大脑配置"。人拿着工具箱、按配置好的大脑去干活，这就是 WorkBuddy 的基本工作模型。

那它适合谁用？我的判断是三类人收益最明显。第一类是内容与运营岗，需要大量重复性的信息整理、文案生成、数据汇总；第二类是研发与测试岗，需要把一些固定的脚本任务、代码审查、日志分析流程自动化；第三类是独立开发者和小团队，没有资源自建 AI 中台，但需要一个能快速把想法变成可用工具的平台。如果你只是偶尔问 AI 几个问题，那用普通对话工具就够了，没必要上工作台。但只要你发现自己每周都在重复同样的 AI 操作，那就是该考虑 WorkBuddy 的信号。

还有一点必须提前说清楚：WorkBuddy 和 CodeBuddy 经常被放在一起讨论，很多人搞混。我的理解是，CodeBuddy 更偏向编码场景的深度辅助，聚焦在写代码、改代码这条线上；而 WorkBuddy 是更上层的工作台，它可以把编码能力作为一个 Skill 来调用，但它的野心不止于代码，而是覆盖文档、数据、流程等更广的工作场景。你可以把 CodeBuddy 理解成一把专业螺丝刀，WorkBuddy 是一整个工具箱，螺丝刀可以是工具箱里的一件。搞清楚这个定位，后面的安装和配置思路就顺了。

2. 安装部署：不同系统下的真实差异与选择逻辑

2.1 安装前必须想清楚的两件事

在动手装之前，我建议你先回答两个问题，这两个问题决定了你后面会不会白折腾。

第一个问题：你打算把它跑在本地还是服务器上。本地安装的好处是数据不出机器，调试方便，改配置即时生效；坏处是占资源，而且一旦你关掉电脑任务就断了。服务器部署（比如 Linux 环境）的好处是任务可以常驻运行，适合定时任务和长期挂载的服务；坏处是配置门槛高一些，调试没那么直观。我自己的做法是：开发和调试阶段用本地，稳定运行的任务迁到 Linux 服务器。这个组合实测下来最省心。

第二个问题：你用国内版还是国际版。这两个版本在模型接入、可用 Skill 生态、网络环境适配上都有差异。国内版在中文语境理解、本地化服务对接上更顺；国际版在某些特定模型和 Skill 的丰富度上可能更全。选择的核心依据是你的实际使用场景——如果你的任务主要处理中文内容、对接国内服务，国内版足够；如果你需要调用某些特定的海外模型能力，再考虑国际版。不要盲目追新，够用就好。

2.2 本地安装的完整流程与关键节点

本地安装的流程本身不复杂，但有几个节点特别容易出问题，我按顺序说。

第一步是环境准备。WorkBuddy 对运行环境有基础要求，主要是运行时的版本。这里最常见的坑是版本不匹配——你系统里装了一个旧版本运行时，安装脚本检测到之后要么报错要么静默用了旧版本，导致后面功能异常。我的建议是安装前先手动确认运行时版本，必要时用版本管理工具切到推荐版本，别嫌麻烦，这一步省下的时间后面会加倍还回来。

第二步是获取安装包并执行安装。安装过程中会创建配置目录，这个目录的位置很关键，后面所有的配置修改都在这里。默认路径通常在用户目录下的隐藏文件夹里，很多人装完之后找不到配置文件在哪，就是因为没注意安装日志里打印的路径。装完第一件事：把配置目录路径记下来。

第三步是首次启动与初始化。第一次启动会引导你完成基础配置，包括模型接入方式、工作目录设置等。这里有个细节：工作目录建议单独指定一个干净的文件夹，不要用系统默认的临时目录，否则任务产生的中间文件会散落各处，清理起来很痛苦。

2.3 Linux 服务器部署的注意事项

Linux 部署和本地最大的区别在于权限和后台运行。我踩过的最典型的坑是权限问题：用 root 装完之后用普通用户跑，结果配置文件读不到；或者反过来，用普通用户装，某些目录写不进去。解决办法是统一用一个专用用户来安装和运行，从安装到启动全程用同一个账号，避免权限错位。

后台运行方面，不要用简单的&挂后台，进程一断就没了。用系统自带的服务管理机制把它注册成服务，这样开机自启、崩溃重启都能自动处理。配置服务的时候注意两点：一是工作目录要写绝对路径，二是环境变量要在服务配置里显式声明，因为服务启动时的环境和你登录 shell 的环境不是一回事，这个坑我见过太多人中招。

还有一个容易被忽略的点：日志路径。服务器上跑任务，出问题第一件事就是看日志。安装时就把日志输出到一个固定且容易访问的位置，别用默认的临时路径，否则排查问题时找日志就要找半天。

2.4 安装环节的避坑清单

把安装阶段的高频问题整理成一张表，方便对照排查：

这张表里的每一条都是我在实际部署中真实遇到过的，尤其是权限和日志这两条，几乎每次帮别人排查都会碰到。安装本身十分钟能搞定，但这些细节决定了你后面用得顺不顺。

3. models.json：整个工作台的"大脑接线图"

3.1 为什么这个文件这么重要

如果 WorkBuddy 是一台机器，那 models.json 就是它的接线图——决定了用哪个模型、怎么调用、参数怎么设。这个文件配错了，后面所有功能都是空中楼阁。我见过不少人装完之后发现"AI 不响应"或者"回答质量很差"，排查半天，最后发现就是 models.json 里模型名称写错了或者接口地址填错了。

这个文件的结构本质是一个 JSON 配置，核心是定义模型提供方、模型标识、访问凭证、调用参数这几块。不同版本的 WorkBuddy 在字段命名上可能有细微差异，但逻辑是一致的。理解了这个逻辑，你照着官方示例改就不会错。

3.2 配置项的逐项拆解

我拿一个典型的配置结构来说明每个字段的作用，你对照自己的实际情况填：

{ "models": [ { "name": "主力模型", "provider": "你的模型提供方", "model": "具体的模型标识", "apiKey": "你的访问凭证", "baseUrl": "接口地址", "maxTokens": 4096, "temperature": 0.7 } ] }

name是你自己给这个模型起的别名，方便在任务里引用，随便起但要能看懂。provider和model要严格按提供方的文档填，这里最容易出错——模型标识写错一个字符，调用就失败。apiKey是访问凭证，这个要妥善保管，不要提交到代码仓库。baseUrl是接口地址，国内版和国际版在这里差异最大，填错直接连不上。maxTokens控制单次输出长度，temperature控制输出的随机性，这两个参数后面细说。

3.3 参数调优：temperature 和 maxTokens 怎么设

这两个参数看似简单，但设不好直接影响使用体验。

temperature的取值范围通常在 0 到 1 之间。做事实性任务（比如数据提取、格式转换、代码生成）时，把它调低，0.1 到 0.3 之间，这样输出稳定、可复现。做创意性任务（比如文案撰写、头脑风暴）时，调到 0.7 到 0.9，让输出更有变化。我一开始所有任务都用默认值，结果发现做数据提取时偶尔会"自由发挥"，把原本没有的内容加进去，后来把 temperature 降到 0.2 就稳了。

maxTokens要根据任务类型设。太小的直接后果是输出被截断，任务做一半停了；太大则浪费资源，还可能让模型在无关内容上啰嗦。我的经验值是：短文本处理设 1024 到 2048，长文档生成设 4096 到 8192，具体看你的任务输出长度。有个技巧是先设大一点跑一次，看实际输出用了多少，再回调到合理值。

3.4 多模型配置的策略

WorkBuddy 支持配置多个模型，这个能力很多人没用起来。我的做法是按任务类型分配不同模型：快速响应的轻量任务用一个便宜快速的模型，复杂推理任务用能力更强的模型。在任务配置里通过name引用对应的模型就行。

这样做的收益很明显：成本降下来了，因为不是所有任务都需要最强模型；速度也上去了，轻量任务不用排队等大模型。配置多个模型时注意给每个模型起清晰的名字，比如"快速-提取""强力-推理"，别用"model1""model2"这种，过两天你自己都忘了哪个是哪个。

3.5 models.json 的高频错误排查

配置这个文件时，报错信息往往很模糊，我总结了几类高频问题和定位方法：

• 调用直接失败：先检查baseUrl和apiKey，这两个错了连请求都发不出去。用最简单的测试任务验证连通性。
• 返回内容为空：多半是model标识写错，或者该模型不支持你用的调用方式。
• 输出被截断：maxTokens设小了，调大重试。
• 输出不稳定：temperature设高了，事实性任务调低。
• JSON 解析报错：配置文件格式错误，多半是多了逗号、少了引号，用 JSON 校验工具过一遍。

提示：修改 models.json 之后一定要重启服务或重新加载配置，很多"改了没生效"的问题都是因为没重载。

4. Skill 机制：把重复劳动变成一键调用

4.1 Skill 到底是什么，和普通提示词有什么区别

Skill 是 WorkBuddy 最核心也最容易被低估的能力。很多人把它理解成"保存的提示词"，这个理解只对了一半。保存的提示词只是把一段文字存起来，而 Skill 是一段带有明确输入输出定义、可以携带脚本和资源、能被 Agent 自动调用的能力单元。

打个比方：提示词像是你写在便签上的做菜步骤，每次做菜照着念一遍；Skill 像是把这道菜做成了预制菜包，需要的时候直接下锅，甚至可以让别人帮你下锅。区别在于可复用性、可组合性和可自动化程度。

从关键词里能看到"book to skill""数学建模 skill""仓颉 skill"这些说法，这说明 Skill 的形态非常灵活——它可以是处理某类文档的流程，可以是某个专业领域的计算逻辑，也可以是特定工具的封装。核心特征是：有明确的触发条件、有规范的输入、有稳定的输出。

4.2 一个 Skill 的构成要素

拆开来看，一个完整的 Skill 通常包含这几部分：

• 元信息：名称、描述、适用场景。这部分决定了 Agent 能不能在合适的时机找到并调用它。
• 输入定义：需要什么参数，每个参数的类型和含义。
• 执行逻辑：核心的处理步骤，可以是提示词编排，也可以调用外部脚本。
• 输出定义：产出什么格式的结果。
• 依赖声明：需要哪些环境、工具或数据。

元信息里的描述特别关键。Agent 是靠描述来判断"这个任务该不该用这个 Skill"的，描述写得含糊，Agent 就找不到它，或者找错了。我写描述的原则是：把触发场景写具体，比如不要写"处理文档"，而要写"从 PDF 格式的合同文件中提取甲乙方名称、金额、签署日期并输出为表格"。

4.3 从零写一个 Skill 的实操路径

我拿一个真实场景来演示：把每周的会议纪要整理成结构化待办清单。

第一步，明确输入输出。输入是一段会议纪要文本，输出是一个包含"负责人、事项、截止时间"的表格。

第二步，写元信息。名称叫"会议纪要转待办"，描述写清楚"输入会议纪要文本，提取其中的行动项，输出结构化待办表格，适用于周会、项目会等场景"。

第三步，设计执行逻辑。核心是让模型识别纪要中的行动项——通常带有"负责""跟进""完成""之前"这类词的句子。然后提取三个要素：谁负责、做什么、什么时候完成。这里有个技巧：在提示词里给出几个示例，模型提取的准确率会明显提升。

第四步，定义输出格式。用 Markdown 表格，列固定为三列，这样后续可以直接复制到任务管理工具里。

第五步，测试和迭代。拿几份真实的会议纪要跑一遍，看提取结果对不对。我第一版跑下来发现"截止时间"经常提取不到，因为很多纪要里写的是"下周"这种模糊表述。后来在提示词里加了一条规则：遇到模糊时间就标注"待确认"，问题就解决了。

4.4 Skill 组合：让能力产生复利

单个 Skill 解决单个问题，但真正的威力在于组合。比如你有"网页内容提取"和"结构化总结"两个 Skill，把它们串起来，就得到了一个"输入网址、输出摘要"的完整流程。再叠加一个"生成周报"的 Skill，整条链路就自动化了。

组合的关键是输入输出格式要对齐。前一个 Skill 的输出格式，要正好是后一个 Skill 能接受的输入格式。设计 Skill 的时候就要有"接口意识"，输出尽量用标准格式（JSON、Markdown 表格），这样组合起来才顺。

我自己的 Skill 库里现在有十几个，常用的就那么五六个，但它们互相组合能覆盖我大部分重复性工作。这个积累过程是渐进的，不用一开始就想着建一个大而全的库，从你最烦的那件重复劳动开始，做一个 Skill 解决它，然后慢慢加。

4.5 Skill 开发中的常见坑

• 描述太泛：Agent 找不到或找错 Skill，触发场景要写具体。
• 输入没校验：用户传了格式不对的内容，Skill 直接崩。加一层输入检查。
• 输出格式不固定：这次是表格下次是列表，下游没法用。输出格式要锁死。
• 依赖没声明：Skill 里用了某个工具但没说明，换台机器就跑不起来。
• 没有版本管理：改了 Skill 之后旧任务行为变了。重要 Skill 要留版本记录。

5. 给 WorkBuddy 定规则：让 Agent 长期听话

5.1 为什么需要"定规则"

关键词里有一条很显眼："给 workbuddy 定几条规则，后续对所有任务都生效"。这其实是 Agent 使用中最实用也最容易被忽略的技巧。默认情况下，Agent 每次任务都是"从零开始"理解你的意图，你不在提示词里说的，它就按自己的默认习惯来。结果就是：同样的偏好，你每次都要重复交代一遍。

定规则的本质，是把你的长期偏好固化成 Agent 的默认行为。比如你希望所有输出都用中文、所有代码都带注释、所有表格都按某个格式来——这些不该每次都说，应该一次设定、长期生效。

5.2 规则该定哪些内容

我的经验是，规则分三类，优先级从高到低：

第一类是输出规范。比如语言、格式、长度偏好。这类规则最通用，几乎对所有任务都适用，应该优先定。"所有输出使用简体中文""代码块必须标注语言类型""表格用 Markdown 格式"——这几条我一开始就定了，省了大量重复交代。

第二类是行为约束。比如"不确定的信息要标注出来，不要编造""涉及删除操作前必须先确认"。这类规则关乎安全和准确性，也很重要。尤其是"不要编造"这条，能显著降低幻觉带来的麻烦。

第三类是领域偏好。比如你做技术内容，可以定"技术术语保留英文原文并附中文解释"；你做财务，可以定"金额统一保留两位小数"。这类规则针对性强，按你的实际工作定。

5.3 规则怎么写才有效

规则不是写得越多越好，写多了反而互相冲突、稀释重点。我的原则是少而精，每条都可执行。

对比一下两种写法：

• 差的写法："回答要专业、准确、有帮助。"——太虚，Agent 没法执行。
• 好的写法："涉及数据时必须注明来源；无法确认的信息标注'待核实'；不使用'可能''大概'等模糊表述描述确定事实。"——具体、可判断。

规则要能被"验证"——任务完成后你能一眼看出它有没有遵守。写"要专业"你没法验证，写"代码块标注语言"你一眼就能看出来。

5.4 规则的生效范围与优先级

规则设定时要注意生效范围。有些规则是全局的，对所有任务生效；有些只针对特定类型的任务。全局规则放在最上层，特定规则在具体任务里覆盖。优先级上，具体任务的指令高于全局规则，这样既保证了默认行为一致，又保留了灵活性。

我踩过的一个坑是：早期定了一条全局规则"输出尽量简洁"，结果做文档生成任务时，Agent 把该详细展开的内容也压缩了，输出质量下降。后来我把这条规则改成"对话式回答保持简洁，文档类输出按内容需要展开"，问题就解决了。规则要留出例外空间，别一刀切。

6. 实战场景：从想法到可运行任务的完整链路

6.1 场景选择：什么样的任务适合交给 WorkBuddy

不是所有任务都适合。我的判断标准是三个"重复"：重复出现、重复步骤、重复判断。满足这三个，就值得做成 WorkBuddy 任务。

举个反例：一次性写一篇特定主题的文章，这种任务每次内容都不同，做成自动化意义不大，直接用对话工具更快。正例：每周从固定几个来源收集信息、按固定维度整理、输出固定格式的报告——这种就是典型适合自动化的任务。

6.2 完整案例：搭建一个"资料整理"任务

我拿一个通用性强的场景来走完整流程：把一堆杂乱的资料链接整理成结构化摘要。

第一步，拆解流程。这个任务可以拆成：读取链接列表 → 逐个抓取内容 → 提取核心信息 → 按统一格式汇总 → 输出结果。每一步对应一个能力，前两步可能需要 Skill 支持，后三步是模型处理。

第二步，准备输入。把链接整理成一个文本文件，一行一个。输入格式要固定，这样任务才能稳定解析。

第三步，配置任务。在 WorkBuddy 里新建任务，指定输入文件路径，选择要调用的 Skill 和模型，设定输出路径和格式。

第四步，试跑和调试。先拿两三条链接试，看抓取是否成功、提取是否准确、格式是否符合预期。有问题就回到对应环节调整。

第五步，固化并复用。调试通过后，把这个任务保存下来，下次换输入文件直接跑。

6.3 任务调试中的排查思路

任务跑不通时，不要盲目改配置，按链路逐段排查：

1. 输入是否正常：文件路径对不对，内容格式对不对。
2. Skill 是否被正确调用：看日志里有没有 Skill 的执行记录。
3. 模型是否正常响应：单独测一下模型连通性。
4. 输出是否符合预期：是格式问题还是内容问题，分别处理。

这个顺序是从上游到下游，先确认上游没问题再查下游，能避免在错误的方向上浪费时间。我见过有人一上来就调模型参数，结果发现是输入文件路径写错了。

6.4 让任务稳定运行的经验

任务能跑通和能稳定跑是两回事。稳定运行的关键在于处理异常情况。网络会断、数据会缺、格式会变，这些都要提前考虑。

我的做法是给每个关键步骤加"兜底"：抓取失败就记录失败链接继续跑，不要整个任务中断；提取不到某个字段就填默认值，不要让流程卡住；最后输出一份"处理报告"，说明哪些成功、哪些失败、失败原因是什么。这样即使有问题，你也能快速定位，而不是面对一个"任务失败"的笼统提示。

7. 那些没人告诉你但很重要的细节

7.1 关于成本控制

AI 工作台用起来爽，但成本是会累积的。我的控制方法有三条：一是按任务选模型，简单任务不用强模型；二是控制输入长度，无关内容不要塞进去；三是设置用量监控，定期看消耗情况，发现异常及时调整。尤其是做批量任务时，先小批量试跑估算成本，再决定要不要全量跑。

7.2 关于数据安全

工作台会处理你的各种数据，有些可能敏感。我的原则是：敏感数据本地处理，不外传；凭证类信息单独管理，不进配置文件明文；任务日志定期清理。这些习惯平时看不出价值，出事的时候能救命。

7.3 关于版本更新

WorkBuddy 这类工具迭代很快，更新可能带来新功能，也可能改变原有行为。我的做法是：更新前备份配置和 Skill，更新后先在小任务上验证，确认没问题再用于正式任务。不要一有更新就无脑升，生产环境稳定优先。

7.4 关于学习路径

从关键词里能看到很多人在找"从入门到精通"的资料。我的建议是别追求一次学全，按需学习效率最高。先把安装和 models.json 搞定，能跑起来；然后学写第一个 Skill，解决一个具体问题；再学定规则，优化长期体验；最后学任务编排，做复杂流程。每一步都对应一个实际需求，学完就能用，比啃文档快得多。

7.5 一个容易被忽略的效率技巧

最后分享一个我用了很久的技巧：给常用任务建快捷入口。WorkBuddy 里可以把高频任务固定到显眼位置，或者设置简短的触发词。这样你就不用每次翻菜单找任务了。我把自己最常用的五个任务都设了快捷方式，每天省下的点击时间累积起来相当可观。工具的价值在于用起来顺手，顺手了才会真正融入工作流，否则再强大也是摆设。

这套东西我从安装踩坑到跑通完整流程，前后折腾了大概两周，中间踩的坑基本都写在上面的内容里了。真正用顺之后，它帮我省下的重复劳动时间远超学习成本。如果你也在用或者准备用，建议从一个小任务开始，别贪多，跑通一个再扩展一个，这个节奏最稳。