Hermes Agent技能开发实战：用Skills机制实现自动回复

之前一个朋友在做一个 AI 助手类项目时，遇到一个很典型的问题：助手能聊、能查资料、能写代码，但没办法替他处理“每天会被问很多遍”的固定消息场景。比如陌陌上经常有人问“在吗”“做什么工作的”“能不能加微信”，每次都是同样的话术，手动回复又浪费时间，于是他开始研究 Hermes Agent 的 Skills 机制，想用一套“技能”把这类回复自动化。

这篇文章就是把那套思路完整整理出来：从 Hermes Agent 和 Skills 的概念讲起，到写一个“陌陌回复信息技能”的完整流程，再到常见报错排查和工程化建议。文章不会教你绕过任何平台限制，而是把“技能开发”这件事本身讲透，让你能迁移到微信、企业微信、短信、邮件等其它消息场景。

适用读者：正在用 Hermes Agent、Claude Code、Codex 等 Agent 工具做自动化的人，或者准备系统学习 Agent Skills 开发的开发者。

1. 为什么需要给 Hermes Agent 添加“陌陌回复”技能

1.1 先搞清楚 Hermes Agent 是什么

Hermes Agent 属于最近很热的一类“AI Agent”应用。你可以把它理解成一个跑在本地或服务器上的智能代理程序，它不只是简单聊天，而是能调用工具、读取文件、执行命令、完成多步任务。

比较常见的形态是终端助手，也就是你在命令行里输入自然语言请求，它帮你拆解任务、调用各种能力、最终给出结果。这类工具让“写一套固定逻辑”变成了“用自然语言发指令就能安排任务”。

不过在真实业务里，光有“能理解指令”还不够。不同用户有不同场景：有人要处理陌陌消息，有人要自动回复微信，有人要让 Agent 做周报。这些高度个性化的需求，不可能全部内置在 Agent 里，于是就需要一种“插件化”的能力，也就是本文要讲的 Skills。

1.2 Skills 机制解决了什么问题

Skills 在汉化语境里常被称为“技能”，可以理解为一组带描述、带参数、带执行逻辑的功能模块。给 Agent 安装一个 Skill 之后，它就知道在什么场景下调用这个技能、需要哪些输入、产出的结果是什么。

和普通脚本相比，Skills 有几个明显区别：

第一，Skills 带有机器可读的描述。Agent 会通过描述判断“这个技能适不适合当前任务”。第二，Skills 有参数约束。你想让技能回复什么、发给谁、用什么话术，都是通过参数传递，而不是把逻辑写死。第三，Skills 的加载和卸载是动态的，不改 Agent 主程序就能扩展功能。

所以，与其说 Skills 是“写了一个脚本”，不如说是在 Agent 上注册了一个“可被动态调用的能力”。

1.3 陌陌消息自动化回复的业务场景

以一个常见的个人使用场景为例：你平时会收到很多陌陌好友发来的招呼、提问、或者重复性咨询。如果每条都手动回复，一天会打断好几次工作节奏。

给 Hermes Agent 做一个“陌陌回复信息技能”之后，可以实现这些能力：

• 自动识别消息类型：问候、提问、广告、骚扰。
• 根据消息内容匹配预设话术，例如“在吗”回复“在的，有什么可以帮你”。
• 对包含敏感词或骚扰意图的消息，不回复或仅标记。
• 把无法自动处理的消息统一收集，延迟提醒人工处理。

这里要特别说明：个人消息自动回复和批量营销是完全不同的两件事。前者服务于“减少重复劳动”，后者属于平台高压线。本文所有示例都基于个人账号的辅助管理场景，绝对不涉及群发、骚扰、伪装等行为。

1.4 一个容易被忽视的边界：合规性

在开始之前，必须先强调合规问题。陌陌这类即时通讯软件，在用户协议里通常明确禁止使用非官方接口进行消息自动化。因此，接入前请务必确认：

• 你只对自己有权限管理的账号操作。
• 自动化逻辑不会绕过平台安全机制。
• 不影响正常用户，不构成骚扰。
• 本地测试时使用小号，避免影响真实社交关系。
• 接入通道必须遵守平台规则，法律风险由使用者自行评估。

即使是做技术研究，也建议先在小范围、测试账号上验证，不要把脚本直接跑在核心账号上。文章的核心是 Skill 开发工程方法，不是教你如何“破解”某个 App。所以后面的代码示例会把“消息获取”和“消息发送”这两层做成可替换的适配器，你只需要关注 Skill 本身的逻辑。

2. 环境准备与运行框架

2.1 运行环境说明

Hermes Agent 目前在不同系统上的安装方式有差异，本文不会替你把特定版本的安装命令写死，因为社区版本更新比较快。更推荐的做法是：先根据官方文档把 Agent 本体装好，再做 Skills 开发。

一个常见的最小环境是这样：

• 操作系统：macOS 或 Linux 均可，社区反馈 mac 上跑 Hermes Agent 的案例比较多。
• 运行时：Python 3.10 或更高版本，Node.js 看项目需要。
• Agent 主体：Hermes Agent（以你从官方渠道获取的版本为准）。
• 代码编辑器：VS Code 或任意支持 Python 的编辑器。

如果你在安装 Agent 本体时遇到需要登录、需要配置 API Key 等情况，属于正常现象。这类 Agent 通常需要调用大模型接口，所以需要准备模型服务的 API Key，配置方法在官方 README 里一般都写得很清楚。

2.2 工具链准备

除了 Agent 本体，建议准备以下工具：

• Git：拉取 Skills 示例仓库或管理自己的技能代码。
• Python 虚拟环境：避免依赖冲突。
• HTTP 调试工具（如 curl、Postman），如果 Skill 里要请求模型服务或外部 API。
• 日志查看工具，终端本身即可。

本文示例代码以 Python 为主，因为这个生态处理文本规则、消息队列、HTTP 请求都比较方便。

2.3 项目目录设计

一个规范的 Skills 项目，建议这样组织目录：

hermes-skills/ ├── skills/ │ └── momo-reply/ │ ├── SKILL.md │ ├── skill.py │ ├── config.yaml │ └── rules/ │ └── reply_rules.json ├── logs/ └── tests/ └── test_reply_rules.py

简单说明每个文件的作用：

• SKILL.md：技能描述文件，给 Agent 看的“说明书”。
• skill.py：技能核心逻辑。
• config.yaml：配置参数，包括回复开关、冷却时间、关键词文件路径等。
• reply_rules.json：消息匹配规则和回复话术。
• tests/：自动化测试，用来保证改规则时不破坏原有功能。

下面会按照这个目录结构逐步实现。

3. Hermes Agent 与 Skills 机制拆解

3.1 Skills 是什么，和普通脚本有什么区别

可以把 Skills 理解成给 Agent 准备的“能力卡片”。每张卡片包含两部分：描述和实现。描述部分告诉 Agent“这个技能能做什么、什么时候用”，实现部分告诉 Agent“具体怎么做”。

举一个很简单的比喻：普通脚本就像一台没有说明书的外设，只有你自己知道怎么用；Skill 则像一台带标准说明书的设备，任何会读说明书的 Agent 都能接上。

因此，写 Skill 的第一个重点是写清楚描述，而不是只写代码。

3.2 Skill 文件的标准结构

大多数 Agent 框架对 Skill 有一个约定：使用一个SKILL.md文件来描述技能元信息，再通过引用文件路径或函数名来加载实现。

下面给出一个通用的SKILL.md示例，它不是一个特定框架的严格模板，但思路是通用的：

--- name: momo-reply description: 自动处理陌陌消息回复。当收到重复性提问、常见问候时，根据规则匹配并返回回复内容。 version: 1.0.0 author: your-name license: MIT parameters: - name: message type: string required: true description: 收到的原始消息文本 - name: session_id type: string required: false description: 会话标识，用于上下文去重和冷却判断 entrypoint: skill.py ---

这段 YAML 格式的元信息里：

• name：技能名称，Agent 用它来识别技能。
• description：极其重要。Agent 判断是否调用这个技能，主要靠这段描述。
• parameters：声明调用技能时需要传入哪些参数，有没有默认值。
• entrypoint：指明实现入口文件。

写描述时，不要写“这是一个关于消息回复的技能”，而要写清“在什么场景下、收到什么输入、输出什么结果”。例如：

description: 当用户收到陌陌好友发来的问候、常见提问或重复咨询时，根据预设话术生成自动回复内容。

这样的描述，Agent 在决策时更容易命中。

3.3 Agent 如何调度一个 Skill

Agent 调用 Skill 的过程，大致可以拆成四步：

1. Agent 接收用户的一条指令。
2. Agent 根据指令语义，结合 Skill 的description，决定要不要调用这个技能。
3. 如果决定调用，Agent 会按照parameters的定义提取必要信息。
4. Agent 执行entrypoint里的逻辑，拿到返回结果，再组织成自然语言回复给用户。

也就是说，写 Skill 时你不一定“亲自触发逻辑”，而是要确保 Agent 能正确识别“什么时候该用它”。这也就是为什么描述写得越精确，Skill 使用率越高。

3.4 对外挂知识库和 API Key 的理解

从最近社区讨论的热词来看，很多人还在研究“外挂知识库”和“修改 API Key”。这两个其实都属于 Agent 的扩展能力：

• 外挂知识库：把业务资料放在本地或向量数据库里，Agent 在回答时先检索再组织答案。写 Skills 时，如果你的回复规则比较复杂，也可以把规则文件放在知识库目录中，让 Skill 动态读取。
• API Key：Agent 调用大模型或第三方服务时需要的身份凭证。修改方式一般在配置文件中，而不是在 Skill 里写死。

在下面的实战案例里，我们会把回复话术放在独立 JSON 文件中，而不是硬编码在 Python 代码里，这样后续调整话术不需要改代码，对新手更友好，也方便 Agent 在运行时读取外部配置。

4. 完整实战：开发一个陌陌自动回复 Skill

4.1 需求拆分

先别急着写代码。我们把需求拆成几个明确的功能点：

1. 接收一条消息文本。
2. 判断消息类型：问候、咨询、广告、骚扰、其他。
3. 根据类型匹配回复话术。
4. 对广告和骚扰消息不做回复，只返回一个标记。
5. 记录处理日志，方便事后查看。
6. 提供一个模拟入口，可以在命令行里输入消息，观察输出结果。

整个 Skill 保持“规则驱动”，不依赖大模型处理每一条消息，这样速度快、成本低，也更稳定。只有遇到无法匹配的消息时，才可选的交给模型生成回复。

4.2 自动回复策略设计

在设计回复策略时，要注意几点：

• 对“在吗”“你好”这类高频问候，统一走“自然问候”规则。
• 对“做什么的”“多大年龄”这类隐私问题，策略上不直接回答，话术可以设置为“关于我可以在合适的时候聊聊，先说说你吧”。
• 对广告、赌博、诈骗等敏感词，直接走“不回复”分支，并记录风险。
• 对同一会话短时间内的重复消息，要触发冷却机制，避免被误判为机器循环响应。

策略上要优先保证“不打扰”和“不违法”，其次才是“回复得好”。

4.3 编写 Skill 定义文件

先创建项目目录：

mkdir -p hermes-skills/skills/momo-reply cd hermes-skills/skills/momo-reply

然后创建SKILL.md：

--- name: momo-reply description: 用于处理陌陌消息的自动回复。当收到常见问候、重复提问、咨询类消息时，按预设规则返回回复内容；对广告、骚扰消息不回复。 version: 1.0.0 author: your-name parameters: - name: message type: string required: true description: 收到的原始消息文本 - name: session_id type: string required: false description: 会话标识，用于冷却和去重判断 entrypoint: skill.py ---

接下来创建config.yaml：

# 文件路径：hermes-skills/skills/momo-reply/config.yaml reply_enabled: true # 总开关，false 时技能不产生任何回复 cooling_seconds: 30 # 同一会话冷却时间 max_reply_length: 200 # 回复内容最大长度 risk_action: "ignore" # 风险消息动作：ignore / log / review rules_file: "./rules/reply_rules.json"

这里的cooling_seconds很重要，它可以防止同一个会话里短时间收到大量消息时，技能每次都去回复，造成过度响应。

4.4 编写核心逻辑代码

下面编写skill.py。这里先给一个不依赖任何特定 Agent SDK 的版本，方便你理解核心流程。

# 文件路径：hermes-skills/skills/momo-reply/skill.py import json import time import re from pathlib import Path class MomoReplySkill: def __init__(self, config_path: str = "./config.yaml", rules_path: str = "./rules/reply_rules.json"): self.config = self._load_config(config_path) self.rules = self._load_rules(rules_path) self._last_reply_time: dict[str, float] = {} def _load_config(self, path: str): try: import yaml with open(path, "r", encoding="utf-8") as f: return yaml.safe_load(f) except Exception: return {"reply_enabled": True, "cooling_seconds": 30} def _load_rules(self, path: str): with open(path, "r", encoding="utf-8") as f: return json.load(f) def _classify(self, message: str) -> str: """根据规则文件将消息分类""" for rule in self.rules["rules"]: for keyword in rule["keywords"]: if keyword in message: return rule["type"] return "other" def _respect_cooling(self, session_id: str) -> bool: """判断是否处于冷却期""" now = time.time() last = self._last_reply_time.get(session_id, 0) if now - last < self.config.get("cooling_seconds", 30): return False self._last_reply_time[session_id] = now return True def handle(self, message: str, session_id: str = "default") -> dict: if not self.config.get("reply_enabled", True): return {"should_reply": False, "reason": "reply_disabled"} if not self._respect_cooling(session_id): return {"should_reply": False, "reason": "cooling"} msg_type = self._classify(message) if msg_type == "risk": return {"should_reply": False, "reason": "risk_message"} reply = self._get_reply_by_type(msg_type) return { "should_reply": True, "message_type": msg_type, "reply": reply, } def _get_reply_by_type(self, msg_type: str) -> str: for rule in self.rules["rules"]: if rule["type"] == msg_type: replies = rule.get("replies", []) if replies: return replies[0] return "你好，收到你的消息了。" if __name__ == "__main__": skill = MomoReplySkill() while True: text = input("请输入消息（输入 q 退出）：") if text.lower() == "q": break result = skill.handle(text, session_id="test") print(json.dumps(result, ensure_ascii=False, indent=2))

这段代码的职责很清晰：

• _load_config读取 yaml 配置。
• _load_rules读取 JSON 规则。
• _classify根据关键词对消息分类。
• _respect_cooling实现冷却机制。
• handle是外部调用的入口，Agent 会调用这个方法。

4.5 消息发送适配层

上面的skill.py只负责“生成回复内容”，不负责“把消息真正发出去”。这么设计是有意的。因为陌陌没有开放公共的开发者 API，不同接入方式差异很大，而且存在合规风险。所以更稳妥的做法是：把发送逻辑独立成适配层，由你自己选择一个合法、可控的通道。

下面是一个发送适配器的接口示例：

# 文件路径：hermes-skills/skills/momo-reply/sender.py from abc import ABC, abstractmethod class MessageSender(ABC): """消息发送适配器接口。请根据你实际可用的通道实现。""" @abstractmethod def send(self, session_id: str, content: str) -> bool: """发送消息到指定会话""" @abstractmethod def receive(self, session_id: str) -> str: """从指定会话接收最新消息"""

比如你有一个内部桥接服务，可以通过 HTTP 接口接收和发送消息，那么可以这样做：

# 文件路径：hermes-skills/skills/momo-reply/sender.py import requests class HttpSender(MessageSender): def __init__(self, base_url: str, token: str): self.base_url = base_url self.token = token def send(self, session_id: str, content: str) -> bool: resp = requests.post( f"{self.base_url}/send", json={"session_id": session_id, "content": content}, headers={"Authorization": f"Bearer {self.token}"}, timeout=5, ) return resp.status_code == 200 def receive(self, session_id: str) -> str: resp = requests.get( f"{self.base_url}/receive", params={"session_id": session_id}, headers={"Authorization": f"Bearer {self.token}"}, timeout=5, ) return resp.json().get("message", "")

注意：这里的HttpSender只是演示适配器模式，不是让你去搭一个“绕过陌陌协议”的服务。实际项目中，请使用“用户自己可控且合规”的消息通道。

4.6 将 Skill 注册到 Hermes Agent

Skill 开发完成后，如何让 Hermes Agent 加载它？

不同版本的 Agent 加载方式不一样，常见做法有两种：

• 把整个momo-reply目录放进 Agent 的skills目录，Agent 启动时扫描目录并读取SKILL.md。
• 在 Agent 配置文件中声明技能路径，例如：

# 示例配置片段，具体字段以你的 Agent 版本为准 skills: - path: "./skills/momo-reply" enabled: true

建议先把核心逻辑用一个main()入口封装好，再根据实际 Agent 框架的扩展点接入。例如，如果 Hermes Agent 允许自定义工具函数，那么只需要在对应位置 importMomoReplySkill，然后调用handle()方法即可。

为了让 Agent 能在拿到回复后继续对话，handle()返回结构化结果比返回纯文本更友好：

# 示例：把结果转为 Agent 可读字符串 def format_result(result: dict) -> str: if result["should_reply"]: return f"建议回复：{result['reply']}" return f"不回复，原因：{result['reason']}"

5. 运行与验证

5.1 本地启动

先安装依赖：

cd hermes-skills python -m venv .venv source .venv/bin/activate pip install pyyaml requests

然后运行模块：

python skills/momo-reply/skill.py

运行时你会进入一个交互式命令行，可以输入消息来观察分类和回复结果。

5.2 功能验证流程

设计一组测试输入，覆盖每个分支：

用q退出测试。

还可以把测试写进脚本，方便回归：

# 文件路径：hermes-skills/tests/test_reply_rules.py from skills.momo_reply.skill import MomoReplySkill def test_risk_message_not_reply(): skill = MomoReplySkill() result = skill.handle("免费领取红包", session_id="test1") assert result["should_reply"] is False assert result["reason"] == "risk_message" def test_greeting_reply_exists(): skill = MomoReplySkill() result = skill.handle("在吗", session_id="test2") assert result["should_reply"] is True assert len(result["reply"]) > 0 if __name__ == "__main__": test_risk_message_not_reply() test_greeting_reply_exists() print("所有测试通过")

5.3 日志与告警

自动回复最怕“机器失控”。所以 Skill 每次处理消息，都应该记录结构化日志，至少要包含：

• 时间戳
• 会话 ID
• 原始消息
• 分类结果
• 是否回复
• 回复内容

建议使用 Python 自带的logging模块，输出到文件：

# 文件路径：hermes-skills/skills/momo-reply/skill.py import logging logging.basicConfig( filename="logs/momo_reply.log", level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s", ) # 在 handle() 中记录日志 def handle(self, message: str, session_id: str = "default") -> dict: result = self._process(message, session_id) logging.info( "session=%s message=%s result=%s", session_id, message, json.dumps(result, ensure_ascii=False) ) return result

如果长时间没有日志产生，说明消息接收链路可能断了，这种告警可以交给外部监控。

6. 常见问题与排查思路

无论是自己开发，还是在社区里看别人的踩坑记录，下面几个问题出现的频率最高。

7. 最佳实践与工程建议

7.1 规则优先于全量 AI 接管

在消息回复场景下，规则匹配的优势是快、可控、零成本。AI 生成回复的优势是灵活，但有延迟和不确定性。最佳实践是“规则优先，AI 兜底”：

• 高频简单消息走规则匹配。
• 只有规则没覆盖、且你判断需要回复的消息，才交给大模型生成候选回复。
• 模型生成的回复最好经过人工审核，或者加上明显的“自动回复”标识。

这样可以避免出现不可控的回复内容，也方便事后追责和调整。

7.2 频率控制与冷却机制

这是最容易踩坑的地方。自动回复不是越快越好，频率过高会导致：

• 被平台判定为营销机器人。
• 在真实社交关系里显得很突兀。
• 一旦循环触发，可能在短时间内产生大量消息。

因此，冷却机制必须有，而且建议设置为“同一会话 30 秒到 5 分钟不等”。如果消息量很大，还可以引入全局限速，比如“每分钟最多处理 10 条消息”。

7.3 敏感信息与隐私安全

消息自动回复会接触到大量的隐私内容。开发时要注意：

• 不要把原始消息日志长期明文保存。
• 日志中不要打印完整的手机号、微信号等敏感信息。
• 配置文件和 API Key 不要提交到 Git 仓库，使用环境变量注入。
• 如果消息内容包含收货地址、身份证号等信息，应立即停止自动回复，转入人工处理。

实用做法是：把日志写入带权限控制的目录，并定期清理。

7.4 消息幂等与去重

接收消息时，同一个会话可能因为网络重试导致同一条消息被处理两次。建议在 Skill 中维护一个message_id去重集合，用消息的唯一 ID 做幂等判断：

# 伪代码示例：消息去重 seen_ids = set() def handle_message(message_id: str, message: str, session_id: str): if message_id in seen_ids: return {"should_reply": False, "reason": "duplicate"} seen_ids.add(message_id) # 继续处理

不过要注意，内存去重在进程重启后会丢失。如果对可靠性要求高，可以把seen_ids持久化到 SQLite 或 Redis。

7.5 便于维护的设计

一句话总结：把“决策逻辑”和“话术内容”分离。

• 关键词、话术放 JSON 文件。
• 流程控制放 Python 代码。
• 发送通道走适配器接口。
• 配置参数放 YAML。

这样改话术不用改代码，换发送通道不影响核心逻辑，测试也更容易。

8. 总结与学习路线

这篇教程围绕“Hermes Agent Skills 开发”和“陌陌自动回复”两个主题，完整拆解了一个 Skill 从设计、编码、运行到排错的全过程。

核心掌握点可以总结为四个：

• Skills 本质上是给 Agent 提供“带描述的能力模块”，描述写得好，Skill 才会被正确调用。
• 自动回复逻辑推荐“规则优先、AI 兜底”，不要一上来就让大模型接管所有消息。
• 无论接哪个消息平台，都必须做频率控制、冷却、去重、日志和风险过滤。
• 发送通道要解耦成适配器，既为了合规，也为了以后能迁移到微信、企业微信、短信等其它场景。

如果你之前完全没接触过 Agent 开发，下一步可以继续研究：

• 如何用 Hermes Agent 连接不同的大模型 API。
• 如何给 Agent 挂载本地知识库，让回复更贴合业务。
• 如何把 Skill 发布成可分享的模块，让团队其他人也能直接安装使用。

如果你的 Skills 已经能稳定处理消息，建议接着做两件事：一是给日志加一个简单的统计面板，看看哪些话术命中率高、哪些场景被误判；二是写一套更完整的离线测试用例，防止改规则时把原有的行为改坏。

工具会一直更新，但“把能力抽象成技能、把流程拆成可替换模块”这套开发思路是通用的。先用小场景跑通一条链路，再逐步放大，比一开始就想做一个大而全的自动化系统要靠谱得多。

如果你在配置中文路径、规则匹配或者 Agent 加载时遇到奇怪问题，可以把具体报错和目录结构发出来一起讨论。