1 files changed, 82 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..f090991
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,82 @@
+# Xiaomi MiMo ASR (mimo-v2.5-asr) — Hermes STT 安装说明
+
+将小米 MiMo ASR 语音识别模型接入 Hermes 的语音转文字功能。
+
+## 前置条件
+
+- Hermes Agent 已安装
+- Xiaomi MiMo API Key（https://platform.xiaomimimo.com 获取）
+- ffmpeg（用于音频格式转换）：`brew install ffmpeg`
+
+## 工作原理
+
+Xiaomi ASR **不使用**标准的 `/v1/audio/transcriptions` 端点，而是通过
+`/v1/chat/completions` 接口 + `input_audio` 格式工作。因此需要一个包装脚本来处理：
+- 音频格式转换（非 wav/mp3 文件通过 ffmpeg 转为 16kHz 单声道 WAV）
+- Base64 编码音频数据
+- 构造 chat completions JSON payload
+- 解析响应提取转录文本
+
+Hermes 的 **command provider** 机制允许通过 shell 命令接入任意 STT 后端，
+无需编写 Python 插件。
+
+## 安装步骤
+
+### 1. 复制脚本
+
+```bash
+cp xiaomi-asr.sh ~/.hermes/scripts/xiaomi-asr.sh
+chmod +x ~/.hermes/scripts/xiaomi-asr.sh
+```
+
+### 2. 配置环境变量
+
+在 `~/.hermes/.env` 中添加（如果还没有）：
+
+```
+XIAOMI_API_KEY=your_api_key_here
+XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+```
+
+> 如果你的 API Key 绑定的是国际站，用 `https://api.xiaomimimo.com/v1`
+
+### 3. 修改 Hermes 配置
+
+在 `~/.hermes/config.yaml` 的 `stt` 部分：
+
+```yaml
+stt:
+  enabled: true
+  provider: xiaomi-asr
+  providers:
+    xiaomi-asr:
+      type: command
+      command: ~/.hermes/scripts/xiaomi-asr.sh {input_path} {output_path} mimo-v2.5-asr {language}
+      language: zh
+      format: txt
+      timeout: 120
+```
+
+### 4. 重启 Hermes
+
+- Desktop / TUI：关闭并重新打开
+- Gateway：运行 `/restart`
+
+## 验证
+
+```bash
+# 手动测试脚本
+export XIAOMI_API_KEY=your_key
+export XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+~/.hermes/scripts/xiaomi-asr.sh /path/to/audio.wav /tmp/output.txt mimo-v2.5-asr zh
+cat /tmp/output.txt
+```
+
+## 注意事项
+
+| 问题 | 说明 |
+|------|------|
+| 音频格式 | 只支持 wav 和 mp3，其他格式自动通过 ffmpeg 转换 |
+| 纯音乐 | 无法识别纯音乐内容，会返回空结果 |
+| 语言 | 主要针对中文优化，其他语言效果较差 |
+| ffmpeg | 非 wav/mp3 格式必须安装 ffmpeg |