第十二章

如何扩展 Hermes-Agent

🎧 语音播放

从阅读者到贡献者的实战指南

🎯 本章目标

掌握扩展 Hermes 的常见模式
能够添加自定义工具
理解如何贡献代码

📚 前置知识

前十一章的所有内容

💡 学完收获

具备二次开发能力
知道如何提交 PR

12.1 扩展方式总览

Hermes-Agent 支持多种扩展方式，按难度排序：

方式	难度	适用场景	需要编程
创建 Skill	⭐ 简单	复用 Prompt 工作流	否
MCP 集成	⭐ 简单	接入外部服务	一点点
添加工具	⭐⭐ 中等	新增功能	是
接入平台	⭐⭐⭐ 中等	新消息渠道	是
修改核心	⭐⭐⭐⭐ 复杂	架构调整	是

12.2 方式一：创建 Skill

Skill 是一种零代码的扩展方式，只需要写 Markdown：

📚 创建步骤

在 ~/.hermes/skills/ 创建目录
添加 SKILL.md 文件
编写技能描述和使用说明
重启 Hermes，技能自动加载

~/.hermes/skills/my-skill/SKILL.md

---
name: my-skill
description: 做某事的技能
---

# My Skill

当你需要完成 X 任务时，使用这个技能。

## 步骤

1. 第一步
2. 第二步
3. 第三步

## 示例

输入：... → 输出：...

12.3 方式二：MCP 集成

如果已有 MCP 服务器，可以直接接入：

🔌 MCP (Model Context Protocol)

MCP 是一个开放协议，允许 AI 应用连接外部工具和服务。Hermes 内置了 MCP 客户端支持。

~/.hermes/config.yaml

mcp:
  servers:
    my-server:
      command: npx
      args: ["-y", "@my/mcp-server"]

12.4 方式三：添加工具

最常见的扩展方式。完整步骤：

创建文件

tools/my_tool.py

定义 Schema

描述工具接口

registry.register()

完成

Agent 即可使用

Step 1: 创建工具文件

tools/my_tool.py

import registry

def my_tool(arg1: str, arg2: int = 10) -> str:
    """我的自定义工具"""
    return f"结果: {arg1}, {arg2}"

SCHEMA = {
    "name": "my_tool",
    "description": "我的工具描述",
    "parameters": {
        "type": "object",
        "properties": {
            "arg1": {"type": "string", "description": "参数1"},
            "arg2": {"type": "integer", "description": "参数2"}
        },
        "required": ["arg1"]
    }
}

registry.register(
    name="my_tool",
    toolset="my_tools",
    schema=SCHEMA,
    handler=my_tool
)

Step 2: 注册到发现列表

model_tools.py

_modules = [
    ...
    "tools.my_tool",  # 新增
]

12.5 方式四：接入新消息平台

以添加"企业微信"为例，使用适配器模式：

1 创建适配器

gateway/platforms/wecom.py

2 注册平台

gateway/run.py

gateway/platforms/wecom.py

from .base import PlatformAdapter

class WeComAdapter(PlatformAdapter):
    platform_name = "wecom"
    
    async def handle_message(self, event):
        text = event.text
        await self.send_to_agent(text)
    
    async def send_response(self, text):
        await self.wecom_api.send_message(text)

12.6 代码贡献指南

如果你想贡献代码到 Hermes-Agent：

Fork

Fork 仓库

Clone

克隆到本地

开发

功能分支开发

测试

pytest 测试

提交 Pull Request

12.7 开发环境

Terminal

# 克隆
git clone https://github.com/YOUR_NAME/hermes-agent.git
cd hermes-agent

# 安装
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"

# 测试
pytest tests/ -q