mijiaAPI 3.1.0__tar.gz → 3.2.0__tar.gz

{mijiaapi-3.1.0 → mijiaapi-3.2.0}/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 本文档记录了项目的v1.3.7以来的重要变更。
 
+## [3.2.0](https://github.com/Do1e/mijia-api/compare/v3.1.0...v3.2.0) - 2026-06-09
+### improvement
+* 将 `--run` 参数重构为独立的 `run` 子命令，提升 CLI 结构一致性
+* 保留 `--run` 作为隐藏的废弃参数，并显示迁移提示
+
 ## [3.1.0](https://github.com/Do1e/mijia-api/compare/v3.0.5...v3.1.0) - 2026-05-27
 ### new feature
 * 删除设备属性的单位`unit`属性，因为 home.miot-spec.com 上已废弃

{mijiaapi-3.1.0 → mijiaapi-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mijiaAPI
-Version: 3.1.0
+Version: 3.2.0
 Summary: A Python API for Xiaomi Mijia
 Author-email: Do1e <i@do1e.cn>
 License-Expression: GPL-3.0-or-later
@@ -359,14 +359,17 @@ MIJIA_LOG_LEVEL=WARNING mijiaAPI get --dev_name "卧室台灯" --prop_name "brig
 完整的命令行参数说明：
 
 ```
-usage: mijiaAPI [-h] [-p AUTH_PATH] [--list_homes] [-l] [--list_scenes] 
-                 [--list_consumable_items] [--run_scene SCENE_ID/SCENE_NAME ...] 
-                 [--get_device_info DEVICE_MODEL] [--run PROMPT] 
-                 [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
-                 {get,set} ...
+usage: mijiaAPI [-h] [-v] [-p AUTH_PATH] [--list_homes] [-l]
+                   [--list_scenes] [--list_consumable_items]
+                   [--run_scene SCENE_ID/SCENE_NAME [SCENE_ID/SCENE_NAME ...]]
+                   [--get_device_info DEVICE_MODEL]
+                   {run,get,set} ...
+
+Mijia API CLI (v3.1.0)
 
 positional arguments:
-  {get,set}
+  {run,get,set}
+    run                 使用自然语言描述你的需求，如果你有小爱音箱的话
     get                 获取设备属性
     set                 设置设备属性
 
@@ -384,10 +387,6 @@ options:
                         运行场景，指定场景ID或名称
   --get_device_info DEVICE_MODEL
                         获取设备信息，指定设备model，先使用 --list_devices 获取
-  --run PROMPT          使用自然语言描述你的需求，如果你有小爱音箱的话
-  --wifispeaker_name WIFISPEAKER_NAME
-                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
-  --quiet               小爱音箱静默执行
 ```
 
 ```
@@ -417,6 +416,23 @@ options:
   --value VALUE         需要设定的属性值
 ```
 
+```
+usage: mijiaAPI run [-h] [-p AUTH_PATH]
+                       [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
+                       PROMPT
+
+positional arguments:
+  PROMPT                使用自然语言描述你的需求
+
+options:
+  -h, --help            show this help message and exit
+  -p, --auth_path AUTH_PATH
+                        认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json
+  --wifispeaker_name WIFISPEAKER_NAME
+                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
+  --quiet               小爱音箱静默执行
+```
+
 #### 获取设备属性
 
 ```bash
@@ -465,9 +481,9 @@ mijiaAPI --get_device_info yeelink.light.lamp4
 mijiaAPI --list_consumable_items
 
 # 使用小爱音箱执行自然语言命令
-mijiaAPI --run "打开卧室台灯"
-mijiaAPI --run "把亮度调到50%" --wifispeaker_name "卧室小爱"
-mijiaAPI --run "关闭所有灯" --quiet
+mijiaAPI run "打开卧室台灯"
+mijiaAPI run "把亮度调到50%" --wifispeaker_name "卧室小爱"
+mijiaAPI run "关闭所有灯" --quiet
 ```
 
 #### 直接使用 uvx（无需安装）

{mijiaapi-3.1.0 → mijiaapi-3.2.0}/README.md

@@ -339,14 +339,17 @@ MIJIA_LOG_LEVEL=WARNING mijiaAPI get --dev_name "卧室台灯" --prop_name "brig
 完整的命令行参数说明：
 
 ```
-usage: mijiaAPI [-h] [-p AUTH_PATH] [--list_homes] [-l] [--list_scenes] 
-                 [--list_consumable_items] [--run_scene SCENE_ID/SCENE_NAME ...] 
-                 [--get_device_info DEVICE_MODEL] [--run PROMPT] 
-                 [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
-                 {get,set} ...
+usage: mijiaAPI [-h] [-v] [-p AUTH_PATH] [--list_homes] [-l]
+                   [--list_scenes] [--list_consumable_items]
+                   [--run_scene SCENE_ID/SCENE_NAME [SCENE_ID/SCENE_NAME ...]]
+                   [--get_device_info DEVICE_MODEL]
+                   {run,get,set} ...
+
+Mijia API CLI (v3.1.0)
 
 positional arguments:
-  {get,set}
+  {run,get,set}
+    run                 使用自然语言描述你的需求，如果你有小爱音箱的话
     get                 获取设备属性
     set                 设置设备属性
 
@@ -364,10 +367,6 @@ options:
                         运行场景，指定场景ID或名称
   --get_device_info DEVICE_MODEL
                         获取设备信息，指定设备model，先使用 --list_devices 获取
-  --run PROMPT          使用自然语言描述你的需求，如果你有小爱音箱的话
-  --wifispeaker_name WIFISPEAKER_NAME
-                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
-  --quiet               小爱音箱静默执行
 ```
 
 ```
@@ -397,6 +396,23 @@ options:
   --value VALUE         需要设定的属性值
 ```
 
+```
+usage: mijiaAPI run [-h] [-p AUTH_PATH]
+                       [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
+                       PROMPT
+
+positional arguments:
+  PROMPT                使用自然语言描述你的需求
+
+options:
+  -h, --help            show this help message and exit
+  -p, --auth_path AUTH_PATH
+                        认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json
+  --wifispeaker_name WIFISPEAKER_NAME
+                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
+  --quiet               小爱音箱静默执行
+```
+
 #### 获取设备属性
 
 ```bash
@@ -445,9 +461,9 @@ mijiaAPI --get_device_info yeelink.light.lamp4
 mijiaAPI --list_consumable_items
 
 # 使用小爱音箱执行自然语言命令
-mijiaAPI --run "打开卧室台灯"
-mijiaAPI --run "把亮度调到50%" --wifispeaker_name "卧室小爱"
-mijiaAPI --run "关闭所有灯" --quiet
+mijiaAPI run "打开卧室台灯"
+mijiaAPI run "把亮度调到50%" --wifispeaker_name "卧室小爱"
+mijiaAPI run "关闭所有灯" --quiet
 ```
 
 #### 直接使用 uvx（无需安装）

{mijiaapi-3.1.0 → mijiaapi-3.2.0}/mijiaAPI/__main__.py

@@ -69,16 +69,36 @@ def parse_args(args):
     parser.add_argument(
         '--run',
         type=str,
+        help=argparse.SUPPRESS,
+        nargs='?',
+        default=None,
+        metavar='PROMPT',
+    )
+
+    run = subparsers.add_parser(
+        'run',
         help="使用自然语言描述你的需求，如果你有小爱音箱的话",
+    )
+    run.set_defaults(func='run')
+    run.add_argument(
+        '-p', '--auth_path',
+        type=Path,
+        default=Path.home() / ".config" / "mijia-api" / "auth.json",
+        help="认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json",
+    )
+    run.add_argument(
+        'prompt',
+        type=str,
+        help="使用自然语言描述你的需求",
         metavar='PROMPT',
     )
-    parser.add_argument(
+    run.add_argument(
         '--wifispeaker_name',
         type=str,
         help="指定小爱音箱名称，默认是获取到的第一个小爱音箱",
         default=None,
     )
-    parser.add_argument(
+    run.add_argument(
         '--quiet',
         action='store_true',
         help="小爱音箱静默执行",
@@ -280,6 +300,11 @@ def set(args):
 def main(args):
     args = parse_args(args)
 
+    if args.run is not None:
+        print("错误: '--run' 参数已弃用，请使用 'run' 子命令代替。")
+        print(f"新用法: mijiaAPI run \"{args.run}\"")
+        sys.exit(1)
+
     if args.get_device_info:
         device_info = get_device_info(args.get_device_info)
         print(json.dumps(device_info, indent=2, ensure_ascii=False))
@@ -288,7 +313,6 @@ def main(args):
             args.list_scenes or
             args.list_consumable_items or
             args.run_scene or
-            args.run or
             hasattr(args, 'func') and args.func is not None):
         return
 
@@ -308,25 +332,25 @@ def main(args):
     if args.run_scene:
         for scene_id in args.run_scene:
             run_scene(api, scene_id, scene_mapping=scenes_mapping)
-    if args.run:
-        if device_mapping is None:
-            device_mapping = get_devices_list(api, verbose=False)
-        if args.wifispeaker_name is None:
-            wifispeaker = None
-            for device in device_mapping.values():
-                if 'xiaomi.wifispeaker' in device['model']:
-                    wifispeaker = mijiaDevice(api, dev_name=device['name'])
-                    break
-            if wifispeaker is None:
-                raise ValueError("未找到小爱音箱设备")
-        else:
-            wifispeaker = mijiaDevice(api, dev_name=args.wifispeaker_name)
-        wifispeaker.run_action('execute-text-directive', _in=[args.run, 1 if args.quiet else 0])
     if hasattr(args, 'func') and args.func is not None:
         if args.func == 'get':
             get(args)
         if args.func == 'set':
             set(args)
+        if args.func == 'run':
+            if device_mapping is None:
+                device_mapping = get_devices_list(api, verbose=False)
+            if args.wifispeaker_name is None:
+                wifispeaker = None
+                for device in device_mapping.values():
+                    if 'xiaomi.wifispeaker' in device['model']:
+                        wifispeaker = mijiaDevice(api, dev_name=device['name'])
+                        break
+                if wifispeaker is None:
+                    raise ValueError("未找到小爱音箱设备")
+            else:
+                wifispeaker = mijiaDevice(api, dev_name=args.wifispeaker_name)
+            wifispeaker.run_action('execute-text-directive', _in=[args.prompt, 1 if args.quiet else 0])
 
 def cli():
     main(sys.argv[1:])

mijiaapi-3.2.0/mijiaAPI/version.py

@@ -0,0 +1 @@
+version = "3.2.0"

{mijiaapi-3.1.0 → mijiaapi-3.2.0}/mijiaAPI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mijiaAPI
-Version: 3.1.0
+Version: 3.2.0
 Summary: A Python API for Xiaomi Mijia
 Author-email: Do1e <i@do1e.cn>
 License-Expression: GPL-3.0-or-later
@@ -359,14 +359,17 @@ MIJIA_LOG_LEVEL=WARNING mijiaAPI get --dev_name "卧室台灯" --prop_name "brig
 完整的命令行参数说明：
 
 ```
-usage: mijiaAPI [-h] [-p AUTH_PATH] [--list_homes] [-l] [--list_scenes] 
-                 [--list_consumable_items] [--run_scene SCENE_ID/SCENE_NAME ...] 
-                 [--get_device_info DEVICE_MODEL] [--run PROMPT] 
-                 [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
-                 {get,set} ...
+usage: mijiaAPI [-h] [-v] [-p AUTH_PATH] [--list_homes] [-l]
+                   [--list_scenes] [--list_consumable_items]
+                   [--run_scene SCENE_ID/SCENE_NAME [SCENE_ID/SCENE_NAME ...]]
+                   [--get_device_info DEVICE_MODEL]
+                   {run,get,set} ...
+
+Mijia API CLI (v3.1.0)
 
 positional arguments:
-  {get,set}
+  {run,get,set}
+    run                 使用自然语言描述你的需求，如果你有小爱音箱的话
     get                 获取设备属性
     set                 设置设备属性
 
@@ -384,10 +387,6 @@ options:
                         运行场景，指定场景ID或名称
   --get_device_info DEVICE_MODEL
                         获取设备信息，指定设备model，先使用 --list_devices 获取
-  --run PROMPT          使用自然语言描述你的需求，如果你有小爱音箱的话
-  --wifispeaker_name WIFISPEAKER_NAME
-                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
-  --quiet               小爱音箱静默执行
 ```
 
 ```
@@ -417,6 +416,23 @@ options:
   --value VALUE         需要设定的属性值
 ```
 
+```
+usage: mijiaAPI run [-h] [-p AUTH_PATH]
+                       [--wifispeaker_name WIFISPEAKER_NAME] [--quiet]
+                       PROMPT
+
+positional arguments:
+  PROMPT                使用自然语言描述你的需求
+
+options:
+  -h, --help            show this help message and exit
+  -p, --auth_path AUTH_PATH
+                        认证文件保存路径，默认保存在 ~/.config/mijia-api/auth.json
+  --wifispeaker_name WIFISPEAKER_NAME
+                        指定小爱音箱名称，默认是获取到的第一个小爱音箱
+  --quiet               小爱音箱静默执行
+```
+
 #### 获取设备属性
 
 ```bash
@@ -465,9 +481,9 @@ mijiaAPI --get_device_info yeelink.light.lamp4
 mijiaAPI --list_consumable_items
 
 # 使用小爱音箱执行自然语言命令
-mijiaAPI --run "打开卧室台灯"
-mijiaAPI --run "把亮度调到50%" --wifispeaker_name "卧室小爱"
-mijiaAPI --run "关闭所有灯" --quiet
+mijiaAPI run "打开卧室台灯"
+mijiaAPI run "把亮度调到50%" --wifispeaker_name "卧室小爱"
+mijiaAPI run "关闭所有灯" --quiet
 ```
 
 #### 直接使用 uvx（无需安装）

mijiaapi-3.1.0/mijiaAPI/version.py

@@ -1 +0,0 @@
-version = "3.1.0"