前言¶
DeepSeek Harness (DSH) 生态强调插件化。对于需要对接智能家居设备的智能体，如何安全地获取设备列表、读取状态并执行指令是一个常见需求。dsh-mihome 插件提供了这套能力，它允许 DSH 智能体操作米家设备，并强制将所有状态变更请求置于人工审批流程之后。
插件简介¶
dsh-mihome 是 SiriusWJ 维护的一个联网工具插件，旨在为 DeepSeek Harness 智能体提供米家控制接口。
- 核心功能：列出家庭与房间、读取设备属性、控制设备（需审批）、等待设备状态变化、生成 Web UI 仪表盘卡片。
- 开源协议：MIT。
- 仓库：siriuswj/dsh-mihome。
核心功能¶
该插件提供了一组工具函数，涵盖从查询到控制的全流程：
- 连接检查 (
mi_health)：验证账户、地区以及家庭/设备数量。 - 设备查询 (
mi_list_homes,mi_list_devices)：获取家庭与房间信息，列出设备详情（包含类别、在线状态，并支持过滤）。 - 状态读取 (
mi_get_state)：获取单个设备的常用属性，如开关状态、亮度、温度、湿度等。 - 设备控制 (
mi_turn,mi_control)：执行开关动作或任意miIO/raw_command。注意，这两个功能均处于审批闸门之后。 - 状态轮询 (
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
安装完成后，需要重启 dsh --profile web。在 Web UI 的设置页面中管理此插件。
典型用法¶
插件支持两种运行模式：演示模式和云端连接模式。
演示模式¶
在没有真实米家账户的情况下，可以使用内置的模拟服务器进行测试。
- 克隆仓库并安装依赖：
git clone https://github.com/SiriusWJ/dsh-mihome
cd dsh-mihome && pnpm install
- 启动模拟服务器：
pnpm demo:mi
这会在 `http://127.0.0.1:8125` 启动一个假米家云。
- 在 DSH 配置中启用插件：
- id: mihome
config:
mode: demo
baseUrl: http://127.0.0.1:8125
此时，智能体可以通过自然语言指令（如“检查米家并列出所有设备”）进行操作。
云端连接模式¶
连接真实的米家云需要使用账户凭证。
- 设置环境变量（或使用
.env文件）：
MIHOME_USERNAME=<mi-account> MIHOME_PASSWORD=<mi-password> dsh --profile web
- 在 DSH 插件配置中指定云端模式及区域：
- id: mihome
config:
mode: cloud
region: cn # 可选：cn / de / ru / us / tw / sg / in …
usernameEnv: MIHOME_USERNAME
passwordEnv: MIHOME_PASSWORD
requireApproval: true
allowedCategories: [light, outlet, climate] # 可选：允许操作的类别白名单
凭证通过 DSH 的凭证闸门解析（优先读取进程环境变量，其次读取 `.env` 文件），因此更新凭证后下次调用即可生效。
安全与注意事项¶
该插件的安全性建立在 DSH 的审批机制之上。
- 审批闸门：所有状态变更操作（
mi_turn,mi_control）默认通过requireApproval进行拦截。当类别无法解析时，调用会被拒绝，遵循最小权限原则。 - 协议性质：云端适配器实现的是社区文档化的米家 App API，这是一个非官方协议。若米家更新 App，协议可能发生变化（参考
Xiaomi-cloud-tokens-extractor或python-miio的流程）。 - 错误提示：对于需要验证码或双因素认证（2FA）的账户，插件会返回明确的错误信息，而非模糊的失败提示。
- 运行依赖：插件本身对宿主机零依赖，仅使用 Node.js 内置的
crypto和fetch模块。
结语¶
dsh-mihome 为 DeepSeek Harness 提供了标准化的米家接入能力。通过将控制操作置于审批流程之后，并在类别解析层面实施白名单限制，它为智能体控制物理设备提供了安全的基础设施。
