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/tts.md

@@ -0,0 +1,456 @@
+---
+sidebar_position: 9
+title: "语音与 TTS"
+description: "跨所有平台的文字转语音与语音消息转录"
+---
+
+# 语音与 TTS
+
+Hermes Agent 支持跨所有消息平台的文字转语音（TTS）输出和语音消息转录（STT）。
+
+:::tip Nous 订阅用户
+如果你拥有付费的 [Nous Portal](https://portal.nousresearch.com) 订阅，OpenAI TTS 可通过 **[Tool Gateway](tool-gateway.md)** 使用，无需单独的 OpenAI API 密钥。新安装可运行 `hermes setup --portal` 登录并一次性开启所有 gateway 工具；已有安装可通过 `hermes model` 或 `hermes tools` 选择 **Nous Subscription** 仅启用 TTS。
+:::
+
+## 文字转语音（TTS）
+
+支持十个提供商将文字转换为语音：
+
+| 提供商 | 质量 | 费用 | API 密钥 |
+|----------|---------|------|---------|
+| **Edge TTS**（默认） | 良好 | 免费 | 无需 |
+| **ElevenLabs** | 优秀 | 付费 | `ELEVENLABS_API_KEY` |
+| **OpenAI TTS** | 良好 | 付费 | `VOICE_TOOLS_OPENAI_KEY` |
+| **MiniMax TTS** | 优秀 | 付费 | `MINIMAX_API_KEY` |
+| **Mistral (Voxtral TTS)** | 优秀 | 付费 | `MISTRAL_API_KEY` |
+| **Google Gemini TTS** | 优秀 | 免费额度 | `GEMINI_API_KEY` |
+| **xAI TTS** | 优秀 | 付费 | `XAI_API_KEY` |
+| **NeuTTS** | 良好 | 免费（本地） | 无需 |
+| **KittenTTS** | 良好 | 免费（本地） | 无需 |
+| **Piper** | 良好 | 免费（本地） | 无需 |
+
+### 平台投递方式
+
+| 平台 | 投递方式 | 格式 |
+|----------|----------|--------|
+| Telegram | 语音气泡（内联播放） | Opus `.ogg` |
+| Discord | 语音气泡（Opus/OGG），回退为文件附件 | Opus/MP3 |
+| WhatsApp | 音频文件附件 | MP3 |
+| CLI | 保存至 `~/.hermes/audio_cache/` | MP3 |
+
+### 配置
+
+```yaml
+# In ~/.hermes/config.yaml
+tts:
+  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts" | "kittentts" | "piper"
+  speed: 1.0                    # Global speed multiplier (provider-specific settings override this)
+  edge:
+    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
+    speed: 1.0                  # Converted to rate percentage (+/-%)
+  elevenlabs:
+    voice_id: "pNInz6obpgDQGcFmaJgB"  # Adam
+    model_id: "eleven_multilingual_v2"
+  openai:
+    model: "gpt-4o-mini-tts"
+    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
+    base_url: "https://api.openai.com/v1"  # Override for OpenAI-compatible TTS endpoints
+    speed: 1.0                  # 0.25 - 4.0
+  minimax:
+    model: "speech-2.8-hd"     # speech-2.8-hd (default), speech-2.8-turbo
+    voice_id: "English_Graceful_Lady"  # See https://platform.minimax.io/faq/system-voice-id
+    speed: 1                    # 0.5 - 2.0
+    vol: 1                      # 0 - 10
+    pitch: 0                    # -12 - 12
+  mistral:
+    model: "voxtral-mini-tts-2603"
+    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul - Neutral (default)
+  gemini:
+    model: "gemini-2.5-flash-preview-tts"  # or gemini-2.5-pro-preview-tts
+    voice: "Kore"               # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, Gacrux, etc.
+  xai:
+    voice_id: "eve"             # or a custom voice ID — see docs below
+    language: "en"              # ISO 639-1 code
+    sample_rate: 24000          # 22050 / 24000 (default) / 44100 / 48000
+    bit_rate: 128000            # MP3 bitrate; only applies when codec=mp3
+    # base_url: "https://api.x.ai/v1"   # Override via XAI_BASE_URL env var
+  neutts:
+    ref_audio: ''
+    ref_text: ''
+    model: neuphonic/neutts-air-q4-gguf
+    device: cpu
+  kittentts:
+    model: KittenML/kitten-tts-nano-0.8-int8   # 25MB int8; also: kitten-tts-micro-0.8 (41MB), kitten-tts-mini-0.8 (80MB)
+    voice: Jasper                               # Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo
+    speed: 1.0                                  # 0.5 - 2.0
+    clean_text: true                            # Expand numbers, currencies, units
+  piper:
+    voice: en_US-lessac-medium                  # voice name (auto-downloaded) OR absolute path to .onnx
+    # voices_dir: ''                            # default: ~/.hermes/cache/piper-voices/
+    # use_cuda: false                           # requires onnxruntime-gpu
+    # length_scale: 1.0                         # 2.0 = twice as slow
+    # noise_scale: 0.667
+    # noise_w_scale: 0.8
+    # volume: 1.0                               # 0.5 = half as loud
+    # normalize_audio: true
+```
+
+**速度控制**：全局 `tts.speed` 值默认应用于所有提供商。每个提供商可用自身的 `speed` 设置覆盖它（例如 `tts.openai.speed: 1.5`）。提供商级别的速度优先于全局值。默认值为 `1.0`（正常速度）。
+
+
+### 输入长度限制
+
+每个提供商都有文档记录的单次请求输入字符上限。Hermes 在调用提供商前会截断文本，确保请求不会因长度错误而失败：
+
+| 提供商 | 默认上限（字符数） |
+|----------|---------------------|
+| Edge TTS | 5000 |
+| OpenAI | 4096 |
+| xAI | 15000 |
+| MiniMax | 10000 |
+| Mistral | 4000 |
+| Google Gemini | 5000 |
+| ElevenLabs | 取决于模型（见下文） |
+| NeuTTS | 2000 |
+| KittenTTS | 2000 |
+
+**ElevenLabs** 根据配置的 `model_id` 选择上限：
+
+| `model_id` | 上限（字符数） |
+|------------|-------------|
+| `eleven_flash_v2_5` | 40000 |
+| `eleven_flash_v2` | 30000 |
+| `eleven_multilingual_v2`（默认）、`eleven_multilingual_v1`、`eleven_english_sts_v2`、`eleven_english_sts_v1` | 10000 |
+| `eleven_v3`、`eleven_ttv_v3` | 5000 |
+| 未知模型 | 回退至提供商默认值（10000） |
+
+**按提供商覆盖**，在 TTS 配置的提供商节下使用 `max_text_length:`：
+
+```yaml
+tts:
+  openai:
+    max_text_length: 8192   # raise or lower the provider cap
+```
+
+仅接受正整数。零、负数、非数字或布尔值将回退至提供商默认值，因此错误的配置不会意外禁用截断。
+
+### Telegram 语音气泡与 ffmpeg
+
+Telegram 语音气泡需要 Opus/OGG 音频格式：
+
+- **OpenAI、ElevenLabs 和 Mistral** 原生输出 Opus，无需额外配置
+- **Edge TTS**（默认）输出 MP3，需要 **ffmpeg** 进行转换
+- **MiniMax TTS** 输出 MP3，需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
+- **Google Gemini TTS** 输出原始 PCM，使用 **ffmpeg** 直接编码为 Opus 以在 Telegram 显示语音气泡
+- **xAI TTS** 输出 MP3，需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
+- **NeuTTS** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
+- **KittenTTS** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
+- **Piper** 输出 WAV，同样需要 **ffmpeg** 转换以在 Telegram 显示语音气泡
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# macOS
+brew install ffmpeg
+
+# Fedora
+sudo dnf install ffmpeg
+```
+
+若未安装 ffmpeg，Edge TTS、MiniMax TTS、NeuTTS、KittenTTS 和 Piper 的音频将作为普通音频文件发送（可播放，但显示为矩形播放器而非语音气泡）。
+
+:::tip
+如果你希望在不安装 ffmpeg 的情况下使用语音气泡，请切换至 OpenAI、ElevenLabs 或 Mistral 提供商。
+:::
+
+### xAI 自定义声音（声音克隆）
+
+xAI 支持克隆你的声音并将其用于 TTS。在 [xAI Console](https://console.x.ai/team/default/voice/voice-library) 中创建自定义声音，然后在配置中设置生成的 `voice_id`：
+
+```yaml
+tts:
+  provider: xai
+  xai:
+    voice_id: "nlbqfwie"   # your custom voice ID
+```
+
+有关录制、支持格式和限制的详细信息，请参阅 [xAI Custom Voices 文档](https://docs.x.ai/developers/model-capabilities/audio/custom-voices)。
+
+### Piper（本地，支持 44 种语言）
+
+Piper 是来自 Open Home Foundation（Home Assistant 维护者）的快速本地神经网络 TTS 引擎。它完全在 CPU 上运行，支持 **44 种语言**的预训练声音，无需 API 密钥。
+
+**通过 `hermes tools` 安装** → Voice & TTS → Piper — Hermes 会自动为你运行 `pip install piper-tts`。或手动安装：`pip install piper-tts`。
+
+**切换至 Piper：**
+
+```yaml
+tts:
+  provider: piper
+  piper:
+    voice: en_US-lessac-medium
+```
+
+首次对未在本地缓存的声音进行 TTS 调用时，Hermes 会运行 `python -m piper.download_voices <name>` 并将模型（约 20-90MB，取决于质量等级）下载至 `~/.hermes/cache/piper-voices/`。后续调用将复用已缓存的模型。
+
+**选择声音。** [完整声音目录](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md) 涵盖英语、西班牙语、法语、德语、意大利语、荷兰语、葡萄牙语、俄语、波兰语、土耳其语、中文、阿拉伯语、印地语等——每种语言均有 `x_low` / `low` / `medium` / `high` 质量等级。可在 [rhasspy.github.io/piper-samples](https://rhasspy.github.io/piper-samples/) 试听声音样本。
+
+**使用预下载的声音。** 将 `tts.piper.voice` 设置为以 `.onnx` 结尾的绝对路径：
+
+```yaml
+tts:
+  piper:
+    voice: /path/to/my-custom-voice.onnx
+```
+
+**高级参数**（`tts.piper.length_scale` / `noise_scale` / `noise_w_scale` / `volume` / `normalize_audio`、`use_cuda`）与 Piper 的 `SynthesisConfig` 一一对应。在较旧的 `piper-tts` 版本上这些参数会被忽略。
+
+### 自定义命令提供商
+
+如果你想使用的 TTS 引擎未被原生支持（VoxCPM、MLX-Kokoro、XTTS CLI、声音克隆脚本，或任何其他暴露 CLI 的引擎），你可以将其作为**命令类型提供商**接入，无需编写任何 Python 代码。Hermes 将输入文本写入临时 UTF-8 文件，运行你的 shell 命令，并读取命令生成的音频文件。
+
+在 `tts.providers.<name>` 下声明一个或多个提供商，并通过 `tts.provider: <name>` 在它们之间切换——与切换 `edge` 和 `openai` 等内置提供商的方式相同。
+
+```yaml
+tts:
+  provider: voxcpm                 # pick any name under tts.providers
+  providers:
+    voxcpm:
+      type: command
+      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
+      output_format: mp3
+      timeout: 180
+      voice_compatible: true       # try to deliver as a Telegram voice bubble
+
+    mlx-kokoro:
+      type: command
+      command: "python -m mlx_kokoro --in {input_path} --out {output_path} --voice {voice}"
+      voice: af_sky
+      output_format: wav
+
+    piper-custom:                  # native Piper also supports custom .onnx via tts.piper.voice
+      type: command
+      command: "piper -m /path/to/custom.onnx -f {output_path} < {input_path}"
+      output_format: wav
+```
+
+#### 示例：Doubao（中文 seed-tts-2.0）
+
+如需通过字节跳动的 [seed-tts-2.0](https://www.volcengine.com/docs/6561/1257544) 双向流式 API 实现高质量中文 TTS，请安装 [`doubao-speech`](https://pypi.org/project/doubao-speech/) PyPI 包并将其作为命令提供商接入：
+
+```bash
+pip install doubao-speech
+export VOLCENGINE_APP_ID="your-app-id"
+export VOLCENGINE_ACCESS_TOKEN="your-access-token"
+```
+
+```yaml
+tts:
+  provider: doubao
+  providers:
+    doubao:
+      type: command
+      command: "doubao-speech say --text-file {input_path} --out {output_path}"
+      output_format: mp3
+      max_text_length: 1024
+      timeout: 30
+```
+
+凭据来自你的 shell 环境（`VOLCENGINE_APP_ID` / `VOLCENGINE_ACCESS_TOKEN`）或 `~/.doubao-speech/config.yaml`。通过在命令中添加 `--voice zh-female-warm`（或 `doubao-speech list-voices` 中的任何其他别名）来选择声音。`doubao-speech` 还内置了流式 ASR——有关 Hermes 集成，请参阅[下方的 STT 章节](#example-doubao--volcengine-asr)。源码和完整文档：[github.com/Hypnus-Yuan/doubao-speech](https://github.com/Hypnus-Yuan/doubao-speech)。
+
+#### 占位符
+
+你的命令模板可以引用以下占位符。Hermes 在渲染时会替换它们，并根据上下文（裸值 / 单引号 / 双引号）对每个值进行 shell 转义，因此包含空格和其他 shell 敏感字符的路径是安全的。
+
+| 占位符 | 含义 |
+|------------------|------------------------------------------------------|
+| `{input_path}` | Hermes 写入的临时 UTF-8 文本文件路径 |
+| `{text_path}` | `{input_path}` 的别名 |
+| `{output_path}` | 命令必须写入音频的路径 |
+| `{format}` | `mp3` / `wav` / `ogg` / `flac` |
+| `{voice}` | `tts.providers.<name>.voice`，未设置时为空 |
+| `{model}` | `tts.providers.<name>.model` |
+| `{speed}` | 解析后的速度倍率（提供商级别或全局） |
+
+使用 `{{` 和 `}}` 表示字面大括号。
+
+#### 可选键
+
+| 键 | 默认值 | 含义 |
+|--------------------|---------|------------------------------------------------------------------------------------------------------------|
+| `timeout` | `120` | 秒数；超时后进程树将被终止（Unix `killpg`，Windows `taskkill /T`）。 |
+| `output_format` | `mp3` | `mp3` / `wav` / `ogg` / `flac` 之一。若 Hermes 选择路径，则从输出扩展名自动推断。 |
+| `voice_compatible` | `false` | 为 `true` 时，Hermes 通过 ffmpeg 将 MP3/WAV 输出转换为 Opus/OGG，使 Telegram 渲染语音气泡。 |
+| `max_text_length` | `5000` | 渲染命令前，输入将被截断至此长度。 |
+| `voice` / `model` | 空 | 仅作为占位符值传递给命令。 |
+
+#### 行为说明
+
+- **内置名称始终优先。** `tts.providers.openai` 条目永远不会覆盖原生 OpenAI 提供商，因此任何用户配置都无法静默替换内置提供商。
+- **默认投递方式为文档。** 命令提供商在所有平台上均以普通音频附件投递。通过 `voice_compatible: true` 按提供商选择加入语音气泡投递。
+- **命令失败会暴露给 Agent。** 非零退出码、空输出或超时均会返回包含命令 stderr/stdout 的错误，便于你从对话中调试提供商。
+- **设置了 `command:` 时，`type: command` 为默认值。** 显式写出 `type: command` 是良好实践，但非必须；包含非空 `command` 字符串的条目会被视为命令提供商。
+- **`{input_path}` / `{text_path}` 可互换。** 使用在你的命令中读起来更自然的那个。
+
+#### 安全性
+
+命令类型提供商会以你的用户权限运行你配置的任何 shell 命令。Hermes 会对占位符值进行转义并强制执行配置的超时，但命令模板本身是受信任的本地输入——请像对待 PATH 中的 shell 脚本一样对待它。
+
+### Python 插件提供商
+
+对于无法用单个 shell 命令表达的 TTS 引擎——没有 CLI 的 Python SDK、流式引擎、声音列表 API、OAuth 刷新认证——可通过 `ctx.register_tts_provider()` 注册 Python 插件。该插件与[自定义命令提供商](#custom-command-providers)注册表**共存**（不替换）；选择适合你引擎的接入方式。
+
+#### 如何选择
+
+| 你的后端具有… | 使用 |
+|---|---|
+| 单个 CLI，从文件/stdin 读取文本并将音频写入文件/stdout | **命令提供商**（无需 Python） |
+| 两三个通过 shell 管道串联的 CLI | **命令提供商** |
+| 仅有 Python SDK，没有 CLI | **插件** |
+| 你希望分块投递的流式字节（生成中的语音气泡） | **插件**（覆盖 `stream()`） |
+| `hermes setup` 使用的声音列表 API | **插件**（覆盖 `list_voices()`） |
+| OAuth 刷新流程（非静态 bearer token） | **插件** |
+
+内置提供商始终优先，命令提供商优先于同名插件——因此插件可以安全地注册任何非内置名称，无需担心覆盖现有配置。
+
+#### 最小插件
+
+将以下内容放入 `~/.hermes/plugins/my-tts/`：
+
+`plugin.yaml`：
+```yaml
+name: my-tts
+version: 0.1.0
+description: "My custom Python TTS backend"
+```
+
+`__init__.py`：
+```python
+from agent.tts_provider import TTSProvider
+
+
+class MyTTSProvider(TTSProvider):
+    @property
+    def name(self) -> str:
+        return "my-tts"  # what tts.provider matches against
+
+    @property
+    def display_name(self) -> str:
+        return "My Custom TTS"
+
+    def is_available(self) -> bool:
+        # Return False when credentials/deps are missing — picker skips
+        # this row but the dispatcher still routes here on explicit config.
+        import os
+        return bool(os.environ.get("MY_TTS_API_KEY"))
+
+    def synthesize(self, text, output_path, *, voice=None, model=None,
+                   speed=None, format="mp3", **extra) -> str:
+        # Write audio bytes to output_path, return the path.
+        # Raise on failure — the dispatcher converts exceptions to a
+        # standard error envelope.
+        import my_tts_sdk
+        client = my_tts_sdk.Client()
+        audio_bytes = client.synthesize(text=text, voice=voice or "default")
+        with open(output_path, "wb") as f:
+            f.write(audio_bytes)
+        return output_path
+
+
+def register(ctx):
+    ctx.register_tts_provider(MyTTSProvider())
+```
+
+启用它（`hermes plugins enable my-tts`），将 `tts.provider` 指向它（在 `config.yaml` 中设置 `tts.provider: my-tts`），`text_to_speech` 工具将通过你的插件路由。
+
+#### 可选 hook
+
+在你的提供商类上覆盖以下方法以获得更丰富的集成：
+
+- `list_voices()` → 返回 `{id, display, language, gender, preview_url}` 字典列表，显示在 `hermes tools` 中。
+- `list_models()` → 返回 `{id, display, languages, max_text_length}` 字典列表。
+- `get_setup_schema()` → 返回 `{name, badge, tag, env_vars: [{key, prompt, url}]}` 以驱动 `hermes tools` / `hermes setup` 中的选择器行。若不提供，插件仍可正常工作，但其在选择器中的行信息会很简略。
+- `stream(text, *, voice, model, format, **extra)` → 迭代器，产出音频字节用于流式投递（默认抛出 `NotImplementedError`）。
+- `voice_compatible` 属性 → 若你的输出与 Opus 兼容且 gateway 应将其作为语音气泡投递，则设为 `True`（默认 `False` = 普通音频附件）。
+
+完整的抽象基类（含文档字符串）请参阅 `agent/tts_provider.py`。
+
+## 语音消息转录（STT）
+
+在 Telegram、Discord、WhatsApp、Slack 或 Signal 上发送的语音消息会被自动转录并作为文本注入对话。Agent 将转录内容视为普通文本。
+
+| 提供商 | 质量 | 费用 | API 密钥 |
+|----------|---------|------|---------| 
+| **本地 Whisper**（默认） | 良好 | 免费 | 无需 |
+| **Groq Whisper API** | 良好至最佳 | 免费额度 | `GROQ_API_KEY` |
+| **OpenAI Whisper API** | 良好至最佳 | 付费 | `VOICE_TOOLS_OPENAI_KEY` 或 `OPENAI_API_KEY` |
+
+:::info 零配置
+安装了 `faster-whisper` 后，本地转录即可开箱即用。若不可用，Hermes 也可使用常见安装位置（如 `/opt/homebrew/bin`）的本地 `whisper` CLI，或通过 `HERMES_LOCAL_STT_COMMAND` 指定的自定义命令。
+:::
+
+### 配置
+
+```yaml
+# In ~/.hermes/config.yaml
+stt:
+  provider: "local"           # "local" | "groq" | "openai" | "mistral" | "xai"
+  local:
+    model: "base"             # tiny, base, small, medium, large-v3
+  openai:
+    model: "whisper-1"        # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe, gpt-transcribe
+  mistral:
+    model: "voxtral-mini-latest"  # voxtral-mini-latest, voxtral-mini-2602
+  xai:
+    model: "grok-stt"         # xAI Grok STT
+```
+
+### 提供商详情
+
+**本地（faster-whisper）** — 通过 [faster-whisper](https://github.com/SYSTRAN/faster-whisper) 在本地运行 Whisper。默认使用 CPU，有 GPU 时使用 GPU。模型大小：
+
+| 模型 | 大小 | 速度 | 质量 |
+|-------|------|-------|---------|
+| `tiny` | ~75 MB | 最快 | 基础 |
+| `base` | ~150 MB | 快 | 良好（默认） |
+| `small` | ~500 MB | 中等 | 较好 |
+| `medium` | ~1.5 GB | 较慢 | 优秀 |
+| `large-v3` | ~3 GB | 最慢 | 最佳 |
+
+**Groq API** — 需要 `GROQ_API_KEY`。当你需要免费托管 STT 选项时，是良好的云端备选方案。
+
+**OpenAI API** — 优先使用 `VOICE_TOOLS_OPENAI_KEY`，回退至 `OPENAI_API_KEY`。支持 `whisper-1`、`gpt-4o-mini-transcribe`、`gpt-4o-transcribe` 和 `gpt-transcribe`。
+
+**Mistral API（Voxtral Transcribe）** — 需要 `MISTRAL_API_KEY`。使用 Mistral 的 [Voxtral Transcribe](https://docs.mistral.ai/capabilities/audio/speech_to_text/) 模型。支持 13 种语言、说话人分离和词级时间戳。通过 `cd ~/.hermes/hermes-agent && uv pip install -e ".[mistral]"` 安装。
+
+**xAI Grok STT** — 需要 `XAI_API_KEY`。以 multipart/form-data 格式发送至 `https://api.x.ai/v1/stt`。如果你已在使用 xAI 进行聊天或 TTS 并希望一个 API 密钥搞定一切，这是个好选择。自动检测顺序将其排在 Groq 之后——显式设置 `stt.provider: xai` 可强制使用。
+
+**自定义本地 CLI 回退** — 若你希望 Hermes 直接调用本地转录命令，请设置 `HERMES_LOCAL_STT_COMMAND`。命令模板支持 `{input_path}`、`{output_dir}`、`{language}` 和 `{model}` 占位符。你的命令必须在 `{output_dir}` 下某处写入 `.txt` 转录文件。
+
+#### 示例：Doubao / Volcengine ASR
+
+如果你使用 [`doubao-speech`](https://pypi.org/project/doubao-speech/) 进行 Doubao TTS（见[上文](#example-doubao-chinese-seed-tts-20)），同一个包也可通过本地命令 STT 接口处理语音转文字：
+
+```bash
+pip install doubao-speech
+export VOLCENGINE_APP_ID="your-app-id"
+export VOLCENGINE_ACCESS_TOKEN="your-access-token"
+export HERMES_LOCAL_STT_COMMAND='doubao-speech transcribe {input_path} --out {output_dir}/transcript.txt'
+```
+
+```yaml
+stt:
+  provider: local_command
+```
+
+Hermes 将传入的语音消息写入 `{input_path}`，运行命令，并读取 `{output_dir}` 下生成的 `.txt` 文件。语言由 Volcengine bigmodel 端点自动检测。
+
+### 回退行为
+
+若配置的提供商不可用，Hermes 会自动回退：
+- **本地 faster-whisper 不可用** → 在云端提供商之前尝试本地 `whisper` CLI 或 `HERMES_LOCAL_STT_COMMAND`
+- **未设置 Groq 密钥** → 回退至本地转录，然后是 OpenAI
+- **未设置 OpenAI 密钥** → 回退至本地转录，然后是 Groq
+- **未设置 Mistral 密钥/SDK** → 在自动检测中跳过；回退至下一个可用提供商
+- **无可用提供商** → 语音消息直接传递，并向用户给出准确说明

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

@@ -0,0 +1,210 @@
+---
+title: 视觉与图像粘贴
+description: 将剪贴板中的图像粘贴到 Hermes CLI，进行多模态视觉分析。
+sidebar_label: 视觉与图像粘贴
+sidebar_position: 7
+---
+
+# 视觉与图像粘贴
+
+Hermes Agent 支持**多模态视觉**——你可以直接将剪贴板中的图像粘贴到 CLI，让 Agent 对其进行分析、描述或处理。图像以 base64 编码的内容块形式发送给模型，因此任何支持视觉的模型均可处理。
+
+## 工作原理
+
+1. 将图像复制到剪贴板（截图、浏览器图片等）
+2. 使用以下任一方式附加图像
+3. 输入问题并按 Enter
+4. 图像以 `[📎 Image #1]` 徽章形式显示在输入框上方
+5. 提交时，图像作为视觉内容块发送给模型
+
+发送前可附加多张图像，每张图像都有独立徽章。按 `Ctrl+C` 可清除所有已附加图像。
+
+图像以带时间戳的 PNG 文件名保存至 `~/.hermes/images/`。
+
+## 粘贴方式
+
+附加图像的方式取决于你的终端环境。并非所有方式在所有环境下均可用——以下是完整说明：
+
+### `/paste` 命令
+
+**最可靠的显式图像附加备用方案。**
+
+```
+/paste
+```
+
+输入 `/paste` 并按 Enter。Hermes 会检查剪贴板中是否有图像并附加。当你的终端重写了 `Cmd+V`/`Ctrl+V`，或剪贴板中只有图像而没有 bracketed-paste（括号粘贴）文本载荷可供检查时，这是最安全的选项。
+
+### Ctrl+V / Cmd+V
+
+Hermes 现在将粘贴处理为分层流程：
+- 优先进行普通文本粘贴
+- 若终端未能正常传递文本，则回退到原生剪贴板 / OSC52 文本
+- 当剪贴板或粘贴内容解析为图像或图像路径时，附加图像
+
+这意味着粘贴的 macOS 截图临时路径和 `file://...` 图像 URI 可以立即附加，而不是以原始文本形式留在编辑器中。
+
+:::warning
+如果剪贴板中**只有图像**（无文本），终端仍无法直接发送二进制图像字节。请使用 `/paste` 作为显式图像附加的备用方案。
+:::
+
+### `/terminal-setup`（适用于 VS Code / Cursor / Windsurf）
+
+如果你在 macOS 上的 VS Code 系列集成终端中运行 TUI，Hermes 可以安装推荐的 `workbench.action.terminal.sendSequence` 绑定，以获得更好的多行输入及撤销/重做一致性：
+
+```text
+/terminal-setup
+```
+
+当 `Cmd+Enter`、`Cmd+Z` 或 `Shift+Cmd+Z` 被 IDE 拦截时，此命令尤为有用。仅在本地机器上运行——不要在 SSH 会话中使用。
+
+## 平台兼容性
+
+| 环境 | `/paste` | Cmd/Ctrl+V | `/terminal-setup` | 备注 |
+|---|:---:|:---:|:---:|---|
+| **macOS Terminal / iTerm2** | ✅ | ✅ | n/a | 最佳体验——原生剪贴板 + 截图路径恢复 |
+| **Apple Terminal** | ✅ | ✅ | n/a | 若 Cmd+←/→/⌫ 被重写，使用 Ctrl+A / Ctrl+E / Ctrl+U 备用方案 |
+| **Linux X11 桌面** | ✅ | ✅ | n/a | 需要 `xclip`（`apt install xclip`） |
+| **Linux Wayland 桌面** | ✅ | ✅ | n/a | 需要 `wl-paste`（`apt install wl-clipboard`） |
+| **WSL2（Windows Terminal）** | ✅ | ✅ | n/a | 使用 `powershell.exe`——无需额外安装 |
+| **VS Code / Cursor / Windsurf（本地）** | ✅ | ✅ | ✅ | 推荐，以获得更好的 Cmd+Enter / 撤销 / 重做一致性 |
+| **VS Code / Cursor / Windsurf（SSH）** | ❌² | ❌² | ❌³ | 请在本地机器上运行 `/terminal-setup` |
+| **SSH 终端（任意）** | ❌² | ❌² | n/a | 无法访问远程剪贴板 |
+
+² 参见下方 [SSH 与远程会话](#ssh--remote-sessions)
+³ 该命令写入本地 IDE 快捷键绑定，不应从远程主机运行
+
+## 各平台配置说明
+
+### macOS
+
+**无需任何配置。** Hermes 使用 `osascript`（macOS 内置）读取剪贴板。如需更快的性能，可选择安装 `pngpaste`：
+
+```bash
+brew install pngpaste
+```
+
+### Linux（X11）
+
+安装 `xclip`：
+
+```bash
+# Ubuntu/Debian
+sudo apt install xclip
+
+# Fedora
+sudo dnf install xclip
+
+# Arch
+sudo pacman -S xclip
+```
+
+### Linux（Wayland）
+
+现代 Linux 桌面（Ubuntu 22.04+、Fedora 34+）通常默认使用 Wayland。安装 `wl-clipboard`：
+
+```bash
+# Ubuntu/Debian
+sudo apt install wl-clipboard
+
+# Fedora
+sudo dnf install wl-clipboard
+
+# Arch
+sudo pacman -S wl-clipboard
+```
+
+:::tip 如何检查是否在使用 Wayland
+```bash
+echo $XDG_SESSION_TYPE
+# "wayland" = Wayland，"x11" = X11，"tty" = 无显示服务器
+```
+:::
+
+### WSL2
+
+**无需额外配置。** Hermes 通过 `/proc/version` 自动检测 WSL2，并使用 `powershell.exe` 通过 .NET 的 `System.Windows.Forms.Clipboard` 访问 Windows 剪贴板。这是 WSL2 Windows 互操作的内置功能——`powershell.exe` 默认可用。
+
+剪贴板数据通过 stdout 以 base64 编码的 PNG 格式传输，无需路径转换或临时文件。
+
+:::info WSLg 说明
+如果你使用的是 WSLg（带 GUI 支持的 WSL2），Hermes 会优先尝试 PowerShell 路径，然后回退到 `wl-paste`。WSLg 的剪贴板桥接仅支持 BMP 格式的图像——Hermes 会使用 Pillow（如已安装）或 ImageMagick 的 `convert` 命令自动将 BMP 转换为 PNG。
+:::
+
+#### 验证 WSL2 剪贴板访问
+
+```bash
+# 1. 检查 WSL 检测
+grep -i microsoft /proc/version
+
+# 2. 检查 PowerShell 是否可访问
+which powershell.exe
+
+# 3. 复制一张图像，然后检查
+powershell.exe -NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::ContainsImage()"
+# 应输出 "True"
+```
+
+## SSH 与远程会话
+
+**通过 SSH 进行剪贴板图像粘贴无法完全正常工作。** 当你 SSH 到远程机器时，Hermes CLI 运行在远程主机上。剪贴板工具（`xclip`、`wl-paste`、`powershell.exe`、`osascript`）读取的是其所在机器的剪贴板——即远程服务器，而非你的本地机器。因此，本地剪贴板中的图像在远程端无法访问。
+
+文本有时仍可通过终端粘贴或 OSC52 传输，但图像剪贴板访问和本地截图临时路径始终绑定于运行 Hermes 的机器。
+
+### SSH 的变通方案
+
+1. **上传图像文件**——在本地保存图像，通过 `scp`、VSCode 文件浏览器（拖放）或任何文件传输方式上传到远程服务器，然后通过路径引用。*（计划在未来版本中提供 `/attach <filepath>` 命令。）*
+
+2. **使用 URL**——如果图像可在线访问，直接在消息中粘贴 URL。Agent 可使用 `vision_analyze` 直接查看任意图像 URL。
+
+3. **X11 转发**——使用 `ssh -X` 连接以转发 X11。这允许远程机器上的 `xclip` 访问你本地的 X11 剪贴板。需要本地运行 X 服务器（macOS 上为 XQuartz，Linux X11 桌面内置）。大图像传输较慢。
+
+4. **使用消息平台**——通过 Telegram、Discord、Slack 或 WhatsApp 向 Hermes 发送图像。这些平台原生支持图像上传，不受剪贴板/终端限制的影响。
+
+## 为什么终端无法粘贴图像
+
+这是一个常见的困惑来源，以下是技术说明：
+
+终端是**基于文本**的界面。当你按下 Ctrl+V（或 Cmd+V）时，终端模拟器会：
+
+1. 从剪贴板读取**文本内容**
+2. 将其包裹在 [bracketed paste](https://en.wikipedia.org/wiki/Bracketed-paste)（括号粘贴）转义序列中
+3. 通过终端的文本流将其发送给应用程序
+
+如果剪贴板中只有图像（无文本），终端没有任何内容可发送。目前没有标准的终端转义序列用于传输二进制图像数据，终端会直接忽略。
+
+这就是为什么 Hermes 使用独立的剪贴板检查——它不通过终端粘贴事件接收图像数据，而是直接通过子进程调用操作系统级工具（`osascript`、`powershell.exe`、`xclip`、`wl-paste`）独立读取剪贴板。
+
+## 支持的模型
+
+图像粘贴适用于任何支持视觉的模型。图像以 base64 编码的 data URL 形式，按 OpenAI 视觉内容格式发送：
+
+```json
+{
+  "type": "image_url",
+  "image_url": {
+    "url": "data:image/png;base64,..."
+  }
+}
+```
+
+大多数现代模型支持此格式，包括 GPT-4 Vision、Claude（带视觉）、Gemini，以及通过 OpenRouter 提供服务的开源多模态模型。
+
+## 图像路由（视觉模型 vs 纯文本模型）
+
+当用户附加图像时——无论来自 CLI 剪贴板、gateway（Telegram/Discord 图片）还是其他入口——Hermes 会根据当前模型是否支持视觉进行路由：
+
+| 你的模型 | 图像处理方式 |
+|---|---|
+| **支持视觉的模型**（GPT-4V、Claude with vision、Gemini、Qwen-VL、MiMo-VL、DeepSeek Flash / V4.1-Flash 等） | 使用上述提供商原生图像内容格式，以**真实像素**发送。无文本摘要层。 |
+| **纯文本模型**（DeepSeek V4 Pro、DeepSeek V3、较小的开源模型、旧版纯对话端点） | 通过 `vision_analyze` 辅助工具路由——辅助视觉模型描述图像，文本描述注入对话。 |
+
+无需手动配置——Hermes 在提供商元数据中查找当前模型的能力并自动选择正确路径。实际效果：你可以在会话中途切换视觉模型与非视觉模型，图像处理"开箱即用"，无需更改工作流。纯文本模型会获得关于图像的连贯上下文，而不是一个会被拒绝的损坏多模态载荷。
+
+处理文本描述路径的辅助模型可在 `auxiliary.vision` 下配置——参见[辅助模型](/user-guide/configuration#auxiliary-models)。
+
+### `vision_analyze` 具有相同的双重行为
+
+`vision_analyze` 工具本身遵循相同的路由逻辑。当当前主模型支持视觉，**且**其提供商支持在工具结果中包含图像内容（目前为 Anthropic、OpenAI、Azure-OpenAI 和 Gemini 3.x 技术栈），`vision_analyze` 会跳过辅助描述器，直接将原始图像像素作为多模态工具结果信封返回。主模型在下一轮会原生看到图像——无辅助调用、无文本摘要信息损失、无额外延迟。
+
+对于纯文本主模型（或工具结果通道不支持图像的提供商），`vision_analyze` 回退到旧路径：请求已配置的辅助视觉模型描述图像，并以纯文本形式返回描述。无论哪种情况，调用工具的签名相同——工具在运行时根据当前模型决定采用哪条路径。