dsh-smarthome

Home Assistant control for DeepSeek Harness agents — read entity states, query history, and call services behind an approval gate.

Agent 协作

包名: dsh-smarthome
版本: 1.3.0
许可证: MIT
最近更新: 2026年8月14日

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:YLifeOnlyOnce/dsh-smarthome

说明文档

阅读完整 README ↗

给 DeepSeek Harness agent 的 Home Assistant 控制插件。

读取实体状态 · 查询历史 · 调用服务——所有改变状态的调用都经过人工审批闸门。

English · · ·

除 harness 本身外零运行时依赖。使用 Home Assistant 内置 REST API——不需要 MQTT、WebSocket 或额外守护进程。

✨ 效果预览

点击图片可打开在线演示 —— docs/demo.html 会模拟完整的 DSH 对话，右侧实时控制台直连自带的 HA 模拟器（不需要真实 Home Assistant）。

① 提问	② 审批闸门	③ 完成——状态真的变了

还有 Web UI 仪表盘卡片 —— 调用 ha_dashboard，全屋状态直接渲染在对话里：

家庭仪表盘

它接入的就是这样的 Home Assistant（典型智能家居仪表盘，示意图）：

Home Assistant 仪表盘示意图

dsh-smarthome · DSH Hub

你说	会发生什么
「检查一下全屋，哪些设备还开着？」	agent 用 `ha_list_entities` / `ha_get_state` 扫描并汇总
「给我看看家庭仪表盘。」	`ha_dashboard` 在对话里渲染实时仪表盘卡片——设备、场景、最近变化一览无余
「把卧室灯调到 200 亮度。」	`ha_call_service` → 审批弹窗 → 执行 → 状态即时更新
「关掉客厅里所有的灯。」	区域定位——一次调用控制整间房
「开启电影模式。」	场景联动：灯调暗、电视打开——一条命令多设备联动（`ha_events` 实时显示每个变化）
「过去一小时家里发生了什么变化？」	WebSocket 实时事件流
「客厅温度够吗？和卧室比一下。」	`ha_get_state` / `ha_render_template` 查传感器、算模板
「我要出门了，把一切都关掉。」	一个场景（`scene.away`）或批量实体调用

工具	说明	审批
`ha_health`	验证连接；返回实例名、版本、时区、WebSocket 状态	只读
`ha_list_entities`	列出实体，按 domain（`light`、`switch`、`sensor`…）和文本过滤	只读
`ha_list_areas`	通过 WebSocket 列出房间（区域），如 `living_room`	只读
`ha_list_devices`	通过 WebSocket 设备注册表列出物理设备	只读
`ha_get_state`	单个实体的完整状态与属性	只读
`ha_history`	一段时间内的状态变化时间线	只读
`ha_events`	WebSocket 缓冲的最近实时状态变化	只读
`ha_list_scenes`	列出一键场景（`cinema`、`goodnight`、`away`…）	只读
`ha_dashboard`	全屋快照，在 Web UI 里渲染为仪表盘卡片	只读
`ha_call_service`	调用任意服务——按实体、按区域（整间房）、按设备、按场景	需批准
`ha_render_template`	服务端渲染 Jinja2 模板	需批准

# 从 npm 安装（推荐，预构建产物）：
dsh plugin --profile web add dsh-smarthome

# 或从 GitHub 安装（源码安装，pnpm 会在安装时自动构建）：
# dsh plugin --profile web add github:YLifeOnlyOnce/dsh-smarthome
# 如果 pnpm 拒绝运行 git 依赖的 prepare 构建脚本，需要放行一次：
#   在 
/pnpm-workspace.yaml 里加上，然后重新执行 add：
#     allowBuilds:
#       dsh-smarthome: true

git clone https://github.com/YLifeOnlyOnce/dsh-smarthome
cd dsh-smarthome
pnpm install
pnpm demo:ha          # 在 http://127.0.0.1:8124 起一个假的 Home Assistant

- id: smarthome
  config:
    baseUrl: http://127.0.0.1:8124
    tokenEnv: HOME_ASSISTANT_TOKEN

HOME_ASSISTANT_TOKEN=demo-token dsh --profile web

- id: smarthome
  config:
    baseUrl: http://192.168.1.10:8123   # 你的 Home Assistant 实例
    token: ''                           # 建议用 tokenEnv，不要把令牌写进配置
    tokenEnv: HOME_ASSISTANT_TOKEN      # 存放令牌的环境变量名
    timeoutMs: 15000
    requireApproval: true               # 改变状态的调用需要人工批准
    allowedDomains: []                  # 例如 ["light", "switch"]；留空 = 允许所有 domain
    maxHistoryEvents: 200
    wsEnabled: true                     # 实时事件 + 区域注册表（WebSocket）
    eventBufferSize: 50                 # ha_events 滚动缓冲大小

HOME_ASSISTANT_TOKEN= dsh --profile web

pnpm install
pnpm typecheck   # 针对已发布的 @deepseek-ai/* 类型做严格 TS 检查
pnpm build       # 打包 lib/（ESM + d.ts）
pnpm test        # 24 个测试：客户端 + 真实 ToolRuntime 集成 + 完整 agent-loop 端到端
node scripts/capture-demo.mjs   # 重新生成 README 截图

dsh-smarthome

安装

说明文档

✨ 效果预览

🎯 能做什么？

💡 为什么好用？

💻 你的电脑就是控制中心

🛠 功能

📦 安装

🧪 没有 Home Assistant？先玩演示模式

⚙️ 配置

令牌如何解析

🔒 安全说明

🛠 开发

📋 兼容性

真实 Home Assistant 兼容性

📄 许可证