Xiaoi

🚀 小愛音箱語音通知工具

小愛音箱語音通知工具可通過 CLI / TUI / MCP / Webhook 向小愛音箱發送語音通知，為用戶提供便捷的語音通知服務。

🚀 快速開始

你可以通過以下步驟快速使用小愛音箱語音通知工具：

1. 安裝工具（全局安裝或從源碼安裝）。
2. 完成配置（自動創建或手動配置）。
3. 根據需求選擇 TUI 交互界面、CLI 命令、MCP Server 或 Webhook 服務等方式使用。

✨ 主要特性

• TUI 交互界面：可配置賬號、發送通知、管理 Webhook/PM2。
• CLI 命令：適用於腳本/自動化場景。
• MCP Server：可供 Codex/Cursor/VS Code 等 AI 編程助手調用。
• Webhook 服務：提供 HTTP 接口，便於第三方系統集成。
• 多音箱路由：支持維護音箱列表、設置默認音箱、按請求 did 臨時覆蓋。
• PM2 常駐：可一鍵讓 Webhook 在後臺運行，無需掛著終端。

📦 安裝指南

全局安裝（推薦）

# npm
npm i -g xiaoii

# 或 pnpm
pnpm add -g xiaoii

安裝後可在任何目錄使用 xiaoi 和 xiaoi-mcp 命令。

從源碼安裝

git clone https://github.com/xvhuan/xiaoi.git
cd xiaoi

# npm
npm i
npm link

# 或 pnpm
pnpm install
pnpm link --global

💻 使用示例

基礎用法

TUI 交互界面

xiaoi

CLI 命令

# 發送語音通知
xiaoi tts "代碼編譯完成"
xiaoi tts 部署已完成，請查看

# 設置音量
xiaoi volume 30

# 發送 MiOT 指令（可選 did）
xiaoi command 3 1 "[]"
xiaoi command 3 1 '[{"piid":1,"value":true}]' --did 客廳小愛

# 讀取 MiOT 屬性（可選 did）
xiaoi getprop 3 1 --did 客廳小愛

# 檢查連接狀態
xiaoi status

# 幫助
xiaoi help

高級用法

MCP Server（AI 編程助手集成）

需要先全局安裝並運行 xiaoi 完成賬號配置。

VS Code / Cursor（JSON）

在項目中創建 .vscode/mcp.json：

{
  "servers": {
    "xiaoi-voice-notify": {
      "type": "stdio",
      "command": "xiaoi-mcp"
    }
  }
}

Codex CLI（TOML）

[mcp_servers.xiaoi-voice-notify]
command = "xiaoi-mcp"

Webhook 服務（HTTP 接口）

當配置了 webhook.token 時，請在請求中攜帶請求頭：

• Authorization: Bearer <token>
• 或 X-Xiaoi-Token: <token> 也可在請求體裡傳 did 指定本次目標音箱；不傳時按默認優先級自動路由。

# 發送語音通知（可選 did 指定目標音箱）
curl -X POST http://localhost:51666/webhook/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"text":"你好，世界","did":"客廳小愛"}'

# 播放音頻（可選 did）
curl -X POST http://localhost:51666/webhook/audio \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"url":"https://example.com/audio.mp3","did":"臥室小愛"}'

# 設置音量（可選 did）
curl -X POST http://localhost:51666/webhook/volume \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"volume":50,"did":"客廳小愛"}'

# 發送 MiOT 指令（可選 did）
curl -X POST http://localhost:51666/webhook/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"siid":3,"aiid":1,"params":[],"did":"客廳小愛"}'

Webhook 常駐（PM2 一鍵啟動）

# 一鍵常駐啟動（後臺運行）
xiaoi pm2 start

# 一鍵部署（start + save）
xiaoi pm2 deploy

# 查看狀態
xiaoi pm2 status

# 查看 pm2 進程日誌（stdout/stderr）
xiaoi pm2 logs 200

# 查看 Webhook 日誌文件（~/.xiaoi/log/webhook.log 等）
xiaoi pm2 webhook-log 200

# 開關公網訪問（修改 webhook.host）
xiaoi pm2 public on
xiaoi pm2 public off

# 停止/刪除
xiaoi pm2 stop
xiaoi pm2 delete

# 保存進程列表（配合 pm2 startup 可實現開機自啟）
xiaoi pm2 save

# 生成開機自啟命令（通常需要管理員/Root 權限）
xiaoi pm2 startup

Docker 部署（容器化 Webhook）

快速開始（直接拉鏡像，不用 clone）

# 拉取鏡像
docker pull iusy/xiaoi:latest

# 一行啟動
docker run -d \
  --name xiaoi-webhook \
  --restart unless-stopped \
  -p 51666:51666 \
  -e XIAOI_USER_ID=你的小米ID \
  -e XIAOI_PASS_TOKEN=你的passToken \
  -e XIAOI_DID=你的音箱名稱 \
  -e XIAOI_DEFAULT_DID=默認音箱did \
  -e XIAOI_TOKEN=你的Webhook鑑權Token \
  iusy/xiaoi:latest

或者用 Docker Compose

# 1. 下載 docker-compose.yml 和 .env 模板
curl -O https://raw.githubusercontent.com/xvhuan/xiaoi/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/xvhuan/xiaoi/main/.env.example

# 2. 編輯 .env，填入你的信息
#    XIAOI_USER_ID、XIAOI_PASS_TOKEN、XIAOI_DID（可選 XIAOI_DEFAULT_DID）

# 3. 一鍵啟動
docker-compose up -d

📚 詳細文檔

配置

自動創建（安裝/首次運行）

安裝完成或首次執行 xiaoi 時，會自動創建：

• 目錄：~/.xiaoi/（Windows 為 %USERPROFILE%\.xiaoi\）
• 配置：~/.xiaoi/config.json（空模板）

手動配置

編輯 ~/.xiaoi/config.json：

{
    "speaker": {
        "userId": "你的小米ID（數字，不是手機號）",
        "password": "你的密碼（不推薦）",
        "passToken": "你的passToken（推薦）",
        "did": "音箱在米家中的名稱",
        "defaultDid": "默認音箱 did（可選）",
        "speakers": [
            {
                "did": "音箱 did",
                "name": "客廳小愛",
                "model": "lx04",
                "enabled": true
            }
        ],
        "ttsMode": "auto",
        "verboseLog": false,
        "ttsFallbackCommand": [5, 1],
        "ttsFallbackCommands": {
            "oh2p": [7, 3],
            "oh2": [5, 3],
            "lx06": [5, 1],
            "s12": [5, 1],
            "l15a": [7, 3],
            "lx5a": [5, 1],
            "lx05": [5, 1],
            "x10a": [7, 3],
            "l17a": [7, 3],
            "l06a": [5, 1],
            "lx01": [5, 1],
            "l05b": [5, 3],
            "l05c": [5, 3],
            "l09a": [3, 1],
            "lx04": [5, 1],
            "asx4b": [5, 3],
            "x6a": [7, 3],
            "x08e": [7, 3],
            "x8f": [7, 3]
        }
    },
    "webhook": {
        "port": 51666,
        "host": "localhost",
        "token": "",
        "logFile": "log/webhook.log"
    },
    "mcp": {
        "logFile": "log/mcp_server.log"
    }
}

配置文件查找優先級：

1. ~/.xiaoi/config.json
2. （兜底）安裝目錄/項目目錄下的 config.json

字段說明（常用）：

Webhook 默認音箱優先級：

1. speaker.defaultDid
2. XIAOI_DEFAULT_DID（環境變量）
3. speaker.did（兼容字段）

請求體顯式傳 did 時，did 必須在 speaker.speakers 中且 enabled=true，否則返回 400。

提示：在 TUI 的「賬號設置」裡可切換 TTS 模式、修改默認/機型 ttscmd、開關詳細日誌；在「連接測試」裡可手動輸入臨時 ttscmd 與臨時模式進行調試。

推薦使用 passToken 登錄。passToken 獲取參考：migpt-next/issues/4

項目結構

xiaoi/
├── bin/
│   └── xiaoi.js              # CLI + TUI 入口
├── lib/
│   ├── config.js             # 用戶目錄配置管理（自動生成 ~/.xiaoi/config.json）
│   ├── speaker.js            # 核心模塊（直連音箱 API）
│   ├── tui.js                # TUI 交互界面
│   ├── webhook_server.js     # 常駐 Webhook 服務入口（可配合 PM2）
│   └── pm2.js                # PM2 一鍵管理封裝
├── mcp_server.js             # MCP Server
├── config.example.json       # 配置模板
├── Dockerfile                # Docker 鏡像構建
├── docker-compose.yml        # Docker Compose 編排
├── docker-entrypoint.sh      # 容器啟動入口腳本
├── .env.example              # Docker 環境變量模板
└── README.md

常見問題

登錄失敗怎麼辦？

1. 確認 userId 是小米 ID（數字），不是手機號或郵箱。
2. 推薦使用 passToken 代替密碼登錄。
3. passToken 獲取參考：migpt-next/issues/4。

找不到設備？

• 確認 did 與米家 App 中音箱名稱完全一致。

致謝

本項目基於 @mi-gpt/next 構建。 https://github.com/idootop/migpt-next

🔧 技術細節

更新日誌

v1.0.10 (2026-02-14)

• 新增多音箱路由能力：支持 speaker.defaultDid 與 speaker.speakers，併兼容舊 speaker.did。
• Webhook 四個接口支持 body 傳 did（tts/audio/volume/command），不傳按默認優先級路由。
• 新增 TUI「音箱列表管理」：支持添加設備、設置默認、啟用/禁用、刪除。
• 新增 CLI MiOT 能力：xiaoi command（動作）與 xiaoi getprop（屬性讀取）。
• 新增 MCP 工具：do_action 與 get_property，並統一支持可選 did。
• Docker/文檔更新：新增 XIAOI_DEFAULT_DID 與 OH2P（xiaomi.wifispeaker.oh2p）簡單 cmd 用例。

v1.0.9 (2026-02-14)

• 修復 .mi.json（登錄憑證緩存）在任意目錄執行 CLI 時被寫到當前目錄的問題，現在固定寫入 ~/.xiaoi/ 目錄。

v1.0.8 (2026-02-12)

• 修復 Docker 容器啟動失敗：移除 pm2-runtime 不支持的 --log-date-format 參數。
• 修復 Docker 構建失敗：npm ci 改為 npm install（兼容 pnpm 項目）。
• 文檔補充 XIAOI_TOKEN 環境變量示例，方便用戶自定義 Webhook 鑑權 Token。

v1.0.7 (2026-02-12)

• 新增 Docker 容器化部署：支持通過環境變量配置，無需手動編輯配置文件，一行命令即可啟動 Webhook 服務。
• 新增 GitHub Actions CI/CD：打 tag 自動發佈 npm 包 + 構建推送 Docker 鏡像（Docker Hub + GHCR，支持 amd64/arm64 雙架構）。
• 新增 .env.example 環境變量模板，降低 Docker 部署門檻。
• 容器內使用 PM2（pm2-runtime）管理進程，自動健康檢查與重啟。

v1.0.6 (2026-02-12)

• 修復 ttscmd 輸入解析錯誤：[7,3] 不再被誤解析為 [0,7]。
• 優化賬號設置顯示：默認 ttscmd 未設置時，自動顯示當前 did 解析出的設備命令（自動映射）。

v1.0.5 (2026-02-12)

• 新增 ttscmd 自動映射日誌輸出：顯示 model / match / source / command。
• 詳細日誌統一增加 [XIAOI] 前綴，便於在 PM2/控制檯過濾檢索。

v1.0.4 (2026-02-12)

• 賬號設置頁新增按 did 自動解析機型並展示“生效 ttscmd 映射”。
• 鏈路調試能力完善：支持手動 cmd、臨時鏈路模式、詳細日誌開關。

v1.0.3 (2026-02-12)

• 新增 TTS 鏈路模式切換：auto / command / default。
• 連接測試支持手動輸入臨時 ttscmd 與臨時模式，便於現場調試。
• 新增詳細日誌開關，可顯示/隱藏 ttscmd 與默認鏈路執行細節。

v1.0.2 (2026-02-11)

• 調整 TTS 調用順序：優先 ttscmd(MiOT.doAction)，失敗後回退默認 MiNA.play(text)。
• 內置完整機型 ttsFallbackCommands 映射（含 LX04 等常見型號），並支持用戶自定義覆蓋。
• 賬號設置新增「查看設備列表並選擇 did」，可直接從設備列表一鍵寫回配置，降低 did 填錯概率。
• 配置模板/自動生成配置/README 同步新增 speaker.ttsFallbackCommand 與 speaker.ttsFallbackCommands。
• 新增主動測試模式：支持分別測試 ttscmd 鏈路和默認鏈路（MiNA.play）。
• 賬號設置新增 ttscmd 編輯入口：支持修改默認命令與按機型覆蓋命令。
• 新增 TTS 鏈路模式：支持 auto / command / default 三種模式，用戶可手動切換。
• 新增詳細日誌開關：支持顯示/隱藏 ttscmd 與默認鏈路的執行日誌。
• 連接測試支持手動輸入臨時 ttscmd 與臨時鏈路模式，便於現場調試。

v1.0.1 (2026-02-10)

• 修復 Windows 下 pm2/npm/npx 探測誤判（.cmd shim 導致的 ENOENT/不可執行問題）。
• 修復 npm v10+ 不支持 npm bin -g 導致的全局 pm2 識別失敗（改用 npm prefix -g 回退）。
• TUI 方向鍵/小鍵盤數字選擇體驗優化（減少重繪卡頓、返回不再二次回車）。
• Webhook 菜單狀態顯示優化（區分內嵌/PM2 常駐，避免誤導）。
• 新增：TUI 查看 PM2 日誌。
• 新增：每次啟動都會檢測更新（可用 XIAOI_NO_UPDATE_CHECK=1 禁用）。

📄 許可證

本項目採用 MIT 許可證，詳見 LICENSE。