better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/gateway-internals.md

@@ -0,0 +1,267 @@
+---
+sidebar_position: 7
+title: "Gateway 内部机制"
+description: "消息 gateway 如何启动、授权用户、路由会话以及投递消息"
+---
+
+# Gateway 内部机制
+
+消息 gateway 是一个长期运行的进程，通过统一架构将 Hermes 连接到 20 余个外部消息平台。
+
+## 关键文件
+
+| 文件 | 用途 |
+|------|---------|
+| `gateway/run.py` | `GatewayRunner` — 主循环、斜杠命令、消息分发（大文件；请查看 git 获取当前行数） |
+| `gateway/session.py` | `SessionStore` — 会话持久化与会话键构造 |
+| `gateway/delivery.py` | 向目标平台/频道投递出站消息 |
+| `gateway/pairing.py` | 用于用户授权的 DM 配对流程 |
+| `gateway/channel_directory.py` | 将聊天 ID 映射为可读名称，用于 cron 投递 |
+| `gateway/hooks.py` | Hook（钩子）发现、加载与生命周期事件分发 |
+| `gateway/mirror.py` | 为 `send_message` 提供跨会话消息镜像 |
+| `gateway/status.py` | 面向 profile 范围的 gateway 实例的 token 锁管理 |
+| `gateway/builtin_hooks/` | 始终注册的 hook 扩展点（当前未内置任何 hook） |
+| `gateway/platform_registry.py` | 适配器注册表、工厂，以及对捆绑平台插件的延迟（惰性）加载 |
+| `plugins/platforms/<name>/` | 捆绑的消息适配器（多数平台：`adapter.py` + `plugin.yaml`） |
+| `gateway/platforms/` | 共享的 `base.py` 与遗留/直接适配器（Signal、API server、webhooks 等） |
+
+## 架构概览
+
+```text
+┌─────────────────────────────────────────────────┐
+│                  GatewayRunner                  │
+│                                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
+│  │ Telegram │  │ Discord  │  │  Slack   │       │
+│  │ Adapter  │  │ Adapter  │  │ Adapter  │       │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
+│       │             │             │             │
+│       └─────────────┼─────────────┘             │
+│                     ▼                           │
+│              _handle_message()                  │
+│                     │                           │
+│         ┌───────────┼───────────┐               │
+│         ▼           ▼           ▼               │
+│  Slash command   AIAgent    Queue/BG            │
+│    dispatch      creation   sessions            │
+│                     │                           │
+│                     ▼                           │
+│                 SessionStore                    │
+│              (SQLite persistence)               │
+└───────┴─────────────┴─────────────┴─────────────┘
+```
+
+## 消息流程
+
+当消息从任意平台到达时：
+
+1. **平台适配器**接收原始事件，将其规范化为 `MessageEvent`
+2. **基础适配器**检查活跃会话守卫：
+   - 若该会话的 agent 正在运行 → 将消息加入队列，设置中断事件
+   - 若为 `/approve`、`/deny`、`/stop` → 绕过守卫（内联分发）
+3. **GatewayRunner._handle_message()** 接收事件：
+   - 通过 `_session_key_for_source()` 解析会话键（格式：`agent:main:{platform}:{chat_type}:{chat_id}`）
+   - 检查授权（见下方授权章节）
+   - 检查是否为斜杠命令 → 分发至命令处理器
+   - 检查 agent 是否已在运行 → 拦截 `/stop`、`/status` 等命令
+   - 否则 → 创建 `AIAgent` 实例并运行对话
+4. **响应**通过平台适配器回传
+
+### 会话键格式
+
+会话键编码了完整的路由上下文：
+
+```
+agent:main:{platform}:{chat_type}:{chat_id}
+```
+
+示例：`agent:main:telegram:private:123456789`
+
+支持线程的平台（Telegram 论坛话题、Discord 线程、Slack 线程）可能在 chat_id 部分包含线程 ID。**切勿手动构造会话键** — 请始终使用 `gateway/session.py` 中的 `build_session_key()`。
+
+### 两级消息守卫
+
+当 agent 正在运行时，传入消息会依次经过两级守卫：
+
+1. **第一级 — 基础适配器**（`gateway/platforms/base.py`）：检查 `_active_sessions`。若会话处于活跃状态，将消息加入 `_pending_messages` 队列并设置中断事件。此级在消息到达 gateway runner *之前*进行拦截。
+
+2. **第二级 — Gateway runner**（`gateway/run.py`）：检查 `_running_agents`。拦截特定命令（`/stop`、`/new`、`/queue`、`/status`、`/approve`、`/deny`）并进行相应路由。其余所有消息触发 `running_agent.interrupt()`。
+
+必须在 agent 被阻塞时到达 runner 的命令（如 `/approve`）通过 `await self._message_handler(event)` **内联**分发 — 绕过后台任务系统以避免竞态条件。
+
+## 授权
+
+Gateway 使用多层授权检查，按顺序评估：
+
+1. **平台级全量放行标志**（如 `TELEGRAM_ALLOW_ALL_USERS`）— 若设置，该平台所有用户均被授权
+2. **平台白名单**（如 `TELEGRAM_ALLOWED_USERS`）— 逗号分隔的用户 ID
+3. **DM 配对** — 已认证用户可通过配对码为新用户授权
+4. **全局放行标志**（`GATEWAY_ALLOW_ALL_USERS`）— 若设置，所有平台的所有用户均被授权
+5. **默认：拒绝** — 未授权用户被拒绝
+
+### DM 配对流程
+
+```text
+Admin: /pair
+Gateway: "Pairing code: ABC123. Share with the user."
+New user: ABC123
+Gateway: "Paired! You're now authorized."
+```
+
+配对状态持久化于 `gateway/pairing.py`，重启后仍然有效。
+
+## 斜杠命令分发
+
+Gateway 中所有斜杠命令均经过相同的解析流程：
+
+1. `hermes_cli/commands.py` 中的 `resolve_command()` 将输入映射为规范名称（处理别名、前缀匹配）
+2. 规范名称与 `GATEWAY_KNOWN_COMMANDS` 进行比对
+3. `_handle_message()` 中的处理器根据规范名称进行分发
+4. 部分命令受配置门控（`CommandDef` 上的 `gateway_config_gate`）
+
+### 运行中 Agent 守卫
+
+在 agent 处理消息期间不得执行的命令会被提前拒绝：
+
+```python
+if _quick_key in self._running_agents:
+    if canonical == "model":
+        return "⏳ Agent is running — wait for it to finish or /stop first."
+```
+
+绕过命令（`/stop`、`/new`、`/approve`、`/deny`、`/queue`、`/status`）具有特殊处理逻辑。
+
+## 配置来源
+
+Gateway 从多个来源读取配置：
+
+| 来源 | 提供内容 |
+|--------|-----------------|
+| `~/.hermes/.env` | API 密钥、bot token、平台凭据 |
+| `~/.hermes/config.yaml` | 模型设置、工具配置、显示选项 |
+| 环境变量 | 覆盖上述任意配置 |
+
+与 CLI（使用带硬编码默认值的 `load_cli_config()`）不同，gateway 通过 YAML 加载器直接读取 `config.yaml`。这意味着存在于 CLI 默认值字典但不在用户配置文件中的配置键，在 CLI 和 gateway 之间可能表现不同。
+
+## 平台适配器
+
+大多数消息平台以插件适配器形式位于 `plugins/platforms/<name>/adapter.py`；少数旧适配器仍直接位于 `gateway/platforms/`。它们都继承 `gateway/platforms/base.py` 中的 `BasePlatformAdapter`：
+
+```text
+plugins/platforms/                  # 插件打包的适配器（每个一个目录）
+├── telegram/adapter.py     # Telegram Bot API（长轮询或 webhook）
+├── discord/adapter.py      # Discord bot（通过 discord.py）
+├── slack/adapter.py        # Slack Socket Mode
+├── whatsapp/adapter.py     # WhatsApp Business Cloud API
+├── matrix/adapter.py       # Matrix（通过 mautrix，可选 E2EE）
+├── mattermost/adapter.py   # Mattermost WebSocket API
+├── email/adapter.py        # 电子邮件（通过 IMAP/SMTP）
+├── sms/adapter.py          # 短信（通过 Twilio）
+├── dingtalk/adapter.py     # 钉钉 WebSocket
+├── feishu/adapter.py       # 飞书/Lark WebSocket 或 webhook
+├── wecom/adapter.py        # 企业微信（WeCom）回调
+├── line/adapter.py         # LINE Messaging API
+├── teams/adapter.py        # Microsoft Teams
+├── irc/adapter.py          # IRC（作用域锁的标准示例）
+├── homeassistant/adapter.py # Home Assistant 对话集成
+└── …                       # google_chat、ntfy、photon、raft、simplex 等
+
+gateway/platforms/                  # 核心 base 与旧的直接适配器
+├── base.py              # BasePlatformAdapter — 所有平台的共享逻辑
+├── signal.py            # Signal（通过 signal-cli REST API）
+├── weixin.py            # 微信（个人版，通过 iLink Bot API）
+├── bluebubbles.py       # Apple iMessage（通过 BlueBubbles macOS 服务端）
+├── qqbot/               # QQ Bot（腾讯 QQ，通过官方 API v2，子包）
+├── yuanbao.py           # 元宝（腾讯）私信/群组适配器
+├── msgraph_webhook.py   # Microsoft Graph 变更通知 webhook（Teams、Outlook 等）
+├── webhook.py           # 入站/出站 webhook 适配器
+└── api_server.py        # REST API 服务器适配器
+```
+
+适配器实现统一接口：
+- `connect()` / `disconnect()` — 生命周期管理
+- `send_message()` — 出站消息投递
+- `on_message()` — 入站消息规范化 → `MessageEvent`
+
+### Token 锁
+
+使用唯一凭据连接的适配器在 `connect()` 中调用 `acquire_scoped_lock()`，在 `disconnect()` 中调用 `release_scoped_lock()`。这可防止两个 profile 同时使用同一 bot token。
+
+## 投递路径
+
+出站投递（`gateway/delivery.py`）处理以下场景：
+
+- **直接回复** — 将响应发回原始聊天
+- **主频道投递** — 将 cron 任务输出和后台结果路由至已配置的主频道
+- **显式目标投递** — `send_message` 工具指定 `telegram:-1001234567890`，或通过 [`hermes send` CLI](/guides/pipe-script-output) 封装同一工具供 shell 脚本使用
+- **跨平台投递** — 投递至与原始消息不同的平台
+
+Cron 任务投递**不会**镜像到 gateway 会话历史中 — 它们仅存在于各自的 cron 会话中。这是有意为之的设计选择，以避免消息交替违规。
+
+## Hooks
+
+Gateway hook 是响应生命周期事件的 Python 模块。
+
+### Gateway Hook 事件
+
+| 事件 | 触发时机 |
+|-------|-----------|
+| `gateway:startup` | Gateway 进程启动时 |
+| `session:start` | 新对话会话开始时 |
+| `session:end` | 会话完成或超时时 |
+| `session:reset` | 用户通过 `/new` 重置会话时 |
+| `agent:start` | Agent 开始处理消息时 |
+| `agent:step` | Agent 完成一次工具调用迭代时 |
+| `agent:end` | Agent 完成并返回响应时 |
+| `command:*` | 任意斜杠命令被执行时 |
+
+Hook 从 `gateway/builtin_hooks/`（扩展点 — 当前发行版中为空；`_register_builtin_hooks()` 是一个空操作存根）和 `~/.hermes/hooks/`（用户安装）中发现。每个 hook 是一个包含 `HOOK.yaml` 清单和 `handler.py` 的目录。
+
+## 内存提供者集成
+
+当内存提供者插件（如 Honcho）启用时：
+
+1. Gateway 为每条消息创建一个带会话 ID 的 `AIAgent`
+2. `MemoryManager` 使用会话上下文初始化提供者
+3. 提供者工具（如 `honcho_profile`、`viking_search`）通过以下路径路由：
+
+```text
+AIAgent._invoke_tool()
+  → self._memory_manager.handle_tool_call(name, args)
+    → provider.handle_tool_call(name, args)
+```
+
+4. 会话结束/重置时，`on_session_end()` 触发以进行清理和最终数据刷写
+
+### 内存刷写生命周期
+
+显式对话边界（例如 `/new`、`/reset` 或 `/resume`）会刷新并结束原会话。空闲时间和每日时间边界不会结束会话。
+
+TTL、LRU 和内存压力触发的资源缓存淘汰会先将缓存的对话记录提交给已配置的记忆提供者，再释放 agent 客户端。它不会关闭持久化对话：下一轮会重新加载相同的对话记录和会话标识。
+
+## 后台维护
+
+Gateway 在处理消息的同时运行周期性维护任务：
+
+- **Cron 计时** — 检查任务计划并触发到期任务
+- **会话维护** — 回收缓存资源，但不结束会话记录
+- **内存刷写** — 在软释放缓存前提交记忆
+- **缓存刷新** — 刷新模型列表和提供者状态
+
+## 进程管理
+
+Gateway 作为长期运行进程运行，管理方式如下：
+
+- `hermes gateway start` / `hermes gateway stop` — 手动控制
+- `systemctl`（Linux）或 `launchctl`（macOS）— 服务管理
+- PID 文件位于 `~/.hermes/gateway.pid` — 面向 profile 的进程追踪
+
+**Profile 范围 vs 全局**：`start_gateway()` 使用 profile 范围的 PID 文件。`hermes gateway stop` 仅停止当前 profile 的 gateway。`hermes gateway stop --all` 使用全局 `ps aux` 扫描来终止所有 gateway 进程（用于更新时）。
+
+## 相关文档
+
+- [会话存储](./session-storage.md)
+- [Cron 内部机制](./cron-internals.md)
+- [ACP 内部机制](./acp-internals.md)
+- [Agent 循环内部机制](./agent-loop.md)
+- [消息 Gateway（用户指南）](/user-guide/messaging)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/image-gen-provider-plugin.md

@@ -0,0 +1,288 @@
+---
+sidebar_position: 11
+title: "图像生成 Provider 插件"
+description: "如何为 Hermes Agent 构建图像生成后端插件"
+---
+
+# 构建图像生成 Provider 插件
+
+图像生成 provider 插件注册一个后端，用于处理所有 `image_generate` 工具调用——DALL·E、gpt-image、Grok、Flux、Imagen、Stable Diffusion、fal、Replicate、本地 ComfyUI 装置，任何后端均可。内置 provider（OpenAI、OpenAI-Codex、xAI）均以插件形式提供。你可以通过在 `plugins/image_gen/<name>/` 目录下放置一个目录来添加新的 provider，或覆盖内置 provider。
+
+:::tip
+图像生成是 Hermes 支持的多种**后端插件**之一。其他插件（各有更专用的 ABC）包括：[Memory Provider 插件](/developer-guide/memory-provider-plugin)、[Context Engine 插件](/developer-guide/context-engine-plugin) 和 [Model Provider 插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅 [构建 Hermes 插件](/developer-guide/plugins)。
+:::
+
+## 发现机制
+
+Hermes 在三个位置扫描图像生成后端：
+
+1. **内置** — `<repo>/plugins/image_gen/<name>/`（以 `kind: backend` 自动加载，始终可用）
+2. **用户** — `~/.hermes/plugins/image_gen/<name>/`（通过 `plugins.enabled` 选择启用）
+3. **Pip** — 声明了 `hermes_agent.plugins` 入口点的包
+
+每个插件的 `register(ctx)` 函数调用 `ctx.register_image_gen_provider(...)` — 将其注册到 `agent/image_gen_registry.py` 中的注册表。活跃 provider 由 `config.yaml` 中的 `image_gen.provider` 指定；`hermes tools` 会引导用户完成选择。
+
+`image_generate` 工具包装器向注册表请求活跃 provider 并分发调用。若未注册任何 provider，工具会显示一条有用的错误信息，指引用户使用 `hermes tools`。
+
+## 目录结构
+
+```
+plugins/image_gen/my-backend/
+├── __init__.py      # ImageGenProvider 子类 + register()
+└── plugin.yaml      # 包含 kind: backend 的清单文件
+```
+
+内置插件到此即完整。位于 `~/.hermes/plugins/image_gen/<name>/` 的用户插件需要在 `config.yaml` 的 `plugins.enabled` 中添加（或运行 `hermes plugins enable <name>`）。
+
+## ImageGenProvider ABC
+
+继承 `agent.image_gen_provider.ImageGenProvider`。唯一必须实现的成员是 `name` 属性和 `generate()` 方法——其他所有成员均有合理的默认值：
+
+```python
+# plugins/image_gen/my-backend/__init__.py
+from typing import Any, Dict, List, Optional
+import os
+
+from agent.image_gen_provider import (
+    DEFAULT_ASPECT_RATIO,
+    ImageGenProvider,
+    error_response,
+    resolve_aspect_ratio,
+    save_b64_image,
+    success_response,
+)
+
+
+class MyBackendImageGenProvider(ImageGenProvider):
+    @property
+    def name(self) -> str:
+        # Stable id used in image_gen.provider config. Lowercase, no spaces.
+        return "my-backend"
+
+    @property
+    def display_name(self) -> str:
+        # Human label shown in `hermes tools`. Defaults to name.title() if omitted.
+        return "My Backend"
+
+    def is_available(self) -> bool:
+        # Return False if credentials or deps are missing.
+        # The tool's availability gate calls this before dispatch.
+        if not os.environ.get("MY_BACKEND_API_KEY"):
+            return False
+        try:
+            import my_backend_sdk  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    def list_models(self) -> List[Dict[str, Any]]:
+        # Catalog shown in `hermes tools` model picker.
+        return [
+            {
+                "id": "my-model-fast",
+                "display": "My Model (Fast)",
+                "speed": "~5s",
+                "strengths": "Quick iteration",
+                "price": "$0.01/image",
+            },
+            {
+                "id": "my-model-hq",
+                "display": "My Model (HQ)",
+                "speed": "~30s",
+                "strengths": "Highest fidelity",
+                "price": "$0.04/image",
+            },
+        ]
+
+    def default_model(self) -> Optional[str]:
+        return "my-model-fast"
+
+    def get_setup_schema(self) -> Dict[str, Any]:
+        # Metadata for the `hermes tools` picker — keys to prompt for at setup.
+        return {
+            "name": "My Backend",
+            "badge": "paid",        # optional; shown as a short tag in the picker
+            "tag": "One-line description shown under the name",
+            "env_vars": [
+                {
+                    "key": "MY_BACKEND_API_KEY",
+                    "prompt": "My Backend API key",
+                    "url": "https://my-backend.example.com/api-keys",
+                },
+            ],
+        }
+
+    def generate(
+        self,
+        prompt: str,
+        aspect_ratio: str = DEFAULT_ASPECT_RATIO,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        prompt = (prompt or "").strip()
+        aspect_ratio = resolve_aspect_ratio(aspect_ratio)
+
+        if not prompt:
+            return error_response(
+                error="Prompt is required",
+                error_type="invalid_input",
+                provider=self.name,
+                prompt="",
+                aspect_ratio=aspect_ratio,
+            )
+
+        # Model selection precedence: env var → config → default. The helper
+        # _resolve_model() in the built-in openai plugin is a good reference.
+        model_id = kwargs.get("model") or self.default_model() or "my-model-fast"
+
+        try:
+            import my_backend_sdk
+            client = my_backend_sdk.Client(api_key=os.environ["MY_BACKEND_API_KEY"])
+            result = client.generate(
+                prompt=prompt,
+                model=model_id,
+                aspect_ratio=aspect_ratio,
+            )
+
+            # Two shapes supported:
+            #   - URL string: return it as `image`
+            #   - base64 data: save under $HERMES_HOME/cache/images/ via save_b64_image()
+            if result.get("image_b64"):
+                path = save_b64_image(
+                    result["image_b64"],
+                    prefix=self.name,
+                    extension="png",
+                )
+                image = str(path)
+            else:
+                image = result["image_url"]
+
+            return success_response(
+                image=image,
+                model=model_id,
+                prompt=prompt,
+                aspect_ratio=aspect_ratio,
+                provider=self.name,
+            )
+        except Exception as exc:
+            return error_response(
+                error=str(exc),
+                error_type=type(exc).__name__,
+                provider=self.name,
+                model=model_id,
+                prompt=prompt,
+                aspect_ratio=aspect_ratio,
+            )
+
+
+def register(ctx) -> None:
+    """Plugin entry point — called once at load time."""
+    ctx.register_image_gen_provider(MyBackendImageGenProvider())
+```
+
+## plugin.yaml
+
+```yaml
+name: my-backend
+version: 1.0.0
+description: My image backend — text-to-image via My Backend SDK
+author: Your Name
+kind: backend
+requires_env:
+  - MY_BACKEND_API_KEY
+```
+
+`kind: backend` 决定插件被路由到图像生成注册路径。`requires_env` 在 `hermes plugins install` 期间会提示用户输入。
+
+## ABC 参考
+
+完整契约位于 `agent/image_gen_provider.py`。通常需要覆盖的方法：
+
+| 成员 | 必须 | 默认值 | 用途 |
+|---|---|---|---|
+| `name` | ✅ | — | 在 `image_gen.provider` 配置中使用的稳定 id |
+| `display_name` | — | `name.title()` | 在 `hermes tools` 中显示的标签 |
+| `is_available()` | — | `True` | 缺少凭据/依赖时的拦截门控 |
+| `list_models()` | — | `[]` | `hermes tools` 模型选择器的目录 |
+| `default_model()` | — | `list_models()` 的第一项 | 未配置模型时的回退 |
+| `get_setup_schema()` | — | 最小值 | 选择器元数据 + 环境变量提示 |
+| `generate(prompt, aspect_ratio, **kwargs)` | ✅ | — | 实际调用 |
+
+## 响应格式
+
+`generate()` 必须返回通过 `success_response()` 或 `error_response()` 构建的字典。两者均位于 `agent/image_gen_provider.py`。
+
+**成功：**
+```python
+success_response(
+    image=<url-or-absolute-path>,
+    model=<model-id>,
+    prompt=<echoed-prompt>,
+    aspect_ratio="landscape" | "square" | "portrait",
+    provider=<your-provider-name>,
+    extra={...},  # optional backend-specific fields
+)
+```
+
+**错误：**
+```python
+error_response(
+    error="human-readable message",
+    error_type="provider_error" | "invalid_input" | "<exception class name>",
+    provider=<your-provider-name>,
+    model=<model-id>,
+    prompt=<prompt>,
+    aspect_ratio=<resolved aspect>,
+)
+```
+
+工具包装器将字典 JSON 序列化后传给 LLM。错误以工具结果的形式呈现；LLM 决定如何向用户解释。
+
+## 处理 base64 与 URL 输出
+
+部分后端返回图像 URL（fal、Replicate）；其他后端返回 base64 载荷（OpenAI gpt-image-2）。对于 base64 情况，使用 `save_b64_image()` — 它将文件写入 `$HERMES_HOME/cache/images/<prefix>_<timestamp>_<uuid>.<ext>` 并返回绝对 `Path`。将该路径（转为 `str`）作为 `image=` 传入 `success_response()`。Gateway 投递（Telegram 图片气泡、Discord 附件）同时识别 URL 和绝对路径。
+
+## 用户覆盖
+
+在 `~/.hermes/plugins/image_gen/<name>/` 放置一个用户插件，使其 `name` 属性与某个内置插件相同，并通过 `hermes plugins enable <name>` 启用——注册表采用后写入优先策略，你的版本将替换内置版本。适用于将 `openai` 插件指向私有代理，或替换自定义模型目录等场景。
+
+## 测试
+
+```bash
+export HERMES_HOME=/tmp/hermes-imggen-test
+mkdir -p $HERMES_HOME/plugins/image_gen/my-backend
+# …copy __init__.py + plugin.yaml into that dir…
+
+export MY_BACKEND_API_KEY=your-test-key
+hermes plugins enable my-backend
+
+# Pick it as the active provider
+echo "image_gen:" >> $HERMES_HOME/config.yaml
+echo "  provider: my-backend" >> $HERMES_HOME/config.yaml
+
+# Exercise it
+hermes -z "Generate an image of a corgi in a spacesuit"
+```
+
+或交互式操作：`hermes tools` → "Image Generation" → 选择 `my-backend` → 根据提示输入 API key。
+
+## 参考实现
+
+- **`plugins/image_gen/openai/__init__.py`** — gpt-image-2 以低/中/高三个档位作为三个虚拟模型 ID，共享同一 API 模型并使用不同的 `quality` 参数。适合参考单一后端下的分层模型设计 + config.yaml 优先级链。
+- **`plugins/image_gen/xai/__init__.py`** — 通过 xAI 的 Grok Imagine。不同的响应结构（URL 输出，目录更简单）。
+- **`plugins/image_gen/openai-codex/__init__.py`** — Codex 风格的 Responses API 变体，复用 OpenAI SDK 并使用不同的路由基础 URL。
+
+## 通过 pip 分发
+
+```toml
+# pyproject.toml
+[project.entry-points."hermes_agent.plugins"]
+my-backend-imggen = "my_backend_imggen_package"
+```
+
+`my_backend_imggen_package` 必须暴露一个顶层 `register` 函数。完整配置请参阅通用插件指南中的 [通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
+
+## 相关页面
+
+- [图像生成](/user-guide/features/image-generation) — 面向用户的功能文档
+- [插件概览](/user-guide/features/plugins) — 所有插件类型一览
+- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南