前言¶

给 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