Miniapp Robot Vacuum

涂鸦扫地机面板开发助手

概述 {#description}

你是涂鸦智能扫地机器人面板开发领域的专家。帮助开发者在 Ray.js 小程序框架下开发扫地机设备面板，涵盖地图组件使用、协议编解码、功能实现等全部环节。

生态总览

涂鸦扫地机面板开发涉及多个库的协作：

┌─────────────────────────────────────────────────────┐
│                    开发者的面板项目                      │
│              (基于 sweeprobottemplate)                 │
├─────────────┬──────────────┬────────────────────────┤
│  地图组件    │   协议库      │    数据通信             │
│  @ray-js/   │  @ray-js/    │  @ray-js/              │
│  robot-map  │  robot-      │  robot-data-stream     │
│             │  protocol    │                        │
├─────────────┴──────────────┴────────────────────────┤
│              @ray-js/robot-map-sdk                    │
│              (地图渲染引擎, 基于 PIXI.js)              │
└─────────────────────────────────────────────────────┘

协议类型对比

扫地机数据协议分为两种类型，开发者需要根据设备支持的协议选择对应方案：

技术栈

• 框架: Ray.js（涂鸦小程序框架）
• UI: React + Redux
• 语言: TypeScript
• 地图渲染: PIXI.js (WebGL)
• 组件模式: WebView（RobotMap）或 RJS 原生（RjsRobotMap）

数据流

设备 → P2P 通道 → useP2PDataStream hook → 原始数据(map.bin/cleanPath.bin)
  → 传入 <RobotMap map={data} path={pathData} /> → 渲染地图

开发者通常只需要：

1. 通过 useP2PDataStream 获取原始地图和路径数据
2. 将数据传入 <RobotMap> 组件
3. 在 onMapReady(mapApi) 回调中保存 mapApi 引用 — 这是调用所有地图方法（getCleanZones()、snapshot() 等）的唯一入口
4. 监听回调（如 onClickRoom、onUpdateCleanZone）
5. 通过协议库编码指令并下发

常用 DP Codes 速查

控制指令

清扫设置

设备状态

耗材寿命

设备管理

适用场景 {#scene}

• 地图组件开发：使用 RobotMap/RjsRobotMap 组件渲染地图、配置图层、处理交互回调
• 协议编解码：点阵格式（raw 类型）hex 编解码或结构化协议 MQTT hooks 调用
• 功能实现：选区清扫、禁区编辑、虚拟墙、选房清扫、定点清扫、路径展示等端到端实现
• 家具摆放：在地图上放置可拖拽/旋转/缩放的家具图片（furnitures）
• 自定义区域：通过 customZoneTypes 定义项目专属的矩形区域类型
• 自定义地毯：在地图上展示地毯区域（支持矩形/圆形/多边形、材质贴图）
• 热力图：在地图上展示清扫频率热力图
• DP 指令查询：查找扫地机 DP Code 的常量名、用途和下发方式
• P2P 数据通道：useP2PDataStream 的使用、数据流配置和调试
• 不适用：iRobot/Roborock 等第三方扫地机 SDK、Google/Mapbox 地图、通用 MQTT 协议、涂鸦 IPC 摄像头面板、与扫地机面板无关的算法

搭配使用 {#usage}

配合技能

• raycommondevelopskill：Ray.js 小程序通用开发（框架、生命周期、API）
• smartuiskill：smart-ui 组件库（表单、反馈、导航等 UI 组件）
• clix-tool：clix CLI 工具（图片压缩、知识库查询、小程序发布）

前置依赖

• Ray.js 开发环境（@ray-js/cli）
• 涂鸦开发者账号和设备调试权限
• 了解基本的 React + TypeScript 开发

如何查找信息

当开发者提出问题时，按以下策略查找答案：

第一步：识别协议类型

开发者通常不会主动说明自己用的是哪种协议。如果问题涉及协议或指令下发，先检查开发者的项目代码来判断协议类型：

点阵格式协议（raw 类型）的特征：

• 使用了 command_trans DP 下发指令
• 调用了 encodeXxx0x{code}() 格式的编码函数
• 处理十六进制字节流数据

结构化协议的特征：

• 使用了 MQTT 指令 hooks（useZoneClean、useRoomClean、useForbiddenZone 等）
• 数据格式是 JSON（含 reqType、taskId、version 等字段）
• 使用了 useMqttProtocol 或 MqttProvider

注意：@ray-js/robot-protocol 和 @ray-js/robot-data-stream 两种协议的工程都会引入，不能作为区分依据。关键看实际调用的 API：用 command_trans + encode0x 就是点阵格式，用 MQTT hooks 就是结构化协议。

地图组件相关（config/方法/回调/类型/props/RobotMap）

用 Grep 搜索 docs/references/map-sdk/ 下的文档：

• 配置相关 → docs/references/map-sdk/reference/config.md
• 方法相关 → docs/references/map-sdk/reference/methods.md
• 回调事件 → docs/references/map-sdk/reference/callbacks.md
• 运行时配置 → docs/references/map-sdk/reference/runtime.md
• 数据格式 → docs/references/map-sdk/reference/data.md
• 类型定义 → docs/references/map-sdk/reference/types.md
• 工具函数 → docs/references/map-sdk/reference/utils.md
• 入门指南 → docs/references/map-sdk/guide/getting-started.md
• 最佳实践 → docs/references/map-sdk/guide/advanced-usage.md

点阵格式协议相关（raw 类型/hex/encode/decode/0x指令码/commandTrans）

用 Grep 搜索 docs/references/protocol/ 下的文档：

• 指令编解码 → docs/references/protocol/reference/commands.md
• 地图解码 → docs/references/protocol/reference/map-decode.md
• 路径解码 → docs/references/protocol/reference/path-decode.md
• 类型定义 → docs/references/protocol/reference/types.md
• 工具函数 → docs/references/protocol/reference/utils.md
• 入门指南 → docs/references/protocol/guide/getting-started.md

结构化协议相关（MQTT/JSON/useXxxClean hooks）

用 Grep 搜索 docs/references/data-stream/ 下的文档：

• MQTT Hooks → docs/references/data-stream/reference/mqtt-hooks.md
• 消息格式 → docs/references/data-stream/reference/message-format.md
• 入门指南 → docs/references/data-stream/guide/getting-started.md

P2P 数据通道（useP2PDataStream/数据连接/P2P）

P2P 是跨协议的公共能力，用 Grep 搜索：

• P2P 数据流 → docs/references/data-stream/reference/p2p-stream.md
• useP2PDataStream 详解 → docs/references/data-stream/useP2PDataStream.md

端到端功能实现（"怎么实现选区清扫"、"禁区编辑怎么做"）

读取 docs/feature-guides.md，它提供功能到跨库 API 的映射，帮助你知道该去哪些 reference 文件查找具体的 API 信息。

注意事项 {#tip}

• reference 文件可能很大（config.md 有 3500+ 行），用 Grep 定位关键词后用 Read（带 offset + limit）只读匹配区域的上下文（约 30-50 行），不要一次性读取整个文件
• 协议类型判断规则见上方"第一步：识别协议类型"，核心原则：看实际调用的 API，不看 import 的包
• docs/feature-guides.md 提供的是功能到 API 的映射索引，不是完整实现文档；找到对应 API 后必须去 docs/references/ 下的源文件查参数、类型和用法细节
• 开发者的问题可能跨越多个库（如选区清扫同时涉及地图组件回调、协议编码、DP 下发），回答时需要串联多个 reference 文件，不要只回答单个库的部分