Hermes Agent的Skill机制：从零实现陌陌消息自动回复

在 Hermes Agent 这类 AI Agent 工具里把“陌陌回复信息”做成一个 Skills本质上不是写一段提示词而是给 Agent 增加一项可复用的消息处理能力。很多人在第一次接触 Skills 时会误以为只要把需求描述清楚Agent 就能自动完成所有事情。真正跑过之后你会发现自动回复类技能真正值得关注的不是“能不能回”而是能不能在收到一条消息后按可控流程完成消息读取、意图判断、回复生成、发送动作和结果记录。这篇文章会把 Hermes Agent 的 Skills 机制、消息自动回复的最小实现、批量化和踩坑经验都拆开讲一遍。如果你的目标是陌陌这类 IM 平台而且准备接真实消息源我建议你先确认平台接口、账号授权和合规边界再用自己的测试会话验证不要一上来就对真实用户批量发送。1. 先搞清楚 Skills 在 Hermes Agent 里的角色再谈自动回复1.1 它不是普通插件是一次“能力封装”在 Hermes Agent 中Skills 可以理解成给 Agent 提供的一组可调用能力包。每个技能通常包含三个部分一份给 Agent 看的技能描述、一份参数定义以及一个可执行入口。Agent 会根据当前对话内容、用户指令和技能描述决定什么时机调用这个能力。这里的关键点在于技能不是简单的“插件开关”。插件一般是按固定规则直接生效而 Skills 是让 Agent 像人一样判断“我现在需不需要调用这个工具”。比如你正在和 Agent 讨论技术方案它大概率不会触发“消息自动回复”技能。但当你把一条消息原文传进去说“帮我回一下”它可能就会调用技能。所以如果你想让 Hermes Agent 学会回复陌陌信息第一步不是急着写代码而是先把“技能描述、参数、执行逻辑”这三层结构想清楚。描述写得太模糊Agent 就不知道什么时候该调用参数定义错了技能执行时会频繁报错执行逻辑里如果缺少去重和冷却可能产生重复回复。1.2 消息自动回复适合做成 Skill但流程要拆细有开发者习惯把自动回复逻辑直接写进系统提示词比如“收到消息后按照某种风格回答”。这种方式在演示时看起来没问题但一旦消息类型变多、回复策略变复杂提示词会变得很难维护。每次调整都可能影响 Agent 的其他行为。把“陌陌回复信息”做成 Skill 的优势很明显逻辑独立可以单独测试回复策略可以版本化管理技能可以复用到其他消息平台出现问题时定位更清晰。但把逻辑封装起来并不等于自动能用。我见过不少人把一段 Python 脚本放在技能目录里结果 Agent 完全没调用或者调用之后连参数都没传对。原因通常是技能描述里没有说清楚“这个脚本是做什么的适合什么场景”导致 Agent 不知道该在什么时候激活它。因此给 Hermes Agent 写消息自动回复技能时建议把场景拆成三个环节消息输入、回复策略、发送结果。输入层决定技能能不能接收到完整消息策略层决定回复内容是否准确、安全发送层决定最终动作是否成功。技能只负责这三层中的一部分其他部分留给 Agent 或外层流程去处理。2. 把“陌陌回复信息”拆成输入、判断、输出三个环节2.1 输入层消息来源和格式怎么处理做自动回复之前先想清楚消息从哪里来。常见来源有两种一种是平台提供了 Webhook当有新消息时主动推送给你另一种是定期轮询接口主动拉取新消息。Hermes Agent 的 Skill 本身不关心消息来源它只负责处理你传进来的数据。所以你需要先有一个“消息适配层”。假设你从陌陌或其他 IM 平台收到一条消息最好先转成统一结构。我一般会用类似这样的 JSON 格式{ session_id: session_12345, sender_id: user_6789, message_id: msg_abc_001, message_type: text, content: 你好我想了解一下商品信息, timestamp: 1730000000 }sender_id用来区分是谁发的session_id用来关联同一个会话message_id则用于去重。很多新手写自动回复时会漏掉message_id结果平台回调两条相同消息时技能会把同一条消息回复两次。如果平台没有开放 Webhook也不能用非官方方式强行接入。这种情况下比较稳妥的做法是先把消息导出为本地文件或 JSONL再交给 Hermes Agent 的 Skills 做批量草稿生成。虽然做不到实时但至少不会碰平台边界。2.2 判断层意图、敏感词和时效性拿到消息后不要立刻丢给大模型生成回复。先做一层前置过滤能省很多 API 调用也能降低风险。我一般会按顺序检查消息是否重复通过message_id判断消息是否在冷却期同一会话短时间内连续收到多条消息可能不需要每条都回复消息是否包含明显不想处理的类型比如图片、表情、系统通知消息是否命中敏感词这里要做本地方案不要只依赖模型消息是否真正需要回复部分消息只是对方单纯表达不一定要触发动作。前置过滤可以写成简单规则。例如冷却期的逻辑import time cooldown_cache {} def is_in_cooldown(session_id: str, cooldown_seconds: int 30) - bool: now time.time() last_time cooldown_cache.get(session_id, 0) if now - last_time cooldown_seconds: return True cooldown_cache[session_id] now return False这样做的好处是只有需要回复的消息才会进入大模型或后续策略模块。实际测试时可以先在小样本上验证过滤规则是否会把正常消息误杀。如果冷却时间设得太长用户体验会很差设得太短又会给平台造成压力。2.3 输出层回复内容、发送动作和反馈技能的输出其实可以有两种模式。第一种是“只生成回复草稿”技能返回一段建议文本由外层脚本或人工决定是否发送第二种是“执行发送动作”技能直接调用平台接口把消息发出去。我更建议第一个版本只做第一种。原因很简单直接发送意味着技能一旦出错可能对真实用户产生可见影响。只生成草稿的话你可以在日志里检查内容确认没问题后再打开发送开关。如果确实要执行发送动作技能函数最好返回一个结构化结果方便 Hermes Agent 判断下一步{ status: sent, reply_text: 你好已收到你的消息我会尽快回复。, message_id: reply_abc_001 }如果发送失败也把错误信息返回给 Agent让它决定是否重试或提示用户。很多自动回复技能看起来“没反应”其实不是生成失败而是发送失败后错误被静默吞掉了。3. 准备 Hermes Agent 运行环境先跑通最小技能3.1 安装、登录和 API Key 的常见问题如果你刚开始接触 Hermes Agent可能会遇到安装时需要登录的问题。根据你拿到的客户端或 CLI 版本不同登录用途可能也不一样有的是为了同步技能市场有的是为了保存配置和模型密钥。我个人建议先确认你下载的发行包来源再决定是否登录。如果你只想本地测试 Skills不一定要注册账号。登录页面卡住时先看日志别急着反复刷新。很多这类工具在首次启动时要拉取基础配置网络异常或本地目录权限不足都可能导致登录流程不结束。API Key 的修改也比较常见。新手容易把 Key 直接写死在技能代码里这会有泄露风险。更稳妥的做法是通过环境变量或客户端配置项注入。如果你在客户端界面里找不到修改入口可以检查配置文件里的api_key字段通常修改后需要重启客户端才会生效。注意不要随便相信网上流传的“公用测试 Key”该使用自己的开发密钥时不要省略。3.2 先找到 Skills 目录和配置文件不同版本的 Hermes Agent对 Skills 目录的约定可能不完全一样。常见的有两种项目内skills/目录以及用户目录下的~/.hermes/skills/。你需要做的是先看启动日志确认当前加载的是哪个目录。如果日志不显示也可以通过技能市场下载一个现成技能再观察它落在哪里。这样你能快速定位 Skills 根目录而不用盲目猜测。我实际测试时会先写一个非常小的技能比如“返回一段固定文案”然后看 Agent 是否会加载。如果这个最小技能都加载不了那就没必要急着写复杂逻辑。先把目录结构、文件名、格式都摸清楚。3.3 最小技能自定义一个回复模板这里给一个最小可运行示例具体目录名和文件后缀以你的版本为准。im-reply/ SKILL.md main.pySKILL.md里先写简单描述和参数# IM Reply 根据输入消息内容生成一条自动回复文本。 参数 - content: 消息内容字符串 - tone: 回复语气可选值neutral, friendly, professionalmain.py里只做字符串拼接不调用大模型def main(content: str, tone: str neutral): prefix { neutral: 您好, friendly: 哈喽哈喽, professional: 尊敬的客户, } return prefix.get(tone, 您好) content把它放到 Skills 目录后在 Hermes Agent 会话中传入类似“帮我用友好的语气回复这条消息”的指令如果能在日志里看到技能被调用说明链路已经通了。成功标准就是技能返回了你预期的文案而且没有报错。4. 写一个“消息自动回复” Skill 的完整实现思路4.1 skill 描述文件和参数定义技能描述文件是整个 Skill 能否被 Agent 正确调用的关键。描述文件不是写给人看的有很大一部分是给 Agent 的模型看的。所以不要用“im_reply”这种含糊的表达应该写清楚这个技能什么时候该被调用。一个相对完整的描述示例# IM Auto Reply 在用户提供一条待回复的消息时使用例如“帮我回一下这条消息”“把这条消息自动回复一下”。 该技能会基于本地规则去重、过滤敏感词并生成一段待发送的回复文案。 不要用于普通的对话问答也不要直接发送消息。参数部分可以定义成content: string消息文本 sender_id: string可选的发送者标识 session_id: string可选的会话标识 message_id: string可选的消息唯一标识 style: string可选的回复风格默认 neutral参数越完整Agent 传参越准确。但也不要把所有字段都设置成必填否则 Agent 不知道填什么时容易报错。建议只有content必填其他字段按需传入。4.2 业务代码消息轮询、去重、回复生成这里的核心是数据结构和去重逻辑。下面的代码是示例写法接口名和调用方式以你的实际环境为准。import time from typing import Optional seen_messages set() cooldown_map {} def is_duplicate(message_id: str) - bool: if message_id in seen_messages: return True seen_messages.add(message_id) return False def in_cooldown(session_id: str, cooldown: int 20) - bool: now time.time() if now - cooldown_map.get(session_id, 0) cooldown: return True cooldown_map[session_id] now return False def handle_message(content: str, message_id: Optional[str] None, session_id: Optional[str] None, style: str neutral): if message_id and is_duplicate(message_id): return None if session_id and in_cooldown(session_id): return None if not content.strip(): return None # 这里接入你的大模型或策略返回回复文案 if style friendly: return f收到感谢你的留言。你说的是{content[:50]} return f你好我们已经收到消息稍后会有人跟进。这段代码有几点值得注意is_duplicate处理重复消息in_cooldown避免同一会话在短时间内被多次回复空内容直接不处理回复内容只取前 50 个字防止长文本撑爆输出。如果你只想本地测试可以把这个函数直接导入后跑几条消息观察返回值是否符合预期。如果能通过再接到 Hermes Agent 技能入口里。4.3 接入 Hermes Agent 的调用方式Hermes Agent 加载技能后通常可以通过对话触发。比如你在会话里写请调用 IM Auto Reply用 friendly 风格回复这条消息“你好请问还在吗”如果 Agent 没有自动调用先检查技能描述里是否有足够的触发词。不同客户端可能还支持通过斜杠命令手动触发但具体命令要看当前版本的实现。不要一上来就认定是 Agent 问题先确认技能文件和描述是否被正确加载。另外技能的执行入口要能接收参数。如果你的技能脚本没有定义参数接收函数Agent 即使描述了参数也传不进去。这是很常见的报错原因。解决方法是先固定入参、写一个最简单的返回值验证整个调用链再逐步增加逻辑。5. 参数、限频和稳定性从能跑到能批量5.1 并发、队列和冷却时间怎么设置能回复一条消息和能稳定回复一小时消息是完全两回事。很多人在本地测试时觉得速度很快一旦接上真实消息流就会出现重复、漏错、卡死。我建议先不要开并发。哪怕你的机器性能不错也先设置单条任务处理。消息同时到达时使用一个简单的 FIFO 队列让技能一条一条地消费。这样便于观察日志也方便定位问题。比较常见的参数表如下具体数值以你的场景为准参数建议值作用max_concurrency1同一时间只处理一条消息queue_size10 到 20超出队列的消息先丢弃或记录不阻塞主流程cooldown_seconds20 到 30同一会话的回复间隔retry_times2 到 3大模型调用失败后的重试次数timeout_seconds30网络请求超时时间不要一开始就把max_concurrency调到 5 或 10。并发高时如果模型接口没有限流保护很容易把 API 调用打满或者导致技能内部状态互相覆盖。先跑一段时间看日志再逐步增加并发。5.2 多账号和多会话的隔离原则如果你的目标是面对多个账号或多个会话最重要的原则是不能让不同会话的上下文混在一起。我见过有人用一个全局列表保存所有历史消息结果 A 用户发来的消息回复时却带着 B 用户的信息这在隐私上很严重。正确做法是每个会话用独立的缓存 Key比如account_1:session_123 account_1:session_456 account_2:session_789生成回复时只从当前 Key 对应的历史中读取上下文。如果有账号级别差异例如不同账号使用不同回复语气也要在参数里把account_id传进去而不是靠 Agent 猜测。多账号场景下日志里也一定要包含account_id和session_id。否则一旦出现问题你很难判断是哪条链路出了问题。5.3 从日志和监控判断技能是否稳定一个自动回复技能上线前至少要盯住这几项指标技能触发次数消息去重命中率大模型请求耗时和错误率回复发送成功率冷却期命中次数。日志格式不用太复杂只要能在每条记录里看到时间、会话 ID、消息 ID、处理结果即可。2025-06-01 10:00:01 | session_123 | msg_abc_001 | duplicate_skip 2025-06-01 10:00:05 | session_123 | msg_abc_002 | reply_generated 2025-06-01 10:00:06 | session_123 | msg_abc_002 | send_success当回复出现问题时不要急着修改提示词。先看日志确定是消息输入的问题、去重的问题还是发送接口的问题。很多“模型回复不好”的案例最终发现是上游传参时把字段拼错了。6. 陌陌场景的合规边界和替代方案6.1 平台接口、授权和自动化风险回到陌陌这个具体场景有一个现实问题这类社交平台不一定提供公开的自动回复 API。就算有也通常需要官方企业资质或授权而不是个人账号直接调用。如果你只在自己的测试账号、开发环境里跑通流程用来学习 Skills 和消息处理那是没问题的。但如果要在未经授权的情况下用非官方方式批量读取或自动回复真实用户消息就存在账号风控、隐私和合规风险。这类问题不是写一个更好的 Skill 就能解决的而是产品边界问题。所以这篇文章里的“自动回复”更适合理解成一个消息处理流程示例。具体能不能接到陌陌取决于平台规则和你的使用目的。如果只是个人学习建议使用一个允许自动化测试的开放平台来验证比如企业微信、Slack、Telegram Bot 或模拟消息服务。核心 Skills 逻辑基本可以复用。6.2 没有开放接口时可以做什么如果目标平台确实没有开放接口仍然有几个合规的替代方案。第一把消息数据导出到本地 CSV 或 JSON 文件中然后用 Hermes Agent 的 Skill 批量生成回复草稿。这种方式做不到实时但适合客服团队批量处理、内容创作、运营素材整理等场景。第二使用“人工复制进技能”的半自动模式。把收到的消息内容粘贴到 Agent 对话里由技能生成回复建议再手动粘贴回去发送。虽然没有全自动但比纯靠人写回复要快很多。第三在平台允许的范围内使用官方提供的消息接口。如果未来平台开放了相关能力你只需要改技能里的“发送模块”前面的过滤、去重、回复生成逻辑可以不动。6.3 技能加不进 Agent 时的排查链路最后总结一个排查顺序当你发现 Hermes Agent 一直没有调用你写的“陌陌回复信息”技能时按这个顺序看先确认技能目录被加载。启动日志里有没有技能名。再确认技能描述是否清楚。描述里有没有出现“回复”“消息”这些关键词。然后确认参数是否能正常传递。可以先在技能入口写死返回值测试调用链路。接着看技能执行是否报错。异常是否被捕获日志有没有输出。最后查权限、路径、API Key、依赖版本。实际上我发现大量技能不生效的问题不是 Agent 无法理解而是技能文件本身没有放到正确目录或者描述文件里没有写清楚触发条件。所以说先看加载再看描述再看日志不要一上来就怀疑模型能力。我个人更建议你把第一版技能做成“输入消息返回回复草稿”的纯文本能力先跑通 Hermes Agent 的 Skills 链路再慢慢往里面加发送动作、多账号隔离和批量队列。自动回复类技能真正难的不是大模型怎么生成一句漂亮话而是消息去重、冷却时间、限频、日志和合规边界这几件看起来不起眼的小事。把这几个点处理好换到任何 IM 平台都只是换个数据源的问题。