前言¶

給 DSH（DeepSeek Harness）寫智能體工作流的人，通常都要回答一類問題：某個會話能不能看到家裏的 Home Assistant？HA 跑在哪個地址、什麼版本、現在狀態如何？常見做法是把地址和令牌寫進文檔，或者每次開會話先讓用戶報一遍。dsh-home-assistant-panel 把這件事收斂成一次配置：在設置頁填好地址、令牌和 1–6 個觀測項，插件會把環境基線注入系統提示詞，並提供只讀的 ha_status 工具和一張實時狀態卡。

下面是這個插件的介紹。資料以 GitHub README 爲準。

這是什麼¶

dsh-home-assistant-panel 是維護者 hotkong 寫的一個 DeepSeek Harness 插件，分類爲客戶端。它的定位是隻讀：把 Home Assistant 的地址、版本、運行狀態和少量觀測值注入系統提示詞，讓每個新會話開局就知道 HA 在哪、什麼版本、什麼狀態，不用再讀文檔、不用再抄令牌。它不做設備控制、不改配置、不查日誌。

注入塊會出現在每次請求的系統提示詞裏，約 150–300 token，形如：

<home_assistant label="客廳 HA" url="http://homeassistant.local:8123">
Core 2026.10.4 ｜ Supervisor 2026.10.4 ｜ OS 18.3.1
狀態：RUNNING（recovery_mode=false，watchdog=true）
規模：42 實體 / 7 設備 / 3 區域 / 5 集成
磁盤：已用 13.8/27.7 GB
統計：亮燈數 3 ｜ 室內溫度 22.0 °C ｜ 在家 1
備註：重啓約 4.5–5 分鐘；YAML 配置文件無 API，控制走 HA 原生界面
更新：2026-11-04 16:34 (+08:00)
</home_assistant>

配置存在 profile 裏，所有 workspace 共享，因此換一個 workspace 同樣生效。

核心功能¶

插件註冊了四個入口，能力分工明確。

1. 左側主面板。左側導航裏的 Home Assistant，打開後是隻讀狀態總覽：版本、運行狀態、規模、磁盤、時區、全部觀測項、更新時間、刷新與打開 HA。配置入口提示在設置頁。
2. 右側欄速覽。在右側欄的「+ / 指南」裏添加 Home Assistant，顯示狀態點、Core/Supervisor 版本、運行狀態、實體規模、最多 3 個觀測項和更新時間；每 30 秒刷新，隱藏時暫停，可點「刷新」強制探測、「打開」跳轉 HA 實例。
3. 配置頁。位置在 設置（Settings）→ Home Assistant，頂部是完整狀態卡，下面是配置表單。
4. Agent 側。直接問「看下 HA 狀態」會調用 ha_status；系統提示詞本來就帶環境塊，問「家裏現在幾盞燈亮着」也能答上來。

各入口的註冊機制不同：設置頁註冊在 settings.section，左側主面板註冊在 sidebar.panellist + main，右側欄註冊在官方 sidebarRightTabs + sidebar.right.pane.tab。宿主缺少對應服務時該入口靜默跳過，其餘入口與 ha_status 不受影響；沒有 configForms 時，表單退化爲只讀提示。

瀏覽器通知是一個獨立開關，默認關閉，且只通知 HA 不可用與恢復，不監聽設備事件。首次加載只記基線，不會一打開就彈；連續失敗 failureThreshold 次（默認 2）才判定 DOWN；權限必須在設置頁點「啓用瀏覽器通知」申請，可發測試通知；通知需要 DSH 頁面保持打開。

安裝與啓用¶

安裝命令來自 README 原文：

dsh plugin --profile web add dsh-home-assistant-panel

裝完刷新頁面，或重啓 dsh web。插件在市場裏的名字是 dsh-home-assistant-panel。

如果 Settings 裏沒有「Home Assistant」入口，先檢查是否加進了 bundles：

dsh --profile web --dump-config | grep home-assistant

沒有這一行說明插件沒有被加進 dsh.profile.bundles，只裝進 node_modules 不夠。

本地開發時可以把倉庫 link: 進 profile 的 dependencies，並把包名加進 dsh.profile.bundles；插件自帶的 cordis.patch.yml 會自動插入 home-assistant 行，profile 的 patch 只需覆蓋 config。README 提到本機就是這麼跑的，驗證記錄在倉庫的 openspec/changes/0001-dsh-ha-plugin/tasks.md。

典型用法¶

裝好之後先配置。打開 設置 → Home Assistant，頂部是狀態卡，下面是配置表單，字段包括實例地址、顯示名、備註、訪問令牌、觀測項、是否注入提示詞、注入工作區白名單、是否統計規模。點「保存配置」或「保存令牌」立即生效，不需要重啓。

訪問令牌建議走 UI：在設置頁粘貼長期令牌後點「保存令牌」。它通過宿主憑據服務寫入 $DSH_HOME/.credentials.yaml 的 HA_TOKEN，不會進 profile 配置、日誌或市場備份；旁邊有「清除」按鈕。頁面會顯示當前解析結果，例如 credential:HA_TOKEN 或 未找到令牌。

手動場景也可以自己維護憑據文件，權限必須爲 0600：

version: 1
refs:
  HA_TOKEN: <你的長期訪問令牌>

在 profile YAML 裏直接內聯 token 屬於兜底方案，不建議使用：令牌會明文落在 cordis.patch.yml，並進入「包含配置文件」的備份。

觀測項寫在 stats 下，1–6 個，兩種寫法二選一：

stats:
  # 1) 實體快捷方式（不需要管理員令牌）
  - title: 室內溫度
    entity: sensor.living_room_temperature
    unit: " °C"
  # 2) Jinja 模板（需要管理員令牌；可做聚合）
  - title: 亮燈數
    template: "{{ states.light | selectattr('state','eq','on') | list | count }}"

實體快捷方式可選 attribute 讀取某個屬性；單項失敗只顯示 —，不影響其它項。模板只能來自配置，工具參數不接受模板——HA 的模板接口能讀取全屋狀態，不能暴露給運行時參數。

配置完成後，在會話裏可以直接問 HA 狀態，或讓它讀取觀測值。右側欄的速覽卡每 30 秒自動刷新，適合常掛在頁面上。

適用場景與注意¶

適合想把 HA 環境一次性交給 DSH 會話、並且只關心狀態的開發者或家庭用戶。如果需要控制設備、改配置、重啓、查日誌、編輯自動化、備份或讀 YAML，應改用 HA 原生界面或 HA 官方 MCP Server；dsh-home-assistant-panel 有意不做這些。v0.1 也不支持多實例，需要多個 HA 時用不同 profile。

安全方面，探測只發只讀請求，從不修改 HA；令牌在日誌、注入塊、狀態卡和瀏覽器裏都會被替換成 ***；注入塊在系統提示詞組裝時只讀緩存，不等網絡，HA 掛了不會卡住對話。憑據文件請保持 0600。

按 DSH 的插件機制，插件以當前 dsh 進程的權限運行。安裝前應看一遍源碼，確認補丁和依賴符合預期。本插件依賴 @deepseek-ai/cordis 與 @deepseek-ai/schemastery（peerDependencies，均爲可選），engines.dsh 要求 >=0.2.1-rc.1 <0.3.0-0。

幾個常見故障的排查起點：

插件版本爲 0.1.0，許可證 MIT。

結尾¶

dsh-home-assistant-panel 的價值把 HA 環境的配置收斂到一處：配一次，之後每個新會話開局就知道 HA 在哪、什麼版本、什麼狀態，同時保留只讀的狀態卡和 ha_status 工具。如果會話只需要「知道」，它足夠；如果需要「操作」，請走 HA 原生界面或 HA 官方 MCP Server。

• 目錄頁：https://www.skillhub.cn/plugins/hotkong/dsh-home-assistant-panel
• GitHub：https://github.com/hotkong/dsh-home-assistant-panel