1 files changed, 36 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f4deeee
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# MiMo V2.5 ASR — Hermes Agent Plugin
+
+将小米 MiMo ASR 语音识别模型接入 Hermes 的语音转文字功能。可作为 Hermes 插件加载，也可在 command 模式下独立使用。
+
+## 工作原理
+
+Xiaomi ASR **不使用**标准的 `/v1/audio/transcriptions` 端点，而是通过 `/v1/chat/completions` 接口 + `input_audio` 格式工作。
+
+- 音频格式检测（wav/mp3 直接发送，其他格式通过 ffmpeg 转为 16kHz 单声道 WAV）
+- Base64 编码音频数据
+- 构造 chat completions JSON payload
+- 解析响应提取转录文本
+
+## 注意事项
+
+| 问题 | 说明 |
+|------|------|
+| 音频格式 | 只支持 wav 和 mp3，其他格式自动通过 ffmpeg 转换 |
+| 纯音乐 | 无法识别纯音乐内容，会返回空结果 |
+| 语言 | 主要针对中文优化，其他语言效果较差 |
+| ffmpeg | 非 wav/mp3 格式必须安装 ffmpeg |
+| 环境变量 | `XIAOMI_API_KEY` 必须在 `.env` 文件中，Hermes 会自动加载到子进程环境 |
+
+## 文件说明
+
+```
+mimo-asr-for-hermes/
+├── README.md          # 本文档（介绍）
+├── INSTALL.md         # 安装说明（给 Agent 看）
+├── plugin.yaml        # Hermes 插件清单
+├── setup.sh           # 安装/卸载脚本（仅供参考）
+├── __init__.py        # 插件注册入口
+├── provider.py        # STTProvider 实现
+├── xiaomi-asr.py      # 独立脚本（Python，全平台）
+└── xiaomi-asr.sh      # 独立脚本（Bash，仅 Linux/macOS）
+```