Metadata-Version: 2.4
Name: roborock-cli
Version: 0.1.2
Summary: Roborock 扫地机 CLI 控制工具
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiohttp<4,>=3.8.2
Requires-Dist: aiomqtt<3,>=2.5.0
Requires-Dist: certifi
Requires-Dist: click-shell~=2.1
Requires-Dist: click>=8
Requires-Dist: construct<3,>=2.10.57
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: paho-mqtt<3.0.0,>=1.6.1
Requires-Dist: pycryptodomex~=3.18; sys_platform == 'darwin'
Requires-Dist: pycryptodome~=3.18
Requires-Dist: pyrate-limiter<5,>=4.0.0
Requires-Dist: vacuum-map-parser-roborock
Description-Content-Type: text/markdown

# roborock-cli

Roborock 扫地机 CLI 控制工具，也可作为 MCP 服务器使用。

## 功能

提供 15 个 CLI 命令，支持多设备（通过设备名称模糊匹配选择目标设备）。

### 查询命令（5 个）

| 命令 | 说明 |
|------|------|
| `roborock-cli devices` | 列出所有设备（名称、型号、DUID、固件版本） |
| `roborock-cli status` | 设备精简状态（电量、清洁进度、耗材、房间列表等） |
| `roborock-cli map` | 获取地图元数据和图片 |
| `roborock-cli routines` | 列出智能场景 |
| `roborock-cli auth` | 交互式认证（需要 TTY） |

### 控制命令（10 个）

| 命令 | 说明 |
|------|------|
| `roborock-cli start-clean` | 开始清洁（全屋或指定房间） |
| `roborock-cli stop-clean` | 停止清洁 |
| `roborock-cli pause-clean` | 暂停清洁 |
| `roborock-cli resume-clean` | 恢复清洁 |
| `roborock-cli go-home` | 回充电座 |
| `roborock-cli find-robot` | 寻找机器人（发出声音） |
| `roborock-cli dock-action` | 基座操作（集尘/洗拖布） |
| `roborock-cli set-volume` | 设置音量（0-100） |
| `roborock-cli set-dnd` | 设置勿扰模式 |
| `roborock-cli execute-routine` | 执行智能场景 |

## 安装使用

### 前置：安装 uv

本项目通过 `uvx` 运行，需要先安装 [uv](https://docs.astral.sh/uv/)：

**macOS / Linux**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

安装后终端输入 `uvx --version` 验证。

### 通过 uvx（推荐）

**1. 首次认证**

```bash
uvx roborock-cli auth
```

按提示输入 Roborock 账户邮箱和验证码，认证信息保存在 `~/.cache/roborock-cli/`。

**2. 使用 CLI**

```bash
# 列出设备
roborock-cli devices

# 查看状态
roborock-cli status

# 开始全屋清洁
roborock-cli start-clean

# 开始房间清洁（房间 ID 通过 status 命令获取）
roborock-cli start-clean -s 1 2 3

# 回充电座
roborock-cli go-home
```

### 作为 MCP 服务器使用

roborock-cli 也可以作为 MCP 服务器运行，供 Claude Desktop/Code 等客户端使用：

```bash
roborock-cli mcp
```

**配置 Claude Code**

在项目目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "roborock": {
      "command": "uvx",
      "args": ["roborock-cli@latest", "mcp"]
    }
  }
}
```

### 开发模式

```bash
# 需要先 clone python-roborock 到 ./python-roborock/
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

roborock-cli --help          # CLI 帮助
roborock-cli auth            # 认证
roborock-cli mcp             # 启动 MCP server
```

## 输出格式

CLI 命令默认输出 JSON 格式，便于程序解析：

```json
{
  "count": 2,
  "devices": [
    {"name": "客厅扫地机", "duid": "abc123", "model": "roborock.vacuum.a75", "firmware": "02.00.01"},
    {"name": "卧室扫地机", "duid": "def456", "model": "roborock.vacuum.s8", "firmware": "02.00.02"}
  ]
}
```

## 错误退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 通用业务错误 |
| 2 | 认证错误（需重新运行 `roborock-cli auth`） |
| 3 | 设备错误 |
| 4 | 参数无效 |
| 5 | 内部错误 |

## 要求

- Python >= 3.12
- Roborock 账户（国际版，邮箱注册）

## 许可证

GPL-3.0-only（由于 vendoring 了 [python-roborock](https://github.com/humbertogontijo/python-roborock)）
