dsh-mihome

English | 中文

给 DeepSeek Harness 装上"控制米家智能设备"的能力：列设备、开关、调亮度、开合窗帘、启停扫地机、锁门、调温等。通过 Home Assistant 桥接，走米家云端或局域网协议。

你说："把客厅灯打开"
  └─> dsh agent 调 home_device_list   找到 light.客厅_吸顶灯
  └─> dsh agent 调 home_device_set    动作 on
  └─> 本插件 POST /api/services/light/turn_on（HA REST API）
  └─> HA 经米家云（或局域网协议）下发指令
  └─> 灯亮，返回"已执行 light.turn_on"

特性

• 3 个模型可见工具：home_device_list（列设备/关键字过滤）、home_device_set（控制）、home_device_state（查状态）
• 动作按设备域自动翻译：灯/插座/风扇/空调 → turn_on/off，窗帘 → open/close，扫地机 → start/stop，门锁 → lock/unlock；未知动作直通任意 HA 服务名（如 set_temperature）
• 凭据零硬编码：token 只经环境变量注入，可安全开源
• 设备 attributes 白名单截取，避免整包状态塞进上下文

环境要求

| 依赖 | 说明 | |---|---| | DeepSeek Harness | dsh 源码仓库（提供 CLI 与运行时） | | Home Assistant | 米家设备桥接层（部署方式不限，见工作原理） | | 米家账号 | 中国大陆或海外区均可（Miot Auto 支持多区域） |

快速开始

1. 部署 Home Assistant（macOS/Linux，docker）

docker compose -f docker/docker-compose.ha.yml up -d
# 打开 http://127.0.0.1:8123 初始化

已有 HA 实例？跳过这一步，把第 4 步的 HA_BASE_URL 指向你自己的 HA 即可。

2. 接入米家（中国大陆账号）

⚠️ 不要用 HA 自带的 "Xiaomi Home" 集成（那个用户名密码框实际是老 Miio，国区登录不稳）。装 HACS + Xiaomi Miot Auto：

docker exec -it homeassistant bash -c "wget -O - https://get.hacs.xyz | bash -"
docker restart homeassistant

浏览器：设置 → 设备与服务 → 添加集成 → 搜 HACS → GitHub 授权 → 左侧出现 HACS → HACS → 集成 → 浏览并下载存储库 → 搜 Xiaomi Miot Auto → 安装并重启 → 添加集成 → 搜 Xiaomi Miot Auto → 账号集成 → 米家账号密码 + 区域 cn → 选家庭导入设备。

账号登录报 verification ticket rejected 时，先在浏览器登录一次 account.xiaomi.com 解锁风控，再回 HA 重试。

3. 创建长期访问令牌

HA 里 个人资料 → 安全 → 长期访问令牌 → 创建令牌。

4. 配置环境变量

写入 deepseek-harness 仓库根 .env（或 export）：

HA_BASE_URL=http://127.0.0.1:8123
HA_TOKEN=<上一步的令牌>
DEEPSEEK_API_KEY=<你的 DeepSeek key>

5. 运行

./scripts/mihome.sh "列出我家的设备"
./scripts/mihome.sh "把客厅主灯调亮到 50%"
./scripts/mihome.sh "关掉空气净化器"

底层等价命令（在 deepseek-harness 仓库根）：

CI=true pnpm dsh --profile headless \
  --patch <本仓库绝对路径>/cordis/mihome.patch.yml "任务"

cordis/mihome.patch.yml 里的 name 用的是绝对路径（dsh loader 以 profile 目录为解析根）——clone 到别处请改成你的实际路径。

接入你自己的 dsh

前提：已有 dsh（clone deepseek-harness + pnpm install + pnpm run build），并配置 DEEPSEEK_API_KEY。

方式 A：临时叠加（--patch）

CI=true pnpm dsh --profile headless \
  --patch <本仓库绝对路径>/cordis/mihome.patch.yml "任务"

只对本次命令生效。cordis/mihome.patch.yml 里的 name 请改成你的实际路径。

方式 B：永久接入（推荐）

编辑 profile 补丁文件 ~/.dsh/profiles/headless/cordis.patch.yml（web 为 ~/.dsh/profiles/web/），插入：

- insert:
    - id: mihome
      name: '<本仓库绝对路径>/src/mihome.ts'
      config:
        baseUrl: !!js "process.env.HA_BASE_URL ?? 'http://127.0.0.1:8123'"
        token: !!js "process.env.HA_TOKEN ?? ''"

之后每次 dsh 启动自动加载，无需再传 --patch。

方式 C：npm 安装（推荐）

# 在 profile 目录下安装（如 ~/.dsh/profiles/headless）
npm install dsh-mihome

patch 里直接用包名引用：

- insert:
    - id: mihome
      name: 'dsh-mihome'
      config:
        baseUrl: !!js "process.env.HA_BASE_URL ?? 'http://127.0.0.1:8123'"
        token: !!js "process.env.HA_TOKEN ?? ''"

包名方式与路径无关，升级只需 npm update dsh-mihome，是长期使用的最优解。

最后配置环境变量（deepseek-harness 根 .env 或 export）：HA_BASE_URL、HA_TOKEN。

模型可见工具

| 工具 | 作用 | 关键参数 | |---|---|---| | home_device_list | 列出全部/按关键字过滤设备 | area（可选，如"客厅"） | | home_device_set | 控制设备 | entity_id、action（on/off/toggle/open/close/start/stop/…或任意服务名）、data（可选，如亮度/温度） | | home_device_state | 查单设备状态与关键属性 | entity_id |

动作自动按设备域翻译：灯/插座/风扇/加湿器/音箱/空调 → turn_on/turn_off，窗帘 → open_cover/close_cover，扫地机 → start/stop/return_to_base，门锁 → lock/unlock。未知动作直通为 {域}.{动作}，所以 set_temperature 这类服务名也直接可用。

常用问法

• "列出我家的设备"
• "把客厅灯调亮一点"（模型会带 data: {brightness: ...}）
• "空调设到 26 度"
• "扫地机回充"
• "卧室窗帘拉开"

工作原理：为什么需要 HA

米家设备不开放公网直连，因此需要 Home Assistant 作为"翻译官"登录米家账号并暴露统一的 REST API。本插件只做一件事：把模型可见工具翻译成 HA 的 REST 调用。

用不用 docker？ 不用。docker 只是 HA 的一种部署方式（本仓库的 compose 是最省事的一种）。插件本身只是一个 HTTP 客户端，对 HA 的部署形态无感知——对方已有 HA 时连桥都不用装，只需配置 HA_BASE_URL。HA 也可以用 HA OS（树莓派/迷你主机）、NAS 套件、Python venv 等方式部署。

开发与验证

• scripts/smoke.mjs：单元冒烟（mock HA），无需真实设备。需在 deepseek-harness 仓库的 examples 环境跑（依赖 @deepseek-ai/dsh-tools 等 workspace 包）。
• scripts/ha-live.mjs：真实联调，直驱插件连真实 HA（无需 API key）：

  HA_TOKEN=<令牌> node --import tsx/esm scripts/ha-live.mjs list
  HA_TOKEN=<令牌> node --import tsx/esm scripts/ha-live.mjs set light.xxx on

• 类型检查：npm run typecheck（需先安装 peer 依赖）。

已知限制

• 云端模式不稳定：HA 与设备跨网段时，局域网发现失败，状态走云端且可能超时（部分设备 unavailable）。要彻底解决，把 HA 部署到设备所在网段的常开机器上走局域网直连（延迟从云端几百毫秒降到几十毫秒）。
• 红外遥控设备（miir.*）无 IP/token，仅云端可控。
• 首次响应偏慢属正常：模型思考 + 多轮工具调用 + 云端查询。可在 ~/.dsh/settings.yaml 降低 llm-deepseek 的 reasoningEffort 提速。

FAQ

为什么不用 HA 自带的 Xiaomi Home 集成？ 那个对话框实际是老的 Xiaomi Miio 集成（用户名密码 + openhab miio 链接），中国大陆账号登录极不稳定。Xiaomi Miot Auto（HACS）是国区事实标准，账号密码直登、设备支持最全。

报 verification ticket rejected？ 小米风控。先在浏览器登录 account.xiaomi.com 一次解锁，再回 HA 用账号集成重试（验证码流程走完）。

设备显示 unavailable？ HA 与设备跨网段导致局域网发现失败。把 HA 放到设备所在网段，或接受云端模式的延迟。

联系与反馈

有问题、有想法或想参与贡献？欢迎通过 GitHub Issues 交流（公开讨论）：

https://github.com/loki888666/dsh-mihome/issues

致谢

• Xiaomi Miot Auto —— 米家设备接入 HA 的社区集成
• Xiaomi-cloud-tokens-extractor —— 设备 token 提取工具（调试用）
• DeepSeek Harness —— 插件运行的 agent 框架

License

MIT