SiriusWJ/dsh-mihome

dsh-mihome

给 DeepSeek Harness agent 的米家（Xiaomi Home）控制插件。
读取家庭/设备 · 查询属性 · 控制设备——所有改变状态的调用都经过人工审批闸门。

English ·
·

✨ 效果预览

| ① 提问 | ② 审批闸门 | ③ 完成——状态真的变了 |
|---|---|---|
| agent 用 mi_list_devices 列出你的设备。 | mi_turn / mi_control 暂停，弹出人工审批框。 | 批准后设备状态更新，mi_get_state 确认。 |

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

🏠 米家仪表盘 · 14 台设备 · 12 在线 · 18:32:05
🏠 客厅  🏠 卧室  🏠 厨房
💡 灯光        💡 客厅灯  on · brightness 100%      💡 卧室灯  off
🔌 插座        🔌 客厅插线板  on · 32 W              …
📊 传感器      🌡️ 客厅温湿度  temperature 22.5°C   💧 卧室温湿度  humidity 52%
…
🕐 最近变化    卧室灯: power — → on   18:31

没有米家账号也能玩 —— 自带演示模拟器（pnpm demo:mi）+ 交互式演示页（docs/demo.html），5 分钟完整体验。

🎯 能做什么？

像跟管家说话一样指挥你的家——所有写操作都先经过人工审批：

| 你说 | 会发生什么 |
|---|---|
| 「检查米家连接，列出所有设备」 | mi_health / mi_list_devices 扫描并汇总 |
| 「客厅灯开着吗？卧室呢？」 | mi_get_state 按需读取属性 |
| 「给我看看家庭仪表盘。」 | mi_dashboard 在对话里渲染实时仪表盘卡片——分类、房间、最近变化一览无余 |
| 「关掉卧室灯。」 | mi_turn → 审批弹窗 → 执行 → 状态即时更新 |
| 「把客厅灯调到 60% 亮度。」 | mi_control（set_bright）→ 审批弹窗 → 执行 |
| 「等空调到 24° 再告诉我。」 | mi_wait_for_state 轮询到目标状态 |
| 「出门模式：把所有灯都关掉。」 | 批量 mi_turn（每条都过审批） |

🛠 功能

| 工具 | 说明 | 审批 |
|---|---|---|
| mi_health | 验证连接；返回账号、区域、家庭数、设备数 | 只读 |
| mi_list_homes | 列出家庭与房间（home_id / owner_id / 房间） | 只读 |
| mi_list_devices | 列出设备，按名称/类别过滤（light、outlet、sensor、climate…） | 只读 |
| mi_get_state | 单设备状态：在线状态、类别、常见属性（power/brightness/温度/湿度/电量…） | 只读 |
| mi_turn | set_power 开/关设备 | 需批准 |
| mi_control | 任意 miIO raw_command：set_bright、set_properties（MIoT）… | 需批准 |
| 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

或从 GitHub 安装（源码安装，pnpm 会在安装时自动构建）：
dsh plugin --profile web add github:/dsh-mihome

安装后重启 dsh --profile web。可在 Settings → Plugins 管理。

🧪 没有米家账号？先玩演示模式

git clone https://github.com//dsh-mihome
cd dsh-mihome
pnpm install
pnpm demo:mi          # 在 http://127.0.0.1:8125 起一个假的米家云

在 profile 的 cordis.patch.yml 里配置：

- id: mihome
config:
mode: demo
baseUrl: http://127.0.0.1:8125

然后启动 dsh 试试：

「检查米家连接，然后列出所有设备。」

「把卧室灯调到 60 亮度。」——会弹出审批请求；批准后 mi_get_state 显示 brightness: 60。

「关掉客厅里所有的灯。」

模拟器里的温度传感器每几秒漂移一次，所以仪表盘和「最近变化」永远有新数据。

想完全不启动 dsh 就先看效果？ 用浏览器打开 docs/demo.html：模拟 DSH 对话（工具卡片 + 审批弹窗），右侧实时控制台直连模拟器做真实调用。

可直接粘贴的配置（演示 / 真实米家 / 关闭审批）见 examples/cordis.patch.yml。

⚙️ 配置

在 profile 的 cordis.patch.yml 中覆盖插件配置（后层覆盖前层）：

- id: mihome
config:
mode: cloud                # cloud 或 demo
region: cn                 # 米家账号区域：cn / de / ru / us / tw / sg / in…
usernameEnv: MIHOME_USERNAME   # 存放账号的环境变量名
passwordEnv: MIHOME_PASSWORD   # 存放密码的环境变量名
timeoutMs: 15000
requireApproval: true      # 改变状态的调用需要人工批准
allowedCategories: []      # 可控制类别白名单，例如 [light, outlet, climate]；留空 = 全部允许
dashboardPropsLimit: 30    # 仪表盘拉取属性的设备上限
recentBufferSize: 50       # 最近变化缓冲大小

然后带上环境变量启动：

MIHOME_USERNAME= MIHOME_PASSWORD= dsh --profile web

username / password 也可以直接写进配置，但强烈建议用 usernameEnv / passwordEnv 走环境变量或 credentials 接缝——凭证每次请求重新解析，轮换无需重启。

🔒 安全说明

- 运输安全：米家云 API 使用账号密码登录换取一次性会话（serviceToken / ssecurity），插件不在本地保存密码，只在使用时通过凭证接缝读取。
- 审批闸门：mi_turn / mi_control 永远走 harness 的审批接缝（requireApproval: true 默认开启）——agent 不经你同意碰不了你的家。
- 类别白名单：allowedCategories 是第二道保险，设置后其他类别的控制调用直接被拒绝，且设备类别解析失败时默认拒绝（最小权限）。
- 账号安全：建议开启米家 App 的「设备授权」验证；如账号触发验证码/2FA 登录（部分账号会有安全风控），当前版本会给出明确报错——这种情况请用无 2FA 的账号或等待风控解除。

⚠️ 已知限制

- 云 API（account.xiaomi.com / api.io.mi.com）非官方文档，接口可能随米家 App 更新而变化；本插件按社区验证过的登录/签名流程实现（参考 Xiaomi-cloud-tokens-extractor / python-miio）。
- 不支持的场景：米家账号需验证码/2FA；分组设备（get_split_device 的子设备）属性读取可能受限。
- 本地直连（miIO UDP + 设备 token）规划中，接入后不依赖云端即可控制局域网设备。

🛠 开发

pnpm install
pnpm typecheck   # 针对 @deepseek-ai/* 类型做严格 TS 检查
pnpm build       # 打包 lib/（ESM + d.ts）
pnpm test        # 签名/加密原语 + 演示服务器端到端测试

📋 兼容性

- Host 端零运行时依赖：Node 内置 crypto / fetch + 标准库，无 MQTT、无额外守护进程。
- 已针对 npm 发布的 @deepseek-ai/dsh@0.1.1-rc.2 类型验证；harness 更新导致不兼容请提 issue。

📄 许可证

MIT