小米家居 (Xiaomi Home)

核心用法

本技能基于 python-miio 库实现小米智能家居设备的本地局域网控制。用户需提前获取设备的 IP 地址和 32 字符 Token，通过 miiocli 命令行工具执行各类操作。

配置流程：
1. 使用 Xiaomi Cloud Tokens Extractor 登录米家账号提取设备 Token
2. 在 references/devices.md 中建立设备信息表（含 IP、Token、型号）
3. 通过 miiocli 执行 MIOT 协议命令

支持操作：

• 通用 MIOT 设备：查询属性（get_property_by）、开关控制（set_properties）
• 加湿器：专用 airhumidifiermiot 模块状态查询
• 电饭煲：专用 cooker 模块状态查询

显著优点

• 纯本地控制：不依赖小米云服务，响应速度快且隐私性更强
• 设备覆盖广：支持 MIOT 协议的各类小米/生态链设备
• 协议标准化：基于小米公开的 MIOT 协议，指令结构统一
• 零硬件成本：利用现有局域网基础设施，无需额外网关

潜在缺点与局限性

• Token 获取门槛：需运行第三方脚本或抓包提取 Token，对普通用户技术门槛较高
• Token 时效性：部分设备 Token 可能随固件更新或重置而变化
• 功能受限：仅能执行基础开关和状态读取，复杂场景联动需配合米家 App
• 网络绑定：必须与设备同局域网，无法远程控制（除非配合 VPN）
• 依赖维护：python-miio 需社区持续更新以适配新设备

适合人群

• 注重隐私、希望减少云端依赖的技术用户
• 需将小米设备集成到自定义自动化工作流的开发者
• 已有局域网基础设施的智能家居爱好者

常规风险

• 凭证泄露：Token 相当于设备密码，明文存储在配置文件中有泄露风险
• 依赖冲突：已知 click>=8.1.0 会导致 TypeError，需锁定旧版本
• 网络稳定性：局域网波动会导致控制失败，无云端 fallback 机制
• 设备误操作：命令行操作缺乏确认机制，存在误触开关的可能
• 固件兼容性：小米未公开承诺协议稳定性，固件升级可能破坏兼容性

核心用法

Xiaomi Home Control 是一个基于 python-miio 库的智能家居控制 Skill，允许用户在本地网络内通过 miiocli 命令行工具操控小米生态设备。使用时需先在本地网络环境中配置设备的 IP 地址和 32 字符 Token（通过 Xiaomi Cloud Tokens Extractor 获取），随后在 references/devices.md 中建立设备清单，即可执行开关电源、查询状态、调节 MIOT 属性等操作。

支持的设备类型涵盖智能插座（cuco.plug.v3 等）、加湿器（airhumidifiermiot）、电饭煲（cooker）等，通过 miotdevice 通用接口或专用设备驱动进行控制。

显著优点

• 本地优先：所有通信在 192.168.x.x 内网完成，无外发第三方服务器风险，隐私可控
• 功能完整：覆盖设备发现、状态轮询、属性读写、批量控制等核心 IoT 场景
• 生态兼容：借助 python-miio 社区驱动，支持数百种小米/米家设备型号
• 零云服务依赖：无需小米云账号持续授权，Token 一次获取长期有效

潜在缺点与局限性

• 凭证管理繁琐：32 字符 Token 需手动提取并硬编码配置，轮换成本高
• 网络环境受限：必须与被控设备处于同一 LAN，跨网段、VPN、Docker 网络隔离场景下失效
• 无状态同步机制：Skill 本身不维护设备状态缓存，频繁查询可能触发设备限流
• MIOT 协议门槛：部分高级功能需查阅 MIOT 规范（siid/piid）手动构造 JSON 指令

适合人群

• 技术型智能家居用户，熟悉命令行与网络配置
• 隐私敏感者，倾向于本地控制而非云端方案
• 已有小米设备生态、希望集成到自动化工作流（与 Home Assistant、Claude 等联动）的用户

常规风险

• Token 泄露风险：设备 Token 等价于长期密码，一旦泄露可被本地网络内任意主机控制设备
• 权限滥用风险：依赖 shell.execute 权限执行外部命令，配置不当可能引发命令注入
• 供应链风险：python-miio 及 click 依赖包存在被篡改可能，需关注 CVE 公告
• 物理安全风险：智能插座、热水器等设备的误操作可能导致电气安全隐患