@ray-js/robot-data-stream 0.0.16 → 0.0.17-beta.10

package/lib/mqtt/cruise.d.ts

@@ -0,0 +1,2 @@
+import type { SetCruiseData } from './type/protocols/cruiseProtocol';
+export declare const createCruisePayload: (message: SetCruiseData) => SetCruiseData;

package/lib/mqtt/cruise.js

@@ -0,0 +1,9 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+export const createCruisePayload = message => {
+  if (message.polygons && message.num === undefined) {
+    return _objectSpread(_objectSpread({}, message), {}, {
+      num: message.polygons.length
+    });
+  }
+  return message;
+};

package/lib/mqtt/hooks/useStructuredMessage.d.ts

@@ -1,3 +1,4 @@
+import { MqttError } from '../promise';
 import { BaseResponse } from '../type/protocols/base';
 /**
  * 统一的 MQTT 消息发送 Hook
@@ -9,4 +10,4 @@ export declare const useStructuredMessage: () => {
 /**
  * 错误处理工具函数
  */
-export declare const handleMqttError: (error: unknown, defaultMessage: string) => Error;
+export declare const handleMqttError: (error: unknown, defaultMessage: string) => MqttError;

package/lib/mqtt/hooks/useStructuredMessage.js

@@ -5,7 +5,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { getBitValue, logger } from '../../utils';
 import { createSetCommonParams } from '../createCommonOptions';
 import { useMqtt } from '../mqttProvider';
-import { normalResolve } from '../promise';
+import { MqttError, normalResolve } from '../promise';
 // 常量定义
 const COMMUNICATION_CHANNELS = {
   MQTT: 'mqtt',
@@ -196,11 +196,18 @@ export const useStructuredMessage = () => {
  * 错误处理工具函数
  */
 export const handleMqttError = (error, defaultMessage) => {
-  if (error instanceof Error) {
+  var _errCode, _reqType;
+  // 已是本库错误则直接透传
+  if (error instanceof MqttError) {
     return error;
   }
-  if (typeof error === 'string') {
-    return new Error(error);
-  }
-  return new Error(defaultMessage);
+
+  // 统一包装为 MqttError，打上标记，便于全局 unhandledrejection 兜底时识别为本库错误
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : defaultMessage;
+  const errCode = (_errCode = error === null || error === void 0 ? void 0 : error.errCode) !== null && _errCode !== void 0 ? _errCode : -1;
+  const reqType = (_reqType = error === null || error === void 0 ? void 0 : error.reqType) !== null && _reqType !== void 0 ? _reqType : '';
+  return new MqttError(message, {
+    errCode,
+    reqType
+  });
 };

package/lib/mqtt/index.d.ts

@@ -19,4 +19,9 @@ import { useCarpet } from './useCarpet';
 import { useCarpetClean } from './useCarpetClean';
 import { useDeviceModel } from './useDeviceModel';
 import { useFurnitureModel } from './useFurnitureModel';
-export { useCarpet, useCarpetClean, useVoice, MqttProvider, useDeviceModel, useFurnitureModel, useDevInfo, usePartMerge, usePartDivision, usePassword, useWifiMap, useQuiteHours, useVirtualArea, useSpotClean, useZoneClean, useSelectRoomClean, useVirtualWall, useSchedule, useHistoryMap, useRoomProperty, useResetMap, };
+import { usePurifierSchedule } from './usePurifierSchedule';
+import { useCruise } from './useCruise';
+import { useSpotPolygons } from './useSpotPolygons';
+import { useMcsRoomInfo } from './useMcsRoomInfo';
+import { useThreshold } from './useThreshold';
+export { useCarpet, useCarpetClean, useVoice, MqttProvider, useDeviceModel, useFurnitureModel, useDevInfo, usePartMerge, usePartDivision, usePassword, useWifiMap, useQuiteHours, useVirtualArea, useSpotClean, useZoneClean, useSelectRoomClean, useVirtualWall, useSchedule, useHistoryMap, useRoomProperty, useResetMap, usePurifierSchedule, useCruise, useSpotPolygons, useMcsRoomInfo, useThreshold, };

package/lib/mqtt/index.js

@@ -19,4 +19,9 @@ import { useCarpet } from './useCarpet';
 import { useCarpetClean } from './useCarpetClean';
 import { useDeviceModel } from './useDeviceModel';
 import { useFurnitureModel } from './useFurnitureModel';
-export { useCarpet, useCarpetClean, useVoice, MqttProvider, useDeviceModel, useFurnitureModel, useDevInfo, usePartMerge, usePartDivision, usePassword, useWifiMap, useQuiteHours, useVirtualArea, useSpotClean, useZoneClean, useSelectRoomClean, useVirtualWall, useSchedule, useHistoryMap, useRoomProperty, useResetMap };
+import { usePurifierSchedule } from './usePurifierSchedule';
+import { useCruise } from './useCruise';
+import { useSpotPolygons } from './useSpotPolygons';
+import { useMcsRoomInfo } from './useMcsRoomInfo';
+import { useThreshold } from './useThreshold';
+export { useCarpet, useCarpetClean, useVoice, MqttProvider, useDeviceModel, useFurnitureModel, useDevInfo, usePartMerge, usePartDivision, usePassword, useWifiMap, useQuiteHours, useVirtualArea, useSpotClean, useZoneClean, useSelectRoomClean, useVirtualWall, useSchedule, useHistoryMap, useRoomProperty, useResetMap, usePurifierSchedule, useCruise, useSpotPolygons, useMcsRoomInfo, useThreshold };

package/lib/mqtt/mqttProvider.js

@@ -3,7 +3,7 @@ import { registerMQTTProtocolListener } from '@ray-js/ray';
 import { get, isFunction, isNil } from 'lodash-es';
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from 'react';
 import { emitter } from '../utils';
-import { setUnhandledRejectionHandler } from './promise';
+import { dispatchUnhandledRejection, setUnhandledRejectionHandler } from './promise';
 import { ProtocolEnum } from './type';
 import log4js from '@ray-js/log4js';
 
@@ -94,25 +94,27 @@ export function MqttProvider(_ref) {
 
   // 设置全局错误处理器（不依赖 window，适用于小程序环境）
   useEffect(() => {
-    if (onError) {
-      // 设置全局错误处理器
-      setUnhandledRejectionHandler(error => {
-        try {
-          onError(error);
-        } catch (handlerError) {
-          // 避免错误处理器本身抛出错误导致无限循环
-          console.error('Error in MQTT error handler:', handlerError);
-        }
-      });
-    } else {
-      // 如果没有提供错误处理器，设置默认处理器（记录警告）
-      setUnhandledRejectionHandler(error => {
-        console.warn(`[MQTT] Unhandled rejection for ${error.reqType}:`, error.message);
-      });
-    }
+    var _tyGlobal$onUnhandled;
+    // 注册处理器：业务方传了 onError 就用它，否则退化为警告日志
+    setUnhandledRejectionHandler(onError !== null && onError !== void 0 ? onError : error => {
+      console.warn(`[MQTT] Unhandled rejection for ${error.reqType}:`, error.message);
+    });
+
+    // 兜底：监听小程序全局未处理的 Promise rejection。
+    // 当业务方"即发即忘"地调用 query/request（未 catch）且失败时，rejection 会走到这里；
+    // dispatchUnhandledRejection 只转发本库产生的 MqttError 给上面注册的处理器（onError），
+    // 从而避免这类错误作为未处理异常继续向上冒泡，同时不会误吞无关的应用级 rejection。
+    const onGlobalUnhandledRejection = res => {
+      dispatchUnhandledRejection(res === null || res === void 0 ? void 0 : res.reason);
+    };
+    // 部分环境 / 旧类型定义未声明该 API，做类型收窄 + 运行时判空，避免非小程序环境（如测试）报错
+    const tyGlobal = typeof ty === 'undefined' ? undefined : ty;
+    tyGlobal === null || tyGlobal === void 0 || (_tyGlobal$onUnhandled = tyGlobal.onUnhandledRejection) === null || _tyGlobal$onUnhandled === void 0 || _tyGlobal$onUnhandled.call(tyGlobal, onGlobalUnhandledRejection);
 
-    // 清理函数：组件卸载时移除全局处理器
+    // 清理函数：组件卸载时移除全局处理器与监听
     return () => {
+      var _tyGlobal$offUnhandle;
+      tyGlobal === null || tyGlobal === void 0 || (_tyGlobal$offUnhandle = tyGlobal.offUnhandledRejection) === null || _tyGlobal$offUnhandle === void 0 || _tyGlobal$offUnhandle.call(tyGlobal, onGlobalUnhandledRejection);
       setUnhandledRejectionHandler(null);
     };
   }, [onError]);

package/lib/mqtt/promise.d.ts

@@ -24,6 +24,18 @@ export declare class MqttError extends Error {
         reqType: string;
     });
 }
+/**
+ * 判断是否为本库（MQTT 请求）产生的错误。
+ * 用于全局 unhandledrejection 兜底时，只处理本库错误，避免误吞/误报无关的应用级 rejection。
+ */
+export declare function isMqttError(error: unknown): error is MqttError;
+/**
+ * 分发一个未被业务方 catch 的 rejection。
+ * 仅当它是本库产生的 MQTT 错误、且已通过 setUnhandledRejectionHandler 注册处理器时，才转发给该处理器。
+ *
+ * @returns 是否已被本库处理（true 表示已转发给 onError，可视为"已消费"）
+ */
+export declare function dispatchUnhandledRejection(reason: unknown): boolean;
 /**
  * MQTT 响应消息类型（兼容 MQTT 响应格式）
  */

package/lib/mqtt/promise.js

@@ -51,6 +51,33 @@ export class MqttError extends Error {
   }
 }
 
+/**
+ * 判断是否为本库（MQTT 请求）产生的错误。
+ * 用于全局 unhandledrejection 兜底时，只处理本库错误，避免误吞/误报无关的应用级 rejection。
+ */
+export function isMqttError(error) {
+  return error instanceof MqttError || (error === null || error === void 0 ? void 0 : error.name) === 'MqttError';
+}
+
+/**
+ * 分发一个未被业务方 catch 的 rejection。
+ * 仅当它是本库产生的 MQTT 错误、且已通过 setUnhandledRejectionHandler 注册处理器时，才转发给该处理器。
+ *
+ * @returns 是否已被本库处理（true 表示已转发给 onError，可视为"已消费"）
+ */
+export function dispatchUnhandledRejection(reason) {
+  if (!isMqttError(reason) || !globalUnhandledRejectionHandler) {
+    return false;
+  }
+  try {
+    globalUnhandledRejectionHandler(reason);
+  } catch (handlerError) {
+    // 避免错误处理器本身抛出错误导致无限循环
+    console.error('Error in MQTT error handler:', handlerError);
+  }
+  return true;
+}
+
 /**
  * MQTT 响应消息类型（兼容 MQTT 响应格式）
  */

package/lib/mqtt/spotPolygons.d.ts

@@ -0,0 +1,7 @@
+import type { SetSpotPolygonsData } from './type/protocols/spotPolygonsProtocol';
+export declare const createSpotPolygonsPayload: ({ polygons, spotNames, version, }: SetSpotPolygonsData) => {
+    version?: string | undefined;
+    num: number;
+    polygons: string[];
+    spotNames: string[];
+};

package/lib/mqtt/spotPolygons.js

@@ -0,0 +1,18 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+export const createSpotPolygonsPayload = _ref => {
+  let {
+    polygons,
+    spotNames,
+    version
+  } = _ref;
+  if (polygons.length !== spotNames.length) {
+    throw new Error('polygons and spotNames must have the same length');
+  }
+  return _objectSpread({
+    num: polygons.length,
+    polygons,
+    spotNames
+  }, version && {
+    version
+  });
+};

package/lib/mqtt/type/protocols/cruiseProtocol.d.ts

@@ -0,0 +1,39 @@
+import type { BaseResponse } from './base';
+/** 巡航控制指令 */
+export type CruiseCmd = 'start' | 'pause' | 'resume' | 'stop';
+/** 巡航状态：idle 未巡航 / cruising 巡航中 / paused 已暂停 */
+export type CruiseStatus = 'idle' | 'cruising' | 'paused';
+/** 巡航类型：whole_house 全屋巡航 / spot 定点巡航（按净化点坐标） */
+export type CruiseType = 'whole_house' | 'spot';
+export interface SetCruiseData {
+    /** start 开始 / pause 暂停 / resume 继续 / stop 结束 */
+    cmd: CruiseCmd;
+    /** 巡航类型，cmd 为 start 时必填 */
+    cruiseType?: CruiseType;
+    /** spot 定点巡航时的净化点坐标列表，格式 "x, y"；不传表示全部净化点 */
+    polygons?: string[];
+    /** spot 定点巡航时的净化点数量，= polygons.length；不传时由设备侧根据 polygons 长度推断 */
+    num?: number;
+    version?: string;
+}
+export interface RequestCruiseData {
+    version?: string;
+}
+export interface CruiseResponse extends BaseResponse {
+    /** Wiki 协议中的当前巡航指令/状态字段 */
+    cmd?: CruiseCmd;
+    /** 兼容旧设备的巡航状态 */
+    status?: CruiseStatus;
+    /** 当前地图 ID，设备可不返回 */
+    mapId?: number;
+    /** 巡航类型；idle 时可不携带 */
+    cruiseType?: CruiseType;
+    /** spot 定点巡航时的净化点坐标列表，格式 "x, y" */
+    polygons?: string[];
+    /** spot 定点巡航时的净化点数量 */
+    num?: number;
+    /** 当前正在净化的坐标 "x, y" */
+    currentPolygon?: string;
+}
+export type TRequestCruise = (message?: RequestCruiseData) => Promise<CruiseResponse>;
+export type TSetCruise = (message: SetCruiseData) => Promise<CruiseResponse>;

package/lib/mqtt/type/protocols/cruiseProtocol.js

@@ -0,0 +1 @@
+export {};

package/lib/mqtt/type/protocols/index.d.ts

@@ -18,3 +18,8 @@ export * from './deviceModelProtocol';
 export * from './carpetCleanProtocol';
 export * from './devInfoProtocol';
 export * from './roomPropertyProtocol';
+export * from './purifierScheduleProtocol';
+export * from './cruiseProtocol';
+export * from './spotPolygonsProtocol';
+export * from './mcsRoomInfoProtocol';
+export * from './thresholdProtocol';

package/lib/mqtt/type/protocols/index.js

@@ -17,4 +17,9 @@ export * from './furnitureModelProtocol';
 export * from './deviceModelProtocol';
 export * from './carpetCleanProtocol';
 export * from './devInfoProtocol';
-export * from './roomPropertyProtocol';
+export * from './roomPropertyProtocol';
+export * from './purifierScheduleProtocol';
+export * from './cruiseProtocol';
+export * from './spotPolygonsProtocol';
+export * from './mcsRoomInfoProtocol';
+export * from './thresholdProtocol';

package/lib/mqtt/type/protocols/mcsRoomInfoProtocol.d.ts

@@ -0,0 +1,18 @@
+import type { BaseResponse } from './base';
+export interface RequestMcsRoomInfoData {
+    /** 协议版本；默认 '1.0.0' */
+    version?: string;
+}
+/**
+ * McsRoomInfoQry 应答（RVC SDK Alexa 语音方案协议）。
+ * 注意：房间字段为 snake_case（与设备端 MCS_ROOM_INFO_S 结构体对应）。
+ */
+export interface McsRoomInfoResponse extends BaseResponse {
+    /** 当前地图 ID */
+    mapId: number;
+    /** 设备当前所在房间 ID（与 roomPropertyQry 的 ids 对应） */
+    curr_room_id: number;
+    /** 设备当前所在房间名称 */
+    curr_room_name: string;
+}
+export type TRequestMcsRoomInfo = (message?: RequestMcsRoomInfoData) => Promise<McsRoomInfoResponse>;

package/lib/mqtt/type/protocols/mcsRoomInfoProtocol.js

@@ -0,0 +1 @@
+export {};

package/lib/mqtt/type/protocols/purifierScheduleProtocol.d.ts

@@ -0,0 +1,50 @@
+import type { BaseResponse } from './base';
+/**
+ * 工作类型：
+ * - select_room 选房净化（携带 ids）
+ * - whole_house 整屋净化
+ * - spot 定点净化
+ * - current_location 原地净化
+ */
+export type PurifierWorkType = 'select_room' | 'whole_house' | 'spot' | 'current_location';
+/** 风速档位，透传字符串，不限制具体取值（不同设备支持的档位不同） */
+export type PurifierFanMode = string;
+export interface PurifierScheduleItem {
+    /** 是否启用：1 启用 / 0 禁用 */
+    active: number;
+    /** 周重复，长度 7（周一~周日），1 生效；全 0 表示仅执行一次 */
+    cycle: number[];
+    /** 执行时间 [时, 分]，24 小时制 */
+    time: number[];
+    /** 房间 ID 列表；workTypes 为 whole_house / spot / current_location 时为空数组 */
+    ids: number[];
+    /** 工作类型，与 ids 对齐；非 select_room 时为单元素 */
+    workTypes: PurifierWorkType[];
+    /** 风速，与 ids 对齐（整屋时单元素） */
+    fanModes: PurifierFanMode[];
+    /** 风速速度百分比 percent_setting(0-100)，与 ids 对齐（整屋时单元素）；仅当对应 fanMode 为 manual 时才下发 */
+    percents?: number[];
+    /** 净化顺序，与 ids 对齐 */
+    orders?: number[];
+    /** 房间名称，与 ids 对齐 */
+    names?: string[];
+    /** 净化点坐标 "x, y"，与 ids 对齐 */
+    polygons?: string[];
+}
+export interface SetPurifierScheduleData {
+    /** 定时任务数量，= list.length */
+    num: number;
+    /** 定时任务列表（覆盖式全量下发） */
+    list: PurifierScheduleItem[];
+    version?: string;
+}
+export interface RequestPurifierScheduleData {
+    version?: string;
+}
+export interface PurifierScheduleResponse extends BaseResponse {
+    mapId: number;
+    num: number;
+    list: PurifierScheduleItem[];
+}
+export type TRequestPurifierSchedule = (message?: RequestPurifierScheduleData) => Promise<PurifierScheduleResponse>;
+export type TSetPurifierSchedule = (message: SetPurifierScheduleData) => Promise<PurifierScheduleResponse>;

package/lib/mqtt/type/protocols/purifierScheduleProtocol.js

@@ -0,0 +1 @@
+export {};

package/lib/mqtt/type/protocols/roomPropertyProtocol.d.ts

@@ -13,6 +13,8 @@ export interface SetRoomPropertyData {
     orders?: number[];
     routePreferences?: string[];
     waterValues?: number[];
+    /** 净化点坐标 "x, y"，与 ids 一一对应；空字符串表示该房间未设置净化点 */
+    polygons?: string[];
 }
 export interface RoomPropertyResponse extends BaseResponse {
     suctions?: string[];
@@ -29,6 +31,8 @@ export interface RoomPropertyResponse extends BaseResponse {
     orders?: number[];
     routePreferences?: string[];
     waterValues?: number[];
+    /** 净化点坐标 "x, y"，与 ids 一一对应；空字符串表示该房间未设置净化点 */
+    polygons?: string[];
 }
 export type TRequestRoomProperty = () => Promise<RoomPropertyResponse>;
 export type TSetRoomProperty = (data: SetRoomPropertyData) => Promise<RoomPropertyResponse>;

package/lib/mqtt/type/protocols/spotCleanProtocol.d.ts

@@ -3,6 +3,7 @@ export interface SetSpotCleanData extends RoomPreferenceFields {
     spots: Point[];
     origin?: Point;
     names?: string[];
+    spotNames?: string[];
 }
 export interface SpotCleanResponse extends BaseResponse {
     suctions?: string[];
@@ -15,6 +16,7 @@ export interface SpotCleanResponse extends BaseResponse {
     ids?: number[];
     polygons: string[];
     names?: string[];
+    spotNames?: string[];
 }
 export type TRequestSpotClean = () => Promise<SpotCleanResponse>;
 export type TSetSpotClean = (data: SetSpotCleanData) => Promise<SpotCleanResponse>;

package/lib/mqtt/type/protocols/spotPolygonsProtocol.d.ts

@@ -0,0 +1,21 @@
+import type { BaseResponse } from './base';
+export interface SetSpotPolygonsData {
+    /** 定点位置坐标，格式为 "x,y" */
+    polygons: string[];
+    /** 定点位置名称，与 polygons 一一对应 */
+    spotNames: string[];
+    version?: string;
+}
+export interface RequestSpotPolygonsData {
+    version?: string;
+}
+export interface SpotPolygonsResponse extends BaseResponse {
+    /** 定点位置数量 */
+    num: number;
+    /** 定点位置坐标，格式为 "x,y" */
+    polygons: string[];
+    /** 定点位置名称，与 polygons 一一对应 */
+    spotNames: string[];
+}
+export type TRequestSpotPolygons = (message?: RequestSpotPolygonsData) => Promise<SpotPolygonsResponse>;
+export type TSetSpotPolygons = (message: SetSpotPolygonsData) => Promise<SpotPolygonsResponse>;

package/lib/mqtt/type/protocols/spotPolygonsProtocol.js

@@ -0,0 +1 @@
+export {};

package/lib/mqtt/type/protocols/thresholdProtocol.d.ts

@@ -0,0 +1,22 @@
+import type { BaseResponse, Point } from './base';
+export interface ThresholdItem {
+    /** 门槛的 4 个顶点，面板坐标系（未减地图原点） */
+    points: Point[];
+    /** 门槛类型：0 可通过门槛，1 不可通过门槛，2 坡道 */
+    type: number;
+    /** 门槛名称，协议预留字段，不传按空字符串下发 */
+    name?: string;
+}
+export interface SetThresholdData {
+    data: ThresholdItem[];
+    origin: Point;
+}
+export interface ThresholdResponse extends BaseResponse {
+    num: number;
+    polygons: string[];
+    types: number[];
+    names: string[];
+    mapId: number;
+}
+export type TRequestThreshold = () => Promise<ThresholdResponse>;
+export type TSetThreshold = (data: SetThresholdData) => Promise<ThresholdResponse>;

package/lib/mqtt/type/protocols/thresholdProtocol.js

@@ -0,0 +1 @@
+export {};

package/lib/mqtt/type/requestType.d.ts

@@ -46,6 +46,10 @@ export declare enum VirtualAreaEnum {
     query = "restrictedAreaQry",
     set = "restrictedAreaSet"
 }
+export declare enum ThresholdEnum {
+    query = "thresholdQry",
+    set = "thresholdSet"
+}
 export declare enum VoiceLanguageEnum {
     query = "voiceLanguageQry",
     set = "voiceLanguageSet"
@@ -92,3 +96,18 @@ export declare enum CarpetCleanEnum {
     query = "carpetCleanQry",
     set = "carpetCleanSet"
 }
+export declare enum PurifierScheduleEnum {
+    query = "purifierScheduleQry",
+    set = "purifierScheduleSet"
+}
+export declare enum CruiseEnum {
+    query = "purifierCruiseQry",
+    set = "purifierCruiseSet"
+}
+export declare enum SpotPolygonsEnum {
+    query = "spotPolygonsQry",
+    set = "spotPolygonsSet"
+}
+export declare enum McsRoomInfoEnum {
+    query = "McsRoomInfoQry"
+}

package/lib/mqtt/type/requestType.js

@@ -66,6 +66,13 @@ export let VirtualAreaEnum = /*#__PURE__*/function (VirtualAreaEnum) {
   return VirtualAreaEnum;
 }({});
 
+// 门槛
+export let ThresholdEnum = /*#__PURE__*/function (ThresholdEnum) {
+  ThresholdEnum["query"] = "thresholdQry";
+  ThresholdEnum["set"] = "thresholdSet";
+  return ThresholdEnum;
+}({});
+
 // 语音语言枚举
 export let VoiceLanguageEnum = /*#__PURE__*/function (VoiceLanguageEnum) {
   VoiceLanguageEnum["query"] = "voiceLanguageQry";
@@ -137,4 +144,31 @@ export let CarpetCleanEnum = /*#__PURE__*/function (CarpetCleanEnum) {
   CarpetCleanEnum["query"] = "carpetCleanQry";
   CarpetCleanEnum["set"] = "carpetCleanSet";
   return CarpetCleanEnum;
+}({});
+
+// 净化定时（移动空气净化器）
+export let PurifierScheduleEnum = /*#__PURE__*/function (PurifierScheduleEnum) {
+  PurifierScheduleEnum["query"] = "purifierScheduleQry";
+  PurifierScheduleEnum["set"] = "purifierScheduleSet";
+  return PurifierScheduleEnum;
+}({});
+
+// 巡航（面板通用能力，设备侧使用净化器巡航协议）
+export let CruiseEnum = /*#__PURE__*/function (CruiseEnum) {
+  CruiseEnum["query"] = "purifierCruiseQry";
+  CruiseEnum["set"] = "purifierCruiseSet";
+  return CruiseEnum;
+}({});
+
+// 定点位置
+export let SpotPolygonsEnum = /*#__PURE__*/function (SpotPolygonsEnum) {
+  SpotPolygonsEnum["query"] = "spotPolygonsQry";
+  SpotPolygonsEnum["set"] = "spotPolygonsSet";
+  return SpotPolygonsEnum;
+}({});
+
+// 设备当前所在房间（MCS 房间信息；RVC SDK Alexa 语音方案协议，通常仅在任务中查询）
+export let McsRoomInfoEnum = /*#__PURE__*/function (McsRoomInfoEnum) {
+  McsRoomInfoEnum["query"] = "McsRoomInfoQry";
+  return McsRoomInfoEnum;
 }({});

package/lib/mqtt/useCruise.d.ts

@@ -0,0 +1,9 @@
+import { type TRequestCruise, type TSetCruise } from './type/protocols/cruiseProtocol';
+/**
+ * 自定义 Hook，用于移动设备巡航状态查询与控制（如移动空气净化器、移动垃圾桶）
+ * @returns 包含 requestCruise 和 setCruise 函数的对象
+ */
+export declare const useCruise: () => {
+    requestCruise: TRequestCruise;
+    setCruise: TSetCruise;
+};

package/lib/mqtt/useCruise.js

@@ -0,0 +1,67 @@
+// 巡航（通用：移动空气净化器、移动垃圾桶等移动设备）
+import { useContext } from 'react';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+import { SingletonContext } from './mqttProvider';
+import { createCruisePayload } from './cruise';
+import { CruiseEnum } from './type';
+/**
+ * 自定义 Hook，用于移动设备巡航状态查询与控制（如移动空气净化器、移动垃圾桶）
+ * @returns 包含 requestCruise 和 setCruise 函数的对象
+ */
+export const useCruise = () => {
+  const {
+    useMqtt
+  } = useContext(SingletonContext);
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+
+  /**
+   * 查询巡航状态（status）与巡航类型（cruiseType）
+   * @param message 可选参数，包含版本号
+   * @returns Promise<CruiseResponse> 响应结果
+   */
+
+  /**
+   * 巡航控制：cmd 为 start / pause / resume / stop；start 时需携带 cruiseType
+   * @param message 巡航控制数据
+   * @returns Promise<CruiseResponse> 响应结果
+   */
+
+  return {
+    requestCruise: function () {
+      let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+        version: '1.0.0'
+      };
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(CruiseEnum.query, message, resolve, error => reject(handleMqttError(error, 'Failed to request cruise')));
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to request cruise'));
+        }
+      });
+    },
+    setCruise: message => {
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          if (message.cmd === 'start' && !message.cruiseType) {
+            reject(new Error('cruiseType is required when cmd is "start"'));
+            return;
+          }
+          sendStructuredMessage(CruiseEnum.set, createCruisePayload(message), resolve, error => reject(handleMqttError(error, 'Failed to set cruise')), CruiseEnum.query // 响应类型是 query，不是 set
+          );
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to set cruise'));
+        }
+      });
+    }
+  };
+};

package/lib/mqtt/useMcsRoomInfo.d.ts

@@ -0,0 +1,9 @@
+import { type TRequestMcsRoomInfo } from './type/protocols/mcsRoomInfoProtocol';
+/**
+ * 自定义 Hook，用于查询设备当前所在房间（mapId / currNameId / currName）。
+ * 面板通常仅在设备处于任务中时查询，用于展示「当前位置」。
+ * @returns 包含 requestMcsRoomInfo 函数的对象
+ */
+export declare const useMcsRoomInfo: () => {
+    requestMcsRoomInfo: TRequestMcsRoomInfo;
+};

package/lib/mqtt/useMcsRoomInfo.js

@@ -0,0 +1,43 @@
+// 设备当前所在房间（MCS 房间信息）
+import { useContext } from 'react';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+import { SingletonContext } from './mqttProvider';
+import { McsRoomInfoEnum } from './type';
+/**
+ * 自定义 Hook，用于查询设备当前所在房间（mapId / currNameId / currName）。
+ * 面板通常仅在设备处于任务中时查询，用于展示「当前位置」。
+ * @returns 包含 requestMcsRoomInfo 函数的对象
+ */
+export const useMcsRoomInfo = () => {
+  const {
+    useMqtt
+  } = useContext(SingletonContext);
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+
+  /**
+   * 查询设备当前所在房间
+   * @param message 可选参数，包含版本号
+   * @returns Promise<McsRoomInfoResponse> 响应结果
+   */
+
+  return {
+    requestMcsRoomInfo: function () {
+      let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+        version: '1.0.0'
+      };
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(McsRoomInfoEnum.query, message, resolve, error => reject(handleMqttError(error, 'Failed to request mcs room info')));
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to request mcs room info'));
+        }
+      });
+    }
+  };
+};

package/lib/mqtt/usePurifierSchedule.d.ts

@@ -0,0 +1,9 @@
+import { type TRequestPurifierSchedule, type TSetPurifierSchedule } from './type/protocols/purifierScheduleProtocol';
+/**
+ * 自定义 Hook，用于净化定时任务管理（移动空气净化器）
+ * @returns 包含 requestPurifierSchedule 和 setPurifierSchedule 函数的对象
+ */
+export declare const usePurifierSchedule: () => {
+    requestPurifierSchedule: TRequestPurifierSchedule;
+    setPurifierSchedule: TSetPurifierSchedule;
+};

package/lib/mqtt/usePurifierSchedule.js

@@ -0,0 +1,66 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+// 净化定时（移动空气净化器）
+import { useContext } from 'react';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+import { SingletonContext } from './mqttProvider';
+import { PurifierScheduleEnum } from './type';
+/**
+ * 自定义 Hook，用于净化定时任务管理（移动空气净化器）
+ * @returns 包含 requestPurifierSchedule 和 setPurifierSchedule 函数的对象
+ */
+export const usePurifierSchedule = () => {
+  const {
+    useMqtt
+  } = useContext(SingletonContext);
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+
+  /**
+   * 请求净化定时数据
+   * @param message 可选参数，包含版本号
+   * @returns Promise<PurifierScheduleResponse> 响应结果
+   */
+
+  /**
+   * 设置净化定时数据（覆盖式全量下发）
+   * @param message 定时任务数据
+   * @returns Promise<PurifierScheduleResponse> 响应结果
+   */
+
+  return {
+    requestPurifierSchedule: function () {
+      let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+        version: '1.0.0'
+      };
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(PurifierScheduleEnum.query, message, resolve, error => reject(handleMqttError(error, 'Failed to request purifier schedule')));
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to request purifier schedule'));
+        }
+      });
+    },
+    setPurifierSchedule: message => {
+      return new Promise((resolve, reject) => {
+        try {
+          var _message$num;
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(PurifierScheduleEnum.set, _objectSpread(_objectSpread({}, message), {}, {
+            num: (_message$num = message.num) !== null && _message$num !== void 0 ? _message$num : message.list.length
+          }), resolve, error => reject(handleMqttError(error, 'Failed to set purifier schedule')), PurifierScheduleEnum.query // 响应类型是 query，不是 set
+          );
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to set purifier schedule'));
+        }
+      });
+    }
+  };
+};

package/lib/mqtt/useRoomProperty.js

@@ -57,7 +57,7 @@ export const useRoomProperty = () => {
             ids
           } = data;
           const len = ids.length;
-          const sendData = _objectSpread(_objectSpread({
+          const sendData = _objectSpread(_objectSpread(_objectSpread({
             num: (_data$num = data.num) !== null && _data$num !== void 0 ? _data$num : len,
             ids,
             suctions: (_data$suctions = data.suctions) !== null && _data$suctions !== void 0 ? _data$suctions : new Array(len).fill('closed'),
@@ -70,6 +70,8 @@ export const useRoomProperty = () => {
             orders: data.orders
           }, data.routePreferences && {
             routePreferences: data.routePreferences
+          }), data.polygons && {
+            polygons: data.polygons
           }), pickWaterFields(len, data.cisterns, data.waterValues));
           sendStructuredMessage(RoomPropertyEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set room property')), RoomPropertyEnum.query // 响应类型是 query，不是 set
           );

package/lib/mqtt/useSpotClean.js

@@ -62,10 +62,11 @@ export const useSpotClean = () => {
             yMops = new Array(num).fill(-1),
             sweepMopModes = new Array(num).fill('only_sweep'),
             routePreferences,
-            names
+            names,
+            spotNames
           } = message;
           if (useMqtt) {
-            sendStructuredMessage(SpotCleanEnum.set, _objectSpread(_objectSpread(_objectSpread({
+            sendStructuredMessage(SpotCleanEnum.set, _objectSpread(_objectSpread(_objectSpread(_objectSpread({
               num,
               polygons: spots.map(spot => pointsToString([spot], origin)),
               suctions
@@ -77,6 +78,8 @@ export const useSpotClean = () => {
               routePreferences
             }), names && {
               names
+            }), spotNames && {
+              spotNames
             }), resolve, error => reject(handleMqttError(error, 'Failed to set spot clean')), SpotCleanEnum.query // 响应类型是 query，不是 set
             );
             return;
@@ -89,7 +92,7 @@ export const useSpotClean = () => {
             point: spots[0]
           });
           devices.common.model.actions.command_trans.set(command);
-          resolve(_objectSpread(_objectSpread(_objectSpread({
+          resolve(_objectSpread(_objectSpread(_objectSpread(_objectSpread({
             success: true,
             errCode: 0,
             reqType: SpotCleanEnum.query,
@@ -105,6 +108,8 @@ export const useSpotClean = () => {
             routePreferences
           }), names && {
             names
+          }), spotNames && {
+            spotNames
           }));
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set spot clean'));

package/lib/mqtt/useSpotPolygons.d.ts

@@ -0,0 +1,9 @@
+import { type TRequestSpotPolygons, type TSetSpotPolygons } from './type/protocols/spotPolygonsProtocol';
+/**
+ * 自定义 Hook，用于定点位置查询与设置
+ * @returns 包含 requestSpotPolygons 和 setSpotPolygons 函数的对象
+ */
+export declare const useSpotPolygons: () => {
+    requestSpotPolygons: TRequestSpotPolygons;
+    setSpotPolygons: TSetSpotPolygons;
+};

package/lib/mqtt/useSpotPolygons.js

@@ -0,0 +1,48 @@
+import { useContext } from 'react';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+import { SingletonContext } from './mqttProvider';
+import { createSpotPolygonsPayload } from './spotPolygons';
+import { SpotPolygonsEnum } from './type';
+/**
+ * 自定义 Hook，用于定点位置查询与设置
+ * @returns 包含 requestSpotPolygons 和 setSpotPolygons 函数的对象
+ */
+export const useSpotPolygons = () => {
+  const {
+    useMqtt
+  } = useContext(SingletonContext);
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+  return {
+    requestSpotPolygons: function () {
+      let message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+        version: '1.0.0'
+      };
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(SpotPolygonsEnum.query, message, resolve, error => reject(handleMqttError(error, 'Failed to request spot polygons')));
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to request spot polygons'));
+        }
+      });
+    },
+    setSpotPolygons: message => {
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(SpotPolygonsEnum.set, createSpotPolygonsPayload(message), resolve, error => reject(handleMqttError(error, 'Failed to set spot polygons')), SpotPolygonsEnum.query);
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to set spot polygons'));
+        }
+      });
+    }
+  };
+};

package/lib/mqtt/useThreshold.d.ts

@@ -0,0 +1,10 @@
+import { type TRequestThreshold, type TSetThreshold } from './type/protocols';
+/**
+ * 自定义 Hook，用于门槛管理（可通过门槛 / 不可通过门槛 / 坡道）
+ * 门槛协议仅支持 MQTT / LAN 结构化消息通道，未启用 useMqtt 时直接 reject
+ * @returns 包含 requestThreshold 和 setThreshold 函数的对象
+ */
+export declare const useThreshold: () => {
+    requestThreshold: TRequestThreshold;
+    setThreshold: TSetThreshold;
+};

package/lib/mqtt/useThreshold.js

@@ -0,0 +1,88 @@
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.for-each.js";
+// 门槛（可通过门槛 / 不可通过门槛 / 坡道）
+import { useContext } from 'react';
+import { pointsToString } from '../utils';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+import { SingletonContext } from './mqttProvider';
+import { ThresholdEnum } from './type';
+// 门槛
+
+/**
+ * 自定义 Hook，用于门槛管理（可通过门槛 / 不可通过门槛 / 坡道）
+ * 门槛协议仅支持 MQTT / LAN 结构化消息通道，未启用 useMqtt 时直接 reject
+ * @returns 包含 requestThreshold 和 setThreshold 函数的对象
+ */
+export const useThreshold = () => {
+  const {
+    useMqtt
+  } = useContext(SingletonContext);
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+
+  /**
+   * 请求门槛数据
+   * @returns Promise<ThresholdResponse> 响应结果
+   */
+
+  /**
+   * 设置门槛数据（全量覆盖，传空数组表示清空全部门槛）
+   * @param message 包含门槛设置参数的对象
+   * @param message.data 门槛的数据数组，每项含 4 个顶点、类型与可选名称
+   * @param message.origin 原点坐标
+   * @returns Promise<ThresholdResponse> 响应结果
+   */
+
+  return {
+    requestThreshold: () => {
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          sendStructuredMessage(ThresholdEnum.query, {}, resolve, error => reject(handleMqttError(error, 'Failed to request threshold')));
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to request threshold'));
+        }
+      });
+    },
+    setThreshold: message => {
+      return new Promise((resolve, reject) => {
+        try {
+          if (!useMqtt) {
+            reject(new Error('useMqtt is not used'));
+            return;
+          }
+          const {
+            data,
+            origin
+          } = message;
+          const polygons = [];
+          const types = [];
+          const names = [];
+          data.forEach(_ref => {
+            let {
+              points,
+              type,
+              name
+            } = _ref;
+            polygons.push(pointsToString(points, origin));
+            types.push(type);
+            names.push(name !== null && name !== void 0 ? name : '');
+          });
+          sendStructuredMessage(ThresholdEnum.set, {
+            num: data.length,
+            polygons,
+            types,
+            names
+          }, resolve, error => reject(handleMqttError(error, 'Failed to set threshold')), ThresholdEnum.query // 响应类型是 query，不是 set
+          );
+        } catch (error) {
+          reject(handleMqttError(error, 'Failed to set threshold'));
+        }
+      });
+    }
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/robot-data-stream",
-  "version": "0.0.16",
+  "version": "0.0.17-beta.10",
   "description": "扫地机P2P数据流标准化组件",
   "main": "lib/index",
   "files": [