better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/open-webui.md

@@ -0,0 +1,296 @@
+---
+sidebar_position: 8
+title: "Open WebUI"
+description: "通过 OpenAI 兼容 API 服务器将 Open WebUI 连接到 Hermes Agent"
+---
+
+# Open WebUI 集成
+
+[Open WebUI](https://github.com/open-webui/open-webui)（126k★）是最受欢迎的自托管 AI 聊天界面。借助 Hermes Agent 内置的 API 服务器，你可以将 Open WebUI 用作 agent 的精美 Web 前端——完整支持对话管理、用户账户和现代聊天界面。
+
+## 架构
+
+```mermaid
+flowchart LR
+    A["Open WebUI<br/>浏览器 UI<br/>端口 3000"]
+    B["hermes-agent<br/>gateway API 服务器<br/>端口 8642"]
+    A -->|POST /v1/chat/completions| B
+    B -->|SSE 流式响应| A
+```
+
+Open WebUI 连接 Hermes Agent 的 API 服务器，方式与连接 OpenAI 完全相同。Hermes 使用其完整工具集——终端、文件操作、网络搜索、记忆、技能——处理请求并返回最终响应。
+
+:::important 运行时位置
+API 服务器是一个 **Hermes agent 运行时**，而非纯 LLM 代理。对于每个请求，Hermes 会在 API 服务器所在主机上创建一个服务端 `AIAgent`。工具调用在该 API 服务器运行的位置执行。
+
+例如，如果笔记本电脑将 Open WebUI 或其他 OpenAI 兼容客户端指向远程机器上的 Hermes API 服务器，则 `pwd`、文件工具、浏览器工具、本地 MCP 工具及其他工作区工具将在远程 API 服务器主机上运行，而非在笔记本电脑上。
+:::
+
+Open WebUI 与 Hermes 之间是服务器到服务器的通信，因此此集成无需配置 `API_SERVER_CORS_ORIGINS`。
+
+## 快速设置
+
+### 1. 启用 API 服务器
+
+```bash
+hermes config set API_SERVER_ENABLED true
+hermes config set API_SERVER_KEY your-secret-key
+```
+
+`hermes config set` 会自动将标志路由到 `config.yaml`，将密钥路由到 `~/.hermes/.env`。如果 gateway 已在运行，请重启以使更改生效：
+
+```bash
+hermes gateway stop && hermes gateway
+```
+
+### 2. 启动 Hermes Agent gateway
+
+```bash
+hermes gateway
+```
+
+你应该看到：
+
+```
+[API Server] API server listening on http://127.0.0.1:8642
+```
+
+### 3. 验证 API 服务器可访问
+
+```bash
+curl -s http://127.0.0.1:8642/health
+# {"status": "ok", ...}
+
+curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
+# {"object":"list","data":[{"id":"hermes-agent", ...}]}
+```
+
+如果 `/health` 失败，说明 gateway 未加载 `API_SERVER_ENABLED=true`——重启它。如果 `/v1/models` 返回 `401`，说明你的 `Authorization` 头与 `API_SERVER_KEY` 不匹配。
+
+### 4. 启动 Open WebUI
+
+```bash
+docker run -d -p 3000:8080 \
+  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
+  -e OPENAI_API_KEY=your-secret-key \
+  -e ENABLE_OLLAMA_API=false \
+  --add-host=host.docker.internal:host-gateway \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  ghcr.io/open-webui/open-webui:main
+```
+
+`ENABLE_OLLAMA_API=false` 会禁用默认的 Ollama 后端，否则它会显示为空并干扰模型选择器。如果你确实在同时运行 Ollama，可以省略此参数。
+
+首次启动需要 15–30 秒：Open WebUI 在第一次启动时会下载 sentence-transformer embedding（嵌入）模型（约 150MB）。请等待 `docker logs open-webui` 输出稳定后再打开 UI。
+
+### 5. 打开 UI
+
+访问 **http://localhost:3000** 。创建管理员账户（第一个用户将成为管理员）。你应该能在模型下拉列表中看到你的 agent（以你的 profile 命名，默认 profile 则显示为 **hermes-agent**）。开始聊天吧！
+
+## Docker Compose 设置
+
+如需更持久的设置，创建 `docker-compose.yml`：
+
+```yaml
+services:
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    ports:
+      - "3000:8080"
+    volumes:
+      - open-webui:/app/backend/data
+    environment:
+      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
+      - OPENAI_API_KEY=your-secret-key
+      - ENABLE_OLLAMA_API=false
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: always
+
+volumes:
+  open-webui:
+```
+
+然后：
+
+```bash
+docker compose up -d
+```
+
+## 通过管理员 UI 配置
+
+如果你更倾向于通过 UI 而非环境变量配置连接：
+
+1. 在 **http://localhost:3000** 登录 Open WebUI
+2. 点击你的**头像** → **Admin Settings**
+3. 进入 **Connections**
+4. 在 **OpenAI API** 下，点击**扳手图标**（Manage）
+5. 点击 **+ Add New Connection**
+6. 填写：
+   - **URL**：`http://host.docker.internal:8642/v1`
+   - **API Key**：与 Hermes 中 `API_SERVER_KEY` 完全相同的值
+7. 点击**对勾**验证连接
+8. **保存**
+
+你的 agent 模型现在应出现在模型下拉列表中（以你的 profile 命名，默认 profile 则显示为 **hermes-agent**）。
+
+:::warning
+环境变量仅在 Open WebUI **首次启动**时生效。此后，连接设置存储在其内部数据库中。如需后续修改，请使用管理员 UI，或删除 Docker 卷后重新启动。
+:::
+
+## API 类型：Chat Completions 与 Responses
+
+Open WebUI 连接后端时支持两种 API 模式：
+
+| 模式 | 格式 | 使用场景 |
+|------|--------|-------------|
+| **Chat Completions**（默认） | `/v1/chat/completions` | 推荐。开箱即用。 |
+| **Responses**（实验性） | `/v1/responses` | 通过 `previous_response_id` 实现服务端对话状态。 |
+
+### 使用 Chat Completions（推荐）
+
+这是默认模式，无需额外配置。Open WebUI 发送标准 OpenAI 格式请求，Hermes Agent 相应响应。每个请求包含完整的对话历史。
+
+### 使用 Responses API
+
+启用 Responses API 模式：
+
+1. 进入 **Admin Settings** → **Connections** → **OpenAI** → **Manage**
+2. 编辑你的 hermes-agent 连接
+3. 将 **API Type** 从 "Chat Completions" 改为 **"Responses (Experimental)"**
+4. 保存
+
+使用 Responses API 时，Open WebUI 以 Responses 格式发送请求（`input` 数组 + `instructions`），Hermes Agent 可通过 `previous_response_id` 在多轮对话中保留完整的工具调用历史。当 `stream: true` 时，Hermes 还会流式传输符合规范的 `function_call` 和 `function_call_output` 事件，这使得支持 Responses 事件渲染的客户端能够展示自定义结构化工具调用 UI。
+
+:::note
+Open WebUI 目前即使在 Responses 模式下也在客户端管理对话历史——它在每个请求中发送完整的消息历史，而非使用 `previous_response_id`。Responses 模式目前的主要优势在于结构化事件流：文本增量、`function_call` 和 `function_call_output` 事件以 OpenAI Responses SSE 事件形式到达，而非 Chat Completions 分块。
+:::
+
+## 工作原理
+
+当你在 Open WebUI 中发送消息时：
+
+1. Open WebUI 发送包含你的消息和对话历史的 `POST /v1/chat/completions` 请求
+2. Hermes Agent 使用 API 服务器的 profile、模型/提供商配置、记忆、技能和已配置的 API 服务器工具集，在服务端创建一个 `AIAgent` 实例
+3. Agent 处理你的请求——它可能在 API 服务器主机上调用工具（终端、文件操作、网络搜索等）
+4. 工具执行时，**内联进度消息会流式传输到 UI**，让你实时看到 agent 的操作（例如 `` `💻 ls -la` ``、`` `🔍 Python 3.12 release` ``）
+5. Agent 的最终文本响应流式返回给 Open WebUI
+6. Open WebUI 在聊天界面中显示响应
+
+你的 agent 可以访问该 API 服务器 Hermes 实例所拥有的相同工具和能力。如果 API 服务器是远程的，这些工具也是远程的。
+
+如果你今天需要工具在**本地**工作区运行，请在本地运行 Hermes 并将其指向纯 LLM 提供商或纯 OpenAI 兼容模型代理（例如 vLLM、LiteLLM、Ollama、llama.cpp、OpenAI、OpenRouter 等）。"远程大脑、本地执行"的分离运行时模式正在 [#18715](https://github.com/NousResearch/hermes-agent/issues/18715) 中跟踪；这不是当前 API 服务器的行为。
+
+:::tip 工具进度
+启用流式传输（默认）后，工具运行时你会看到简短的内联指示——工具 emoji 及其关键参数。这些内容在 agent 最终答案之前出现在响应流中，让你了解后台正在发生的事情。
+:::
+
+## 配置参考
+
+### Hermes Agent（API 服务器）
+
+| 变量 | 默认值 | 描述 |
+|----------|---------|-------------|
+| `API_SERVER_ENABLED` | `false` | 启用 API 服务器 |
+| `API_SERVER_PORT` | `8642` | HTTP 服务器端口 |
+| `API_SERVER_HOST` | `127.0.0.1` | 绑定地址 |
+| `API_SERVER_KEY` | _（必填）_ | 用于认证的 Bearer token（令牌）。需与 `OPENAI_API_KEY` 匹配。 |
+
+### Open WebUI
+
+| 变量 | 描述 |
+|----------|-------------|
+| `OPENAI_API_BASE_URL` | Hermes Agent 的 API URL（包含 `/v1`） |
+| `OPENAI_API_KEY` | 不能为空。需与你的 `API_SERVER_KEY` 匹配。 |
+
+## 故障排查
+
+### 下拉列表中没有模型
+
+- **检查 URL 是否有 `/v1` 后缀**：`http://host.docker.internal:8642/v1`（不只是 `:8642`）
+- **验证 gateway 是否运行**：`curl http://localhost:8642/health` 应返回 `{"status": "ok"}`
+- **检查模型列表**：`curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models` 应返回包含 `hermes-agent` 的列表
+- **Docker 网络**：在 Docker 内部，`localhost` 指容器本身，而非你的主机。请使用 `host.docker.internal` 或 `--network=host`。
+- **空 Ollama 后端遮挡选择器**：如果你省略了 `ENABLE_OLLAMA_API=false`，Open WebUI 会在你的 Hermes 模型上方显示一个空的 Ollama 区域。请使用 `-e ENABLE_OLLAMA_API=false` 重启容器，或在 **Admin Settings → Connections** 中禁用 Ollama。
+
+### 连接测试通过但模型无法加载
+
+这几乎总是因为缺少 `/v1` 后缀。Open WebUI 的连接测试只是基本的连通性检查——它不验证模型列表是否正常工作。
+
+### 响应耗时很长
+
+Hermes Agent 可能在生成最终响应之前执行了多次工具调用（读取文件、运行命令、搜索网络）。对于复杂查询，这是正常现象。响应会在 agent 完成后一次性出现。
+
+### "Invalid API key" 错误
+
+确保 Open WebUI 中的 `OPENAI_API_KEY` 与 Hermes Agent 中的 `API_SERVER_KEY` 匹配。
+
+:::warning
+Open WebUI 在首次启动后会将 OpenAI 兼容连接设置持久化到其自身数据库中。如果你在管理员 UI 中误保存了错误的密钥，仅修改环境变量是不够的——请在 **Admin Settings → Connections** 中更新或删除已保存的连接，或重置 Open WebUI 数据目录/数据库。
+:::
+
+## 多用户设置与 Profiles
+
+要为每个用户运行独立的 Hermes 实例——各自拥有独立的配置、记忆和技能——请使用 [profiles](/user-guide/profiles)。每个 profile 在不同端口上运行自己的 API 服务器，并自动将 profile 名称作为模型名称公告给 Open WebUI。
+
+### 1. 创建 profiles 并配置 API 服务器
+
+`API_SERVER_*` 是环境变量，而非 YAML 配置键，因此请将它们写入每个 profile 的 `.env`。选择默认平台范围之外的端口（`8644` 是 webhook 适配器，`8645` 是 wecom-callback，`8646` 是 msgraph-webhook），例如 `8650+`：
+
+```bash
+hermes profile create alice
+cat >> ~/.hermes/profiles/alice/.env <<EOF
+API_SERVER_ENABLED=true
+API_SERVER_PORT=8650
+API_SERVER_KEY=alice-secret
+EOF
+
+hermes profile create bob
+cat >> ~/.hermes/profiles/bob/.env <<EOF
+API_SERVER_ENABLED=true
+API_SERVER_PORT=8651
+API_SERVER_KEY=bob-secret
+EOF
+```
+
+### 2. 启动各 gateway
+
+```bash
+hermes -p alice gateway &
+hermes -p bob gateway &
+```
+
+### 3. 在 Open WebUI 中添加连接
+
+在 **Admin Settings** → **Connections** → **OpenAI API** → **Manage** 中，为每个 profile 添加一个连接：
+
+| 连接 | URL | API Key |
+|-----------|-----|---------|
+| Alice | `http://host.docker.internal:8650/v1` | `alice-secret` |
+| Bob | `http://host.docker.internal:8651/v1` | `bob-secret` |
+
+模型下拉列表将显示 `alice` 和 `bob` 作为独立模型。你可以通过管理员面板将模型分配给 Open WebUI 用户，为每个用户提供其独立的 Hermes agent。
+
+:::tip 自定义模型名称
+模型名称默认为 profile 名称。如需覆盖，请在 profile 的 `.env` 中设置 `API_SERVER_MODEL_NAME`：
+```bash
+hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"
+```
+:::
+
+## Linux Docker（无 Docker Desktop）
+
+在没有 Docker Desktop 的 Linux 上，`host.docker.internal` 默认无法解析。可选方案：
+
+```bash
+# 方案 1：添加主机映射
+docker run --add-host=host.docker.internal:host-gateway ...
+
+# 方案 2：使用主机网络
+docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...
+
+# 方案 3：使用 Docker bridge IP
+docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...
+```

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

@@ -0,0 +1,123 @@
+# QQ Bot
+
+通过**官方 QQ Bot API（v2）**将 Hermes 接入 QQ——支持私聊（C2C）、群组 @-提及、频道及直接消息，并具备语音转写功能。
+
+## 概述
+
+QQ Bot 适配器使用[官方 QQ Bot API](https://bot.q.qq.com/wiki/develop/api-v2/) 实现以下功能：
+
+- 通过持久 **WebSocket** 连接至 QQ Gateway（网关）接收消息
+- 通过 **REST API** 发送文本和 Markdown 回复
+- 下载并处理图片、语音消息及文件附件
+- 使用腾讯内置 ASR 或可配置的 STT（语音转文字）提供商转写语音消息
+
+## 前提条件
+
+1. **QQ Bot 应用** — 在 [q.qq.com](https://q.qq.com) 注册：
+   - 创建新应用并记录您的 **App ID** 和 **App Secret**
+   - 启用所需 intent（意图）：C2C 消息、群组 @-消息、频道消息
+   - 在沙盒模式下配置机器人以进行测试，或发布至生产环境
+
+2. **依赖项** — 适配器需要 `aiohttp` 和 `httpx`：
+   ```bash
+   pip install aiohttp httpx
+   ```
+
+## 配置
+
+### 交互式设置
+
+```bash
+hermes gateway setup
+```
+
+从平台列表中选择 **QQ Bot** 并按提示操作。
+
+### 手动配置
+
+在 `~/.hermes/.env` 中设置所需环境变量：
+
+```bash
+QQ_APP_ID=your-app-id
+QQ_CLIENT_SECRET=your-app-secret
+```
+
+## 环境变量
+
+| 变量 | 描述 | 默认值 |
+|---|---|---|
+| `QQ_APP_ID` | QQ Bot App ID（必填） | — |
+| `QQ_CLIENT_SECRET` | QQ Bot App Secret（必填） | — |
+| `QQBOT_HOME_CHANNEL` | 用于 cron/通知投递的 OpenID | — |
+| `QQBOT_HOME_CHANNEL_NAME` | 主频道显示名称 | `Home` |
+| `QQ_ALLOWED_USERS` | 允许私聊访问的用户 OpenID 列表（逗号分隔） | 开放（所有用户） |
+| `QQ_GROUP_ALLOWED_USERS` | 允许群组访问的群组 OpenID 列表（逗号分隔） | — |
+| `QQ_ALLOW_ALL_USERS` | 设为 `true` 以允许所有私聊 | `false` |
+| `QQ_PORTAL_HOST` | 覆盖 QQ portal 主机（沙盒路由设为 `sandbox.q.qq.com`） | `q.qq.com` |
+| `QQ_STT_API_KEY` | 语音转文字提供商的 API 密钥 | — |
+| `QQ_STT_BASE_URL` | （不直接读取——请在 `config.yaml` 中设置 `platforms.qqbot.extra.stt.baseUrl`） | n/a |
+| `QQ_STT_MODEL` | STT 模型名称 | `glm-asr` |
+
+## 高级配置
+
+如需精细控制，可在 `~/.hermes/config.yaml` 中添加平台设置：
+
+```yaml
+platforms:
+  qqbot:
+    enabled: true
+    extra:
+      app_id: "your-app-id"
+      client_secret: "your-secret"
+      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
+      dm_policy: "open"          # open | allowlist | disabled
+      allow_from:
+        - "user_openid_1"
+      group_policy: "open"       # open | allowlist | disabled
+      group_allow_from:
+        - "group_openid_1"
+      stt:
+        provider: "zai"          # zai (GLM-ASR), openai (Whisper), etc.
+        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
+        apiKey: "your-stt-key"
+        model: "glm-asr"
+```
+
+## 语音消息（STT）
+
+语音转写分两个阶段进行：
+
+1. **QQ 内置 ASR**（免费，始终优先尝试）——QQ 在语音消息附件中提供 `asr_refer_text`，使用腾讯自有语音识别
+2. **已配置的 STT 提供商**（备用）——若 QQ 的 ASR 未返回文本，适配器将调用兼容 OpenAI 的 STT API：
+
+   - **智谱/GLM（zai）**：默认提供商，使用 `glm-asr` 模型
+   - **OpenAI Whisper**：设置 `QQ_STT_BASE_URL` 和 `QQ_STT_MODEL`
+   - 任何兼容 OpenAI 的 STT 端点
+
+## 故障排查
+
+### 机器人立即断开连接（快速断连）
+
+通常原因如下：
+- **App ID / Secret 无效** — 在 q.qq.com 仔细核对您的凭据
+- **缺少权限** — 确保机器人已启用所需 intent
+- **仅限沙盒的机器人** — 若机器人处于沙盒模式，只能接收来自 QQ 沙盒测试频道的消息
+
+### 语音消息未被转写
+
+1. 检查附件数据中是否存在 QQ 内置的 `asr_refer_text`
+2. 若使用自定义 STT 提供商，验证 `QQ_STT_API_KEY` 是否正确设置
+3. 查看 gateway 日志中的 STT 错误信息
+
+### 消息未送达
+
+- 在 q.qq.com 验证机器人的 **intent** 是否已启用
+- 若私聊访问受限，检查 `QQ_ALLOWED_USERS`
+- 对于群组消息，确保机器人被 **@提及**（群组策略可能需要加入白名单）
+- 检查 `QQBOT_HOME_CHANNEL` 以确认 cron/通知投递配置
+
+### 连接错误
+
+- 确保已安装 `aiohttp` 和 `httpx`：`pip install aiohttp httpx`
+- 检查与 `api.sgroup.qq.com` 及 WebSocket gateway 的网络连通性
+- 查看 gateway 日志以获取详细错误信息和重连行为

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

@@ -0,0 +1,257 @@
+---
+sidebar_position: 6
+title: "Signal"
+description: "通过 signal-cli 守护进程将 Hermes Agent 设置为 Signal 机器人"
+---
+
+# Signal 配置
+
+Hermes 通过以 HTTP 模式运行的 [signal-cli](https://github.com/AsamK/signal-cli) 守护进程连接到 Signal。适配器通过 SSE（Server-Sent Events，服务器推送事件）实时接收消息，并通过 JSON-RPC 发送响应。
+
+Signal 是隐私保护最完善的主流即时通讯工具——默认端对端加密、开源协议、极少的元数据收集。这使其非常适合对安全性要求较高的 Agent 工作流。
+
+:::info 无需新增 Python 依赖
+Signal 适配器使用 `httpx`（已是 Hermes 的核心依赖）进行所有通信，无需安装额外的 Python 包。你只需在外部安装 signal-cli。
+:::
+
+---
+
+## 前提条件
+
+- **signal-cli** — 基于 Java 的 Signal 客户端（[GitHub](https://github.com/AsamK/signal-cli)）
+- **Java 17+** 运行时 — signal-cli 所需
+- **一个已安装 Signal 的手机号**（用于作为辅助设备关联）
+
+### 安装 signal-cli
+
+```bash
+# macOS
+brew install signal-cli
+
+# Linux（下载最新版本）
+VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
+  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
+curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
+sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
+sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/
+```
+
+:::caution
+signal-cli **不在** apt 或 snap 仓库中。上述 Linux 安装方式直接从 [GitHub releases](https://github.com/AsamK/signal-cli/releases) 下载。
+:::
+
+---
+
+## 第一步：关联你的 Signal 账号
+
+signal-cli 作为**关联设备**运行——类似 WhatsApp Web，但用于 Signal。你的手机仍是主设备。
+
+```bash
+# 生成关联 URI（显示二维码或链接）
+signal-cli link -n "HermesAgent"
+```
+
+1. 在手机上打开 **Signal**
+2. 进入 **设置 → 关联设备**
+3. 点击 **关联新设备**
+4. 扫描二维码或输入 URI
+
+---
+
+## 第二步：启动 signal-cli 守护进程
+
+```bash
+# 将 +1234567890 替换为你的 Signal 手机号（E.164 格式）
+signal-cli --account +1234567890 daemon --http 127.0.0.1:8080
+```
+
+:::tip
+保持此进程在后台运行。你可以使用 `systemd`、`tmux`、`screen`，或将其作为服务运行。
+:::
+
+验证是否正在运行：
+
+```bash
+curl http://127.0.0.1:8080/api/v1/check
+# 应返回：{"versions":{"signal-cli":...}}
+```
+
+---
+
+## 第三步：配置 Hermes
+
+最简单的方式：
+
+```bash
+hermes gateway setup
+```
+
+从平台菜单中选择 **Signal**。向导将：
+
+1. 检查 signal-cli 是否已安装
+2. 提示输入 HTTP URL（默认：`http://127.0.0.1:8080`）
+3. 测试与守护进程的连通性
+4. 询问你的账号手机号
+5. 配置允许的用户和访问策略
+
+### 手动配置
+
+在 `~/.hermes/.env` 中添加：
+
+```bash
+# 必填
+SIGNAL_HTTP_URL=http://127.0.0.1:8080
+SIGNAL_ACCOUNT=+1234567890
+
+# 安全设置（推荐）
+SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # 逗号分隔的 E.164 号码或 UUID
+
+# 可选
+SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # 启用群组（省略则禁用，* 表示全部）
+SIGNAL_HOME_CHANNEL=+1234567890                  # cron 任务的默认投递目标
+```
+
+然后启动 gateway：
+
+```bash
+hermes gateway              # 前台运行
+hermes gateway install      # 安装为用户服务
+sudo hermes gateway install --system   # 仅 Linux：开机自启系统服务
+```
+
+---
+
+## 访问控制
+
+### 私信访问
+
+私信访问遵循与其他 Hermes 平台相同的模式：
+
+1. **已设置 `SIGNAL_ALLOWED_USERS`** → 仅允许这些用户发送消息
+2. **未设置白名单** → 未知用户会收到私信配对码（通过 `hermes pairing approve signal CODE` 审批）
+3. **`SIGNAL_ALLOW_ALL_USERS=true`** → 任何人均可发送消息（谨慎使用）
+
+### 群组访问
+
+群组访问由 `SIGNAL_GROUP_ALLOWED_USERS` 环境变量控制：
+
+| 配置 | 行为 |
+|------|------|
+| 未设置（默认） | 忽略所有群组消息，机器人仅响应私信。 |
+| 设置群组 ID | 仅监听列出的群组（如 `groupId1,groupId2`）。 |
+| 设置为 `*` | 机器人在其所在的任意群组中均会响应。 |
+
+---
+
+## 功能特性
+
+### 附件
+
+适配器支持双向收发媒体文件。
+
+**接收**（用户 → Agent）：
+
+- **图片** — PNG、JPEG、GIF、WebP（通过魔数自动检测）
+- **音频** — MP3、OGG、WAV、M4A（若已配置 Whisper，语音消息将自动转录）
+- **文档** — PDF、ZIP 及其他文件类型
+
+**发送**（Agent → 用户）：
+
+Agent 可通过响应中的 `MEDIA:` 标签发送媒体文件，支持以下投递方式：
+
+- **图片** — `send_multiple_images` 和 `send_image_file` 将 PNG、JPEG、GIF、WebP 作为原生 Signal 附件发送
+- **语音** — `send_voice` 将音频文件（OGG、MP3、WAV、M4A、AAC）作为附件发送
+- **视频** — `send_video` 发送 MP4 视频文件
+- **文档** — `send_document` 发送任意文件类型（PDF、ZIP 等）
+
+所有外发媒体均通过 Signal 标准附件 API 处理。与某些平台不同，Signal 在协议层面不区分语音消息和文件附件。
+
+附件大小限制：**100 MB**（双向）。
+
+:::warning
+**Signal 服务器会对附件上传进行速率限制**，适配器使用调度器批量发送多张图片，每批最多 32 张，并按照 Signal 服务器策略限速上传。
+:::
+
+### 原生格式、引用回复与表情回应
+
+Signal 消息以**原生格式**渲染，而非显示原始 markdown 字符。适配器将 markdown（`**粗体**`、`*斜体*`、`` `代码` ``、`~~删除线~~`、`||剧透||`、标题）转换为 Signal `bodyRanges`，使文本在接收方客户端以真实样式显示，而非可见的 `**` 或 `` ` `` 字符。
+
+**引用回复。** 当 Hermes 回复某条特定消息时，会发送原生引用回复——与 Signal 用户使用"回复"功能时看到的 UI 效果相同。对于响应入站消息而生成的回复，此功能自动生效。
+
+**表情回应。** Agent 可通过标准 reaction API 对消息添加表情回应；回应会以 emoji 形式显示在被引用消息上，而非额外的文字。
+
+以上功能无需额外配置——在近期的 signal-cli 版本中默认启用。若你的 `signal-cli` 版本过旧，Hermes 会回退到纯文本投递，并记录一次性警告日志。
+
+### 长消息
+
+Signal 单条消息上限为 **8,000 字符**。Hermes 会自动将更长的回复拆分为带编号的分段（`(1/3)`、`(2/3)`……）发送，而不是截断内容。此行为覆盖所有投递路径——实时对话回复、cron 任务投递、`hermes send` 以及 MCP `send_message` 调用——且原生格式（加粗、斜体、代码、剧透）在分段边界处保持不变。
+
+### 正在输入指示器
+
+机器人在处理消息时会发送正在输入指示器，每 8 秒刷新一次。
+
+### 手机号脱敏
+
+所有手机号在日志中自动脱敏：
+- `+15551234567` → `+155****4567`
+- 适用于 Hermes gateway 日志和全局脱敏系统
+
+### 给自己发消息（单号码配置）
+
+如果你将 signal-cli 作为自己手机号的**关联辅助设备**运行（而非单独的机器人号码），可以通过 Signal 的"给自己发消息"功能与 Hermes 交互。
+
+只需从手机向自己发送消息——signal-cli 会接收到该消息，Hermes 在同一会话中响应。
+
+**工作原理：**
+- "给自己发消息"以 `syncMessage.sentMessage` 信封形式到达
+- 适配器检测到这些消息是发给机器人自身账号的，并将其作为普通入站消息处理
+- 回声保护（已发时间戳追踪）防止无限循环——机器人自身的回复会被自动过滤
+
+**无需额外配置。** 只要 `SIGNAL_ACCOUNT` 与你的手机号匹配，此功能自动生效。
+
+### 健康监控
+
+适配器监控 SSE 连接，并在以下情况自动重连：
+- 连接断开（指数退避：2s → 60s）
+- 120 秒内无任何活动（向 signal-cli 发送 ping 以验证连通性）
+
+---
+
+## 故障排查
+
+| 问题 | 解决方案 |
+|------|----------|
+| 配置时提示 **"Cannot reach signal-cli"** | 确保 signal-cli 守护进程正在运行：`signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080` |
+| **消息未收到** | 检查 `SIGNAL_ALLOWED_USERS` 是否包含发送方号码（E.164 格式，带 `+` 前缀） |
+| **"signal-cli not found on PATH"** | 安装 signal-cli 并确保其在 PATH 中，或使用 Docker |
+| **连接持续断开** | 检查 signal-cli 日志中的错误信息，确保已安装 Java 17+。 |
+| **群组消息被忽略** | 使用具体群组 ID 配置 `SIGNAL_GROUP_ALLOWED_USERS`，或设为 `*` 允许所有群组。 |
+| **机器人对所有人无响应** | 配置 `SIGNAL_ALLOWED_USERS`，使用私信配对，或通过 gateway 策略显式允许所有用户（如需更广泛的访问权限）。 |
+| **消息重复** | 确保只有一个 signal-cli 实例在监听你的手机号 |
+
+---
+
+## 安全
+
+:::warning
+**务必配置访问控制。** 机器人默认具有终端访问权限。若未设置 `SIGNAL_ALLOWED_USERS` 或私信配对，gateway 会拒绝所有入站消息作为安全措施。
+:::
+
+- 手机号在所有日志输出中均已脱敏
+- 使用私信配对或显式白名单安全地引导新用户
+- 除非明确需要群组支持，否则保持群组禁用状态，或仅将受信任的群组加入白名单
+- Signal 的端对端加密保护传输中的消息内容
+- `~/.local/share/signal-cli/` 中的 signal-cli 会话数据包含账号凭据——请像保护密码一样保护它
+
+---
+
+## 环境变量参考
+
+| 变量 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `SIGNAL_HTTP_URL` | 是 | — | signal-cli HTTP 端点 |
+| `SIGNAL_ACCOUNT` | 是 | — | 机器人手机号（E.164） |
+| `SIGNAL_ALLOWED_USERS` | 否 | — | 逗号分隔的手机号/UUID |
+| `SIGNAL_GROUP_ALLOWED_USERS` | 否 | — | 要监听的群组 ID，或 `*` 表示全部（省略则禁用群组） |
+| `SIGNAL_ALLOW_ALL_USERS` | 否 | `false` | 允许任意用户交互（跳过白名单） |
+| `SIGNAL_HOME_CHANNEL` | 否 | — | cron 任务的默认投递目标 |