better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/plugins.md

@@ -0,0 +1,346 @@
+---
+sidebar_position: 11
+sidebar_label: "Plugins"
+title: "Plugins"
+description: "通过插件系统为 Hermes 添加自定义工具、hook 和集成"
+---
+
+# Plugins
+
+Hermes 提供了一套插件系统，可在不修改核心代码的情况下添加自定义工具、hook（钩子）和集成。
+
+如果你想为自己、团队或某个项目创建自定义工具，这通常是正确的路径。开发者指南中的
+[Adding Tools](/developer-guide/adding-tools) 页面针对的是存放在 `tools/` 和 `toolsets.py` 中的 Hermes 内置核心工具。
+
+**→ [构建 Hermes Plugin](/developer-guide/plugins)** — 包含完整可运行示例的分步指南。
+
+## 快速概览
+
+在 `~/.hermes/plugins/` 下放入一个目录，包含 `plugin.yaml` 和 Python 代码：
+
+```
+~/.hermes/plugins/my-plugin/
+├── plugin.yaml      # manifest（清单）
+├── __init__.py      # register() — 将 schema 与处理器绑定
+├── schemas.py       # tool schema（LLM 所见的内容）
+└── tools.py         # tool 处理器（调用时实际执行的代码）
+```
+
+启动 Hermes — 你的工具会与内置工具一同出现，模型可立即调用它们。
+
+### 最小可运行示例
+
+以下是一个完整插件，添加了一个 `hello_world` 工具，并通过 hook 记录每次工具调用。
+
+**`~/.hermes/plugins/hello-world/plugin.yaml`**
+
+```yaml
+name: hello-world
+version: "1.0"
+description: A minimal example plugin
+```
+
+**`~/.hermes/plugins/hello-world/__init__.py`**
+
+```python
+"""Minimal Hermes plugin — registers a tool and a hook."""
+
+import json
+
+
+def register(ctx):
+    # --- Tool: hello_world ---
+    schema = {
+        "name": "hello_world",
+        "description": "Returns a friendly greeting for the given name.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Name to greet",
+                }
+            },
+            "required": ["name"],
+        },
+    }
+
+    def handle_hello(params, **kwargs):
+        del kwargs
+        name = params.get("name", "World")
+        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})
+
+    ctx.register_tool(
+        name="hello_world",
+        toolset="hello_world",
+        schema=schema,
+        handler=handle_hello,
+    )
+
+    # --- Hook: log every tool call ---
+    def on_tool_call(tool_name, params, result):
+        print(f"[hello-world] tool called: {tool_name}")
+
+    ctx.register_hook("post_tool_call", on_tool_call)
+```
+
+将两个文件放入 `~/.hermes/plugins/hello-world/`，重启 Hermes，模型即可立即调用 `hello_world`。每次工具调用后，hook 会打印一行日志。
+
+面向模型的工具描述应写在 `schema["description"]` 中。可选的 `ctx.register_tool(description=...)` 值是独立的 `ToolEntry` 注册表元数据：省略时，它会默认使用 schema 中的描述；但如果 schema 缺少 `description`，Hermes 不会把该元数据反向复制到 schema。建议只在 schema 中定义一次描述。如果同时提供两个值，请保持同步；模型看到的是 schema 中的值。
+
+`./.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")` — 参见 [注入消息](#injecting-messages) |
+| 附带数据文件 | `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](/developer-guide/adding-platform-adapters) |
+| 注册图像生成后端 | `ctx.register_image_gen_provider(provider)` — 参见 [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
+| 注册视频生成后端 | `ctx.register_video_gen_provider(provider)` — 参见 [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
+| 注册上下文压缩引擎 | `ctx.register_context_engine(engine)` — 参见 [Context Engine Plugins](/developer-guide/context-engine-plugin) |
+| 注册 memory 后端 | 在 `plugins/memory/<name>/__init__.py` 中继承 `MemoryProvider` — 参见 [Memory Provider Plugins](/developer-guide/memory-provider-plugin)（使用独立发现系统） |
+| 调用宿主 LLM | `ctx.llm.complete(...)` / `ctx.llm.complete_structured(...)` — 借用用户当前激活的模型和认证，进行一次性补全，支持可选 JSON schema 验证。参见 [Plugin LLM Access](/developer-guide/plugin-llm-access) |
+| 注册推理后端（LLM provider） | 在 `plugins/model-providers/<name>/__init__.py` 中调用 `register_provider(ProviderProfile(...))` — 参见 [Model Provider Plugins](/developer-guide/model-provider-plugin)（使用独立发现系统） |
+
+## 插件发现
+
+| 来源 | 路径 | 使用场景 |
+|--------|------|----------|
+| 内置 | `<repo>/plugins/` | 随 Hermes 附带 — 参见 [Built-in Plugins](/user-guide/features/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](/getting-started/nix-setup#plugins) |
+
+名称冲突时，后面的来源会覆盖前面的，因此与内置插件同名的用户插件会替换它。
+
+### 插件子分类
+
+在每个来源内，Hermes 还识别将插件路由到专用发现系统的子分类目录：
+
+| 子目录 | 内容 | 发现系统 |
+|---|---|---|
+| `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 或工具的内容都不会加载。这可防止第三方代码在未经明确同意的情况下运行。
+
+```yaml
+plugins:
+  enabled:
+    - my-tool-plugin
+    - disk-cleanup
+  disabled:       # 可选的拒绝列表 — 若名称同时出现在两个列表中，此列表始终优先
+    - noisy-plugin
+```
+
+切换状态的三种方式：
+
+```bash
+hermes plugins                    # 交互式切换（空格勾选/取消勾选）
+hermes plugins enable <name>      # 添加到允许列表
+hermes plugins disable <name>     # 从允许列表移除并添加到禁用列表
+```
+
+执行 `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 版本（config schema v21+）时，已安装在 `~/.hermes/plugins/` 下且不在 `plugins.disabled` 中的用户插件会**自动纳入** `plugins.enabled`。你的现有配置继续正常工作。内置独立插件**不会**自动纳入 — 即使是现有用户也需要明确选择加入。（内置平台/后端插件从未需要纳入，因为它们从未被控制。）
+
+## 可用 hook
+
+插件可注册 `hermes_cli.plugins.VALID_HOOKS` 当前接受的 24 个生命周期事件。**[Event Hooks 目录](/user-guide/features/hooks#已发布的-plugin-hook-目录)**是精确触发时机、返回值处理、payload 字段和隐私说明的 canonical reference。
+
+| 描述性类别 | 已发布 hook |
+|---|---|
+| **指令/控制** | `pre_tool_call`, `pre_llm_call`, `pre_verify`, `pre_gateway_dispatch` |
+| **Transform** | `transform_tool_result`, `transform_terminal_output`, `transform_llm_output` |
+| **观察者** | `post_tool_call`, `post_llm_call`, `pre_api_request`, `post_api_request`, `api_request_error`, `on_session_start`, `on_session_end`, `on_session_finalize`, `on_session_reset`, `on_skill_lifecycle`, `subagent_start`, `subagent_stop`, `pre_approval_request`, `post_approval_response`, `kanban_task_claimed`, `kanban_task_completed`, `kanban_task_blocked` |
+
+这些类别只描述当前行为，不规定未来命名规则。Plugin middleware 仍是独立的 registry/surface。
+
+## 插件类型
+
+Hermes 有四种插件：
+
+| 类型 | 作用 | 选择方式 | 位置 |
+|------|-------------|-----------|----------|
+| **通用插件** | 添加工具、hook、斜杠命令、CLI 命令 | 多选（启用/禁用） | `~/.hermes/plugins/` |
+| **Memory provider** | 替换或增强内置 memory | 单选（同时只有一个激活） | `plugins/memory/` |
+| **Context engine** | 替换内置上下文压缩器 | 单选（同时只有一个激活） | `plugins/context_engine/` |
+| **Model provider** | 声明推理后端（OpenRouter、Anthropic 等） | 多注册，通过 `--provider` / `config.yaml` 选择 | `plugins/model-providers/` |
+
+Memory provider 和 context engine 是 **provider 插件** — 每种类型同时只能有一个激活。Model provider 也是插件，但可以同时加载多个；用户通过 `--provider` 或 `config.yaml` 一次选择一个。通用插件可以任意组合启用。
+
+## 可插拔接口 — 各场景对应文档
+
+上表展示了四种插件类别，但在"通用插件"中，`PluginContext` 暴露了多个不同的扩展点 — Hermes 还接受 Python 插件系统之外的扩展（配置驱动的后端、shell hook 命令、外部服务器等）。使用下表找到适合你需求的文档：
+
+| 想要添加… | 方式 | 编写指南 |
+|---|---|---|
+| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Adding Tools](/developer-guide/adding-tools) |
+| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/developer-guide/plugins) |
+| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Extending the CLI](/developer-guide/extending-the-cli) |
+| `hermes <thing>` 的**子命令** | Python 插件 — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
+| 插件附带的**skill** | Python 插件 — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
+| **推理后端**（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 `plugins/model-providers/<name>/` 中调用 `register_provider(ProviderProfile(...))` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
+| **Gateway 频道**（Discord / Telegram / IRC / Teams 等） | 平台插件 — 在 `plugins/platforms/<name>/` 中调用 `ctx.register_platform()` | [Adding Platform Adapters](/developer-guide/adding-platform-adapters) |
+| **Memory 后端**（Honcho、Mem0、Supermemory 等） | Memory 插件 — 在 `plugins/memory/<name>/` 中继承 `MemoryProvider` | [Memory Provider Plugins](/developer-guide/memory-provider-plugin) |
+| **上下文压缩策略** | Context-engine 插件 — `ctx.register_context_engine()` | [Context Engine Plugins](/developer-guide/context-engine-plugin) |
+| **图像生成后端**（DALL·E、SDXL 等） | 后端插件 — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin) |
+| **视频生成后端**（Veo、Kling、Pixverse、Grok-Imagine、Runway 等） | 后端插件 — `ctx.register_video_gen_provider()` | [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin) |
+| **TTS 后端**（任意 CLI — Piper、VoxCPM、Kokoro、xtts、语音克隆脚本等） | 配置驱动（推荐）— 在 `config.yaml` 的 `tts.providers.<name>` 下以 `type: command` 声明。或 Python 后端插件 — 对需要超出 shell 模板的 Python SDK / 流式引擎使用 `ctx.register_tts_provider()`。 | [TTS Setup](/user-guide/features/tts#custom-command-providers) · [Python plugin guide](/user-guide/features/tts#python-plugin-providers) |
+| **STT 后端**（自定义 whisper 二进制、本地 ASR CLI） | 配置驱动 — 将 `HERMES_LOCAL_STT_COMMAND` 环境变量设置为 shell 模板 | [Voice Message Transcription (STT)](/user-guide/features/tts#voice-message-transcription-stt) |
+| **通过 MCP 使用外部工具**（文件系统、GitHub、Linear、Notion、任意 MCP 服务器） | 配置驱动 — 在 `config.yaml` 中以 `command:` / `url:` 声明 `mcp_servers.<name>`。Hermes 自动发现服务器的工具并与内置工具一同注册。 | [MCP](/user-guide/features/mcp) |
+| **额外 skill 来源**（自定义 GitHub 仓库、私有 skill 索引） | CLI — `hermes skills tap add <repo>` | [Skills Hub](/user-guide/features/skills#skills-hub) · [发布自定义 tap](/user-guide/features/skills#publishing-a-custom-skill-tap) |
+| **Gateway 事件 hook**（在 `gateway:startup`、`session:start`、`agent:end`、`command:*` 时触发） | 将 `HOOK.yaml` + `handler.py` 放入 `~/.hermes/hooks/<name>/` | [Event Hooks](/user-guide/features/hooks#gateway-event-hooks) |
+| **Shell hook**（在事件时运行 shell 命令 — 通知、审计日志、桌面提醒） | 配置驱动 — 在 `config.yaml` 的 `hooks:` 下声明 | [Shell Hooks](/user-guide/features/hooks#shell-hooks) |
+
+:::note
+并非所有扩展都是 Python 插件。某些扩展接口有意使用**配置驱动的 shell 命令**（TTS、STT、shell hook），这样你已有的任意 CLI 无需编写 Python 即可成为插件。其他的是 agent 连接并自动注册工具的**外部服务器**（MCP）。还有一些是拥有自己 manifest 格式的**即插即用目录**（gateway hook）。根据你的集成风格选择合适的接口；上表中的编写指南各自涵盖了占位符、发现机制和示例。
+:::
+
+## NixOS 声明式插件
+
+在 NixOS 上，插件可通过模块选项声明式安装 — 无需 `hermes plugins install`。完整详情请参见 **[Nix Setup 指南](/getting-started/nix-setup#plugins)**。
+
+```nix
+services.hermes-agent = {
+  # 目录插件（包含 plugin.yaml 的源码树）
+  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
+  # 入口点插件（pip 包）
+  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
+  # 在 config 中启用
+  settings.plugins.enabled = [ "my-plugin" ];
+};
+```
+
+声明式插件以 `nix-managed-` 前缀符号链接 — 与手动安装的插件共存，从 Nix 配置中移除后自动清理。
+
+## 管理插件
+
+```bash
+hermes plugins                                       # 统一交互式 UI
+hermes plugins list                                  # 表格：已启用 / 已禁用 / 未启用
+hermes plugins install user/repo                     # 从 Git 安装，然后提示 Enable? [y/N]
+hermes plugins install user/repo --enable            # 安装并启用（无提示）
+hermes plugins install user/repo --no-enable         # 安装但保持禁用（无提示）
+hermes plugins update my-plugin                      # 拉取最新版本
+hermes plugins remove my-plugin                      # 卸载
+hermes plugins enable my-plugin                      # 添加到允许列表（普通插件）
+hermes plugins enable observability/langfuse         # 添加到允许列表（子分类插件）
+hermes plugins disable my-plugin                     # 从允许列表移除并添加到禁用列表
+```
+
+对于子分类目录下的插件（例如 `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           ▸ compressor
+```
+
+- **General Plugins 区域** — 复选框，用空格切换。勾选 = 在 `plugins.enabled` 中，未勾选 = 在 `plugins.disabled` 中（明确关闭）。
+- **Provider Plugins 区域** — 显示当前选择。按 ENTER 进入单选选择器，选择一个激活的 provider。
+- 内置插件在同一列表中显示，带有 `[bundled]` 标签。
+
+Provider 插件的选择保存到 `config.yaml`：
+
+```yaml
+memory:
+  provider: "honcho"      # 空字符串 = 仅使用内置
+
+context:
+  engine: "compressor"    # 默认内置压缩器
+```
+
+### 已启用 vs. 已禁用 vs. 未设置
+
+插件处于以下三种状态之一：
+
+| 状态 | 含义 | 在 `plugins.enabled` 中？ | 在 `plugins.disabled` 中？ |
+|---|---|---|---|
+| `enabled` | 下次会话时加载 | 是 | 否 |
+| `disabled` | 明确关闭 — 即使同时在 `enabled` 中也不会加载 | （无关） | 是 |
+| `not enabled` | 已发现但从未选择加入 | 否 | 否 |
+
+新安装或内置插件的默认状态为 `not enabled`。`hermes plugins list` 显示全部三种状态，便于区分明确关闭的插件和等待启用的插件。
+
+在运行中的会话里，`/plugins` 显示当前已加载的插件。
+
+## 注入消息
+
+插件可使用 `ctx.inject_message()` 向活跃对话注入消息：
+
+```python
+ctx.inject_message("New data arrived from the webhook", role="user")
+```
+
+**签名：** `ctx.inject_message(content: str, role: str = "user") -> bool`
+
+工作原理：
+
+- 若 agent **空闲**（等待用户输入），消息会作为下一条输入排队并开始新一轮。
+- 若 agent **处于轮次中**（正在运行），消息会中断当前操作 — 与用户输入新消息并按下 Enter 效果相同。
+- 对于非 `"user"` 角色，内容会以 `[role]` 为前缀（例如 `[system] ...`）。
+- 若消息成功排队返回 `True`，若无 CLI 引用（例如在 gateway 模式下）则返回 `False`。
+
+这使得远程控制查看器、消息桥接或 webhook 接收器等插件能够从外部来源向对话注入消息。
+
+:::note
+`inject_message` 仅在 CLI 模式下可用。在 gateway 模式下，没有 CLI 引用，该方法返回 `False`。
+:::
+
+完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](/developer-guide/plugins)**。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/features/provider-routing.md

@@ -0,0 +1,200 @@
+---
+title: Provider Routing
+description: 配置 OpenRouter provider 偏好，以优化成本、速度或质量。
+sidebar_label: Provider Routing
+sidebar_position: 7
+---
+
+# Provider Routing
+
+使用 [OpenRouter](https://openrouter.ai) 作为 LLM provider 时，Hermes Agent 支持 **provider routing**（提供商路由）——对哪些底层 AI provider 处理你的请求以及如何排列优先级进行精细控制。
+
+OpenRouter 将请求路由到多个 provider（例如 Anthropic、Google、AWS Bedrock、Together AI）。Provider routing 让你可以针对成本、速度、质量进行优化，或强制指定特定 provider。
+
+## 配置
+
+在 `~/.hermes/config.yaml` 中添加 `provider_routing` 部分：
+
+```yaml
+provider_routing:
+  sort: "price"           # 如何对 provider 排序
+  only: []                # 白名单：仅使用这些 provider
+  ignore: []              # 黑名单：永不使用这些 provider
+  order: []               # 显式 provider 优先级顺序
+  require_parameters: false  # 仅使用支持所有参数的 provider
+  data_collection: null   # 控制数据收集（"allow" 或 "deny"）
+```
+
+:::info
+Provider routing 仅在使用 OpenRouter 时生效。直接连接 provider（例如直接连接 Anthropic API）时无效。
+:::
+
+## 选项
+
+### `sort`
+
+控制 OpenRouter 如何对可用 provider 排序。
+
+| 值 | 说明 |
+|-------|-------------|
+| `"price"` | 最便宜的 provider 优先 |
+| `"throughput"` | 每秒 token 数最高的 provider 优先 |
+| `"latency"` | 首 token 延迟最低的 provider 优先 |
+
+```yaml
+provider_routing:
+  sort: "price"
+```
+
+### `only`
+
+Provider 名称白名单。设置后，**仅**使用这些 provider，其余全部排除。
+
+```yaml
+provider_routing:
+  only:
+    - "Anthropic"
+    - "Google"
+```
+
+### `ignore`
+
+Provider 名称黑名单。这些 provider **永远不会**被使用，即使它们提供最低价格或最快速度。
+
+```yaml
+provider_routing:
+  ignore:
+    - "Together"
+    - "DeepInfra"
+```
+
+### `order`
+
+显式优先级顺序。列在前面的 provider 优先使用，未列出的 provider 作为备选。
+
+```yaml
+provider_routing:
+  order:
+    - "Anthropic"
+    - "Google"
+    - "AWS Bedrock"
+```
+
+### `require_parameters`
+
+设为 `true` 时，OpenRouter 仅路由到支持请求中**所有**参数（如 `temperature`、`top_p`、`tools` 等）的 provider，避免参数被静默丢弃。
+
+```yaml
+provider_routing:
+  require_parameters: true
+```
+
+### `data_collection`
+
+控制 provider 是否可将你的 prompt（提示词）用于训练。可选值为 `"allow"` 或 `"deny"`。
+
+```yaml
+provider_routing:
+  data_collection: "deny"
+```
+
+## 实用示例
+
+### 优化成本
+
+路由到最便宜的可用 provider，适合高频使用和开发场景：
+
+```yaml
+provider_routing:
+  sort: "price"
+```
+
+### 优化速度
+
+优先选择低延迟 provider，适合交互式使用：
+
+```yaml
+provider_routing:
+  sort: "latency"
+```
+
+### 优化吞吐量
+
+适合长文本生成，token 每秒速率至关重要的场景：
+
+```yaml
+provider_routing:
+  sort: "throughput"
+```
+
+### 锁定特定 Provider
+
+确保所有请求都通过特定 provider 处理，以保证一致性：
+
+```yaml
+provider_routing:
+  only:
+    - "Anthropic"
+```
+
+### 排除特定 Provider
+
+排除不希望使用的 provider（例如出于数据隐私考虑）：
+
+```yaml
+provider_routing:
+  ignore:
+    - "Together"
+    - "Lepton"
+  data_collection: "deny"
+```
+
+### 带备选的优先顺序
+
+优先尝试首选 provider，不可用时回退到其他 provider：
+
+```yaml
+provider_routing:
+  order:
+    - "Anthropic"
+    - "Google"
+  require_parameters: true
+```
+
+## 工作原理
+
+Provider routing 偏好通过每次 API 调用的 `extra_body.provider` 字段传递给 OpenRouter API，适用于以下两种模式：
+
+- **CLI 模式** — 在 `~/.hermes/config.yaml` 中配置，启动时加载
+- **Gateway 模式** — 同一配置文件，gateway 启动时加载
+
+路由配置从 `config.yaml` 读取，并在创建 `AIAgent` 时作为参数传入：
+
+```
+providers_allowed  ← 来自 provider_routing.only
+providers_ignored  ← 来自 provider_routing.ignore
+providers_order    ← 来自 provider_routing.order
+provider_sort      ← 来自 provider_routing.sort
+provider_require_parameters ← 来自 provider_routing.require_parameters
+provider_data_collection    ← 来自 provider_routing.data_collection
+```
+
+:::tip
+可以组合使用多个选项。例如，按价格排序，同时排除某些 provider 并要求参数支持：
+
+```yaml
+provider_routing:
+  sort: "price"
+  ignore: ["Together"]
+  require_parameters: true
+  data_collection: "deny"
+```
+:::
+
+## 默认行为
+
+未配置 `provider_routing` 部分时（默认情况），OpenRouter 使用其自身的默认路由逻辑，通常会自动在成本和可用性之间取得平衡。
+
+:::tip Provider Routing 与 Fallback Models
+Provider routing 控制 OpenRouter **内部的子 provider** 如何处理你的请求。若需要在主模型失败时自动故障转移到完全不同的 provider，请参阅 [Fallback Providers](/user-guide/features/fallback-providers)。
+:::