Hermes Skills 与 Plugins 深度对比

发布于 2026-05-13 17:38

Hermes Skills 与 Plugins 深度对比

一、概念定位

Hermes Skills 和 Hermes Plugins 都是 Hermes 的扩展机制，但定位和用途有本质区别：

特性 Skills Plugins
定义 本地的 SKILL.md 文件，包含工作流和最佳实践 第三方的 Python 插件，提供扩展功能
位置 ~/.hermes/skills/ ~/.hermes/plugins/plugin_name/plugin.py
加载方式 在会话中自动加载 需要通过 hermes plugins install 安装后生效
生效方式 即时生效 需要重启 gateway
作用 扩展 Hermes 的能力边界，提供新功能、新工具等

二、Skills 详解

2.1 Skills 的本质

Skills 是 Hermes 的内置知识库，是本地编写的 markdown 文件（包含 YAML frontmatter）。

核心特点：

  • 纯文本 markdown，易于编写和维护
  • 可包含工作流程、最佳实践、注意事项
  • 支持分类组织（category）
  • 自动加载，无需安装命令

2.2 Skills 的编写步骤

步骤 1：创建 SKILL.md

在 ~/.hermes/skills/ 目录下创建文件，文件名为 SKILL.md。

Skill 文件结构：

---
name: skill-name
description: "简短描述"
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  tags: [tag1, tag2]
  homepage: https://example.com
  related_skills: []
---

# Skill Name

## 前置条件
- condition1
- condition2

## 使用步骤
1. 步骤一：具体操作
2. 步骤二：具体操作
3. 步骤三：具体操作

## 注意事项
- 注意点1
- 注意点2

## 示例

```bash
# 示例命令
hermes command --option value

三、Hermes Plugins 架构设计

3.1 Plugins 的本质与设计理念

Plugins 是 Hermes 的第三方扩展机制，基于 Python 的插件系统。

架构设计原理：

┌─────────────────────────────────────────────────────────────────┐
│                   Hermes Gateway                   │
│                                                      │
│  ┌────────────┐         ┌──────────────┐       │
│  │  Config    │────────▶│  Plugin      │       │
│  │  Loader    │         │  Manager     │       │
│  └────────────┘         └──────────────┘       │
│         │                    │                    │
│         ▼                    ▼                    │
│  ┌─────────────────────────────────────────────┐           │
│  │  Plugin  │    register_plugin()      │           │
│  │  Instance│───────────────────────────────▶│  Tool    │
│  └─────────────────────────────────────┘           │
│         │                    │                    │           │
│         ▼                    ▼                    │
│    Tool Schema         Tool Handler          Result         │
│                                                      │
└─────────────────────────────────────────────────┘

核心组件：

  1. Plugin Manager - 管理所有已安装的 plugins
  2. Config Loader - 从 config.yaml 加载配置
  3. Plugin Instance - 每个 plugin 的运行实例
  4. Tool Registry - 注册工具函数到 Hermes 工具集

生命周期：

  • 安装：hermes plugins install <plugin_name>
  • 加载：Gateway 启动时读取配置
    注册插件：register_plugin() 函数被调用
  • 生效：工具函数加入工具注册表
  • 运行：Agent 可调用新工具

3.2 Plugin 接口设计

每个 plugin 必须实现 register_plugin() 函数，接口规范：

from hermes_tools import register_plugin
import json
import os

def check_requirements() -> bool:
    """检查环境依赖
    
    Returns:
        bool: 依赖是否满足
    """
    # 示例：检查 API 密钥、依赖包等
    api_key = os.environ.get("PPT_API_KEY")
    if not api_key:
        return False
    
    # 检查依赖包（可选）
    # import required_package
    return True

def my_handler(args: dict, **kwargs) -> dict:
    """工具处理函数
    
    Args:
        args: 工具参数
        **kwargs: 其他参数
        
    Returns:
        dict: 处理结果，格式：{"success": bool, "data": any}
    """
    # 实现具体功能逻辑
    result = process(args)
    return {"success": True, "data": result}

def register_plugin():
    """注册 plugin 到 Hermes"""
    register_plugin(
        name="my_plugin",
        toolset="my_toolset",
        schema={
            "name": "my_tool",
            "description": "工具描述",
            "parameters": {
                "type": "object",
                "properties": {
                    "param1": {"type": "string", "description": "参数1"},
                    "param2": {"type": "string", "description": "参数2"}
                }
            }
        },
        handler=my_handler,
        check_fn=check_requirements,
        requires_env=["API_KEY"]
    )

Schema 设计要点：

  • 遵循 OpenAI function calling 格式
  • name: 工具名称（字符串）
  • description: 工具描述（字符串）
  • parameters: JSON Schema 对象，定义参数结构

四、Plugins 编写实战

实战示例：HTML PPT 生成器

创建一个完整的 HTML PPT 生成 plugin。

步骤 1：创建目录结构

mkdir -p ~/.hermes/plugins/html_ppt_generator
cd ~/.hermes/plugins/html_ppt_generator

步骤 2：编写 plugin.py

from hermes_tools import register_plugin
import json
import os

def check_requirements() -> bool:
    """检查环境依赖"""
    # 检查必要的 API 密钥或配置
    api_key = os.environ.get("PPT_API_KEY")
    if not api_key:
        return False
    
    # 检查依赖包（可选）
    # import required_package
    return True

def generate_ppt_handler(args: dict, **kwargs) -> dict:
    """生成 HTML PPT 的处理函数
    
    Args:
        args: 包含 title, content, output_path 等参数
        
    Returns:
        dict: {"success": bool, "data": any, "error": str}
    """
    title = args.get("title", "未命名演示")
    content = args.get("content", "")
    output_path = args.get("output_path")
    
    # 生成 HTML 内容
    html = f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{title}</title>
    <style>
        body {{ font-family: Arial, sans-serif; margin: 40px; }}
        h1 {{ color: #2c3e50; }}
        .slide {{ margin: 20px 0; padding: 20px; background: #f4f4f4; }}
    </style>
</head>
<body>
    <h1>{title}</h1>
    <div class="slide">
        {content}
    </div>
</body>
</html>"""
    
    # 保存到文件（如果提供了 output_path）
    if output_path:
        try:
            with open(output_path, 'w', encoding='utf-8') as f:
                f.write(html)
            return {
                "success": True,
                "output_path": output_path,
                "title": title
            }
        except Exception as e:
            return {
                "success": False,
                "error": f"Failed to save file: {str(e)}"
            }
    
    return {
        "success": True,
        "data": {
            "html": html,
            "output_path": output_path,
            "title": title
        }
    }

def register_plugin():
    """注册 plugin plugin 到 Hermes"""
    register_plugin(
        name="html_ppt_generator",
        toolset="productivity",
        schema={
            "name": "generate_html_ppt",
            "description": "生成 HTML 格式的演示文稿",
            "parameters": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string",
                        "description": "演示文稿标题"
                    },
                    "content":": {
                        "type": "string",
                        "description": "演示文稿内容（支持 Markdown）"
                    },
                    "output_path": {
                        "type": "string",
                        "description": "输出文件路径（可选）"
                    }
                },
                "required": ["title", "content"]
            }
        },
        handler=generate_ppt_handler,
        check_fn=check_requirements,
        requires_env=["PPT_API_KEY"]
    )

步骤 3：配置生效

在 ~/.hermes/config.yaml 中启用：

plugins:
  html_ppt_generator:
    enabled: true
    # 可选配置
    api_key: ${PPT_API_KEY}
    default_style: professional

重启 gateway：

hermes gateway restart

步骤 4：验证安装

# 检查 plugin 是否正确安装
hermes plugins list

# 测试工具调用
hermes tools call generate_html_ppt \
    --title "我的演示" \
    --content "# 欢迎使用 Hermes\n\n这是一个强大的 AI Agent 框架。"

五、Skills vs Plugins 选择指南

何时使用 Skills：

  • ✅ 记录工作流程和最佳实践
  • ✅ 提供使用指南和注意事项
  • ✅ 内容适合用纯文本 markdown表达
  • ✅ 不需要编程实现
  • ✅ 快速迭代和修改

何时使用 Plugins：

  • ✅ 需要新的工具函数
  • ✅ 需要访问 Hermes 内部 API
  • ✅ 功能需要编程实现
  • ✅ 需要复杂的参数验证和处理逻辑

组合使用模式：

  • Skills 提供方法论，Plugins 提供具体实现
  • Skills 可以引用 Plugins 提供的工具完成复杂任务

六、常见问题

Q1: Skill 加载失败怎么办？

检查文件路径和名称：

hermes skills list
hermes skills view skill-name

Q2: Plugin 安装后不生效？

确认已完成以下步骤：

  1. 编辑 config.yaml 启用 plugin
  2. 重启 gateway
hermes gateway restart

Q3: 如何调试 Plugin？

查看 gateway 日志：

hermes logs gateway --tail

Q4: Plugin 之间有依赖怎么办？

在 register_plugin() 中按顺序注册：

def register_plugin():
    register_plugin(name="plugin_a", ...)
    register_plugin(name="plugin_b", ...)
← 返回博客列表
文章信息

标题: Hermes Skills 与 Plugins 深度对比

发布时间: 2026-05-13 17:38