小米家居 (Xiaomi Home)

核心用法

Xiaomi Home Control 技能基于 python-miio 库，通过 miiocli 命令行工具实现对小米/米家智能设备的本地局域网控制。核心操作包括：

• 设备发现与认证：使用 scripts/token_extractor.py 提取设备 IP 和 Token，存储于 references/devices.md
• MIOT 通用控制：通过 siid（服务实例 ID）和 piid（属性实例 ID）读写设备属性
• 设备专属命令：针对加湿器、电饭煲等设备提供专用 CLI 接口
• 批量状态查询：遍历设备注册表执行批量状态检查

显著优点

1. 本地优先：纯局域网通信，无需依赖小米云服务，响应延迟低且隐私性更强
2. MIOT 协议完整支持：覆盖现代小米设备的 MIOT 规范，理论上可控制绝大多数米家生态产品
3. 命令行原生集成：直接输出可执行的 miiocli 命令，便于脚本化与自动化
4. 自然语言映射：提供意图到技术命令的转换表，降低使用门槛

潜在缺点与局限性

• Token 获取门槛高：需通过抓包或第三方工具提取设备 Token，对普通用户不友好
• 网络拓扑依赖：要求控制端与设备处于同一子网，跨 VLAN 或远程场景不可用
• 协议碎片化：旧设备使用 miio 协议，新设备使用 MIOT，命令语法不统一
• click 版本依赖：需强制锁定 click<8.1.0，存在潜在兼容性问题
• 无官方背书：基于社区逆向工程，功能稳定性随小米固件更新可能失效

适合人群

• 拥有小米智能设备、注重本地隐私的技术用户
• 需要将米家设备集成到 Home Assistant 或其他自动化平台的进阶玩家
• 愿意投入时间学习 MIOT 协议、能独立解决网络问题的开发者

常规风险

| 风险类型 | 说明 | 缓释建议 |

|---------|------|---------|

| Token 泄露 | Token 相当于设备密码，泄露后可被局域网内任意控制 | 将 `devices.md` 加入 `.gitignore`，使用私钥加密存储 |

| 固件更新失效 | 小米可能通过固件更新变更协议或重置 Token | 更新前备份 Token，关注 python-miio 社区动态 |

| 误操作风险 | raw_command 可直接修改任意属性，可能触发非预期行为（如加湿器干烧） | 优先使用专用命令，操作前验证 siid/piid 对应关系 |

| 网络隔离失败 | 若 Mac 连接访客网络或 IoT 隔离 VLAN，命令将超时失败 | 确认控制端与设备 IP 段一致（如 `192.168.28.x`） |

核心功能

Xiaomi Home Control 是一款基于 python-miiio 的命令行工具封装 Skill，允许用户通过自然语言指令在本地局域网内控制小米/米家生态设备。核心能力包括：

• 设备控制：支持智能插座、加湿器、电饭煲等设备的电源开关、模式调节
• 状态查询：批量或单独查询设备运行状态、工作模式
• MIOT 协议支持：通过 siid/piid 参数操作现代米家设备的属性
• Token 管理：内置脚本辅助从小米云端提取设备认证令牌

显著优点

1. 本地优先：设备控制完全走局域网，不依赖小米云端转发，响应速度快且隐私性较好
2. 生态兼容：背靠成熟的 python-miio 开源项目，支持数百款小米设备
3. 自然语言映射：将口语化指令（如"加湿器开到最大"）精准转换为技术命令
4. Token 自动化：提供辅助脚本降低获取设备 Token 的技术门槛

潜在局限与风险

安全层面

• 凭证存储风险：设备 Token 以明文形式存储于本地 Markdown 文件，若误提交至 Git 将导致设备控制权泄露（RISK-003）
• 云端依赖：Token 提取脚本必须连接小米云服务（api.io.mi.com、account.xiaomi.com），涉及账号密码传输，且数据跨境至中国服务器
• 弱加密协议：与小米云端通信采用 RC4 算法（存在已知安全弱点），虽外层有 TLS 1.2+ 包裹，但协议层设计受限（RISK-006）
• 本地 HTTP 服务：Token 提取时启动 31415 端口展示验证码，需确保防火墙阻断外部访问

使用门槛

• 需自行获取 IP 和 Token，对非技术用户存在学习曲线
• 设备更换 WiFi 或重置后需重新提取 Token
• 部分新型设备可能尚未被 python-miio 支持

适合人群

• 注重本地控制、希望减少小米云端依赖的智能家居用户
• 具备基础命令行操作能力，能妥善处理 Token 等敏感凭证的技术用户
• 已通过 python-miio 生态积累一定经验的玩家

常规风险提醒

1. 凭证泄露：Token 等效于设备密码，一旦泄露他人可在同一网络内控制你的设备
2. 网络隔离：建议将 IoT 设备置于独立子网或 VLAN，限制潜在攻击面
3. 供应链风险：依赖 pycryptodome 等第三方库，需关注安全更新
4. 厂商协议变更：小米可能调整私有协议导致部分功能失效