1. 为什么我要认真写这篇 WorkBuddy 实战指南第一次打开 WorkBuddy 的时候我以为它就是个套壳的对话工具用两天就扔。结果连续用了三周从安装踩坑、模型配置、Skill 调试到缓存目录迁移我把它当成了一个真正的工作台来折腾。现在回头看网上大部分内容要么是官方文档的复读要么是“一键部署”的标题党真正讲清楚“为什么这么配”“哪里会翻车”的内容少得可怜。这篇东西写给三类人第一类是完全没接触过 AI Agent、想找个能上手的工作台练手的新人第二类是用过 CodeBuddy 或者类似工具、想搞清楚 WorkBuddy 到底差在哪的老手第三类是想把 WorkBuddy 落到实际工作流里、需要自定义模型和 Skill 的进阶用户。我会从安装讲到避坑把 models.json 配置、Skill 机制、缓存目录迁移、跨对话记忆这些核心点全部拆开讲该给参数给参数该说原理说原理。先明确一件事WorkBuddy 是腾讯出的 AI 工作台产品定位偏向“Agent 编排 多模型接入 Skill 扩展”和 CodeBuddy 那种偏代码补全的工具不是一回事。你可以把它理解成一个可以自己搭积木的工作台模型是发动机Skill 是各种功能插件规则系统是方向盘。理解这个定位后面所有配置逻辑就顺了。2. 安装前的准备工作与版本选择2.1 先搞清楚你要装哪个版本WorkBuddy 目前有网页版、桌面客户端以及面向 Linux 环境的安装包。很多人一上来就问“哪个版本好用”这个问题本身就问错了。正确的问法是你的使用场景是什么。如果你只是偶尔用一下、不想占本地资源网页版足够打开浏览器就能用Skill 和模型配置都在云端同步。缺点是本地文件读写、系统级操作这类能力会受限。如果你是重度用户需要频繁调用本地文件、跑脚本、做自动化那桌面客户端是必须的因为它能拿到更多系统权限。至于 Linux 版本适合放在服务器或者开发机上做长期运行的任务比如定时抓取、批量处理。我自己的组合是日常轻量任务用网页版重活和需要本地文件操作的全部走桌面客户端。Linux 版本我单独装在一台测试机上跑长任务互不干扰。注意不同版本的 Skill 支持范围不完全一致装之前先确认你需要的 Skill 在目标版本上是否可用别装完了才发现关键功能缺失。2.2 系统缓存目录的默认位置与隐患这是被问得最多的问题之一WorkBuddy 的系统缓存目录能不能改到 D 盘答案是能但你要先知道它默认在哪、为什么会有这个需求。默认情况下桌面客户端会把缓存、日志、临时文件放在系统盘的用户目录下。用久了之后这个目录会膨胀得很快尤其是你频繁调用模型、跑 Skill 的时候。C 盘空间紧张的用户迁移缓存目录几乎是必做操作。迁移的逻辑不复杂找到设置里的存储路径选项改成你想要的盘符下的目录然后重启客户端让配置生效。但这里有个坑——直接改路径不会自动迁移已有缓存旧数据还留在原位置。正确做法是先关闭客户端手动把旧缓存目录整个复制到新位置再在设置里指向新目录最后确认新目录有读写权限。我实测下来迁移之后第一次启动会稍微慢一点因为要重建索引之后就正常了。如果你用的是 Linux 版本缓存目录通常在用户主目录下的隐藏文件夹里改的时候注意权限别用 root 跑普通任务否则后面文件归属会乱。2.3 安装过程中的常见报错安装阶段最容易遇到的是权限问题和依赖缺失。Windows 上如果装在 Program Files 下某些 Skill 写文件会失败建议装在用户目录下。Linux 上常见的是缺少运行库装之前先更新系统包把基础的运行环境补齐。还有一个隐蔽的坑如果你之前装过同系列的其他工具环境变量或者配置目录可能冲突。我遇到过配置文件互相覆盖的情况排查了半天才发现是两个工具共用了同一个配置路径。解决办法是给 WorkBuddy 单独指定配置目录别用默认的。3. 自定义模型配置models.json 到底怎么写3.1 为什么需要自定义模型WorkBuddy 内置了默认模型但默认模型不一定适合所有任务。有的任务需要强推理有的任务需要快响应有的任务对成本敏感。自定义模型配置的意义就在于你可以针对不同场景挂不同的模型让工作台按需调度。models.json 就是干这个的。它是一个 JSON 格式的配置文件里面定义了模型名称、接入地址、鉴权方式、参数默认值等信息。你把这个文件配好WorkBuddy 启动时就会加载之后在对话或者 Skill 里就能选到你自定义的模型。3.2 models.json 的结构拆解一个典型的 models.json 结构大致是这样的顶层是一个模型列表每个模型对象包含几个关键字段。我按重要性排序讲。第一个是模型标识也就是你在界面上看到的名字起名要清晰别用 model1、model2 这种后面自己都分不清。第二个是接入端点指向模型服务的地址。第三个是鉴权信息通常是密钥或者令牌这里要特别注意安全别把密钥明文提交到版本控制里。第四个是默认参数比如温度、最大输出长度这些可以针对模型特性预设。{ models: [ { name: reasoning-model, endpoint: https://your-endpoint/v1, apiKey: YOUR_KEY_HERE, params: { temperature: 0.3, maxTokens: 4096 } }, { name: fast-model, endpoint: https://your-endpoint/v1, apiKey: YOUR_KEY_HERE, params: { temperature: 0.7, maxTokens: 2048 } } ] }上面这个例子配了两个模型一个偏推理、温度低一个偏快速响应、温度高。实际用的时候写文献综述这种任务走 reasoning-model日常问答走 fast-model。3.3 参数选择的逻辑温度这个参数很多人随手填 0.7 就完事。其实它直接决定输出的随机性。做需要严谨推理、代码生成、数据分析的任务温度要压低0.2 到 0.4 之间比较稳。做创意写作、头脑风暴可以拉到 0.8 以上。最大输出长度要根据任务预估设太小会截断设太大浪费资源一般 2048 到 4096 覆盖大部分场景。提示改完 models.json 一定要重启 WorkBuddy热加载不一定生效。改之前先备份原文件配错了还能回滚。3.4 配置不生效的排查顺序模型配好了但界面上选不到或者选了报错按这个顺序查先确认 JSON 格式合法用在线校验工具过一遍再确认端点地址能通用 curl 测一下然后确认密钥有效且没过期最后看 WorkBuddy 的日志日志里通常会写明加载失败的原因。我踩过的坑是 JSON 里多了一个逗号格式校验不通过但界面不报错只是静默忽略查日志才发现。4. Skill 机制WorkBuddy 真正的扩展能力4.1 Skill 是什么和普通插件有什么区别Skill 是 WorkBuddy 的核心扩展方式。你可以把它理解成一个个独立的能力模块每个 Skill 负责一类任务比如文件处理、网页抓取、数据整理、代码执行。和传统插件不同的是Skill 可以被 Agent 自动编排调用也就是说你不需要手动点Agent 会根据任务需要自己决定用哪个 Skill。这就引出一个关键问题哪些 Skill 最好用我的经验是优先装那些高频、通用、稳定的 Skill别一上来装一堆冷门的。常用的几类包括文件读写、文本处理、网络请求、结构化数据转换。这些覆盖了大部分日常工作。4.2 Skill 的安装与调试Skill 的安装方式取决于你用的版本。桌面客户端一般有 Skill 管理界面可以直接搜索安装。Linux 版本可能需要手动放到指定目录。装完之后别急着用先跑一个最小测试用例确认 Skill 能正常调用。调试 Skill 的时候日志是你的朋友。每个 Skill 调用都会留下记录包括输入、输出、耗时、是否报错。如果 Skill 没按预期工作先看日志里输入对不对再看输出是不是被截断或者格式错了。我遇到过一次 Skill 返回的数据结构变了导致后续处理全挂查日志才发现是 Skill 版本更新改了返回格式。4.3 跨对话记忆 Skill 的实战价值跨对话记忆是很多人关心的能力。默认情况下每个对话是独立的上一个对话的上下文不会带到下一个。跨对话记忆 Skill 的作用就是把这个限制打破让 WorkBuddy 记住你之前说过的东西。这个能力在长期项目里特别有用。比如你在做一个持续几周的研究每次开新对话都要重新交代背景很烦。有了跨对话记忆背景信息存一次后面直接接着聊。但要注意记忆不是无限的存太多会拖慢响应也会引入噪声。我的做法是只存关键结论和偏好设置过程性的内容不存。4.4 给 WorkBuddy 定规则让配置对所有任务生效“给 WorkBuddy 定几条规则后续对所有任务都生效”这个需求很实际。规则系统的本质是把你的偏好固化成指令每次任务开始前自动注入。比如你可以定一条规则所有输出用中文代码块标注语言类型。再定一条涉及数据处理的先确认字段含义再动手。规则要写得具体、可执行别写“认真回答”这种废话。好的规则是输出前先列出你的理解确认无误再执行。这样能大幅减少答非所问的情况。规则定多了也会互相冲突建议控制在五条以内定期清理。5. 从零搭建一个可用的 AI Agent 工作流5.1 明确任务边界搭建 Agent 的第一步不是配工具是想清楚你要它干什么。任务边界越清晰Agent 越稳定。比如“帮我处理文档”太模糊“把指定目录下的 Markdown 文件转成统一格式并提取标题生成目录”就具体得多。我一般会把任务拆成输入、处理、输出三段。输入是什么格式、从哪来处理分几步、每步用什么 Skill输出成什么格式、放到哪。拆清楚了再动手配。5.2 编排 Skill 的顺序Skill 的调用顺序直接影响结果。以文档处理为例正确顺序是先读取、再解析、再转换、最后写出。顺序错了比如先转换再解析数据可能已经变形了。WorkBuddy 的 Agent 能自动编排但你要在规则里给出大方向别完全放任。5.3 测试与迭代搭完不要直接上生产任务先用小样本测。准备三五个测试文件跑一遍看结果对不对。有问题就调规则、换 Skill、改参数。迭代几轮之后再上真实数据。我自己的习惯是保留每次测试的输入输出方便对比哪次改动带来了什么变化。6. 常见问题与避坑实录6.1 高频问题速查表问题现象可能原因解决方向模型选不到models.json 格式错误校验 JSON查日志Skill 调用失败权限不足或依赖缺失检查目录权限补依赖缓存占满 C 盘默认缓存在系统盘迁移缓存目录到其他盘跨对话记不住记忆 Skill 未启用启用并配置记忆范围规则不生效规则冲突或太模糊精简规则写具体指令响应变慢缓存过大或记忆过多清理缓存精简记忆6.2 几个我踩过的坑第一个坑是缓存目录迁移后没改权限导致 Skill 写文件失败报错信息还很隐晦。后来养成习惯迁移完先手动在新目录建个测试文件确认能写再继续。第二个坑是规则定太多互相打架。有一次我同时定了“输出简洁”和“详细解释每一步”结果 Agent 每次都在纠结输出质量反而下降。删到三条之后正常了。第三个坑是模型密钥泄露风险。早期我图省事把密钥写在 models.json 里直接同步了后来意识到不对改成用环境变量注入配置文件里只留引用。6.3 WorkBuddy 和 CodeBuddy 的区别经常有人问这俩是不是一回事。简单说CodeBuddy 偏代码场景强在补全、生成、调试代码。WorkBuddy 偏工作台场景强在 Agent 编排、多模型接入、Skill 扩展。两者定位不同不是替代关系。如果你主要写代码CodeBuddy 更顺手如果你要做跨领域的自动化任务WorkBuddy 更合适。实际用的时候两个可以配合各干各擅长的。7. 本地化部署与安全审核的注意事项7.1 本地部署适合谁本地部署的核心价值是数据不出本地、可控性强。适合对数据敏感、或者需要深度定制的场景。但本地部署的代价是维护成本高模型要自己跑硬件要自己扛。如果你的任务量不大云端版本更省心。7.2 安全审核要点不管云端还是本地安全审核都不能省。重点查三块一是模型接入的鉴权信息别硬编码二是 Skill 的权限范围别开太大能读就别给写三是日志里别记录敏感数据。我见过有人把密钥打进日志排查问题时顺手贴出来直接泄露。7.3 私有化部署的取舍私有化部署听起来很美但不是所有团队都需要。判断标准很简单你的数据敏感度是否高到不能出内网你的团队是否有能力维护。两个都满足才考虑否则用云端版本加权限控制就够了。8. 一些实际使用中的体会用 WorkBuddy 这段时间最大的感受是它不是一个开箱即用的成品而是一个需要你投入时间调教的工作台。配置越细它越好用规则越清晰它越听话。反过来如果你指望装完就万事大吉大概率会失望。我现在的用法是固定三条核心规则挂两个模型分别应对推理和快速任务常用 Skill 装五个左右跨对话记忆只存偏好和结论。这套配置跑下来日常任务的完成度能到八成以上剩下的两成靠手动补。最后分享一个小技巧每次改完配置别急着上正式任务先跑一个你熟悉的测试用例对比改动前后的输出。这样能快速判断改动是正向还是负向。配置这东西改多了容易乱有对比才有判断。