Hermes实战：把重复工作流固化为Agent自定义技能

1. 从重复工作流到技能Agent 落地的分水岭用过一段时间 Agent 的人应该都有同样的感受刚接上的时候觉得好聪明什么都能聊用了一个月之后觉得像个永远记不住事的实习生同一个流程天天要重新教一遍。比如你让它在代码仓库里找出最近三天改过的文件并按模块归类第一次它做得很认真第二次、第三次也还行但到了第五次你会发现它开始漏掉某种后缀、忘掉你上次强调的不要统计 test 目录每次都得把指令重新念一遍甚至要补充对话历史才能复现上次的结果。问题到底出在哪很多人第一反应是模型不够聪明换个更强的大模型。但实际上绝大多数情况下问题不在模型而在 Agent 的结构设计上。你把怎么做这个过程全部压在模型推理上模型每次对话都在重新理解、重新编排、重新踩坑表现自然忽上忽下。把重复执行的工作流程保存成自定义技能就是为了解决这件事。所谓技能我的理解是把一段固定指令模板、参数定义、执行逻辑和验证规则打包成一个可复用的模块。Agent 不再需要每次从零学习怎么处理这类任务它只需要识别用户的需求命中哪个技能然后调用这个技能执行即可。你可以把它理解成给实习生写了一份带检查清单的作业指导书——不是每次手把手教而是让它按标准流程做。标题里的 Hermes目前社区讨论比较多的方向是把它当作一个可本地部署的 Agent 开发框架来用模型底座可以接 DeepSeek 这类开源模型也可以通过 API 方式接入合适的商用模型。它的核心优势在于把 Agent、技能、执行器这几个概念拆得比较清楚不至于一上来就陷入 Prompt 工程的黑洞。这篇内容我就以 Hermes 为例从一个真实需求出发完整走一遍把重复工作流固化为自定义技能的流程包括技能设计、编写、接入、测试和后续维护。这篇文章适合谁看如果你正在做 Agent 开发或者已经跑通了一个原型但觉得它不太稳定又或者是想给团队内部搭建一套可复用的 Agent 能力库那么这篇内容基本就是围绕你的痛点写的。如果你只是刚接触 Agent对技能执行器工作流这些词还比较模糊我也会尽量把概念拆开讲清楚。2. 动手前先理清概念Agent、Skill 与 Harness 到底各管什么很多人在搜 Hermes 相关资料时一定会碰到这么几个词Agent、Skill、Harness、Memory。这几个词在官方文档里各有定义但社区讨论经常混着用导致新手越看越乱。我按自己做项目时的理解给它们划一条清晰的分界线。Agent 是决策者负责理解用户输入、拆解任务、决定调用什么技能、按什么顺序调用。它本身不直接产生最终执行结果而是做编排。Skill 是可复用能力的封装负责怎么做好某件事的细节。Harness 是执行容器负责把技能代码跑起来管理输入输出、异常、资源限制这些基础设施层面的东西。Memory 是 Agent 在多次会话之间保存的上下文信息比如用户偏好、历史决策、中间结果。用个不太严谨但很好懂的类比Agent 像一个项目负责人Skill 像项目组里各领域的专家Harness 像会议室和白板Memory 像项目档案柜。负责人不亲自画架构图但他知道该让哪个专家来画专家们需要会议室才能讨论讨论的结论要归档到档案柜里方便下次调用。组件职责典型问题Agent意图理解、任务编排、技能路由不知道该用哪个技能Skill某个具体能力的执行逻辑技能内部逻辑有 bugHarness执行环境、参数校验、沙箱隔离技能跑不起来、报错中断Memory上下文存储、跨会话状态多轮对话后丢失关键信息搞清楚这个边界之后我们对自定义技能的定位就很清晰了你创建的是一个 Skill不是重写一个 Agent。在 Hermes 里注册技能之后Agent 通过技能的描述和参数定义来判断何时调用它。这里有个关键点技能的描述写得清不清楚直接决定了 Agent 会不会正确地调用它。实际开发中我见过太多人把技能描述写成一句话日志汇总技能结果 Agent 在需要汇总日报的时候调用了一个用于错误码查询的技能就是因为描述里的触发场景写得太模糊。至于 Harness 和 Agent 的关系也有必要多说两句。搜过的朋友可能看到过agent execution terminated due to error这类报错这个报错通常不是 Agent 本身出的问题而是 Harness 在技能执行过程中捕获到异常后强制终止了执行。这种设计在 Hermes 里是刻意的避免一次未处理的异常把整个 Agent 会话拖垮。我在后面讲调试时会专门回到这个问题。3. 技能设计从梳理高频流程到确定参数边界在打开编辑器之前先做设计。这一步的价值容易被低估但它决定了技能能不能被复用。先回答一个问题什么样的工作流值得做成技能我的判断标准有三个缺一不可。第一频率足够高。至少一周要用三五次否则你花一小时写技能结果一个月用不了两次性价比很低。第二流程足够稳定。每次执行的核心步骤是相似的变化的只是输入参数。如果每次任务的要求都天差地别那说明它还没沉淀成标准流程做技能为时过早。第三结果可验证。技能跑完之后你知道什么算做对了什么算做错了。连验证标准都不明确的任务做成技能后只会把一个不确定流程固化成一个稳定产出不确定结果的黑盒。拿我自己项目里的一个例子每周要给几个代码仓库生成变更摘要。之前每次都要让 Agent 读 git log、统计文件改动、按模块归类、排除掉 test 和 docs 里不影响逻辑的变更、最后输出一个 Markdown 报告。这套流程本身就符合上面三个标准每周固定、步骤稳定、结果是文件可以直接检查。确定要做之后再把技能拆成下面几个部分触发场景描述。写清楚这个技能在什么场景下被调用越具体越好最好包含示例句式。输入参数。列出调用这个技能时需要提供的字段包括类型、是否必填、默认值、说明。执行体。技能实际运行的逻辑通常是脚本或命令序列。输出格式。定义好返回给 Agent 的结构化结果方便 Agent 后续拼接、总结或继续追问。参数的定义是这里面最容易出问题的一环。常见错误是把参数设计得太细太多比如一个日志分析技能搞了十几个可选参数Agent 在调用时反而不知道该填什么。我的经验是必填参数控制在 3 个以内其他全部给默认值。以我刚才说的仓库变更摘要为例参数就三个仓库路径必填、时间范围默认最近 7 天、排除目录列表默认排除 test 和 docs。其他像输出风格是否包含提交人信息这些都先不参数化让技能内部用固定规则处理。等跑一段时间发现确实有人需要自定义风格再把参数加上去也不迟。过早的参数化十个里头有八个是过度设计。4. 在 Hermes 里创建一个可复用的自定义技能说完了设计进入正题。我在 Hermes 里创建技能通常走四个步骤建目录、写技能描述文件、写执行脚本、注册验证。Hermes 的版本迭代比较快不同分支的目录结构略有差异但核心逻辑大同小异下面按社区里最常见的方式来讲。4.1 搭建 Hermes 运行环境先解决环境问题。Hermes 支持本地直接跑也支持 Docker 部署。本地运行时需要有 Python 3.10 环境然后用 pip 装 Hermes 的核心包Docker 方式则直接拉镜像方便隔离依赖。本地安装的命令大概是这样git clone https://github.com/your-hermes-fork/hermes.git cd hermes pip install -r requirements.txt python -m hermes init --name my-agent初始化完成之后Hermes 会生成一个项目目录里面有agents/、skills/、memory/、config/这些子目录。其中skills/就是我们放自定义技能的地方。如果你是在 Windows 上部署我的建议是用 Docker 而不是直接在 Windows 里装一堆依赖。我之前在 Windows 下被 Python 虚拟环境和 C 扩展折腾过几次后就统一改成 Docker 了。Windows 上跑 Docker 需要安装 Docker Desktop启动之后映射端口即可docker run -d --name hermes \ -p 8080:8080 \ -v /path/to/my-agent/skills:/app/skills \ -v /path/to/my-agent/config:/app/config \ hermes-agent:latest需要说明的是Hermes 本身提供了一个默认的本地技能文件但它和顶层 Agent 有哪些真正对应的关联不同版本的实现差异挺大。我这里使用的目录挂载方式是社区里维护分支最常见的做法把宿主机的skills/目录挂载进容器改完技能文件不用重新构建镜像。4.2 注册一个技能从定义到执行脚本假设我们要实现一个最简单但完整的技能读取一个日志文件分析其中的错误级别日志按模块统计出现次数并输出 Top 10 错误列表。第一步在skills/下创建log_error_stats/目录技能文件组织如下skills/ └── log_error_stats/ ├── SKILL.md └── run.pySKILL.md是技能定义文件负责告诉 Hermes 这个技能是干什么的、需要什么参数、如何执行。内容可以参照下面这样写--- name: log_error_stats description: 分析指定日志文件中的错误日志按模块统计错误次数并返回 Top 10 错误列表 version: 1.0.0 parameters: - name: log_path type: string required: true description: 日志文件的完整路径 - name: top_n type: integer required: false default: 10 description: 返回错误数量最多的前 N 个模块 executor: type: python entry: run.py output: type: json schema: total_errors: integer top_errors: array analyzed_at: string ---这个文件的核心意义在于让 Agent 知道有这个技能并且知道在什么情况下调用它。description 字段尤其重要因为 Hermes 的 Agent 是通过语义匹配来决定技能路由的它不会遍历执行逻辑只会反复读取你的描述来做判断。如果把 description 写成分析日志它可能在任何涉及日志查看的请求下都调用这个技能哪怕用户只是想看日志里有几行 INFO。反之把 description 写详细一点包含典型场景、输入输出特点匹配精度会明显提升。第二步写执行脚本run.py。这里可以自己处理命令行参数也可以直接读取 Hermes 注入进来的环境变量。为了方便我直接定义标准输入输出#!/usr/bin/env python3 import sys import json from datetime import datetime from collections import Counter def parse_log_line(line: str): # 这里按常见日志格式做简化解析 parts line.split( , 3) if len(parts) 4: return None level parts[2] module parts[3].split(:)[0] return level, module def main(): args json.loads(sys.argv[1]) log_path args[log_path] top_n int(args.get(top_n, 10)) counter Counter() total_errors 0 with open(log_path, r, encodingutf-8, errorsignore) as f: for line in f: parsed parse_log_line(line) if parsed is None: continue level, module parsed if level ERROR: total_errors 1 counter[module] 1 top_errors counter.most_common(top_n) result { total_errors: total_errors, top_errors: [{module: m, count: c} for m, c in top_errors], analyzed_at: datetime.now().isoformat(), } print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()这里我做了两个简化一是用sys.argv[1]直接接收 JSON 字符串作为输入避免依赖具体的框架 API二是日志格式解析得很天真真实项目中这一步要配合正则表达式来做否则很多日志格式会解析失败。不过作为示例它足够说明问题。第三步注册技能。在 Hermes 中注册通常分自动扫描和手动指定两种。自动扫描就是每次启动时检查skills/目录下所有含SKILL.md的子目录把它们加载进技能列表手动指定则是在config/agents.yaml里显式列出技能名称。我建议调试阶段用自动扫描跑通之后改成手动指定因为自动扫描会加载目录下所有技能一旦技能多了路由噪音也会变大。4.3 调用链完整走一遍技能注册好后启动 HermesAgent 能看到log_error_stats这个技能。当用户提出一个自然语言请求比如帮我看一下 /var/log/app/error.log 里有哪些模块错误最多Agent 会经历以下过程识别意图用户需要日志分析。检索技能根据 description 匹配到log_error_stats。抽取参数从用户输入中提取log_path为/var/log/app/error.logtop_n使用默认值 10。调起 Harness 执行run.py把参数以 JSON 字符串形式传入。获取输出结果Agent 会把它组织成自然语言回复用户这个日志文件中共有 87 条错误其中 auth_service 模块最多有 23 条……整个链路里第 3 步是最有意思的。Hermes 的参数抽取由带工具的 Agent 模型完成不靠正则硬匹配。所以如果用户说的是统计一下最新的那个日志Agent 有可能会先调用文件查找技能定位到具体文件路径再调用log_error_stats。也就是说技能之间是可以通过 Agent 的编排组合衔起来的。5. 从命令行到 Agent 路由两种调用方式与测试技巧新技能写完别急着直接扔给 Agent 用。我习惯先在命令行层面把技能跑通确认它没有语法错误、参数解析正常然后再让它进入 Agent 的候选技能池。否则一个本身就有 bug 的技能加上 Agent 的语义包装出了问题你根本分不清是执行逻辑的锅还是路由的锅。5.1 独立的命令行测试在skills/log_error_stats/目录下直接执行python run.py {log_path: /var/log/app/error.log, top_n: 5}观察输出 JSON 是否符合预期。如果脚本本身报错那就先把脚本修好不需要惊动 Agent。测试的时候务必覆盖几类情况文件不存在时怎么办日志格式异常时会不会崩溃超大文件会不会内存被打满这也是技能代码里一定要做防御性编程的原因。我上个月就在类似环节遇到过典型的agent execution terminated due to error报错。当时写了一个技能内部直接用subprocess.run调一个外部命令没有捕获异常。外部命令因为权限问题退出码非零subprocess 直接抛错Harness 捕获异常后终止了整个 Agent 执行。日志里虽然能看到堆栈但用户只会在界面上看到一句execution terminated。后来我在技能里加了异常捕获和标准错误输出才把问题定位到权限上。血的教训技能脚本中任何可能抛异常的代码都必须显式处理尤其是访问文件、网络、外部命令这三类。5.2 在 Agent 侧验证路由命令行跑通后再启动 Hermes用真实对话来测试。我在这里踩过一个很有代表性的坑技能逻辑完全正常但 Agent 死活不调用它。后来排查发现是技能描述里写了一个不太常见的术语而用户请求里用的是日常化表达模型无法把两者关联起来。修正方式很简单把 description 里补上错误日志日志分析统计错误这类近义词Agent 立刻就能精准路由了。所以测试 Agent 路由时建议准备一组用户视角的真实问法而不是只拿官方示例测试。比如这个日志里哪个模块报错最多帮我统计一下今天 error.log 的错误排行看看这些错误集中在哪些组件如果这几种问法都能触发同一个技能说明描述写得到位。如果只命中其中一两种就继续往 description 里补表达。5.3 引入 Memory让技能结果被记住搜过 Hermes 资料的朋友一定看到过agent记忆这个词。在自定义技能的场景里Memory 的价值主要体现在两个地方一是记录技能调用的偏好比如用户总喜欢把top_n设成 20那么第二次调用时 Agent 可以自动带出这个偏好二是缓存技能执行结果避免重复执行耗时任务比如同一个日志文件半小时内被反复分析完全可以直接读缓存。Hermes 里的 Memory 默认是向量存储技能执行完之后可以将结果摘要写入 memory为后续会话提供上下文。但这也要克制不是所有结果都值得写。我一般只让技能返回一个是否值得记忆的标记位或者要求 Agent 只记忆用户表达出的偏好而不是记忆每一次结果明细。要不然跑个几周记忆库里全是过期日志摘要反而污染了 Agent 的上下文判断。6. 技能从能跑到好用调试、维护与迭代的四个关键点技能做完不是终点它就是你代码库里的一个模块后续必须持续维护。我从多次迭代里总结了几条经验。6.1 错误信息要具备可诊断性技能内部的报错信息一定不要只打印分析失败这四个字。要包含参数快照、执行阶段、失败原因、异常堆栈。还是上面权限问题的例子我在 catch 分支里把subprocess.run的returncode和stderr内容原样输出之后定位问题的时间从半小时缩短到两分钟。6.2 版本号不只用在代码里技能定义文件里那个version字段不要懒得改。每次调整逻辑或参数手动递增。这样当你同时挂载多个技能版本时路由表里能清楚地看到实际生效的是哪个版本。更重要的是我在 Agent 里会让它把技能版本记录到输出结果里这样一旦结果不对可以立刻还原是哪个版本的技能产出了这个结果。6.3 灰度策略先小范围试再全量开放如果这个技能会影响线上任务别直接注册成默认技能。Hermes 的配置里通常可以设置某个技能只对特定 Agent 生效我在自己的项目里是先放到测试 Agent 里跑一周记录调用成功率、平均执行耗时、参数抽取准确率都达标后再搬到生产 Agent。这一周里就能暴露很多边角料问题比如某些日志格式解析不了、某些参数在特定表达下抽取不出来。6.4 周期性审视技能列表技能会越加越多这并不代表效率越来越高。我的习惯是一个月回头看一次技能列表把调用率低的技能剔除把参数风格类似的技能合并。比如我之前分别建了日报生成和周报生成两个技能后来发现核心逻辑完全相同只是时间范围不同就合并成一个报表生成技能把时间范围作为必填参数。技能粒度太大不好复用粒度太小则路由成本高需要在实践中慢慢找到那个平衡点。给一个判断技能质量的简单公式调用次数越多、参数抽取越稳、结果修正越少说明这个技能设计得越成功。反过来如果每次调用后用户都要手动纠正输出那不是用户的问题是技能里隐含了一个没被参数化的变量。7. 最后再分享一个实践技巧整个自定义技能的设计里我最大的体会是技能化本质上是把隐性知识变成显性逻辑。每次你发现这个流程我好像又重复教了 Agent 一遍那就是一个制造技能的时机。与其收藏一堆 Prompt 模板不如把最常用、最稳定的那几条沉淀成真正的、可执行的、可测试的技能模块。具体到 Hermes 这个框架我的建议是先从小的开始。挑一个你每个星期都会做的重复任务按照这篇文章里的路径走一遍梳理流程、定义参数、写执行脚本、注册技能、对话验证。等第一个技能跑顺了自然就能体会 Agent 从每次重新理解到直接调用技能的差别有多大。后面再慢慢扩展技能的复杂度和边界逐步建立属于你自己的能力库。