# MiMo V2.5 ASR — 安装说明（给 Agent 看）

> **提示**：如果用户已经在使用 MiMo 作为 LLM provider（如 Token Plan）或已安装其他 MiMo 插件（如 mimo-tts、mimo-websearch），`XIAOMI_API_KEY` 和 `XIAOMI_BASE_URL` 很可能已配置。请先检查现有的 `.env` 配置，直接复用，无需重复询问 API Key 和端点。

## 前置条件

- Hermes Agent 已安装并可运行
- Xiaomi MiMo API Key（获取地址：https://platform.xiaomimimo.com）
- ffmpeg（用于非 wav/mp3 格式的自动转换）

## 安装

> **注意**：`setup.sh` 仅供参考，请勿直接运行。请阅读以下步骤，根据用户的环境自行完成安装。
> 以下命令中的 `~/.hermes` 仅为 Unix 典型路径，**不要硬编码**。安装前请先确认 Hermes 的实际安装目录（如 `$HERMES_HOME`、`$env:HERMES_HOME` 等）。

### 方式一：Plugin 模式（推荐）

将插件文件复制到 Hermes 插件目录并启用：

```bash
mkdir -p ~/.hermes/plugins/stt/mimo
cp plugin.yaml __init__.py provider.py ~/.hermes/plugins/stt/mimo/
hermes plugins enable stt/mimo
```

```powershell
# Windows (PowerShell)
mkdir -Force "$env:USERPROFILE\.hermes\plugins\stt\mimo"
cp plugin.yaml,__init__.py,provider.py "$env:USERPROFILE\.hermes\plugins\stt\mimo\"
hermes plugins enable stt/mimo
```

安装后配置：

```bash
hermes config set stt.provider mimo-asr
hermes config set stt.providers.mimo-asr.type plugin
# 重启 session 生效（/reset）
```

### 方式二：Command 模式

适用于不希望以插件形式加载，或需要自定义脚本路径的场景。

#### 1. 复制脚本

```bash
mkdir -p ~/.hermes/scripts
cp xiaomi-asr.py ~/.hermes/scripts/xiaomi-asr.py
cp xiaomi-asr.sh ~/.hermes/scripts/xiaomi-asr.sh
chmod +x ~/.hermes/scripts/xiaomi-asr.*
```

```powershell
# Windows (PowerShell) — 仅需要 .py 脚本
mkdir -Force "$env:USERPROFILE\.hermes\scripts"
cp xiaomi-asr.py "$env:USERPROFILE\.hermes\scripts\xiaomi-asr.py"
```

#### 2. 配置环境变量

在 Hermes 的 `.env` 文件中添加：

```env
XIAOMI_API_KEY=你的API_Key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```

> 中国站用户：`https://token-plan-cn.xiaomimimo.com/v1`
> 国际站用户：`https://api.xiaomimimo.com/v1`

#### 3. 修改 Hermes 配置

编辑 Hermes 的 `config.yaml` 的 `stt` 部分：

```yaml
stt:
  enabled: true
  provider: mimo-asr
  providers:
    mimo-asr:
      type: command
      command: python ~/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}
      language: zh
      format: txt
      timeout: 120
```

> **Windows 注意**：命令路径需用正斜杠，如 `python C:/Users/<用户名>/.hermes/scripts/xiaomi-asr.py ...`

或使用 `hermes config set`：

```bash
hermes config set stt.provider mimo-asr
hermes config set stt.providers.mimo-asr.type command
hermes config set stt.providers.mimo-asr.command "python ~/.hermes/scripts/xiaomi-asr.py {input_path} {output_path} mimo-v2.5-asr {language}"
hermes config set stt.providers.mimo-asr.language zh
hermes config set stt.providers.mimo-asr.format txt
hermes config set stt.providers.mimo-asr.timeout 120
```

#### 4. 重启 Hermes

- **Desktop**：关闭并重新打开
- **Gateway**：运行 `/restart`

## 独立使用（不依赖 Hermes）

```bash
export XIAOMI_API_KEY="your-key-here"
export XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"

python3 xiaomi-asr.py audio.wav output.txt mimo-v2.5-asr zh
cat output.txt
```

```powershell
# Windows (PowerShell)
$env:XIAOMI_API_KEY="your-key-here"
$env:XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"

python xiaomi-asr.py audio.wav output.txt mimo-v2.5-asr zh
type output.txt
```

## 卸载

```bash
hermes plugins disable stt/mimo
rm -rf ~/.hermes/plugins/stt/mimo
rm -f ~/xiaomi-asr.py ~/xiaomi-asr.sh
```

```powershell
# Windows (PowerShell)
hermes plugins disable stt/mimo
rm -Recurse -Force "$env:USERPROFILE\.hermes\plugins\stt\mimo"
rm -Force "$env:USERPROFILE\xiaomi-asr.py","$env:USERPROFILE\xiaomi-asr.sh"
```

## 验证

```bash
ffmpeg -y -f lavfi -i "sine=frequency=440:duration=3" -ar 16000 -ac 1 test.wav
python3 xiaomi-asr.py test.wav output.txt mimo-v2.5-asr zh
cat output.txt
```

```powershell
# Windows (PowerShell)
ffmpeg -y -f lavfi -i "sine=frequency=440:duration=3" -ar 16000 -ac 1 test.wav
python xiaomi-asr.py test.wav output.txt mimo-v2.5-asr zh
type output.txt
```