1. 先搞清楚 WorkBuddy 到底是个什么东西第一次打开 WorkBuddy 的人十有八九会愣一下这玩意儿跟 CodeBuddy 是什么关系是同一个东西换了个皮还是完全两条产品线我一开始也犯过这个迷糊后来把两个都装了一遍、跑了几轮任务才理清楚——WorkBuddy 是腾讯 AI 工作台这条线CodeBuddy 更偏编码场景的助手两者共享一部分底层能力但定位和使用姿势差别不小。你要是冲着帮我写代码来的可能会觉得 WorkBuddy 有点绕但你要是想搭一个能自己调工具、自己拆任务、自己跑流程的 AI Agent 工作台那它就是对的选择。说白了WorkBuddy 的核心价值在于把一个会聊天的模型变成一个能干活的工作台。它不是一个单纯的对话框而是一套围绕AI Agent组织起来的运行环境你给它一个目标它自己决定调用哪些工具、按什么顺序执行、中间结果怎么传递。这里面最关键的三个概念就是models.json、Skill和Agent 中台。models.json 管的是用哪个模型、怎么连Skill 管的是会哪些具体本事Agent 中台管的是这些本事怎么被调度起来。这三样东西搞明白了WorkBuddy 基本就通了。这篇内容适合谁看三类人。第一类是刚听说 WorkBuddy、想从 0 到 1 搭一个自己的 AI Agent 但不知道从哪下手的新手第二类是已经装上了、但卡在配置或者 Skill 编写上、跑不通任务的中级用户第三类是踩过坑、想找一份别人踩过的坑清单来对照排查的老手。我会从安装讲到避坑中间穿插我自己实测的经验和几个容易翻车的地方尽量让你少走弯路。提示WorkBuddy 有国内版和国际版两条线账号体系、可用模型、部分 Skill 生态不完全一样。装之前先确认你要用哪条线别装完了才发现模型列表对不上。2. 安装这件事坑比你想的多2.1 装之前先想清楚装在哪很多人装 WorkBuddy 的第一反应是双击安装包、一路下一步。能装上但后面大概率会后悔。原因在于 WorkBuddy 运行过程中会产生大量缓存、模型临时文件、Skill 运行日志默认全塞在系统盘的用户目录下。你要是系统盘本来就紧张跑几个稍微重一点的任务C 盘直接告急。我自己的做法是安装前先把缓存目录规划好。WorkBuddy 的缓存路径一般可以在配置里改常见做法是把它指到一个空间充裕的数据盘。具体位置各版本略有差异但思路是一样的——找到配置项里跟 cache、data、workspace 相关的路径改成你想要的目录。改完之后建议重启一次让它重新初始化目录结构。这里有个细节改路径之前先把原目录里的内容备份或者清空别直接改配置指向一个已经有乱七八糟文件的目录否则可能出现权限冲突或者索引错乱。我见过有人把缓存目录指到一个只读的共享盘上结果任务跑到一半写不进去报了一堆看不懂的错。2.2 安装过程中的几个典型报错安装阶段最常见的三类问题我按出现频率排一下问题现象大概率原因处理思路安装卡在某个百分比不动网络拉取依赖超时换网络环境重试或检查是否有代理拦截装完启动闪退运行库缺失或版本不匹配补装对应运行库确认系统版本满足要求启动后界面空白缓存目录权限不足检查目录读写权限换一个有权限的路径这三类里闪退和空白界面是最容易被误判的。很多人一看闪退就以为是软件坏了重装好几遍其实根子在运行库或者权限上。我的建议是第一次装完先别急着跑任务先启动一次、看看界面能不能正常出来、设置能不能打开确认基础环境没问题再往下走。2.3 国际版和国内版的选择逻辑热词里workbuddy 国际版出现频率很高说明不少人在纠结这个。我的判断逻辑很简单看你主要用什么模型、访问什么资源。国际版在模型选择上通常更灵活能接的模型种类多一些国内版在访问速度和账号体系上更顺。如果你只是拿它做本地化的任务、跑自己的 Skill两边差别没那么大如果你重度依赖某些特定模型那就得按模型可用性来选。注意不要为了看起来更全就盲目装两个版本。两个版本如果共用同一套缓存目录很容易互相污染配置。要装两个务必把缓存目录和配置目录彻底分开。3. models.json整个工作台的神经中枢3.1 为什么这个文件这么关键WorkBuddy 里最容易被低估、又最容易出问题的文件就是models.json。它决定了你的工作台能调用哪些模型、每个模型怎么连、参数怎么设。你可以把它理解成工作台的通讯录——Agent 要干活得先知道找谁干、怎么联系上。这个文件的结构一般是 JSON 格式里面按模型分组每组包含模型标识、接入方式、密钥或凭证引用、以及一些运行参数。很多人第一次配的时候直接把密钥明文写进去能跑通但这是个隐患。更稳妥的做法是用环境变量或者独立的凭证文件来引用models.json 里只放引用名。3.2 配置一个模型的最小可用结构下面是一个示意性的结构具体字段名以你所用版本为准但逻辑是通用的{ models: [ { name: default-chat, provider: your-provider, endpoint: https://your-endpoint, credentialRef: ENV_MODEL_KEY, params: { temperature: 0.7, maxTokens: 4096 } } ] }几个关键点解释一下。name是你自己起的别名Agent 调度时用的就是这个名字起得清楚一点别用 model1、model2 这种后面自己都记不住。credentialRef指向环境变量这样密钥不落在文件里。params里的 temperature 和 maxTokens 直接影响输出风格和长度做严谨任务时 temperature 调低做创意任务时调高。3.3 配错了会怎样三个真实症状models.json 配错症状往往不是直接报错而是行为诡异这才是最坑的。我总结了三类任务能启动但一直不返回多半是 endpoint 写错或者凭证无效请求发出去了但拿不到响应。返回内容明显不对路可能是模型名写错实际调到了另一个模型或者参数被覆盖了。时好时坏通常是配了多个模型但没设默认调度时随机命中表现就不稳定。排查这类问题的顺序建议是先确认凭证有效再确认 endpoint 可达最后确认模型名和参数。别一上来就怀疑 Skill 写错了很多时候根子在 models.json。4. Skill让 Agent 真正会干活的东西4.1 Skill 到底是什么别被名字唬住Skill这个词听起来很玄其实本质就是一段可被 Agent 调用的能力封装。它可以是一个脚本、一个 API 调用封装、一段处理逻辑。Agent 接到任务后会判断该用哪个 Skill、传什么参数、拿回什么结果。你可以把 Skill 理解成给 Agent 准备的工具箱工具箱里工具越多、越好用Agent 能干的活就越多。热词里出现了skill 编码247skill 脚本skill 插件skill 开发指南这些说明大家最关心的就是怎么写 Skill。我的经验是先别追求写复杂的 Skill先把一个最简单的跑通。一个能接收输入、返回输出的最小 Skill比十个半成品有用得多。4.2 写第一个 Skill 的完整思路写 Skill 的核心是搞清楚三件事输入是什么、处理逻辑是什么、输出是什么。以最常见的文本处理类 Skill 为例定义输入参数明确需要哪些字段每个字段什么类型。写处理逻辑这一步是纯代码跟普通脚本没区别。定义输出结构返回什么格式Agent 后续要靠这个格式继续处理。注册到工作台让 Agent 知道有这个 Skill 存在、怎么调用。注册这一步最容易被忽略。很多人 Skill 写完了代码也没错但 Agent 就是不用它——因为没注册或者注册信息里的描述写得太模糊Agent 判断不出什么时候该用它。Skill 的描述要写得像给同事交代任务一样清楚别写处理文本要写把输入文本按段落切分并返回段落数组。4.3 Skill 描述写不好Agent 就不会用这是我最想强调的一点。Agent 选择 Skill 靠的是语义匹配你的描述越模糊它越容易选错或者干脆不选。我实测下来好的 Skill 描述有几个特征动词开头说清楚做什么。明确输入输出的类型和含义。如果有使用前提写清楚前提条件。举个例子同样是文本处理描述写成文本工具和写成接收一段中文文本按标点切分成句子列表并返回Agent 的调用准确率完全不是一个量级。这一步花十分钟打磨描述能省你后面几个小时的调试时间。5. 从 0 到 1 搭一个能跑的 Agent5.1 先定目标再选工具搭 Agent 最容易犯的错是一上来就堆 Skill、接模型结果搭出来一个什么都能干但什么都干不好的四不像。正确的顺序是先明确这个 Agent 要解决什么具体问题再倒推需要哪些 Skill、用哪个模型。比如你要搭一个自动整理会议纪要的 Agent那核心能力就是读取文本、提取要点、按结构输出。需要的 Skill 可能就两三个模型选一个擅长长文本理解的就行。目标越具体搭起来越快也越容易验证效果。5.2 最小可运行 Agent 的搭建步骤我按自己的实操顺序列一下在 models.json 里配好至少一个可用模型确认能正常对话。写一个最简单的 Skill跑通输入-处理-输出闭环。在工作台里创建一个 Agent绑定模型和 Skill。给 Agent 写一段清晰的任务描述说明它的职责边界。用一个真实的小任务测试观察它调用了哪些 Skill、结果对不对。根据测试结果调整 Skill 描述或任务描述反复迭代。第 5 步是关键。别只看最终结果对不对要看过程——它调用的 Skill 是不是你预期的、参数传得对不对。过程对了结果偶尔错可以调过程错了结果对了也是蒙的换个任务就崩。5.3 给 Agent 定规则让后续任务都生效热词里有一条给 workbuddy 定几条规则后续对所有任务都生效这个需求非常真实。做法一般是在 Agent 的配置里写一段全局规则或者叫系统提示。这段规则会作为每次任务的前置上下文影响 Agent 的行为。写全局规则有几个原则少而精、可执行、不矛盾。我见过有人写了二十条规则结果互相打架Agent 直接懵了。比较实用的几条规则类型是输出格式要求、禁止行为、优先级说明。比如所有输出必须用 Markdown 格式不确定时先提问再执行优先使用已注册的 Skill不要自己编造能力。提示全局规则不是越多越好。规则太多会挤占上下文反而让 Agent 抓不住重点。控制在五条以内每条一句话说清楚。6. 那些没人告诉你、但一定会踩的坑6.1 缓存目录引发的连锁反应前面提过缓存目录这里展开说。缓存目录出问题症状往往不是缓存报错而是各种莫名其妙的失败Skill 跑一半中断、模型响应超时、界面卡死。原因是缓存目录同时承担了临时文件、日志、索引等多种职责一旦写不进去或者写满了整个工作台都会受影响。我的排查习惯是遇到说不清的故障先看缓存目录的剩余空间和权限。这一步花不了一分钟但能排除掉一大半玄学问题。另外缓存目录不要放在会被自动清理的临时目录里否则系统一清理你的配置和中间状态可能就没了。6.2 Skill 之间的依赖冲突当你 Skill 多了之后冲突就来了。最常见的是两个 Skill 依赖同一个库的不同版本或者两个 Skill 对同一份数据有不同的假设。这类问题在单个 Skill 测试时发现不了只有组合起来跑才暴露。处理思路是给每个 Skill 明确它的输入输出契约尽量让 Skill 之间通过标准格式传递数据而不是共享内部状态。Skill 越独立组合起来越不容易冲突。如果实在有共享依赖考虑把公共部分抽出来做成一个基础 Skill其他 Skill 依赖它。6.3 模型切换导致的行为漂移同一个 Agent换个模型行为可能完全不一样。这不是 bug是不同模型的性格差异。有的模型倾向于多问几句再动手有的直接开干有的输出啰嗦有的精简。你按 A 模型调好的 Skill 描述和规则换到 B 模型可能就不灵了。我的做法是换模型之后把之前跑通的任务重新跑一遍对比结果。如果差异大优先调任务描述和全局规则而不是改 Skill。Skill 是能力规则是行为约束行为漂移通常靠规则来纠。6.4 关于从入门到精通这类资料的现实热词里有workbuddy 从入门到精通 pdf 下载这种我理解大家想找一份系统资料。但说实话这类工具迭代很快任何一份静态文档都可能过时。更靠谱的学习路径是官方文档打底 自己动手跑通一个最小案例 遇到问题查社区。我自己的经验是跑通一个真实任务学到的东西比看十篇教程都多。7. 几个高频场景的实操建议7.1 用 WorkBuddy 生成网站并发布热词里workbuddy 怎么生成网站发布是个高频问题。思路一般是让 Agent 根据你的需求生成前端代码然后走发布流程。这里的关键不是生成代码本身而是把需求描述清楚。你要告诉它页面结构、样式风格、需要哪些交互、数据从哪来。描述越具体生成的东西越接近可用。生成完之后别急着发布先在本地跑起来看看。常见问题是样式错位、交互没反应、资源路径不对。这些基本都是描述不够具体导致的回去补描述再生成一轮比手动改代码快。7.2 数学建模类任务怎么用数学建模 skill这个热词说明有人拿它做建模。这类任务的特点是逻辑链条长、中间步骤多。我的建议是把大任务拆成小步骤每一步让 Agent 输出中间结果你确认没问题再往下走。别指望它一口气把整个建模流程跑完中间任何一步理解偏了后面全错。7.3 和其他工具配合的边界WorkBuddy 不是万能的它擅长的是调度和编排具体某个专业领域的深度处理可能还是得靠专门的工具。把 WorkBuddy 当成一个总调度把专业工具当成执行单元通过 Skill 把它们串起来这个思路比指望它什么都自己干要靠谱得多。8. 我自己的几条经验总结折腾 WorkBuddy 这段时间最大的体会是这东西的上限取决于你怎么用它而不是它本身有多强。同样的工作台有人搭出来只能聊聊天有人搭出来能自动跑完整条业务流程差别就在 models.json 配得细不细、Skill 写得清不清楚、规则定得合不合理。如果让我给刚上手的人一句建议那就是先跑通一个最小闭环再谈扩展。别一上来就想着搭一个全能 Agent先把一个模型 一个 Skill 一个任务跑通把这条链路摸熟后面加什么都是在这个基础上长出来的。我见过太多人卡在想搭个大的上结果连最小的都没跑起来。另外遇到问题别慌按模型配置 → Skill 注册 → 任务描述 → 缓存环境这个顺序排查八成的问题都能定位到。这个顺序是我踩了无数坑之后总结出来的比瞎试高效得多。