initial commit

1 files changed, 146 insertions, 0 deletions

diff --git a/INSTALLATION.md b/INSTALLATION.md
new file mode 100644
index 0000000..3918798
--- /dev/null
+++ b/INSTALLATION.md
@@ -0,0 +1,146 @@
+# MiMo V2.5 TTS — Hermes Agent Plugin
+
+Xiaomi MiMo V2.5 语音合成插件，为 Hermes Agent 提供高质量中英文 TTS 能力。
+
+## 功能
+
+- 9 个内置音色（4 中文 + 4 英文 + 1 自动）
+- 3 种模型：内置音色 / 语音设计 / 声音克隆
+- 自然语言风格控制（播音员、讲故事、方言、情绪等）
+- 流式输出支持
+- 兼容 Hermes 语音气泡投递（Telegram 等）
+
+## 音色列表
+
+| ID | 名称 | 语言 | 性别 |
+|----|------|------|------|
+| `mimo_default` | 默认 | 自动 | - |
+| `冰糖` | Bingtang | 中文 | 女 |
+| `茉莉` | Moli | 中文 | 女 |
+| `苏打` | Suda | 中文 | 男 |
+| `白桦` | Baihua | 中文 | 男 |
+| `Mia` | Mia | 英文 | 女 |
+| `Chloe` | Chloe | 英文 | 女 |
+| `Milo` | Milo | 英文 | 男 |
+| `Dean` | Dean | 英文 | 男 |
+
+## 前置条件
+
+- Hermes Agent 已安装并可运行
+- Xiaomi MiMo API Key（获取地址：https://mimo.mi.com）
+
+## 安装步骤
+
+运行安装脚本：
+
+```bash
+bash ~/mimo-tts-hermes-plugin/setup.sh
+```
+
+脚本会自动完成：
+1. 将插件文件复制到 `~/.hermes/plugins/tts/mimo/`
+2. 在 Hermes 中启用插件（`hermes plugins enable tts/mimo`）
+3. 将独立脚本复制到 `~/mimo_tts.py`
+
+安装后需要手动配置（脚本会提示）：
+
+```bash
+# 设置 TTS provider
+hermes config set tts.provider mimo
+
+# 设置默认音色（可选，不设则用 mimo_default）
+hermes config set tts.voice Mia
+
+# 重启 session 生效
+# 在 Hermes 中执行 /reset
+```
+
+## 使用方式
+
+### Hermes 内置调用
+
+配置完成后，Hermes 的 `text_to_speech` 工具会自动走 MiMo：
+
+```
+text_to_speech(text="你好世界")
+```
+
+### 独立脚本调用（不依赖 Hermes）
+
+```bash
+# 基本用法
+python3 ~/mimo_tts.py "你好世界" --voice 冰糖
+
+# 英文
+python3 ~/mimo_tts.py "Hello world" --voice Mia
+
+# 指定输出路径
+python3 ~/mimo_tts.py "测试" --voice 茉莉 -o output.wav
+
+# 语音设计模型（通过文字描述生成音色）
+python3 ~/mimo_tts.py "Once upon a time" --model voicedesign \
+    --style "A warm storyteller voice with British accent"
+
+# 流式模式
+python3 ~/mimo_tts.py "你好" --stream -o output.wav
+
+# 列出音色
+python3 ~/mimo_tts.py --list-voices
+
+# 列出模型
+python3 ~/mimo_tts.py --list-models
+```
+
+### Python API 调用
+
+```python
+import sys, os
+sys.path.insert(0, os.path.expanduser("~/.hermes/hermes-agent"))
+os.environ.setdefault("XIAOMI_API_KEY", "your_key")
+os.environ.setdefault("XIAOMI_BASE_URL", "https://token-plan-cn.xiaomimimo.com/v1")
+
+# 加载插件
+import importlib.util
+spec = importlib.util.spec_from_file_location(
+    "mimo_tts", os.path.expanduser("~/.hermes/plugins/tts/mimo/__init__.py")
+)
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+
+provider = mod.MiMoTTSProvider()
+provider.synthesize("你好世界", "output.wav", voice="冰糖")
+```
+
+## 环境变量
+
+| 变量 | 必需 | 说明 |
+|------|------|------|
+| `XIAOMI_API_KEY` | ✅ | MiMo API Key |
+| `XIAOMI_BASE_URL` | 可选 | API 端点（默认 `https://api.xiaomimimo.com/v1`，国内用户可能需要设为 `https://token-plan-cn.xiaomimimo.com/v1`） |
+
+这些变量应配置在 `~/.hermes/.env` 中。
+
+## 卸载
+
+```bash
+bash ~/mimo-tts-hermes-plugin/setup.sh --uninstall
+```
+
+或手动：
+
+```bash
+hermes plugins disable tts/mimo
+rm -rf ~/.hermes/plugins/tts/mimo
+rm -f ~/mimo_tts.py
+```
+
+## 文件说明
+
+```
+mimo-tts-hermes-plugin/
+├── INSTALLATION.md   # 本文档
+├── setup.sh          # 安装/卸载脚本
+├── plugin.yaml       # Hermes 插件清单
+├── __init__.py       # Hermes TTS Provider 实现
+└── mimo_tts.py       # 独立命令行脚本
+```