mijia-api

name	mijia-api
description	通过 `uvx mijiaAPI` CLI 控制米家智能设备。适用于：列出米家设备/家庭/场景/耗材、 获取或设置设备属性、执行设备动作、查询统计数据、运行场景、通过小爱音箱执行自然语言命令。 触发词包括"控制米家设备"、"米家"、"mijia"、"列出设备"、"设置亮度"、"打开灯"、 "执行动作"、"统计数据"、"耗电量"、"运行场景"、"小爱音箱"、"耗材"、"场景"。
allowed-tools	Bash(uvx mijiaAPI:*)

mijia-api CLI

通过 uvx mijiaAPI 命令行工具控制米家智能设备。所有命令均通过 uvx 运行， 无需本地安装（首次运行时自动下载包）。CLI 实现位于 mijiaAPI/__main__.py。

行为规则（关键）

1. 绝对不要调用 login。 登录流程会在终端显示二维码，并阻塞等待用户用手机 扫码，会导致会话一直挂起。如果需要登录，停止操作并提醒用户自行执行：

   uvx mijiaAPI login -p [path]
   

2. 绝对不要调用 mcp。 它会启动一个长时间运行的 stdio MCP server，永久阻塞。 该命令用于在 MCP 客户端配置中作为 server 启动，不能直接调用。

3. 其他所有命令（list、get、set、action、statistics、run、run_scene、get_device_info）均为非阻塞， 可以直接调用。

4. 如果任何命令以退出码 1 退出，并打印类似 请调用 'mijiaAPI login' 进行扫描登录 的信息，说明认证文件缺失、损坏或已过期。不要尝试自行修复，提醒用户执行上述 登录命令后停止。

5. 使用 bash 工具调用 uvx 命令时设置较长超时——首次运行可能需要下载包。

认证文件

认证文件默认路径为 ~/.config/mijia-api/auth.json，可用 -p /path/to/auth.json 覆盖。

• 全局参数（--list_devices、--list_homes 等）：-p 放在参数前： uvx mijiaAPI -p /path --list_devices
• 子命令（get、set、action、statistics、run）：-p 放在子命令后： uvx mijiaAPI get -p /path --dev_name "台灯" --prop_name "brightness"

认证失效时，init_api 会打印提示信息并以退出码 1 退出，提示用户运行 mijiaAPI login。将该提示转达给用户——不要自行运行 login。

命令总览

命令 / 参数	用途	需要认证	阻塞
login	二维码登录	否（创建认证）	是——禁止调用
mcp	启动 MCP server（stdio）	是	是——禁止调用
-l、--list_devices	列出所有设备（含共享）	是	否
--list_homes	列出家庭、房间和设备	是	否
--list_scenes	列出各家庭场景	是	否
--list_consumable_items	列出各家庭耗材	是	否
--run_scene 名称/ID [...]	运行一个或多个场景	是	否
--get_device_info MODEL	按 model 获取设备规格	否	否
get	读取设备属性	是	否
set	设置设备属性	是	否
action	按动作名执行设备动作	是	否
statistics	获取设备统计数据	是	否
run	通过小爱音箱执行自然语言命令	是	否

全局参数（--list_devices、--list_homes、--list_scenes、--list_consumable_items、 --run_scene、--get_device_info）可在一次调用中组合使用；其中 --get_device_info 在认证检查之前执行，因此无需登录即可使用。

典型工作流

1. 列出设备，获取设备名称和 model：

   uvx mijiaAPI -l
   

   输出每个设备的 name、did、model、online 状态。

2. 按 model 查看设备支持的属性和动作（无需登录）：

   uvx mijiaAPI --get_device_info yeelink.light.lamp4
   

   返回 JSON，描述设备的属性和动作。用于查找 get/set 可用的 --prop_name 和 action 可用的 --action_name。

3. 获取或设置属性（按设备名称）：

   uvx mijiaAPI get --dev_name "卧室台灯" --prop_name "brightness"
   uvx mijiaAPI set --dev_name "卧室台灯" --prop_name "brightness" --value 60
   uvx mijiaAPI set --dev_name "卧室台灯" --prop_name "on" --value True
   

4. 执行设备动作：

   uvx mijiaAPI action --dev_name "卧室台灯" --action_name toggle
   

5. 获取统计数据：

   uvx mijiaAPI statistics --did 123456 --key 7.1 --data_type stat_month_v3
   

命令详情

列出设备

uvx mijiaAPI -l
uvx mijiaAPI --list_devices
uvx mijiaAPI -p /path/to/auth.json -l

列出所有设备（包含共享设备），每项显示 name、did、model、online 状态。 name 用于 --dev_name，did 用于 --did。

列出家庭

uvx mijiaAPI --list_homes

列出家庭及其房间和房间内设备。与 --list_devices 组合可显示设备名称而非原始 did：

uvx mijiaAPI -l --list_homes

列出场景

uvx mijiaAPI --list_scenes

按家庭列出场景，每项显示 name、scene_id、创建时间。与 --list_homes 组合可避免 重复请求家庭列表：

uvx mijiaAPI --list_homes --list_scenes

运行场景

uvx mijiaAPI --run_scene "睡眠模式"
uvx mijiaAPI --run_scene 123456
uvx mijiaAPI --run_scene "晚安" "睡眠模式"

接受场景 ID 或名称（从完整场景列表中查找）。一次可运行多个场景。与 --list_scenes 组合可避免重复请求场景列表：

uvx mijiaAPI --list_scenes --run_scene "睡眠模式"

列出耗材

uvx mijiaAPI --list_consumable_items

按家庭列出耗材（如滤芯寿命、刷头磨损）。与 --list_homes 组合可复用家庭映射：

uvx mijiaAPI --list_homes --list_consumable_items

获取设备规格（无需认证）

uvx mijiaAPI --get_device_info yeelink.light.lamp4

从公开的 MIoT 规格端点获取设备规格 JSON，返回所有可用属性（含类型和约束）及动作。 无需登录——在认证初始化之前执行。用于在调用 get/set/action 前发现合法的 --prop_name、--value 和 --action_name。

获取设备属性

uvx mijiaAPI get --dev_name "卧室台灯" --prop_name "brightness"
uvx mijiaAPI get --did 123456 --prop_name "on"
uvx mijiaAPI get -p /path/auth.json --dev_name "台灯" --prop_name "on"

参数	是否必填	说明
--prop_name	是	属性名（通过 --get_device_info 发现）
--dev_name	二选一	米家 APP 中设置的设备名称
--did	二选一	设备 did（优先于 --dev_name）
-p	否	认证文件路径

输出：<设备名> (<did>) 的 <prop_name> 值为 <value>

设置设备属性

uvx mijiaAPI set --dev_name "卧室台灯" --prop_name "brightness" --value 60
uvx mijiaAPI set --dev_name "卧室台灯" --prop_name "on" --value True
uvx mijiaAPI set --did 123456 --prop_name "on" --value False

参数	是否必填	说明
--prop_name	是	属性名（通过 --get_device_info 发现）
--value	是	设定值（字符串，如 60、True、False）
--dev_name	二选一	米家 APP 中设置的设备名称
--did	二选一	设备 did（优先于 --dev_name）
-p	否	认证文件路径

成功时输出确认信息，失败时输出 设置 ... 失败: <错误>。

执行设备动作

uvx mijiaAPI action --dev_name "卧室台灯" --action_name toggle
uvx mijiaAPI action --did 123456 --action_name execute-text-directive --params '{"in":["打开空调",1]}'

参数	是否必填	说明
--action_name	是	动作名（通过 --get_device_info 发现）
--dev_name	二选一	米家 APP 中设置的设备名称
--did	二选一	设备 did
--params	否	动作参数 JSON 对象；无参数动作不要传
-p	否	认证文件路径

--params 必须是 JSON 对象。普通动作参数可传 {"value":[2]}；名为 Python 关键字的 字段也直接使用原名，例如 {"in":["打开空调",1]}。成功输出“指令已发送”。

获取统计数据

uvx mijiaAPI statistics --did 123456 --key 7.1 --data_type stat_month_v3
uvx mijiaAPI statistics --did 123456 --key 7.1 --data_type stat_day_v3 --limit 30 --time_start 1700000000 --time_end 1702592000

参数	是否必填	说明
--did	是	设备 did（从 --list_devices 获取）
--key	是	设备相关的统计键，通常为 siid.piid
--data_type	是	统计类型，见下方说明
--limit	否	最大条目数，默认 6
--time_start	否	开始 Unix 时间戳（秒），默认结束时间前 30 天
--time_end	否	结束 Unix 时间戳（秒），默认当前时间
-p	否	认证文件路径

常用统计类型为 stat_hour_v3、stat_day_v3、stat_week_v3、stat_month_v3；较旧设备 可能使用不带 _v3 的 stat_hour、stat_day、stat_week、stat_month。

统计能力和 key 因设备型号而异，不要把 7.1 当作通用值。例如 lumi.acpartner.mcn04 的耗电量使用 7.1，lumi.acpartner.mcn02 使用 powerCost。不同型号甚至 可能使用不同 API；查询失败时应向用户说明设备可能不支持，而不是反复猜测参数。

命令输出 JSON 数组，每项通常包含 Unix 秒级时间戳 time 和字符串 value。value 可能 仍是 JSON 数组字符串，例如 "[48.476]"；需要解析时仅使用 JSON 解析器，不要使用 eval()。相关限制见 https://github.com/Do1e/mijia-api/issues/46，接口参考： https://iot.mi.com/new/doc/accesses/direct-access/extension-development/extension-functions/statistical-interface

运行（通过小爱音箱执行自然语言）

uvx mijiaAPI run "打开卧室台灯"
uvx mijiaAPI run "把亮度调到50%" --wifispeaker_name "卧室小爱"
uvx mijiaAPI run "关闭所有灯" --quiet

将自然语言指令通过小爱音箱的 execute-text-directive 动作执行。未指定 --wifispeaker_name 时，自动选用第一个 model 包含 xiaomi.wifispeaker 的设备。 若未找到小爱音箱，抛出 ValueError("未找到小爱音箱设备")。

参数	是否必填	说明
PROMPT（位置参数）	是	自然语言指令
--wifispeaker_name	否	指定小爱音箱名称
--quiet	否	静默执行（音箱不播报回复）
-p	否	认证文件路径

环境变量

变量	默认值	说明
MIJIA_LOG_LEVEL	INFO	日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL

MIJIA_LOG_LEVEL=DEBUG uvx mijiaAPI -l

退出码

• 0：成功
• 1：认证文件缺失/损坏/过期（信息中包含 请调用 'mijiaAPI login' 进行扫描登录），或命令发生未处理错误。看到认证相关提示时， 提醒用户运行 uvx mijiaAPI login -p [path]。