better-dsh 0.2.5-c → 0.2.5-e

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

@@ -1,456 +0,0 @@
----
-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

@@ -1,210 +0,0 @@
----
-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` 回退到旧路径：请求已配置的辅助视觉模型描述图像，并以纯文本形式返回描述。无论哪种情况，调用工具的签名相同——工具在运行时根据当前模型决定采用哪条路径。