前言¶

在 DSH（DeepSeek Harness）裏控制米家設備，常見做法是讓模型讀設備狀態、再生成控制指令，每次操作都會佔用上下文和調用額度。若你只是想開關燈、調風速或跑一個手動場景，把整條鏈路都交給大模型並不划算。

下面介紹社區插件 dsh-mijia-sidebar（維護者 EchoChan314，分類：客戶端）：在 DSH 側邊欄提供「米家控制」面板，設備列表、屬性讀寫、設備動作與手動場景通過本機 mijiaAPI CLI 執行，經插件私有 RPC 通道到達 Host 半區，不經過模型回合。

這是什麼¶

dsh-mijia-sidebar 是 DSH 的 bundle 插件，入口爲 cordis.patch.yml，同時提供 Host 半區（lib/index.js）與瀏覽器半區（lib/client.js）。面板在側邊欄註冊入口，打開後可刷新設備、展開卡片進行控制。

與「讓模型寫 mijia 命令再執行」相比，面板操作走 /mijia RPC（動作包括 snapshot、props、state、get、set、action、run_scene、setHidden 等），Host 半區直接調用 python -m mijiaAPI，不佔用模型上下文。

核心功能¶

不經過大模型的控制鏈路¶

所有面板操作經包內 /mijia 通道（ctx.connection.register）到 Host 半區，由本機 CLI 與米家雲端通信。設備列舉、批量讀屬性、規格中文說明等還配合助手腳本 lib/state.py（list / state / spec 三種模式）。

面板能力¶

• 場景：手動場景按鈕，一鍵 run_scene。
• 設備卡片：網格展示；展開後分「控制 / 狀態 / 動作」三組。bool 用開關，enum 用選項按鈕，數值用滑塊加「設置」，文本可輸入提交；只讀屬性直接顯示值。
• 一次讀回全部屬性：展開設備時用一次雲調用取該設備全部可讀屬性，避免對每個屬性單獨 get。
• 中文說明：屬性名與枚舉優先從 miot-spec multiLanguage 拉取（本地緩存 7 天），否則回退內置詞表；枚舉顯示爲「說明（原值）」。
• 隱藏與別名：可在面板隱藏設備並在底部恢復；按 model 配置顯示別名（也可寫配置文件）。
• 展開狀態持久化：當前展開設備記在瀏覽器 localStorage。
• 內置分類圖標：按型號關鍵字匹配線性圖標；若字段帶回圖標地址則直接使用。

配置與日誌¶

配置文件路徑：$DSH_HOME/mijia-sidebar.config.json，默認 ~/.dsh/mijia-sidebar.config.json（Windows 爲 %USERPROFILE%\.dsh\mijia-sidebar.config.json）。示例：

{
  "hiddenDids": ["105830834"],
  "aliases": {
    "zhimi.fan.za4": "落地扇",
    "yeelink.light.stripe": "客廳吊燈"
  }
}

環境變量：MIJIA_PYTHON 指定運行 mijiaAPI 的解釋器；DSH_HOME 默認爲 ~/.dsh。解釋器候選順序爲 MIJIA_PYTHON → python3 → python →（僅 Windows）py -3。

改動設備的操作會寫入 $DSH_HOME/mijia-sidebar.log，單文件上限 1 MiB，輪轉保留一份歷史。

安裝與啓用¶

前置條件：

1. Python ≥ 3.10，且 python3 或 python 在 PATH 中。
2. 同一解釋器安裝 mijiaAPI：pip install mijiaAPI 或 python -m pip install mijiaAPI。
3. 掃碼登錄：python -m mijiaAPI login，憑證在 ~/.config/mijia-api/auth.json（與 mijia MCP server 共用，插件不另存）。
4. DSH 需具備 Host 側的 connection 與 webServer 服務；Node 引擎要求 ≥ 20（見 package.json）。

三種安裝方式效果相同，裝完後重啓或刷新 DSH。Host 半區（lib/*.js、lib/*.py）有改動時，須在 DSH 裏重啓插件進程；僅改瀏覽器半區時刷新頁面即可。

從本地目錄安裝（bundle）¶

在 DSH 會話裏執行，路徑指向倉庫或解壓目錄：

plugin_manager install_bundle /path/to/dsh-mijia-sidebar

從 GitHub 獲取後安裝¶

git clone https://github.com/EchoChan314/dsh-mijia-sidebar.git
plugin_manager install_bundle ./dsh-mijia-sidebar

從 npm 安裝¶

npm install dsh-mijia-sidebar
plugin_manager install_bundle ./node_modules/dsh-mijia-sidebar

典型用法¶

1. 完成 mijiaAPI 登錄與插件安裝後，在 DSH 側邊欄點擊「米家控制」入口打開面板。
2. 使用頂部「刷新」拉取設備快照；在「場景」區點擊如「回家」「離家」等手動場景。
3. 點擊設備卡片展開：在「控制」區改開關、檔位或滑塊；在「動作」區點「開機」「關機」等按鈕。
4. 不需要某設備時，用卡片右上角隱藏；底部「已隱藏設備」可恢復。別名可在面板操作後寫回配置文件，或事先編輯 mijia-sidebar.config.json 中的 aliases。

寫入屬性後面板會先樂觀更新再回讀比對（米家雲端立即回讀常返回舊值），最多重試幾次。

適用場景與注意¶

適合誰：已在 DSH 日常開發或對話中使用、家裏設備接入米家、希望側邊欄一點就控、且願意在本機維護 Python 與 mijiaAPI 登錄態的開發者或高級用戶。

權限與安全：插件以當前 DSH 進程權限運行，會啓動本機 Python 調用 mijiaAPI；安裝前建議閱讀倉庫源碼與 MIT 許可證。列表下發到瀏覽器半區的設備字段僅 did、name、model、spec_type、online、icon 六項，不含 token、localip 等；憑證僅由 mijiaAPI 讀寫，插件不復制轉發。需要屬性中文說明時會請求 miot-spec.org（不含設備信息與憑證），結果緩存在 ~/.config/mijia-api/<spec_type>.lang.json。

常見錯誤（面板頂部錯誤卡片，message 爲處理指引）：

DSH 生態強調「一切皆插件」；社區目錄 SkillHub 插件頁 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-mijia-sidebar 把米家設備控制收進 DSH 側邊欄：場景、屬性與動作走本機 mijiaAPI 與私有 RPC，不佔用模型回合。需要細節、截圖與開發說明時，以倉庫 README 爲準。

• 目錄頁：https://www.skillhub.cn/plugins/EchoChan314/dsh-mijia-sidebar
• GitHub：https://github.com/EchoChan314/dsh-mijia-sidebar