词元之母TOK.MOM - 平台充值汇率 1:1 即 1 人民币充值到账 1 美元，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"Plugins"
Plugins
Adding Tools 页面针对的是存放在
tools/ 和 toolsets.py 中的 Hermes 内置核心工具。快速概览
~/.hermes/plugins/ 下放入一个目录，包含 plugin.yaml 和 Python 代码：~/.hermes/plugins/my-plugin/
├── plugin.yaml # manifest（清单）
├── __init__.py # register() — 将 schema 与处理器绑定
├── schemas.py # tool schema（LLM 所见的内容）
└── tools.py # tool 处理器（调用时实际执行的代码）最小可运行示例
hello_world 工具，并通过 hook 记录每次工具调用。~/.hermes/plugins/hello-world/plugin.yaml~/.hermes/plugins/hello-world/__init__.py~/.hermes/plugins/hello-world/，重启 Hermes，模型即可立即调用 hello_world。每次工具调用后，hook 会打印一行日志。./.hermes/plugins/ 下的项目本地插件默认禁用。仅对可信仓库启用，方法是在启动 Hermes 前设置 HERMES_ENABLE_PROJECT_PLUGINS=true。插件能做什么
ctx.* API 均可在插件的 register(ctx) 函数中使用。| 能力 | 方式 |
|---|---|
| 添加工具 | ctx.register_tool(name=..., toolset=..., schema=..., handler=...) |
| 添加 hook | ctx.register_hook("post_tool_call", callback) |
| 添加斜杠命令 | ctx.register_command(name, handler, description) — 在 CLI 和 gateway 会话中添加 /name |
| 从命令中调度工具 | ctx.dispatch_tool(name, args) — 调用已注册的工具，自动注入父 agent 上下文 |
| 添加 CLI 命令 | ctx.register_cli_command(name, help, setup_fn, handler_fn) — 添加 hermes <plugin> <subcommand> |
| 注入消息 | ctx.inject_message(content, role="user") — 参见 注入消息 |
| 附带数据文件 | Path(__file__).parent / "data" / "file.yaml" |
| 打包 skill | ctx.register_skill(name, path) — 命名空间为 plugin:skill，通过 skill_view("plugin:skill") 加载 |
| 按环境变量控制 | 在 plugin.yaml 中设置 requires_env: [API_KEY] — 在 hermes plugins install 时提示输入 |
| 通过 pip 分发 | [project.entry-points."hermes_agent.plugins"] |
| 注册 gateway 平台（Discord、Telegram、IRC 等） | ctx.register_platform(name, label, adapter_factory, check_fn, ...) — 参见 Adding Platform Adapters |
| 注册图像生成后端 | ctx.register_image_gen_provider(provider) — 参见 Image Generation Provider Plugins |
| 注册视频生成后端 | ctx.register_video_gen_provider(provider) — 参见 Video Generation Provider Plugins |
| 注册上下文压缩引擎 | ctx.register_context_engine(engine) — 参见 Context Engine Plugins |
| 注册 memory 后端 | 在 plugins/memory/<name>/__init__.py 中继承 MemoryProvider — 参见 Memory Provider Plugins（使用独立发现系统） |
| 调用宿主 LLM | ctx.llm.complete(...) / ctx.llm.complete_structured(...) — 借用用户当前激活的模型和认证，进行一次性补全，支持可选 JSON schema 验证。参见 Plugin LLM Access |
| 注册推理后端（LLM provider） | 在 plugins/model-providers/<name>/__init__.py 中调用 register_provider(ProviderProfile(...)) — 参见 Model Provider Plugins（使用独立发现系统） |
插件发现
| 来源 | 路径 | 使用场景 |
|---|---|---|
| 内置 | <repo>/plugins/ | 随 Hermes 附带 — 参见 Built-in Plugins |
| 用户 | ~/.hermes/plugins/ | 个人插件 |
| 项目 | .hermes/plugins/ | 项目专属插件（需要 HERMES_ENABLE_PROJECT_PLUGINS=true） |
| pip | hermes_agent.plugins entry_points | 分发包 |
| Nix | services.hermes-agent.extraPlugins / extraPythonPackages | NixOS 声明式安装 — 参见 Nix Setup |
插件子分类
| 子目录 | 内容 | 发现系统 |
|---|---|---|
plugins/（根目录） | 通用插件 — 工具、hook、斜杠命令、CLI 命令、打包 skill | PluginManager（kind: standalone 或 backend） |
plugins/platforms/<name>/ | Gateway 频道适配器（ctx.register_platform()） | PluginManager（kind: platform，深一层） |
plugins/image_gen/<name>/ | 图像生成后端（ctx.register_image_gen_provider()） | PluginManager（kind: backend，深一层） |
plugins/memory/<name>/ | Memory provider（继承 MemoryProvider） | 独立加载器，位于 plugins/memory/__init__.py（kind: exclusive — 同时只有一个激活） |
plugins/context_engine/<name>/ | 上下文压缩引擎（ctx.register_context_engine()） | 独立加载器，位于 plugins/context_engine/__init__.py（同时只有一个激活） |
plugins/model-providers/<name>/ | LLM provider profile（register_provider(ProviderProfile(...))） | 独立加载器，位于 providers/__init__.py（首次调用 get_provider_profile() 时懒加载扫描） |
~/.hermes/plugins/model-providers/<name>/ 和 ~/.hermes/plugins/memory/<name>/ 下的用户插件会覆盖同名内置插件 — register_provider() / register_memory_provider() 中后写者胜出。放入一个目录即可替换内置实现，无需修改仓库。hermes plugins list 和交互式 hermes plugins UI 中以路径派生的 key 显示 — 例如 observability/langfuse、image_gen/openai、platforms/teams。该 key（而非 manifest 中的 name:）是传给 hermes plugins enable … / disable … 的值，也是在 config.yaml 的 plugins.enabled 下填写的字符串。插件默认关闭（少数例外）
hermes plugins 和 /plugins 中），但在你将插件名称添加到 ~/.hermes/config.yaml 的 plugins.enabled 之前，任何带有 hook 或工具的内容都不会加载。这可防止第三方代码在未经明确同意的情况下运行。hermes plugins install owner/repo 后，会询问 Enable 'name' now? [y/N] — 默认为否。脚本化安装时可用 --enable 或 --no-enable 跳过提示。允许列表不控制的内容
plugins.enabled — 它们是 Hermes 内置功能的一部分，若默认关闭会破坏基本功能：| 插件类型 | 激活方式 |
|---|---|
内置平台插件（IRC、Teams 等，位于 plugins/platforms/） | 自动加载，使所有内置 gateway 频道可用。实际频道通过 config.yaml 中的 gateway.platforms.<name>.enabled 开启。 |
内置后端（plugins/image_gen/ 等下的图像生成 provider） | 自动加载，使默认后端"开箱即用"。通过 config.yaml 中的 <category>.provider 选择（例如 image_gen.provider: openai）。 |
Memory provider（plugins/memory/） | 全部发现；同时只有一个激活，由 config.yaml 中的 memory.provider 选择。 |
Context engine（plugins/context_engine/） | 全部发现；同时只有一个激活，由 config.yaml 中的 context.engine 选择。 |
Model provider（plugins/model-providers/） | plugins/model-providers/ 下的所有内置 provider 在首次调用 get_provider_profile() 时发现并注册。用户通过 --provider 或 config.yaml 一次选择一个。 |
pip 安装的 backend 插件 | 通过 plugins.enabled 选择加入（与通用插件相同）。 |
用户安装的平台（位于 ~/.hermes/plugins/platforms/） | 通过 plugins.enabled 选择加入 — 第三方 gateway 适配器需要明确同意。 |
plugins.enabled 允许列表专门用于控制用户放入 ~/.hermes/plugins/ 的任意代码。现有用户的迁移
~/.hermes/plugins/ 下且不在 plugins.disabled 中的用户插件会自动纳入 plugins.enabled。你的现有配置继续正常工作。内置独立插件不会自动纳入 — 即使是现有用户也需要明确选择加入。（内置平台/后端插件从未需要纳入，因为它们从未被控制。）可用 hook
| Hook | 触发时机 |
|---|---|
pre_tool_call | 任意工具执行前 |
post_tool_call | 任意工具返回后 |
pre_llm_call | 每轮一次，LLM 循环前 — 可返回 {"context": "..."} 以向用户消息注入上下文 |
post_llm_call | 每轮一次，LLM 循环后（仅成功轮次） |
on_session_start | 新会话创建时（仅第一轮） |
on_session_end | 每次 run_conversation 调用结束时 + CLI 退出处理器 |
on_session_finalize | CLI/gateway 销毁活跃会话时（/new、GC、CLI 退出） |
on_session_reset | Gateway 换入新会话 key 时（/new、/reset、/clear、空闲轮换） |
subagent_stop | delegate_task 完成后每个子 agent 触发一次 |
pre_gateway_dispatch | Gateway 收到用户消息，在认证和调度之前。返回 {"action": "skip" | "rewrite" | "allow", ...} 以影响流程。 |
插件类型
| 类型 | 作用 | 选择方式 | 位置 |
|---|---|---|---|
| 通用插件 | 添加工具、hook、斜杠命令、CLI 命令 | 多选（启用/禁用） | ~/.hermes/plugins/ |
| Memory provider | 替换或增强内置 memory | 单选（同时只有一个激活） | plugins/memory/ |
| Context engine | 替换内置上下文压缩器 | 单选（同时只有一个激活） | plugins/context_engine/ |
| Model provider | 声明推理后端（OpenRouter、Anthropic 等） | 多注册，通过 --provider / config.yaml 选择 | plugins/model-providers/ |
--provider 或 config.yaml 一次选择一个。通用插件可以任意组合启用。可插拔接口 — 各场景对应文档
PluginContext 暴露了多个不同的扩展点 — Hermes 还接受 Python 插件系统之外的扩展（配置驱动的后端、shell hook 命令、外部服务器等）。使用下表找到适合你需求的文档：| 想要添加… | 方式 | 编写指南 |
|---|---|---|
| LLM 可调用的工具 | Python 插件 — ctx.register_tool() | Build a Hermes Plugin · Adding Tools |
| 生命周期 hook（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — ctx.register_hook() | Hooks reference · Build a Hermes Plugin |
| CLI / gateway 的斜杠命令 | Python 插件 — ctx.register_command() | Build a Hermes Plugin · Extending the CLI |
hermes <thing> 的子命令 | Python 插件 — ctx.register_cli_command() | Extending the CLI |
| 插件附带的skill | Python 插件 — ctx.register_skill() | Creating Skills |
| 推理后端（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 plugins/model-providers/<name>/ 中调用 register_provider(ProviderProfile(...)) | Model Provider Plugins · Adding Providers |
| Gateway 频道（Discord / Telegram / IRC / Teams 等） | 平台插件 — 在 plugins/platforms/<name>/ 中调用 ctx.register_platform() | Adding Platform Adapters |
| Memory 后端（Honcho、Mem0、Supermemory 等） | Memory 插件 — 在 plugins/memory/<name>/ 中继承 MemoryProvider | Memory Provider Plugins |
| 上下文压缩策略 | Context-engine 插件 — ctx.register_context_engine() | Context Engine Plugins |
| 图像生成后端（DALL·E、SDXL 等） | 后端插件 — ctx.register_image_gen_provider() | Image Generation Provider Plugins |
| 视频生成后端（Veo、Kling、Pixverse、Grok-Imagine、Runway 等） | 后端插件 — ctx.register_video_gen_provider() | Video Generation Provider Plugins |
| TTS 后端（任意 CLI — Piper、VoxCPM、Kokoro、xtts、语音克隆脚本等） | 配置驱动（推荐）— 在 config.yaml 的 tts.providers.<name> 下以 type: command 声明。或 Python 后端插件 — 对需要超出 shell 模板的 Python SDK / 流式引擎使用 ctx.register_tts_provider()。 | TTS Setup · Python plugin guide |
| STT 后端（自定义 whisper 二进制、本地 ASR CLI） | 配置驱动 — 将 HERMES_LOCAL_STT_COMMAND 环境变量设置为 shell 模板 | Voice Message Transcription (STT) |
| 通过 MCP 使用外部工具（文件系统、GitHub、Linear、Notion、任意 MCP 服务器） | 配置驱动 — 在 config.yaml 中以 command: / url: 声明 mcp_servers.<name>。Hermes 自动发现服务器的工具并与内置工具一同注册。 | MCP |
| 额外 skill 来源（自定义 GitHub 仓库、私有 skill 索引） | CLI — hermes skills tap add <repo> | Skills Hub · 发布自定义 tap |
Gateway 事件 hook（在 gateway:startup、session:start、agent:end、command:* 时触发） | 将 HOOK.yaml + handler.py 放入 ~/.hermes/hooks/<name>/ | Event Hooks |
| Shell hook（在事件时运行 shell 命令 — 通知、审计日志、桌面提醒） | 配置驱动 — 在 config.yaml 的 hooks: 下声明 | Shell Hooks |
备注
NixOS 声明式插件
hermes plugins install。完整详情请参见 Nix Setup 指南。nix-managed- 前缀符号链接 — 与手动安装的插件共存，从 Nix 配置中移除后自动清理。管理插件
plugins/observability/langfuse/、plugins/image_gen/openai/），使用完整的 <category>/<plugin> key — 这正是 hermes plugins list 在 Name 列中显示的内容。交互式 UI
hermes plugins 会打开一个复合交互界面：Plugins
↑↓ navigate SPACE toggle ENTER configure/confirm ESC done
General Plugins
→ [✓] my-tool-plugin — Custom search tool
[ ] webhook-notifier — Event hooks
[ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]
[ ] observability/langfuse — Trace turns / LLM calls / tools to Langfuse [bundled]
Provider Plugins
Memory Provider ▸ honcho
Context Engine ▸ compressorplugins.enabled 中，未勾选 = 在 plugins.disabled 中（明确关闭）。[bundled] 标签。config.yaml：已启用 vs. 已禁用 vs. 未设置
| 状态 | 含义 | 在 plugins.enabled 中？ | 在 plugins.disabled 中？ |
|---|---|---|---|
enabled | 下次会话时加载 | 是 | 否 |
disabled | 明确关闭 — 即使同时在 enabled 中也不会加载 | （无关） | 是 |
not enabled | 已发现但从未选择加入 | 否 | 否 |
not enabled。hermes plugins list 显示全部三种状态，便于区分明确关闭的插件和等待启用的插件。/plugins 显示当前已加载的插件。注入消息
ctx.inject_message() 向活跃对话注入消息：ctx.inject_message(content: str, role: str = "user") -> bool"user" 角色，内容会以 [role] 为前缀（例如 [system] ...）。True，若无 CLI 引用（例如在 gateway 模式下）则返回 False。备注
inject_message 仅在 CLI 模式下可用。在 gateway 模式下，没有 CLI 引用，该方法返回 False。修改于 2026-05-31 00:25:01