我先说个真实的场景。上周有个朋友找我说他拿到了 WorkBuddy 开放平台的开发者资格结果打开控制台发现文档一摞一摞的什么 Skill、Agent、工作流编排、记忆模块光概念就把他绕晕了。他跟大多数刚接触这个平台的人一样第一反应是这不就是个带插件的聊天工具吗结果越看越发现事情没那么简单——这其实是一套完整的 Agent 应用开发环境只是入口长得很像日常工具。我自己的经历也差不多。从最初把 WorkBuddy 当成一个效率工具来用到后来基于开放平台写自定义 Skill再到现在把它作为 Agent 应用的运行时来设计整个路径踩过不少坑。这篇文章就把这条从零到能跑通一个 Agent 应用的完整路径写清楚包括平台概念怎么理解、环境怎么搭、Skill 怎么写、Agent 怎么组装以及那些文档里不会写的坑。适合刚拿到开放平台权限的个人开发者也适合那些想用它做点什么但还没想清楚从哪下手的玩家。1. 先搞懂 WorkBuddy 开放平台对个人开发者意味着什么很多人拿到 WorkBuddy 开放平台的第一反应是这是不是一个AI 应用商店我上去写个插件就行这个理解不能说错但会把你带偏。因为如果你只把它当成插件平台你做的还是工具而不是Agent。1.1 它不是一个普通聊天工具而是一个 Agent 运行时WorkBuddy 的工作台本质是一个 Agent 运行时环境。所谓 Agent 运行时简单类比就是给 AI 一个能干活的操作系统。普通聊天工具的逻辑是你输入问题模型输出回答结束。Agent 运行时的逻辑是你给一个目标模型自己拆解任务、调用工具、获取信息、判断下一步、反复迭代直到目标完成。WorkBuddy 开放平台做的事情就是把这个运行时暴露给个人开发者让你不光是用 AI 聊天而是可以让 AI 替你执行一套完整的工作流。我当时真正理解这一点是在看它运行日志的时候。你会发现模型每一步的动作都被记录下来思考过程、选择了哪个工具、工具返回了什么、模型根据返回决定下一步做什么。这不是单纯的大模型接口调用而是一个有状态的执行环境。1.2 工作台、Skill、Agent 三者的关系平台里有三个概念特别容易混淆工作台、Skill 和 Agent。我用一个生活化的方式来解释。工作台是你干活的操作台它提供运行环境、文件系统、命令执行能力、网络访问能力。Skill 是单项技能就像你会做饭、会开车、会修电脑这是单个能力点。Agent 则是一个有自主性的执行者它不是一个技能而是一个会调用技能去完成目标的东西。打个比方Skill 是工具箱里的扳手或者螺丝刀Agent 是那个拿着工具箱去修东西的工人。工作台是工人的工作间。在开放平台的体系里Skill 是可以被单独发布、复用的能力单元Agent 则是把这些能力单元组合起来配上规划和记忆形成可以独立完成复杂任务的智能体。1.3 和 CodeBuddy 的区别别再混淆了网上经常有人问 CodeBuddy 和 WorkBuddy 有什么区别。我查过一些资料也实际用过之后的理解是CodeBuddy 更偏向代码生成与代码理解它的场景锚定在开发任务上比如写代码、改代码、解释代码、生成测试用例。WorkBuddy 的工作台定位更宽它是一个通用的 Agent 工作环境Skill 机制让它可以扩展到各种各样的场景代码开发只是其中一类应用。对个人开发者来说这个区别很重要。如果你想做一个写代码的助手CodeBuddy 的路径可能更直接但如果你想让 AI 帮你处理数据分析、内容整理、多步骤信息检索这类跨领域任务WorkBuddy 的 Skill 加 Agent 组合会更契合。我自己为什么选 WorkBuddy 这条路因为我不想只做一个编程专用的玩意我更想要一个能承载多种任务、可以自己定义能力的 Agent 平台。2. 环境准备安装部署与模型服务配置Linux 实测官方文档里环境准备这部分写得看着挺顺但实操起来有不少细节文档没提。我建议第一次装的时候直接看最新版的 Release 说明别依赖旧教程WorkBuddy 的迭代速度相当快。2.1 Ubuntu 下的安装细节与常见报错我自己长时间用的环境是 Ubuntu也听说过有人成功在别的 Linux 发行版上跑起来所以我把 Linux 的安装作为主路径来写。基本安装分这几步下载对应架构的安装包、解压到工作目录、初始化配置、启动服务。如果你是图形界面环境也有桌面版本的安装向导但底层逻辑是一样的。核心步骤我给你直接列出来# 1. 解压到独立目录 mkdir -p ~/apps/workbuddy tar -xzf workbuddy-linux-x64.tar.gz -C ~/apps/workbuddy # 2. 首次启动前检查依赖 # 有些极简安装的系统缺基础库直接启动会报错 ldd ~/apps/workbuddy/workbuddy | grep not foundldd这步是我强烈建议做的。我装的时候遇到过缺libfuse2的情况启动直接失败控制台只给一个含糊的错误提示。ldd会把缺失的动态库全部列出来缺什么补什么比盲试高效得多。# 3. 安装缺失依赖不同发行版包管理器不同 sudo apt install libfuse2 # 4. 启动 ~/apps/workbuddy/workbuddy启动成功之后它会默认开一个本地端口。第一次访问会让你做初始化这个初始化本质上是生成运行配置和密钥对配置目录一般在用户主目录下面。如果你以后想改配置别在程序目录里找去配置目录里找。2.2 对接 DeepSeek 开放平台的 API 配置安装好之后最关键的步骤是把模型服务接进来。我自己用的是 DeepSeek 开放平台作为模型后端原因很简单它在个人开发者这个层级性价比很能打而且它的 API 兼容主流调用风格适配起来很方便。在开放平台那边申请好 API Key 之后把模型服务信息填进 WorkBuddy 的配置里。有些版本的界面里叫模型服务有的叫模型提供商不同版本叫法不一样但本质就是两个信息API 地址和 Key。# 配置文件里模型相关的大致样子具体字段看你的版本 model: provider: deepseek api_base: https://api.deepseek.com # 以官方渠道为准 api_key: sh-你的密钥 model_name: deepseek-chat这里唯一要提醒的是不要明文把 API Key 写在能被随便看到的地方。WorkBuddy 的配置系统通常支持环境变量注入把 Key 放到环境变量里配置文件里只写变量引用这样既方便换 Key也安全一些。2.3 模型选择的经验之谈模型选择我给的方案是日常 Agent 任务用 deepseek-chat它综合表现稳定、速度快、成本低需要复杂推理的任务切成更强推理的模型。模型切换在 Agent 应用中很有用——Agent 不同阶段的子任务难度差异很大拆解任务时用轻量模型能省不少成本真正要深度推理的时候再换重模型。我用 WorkBuddy 接 DeepSeek 开放平台跑下来最直观的感受是上下文窗口很够用Agent 执行长流程的时候不会因为上下文不够中途断掉。而且速度对于大多数个人开发者的使用场景完全够。3. 从 Skill 开始把重复工作封装成能力在开放平台里写 Skill 是个人开发者从使用者变成开发者最关键的一步。你说你不会什么高级编程语言没关系Skill 的门槛低到让我意外。3.1 Skill 的本质与文件结构Skill 本质上就是一套规则加提示词外加可选的外部脚本或 API 调用。一个 Skill 文件里面通常包含这几个部分功能描述说明这个 Skill 是干什么的模型会根据描述决定什么时候调用它执行指令告诉模型具体怎么做参数定义需要输入什么参数输出格式结果应该怎么呈现我用一个很简单的例子来说明。假设我想要一个周报生成器Skillname: weekly_report description: 根据本周的工作记录生成结构化周报 parameters: work_logs: type: string description: 本周的工作记录可以是吃顿的文本 instructions: | 1. 分析用户提供的工作记录提取关键任务和成果 2. 按本周完成/下周计划/问题与风险三部分组织 3. 每条任务写明做了什么、产出是什么 4. 语言简洁使用动词开头这个 Skill 没有一行程序代码但它完全可用。因为模型本身理解自然语言Skill 做的事情是给模型一个清晰的操作手册。3.2 手写一个实际 Skill信息汇总助手我再写一个稍微复杂一点的 Skill 例子这个 Skill 做的事情是给模型一堆杂乱的资料链接和笔记它整理成一份有主题分类、有优先级标记的调研摘要。name: research_synthesis description: 将分散的资料整理为结构化调研摘要 parameters: materials: type: string description: 原始资料、链接、笔记、引用等支持多段文本 focus: type: string description: 这次调研需要重点关注的方向 instructions: | 1. 先判断所有资料的整体主题分布 2. 对资料按主题聚类每类用一段概括性描述 3. 每个主题下列出关键信息点和来源 4. 最后补充待深挖区域列出资料中提到但尚未展开的线索 5. 如果 focus 参数有指定方向优先保证这个方向的信息完整性 output_format: | ## 主题一XXX - 核心信息点 - 资料来源 ## 待深挖 - 线索1、线索2这个 Skill 的实际价值在于它把整理资料这件事的经验固化下来了。以前我自己整理资料是全凭感觉现在模型每次都按照同样的标准去做输出结构稳定质量不会忽上忽下。3.3 自定义指令推荐为什么这么写更有效热词里有workbuddy 自定义指令推荐我根据实际测试给几个方向。第一是给模型定义身份。不要让它觉得自己是个通用助手而是让它进入一个特定的角色。角色定义能明显改变输出的语气和视角。第二是给出限制条件比如不要使用夸张的形容词每段不超过 X 字限制条件对生成质量的提升非常大。第三是给出中间思考要求比如分析之前先列出你需要注意哪些陷阱这个会让模型在生成时更仔细。我自己的习惯是每个 Skill 里都写一句如果信息不足明确说不足不要猜测。这能极大减少模型一本正经胡说八道的情况。4. 组装 Agent让 Skill 组合成自动决策的工作流写了一个 Skill你只是造了一把工具。真正有意思的部分是让 WorkBuddy 把这些工具组合成一个有自主行为能力的 Agent。4.1 从工具集合到Agent的转变工具集合和 Agent 的区别在哪里工具集合是你有什么Agent 是你会怎么用。同样的工具不同 Agent 用出来的效果天差地别。我用一个实际的案例来说。我做过一个竞品情报 Agent它需要做的事情是定期盯几个竞品的信息、把新内容抓下来、按主题归档、生成变化摘要。如果只是把抓取工具和摘要 Skill摆在那里你每次都要手动告诉模型现在抓取 A 网站然后摘要一下。这不叫 Agent这叫遥控器。真正的 Agent 是把决策也交给模型。我给它的目标指令是每天检查竞品信息源如果有新内容做摘要并归档如果无新内容等待第二天。它会自己决定何时调用抓取工具、何时调用摘要 Skill、何时不需要任何动作。这个自己决定下一步的能力就是 Agent 和工具集合最本质的区别。4.2 任务规划与工具编排的关键设计在 WorkBuddy 开放平台里搭 Agent核心是编排什么样的任务顺序最合理、什么条件下走哪条分支、失败之后怎么降级。我的经验是编排设计要遵循几个原则先拆解后执行让模型先输出执行计划把一个大任务拆成步骤这能显著减少漏步骤的情况关键节点设置检查点高风险动作比如发送、修改、删除前面加一层确认判断失败分支要给明确指令告诉模型如果调工具失败重试一次还失败就跳过并且记录原因不要死循环实际配置时我会把这类原则写成 Agent 的工作准则放在最前面。4.3 Agent 记忆短期上下文与长期信息该怎么用热词里agent记忆的出现频率很高这确实是 Agent 从玩具走向实用的分水岭。没有记忆的 Agent 每次对话都是第一次见面它记不住你一周前让它关注的某个话题。WorkBuddy 的记忆机制我做下来大概是三层对话上下文当前任务进行中的临时记忆任务结束就清掉会话记忆保存在一个会话周期内的重要信息长期记忆跨会话保存的用户偏好、历史决策、事实信息我的经验是不要把什么都塞进长期记忆要像人一样只记值得记的。我在设计记忆策略的时候会在 Agent 执行完一个重要任务之后让它自己生成一段本次任务结论并决定是否存入长期记忆。这个让 Agent 自己判断该记什么的做法效果比手动指定要灵活得多。4.4 一个完整的 Agent 示例流程我描述一个实际的 Agent 应用案例个人知识库管理 Agent。这个 Agent 接收用户丢过来的各种碎片信息——网页链接、PDF、笔记片段、想法它做的事情是第一步识别信息类型。判断是一篇文章、一段笔记还是一个需要跟踪的任务。第二步根据类型调用不同的 Skill文章链接走抓取加摘要笔记走分类加打标签任务类走待办提取。第三步更新记忆把新知识按主题写入长期记忆同时检查是不是和已有的知识冲突如果有冲突生成一个冲突提示。第四步生成操作报告告诉用户我处理了什么、放在了哪里、发现了什么潜在问题。这个 Agent 的完整工作流没有写一行传统的业务代码全部是用 Skill 加编排配置出来的。它的价值不在于某个单独的功能有多强而在于它能把散落的输入自动归位持续积累成结构化的个人知识库。5. 接入开放平台后的常见坑与排查链路如果说到这一步你都顺利恭喜你已经超过大多数人了。剩下的篇幅用来写我实际踩过的坑。不会写这些坑的教程不是好教程。5.1 Agent 执行被终止一次完整的问题排查热词里有一条agent execution terminated due to error我见过好多次了我自己也遇到过。这个报错看起来像平台故障但大多数情况下是配置问题。我遇到的一次情况是这样Agent 在执行一个需要联网的任务时中途被终止。我的排查链路是这样的第一步查看运行日志定位终止发生的步骤。日志显示任务在调用某个外部服务这一步被终止不是模型生成阶段。第二步单独测试那个外部服务发现服务本身没问题能正常返回。第三步对比手动调用和 Agent 调用时的差别最后发现是超时时间设置的问题。那个外部服务响应本来就需要比较长的时间但 Agent 调用的超时阈值设置得比较短时间一到就强制终止了。第四步调整超时阈值重新执行问题解决。这个坑特别容易踩的原因是Agent 调用工具的链路比直接调用长多了一层模型解析工具返回结果的时间。你以为工具的响应时间是 10 秒实际上整个调用链路可能耗时 30 秒超时阈值只设了 20 秒就很容易触发终止。5.2 工具调用失败根因往往是模型没理解工具用法另一个高频问题是工具调用失败。打开日志经常能看到模型发起了一个工具调用但参数格式不对或者使用了不存在的参数名。我之前一直以为这是平台调度的问题后来才明白根因在模型那边。模型是根据 Skill 文件里的描述来调用工具的如果你的参数定义写得不够清楚模型就会凭感觉填参数填错很正常。解决方法是把参数定义写得更窄# 不推荐模糊的参数描述 url: type: string description: 目标网址 # 推荐明确的格式约束 url: type: string description: 目标网址必须以 http:// 或 https:// 开头包含完整域名和路径这个细节很微妙。模型不会像人一样去猜你什么意思它严格基于描述来决策。描述越具体模型的选择空间越小出错率越低。5.3 上下文窗口与模型选择的平衡还有一类问题不是报错而是效果变差。通常是 Agent 跑了一段时间之后输出开始变得跳跃、丢失细节。这往往是因为上下文已经堆积了大量不重要的信息把关键信息挤掉了。我的做法是给 Agent 加上下文瘦身机制每次重要对话结束后让 Agent 把这段对话提炼成几条要点存入记忆然后清理掉详细的原始讨论。这样一来长会话也能保持轻装上阵模型始终把注意力放在当前重要的信息上。6. 一些值得收藏的实战习惯最后分享几个我踩过多次坑之后沉淀下来的习惯不一定写进文档但对长期使用很有帮助。第一是多看运行日志特别是失败时候的日志。WorkBuddy 的日志其实非常详细把 Agent 的每一步决策都记录下来了。你只要花十分钟看一次完整日志很多抽象的概念都会具象化。第二是 Skill 文件建议做版本管理。我自己用了一个目录专门放 Skill 的版本每次修改都留档。因为这个平台迭代很快你上一个版本写的 Skill 可能在新版本里就不再兼容有留档就能快速回退。第三是善用环境变量做模型配置的切换。同一个 Agent测试的时候用一个模型正式跑的时候换一个模型这种切换通过环境变量最方便不用改配置结构。特别是对比不同模型跑同一个任务的效果时这个习惯能让你效率翻倍。从最开始把 WorkBuddy 当成一个助手工具到后来在开放平台上写自己的 Skill、搭自己的 Agent整个过程回过头看最大的转折点是心态变化不要把它当成一个配置好的工具来用而是当成一个你可以定义它怎么做事的平台来看待。同样的环境在会写 Skill 的人手里和不会写的人手里产出的东西完全是两个层级。希望这篇东西能帮你把这条路走得更顺一点。 从零搭建WorkBuddy Agent应用：Skill编写与踩坑实战指南
我先说个真实的场景。上周有个朋友找我说他拿到了 WorkBuddy 开放平台的开发者资格结果打开控制台发现文档一摞一摞的什么 Skill、Agent、工作流编排、记忆模块光概念就把他绕晕了。他跟大多数刚接触这个平台的人一样第一反应是这不就是个带插件的聊天工具吗结果越看越发现事情没那么简单——这其实是一套完整的 Agent 应用开发环境只是入口长得很像日常工具。我自己的经历也差不多。从最初把 WorkBuddy 当成一个效率工具来用到后来基于开放平台写自定义 Skill再到现在把它作为 Agent 应用的运行时来设计整个路径踩过不少坑。这篇文章就把这条从零到能跑通一个 Agent 应用的完整路径写清楚包括平台概念怎么理解、环境怎么搭、Skill 怎么写、Agent 怎么组装以及那些文档里不会写的坑。适合刚拿到开放平台权限的个人开发者也适合那些想用它做点什么但还没想清楚从哪下手的玩家。1. 先搞懂 WorkBuddy 开放平台对个人开发者意味着什么很多人拿到 WorkBuddy 开放平台的第一反应是这是不是一个AI 应用商店我上去写个插件就行这个理解不能说错但会把你带偏。因为如果你只把它当成插件平台你做的还是工具而不是Agent。1.1 它不是一个普通聊天工具而是一个 Agent 运行时WorkBuddy 的工作台本质是一个 Agent 运行时环境。所谓 Agent 运行时简单类比就是给 AI 一个能干活的操作系统。普通聊天工具的逻辑是你输入问题模型输出回答结束。Agent 运行时的逻辑是你给一个目标模型自己拆解任务、调用工具、获取信息、判断下一步、反复迭代直到目标完成。WorkBuddy 开放平台做的事情就是把这个运行时暴露给个人开发者让你不光是用 AI 聊天而是可以让 AI 替你执行一套完整的工作流。我当时真正理解这一点是在看它运行日志的时候。你会发现模型每一步的动作都被记录下来思考过程、选择了哪个工具、工具返回了什么、模型根据返回决定下一步做什么。这不是单纯的大模型接口调用而是一个有状态的执行环境。1.2 工作台、Skill、Agent 三者的关系平台里有三个概念特别容易混淆工作台、Skill 和 Agent。我用一个生活化的方式来解释。工作台是你干活的操作台它提供运行环境、文件系统、命令执行能力、网络访问能力。Skill 是单项技能就像你会做饭、会开车、会修电脑这是单个能力点。Agent 则是一个有自主性的执行者它不是一个技能而是一个会调用技能去完成目标的东西。打个比方Skill 是工具箱里的扳手或者螺丝刀Agent 是那个拿着工具箱去修东西的工人。工作台是工人的工作间。在开放平台的体系里Skill 是可以被单独发布、复用的能力单元Agent 则是把这些能力单元组合起来配上规划和记忆形成可以独立完成复杂任务的智能体。1.3 和 CodeBuddy 的区别别再混淆了网上经常有人问 CodeBuddy 和 WorkBuddy 有什么区别。我查过一些资料也实际用过之后的理解是CodeBuddy 更偏向代码生成与代码理解它的场景锚定在开发任务上比如写代码、改代码、解释代码、生成测试用例。WorkBuddy 的工作台定位更宽它是一个通用的 Agent 工作环境Skill 机制让它可以扩展到各种各样的场景代码开发只是其中一类应用。对个人开发者来说这个区别很重要。如果你想做一个写代码的助手CodeBuddy 的路径可能更直接但如果你想让 AI 帮你处理数据分析、内容整理、多步骤信息检索这类跨领域任务WorkBuddy 的 Skill 加 Agent 组合会更契合。我自己为什么选 WorkBuddy 这条路因为我不想只做一个编程专用的玩意我更想要一个能承载多种任务、可以自己定义能力的 Agent 平台。2. 环境准备安装部署与模型服务配置Linux 实测官方文档里环境准备这部分写得看着挺顺但实操起来有不少细节文档没提。我建议第一次装的时候直接看最新版的 Release 说明别依赖旧教程WorkBuddy 的迭代速度相当快。2.1 Ubuntu 下的安装细节与常见报错我自己长时间用的环境是 Ubuntu也听说过有人成功在别的 Linux 发行版上跑起来所以我把 Linux 的安装作为主路径来写。基本安装分这几步下载对应架构的安装包、解压到工作目录、初始化配置、启动服务。如果你是图形界面环境也有桌面版本的安装向导但底层逻辑是一样的。核心步骤我给你直接列出来# 1. 解压到独立目录 mkdir -p ~/apps/workbuddy tar -xzf workbuddy-linux-x64.tar.gz -C ~/apps/workbuddy # 2. 首次启动前检查依赖 # 有些极简安装的系统缺基础库直接启动会报错 ldd ~/apps/workbuddy/workbuddy | grep not foundldd这步是我强烈建议做的。我装的时候遇到过缺libfuse2的情况启动直接失败控制台只给一个含糊的错误提示。ldd会把缺失的动态库全部列出来缺什么补什么比盲试高效得多。# 3. 安装缺失依赖不同发行版包管理器不同 sudo apt install libfuse2 # 4. 启动 ~/apps/workbuddy/workbuddy启动成功之后它会默认开一个本地端口。第一次访问会让你做初始化这个初始化本质上是生成运行配置和密钥对配置目录一般在用户主目录下面。如果你以后想改配置别在程序目录里找去配置目录里找。2.2 对接 DeepSeek 开放平台的 API 配置安装好之后最关键的步骤是把模型服务接进来。我自己用的是 DeepSeek 开放平台作为模型后端原因很简单它在个人开发者这个层级性价比很能打而且它的 API 兼容主流调用风格适配起来很方便。在开放平台那边申请好 API Key 之后把模型服务信息填进 WorkBuddy 的配置里。有些版本的界面里叫模型服务有的叫模型提供商不同版本叫法不一样但本质就是两个信息API 地址和 Key。# 配置文件里模型相关的大致样子具体字段看你的版本 model: provider: deepseek api_base: https://api.deepseek.com # 以官方渠道为准 api_key: sh-你的密钥 model_name: deepseek-chat这里唯一要提醒的是不要明文把 API Key 写在能被随便看到的地方。WorkBuddy 的配置系统通常支持环境变量注入把 Key 放到环境变量里配置文件里只写变量引用这样既方便换 Key也安全一些。2.3 模型选择的经验之谈模型选择我给的方案是日常 Agent 任务用 deepseek-chat它综合表现稳定、速度快、成本低需要复杂推理的任务切成更强推理的模型。模型切换在 Agent 应用中很有用——Agent 不同阶段的子任务难度差异很大拆解任务时用轻量模型能省不少成本真正要深度推理的时候再换重模型。我用 WorkBuddy 接 DeepSeek 开放平台跑下来最直观的感受是上下文窗口很够用Agent 执行长流程的时候不会因为上下文不够中途断掉。而且速度对于大多数个人开发者的使用场景完全够。3. 从 Skill 开始把重复工作封装成能力在开放平台里写 Skill 是个人开发者从使用者变成开发者最关键的一步。你说你不会什么高级编程语言没关系Skill 的门槛低到让我意外。3.1 Skill 的本质与文件结构Skill 本质上就是一套规则加提示词外加可选的外部脚本或 API 调用。一个 Skill 文件里面通常包含这几个部分功能描述说明这个 Skill 是干什么的模型会根据描述决定什么时候调用它执行指令告诉模型具体怎么做参数定义需要输入什么参数输出格式结果应该怎么呈现我用一个很简单的例子来说明。假设我想要一个周报生成器Skillname: weekly_report description: 根据本周的工作记录生成结构化周报 parameters: work_logs: type: string description: 本周的工作记录可以是吃顿的文本 instructions: | 1. 分析用户提供的工作记录提取关键任务和成果 2. 按本周完成/下周计划/问题与风险三部分组织 3. 每条任务写明做了什么、产出是什么 4. 语言简洁使用动词开头这个 Skill 没有一行程序代码但它完全可用。因为模型本身理解自然语言Skill 做的事情是给模型一个清晰的操作手册。3.2 手写一个实际 Skill信息汇总助手我再写一个稍微复杂一点的 Skill 例子这个 Skill 做的事情是给模型一堆杂乱的资料链接和笔记它整理成一份有主题分类、有优先级标记的调研摘要。name: research_synthesis description: 将分散的资料整理为结构化调研摘要 parameters: materials: type: string description: 原始资料、链接、笔记、引用等支持多段文本 focus: type: string description: 这次调研需要重点关注的方向 instructions: | 1. 先判断所有资料的整体主题分布 2. 对资料按主题聚类每类用一段概括性描述 3. 每个主题下列出关键信息点和来源 4. 最后补充待深挖区域列出资料中提到但尚未展开的线索 5. 如果 focus 参数有指定方向优先保证这个方向的信息完整性 output_format: | ## 主题一XXX - 核心信息点 - 资料来源 ## 待深挖 - 线索1、线索2这个 Skill 的实际价值在于它把整理资料这件事的经验固化下来了。以前我自己整理资料是全凭感觉现在模型每次都按照同样的标准去做输出结构稳定质量不会忽上忽下。3.3 自定义指令推荐为什么这么写更有效热词里有workbuddy 自定义指令推荐我根据实际测试给几个方向。第一是给模型定义身份。不要让它觉得自己是个通用助手而是让它进入一个特定的角色。角色定义能明显改变输出的语气和视角。第二是给出限制条件比如不要使用夸张的形容词每段不超过 X 字限制条件对生成质量的提升非常大。第三是给出中间思考要求比如分析之前先列出你需要注意哪些陷阱这个会让模型在生成时更仔细。我自己的习惯是每个 Skill 里都写一句如果信息不足明确说不足不要猜测。这能极大减少模型一本正经胡说八道的情况。4. 组装 Agent让 Skill 组合成自动决策的工作流写了一个 Skill你只是造了一把工具。真正有意思的部分是让 WorkBuddy 把这些工具组合成一个有自主行为能力的 Agent。4.1 从工具集合到Agent的转变工具集合和 Agent 的区别在哪里工具集合是你有什么Agent 是你会怎么用。同样的工具不同 Agent 用出来的效果天差地别。我用一个实际的案例来说。我做过一个竞品情报 Agent它需要做的事情是定期盯几个竞品的信息、把新内容抓下来、按主题归档、生成变化摘要。如果只是把抓取工具和摘要 Skill摆在那里你每次都要手动告诉模型现在抓取 A 网站然后摘要一下。这不叫 Agent这叫遥控器。真正的 Agent 是把决策也交给模型。我给它的目标指令是每天检查竞品信息源如果有新内容做摘要并归档如果无新内容等待第二天。它会自己决定何时调用抓取工具、何时调用摘要 Skill、何时不需要任何动作。这个自己决定下一步的能力就是 Agent 和工具集合最本质的区别。4.2 任务规划与工具编排的关键设计在 WorkBuddy 开放平台里搭 Agent核心是编排什么样的任务顺序最合理、什么条件下走哪条分支、失败之后怎么降级。我的经验是编排设计要遵循几个原则先拆解后执行让模型先输出执行计划把一个大任务拆成步骤这能显著减少漏步骤的情况关键节点设置检查点高风险动作比如发送、修改、删除前面加一层确认判断失败分支要给明确指令告诉模型如果调工具失败重试一次还失败就跳过并且记录原因不要死循环实际配置时我会把这类原则写成 Agent 的工作准则放在最前面。4.3 Agent 记忆短期上下文与长期信息该怎么用热词里agent记忆的出现频率很高这确实是 Agent 从玩具走向实用的分水岭。没有记忆的 Agent 每次对话都是第一次见面它记不住你一周前让它关注的某个话题。WorkBuddy 的记忆机制我做下来大概是三层对话上下文当前任务进行中的临时记忆任务结束就清掉会话记忆保存在一个会话周期内的重要信息长期记忆跨会话保存的用户偏好、历史决策、事实信息我的经验是不要把什么都塞进长期记忆要像人一样只记值得记的。我在设计记忆策略的时候会在 Agent 执行完一个重要任务之后让它自己生成一段本次任务结论并决定是否存入长期记忆。这个让 Agent 自己判断该记什么的做法效果比手动指定要灵活得多。4.4 一个完整的 Agent 示例流程我描述一个实际的 Agent 应用案例个人知识库管理 Agent。这个 Agent 接收用户丢过来的各种碎片信息——网页链接、PDF、笔记片段、想法它做的事情是第一步识别信息类型。判断是一篇文章、一段笔记还是一个需要跟踪的任务。第二步根据类型调用不同的 Skill文章链接走抓取加摘要笔记走分类加打标签任务类走待办提取。第三步更新记忆把新知识按主题写入长期记忆同时检查是不是和已有的知识冲突如果有冲突生成一个冲突提示。第四步生成操作报告告诉用户我处理了什么、放在了哪里、发现了什么潜在问题。这个 Agent 的完整工作流没有写一行传统的业务代码全部是用 Skill 加编排配置出来的。它的价值不在于某个单独的功能有多强而在于它能把散落的输入自动归位持续积累成结构化的个人知识库。5. 接入开放平台后的常见坑与排查链路如果说到这一步你都顺利恭喜你已经超过大多数人了。剩下的篇幅用来写我实际踩过的坑。不会写这些坑的教程不是好教程。5.1 Agent 执行被终止一次完整的问题排查热词里有一条agent execution terminated due to error我见过好多次了我自己也遇到过。这个报错看起来像平台故障但大多数情况下是配置问题。我遇到的一次情况是这样Agent 在执行一个需要联网的任务时中途被终止。我的排查链路是这样的第一步查看运行日志定位终止发生的步骤。日志显示任务在调用某个外部服务这一步被终止不是模型生成阶段。第二步单独测试那个外部服务发现服务本身没问题能正常返回。第三步对比手动调用和 Agent 调用时的差别最后发现是超时时间设置的问题。那个外部服务响应本来就需要比较长的时间但 Agent 调用的超时阈值设置得比较短时间一到就强制终止了。第四步调整超时阈值重新执行问题解决。这个坑特别容易踩的原因是Agent 调用工具的链路比直接调用长多了一层模型解析工具返回结果的时间。你以为工具的响应时间是 10 秒实际上整个调用链路可能耗时 30 秒超时阈值只设了 20 秒就很容易触发终止。5.2 工具调用失败根因往往是模型没理解工具用法另一个高频问题是工具调用失败。打开日志经常能看到模型发起了一个工具调用但参数格式不对或者使用了不存在的参数名。我之前一直以为这是平台调度的问题后来才明白根因在模型那边。模型是根据 Skill 文件里的描述来调用工具的如果你的参数定义写得不够清楚模型就会凭感觉填参数填错很正常。解决方法是把参数定义写得更窄# 不推荐模糊的参数描述 url: type: string description: 目标网址 # 推荐明确的格式约束 url: type: string description: 目标网址必须以 http:// 或 https:// 开头包含完整域名和路径这个细节很微妙。模型不会像人一样去猜你什么意思它严格基于描述来决策。描述越具体模型的选择空间越小出错率越低。5.3 上下文窗口与模型选择的平衡还有一类问题不是报错而是效果变差。通常是 Agent 跑了一段时间之后输出开始变得跳跃、丢失细节。这往往是因为上下文已经堆积了大量不重要的信息把关键信息挤掉了。我的做法是给 Agent 加上下文瘦身机制每次重要对话结束后让 Agent 把这段对话提炼成几条要点存入记忆然后清理掉详细的原始讨论。这样一来长会话也能保持轻装上阵模型始终把注意力放在当前重要的信息上。6. 一些值得收藏的实战习惯最后分享几个我踩过多次坑之后沉淀下来的习惯不一定写进文档但对长期使用很有帮助。第一是多看运行日志特别是失败时候的日志。WorkBuddy 的日志其实非常详细把 Agent 的每一步决策都记录下来了。你只要花十分钟看一次完整日志很多抽象的概念都会具象化。第二是 Skill 文件建议做版本管理。我自己用了一个目录专门放 Skill 的版本每次修改都留档。因为这个平台迭代很快你上一个版本写的 Skill 可能在新版本里就不再兼容有留档就能快速回退。第三是善用环境变量做模型配置的切换。同一个 Agent测试的时候用一个模型正式跑的时候换一个模型这种切换通过环境变量最方便不用改配置结构。特别是对比不同模型跑同一个任务的效果时这个习惯能让你效率翻倍。从最开始把 WorkBuddy 当成一个助手工具到后来在开放平台上写自己的 Skill、搭自己的 Agent整个过程回过头看最大的转折点是心态变化不要把它当成一个配置好的工具来用而是当成一个你可以定义它怎么做事的平台来看待。同样的环境在会写 Skill 的人手里和不会写的人手里产出的东西完全是两个层级。希望这篇东西能帮你把这条路走得更顺一点。