roborock-cli 0.1.1__py3-none-any.whl

roborock_cli/cli.py

@@ -0,0 +1,715 @@
+"""
+CLI 命令实现
+
+15 个命令：
+  auth, devices, status, map, routines
+  start-clean, stop-clean, pause-clean, resume-clean
+  go-home, find-robot, dock-action, set-volume, set-dnd, execute-routine
+"""
+
+import asyncio
+import functools
+import json
+import sys
+from contextlib import asynccontextmanager
+from typing import Any
+
+from roborock_cli._vendor.roborock import RoborockCommand
+from roborock_cli._vendor.roborock.data import DnDTimer, DnDTimer as DnDTimerClass
+from roborock_cli._vendor.roborock.exceptions import RoborockException
+
+from .connection import (
+    AuthExpiredError,
+    AmbiguousDeviceError,
+    ConnectionManager,
+    DeviceNotFoundError,
+    NoDeviceError,
+)
+from .helpers import STATUS_FIELDS, field, safe_refresh, serialize_value
+
+
+# CLIError 类已在此文件中定义，供 __main__.py 导入
+__all__ = ["CLIError", "format_error", "add_cli_subparsers"]
+
+
+# ============================================================================
+# CLI 异常类（退出码绑定）
+# ============================================================================
+
+class CLIError(Exception):
+    """CLI 基础异常"""
+    def __init__(self, message: str, exit_code: int = 1):
+        self.message = message
+        self.exit_code = exit_code
+        super().__init__(message)
+
+
+class AuthError(CLIError):
+    """认证错误"""
+    def __init__(self, message: str = "认证已过期，请运行 roborock-cli auth"):
+        super().__init__(message, exit_code=2)
+
+
+class DeviceError(CLIError):
+    """设备错误"""
+    def __init__(self, message: str):
+        super().__init__(message, exit_code=3)
+
+
+class ParamError(CLIError):
+    """参数无效"""
+    def __init__(self, message: str):
+        super().__init__(message, exit_code=4)
+
+
+class InternalError(CLIError):
+    """内部错误"""
+    def __init__(self, message: str):
+        super().__init__(message, exit_code=5)
+
+
+# ============================================================================
+# 连接管理（含超时，Python 3.7+ 兼容）
+# ============================================================================
+
+@asynccontextmanager
+async def get_connection(timeout: float = 30.0):
+    """获取连接上下文管理器（带超时）"""
+    conn = ConnectionManager.from_env()
+    try:
+        await asyncio.wait_for(conn.ensure_connected(), timeout=timeout)
+    except asyncio.TimeoutError:
+        raise CLIError(f"连接超时（{timeout}秒）")
+    try:
+        yield conn
+    finally:
+        await conn.close()
+
+
+def run_async(coro):
+    """运行异步协程"""
+    import anyio
+
+    async def main():
+        return await coro
+
+    if sys.platform == "win32":
+        backend_options = {"loop_factory": asyncio.SelectorEventLoop}
+    else:
+        backend_options = {}
+
+    return anyio.run(main, backend_options=backend_options)
+
+
+# ============================================================================
+# 错误处理装饰器
+# ============================================================================
+
+def handle_cli_errors(func):
+    """CLI 错误处理装饰器，将底层异常转为 CLI 异常"""
+    @functools.wraps(func)
+    def wrapper(args):
+        try:
+            return func(args)
+        except AuthExpiredError:
+            raise AuthError()
+        except (NoDeviceError, AmbiguousDeviceError, DeviceNotFoundError) as e:
+            raise DeviceError(str(e))
+        except ValueError as e:
+            raise ParamError(str(e))
+        except RoborockException as e:
+            raise CLIError(f"设备通信失败: {type(e).__name__}: {e}")
+        except Exception as e:
+            raise InternalError(f"内部错误: {type(e).__name__}: {e}")
+    return wrapper
+
+
+# ============================================================================
+# 输出格式化（默认 JSON）
+# ============================================================================
+
+def format_output(data: Any) -> str:
+    """默认 JSON 输出"""
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def format_error(error: CLIError) -> str:
+    """错误也输出 JSON"""
+    return json.dumps({"error": error.message, "exit_code": error.exit_code})
+
+
+# ============================================================================
+# 辅助函数
+# ============================================================================
+
+def _parse_time(time_str: str) -> tuple[int, int]:
+    """解析 HH:MM 格式时间，返回 (hour, minute)"""
+    parts = time_str.split(":")
+    if len(parts) != 2:
+        raise ValueError(f"时间格式错误: {time_str}，期望 HH:MM")
+    hour, minute = int(parts[0]), int(parts[1])
+    if not (0 <= hour <= 23 and 0 <= minute <= 59):
+        raise ValueError(f"时间值无效: {time_str}")
+    return hour, minute
+
+
+# ============================================================================
+# 命令实现
+# ============================================================================
+
+# --- auth（交互式，无网络操作）---
+
+def cmd_auth(args):
+    """交互式认证（需要 TTY）"""
+    from .setup_auth import main as auth_main
+    auth_main()
+
+
+# --- devices ---
+
+@handle_cli_errors
+def cmd_devices(args):
+    """列出所有设备"""
+    async def _run():
+        async with get_connection() as conn:
+            devices = await conn.list_devices()
+            return {
+                "count": len(devices),
+                "devices": [
+                    {
+                        "name": d.name,
+                        "duid": d.duid,
+                        "model": d.product.model if d.product else None,
+                        "firmware": d.device_info.fv if d.device_info else None,
+                    }
+                    for d in devices
+                ]
+            }
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- status ---
+
+@handle_cli_errors
+def cmd_status(args):
+    """获取设备状态"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            props = device.v1_properties
+
+            # 并行刷新所有 trait
+            trait_names = [
+                "status", "dnd", "clean_summary", "sound_volume",
+                "rooms", "maps", "consumables", "device_features",
+            ]
+            refresh_results = await asyncio.gather(
+                *[safe_refresh(getattr(props, name), name) for name in trait_names]
+            )
+            ok = dict(zip(trait_names, refresh_results))
+
+            result: dict[str, Any] = {"device_name": device.name}
+
+            # --- status trait ---
+            if ok["status"]:
+                status = props.status
+
+                # 白名单字段
+                for fname, desc in STATUS_FIELDS.items():
+                    raw = getattr(status, fname, None)
+                    result[fname] = field(serialize_value(raw), desc)
+
+                # computed properties
+                result["state"] = field(status.state_name, "设备状态")
+                result["error_code"] = field(status.error_code_name, "错误状态")
+                result["clean_area_m2"] = field(status.square_meter_clean_area, "清洁面积 (m²)")
+                result["clean_time_minutes"] = field(
+                    round(status.clean_time / 60, 1) if status.clean_time else 0,
+                    "清洁时长 (分钟)",
+                )
+                result["fan_speed_name"] = field(status.fan_speed_name, "吸力档位")
+                result["water_mode_name"] = field(status.water_mode_name, "拖布湿度")
+                result["mop_route_name"] = field(status.mop_route_name, "拖地路线")
+
+                # dss 拆解
+                result["clear_water_box_status"] = field(
+                    serialize_value(status.clear_water_box_status), "清水箱状态")
+                result["dirty_water_box_status"] = field(
+                    serialize_value(status.dirty_water_box_status), "污水箱状态")
+                result["dust_bag_status"] = field(
+                    serialize_value(status.dust_bag_status), "尘袋状态")
+
+            # --- dnd ---
+            if ok["dnd"]:
+                dnd = props.dnd
+                result["dnd_enabled"] = field(dnd.is_on, "勿扰模式")
+                result["dnd_start_time"] = field(
+                    f"{dnd.start_hour:02d}:{dnd.start_minute:02d}" if dnd.is_on else None,
+                    "勿扰开始时间",
+                )
+                result["dnd_end_time"] = field(
+                    f"{dnd.end_hour:02d}:{dnd.end_minute:02d}" if dnd.is_on else None,
+                    "勿扰结束时间",
+                )
+
+            # --- clean_summary ---
+            if ok["clean_summary"]:
+                summary = props.clean_summary
+                result["total_clean_time_hours"] = field(
+                    round(summary.clean_time / 3600, 1) if summary.clean_time else 0,
+                    "累计清洁时长 (小时)",
+                )
+                result["total_clean_area_m2"] = field(
+                    round(summary.clean_area / 1_000_000, 1) if summary.clean_area else 0,
+                    "累计清洁面积 (m²)",
+                )
+                result["total_clean_count"] = field(summary.clean_count, "累计清洁次数")
+
+                if summary.last_clean_record:
+                    record = summary.last_clean_record
+                    result["last_clean_begin"] = field(
+                        record.begin_datetime.isoformat() if record.begin_datetime else None,
+                        "最近清洁开始时间",
+                    )
+                    result["last_clean_end"] = field(
+                        record.end_datetime.isoformat() if record.end_datetime else None,
+                        "最近清洁结束时间",
+                    )
+
+            # --- sound_volume ---
+            if ok["sound_volume"]:
+                result["volume"] = field(props.sound_volume.volume, "音量")
+
+            # --- rooms ---
+            if ok["rooms"]:
+                rooms = props.rooms
+                room_list = [
+                    {
+                        "segment_id": room.segment_id,
+                        "iot_id": room.iot_id,
+                        "name": room.raw_name or "<未命名>",
+                    }
+                    for room in rooms.rooms or []
+                ]
+                result["room_count"] = field(len(room_list), "房间数量")
+                result["rooms"] = field(room_list, "房间列表")
+
+            # --- maps ---
+            if ok["maps"]:
+                maps = props.maps
+                map_list = [
+                    {
+                        "map_flag": m.map_flag,
+                        "name": m.name or "<未命名>",
+                        "is_current": m.map_flag == maps.current_map,
+                    }
+                    for m in maps.map_info or []
+                ]
+                result["current_map_flag"] = field(maps.current_map, "当前地图 ID")
+                result["maps"] = field(map_list, "地图列表")
+
+            # --- consumables ---
+            if ok["consumables"]:
+                consumables = props.consumables
+                SECS_PER_HOUR = 3600
+                result["main_brush_hours"] = field(
+                    round(consumables.main_brush_work_time / SECS_PER_HOUR, 1)
+                    if consumables.main_brush_work_time else 0,
+                    "主刷使用时长 (小时)",
+                )
+                result["side_brush_hours"] = field(
+                    round(consumables.side_brush_work_time / SECS_PER_HOUR, 1)
+                    if consumables.side_brush_work_time else 0,
+                    "边刷使用时长 (小时)",
+                )
+                result["filter_hours"] = field(
+                    round(consumables.filter_work_time / SECS_PER_HOUR, 1)
+                    if consumables.filter_work_time else 0,
+                    "滤网使用时长 (小时)",
+                )
+
+            return result
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- map ---
+
+@handle_cli_errors
+def cmd_map(args):
+    """获取地图"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            props = device.v1_properties
+            await props.map_content.refresh()
+            content = props.map_content
+
+            metadata = {
+                "device_name": device.name,
+                "image_size_bytes": len(content.image_content) if content.image_content else 0,
+                "has_map_data": content.map_data is not None,
+            }
+
+            if content.map_data:
+                vacuum_pos = content.map_data.vacuum_position
+                charger_pos = content.map_data.charger
+                metadata["vacuum_position"] = {
+                    "x": vacuum_pos.x if vacuum_pos else None,
+                    "y": vacuum_pos.y if vacuum_pos else None,
+                }
+                metadata["charger_position"] = {
+                    "x": charger_pos.x if charger_pos else None,
+                    "y": charger_pos.y if charger_pos else None,
+                }
+
+            return metadata, content.image_content
+
+    metadata, image_data = run_async(_run())
+
+    if args.save:
+        if not image_data:
+            raise CLIError("无地图图片数据")
+        with open(args.save, "wb") as f:
+            f.write(image_data)
+        print(format_output({"saved": args.save, "metadata": metadata}))
+    else:
+        print(format_output(metadata))
+
+
+# --- routines ---
+
+@handle_cli_errors
+def cmd_routines(args):
+    """列出智能场景"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            routines = await device.v1_properties.routines.get_routines()
+            return {
+                "device_name": device.name,
+                "count": len(routines),
+                "routines": [{"id": r.id, "name": r.name} for r in routines],
+            }
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- start-clean ---
+
+@handle_cli_errors
+def cmd_start_clean(args):
+    """开始清洁"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            cmd = device.v1_properties.command
+            if args.segments:
+                params = [{"segments": args.segments, "repeat": args.repeat}]
+                await cmd.send(RoborockCommand.APP_SEGMENT_CLEAN, params=params)
+                return {"status": "ok", "action": "segment_clean", "segments": args.segments, "repeat": args.repeat}
+            else:
+                await cmd.send(RoborockCommand.APP_START)
+                return {"status": "ok", "action": "full_clean"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- stop-clean ---
+
+@handle_cli_errors
+def cmd_stop_clean(args):
+    """停止清洁"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(RoborockCommand.APP_STOP)
+            return {"status": "ok", "action": "stop"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- pause-clean ---
+
+@handle_cli_errors
+def cmd_pause_clean(args):
+    """暂停清洁"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(RoborockCommand.APP_PAUSE)
+            return {"status": "ok", "action": "pause"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- resume-clean ---
+
+@handle_cli_errors
+def cmd_resume_clean(args):
+    """恢复清洁"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(RoborockCommand.APP_START)
+            return {"status": "ok", "action": "resume"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- go-home ---
+
+@handle_cli_errors
+def cmd_go_home(args):
+    """回充电座"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(RoborockCommand.APP_CHARGE)
+            return {"status": "ok", "action": "go_home"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- find-robot ---
+
+@handle_cli_errors
+def cmd_find_robot(args):
+    """寻找机器人"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(RoborockCommand.FIND_ME)
+            return {"status": "ok", "action": "find_robot"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- dock-action ---
+
+@handle_cli_errors
+def cmd_dock_action(args):
+    """基座操作"""
+    ACTION_MAP = {
+        "start_collect_dust": RoborockCommand.APP_START_COLLECT_DUST,
+        "stop_collect_dust": RoborockCommand.APP_STOP_COLLECT_DUST,
+        "start_wash": RoborockCommand.APP_START_WASH,
+        "stop_wash": RoborockCommand.APP_STOP_WASH,
+    }
+
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.command.send(ACTION_MAP[args.action])
+            return {"status": "ok", "action": args.action}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- set-volume ---
+
+@handle_cli_errors
+def cmd_set_volume(args):
+    """设置音量"""
+    if not 0 <= args.volume <= 100:
+        raise ParamError("音量值需在 0-100 之间")
+
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.sound_volume.set_volume(args.volume)
+            return {"status": "ok", "volume": args.volume}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- set-dnd ---
+
+@handle_cli_errors
+def cmd_set_dnd(args):
+    """设置勿扰模式"""
+    if args.action == "enable":
+        if not args.start or not args.end:
+            raise ParamError("enable 操作需要 --start 和 --end 参数")
+        try:
+            start_hour, start_minute = _parse_time(args.start)
+            end_hour, end_minute = _parse_time(args.end)
+        except ValueError as e:
+            raise ParamError(str(e))
+    else:
+        start_hour = start_minute = end_hour = end_minute = 0
+
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            dnd = device.v1_properties.dnd
+            if args.action == "enable":
+                timer = DnDTimer(start_hour, start_minute, end_hour, end_minute)
+                await dnd.set_dnd_timer(timer)
+                return {
+                    "status": "ok",
+                    "action": "enable",
+                    "time": f"{start_hour:02d}:{start_minute:02d}-{end_hour:02d}:{end_minute:02d}",
+                }
+            else:
+                await dnd.disable()
+                return {"status": "ok", "action": "disable"}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# --- execute-routine ---
+
+@handle_cli_errors
+def cmd_execute_routine(args):
+    """执行智能场景"""
+    async def _run():
+        async with get_connection() as conn:
+            device = await conn.get_device(args.device)
+            if not device.v1_properties:
+                raise DeviceError("设备不支持 V1 协议")
+
+            await device.v1_properties.routines.execute_routine(args.routine_id)
+            return {"status": "ok", "routine_id": args.routine_id}
+
+    result = run_async(_run())
+    print(format_output(result))
+
+
+# ============================================================================
+# argparse 集成
+# ============================================================================
+
+def add_cli_subparsers(subparsers):
+    """注册 CLI 子命令"""
+
+    # auth（交互式）
+    p = subparsers.add_parser("auth", help="交互式认证（需要 TTY）")
+    p.set_defaults(func=cmd_auth)
+
+    # devices
+    p = subparsers.add_parser("devices", help="列出所有设备")
+    p.set_defaults(func=cmd_devices)
+
+    # status
+    p = subparsers.add_parser("status", help="获取设备状态")
+    p.add_argument("-d", "--device", help="设备名称（模糊匹配）")
+    p.set_defaults(func=cmd_status)
+
+    # map
+    p = subparsers.add_parser("map", help="获取地图")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.add_argument("--save", help="保存地图到文件")
+    p.set_defaults(func=cmd_map)
+
+    # routines
+    p = subparsers.add_parser("routines", help="列出智能场景")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_routines)
+
+    # start-clean
+    p = subparsers.add_parser("start-clean", help="开始清洁")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.add_argument("-s", "--segments", type=int, nargs="+", help="房间 ID 列表")
+    p.add_argument("-r", "--repeat", type=int, default=1, help="清洁遍数")
+    p.set_defaults(func=cmd_start_clean)
+
+    # stop-clean
+    p = subparsers.add_parser("stop-clean", help="停止清洁")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_stop_clean)
+
+    # pause-clean
+    p = subparsers.add_parser("pause-clean", help="暂停清洁")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_pause_clean)
+
+    # resume-clean
+    p = subparsers.add_parser("resume-clean", help="恢复清洁")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_resume_clean)
+
+    # go-home
+    p = subparsers.add_parser("go-home", help="回充电座")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_go_home)
+
+    # find-robot
+    p = subparsers.add_parser("find-robot", help="寻找机器人")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_find_robot)
+
+    # dock-action
+    p = subparsers.add_parser("dock-action", help="基座操作")
+    p.add_argument("action", choices=["start_collect_dust", "stop_collect_dust", "start_wash", "stop_wash"],
+                   help="操作类型")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_dock_action)
+
+    # set-volume
+    p = subparsers.add_parser("set-volume", help="设置音量")
+    p.add_argument("volume", type=int, help="音量值 (0-100)")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_set_volume)
+
+    # set-dnd
+    p = subparsers.add_parser("set-dnd", help="设置勿扰模式")
+    p.add_argument("action", choices=["enable", "disable"], help="操作类型")
+    p.add_argument("--start", help="开始时间（HH:MM，enable 时必需）")
+    p.add_argument("--end", help="结束时间（HH:MM，enable 时必需）")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_set_dnd)
+
+    # execute-routine
+    p = subparsers.add_parser("execute-routine", help="执行智能场景")
+    p.add_argument("routine_id", type=int, help="场景 ID")
+    p.add_argument("-d", "--device", help="设备名称")
+    p.set_defaults(func=cmd_execute_routine)