构建一个 Hermes 插件

本指南将引导你从零开始创建一个功能完整、可扩展的 Hermes 插件，涵盖核心组件：工具（Tools）、钩子（Hooks）、数据文件（Data Files）和技能（Skills）。适用于开发者、AI 工程师或自动化架构师。

🧩 一、项目结构概览

首先，创建你的插件目录结构：

hermes-plugin-myplugin/
├── plugin.json                  # 插件元信息配置
├── tools/                       # 自定义工具目录
│   ├── fetch_weather.js         # 示例：获取天气的工具
│   └── send_email.js            # 示例：发送邮件的工具
├── hooks/                       # 钩子脚本（事件触发逻辑）
│   ├── on_message_received.js
│   └── on_plugin_loaded.js
├── data/                        # 数据文件（JSON/YAML/CSV）
│   ├── cities.json              # 城市列表
│   └── templates.yaml           # 消息模板
├── skills/                      # AI 技能定义（LLM 调用策略）
│   ├── weather_skill.md         # 天气查询技能描述
│   └── email_skill.md
├── README.md                    # 插件说明文档
└── package.json                 # Node.js 包依赖管理

✅ 提示：所有路径均为相对路径，Hermes 会自动扫描 plugins/ 目录下的子文件夹。

🔧 二、配置 `plugin.json` —— 插件元信息

这是每个 Hermes 插件的“身份证”，必须包含以下字段：

{
  "name": "myplugin",
  "version": "1.0.0",
  "title": "我的第一个 Hermes 插件",
  "description": "一个集成了天气查询与邮件发送功能的实用工具包。",
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "axios": "^1.6.0"
  },
  "main": "index.js",             // 可选：主入口文件
  "tools": [
    "tools/fetch_weather.js",
    "tools/send_email.js"
  ],
  "hooks": [
    "hooks/on_message_received.js",
    "hooks/on_plugin_loaded.js"
  ],
  "skills": [
    "skills/weather_skill.md",
    "skills/email_skill.md"
  ],
  "data": [
    "data/cities.json",
    "data/templates.yaml"
  ]
}

⚠️ 注意：

tools 和 hooks 必须是相对于插件根目录的路径。

skills 文件应为 Markdown 格式，用于描述技能意图与上下文。

data 支持 JSON、YAML、CSV 等格式。

🛠️ 三、编写自定义工具（Tools）

示例：`tools/fetch_weather.js`

// 功能：调用 OpenWeatherMap API 获取实时天气
const axios = require('axios');

module.exports = {
  name: 'fetch_weather',
  description: '根据城市名称获取当前天气状况',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: '城市名称，如 "Beijing"' }
    },
    required: ['city']
  },
  execute: async (args) => {
    const { city } = args;
    const apiKey = process.env.OPENWEATHER_API_KEY;
    const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`;

    try {
      const response = await axios.get(url);
      const data = response.data;

      return {
        success: true,
        result: {
          city: data.name,
          temp: data.main.temp,
          condition: data.weather[0].main,
          humidity: data.main.humidity
        }
      };
    } catch (error) {
      return {
        success: false,
        error: `无法获取天气数据: ${error.message}`
      };
    }
  }
};

💡 提示：工具需导出一个对象，包含 name, description, parameters, execute 四个字段。

📌 四、添加钩子（Hooks）—— 响应事件

示例：`hooks/on_message_received.js`

// 当用户发送消息时触发
module.exports = async (context) => {
  const { message, sender, plugin } = context;

  // 判断是否包含关键词
  if (message.toLowerCase().includes('天气')) {
    const tool = plugin.getTool('fetch_weather');
    const result = await tool.execute({ city: 'Shanghai' });

    if (result.success) {
      const reply = `📍 上海当前天气：${result.result.temp}°C，${result.result.condition}，湿度 ${result.result.humidity}%`;
      plugin.sendMessage(reply, sender.id);
    } else {
      plugin.sendMessage(`❌ 获取天气失败：${result.error}`, sender.id);
    }
  }

  // 可继续添加更多条件判断...
};

🔄 钩子支持多种事件类型：

on_message_received

on_plugin_loaded

on_user_joined

on_error_occurred

🗂️ 五、管理数据文件（Data Files）

示例：`data/cities.json`

[
  "Beijing",
  "Shanghai",
  "Guangzhou",
  "Shenzhen",
  "Hangzhou",
  "Chengdu"
]

示例：`data/templates.yaml`

greeting:
  welcome: "你好，欢迎使用 {{plugin_name}}！"
  farewell: "再见，祝你有美好的一天！"

weather_report:
  title: "🌤️ 天气报告"
  template: "{{city}} 当前温度为 {{temp}}°C，天气状况：{{condition}}"

✅ 在代码中可通过 require() 或 fs.readFileSync() 加载这些文件。

🎯 六、定义技能（Skills）—— 让 AI 理解如何使用工具

示例：`skills/weather_skill.md`

# 天气查询技能

## 意图识别
- 用户询问“今天天气怎么样？”
- 用户问“北京天气如何？”
- 用户说“帮我查一下上海的气温”

## 使用工具
- 工具名：`fetch_weather`
- 参数：`city`（必填），例如 `Beijing`、`Shanghai`

## 上下文提示
- 若用户未指定城市，默认使用最近一次提到的城市或默认城市（如 Shanghai）
- 若城市不存在于本地数据列表中，应提示：“抱歉，暂不支持该城市。”

## 输出格式
- 返回结构化结果，包括：城市、温度、天气状况、湿度
- 以自然语言回复，如：“上海当前气温 23°C，晴朗，湿度 50%。”

## 错误处理
- 若 API 调用失败，返回：“很抱歉，暂时无法获取天气信息，请稍后再试。”

📌 技能文件是 LLM 的“操作手册”，帮助模型理解何时调用哪个工具、如何构造参数。

📦 七、安装依赖并测试

在插件根目录运行：

npm install

确保 package.json 中声明了所需依赖（如 axios、dotenv 等）。

测试插件

启动 Hermes 主机（或通过 CLI 运行）：

npx hermes start --plugin ./hermes-plugin-myplugin

然后在聊天界面输入：

今天北京天气怎么样？

你应该看到类似输出：

北京当前气温 18°C，多云，湿度 65%。

🚀 八、发布与部署建议

发布到 Hermes 生态

将插件打包为 .zip 文件（保留目录结构）
提交至 agentskills.io 或官方插件市场
添加标签：#tool, #weather, #email, #automation

部署到生产环境

使用 Docker 容器化部署：

FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

配置环境变量（.env）：

OPENWEATHER_API_KEY=your_api_key_here
TELEGRAM_BOT_TOKEN=your_bot_token

✅ 总结：关键要点回顾

组件	必须项	推荐实践
`plugin.json`	`name`, `version`, `tools`, `skills`	使用语义化命名，版本号遵循 `MAJOR.MINOR.PATCH`
工具（Tools）	`execute` 函数返回 `{success, result}`	添加错误处理与日志
钩子（Hooks）	事件监听函数	使用 `plugin.sendMessage()` 回复用户
数据文件	放入 `data/` 目录	使用 JSON/YAML/CSV，避免硬编码
技能（Skills）	明确意图 + 工具映射	用 Markdown 写清晰指令

📚 扩展阅读

🎉 现在你已掌握构建完整 Hermes 插件的全部流程！
立即动手创建属于你的智能助手吧！

🌟 你的下一个插件可能是下一个爆款！
分享给社区，让世界更聪明。"

构建一个 Hermes 插件

本指南将带你从零开始构建一个完整的 Hermes 插件。完成之后，你将拥有一款功能齐全的插件，包含多个工具、生命周期钩子、随附的数据文件以及一个打包好的技能 —— 全面涵盖插件系统支持的所有特性。

你要构建的内容

一个名为 计算器 的插件，包含两个工具：

calculate —— 计算数学表达式（支持 +、-、*、/ 等运算）
unit_convert —— 单位转换（支持长度、重量、温度等单位）

此外还包括：

一个记录每次工具调用的日志钩子
一个打包好的技能文件

第一步：创建插件目录

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

第二步：编写清单文件

创建 plugin.yaml：

name: calculator
version: 1.0.0
description: Math calculator — evaluate expressions and convert units
provides_tools:
  - calculate
  - unit_convert
provides_hooks:
  - post_tool_call

这告诉 Hermes：“我是一个名为 calculator 的插件，提供工具和钩子。” tools 和 hooks 字段列出了该插件注册的内容。

可选字段（你可以添加）：

author: Your Name
requires_env:          # gate loading on env vars; prompted during install
  - SOME_API_KEY       # simple format — plugin disabled if missing
  - name: OTHER_KEY    # rich format — shows description/url during install
    description: "Key for the Other service"
    url: "https://other.com/keys"
    secret: true

第三步：编写工具 Schema

创建 schemas.py —— 这是 LLM 用来判断何时调用你的工具的依据：

"""Tool schemas — what the LLM sees."""

CALCULATE = {
    "name": "calculate",
    "description": (
        "Evaluate a mathematical expression and return the result. "
        "Supports arithmetic (+, -, *, /, **), functions (sqrt, sin, cos, "
        "log, abs, round, floor, ceil), and constants (pi, e). "
        "Use this for any math the user asks about."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Math expression to evaluate (e.g., '2**10', 'sqrt(144)')",
            },
        },
        "required": ["expression"],
    },
}

UNIT_CONVERT = {
    "name": "unit_convert",
    "description": (
        "Convert a value between units. Supports length (m, km, mi, ft, in), "
        "weight (kg, lb, oz, g), temperature (C, F, K), data (B, KB, MB, GB, TB), "
        "and time (s, min, hr, day)."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "value": {
                "type": "number",
                "description": "The numeric value to convert",
            },
            "from_unit": {
                "type": "string",
                "description": "Source unit (e.g., 'km', 'lb', 'F', 'GB')",
            },
            "to_unit": {
                "type": "string",
                "description": "Target unit (e.g., 'mi', 'kg', 'C', 'MB')",
            },
        },
        "required": ["value", "from_unit", "to_unit"],
    },
}

为什么 Schema 很重要？
description 字段决定了 LLM 在什么情况下使用你的工具。请尽可能具体地描述其功能和适用场景。parameters 定义了 LLM 会传入的参数。

第四步：编写工具处理器

创建 tools.py —— 这是当 LLM 调用你的工具时实际执行的代码：

"""Tool handlers — the code that runs when the LLM calls each tool."""

import json
import math

# Safe globals for expression evaluation — no file/network access
_SAFE_MATH = {
    "abs": abs, "round": round, "min": min, "max": max,
    "pow": pow, "sqrt": math.sqrt, "sin": math.sin, "cos": math.cos,
    "tan": math.tan, "log": math.log, "log2": math.log2, "log10": math.log10,
    "floor": math.floor, "ceil": math.ceil,
    "pi": math.pi, "e": math.e,
    "factorial": math.factorial,
}


def calculate(args: dict, **kwargs) -> str:
    """Evaluate a math expression safely.

    Rules for handlers:
    1. Receive args (dict) — the parameters the LLM passed
    2. Do the work
    3. Return a JSON string — ALWAYS, even on error
    4. Accept **kwargs for forward compatibility
    """
    expression = args.get("expression", "").strip()
    if not expression:
        return json.dumps({"error": "No expression provided"})

    try:
        result = eval(expression, {"__builtins__": {}}, _SAFE_MATH)
        return json.dumps({"expression": expression, "result": result})
    except ZeroDivisionError:
        return json.dumps({"expression": expression, "error": "Division by zero"})
    except Exception as e:
        return json.dumps({"expression": expression, "error": f"Invalid: {e}"})


# Conversion tables — values are in base units
_LENGTH = {"m": 1, "km": 1000, "mi": 1609.34, "ft": 0.3048, "in": 0.0254, "cm": 0.01}
_WEIGHT = {"kg": 1, "g": 0.001, "lb": 0.453592, "oz": 0.0283495}
_DATA = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
_TIME = {"s": 1, "ms": 0.001, "min": 60, "hr": 3600, "day": 86400}


def _convert_temp(value, from_u, to_u):
    # Normalize to Celsius
    c = {"F": (value - 32) * 5/9, "K": value - 273.15}.get(from_u, value)
    # Convert to target
    return {"F": c * 9/5 + 32, "K": c + 273.15}.get(to_u, c)


def unit_convert(args: dict, **kwargs) -> str:
    """Convert between units."""
    value = args.get("value")
    from_unit = args.get("from_unit", "").strip()
    to_unit = args.get("to_unit", "").strip()

    if value is None or not from_unit or not to_unit:
        return json.dumps({"error": "Need value, from_unit, and to_unit"})

    try:
        # Temperature
        if from_unit.upper() in {"C","F","K"} and to_unit.upper() in {"C","F","K"}:
            result = _convert_temp(float(value), from_unit.upper(), to_unit.upper())
            return json.dumps({"input": f"{value} {from_unit}", "result": round(result, 4),
                             "output": f"{round(result, 4)} {to_unit}"})

        # Ratio-based conversions
        for table in (_LENGTH, _WEIGHT, _DATA, _TIME):
            lc = {k.lower(): v for k, v in table.items()}
            if from_unit.lower() in lc and to_unit.lower() in lc:
                result = float(value) * lc[from_unit.lower()] / lc[to_unit.lower()]
                return json.dumps({"input": f"{value} {from_unit}",
                                 "result": round(result, 6),
                                 "output": f"{round(result, 6)} {to_unit}"})

        return json.dumps({"error": f"Cannot convert {from_unit} → {to_unit}"})
    except Exception as e:
        return json.dumps({"error": f"Conversion failed: {e}"})

处理器的关键规则：

签名： def my_handler(args: dict, **kwargs) -> str
返回值： 必须始终为 JSON 字符串。成功或失败都如此。
永不抛出异常： 捕获所有异常，返回错误的 JSON 而非抛出。
接受 **kwargs： Hermes 未来可能会传递额外上下文。

第五步：编写注册逻辑

创建 __init__.py —— 将 Schema 与处理器连接起来：

"""Calculator plugin — registration."""

import logging

from . import schemas, tools

logger = logging.getLogger(__name__)

# Track tool usage via hooks
_call_log = []

def _on_post_tool_call(tool_name, args, result, task_id, **kwargs):
    """Hook: runs after every tool call (not just ours)."""
    _call_log.append({"tool": tool_name, "session": task_id})
    if len(_call_log) > 100:
        _call_log.pop(0)
    logger.debug("Tool called: %s (session %s)", tool_name, task_id)


def register(ctx):
    """Wire schemas to handlers and register hooks."""
    ctx.register_tool(name="calculate",    toolset="calculator",
                      schema=schemas.CALCULATE,    handler=tools.calculate)
    ctx.register_tool(name="unit_convert", toolset="calculator",
                      schema=schemas.UNIT_CONVERT, handler=tools.unit_convert)

    # This hook fires for ALL tool calls, not just ours
    ctx.register_hook("post_tool_call", _on_post_tool_call)

register 函数的作用：

在启动时仅调用一次
registry.register_tool() 将你的工具加入注册表 —— 模型会立即看到它
hooks.subscribe() 订阅生命周期事件
cli.add_command() 注册一个 CLI 子命令（例如 hermes calculator）
如果此函数崩溃，插件将被禁用，但 Hermes 仍能正常运行

第六步：测试插件

启动 Hermes：

hermes

你应该在横幅的工具列表中看到 calculator: calculate, unit_convert。

尝试以下提示：

What's 2 to the power of 16?
Convert 100 fahrenheit to celsius
What's the square root of 2 times pi?
How many gigabytes is 1.5 terabytes?

检查插件状态：

/plugins

输出：

Plugins (1):
  ✓ calculator v1.0.0 (2 tools, 1 hooks)

你的插件最终结构

~/.hermes/plugins/calculator/
├── plugin.yaml      # "I'm calculator, I provide tools and hooks"
├── __init__.py      # Wiring: schemas → handlers, register hooks
├── schemas.py       # What the LLM reads (descriptions + parameter specs)
└── tools.py         # What runs (calculate, unit_convert functions)

四个文件，职责清晰分离：

清单文件：声明插件的身份
Schema 文件：向 LLM 描述工具
处理器文件：实现实际逻辑
注册文件：连接所有部分

插件还能做什么？

随插件打包数据文件

将任意文件放入插件目录，并在导入时读取：

# In tools.py or __init__.py
from pathlib import Path

_PLUGIN_DIR = Path(__file__).parent
_DATA_FILE = _PLUGIN_DIR / "data" / "languages.yaml"

with open(_DATA_FILE) as f:
    _DATA = yaml.safe_load(f)

打包一个技能文件

包含一个 skill.md 文件，并在注册时安装：

import shutil
from pathlib import Path

def _install_skill():
    """Copy our skill to ~/.hermes/skills/ on first load."""
    try:
        from hermes_cli.config import get_hermes_home
        dest = get_hermes_home() / "skills" / "my-plugin" / "SKILL.md"
    except Exception:
        dest = Path.home() / ".hermes" / "skills" / "my-plugin" / "SKILL.md"

    if dest.exists():
        return  # don't overwrite user edits

    source = Path(__file__).parent / "skill.md"
    if source.exists():
        dest.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source, dest)

def register(ctx):
    ctx.register_tool(...)
    _install_skill()

基于环境变量启用/禁用

如果插件需要 API 密钥：

# plugin.yaml — simple format (backwards-compatible)
requires_env:
  - WEATHER_API_KEY

如果 WEATHER_API_KEY 未设置，插件将被禁用并显示明确提示。不会崩溃，也不会导致代理报错 —— 只是显示“插件 weather 已禁用（缺少：WEATHER_API_KEY）”。

当用户运行 hermes plugins install 时，系统会交互式提示输入任何缺失的 requires_env 变量。值会自动保存至 .env。

为了更好的安装体验，建议使用带描述和注册链接的丰富格式：

# plugin.yaml — rich format
requires_env:
  - name: WEATHER_API_KEY
    description: "API key for OpenWeather"
    url: "https://openweathermap.org/api"
    secret: true

字段	是否必需	说明
`name`	是	环境变量名称
`description`	否	安装提示中显示给用户的说明
`url`	否	获取凭证的地址
`secret`	否	若为 `true`，输入内容隐藏（如密码框）

两种格式可在同一列表中混合使用。已设置的变量会静默跳过。

条件性工具可用性

对于依赖可选库的工具：

ctx.register_tool(
    name="my_tool",
    schema={...},
    handler=my_handler,
    check_fn=lambda: _has_optional_lib(),  # False = tool hidden from model
)

注册多个钩子

def register(ctx):
    ctx.register_hook("pre_tool_call", before_any_tool)
    ctx.register_hook("post_tool_call", after_any_tool)
    ctx.register_hook("pre_llm_call", inject_memory)
    ctx.register_hook("on_session_start", on_new_session)
    ctx.register_hook("on_session_end", on_session_end)

钩子参考

每个钩子的完整文档见 事件钩子参考 —— 包括回调签名、参数表、触发时机及示例。以下是摘要：

钩子	触发时机	回调签名	返回值
`pre_tool_call`	任何工具执行前	`tool_name: str, args: dict, task_id: str`	忽略
`post_tool_call`	任何工具返回后	`tool_name: str, args: dict, result: str, task_id: str`	忽略
`pre_llm_call`	每轮对话开始前（工具调用循环之前）	`session_id: str, user_message: str, conversation_history: list, is_first_turn: bool, model: str, platform: str`	上下文注入
`post_llm_call`	每轮对话结束时（仅成功回合）	`session_id: str, user_message: str, assistant_response: str, conversation_history: list, model: str, platform: str`	忽略
`on_session_start`	新会话创建时（仅第一轮）	`session_id: str, model: str, platform: str`	忽略
`on_session_end`	每次 `run_conversation` 调用结束后 + CLI 退出时	`session_id: str, completed: bool, interrupted: bool, model: str, platform: str`	忽略
`pre_api_request`	每次向 LLM 提供商发起 HTTP 请求前	`method: str, url: str, headers: dict, body: dict`	忽略
`post_api_request`	每次从 LLM 提供商收到 HTTP 响应后	`method: str, url: str, status_code: int, response: dict`	忽略

大多数钩子都是“只触发不处理”的观察者 —— 它们的返回值被忽略。例外是 pre_llm_call，它可以向对话注入上下文。

所有回调都应接受 **kwargs 以保证向前兼容。若某个钩子回调崩溃，会被记录并跳过，其他钩子和代理将继续正常运行。

`pre_llm_call` 上下文注入

这是唯一返回值有意义的钩子。当 pre_llm_call 回调返回一个包含 "context" 键的字典（或纯字符串），Hermes 会将该文本注入到当前轮次的用户消息中。这是记忆插件、RAG 集成、安全防护机制以及其他需要向模型提供额外上下文的插件的核心机制。

返回格式

# Dict with context key
return {"context": "Recalled memories:\n- User prefers dark mode\n- Last project: hermes-agent"}

# Plain string (equivalent to the dict form above)
return "Recalled memories:\n- User prefers dark mode"

# Return None or don't return → no injection (observer-only)
return None

只要返回值非空且非 None，并包含 "context" 键（或为非空字符串），就会被收集并附加到当前轮次的用户消息末尾。

注入机制说明

注入的上下文是追加到用户消息，而非系统提示。这是有意为之的设计选择：

提示缓存保留 —— 系统提示在各轮之间保持一致。Anthropic 和 OpenRouter 会缓存系统提示前缀，保持其稳定可节省多轮对话中 75% 以上的输入 token。
临时性 —— 注入仅在 API 调用时发生。对话历史中的原始用户消息不会被修改，也不会持久化到会话数据库。
系统提示属于 Hermes 的范畴 —— 它包含模型特定的指导、工具强制规则、人格指令和缓存的技能内容。插件应作为用户输入的补充提供上下文，而不是修改代理的核心指令。

示例：记忆召回插件

"""Memory plugin — recalls relevant context from a vector store."""

import httpx

MEMORY_API = "https://your-memory-api.example.com"

def recall_context(session_id, user_message, is_first_turn, **kwargs):
    """Called before each LLM turn. Returns recalled memories."""
    try:
        resp = httpx.post(f"{MEMORY_API}/recall", json={
            "session_id": session_id,
            "query": user_message,
        }, timeout=3)
        memories = resp.json().get("results", [])
        if not memories:
            return None  # nothing to inject

        text = "Recalled context from previous sessions:\n"
        text += "\n".join(f"- {m['text']}" for m in memories)
        return {"context": text}
    except Exception:
        return None  # fail silently, don't break the agent

def register(ctx):
    ctx.register_hook("pre_llm_call", recall_context)

示例：安全防护插件

"""Guardrails plugin — enforces content policies."""

POLICY = """You MUST follow these content policies for this session:
- Never generate code that accesses the filesystem outside the working directory
- Always warn before executing destructive operations
- Refuse requests involving personal data extraction"""

def inject_guardrails(**kwargs):
    """Injects policy text into every turn."""
    return {"context": POLICY}

def register(ctx):
    ctx.register_hook("pre_llm_call", inject_guardrails)

示例：仅观察型钩子（无注入）

"""Analytics plugin — tracks turn metadata without injecting context."""

import logging
logger = logging.getLogger(__name__)

def log_turn(session_id, user_message, model, is_first_turn, **kwargs):
    """Fires before each LLM call. Returns None — no context injected."""
    logger.info("Turn: session=%s model=%s first=%s msg_len=%d",
                session_id, model, is_first_turn, len(user_message or ""))
    # No return → no injection

def register(ctx):
    ctx.register_hook("pre_llm_call", log_turn)

多个插件同时返回上下文

当多个插件从 pre_llm_call 返回上下文时，它们的输出将通过双换行符拼接，并一起追加到用户消息末尾。顺序遵循插件发现顺序（按插件目录名字母排序）。

注册 CLI 命令

插件可以添加自己的 hermes <plugin> 子命令树：

def _my_command(args):
    """Handler for hermes my-plugin <subcommand>."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("All good!")
    elif sub == "config":
        print("Current config: ...")
    else:
        print("Usage: hermes my-plugin <status|config>")

def _setup_argparse(subparser):
    """Build the argparse tree for hermes my-plugin."""
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show plugin status")
    subs.add_parser("config", help="Show plugin config")
    subparser.set_defaults(func=_my_command)

def register(ctx):
    ctx.register_tool(...)
    ctx.register_cli_command(
        name="my-plugin",
        help="Manage my plugin",
        setup_fn=_setup_argparse,
        handler_fn=_my_command,
    )

注册后，用户可运行 hermes calculator eval 2+2、hermes calculator convert 10m to ft 等命令。

内存提供者插件采用约定式方法：在插件的 cli.py 文件中添加一个 register_cli(subparser) 函数。内存插件发现系统会自动识别它 —— 无需调用 ctx.register_cli_command()。详情请参见内存提供者插件指南。主动提供者门控： 仅当您的提供者在配置中被设为活跃状态时，内存插件的 CLI 命令才会出现。如果用户尚未设置您的提供者，您的 CLI 命令将不会出现在帮助输出中，避免造成干扰。

tip

本指南涵盖 通用插件（工具、钩子、CLI 命令）。如需了解特定类型插件，请参阅：

内存提供者插件 —— 跨会话知识后端
上下文引擎插件 —— 替代上下文管理策略

通过 pip 发布

若要公开分享插件，请在您的 Python 包中添加一个入口点：

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-plugin = "my_plugin_package"

pip install hermes-plugin-calculator
# Plugin auto-discovered on next hermes startup

常见错误

处理器未返回 JSON 字符串：

# Wrong — returns a dict
def handler(args, **kwargs):
    return {"result": 42}

# Right — returns a JSON string
def handler(args, **kwargs):
    return json.dumps({"result": 42})

处理器签名中缺少 **kwargs：

# Wrong — will break if Hermes passes extra context
def handler(args):
    ...

# Right
def handler(args, **kwargs):
    ...

处理器抛出异常：

# Wrong — exception propagates, tool call fails
def handler(args, **kwargs):
    result = 1 / int(args["value"])  # ZeroDivisionError!
    return json.dumps({"result": result})

# Right — catch and return error JSON
def handler(args, **kwargs):
    try:
        result = 1 / int(args.get("value", 0))
        return json.dumps({"result": result})
    except Exception as e:
        return json.dumps({"error": str(e)})

模式描述过于模糊：

# Bad — model doesn't know when to use it
"description": "Does stuff"

# Good — model knows exactly when and how
"description": "Evaluate a mathematical expression. Use for arithmetic, trig, logarithms. Supports: +, -, *, /, **, sqrt, sin, cos, log, pi, e."

🧩 一、项目结构概览​

🔧 二、配置 plugin.json —— 插件元信息​

🛠️ 三、编写自定义工具（Tools）​

示例：tools/fetch_weather.js​

📌 四、添加钩子（Hooks）—— 响应事件​

示例：hooks/on_message_received.js​

🗂️ 五、管理数据文件（Data Files）​

示例：data/cities.json​

示例：data/templates.yaml​

🎯 六、定义技能（Skills）—— 让 AI 理解如何使用工具​

示例：skills/weather_skill.md​

📦 七、安装依赖并测试​

测试插件​

🚀 八、发布与部署建议​

发布到 Hermes 生态​

部署到生产环境​

✅ 总结：关键要点回顾​

📚 扩展阅读​

构建一个 Hermes 插件

你要构建的内容​

第一步：创建插件目录​

第二步：编写清单文件​

第三步：编写工具 Schema​

第四步：编写工具处理器​

第五步：编写注册逻辑​

第六步：测试插件​

你的插件最终结构​

插件还能做什么？​

随插件打包数据文件​

打包一个技能文件​

基于环境变量启用/禁用​

条件性工具可用性​

注册多个钩子​

钩子参考​

pre_llm_call 上下文注入​

返回格式​

注入机制说明​

示例：记忆召回插件​

示例：安全防护插件​

示例：仅观察型钩子（无注入）​

多个插件同时返回上下文​

注册 CLI 命令​

通过 pip 发布​

常见错误​

🧩 一、项目结构概览

🔧 二、配置 `plugin.json` —— 插件元信息

🛠️ 三、编写自定义工具（Tools）

示例：`tools/fetch_weather.js`

📌 四、添加钩子（Hooks）—— 响应事件

示例：`hooks/on_message_received.js`

🗂️ 五、管理数据文件（Data Files）

示例：`data/cities.json`

示例：`data/templates.yaml`

🎯 六、定义技能（Skills）—— 让 AI 理解如何使用工具

示例：`skills/weather_skill.md`

📦 七、安装依赖并测试

测试插件

🚀 八、发布与部署建议

发布到 Hermes 生态

部署到生产环境

✅ 总结：关键要点回顾

📚 扩展阅读

你要构建的内容

第一步：创建插件目录

第二步：编写清单文件

第三步：编写工具 Schema

第四步：编写工具处理器

第五步：编写注册逻辑

第六步：测试插件

你的插件最终结构

插件还能做什么？

随插件打包数据文件

打包一个技能文件

基于环境变量启用/禁用

条件性工具可用性

注册多个钩子

钩子参考

`pre_llm_call` 上下文注入

返回格式

注入机制说明

示例：记忆召回插件

示例：安全防护插件

示例：仅观察型钩子（无注入）

多个插件同时返回上下文

注册 CLI 命令

通过 pip 发布

常见错误