MijiaPilot - 小米-米家生态 × MCP × CLI × AI Agent × HomeKit 全桥接家庭智能家居平台。
一、用途 面向希望统一管理和自动化小米/米家生态设备的用户，提供 Web 界面、API、命令行和 AI Agent 等多入口控制方式，并可将米家设备桥接到 Apple 家庭 App 与 Siri。
二、主要能力
- Web 管理界面：设备控制、家庭/场景管理、能耗统计、自动化规则、深色模式、移动端适配。
- RESTful API：JWT 认证，完整 Swagger 文档（/api/docs/），支持第三方集成。
- CLI 工具：mijia-control 命令行，支持登录、设备列表、属性读写、场景执行。
- 实时通信：SocketIO 推送设备状态变更。
- 设备分组/收藏：自定义分组管理设备，快速收藏常用设备。
- 定时自动化规则：支持 cron、interval、日出/日落等触发方式。
- 能耗统计仪表板：按设备记录和展示能耗数据（日/小时粒度）。
- API Token 管理：为第三方应用创建和管理访问令牌。
- MCP Server：内置 MCP 协议支持，Claude Code / Hermes Agent 等 AI Agent 可直接调用。
- HomeKit 桥接：通过 Apple 家庭 App 和 Siri 控制米家设备，支持灯光、插座、传感器、温控器等。
- BLE 蓝牙传感器：PC 蓝牙直连小米 BLE 温湿度计，本地实时数据采集，支持自动化联动。
- 多用户 & 权限：用户注册登录、管理员后台、限流保护。
三、使用方式
- 复制 .env.example 为 .env 并填写实际配置。
- 启动 Web 服务（python run.py），访问 http://127.0.0.1:5000 ，注册账号后即可使用。
- 完整 API 文档：启动后访问 /api/docs/。
- MCP Server：确保 Web 服务已启动，获取 Token（MIJIA_TOKEN），在 Claude Code 等兼容 MCP 协议的 AI Agent 中使用。
- HomeKit Bridge：通过 HAP-Python 实现，在 .env 中添加或设置环境变量，获取 JWT Token，iPhone 家庭 App 添加设备扫描 QR 码或手动输入 PIN；配对后设备以「米家智能家居」桥接器形式出现。Windows 用户需安装 Bonjour Print Services 或使用 Docker 运行 Bridge。
- BLE 蓝牙传感器：需 PC 具备蓝牙功能（Windows 10/11 内置支持），设置 MIJIA_TOKEN，支持数据展示、历史查询和自动化联动（例如温度 > 30°C 自动开空调）。详细文档见 docs/ble.md。
- CLI：安装并激活虚拟环境后使用 mijia-control 命令，也可通过 Flask CLI 调用 flask mijia <command>。
四、适用场景
- 通过 Web 面板统一管理米家设备与能耗。
- 借助 REST API 或 CLI 将米家控制集成到自有系统。
- 通过 MCP 让 AI Agent 直接控制米家设备。
- 通过 HomeKit 用 Apple 家庭 App 和 Siri 控制米家设备。
- 利用 BLE 蓝牙直连传感器实现本地数据采集与自动化联动。
五、限制与说明
- 本项目基于 GPL-3.0 许可证开源，继承自上游 mijiaAPI 的许可协议。
- 底层使用 Do1e/mijia-api（mijiaAPI v3.0+）提供的 Python SDK，用于与小米云端进行设备通信、属性读写和场景执行。
- v1.0.3 修复 SQLAlchemy 数据库 URI 的 SQLite 默认值；Werkzeug 3.1+ 安全限制下 run.py 添加 allow_unsafe_werkzeug=True 仅保障开发环境启动。
- SQLite 仅在未配置 DATABASE_URL 时作为 fallback；从 MySQL 首次切换到 SQLite 或新建 SQLite 数据库时，需执行 flask db upgrade 创建表，并通过 Web 界面或 /api/auth/register 注册用户，再绑定小米账号后方可使用设备控制功能。
- 当设备型号不在内置规则中时，Bridge 会自动从 spec_data 推断类型；如不准确可创建 homekit_mapping.yaml 自定义映射，可用类别包括 light、outlet、switch、temperature_sensor、thermostat、heater、camera、ignored。
- 具体收费、价格、平台支持与使用效果等信息暂未提供。
