先把结论放在前面如果你手里的大模型产品还停留在你问一句、它答一句的阶段那它对你来说始终是个玩具不是生产力工具。WorkBuddy 这类 AI Agent 工作台真正改变的是人和 AI 的协作方式——你把任务交代清楚它调用工具、读取文件、执行步骤、返回结果整个过程像在跟一个熟悉你业务风格的同事对接而不是每次都要把上下文重新复制粘贴一遍的聊天框。这篇教程是我自己从零上手 WorkBuddy 的完整记录包含安装部署、Skill 技能配置、自定义指令写法、真实工作流搭建以及一堆踩坑实录。适合刚接触 AI Agent 不久、想把 AI 真正用进日常工作的开发者、运维、产品经理和技术管理者也适合那些已经用惯了普通 AI 聊天工具、正在寻找更自动、更可控方案的团队。1. WorkBuddy 到底是什么AI 从聊天到干活的分水岭1.1 先从一个真实场景切入上个月我给一个客户整理供应商技术方案对比传统做法是这样的打开浏览器、搜参数、复制到文档里、再逐条对照需求清单做标注一上午就没了。换成 WorkBuddy 之后我把三十份 PDF 规格书丢进工作目录写了一条技能指令提取每份文档中的关键参数按《需求清单》逐项比对输出差异表和风险项然后去开了个会。回来的时候文件夹里躺着三份文件参数对比表、风险提示、以及一份可以直接发出去的摘要版报告。这个体验和普通 AI 聊天完全不一样。区别不在于生成能力而在于AI 是否拥有执行链路它能访问你的文件、能按步骤检索、能多次调用模型、能把中间过程和最终结果落地成文件。聊天工具是你动手、它动嘴Agent 工作台是它动手、你验收。1.2 WorkBuddy 的核心定位AI Agent 工作台WorkBuddy 在做的事情说穿了就是提供一套AI 同事的容器和工具链。它有四个关键能力任务执行引擎Agent Runtime支持把一个复杂任务拆成多轮多步骤执行每一步可以调用不同工具、读取不同上下文而不是一次对话就结束。技能系统Skill把常用的任务模板化。比如文档比对代码审查周报生成都可以封装成一个 Skill下次直接调用不用重复写提示词。工作区与上下文管理可以指定目录、挂载文件、设定检索范围让 AI 在一个有限但真实的工作环境里运行而不是在一个无边界的对话里瞎猜。自定义指令Custom Instructions类似给新员工做入职培训把你的偏好、术语、输出格式、禁忌事项一次说清楚之后所有任务都遵循这套规则。这套设计解决了一个最核心的痛点上下文。普通聊天工具里,每个新对话都像是换了个刚毕业的实习生,什么都要重新教。WorkBuddy 因为有了工作区、Skill 和指令系统能让你把业务知识沉淀下来越用越顺手。1.3 WorkBuddy 和 CodeBuddy 到底有什么区别这是我在搜索热词里看到最多的疑问之一。简单说CodeBuddy 更偏向AI 编程助手这一块定位是在 IDE 里帮你写代码、补全代码、解释代码而 WorkBuddy 是更广义的AI 工作台编程只是它能干的活之一。下面这张表是我实际用下来总结的差异维度WorkBuddyCodeBuddy核心定位通用 AI Agent 工作台AI 编程开发助手典型场景文档处理、数据分析、代码生成、流程执行IDE 内代码补全、单元测试生成、代码解释Skill 机制支持自定义技能封装和任务模板偏代码相关技能工作区通用目录挂载、多类型文件以代码仓库为主部署方式桌面端/网页端/本地部署均可通常以 IDE 插件或云端方式注意这里不是说谁替代谁而是场景不同。你纯写代码CodeBuddy 这类工具很顺手你要做的是跨文档、跨数据、跨流程的综合任务WorkBuddy 的 Agent 架构明显更合适。我自己现在是两个都在用写代码时开 IDE 助手处理综合事务时丢给 WorkBuddy。2. 安装与初始化半小时内把 WorkBuddy 跑起来2.1 支持哪些平台怎么选WorkBuddy 的安装方式主要分三类桌面客户端、网页端、本地部署。选择依据很简单你的数据敏感程度和你愿意投入的运维成本。桌面客户端适合大多数个人用户和中小企业。安装即用模型走云端 API各家大模型的接口都支持配置成本最低。网页端适合临时使用、多人协作的场景。好处是零安装缺点是数据在服务端敏感项目不建议。本地部署适合有数据合规要求、或者对模型调用成本敏感的团队。可以接私有化大模型也可以接本地模型比如通过 Ollama 拉起一个开源模型。技术门槛稍高但可控性最强。如果你刚接触我建议先从桌面客户端开始跑通主流程之后再决定要不要折腾本地部署。我遇到过不少一上来就自己部署的朋友结果卡在模型配置上连最基本的功能都没用上心态直接崩了。循序渐进别一开始就上难度。2.2 本地部署实操Linux / Ubuntu 环境我第一次本地部署就是在 Ubuntu 20.04 的服务器上记录一下关键步骤给需要的人当参考。第一步确认基础环境。WorkBuddy 本地部署需要 Docker 和 docker-compose也支持直接用二进制跑但推荐 Docker依赖隔离最省心# 安装 DockerUbuntu 系 sudo apt update sudo apt install -y docker.io docker-compose-v2 # 启动 Docker sudo systemctl enable --now docker # 确认版本 docker --version docker compose version第二步拉取 WorkBuddy 服务端镜像并准备配置文件。这里重点说一个我踩过的坑默认配置会去连云端 API本地部署时要改成你自己的模型服务地址。如果你本地有 Ollama配置文件里模型的 base_url 就指向http://localhost:11434如果你用的是内部部署的 vLLM 服务就指向对应的服务端口。# docker-compose.yml 核心片段示例 services: workbuddy: image: workbuddy/server:latest ports: - 8080:8080 volumes: - ./workspace:/workspace - ./config:/config environment: - WORKBUDDY_MODEL_PROVIDERollama - WORKBUDDY_MODEL_NAMEqwen2.5:14b - OLLAMA_BASE_URLhttp://host.docker.internal:11434第三步挂载工作区。这一步很关键WorkBuddy 的文件读写能力靠的是宿主机目录和容器目录的映射。我把宿主机上的/data/workbuddy挂载成容器内的/workspace这样 AI 处理过的文件可以直接落盘到宿主机方便后续人工复核。启动之后浏览器访问http://localhost:8080就能看到控制台。首次登录会让你配置默认模型这一步建议直接写你刚才在配置文件里填的那个模型名字不然 Agent 调用时还会往回找云端接口大概率报错。这一步配置错了是最常见的看着装好了、实际不能用的原因。2.3 首次初始化必须完成的四件事第一次进 WorkBuddy别急着让它干活先花十分钟把下面四件事做了后面的体验会完全不一样。创建或挂载工作区目录。给 WorkBuddy 一个明确的办公区域项目文档放哪、输出文件放哪。没有明确工作区的 Agent 就像没有工位的实习生东一榔头西一棒子。配置模型参数。至少要把默认模型选对上下文长度和温度参数也建议一并设置。我通常把温度调到 0.3 左右任务执行场景需要确定性优先温度太高 AI 容易自由发挥。写入自定义指令。这部分相当于入职培训是你的偏好和规则的集中表达。具体怎么写下一节详细讲。检查工具权限。WorkBuddy 的很多能力依赖外部工具——文件读写、代码执行、网络请求。初次启动要逐个确认这些工具的开关状态和权限边界特别是代码执行这类有真实副作用的工具该关就关该设白名单就设白名单。3. 核心机制Skill 技能和自定义指令的正确玩法3.1 Skill 到底是什么为什么它是 WorkBuddy 的灵魂我用了一个多月才真正想明白 Skill 的价值。一开始我觉得不就是个提示词模板嘛我自己复制粘贴也行。后来发现完全不是一回事。Skill 是一段标准化的任务说明书 可调用的工具集 输出检查规则的组合。它不只是告诉 AI 要干什么还告诉它可以用什么工具、按什么顺序做、做到什么程度算完成。普通提示词是给人类看的流程说明Skill 是给 Agent 看的程序接口。举个例子。我想让 WorkBuddy 帮我做代码审查如果只是在对话框里说帮我审查这个项目的代码它会给你一堆正确但没有重点的废话。但我写了一个code_reviewSkill 之后它会严格按照我定义的步骤执行先列目录结构、定位变更文件、读取 git diff、逐文件分析、按严重程度输出问题清单、最后生成带修改建议的 Markdown 报告。整个过程是流程化执行的不是我一句一句催出来的。一个标准的 Skill 包含下面几部分元信息名字、用途描述、适用的模型。步骤定义把任务拆成 3 到 8 个可执行的子步骤。工具白名单允许调用哪些工具读文件、写文件、跑命令等。系统提示词这部分的风格、规则、语气全在这里定义。输出规范规定最终交付物的格式比如必须输出 Markdown 表格必须包含风险等级打分。下面是我在一个文档处理任务里实际用过的 Skill 骨架给你参考skill: name: doc_compare description: 对比多份文档与需求清单的差异输出风险报告 tools: - list_files - read_file - write_file steps: - 列出工作区中所有待对比文档 - 读取需求清单提取关键条款 - 逐份文档提取对应信息并比对 - 标记缺失项、差异项和高风险项 - 生成对比报告并保存到 outputs 目录 system_prompt: | 你是资深产品方案评审专家。对比时只依据文档中的客观内容 不臆测、不补全缺失信息。对每个差异项标注严重程度 高影响功能实现、中影响体验或兼容性、低建议优化。 output: format: markdown sections: - 对比结论摘要 - 差异明细表 - 高风险项专项说明注意steps部分这是 Skill 和普通提示词最本质的差别。你给 AI 的不是一个目标而是一条路径它才能在执行过程中停下来检查、调整、再继续而不是一口气生成一个看起来很完整但根本经不起推敲的结果。3.2 手把手写一个你自己的 Skill写 Skill 不用一步到位我的建议是从抄开始改到能用再改到好用。第一次动手的话挑一个你每天都在做的重复性任务比如写项目周报。我的经验是分三步先做任务拆解再做指令编写最后测试迭代。任务拆解这一步你把写周报这个模糊概念拆成读取本周代码提交记录、读取工作区里的任务清单、按周报模板整理每个项目的进展和问题、输出 Markdown 文件。拆得越细Skill 越稳定。我一开始图省事只写了两步结果 AI 经常跳过看代码提交记录这一步直接靠猜写周报。后来我加了一条硬性规则未读取 git log 前禁止生成任何进展描述问题才解决。指令编写的时候有几句话术非常管用必须……才能……比如必须读取全部文档才能输出结论、未……禁止……、如果遇到……则……给异常情况预设处理路径。这些是让 Agent 行为可控的关键比一万句请仔细分析管用得多。测试迭代就更直接了找个真实任务跑一遍看输出哪里不对改掉再跑。一个 Skill 至少要跑三轮真实数据才稳别拿示例数据测试完就想直接上生产现实数据的脏乱程度远超你的想象。3.3 自定义指令推荐写法入职培训越细AI 越省心自定义指令和 Skill 的区别在于粒度。Skill 管的是单个任务怎么做自定义指令管的是整体上你是谁的员工。我举个例子如果你经常写技术方案你的自定义指令里可以这样写你是团队的技术方案撰写助手。在执行任何任务时遵循以下规则 1. 所有文档使用中文术语保留英文原文并在首次出现处标注中文释义。 2. 涉及技术选型时必须给出至少两个候选方案并用表格对比优劣。 3. 代码示例必须标注语言类型关键参数必须附注释。 4. 不编造数据。缺少数据时在文档中标注待补充并汇总成待办清单。 5. 语气客观、平实不使用营销化表达。这里面的核心是把你希望产品怎么做和你讨厌产品做什么都说清楚。正反两个方向的约束能让 AI 的稳定性提升一大截。只给正向要求、不给反向约束是很多人觉得 AI 输出忽好忽坏的真正原因——其实不是模型不稳定是你没把红线划清楚。4. 真实实战用 WorkBuddy 完成三类典型工作4.1 编程场景从写一段代码到负责一个模块WorkBuddy 在编程上跟 IDE 里的代码补全工具不是一回事。它更适合模块级和工程级的任务我实际用得最多的是三类新模块骨架生成、存量代码改造、Bug 排查。新模块骨架生成我会这么交代它在services/payment目录下新建一个支付回调处理模块技术栈为 Spring Boot 3 MyBatis-Plus需要包含 Controller、Service、Mapper 三层以及参数校验和异常处理。 它会把整个目录结构建好每个文件的职责注释写好然后等我验收。这个场景下AI 的价值不是省那几百行代码而是把工程规范一次性落地——目录分层、命名规则、异常处理方式都是跟随我自定义指令走的不用我一个个文件去提醒。Bug 排查是我觉得最有意思的场景。以前定位一个线上问题要翻日志、查代码、对比参数来回折腾半小时。现在我把日志文件丢进工作区向 WorkBuddy 描述一下现象它会自动读取日志、定位异常栈、找到相关代码文件、指出可疑逻辑最后给我一份现象—原因—修复建议—验证方案的完整报告。注意它给出的修复建议我不一定会直接采用但排查路径它是真的能帮我省下大量时间。这个场景里 AI 不是替代我写代码是替代我做最枯燥的翻找环节。4.2 文档与数据场景批量处理是 WorkBuddy 的舒适区如果你不是程序员WorkBuddy 最值得用的场景其实是文档和表格处理。我自己处理最多的就是批量提取 PDF 关键信息、多份合同条款比对、Excel 数据清洗和汇总。举一个实际例子。我有一次需要从四十多份设备采购合同里抽出付款节点、质保期、违约责任、验收标准四项内容做成一张总表。传统做法是打开文档逐份看、逐条填至少大半天。用 WorkBuddy我写了一个简单的 Skill读目录下所有 PDF → 按四个维度提取 → 统一格式 → 输出 Excel 汇总表。跑完大概十几分钟中间有七八份文档因为格式太乱被标记为提取存疑我只需要单独人工复核那几份就行。这里有个心得不要让 AI 追求一次全对让它学会把不确定的挑出来。我设计 Skill 时都会加一条规则——凡是置信度不高的信息不要强行填进去单独列一个待确认清单。这比 AI 硬着头皮填一个错的值事后让你去发现要高效得多。4.3 特殊场景PLC 代码生成与工业自动化辅助搜索热词里有AI PLC 代码生成这个我多说两句。工业自动化领域用 AI 的人越来越多WorkBuddy 在这块的思路是结构化任务生成你给它设备选型和工艺要求它能生成 IEC 61131-3 标准下的结构化文本ST或者梯形图逻辑的中间描述然后你再导入到 PLC 编程软件里做后续处理。我试过一次用 WorkBuddy 写一个皮带输送机联锁控制的 ST 程序。把这几个信息给它电机启停条件、前后级设备的联锁关系、急停复位逻辑、故障报警处理。它生成的主逻辑基本能用但我在验收时发现两个问题一是缺少急停按钮的硬件去抖逻辑二是复位策略写得太简单没有考虑故障保持和操作员确认。后来我把这两条写进了 Skill 的规则里再生成的代码就靠谱多了。这给所有想在工业场景用 AI 的人一个提醒AI 生成代码之前,你要比它更懂业务约束。它擅长的是把逻辑写工整,但工艺安全、异常状态、现场条件这些隐性的行业知识,必须由你来补充。把行业规则写进 Skill,AI 才能从能生成代码进化成能生成可用的代码。4.4 与 Spring AI 等开发框架的集成如果你是 Java 开发者问 WorkBuddy 能不能跟 Spring AI 配合答案是能而且配合得好不好取决于你怎么设计。Spring AI 是 Java 生态里的 AI 应用开发框架负责的是你开发的应用怎么调用大模型WorkBuddy 负责的是你日常工作中怎么用 AI 处理任务。两者的关系更像是WorkBuddy 帮你快速验证一个 AI 功能的效果验证通过后再用 Spring AI 把它正式集成进业务系统。举个例子。你想给内部系统加一个文档问答功能先用 WorkBuddy 挂载一批公司制度文档实测它的检索和回答质量。效果满意了再把同样的模型参数、提示词模板迁移到 Spring AI 项目里用spring-ai-starter加上向量数据库做成正式功能上线。这个先验证后开发的流程能帮你少走很多弯路。我自己就经常先拿 WorkBuddy 做 prompt 实验改到满意了再写进代码比在 IDE 里改一次跑一次的效率高太多了。5. 常见问题与排查技巧实录5.1 安装与部署阶段的高频问题本地部署这一块我见过的坑集中在两个地方镜像拉取失败和模型连接不通。镜像拉取失败多半是网络问题解决办法是配置镜像加速器或者检查 Docker 的代理设置。模型连接不通大部分情况是配置文件里的base_url写错了。特别提醒在 Docker 容器里访问宿主机的服务不能用localhost要用host.docker.internal。这个细节我刚开始就栽过整整查了一下午最后发现就是这个地址的问题。另一个高频问题是装好了但网页打不开。如果你用的是云服务器除了确认容器启动正常还要检查安全组是否放行了对应端口。本地访问没有这个问题但云服务器十有八九是卡在这里。5.2 Skill 执行不符合预期的排查思路Skill 加载了但执行结果五花八门这个问题怎么排查我的经验是按下述顺序来看日志。WorkBuddy 每个任务都有执行日志先看它实际调用了哪些工具、每个步骤的输入输出是什么。很多时候你以为 AI 执行了某步其实它跳过了。检查 Skill 的步骤描述。如果步骤写得含糊比如分析文档AI 就不知道是逐页读还是只读目录。把它改成逐页解析提取每页的标题和正文关键段落输出立刻稳定。检查工具白名单。如果 Skill 里声明了要读文件但工具白名单里没给read_file权限AI 会用推测来代替读取结果自然是编的。这类问题最隐蔽因为 AI 不会主动告诉你它没权限。检查模型选择。同一个 Skill 在不同模型下的表现差异巨大。复杂推理任务用强模型简单抽取任务用小模型别指望一个大模型通吃所有 Skill。5.3 结果质量不稳定的真正原因很多人抱怨 AI时好时坏我观察下来绝大多数情况下不是模型的问题而是下面几个因素在捣乱常见现象真正原因解决办法同一个问题答案时好时坏温度参数过高任务型场景把 temperature 降到 0.2~0.4输出总是缺少某些关键字段自定义指令和 Skill 里没写硬性要求增加必须包含……否则视为不完整的规则经常输出编造的数据工具权限未开启AI 无法读取真实数据检查工具白名单强制读取优先于推测上下文越长越容易跑偏工作区文件过多检索范围太大给工作区建子目录Skill 里限定扫描范围排查质量问题我的核心心法是先假设不是模型笨而是你没给够约束和信息。把这句话当成排查原则百分之八十的质量问题都能找到明确原因。6. 进阶经验把 WorkBuddy 调教成真正的老同事用到现在我最深的体会是WorkBuddy 的上手门槛不在安装而在管理预期和持续调教。你第一次用可能觉得惊艳第二次觉得还行第十次开始嫌弃它不够聪明——这其实是正常的因为你已经从能用走到了好用的阶段接下来拼的就是你对它的调教深度。我现在的用法是建立了一个团队级的指令库把常用术语表、输出模板、红线规则都整理进了自定义指令把重复性任务全部封装成 Skill统一存放在一个共享目录里团队其他人直接导入就能用。新同事加入时不用再一遍遍给 AI 讲业务背景因为它已经是一个了解我们团队规则的老同事了。最后分享一个我自己用得最多的小技巧给每个 Skill 都加一条自查清单。生成完结果之后,让 AI 按你预设的标准先检查一遍再交付,比如检查所有引用的数据是否来自工作区内的文件检查输出中是否有未标注的推测内容检查格式是否符合模板。这一步能让交付质量提升一大截,而且花的只是几秒钟的模型调用时间,非常划算。关于 WorkBuddy,我的态度一直是:它不是来替代你的,而是来接管那些重复、琐碎、不需要创造力但特别耗时间的环节。把这些环节交出去,你才能把精力放在真正需要判断力的事情上。这,才是把它从聊天工具变成干活同事的意义所在。