前言¶
DeepSeek Harness (DSH) 生態強調插件化。對於需要對接智能家居設備的智能體，如何安全地獲取設備列表、讀取狀態並執行指令是一個常見需求。dsh-mihome 插件提供了這套能力，它允許 DSH 智能體操作米家設備，並強制將所有狀態變更請求置於人工審批流程之後。
插件簡介¶
dsh-mihome 是 SiriusWJ 維護的一個聯網工具插件，旨在爲 DeepSeek Harness 智能體提供米家控制接口。
- 核心功能：列出家庭與房間、讀取設備屬性、控制設備（需審批）、等待設備狀態變化、生成 Web UI 儀表盤卡片。
- 開源協議：MIT。
- 倉庫：siriuswj/dsh-mihome。
核心功能¶
該插件提供了一組工具函數，涵蓋從查詢到控制的全流程：
- 連接檢查 (
mi_health)：驗證賬戶、地區以及家庭/設備數量。 - 設備查詢 (
mi_list_homes,mi_list_devices)：獲取家庭與房間信息，列出設備詳情（包含類別、在線狀態，並支持過濾）。 - 狀態讀取 (
mi_get_state)：獲取單個設備的常用屬性，如開關狀態、亮度、溫度、溼度等。 - 設備控制 (
mi_turn,mi_control)：執行開關動作或任意miIO/raw_command。注意，這兩個功能均處於審批閘門之後。 - 狀態輪詢 (
mi_wait_for_state)：持續輪詢屬性，直到設備達到或離開指定狀態。 - 儀表盤 (
mi_dashboard)：在 Web UI 中渲染全屋狀態的實時儀表盤卡片，按類別和房間分組，並顯示近期變化。
安裝與啓用¶
使用該插件前，請確保 DSH 版本不低於 0.1.0-rc.7（已驗證於 0.1.1-rc.2）。
通過 npm 安裝插件：
dsh plugin --profile web add dsh-mihome
安裝完成後，需要重啓 dsh --profile web。在 Web UI 的設置頁面中管理此插件。
典型用法¶
插件支持兩種運行模式：演示模式和雲端連接模式。
演示模式¶
在沒有真實米家賬戶的情況下，可以使用內置的模擬服務器進行測試。
- 克隆倉庫並安裝依賴：
git clone https://github.com/SiriusWJ/dsh-mihome
cd dsh-mihome && pnpm install
- 啓動模擬服務器：
pnpm demo:mi
這會在 `http://127.0.0.1:8125` 啓動一個假米家雲。
- 在 DSH 配置中啓用插件：
- id: mihome
config:
mode: demo
baseUrl: http://127.0.0.1:8125
此時，智能體可以通過自然語言指令（如“檢查米家並列出所有設備”）進行操作。
雲端連接模式¶
連接真實的米家雲需要使用賬戶憑證。
- 設置環境變量（或使用
.env文件）：
MIHOME_USERNAME=<mi-account> MIHOME_PASSWORD=<mi-password> dsh --profile web
- 在 DSH 插件配置中指定雲端模式及區域：
- id: mihome
config:
mode: cloud
region: cn # 可選：cn / de / ru / us / tw / sg / in …
usernameEnv: MIHOME_USERNAME
passwordEnv: MIHOME_PASSWORD
requireApproval: true
allowedCategories: [light, outlet, climate] # 可選：允許操作的類別白名單
憑證通過 DSH 的憑證閘門解析（優先讀取進程環境變量，其次讀取 `.env` 文件），因此更新憑證後下次調用即可生效。
安全與注意事項¶
該插件的安全性建立在 DSH 的審批機制之上。
- 審批閘門：所有狀態變更操作（
mi_turn,mi_control）默認通過requireApproval進行攔截。當類別無法解析時，調用會被拒絕，遵循最小權限原則。 - 協議性質：雲端適配器實現的是社區文檔化的米家 App API，這是一個非官方協議。若米家更新 App，協議可能發生變化（參考
Xiaomi-cloud-tokens-extractor或python-miio的流程）。 - 錯誤提示：對於需要驗證碼或雙因素認證（2FA）的賬戶，插件會返回明確的錯誤信息，而非模糊的失敗提示。
- 運行依賴：插件本身對宿主機零依賴，僅使用 Node.js 內置的
crypto和fetch模塊。
結語¶
dsh-mihome 爲 DeepSeek Harness 提供了標準化的米家接入能力。通過將控制操作置於審批流程之後，並在類別解析層面實施白名單限制，它爲智能體控制物理設備提供了安全的基礎設施。
