Cyber-Yichen/hermes-xiaomi-mimo-tts

[!IMPORTANT] AI Agent / Coding Agent：修改本项目之前，请先阅读 AGENTS.md。 其中记录了插件接口、音频格式约束、凭据优先级、测试方法和发布规则。

Hermes Xiaomi MiMo TTS

将小米 MiMo V2.5 TTS 接入 Hermes Agent，并把生成的语音转换为飞书 / Lark 可直接播放的 OGG/Opus 语音条。

这个插件解决三个问题：

1. MiMo TTS 使用 Chat Completions API，而不是常见的 /v1/audio/speech；
2. MiMo 原生返回 WAV、MP3 或 PCM，飞书语音条需要 OGG 容器中的 Opus；
3. 旧的 command provider 方案依赖批处理脚本、Python SDK 和路径配置，容易出现“文件名是 .ogg，内容实际仍是 MP3”的伪转码。

插件使用 Hermes 原生 TTSProvider 接口，无需修改 Hermes 源码，也不依赖 OpenAI SDK。

功能

• 注册 xiaomi-mimo Hermes TTS provider；
• 支持标准 MiMo API 和 Token Plan API；
• Token Plan 凭据存在时自动优先使用；
• 使用 Python 标准库调用 /v1/chat/completions；
• 从 message.audio.data 解码 Base64 音频；
• 自动调用 ffmpeg 转换为 OGG/Opus；
• 飞书 / Lark 中以原生语音条发送；
• 找不到 ffmpeg 时自动降级为真实的 MP3 音频附件；
• 提供中英文内置音色目录；
• 安装前备份 Hermes 配置和旧插件；
• 不保存、上传或提交 API Key。

技术栈

项目不需要：

• OpenAI Python SDK；
• requests；
• Node.js 或 npm；
• Docker；
• 数据库；
• 修改 Hermes Feishu Adapter；
• 将 API Key 写入仓库。

工作原理

flowchart LR
    A["Hermes text_to_speech"] --> B["xiaomi-mimo Provider"]
    B --> C["MiMo /chat/completions"]
    C --> D["Base64 MP3/WAV"]
    D --> E{"能否找到 ffmpeg"}
    E -- "是" --> F["OGG container + Opus codec"]
    E -- "否" --> G["真实 MP3 音频附件"]
    F --> H["Hermes MEDIA tag"]
    G --> H
    H --> I["Feishu Adapter"]
    I --> J["飞书语音条或音频附件"]

MiMo 请求中：

• role: assistant 保存需要合成的正文；
• 可选的 role: user 保存 MIMO_TTS_STYLE 风格提示；
• 音频从 choices[0].message.audio.data 读取；
• 插件不会把正文或 API Key 写入日志。

环境要求

• Windows 10 / 11；
• Hermes Agent 0.15.0 或更新版本；
• Hermes 已启用 tts toolset；
• 可用的小米 MiMo API Key 或 Token Plan API Key；
• ffmpeg 包含 libopus 编码器，语音条功能才可用。

没有 ffmpeg 时，TTS 仍然可用，只会作为普通 MP3 音频附件发送。

安装

git clone https://github.com/Cyber-Yichen/hermes-xiaomi-mimo-tts.git
Set-Location .\hermes-xiaomi-mimo-tts
.\install.ps1

自定义 Hermes 数据目录：

.\install.ps1 -HermesHome 'D:\env\hermes'

如果 ffmpeg 没有加入 PATH，可以显式指定：

.\install.ps1 `
  -HermesHome 'D:\env\hermes' `
  -FfmpegPath 'D:\tools\ffmpeg\bin\ffmpeg.exe'

安装器会：

1. 备份 config.yaml 和现有插件；
2. 复制插件到 HERMES_HOME\plugins\xiaomi-mimo-tts；
3. 可选地复制 ffmpeg 到 HERMES_HOME\bin\ffmpeg.exe；
4. 启用 xiaomi-mimo-tts 插件；
5. 将 TTS provider 设置为 xiaomi-mimo；
6. 设置默认模型、音色和 ogg 输出；
7. 重启 Hermes Gateway。

配置凭据

将凭据写入 HERMES_HOME\.env。不要写进仓库或 config.yaml。

独立 TTS 凭据

MIMO_TTS_API_KEY=你的密钥
MIMO_TTS_BASE_URL=https://api.xiaomimimo.com/v1

Token Plan

XIAOMI_TOKEN_PLAN_API_KEY=你的Token Plan密钥
XIAOMI_TOKEN_PLAN_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

复用已有小米配置

XIAOMI_API_KEY=你已有的小米API密钥
XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1

凭据优先级：

1. MIMO_TTS_API_KEY
2. XIAOMI_TOKEN_PLAN_API_KEY
3. XIAOMI_API_KEY

插件只使用与命中密钥配套的 Base URL。

Hermes 配置

安装后的核心配置：

tts:
  provider: xiaomi-mimo
  voice: Chloe
  model: mimo-v2.5-tts
  output_format: ogg

可选环境变量：

MIMO_TTS_VOICE=Chloe
MIMO_TTS_MODEL=mimo-v2.5-tts
MIMO_TTS_STYLE=温柔、自然、稍慢一些
MIMO_TTS_TIMEOUT=120
MIMO_TTS_FFMPEG=D:\env\hermes\bin\ffmpeg.exe

Hermes config.yaml 中的 tts.voice 和 tts.model 优先于插件环境变量。

可用音色

切换音色：

hermes config set tts.voice 茉莉
hermes gateway restart

使用

在飞书中让 Hermes：

用语音回复我：你好，这是小米 MiMo TTS。

Hermes 会调用 text_to_speech，结果正常时返回 OGG/Opus 语音条。

CLI 中也可以通过 Hermes 的 TTS 工具调用。输出文件默认保存在 Hermes 的语音缓存目录。

从旧 command provider 迁移

旧配置通常类似：

tts:
  provider: mimo
  providers:
    mimo:
      type: command
      command: D:/env/hermes/scripts/mimo-tts.cmd {text_path} {output_path} {voice}
      output_format: ogg

本插件使用不同的 provider 名称 xiaomi-mimo，因此旧配置可以暂时保留，不会覆盖插件。确认插件运行正常后，再手动删除旧的 tts.providers.mimo 和旧脚本。

不要继续使用“请求 MP3 后直接保存成 .ogg”的旧脚本。飞书根据扩展名按 Opus 上传，但文件内部并不是 Opus，可能导致播放失败或兼容性问题。

验证音频

ffmpeg -hide_banner -i .\voice.ogg

正确的输出应包含：

Input #0, ogg
Audio: opus

仅仅看到文件名以 .ogg 结尾并不能证明转码成功。

测试

使用 Hermes 自带 Python：

$python = Join-Path $env:HERMES_HOME 'hermes-agent\venv\Scripts\python.exe'
& $python -B -m unittest discover -s tests -v

测试不会访问真实 MiMo API，也不需要 API Key。

故障排查

Provider 不可用

确认插件和配置：

hermes plugins list
hermes config get tts

检查 .env 中至少存在一个支持的密钥名称，但不要把密钥值粘贴到 Issue。

收到音频附件而不是语音条

这通常表示 ffmpeg 不可用或不包含 libopus：

ffmpeg -encoders | Select-String opus

重新安装时使用 -FfmpegPath，然后重启 Gateway。

HTTP 402

标准 API 账户余额不足。配置 Token Plan 凭据，或为当前账户充值。

HTTP 400 Unsupported audio format

MiMo API 不直接支持 ogg 或 opus。这是预期行为。插件会先请求 MP3，再由 ffmpeg 转码。

旧 command provider 仍在运行

确认：

tts:
  provider: xiaomi-mimo

Hermes 的 command provider 会优先于同名 Python 插件，但本项目使用独立名称避免了该冲突。

安全与隐私

• API Key 仅从环境变量或 HERMES_HOME\.env 读取；
• HTTP 错误不会打印 Authorization Header；
• .gitignore 排除 .env、日志和生成音频；
• 请勿在 GitHub Issue、日志或截图中公开 API Key；
• 需要合成的文本会发送给小米 MiMo API；
• 语音文件保存在本机 Hermes 缓存目录。

已知限制

• 当前发布只支持 mimo-v2.5-tts；
• Voice Design 和 Voice Clone 使用不同请求结构，尚未作为稳定功能开放；
• MiMo 当前不直接输出 OGG/Opus，因此语音条依赖 ffmpeg；
• 安装脚本目前面向 Windows；
• 飞书语音发送由 Hermes Feishu Adapter 提供，本插件不直接持有飞书凭据。

项目结构

.
├── .env.example
├── AGENTS.md
├── LICENSE
├── README.md
├── docs
│   └── origin-and-migration.md
├── install.ps1
├── plugin
│   ├── __init__.py
│   └── plugin.yaml
└── tests
    └── test_provider.py

参考

• Hermes Agent Voice & TTS
• Hermes Agent Plugin Guide
• Xiaomi MiMo Platform
• Feishu file upload API
• Feishu message create API

许可证

MIT License