README.zh.md

# ecovacs-deebot-control

[English](README.md) | 中文

## 技能定位

本仓库为科沃斯 **地宝（Deebot）** 的 **Agent Skill**：面向对话场景整理「助手可以帮用户做到什么」——**查看已绑设备**、**了解电量与工况**、**发起或暂停清扫**、**回充相关操作**，以及在失败时**如何理解原因**；前提是已按规范使用开放平台 **AK**。

技能包用于界定 Agent **默认可覆盖的能力边界**，**不替代**厂商完整协议或附录。

---

## 前置条件

| 项目 | 要求 |
|------|------|
| **开放平台 AK** | 在 Ecovacs 开放平台「服务概览」创建或查看（**国内**：[open.ecovacs.cn](https://open.ecovacs.cn/)，**国际**：[open.ecovacs.com](https://open.ecovacs.com/)）。须与账号及设备所在**区域**一致。 |
| **设备指认** | 使用 **App 里展示名称中的一段话**，在多台设备时能**唯一**指向某一台地宝。 |

---

## 交互方式

用户说明**哪一台地宝**（用 App 里的叫法）以及**想做什么**（清扫、暂停、看电量、回充等）。日常使用**不必**了解内部指令名；开发与对接约定见 [SKILL.md](SKILL.md) 与 [references/api.md](references/api.md)。

### 说法示例

以下均为**用户侧**说法示例，可按 App 里的设备名称改写。

> 「我账号下有哪些**地宝**？」  
>
> 「昵称里带 **厨房** 那台，**电还够吗**？」  
>
> 「让 **客厅宝** **全屋扫一遍**。」 / 「**先暂停**客厅那台。」  
>
> 「让 **客厅宝** **回去充电**。」

---

## 能力范围

下列为技能设计所覆盖的**能力域**；是否可用仍取决于**机型、固件与设备是否在线**。下表为面向用户的**简要说明**，不逐项承诺每台设备均支持。

| 能力域 | 说明 |
|--------|------|
| **设备发现** | 查看账号下已绑定的地宝；与助手对话时请沿用 App 中的称呼习惯。 |
| **电量与工况** | 剩余电量及是否在清扫、回充、在基站等大致状态。 |
| **清扫** | 全屋清扫、在机型支持下的分区 / 房间清扫，以及暂停、继续、结束本轮任务。 |
| **回充** | 开始回充，或中止正在进行的回充过程（以产品支持为准）。 |
| **本次统计** | 如面积、时长等本轮或近期运行摘要（视机型是否提供）。 |
| **扩展能力（视机型）** | 吸力、水量、扫拖模式、基站维护（集尘 / 洗拖 / 烘干）、耗材、预约等，仅在对应硬件与策略开放时可用。 |

---

## 异常与排障

| 现象 | 可能原因 | 建议处理 |
|------|----------|----------|
| AK / token / 权限类错误 | AK 错误、过期或区域与账号不一致 | 在开放平台核对或轮换 AK；区域与账号对齐 |
| 找不到设备 | 口述名称与列表中的设备对不上，或列表里暂时没有该机 | 在 App 或助手段确认列表后，用与 App **一致**的叫法再试 |
| 离线 / 超时 | 主机关机、断网或链路不稳定 | 检查供电、局域网与 App 是否显示在线 |
| 低电、提示无法执行 | 当前电量不足以完成请求的操作 | 充电后再试 |

**升级排障**：保留助手或网关返回的**完整提示原文**，再查阅 [SKILL.md](SKILL.md) 与 [references/api.md](references/api.md)。

---

## 联系方式

[pei.zhou@ecovacs.com](mailto:pei.zhou@ecovacs.com)