Roborock Vacuum Control

核心用法

roborock CLI 提供完整的扫地机器人控制能力，需通过 pipx install python-roborock 安装。首次使用需执行 roborock login 登录账号并获取设备 ID。所有命令需指定 --device_id 参数。

主要功能模块

基础控制：start/stop/pause/home 控制启停与回充；status 实时查看状态。

智能清洁：支持房间分区清洁（segment_clean --rooms），需先通过 roborock rooms 获取房间 ID；可保存地图图片（map-image）。

维护管理：consumables 查看滤网、主刷、边刷寿命；reset-consumable 重置耗材计数器；clean-record/clean-summary 查看清洁历史。

设置调节：音量控制、勿扰模式、LED 状态、童锁等功能。

交互模式：roborock session 支持多命令会话，避免重复输入设备 ID。

显著优点

• 功能全面：覆盖日常控制、维护、地图管理的完整需求
• 开源生态：基于活跃的 python-roborock 库，社区维护
• 跨平台：Python CLI，支持 macOS/Linux/Windows
• 设备兼容广：支持 S/Q/E 系列及小米代工机型
• 自动化友好：CLI 接口便于脚本集成与 Home Assistant 等场景联动

潜在缺点与局限性

• 依赖云端：需登录 Roborock 账号，非纯本地控制
• 无官方背书：非 Roborock 官方工具，API 可能随厂商更新而变动
• 首次配置繁琐：需手动获取设备 ID，无自动发现机制
• 命令冗长：需重复输入 --device_id，虽可用 session 缓解
• 调试困难：部分错误静默失败，需 -d 调试模式排查

适合人群

• 技术用户、Home Assistant 玩家、智能家居自动化爱好者
• 需要批量管理多台设备的用户
• 希望脱离手机 App 进行快捷控制的用户

常规风险

• 账号安全：凭证存储于本地，需确保 .config 目录权限
• 网络依赖：设备与 CLI 均需联网，断网无法使用
• 操作误触：home 等命令会立即执行，确认当前清洁状态再操作
• API 稳定性：第三方逆向实现，存在因官方协议变更导致功能失效的风险

核心用法

Roborock 技能是一个纯文档型智能家居控制工具，通过封装 python-roborock CLI 的命令行接口，让 AI Agent 能够理解和执行与扫地机器人相关的自然语言指令。用户首次使用需通过 pipx 安装 CLI 工具并完成账号登录绑定，之后即可通过设备 ID 执行各类操作。

核心功能覆盖六大场景：状态监控（实时查看设备运行状态、电池电量、清洁进度）、清洁控制（全屋/指定房间清洁、暂停/停止/回充）、地图管理（获取家居地图、保存地图图片、识别房间分区）、耗材维护（滤网、主刷、边刷寿命监测与重置）、历史记录（单次清洁详情与累计清洁统计）、设备设置（音量调节、勿扰模式、LED 状态、童锁开关）。特别支持交互式会话模式，可在多命令连续操作时省去重复输入设备 ID 的繁琐。

显著优点

指令自然化：将 "打扫一下厨房"、"吸尘器回去了吗" 等口语化表达精准映射为对应的 CLI 命令，大幅降低智能家居的技术使用门槛。功能覆盖全面：从基础启停到高级的房间级分区清洁、耗材全生命周期管理，基本覆盖 Roborock App 的核心功能。生态兼容性强：支持 S/Q/E 全系列及小米联名机型，设备覆盖范围广。架构安全简洁：纯 Markdown 文档设计，无可执行代码，所有敏感操作均委托给经过社区验证的开源 CLI 工具，责任边界清晰。

潜在缺点与局限性

外部依赖刚性：必须预先安装 python-roborock CLI，且该工具并非 Roborock 官方出品，存在 API 变更导致功能失效的风险。网络环境敏感：设备控制依赖云端 API 通信，断网或 Roborock 服务器维护时功能不可用。首次配置门槛：需要用户自行处理 pipx 安装、账号登录、设备 ID 查询等步骤，对非技术用户不够友好。功能无扩展性：仅支持 Roborock 品牌设备，无法跨品牌控制其他扫地机器人。地图隐私暴露：生成的家居地图图片包含房间布局信息，需用户自行妥善管理。

适合的目标群体

智能家居爱好者：已拥有 Roborock 设备且希望将扫地机控制整合进 AI Agent 工作流的用户。技术型家庭管理员：熟悉命令行操作、愿意配置 CLI 环境以换取更灵活自动化能力的进阶用户。无障碍需求群体：通过语音或自然语言与 AI 交互，比操作手机 App 更为便捷的老年用户或行动不便者。多设备管理场景：需要同时查看多台设备状态、统一维护耗材更换周期的家庭或小型办公场所。

使用风险

性能风险：CLI 命令执行涉及网络 API 调用，响应延迟通常在 1-3 秒，不适合对实时性要求极高的场景；地图图片生成可能消耗较多内存。依赖维护风险：python-roborock 为社区维护项目，若原仓库停止更新或 Roborock 变更私有协议，功能可能突然失效。凭证安全风险：登录命令需要输入 Roborock/小米账号密码，存在终端历史记录残留或剪贴板泄露风险，建议在私人可信设备操作。隐私泄露风险：设备 ID 和地图数据具有唯一识别性，分享截图或日志时可能暴露家庭布局信息。兼容性风险：部分新机型或固件版本可能存在功能支持不完整的情况，分区清洁等功能依赖地图建图质量。