@ray-js/robot-data-stream 0.0.17-beta.9 → 0.1.0-beta.0

package/lib/index.js

@@ -7,6 +7,8 @@ import { trace } from './trace';
 import { emitter, logger, logP2PDataIfEnabled } from './utils';
 export * from './mqtt';
 export * from './mqtt/type/requestType';
+// 手拼标准指令 payload（自定义指令的字段级扩展场景）需要复用的纯工具
+export { pointsToString, pickWaterFields } from './utils';
 const useP2PDataStream = (devId, onReceiveMapData, onReceivePathData, opt) => {
   const traceId = `${devId}_${Date.now()}`;
   global.robotPanelTraceId = traceId;
@@ -17,9 +19,61 @@ const useP2PDataStream = (devId, onReceiveMapData, onReceivePathData, opt) => {
     onReceiveAIPicHDData,
     onReceiveWifiMapData,
     onLogger,
-    onDefineStructuredMode
+    onDefineStructuredMode,
+    onError,
+    firstFrameTimeout = 8000
   } = opt || {};
   SweeperP2pInstance.enableCustomLog = enableCustomLog;
+  SweeperP2pInstance.onError = onError;
+  const onReceiveMapDataRef = useRef(onReceiveMapData);
+  onReceiveMapDataRef.current = onReceiveMapData;
+  const onReceivePathDataRef = useRef(onReceivePathData);
+  onReceivePathDataRef.current = onReceivePathData;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+  const firstFrameTimer = useRef(null);
+  const hasReceivedFirstFrame = useRef(false);
+  const clearFirstFrameTimer = useCallback(() => {
+    if (firstFrameTimer.current) {
+      clearTimeout(firstFrameTimer.current);
+      firstFrameTimer.current = null;
+    }
+    hasReceivedFirstFrame.current = true;
+  }, []);
+  const startFirstFrameWatchdog = useCallback(() => {
+    clearFirstFrameTimer();
+    hasReceivedFirstFrame.current = false;
+    if (firstFrameTimeout && firstFrameTimeout > 0) {
+      firstFrameTimer.current = setTimeout(() => {
+        if (!hasReceivedFirstFrame.current) {
+          var _onErrorRef$current;
+          logger('warn', {
+            msg: `First frame timeout (${firstFrameTimeout}ms), triggering reDownloadStream`
+          }, onLogger);
+          logP2PDataIfEnabled(enableCustomLog, devId, 'first_frame_timeout', `First frame timeout after ${firstFrameTimeout}ms, triggering reDownloadStream`);
+          (_onErrorRef$current = onErrorRef.current) === null || _onErrorRef$current === void 0 || _onErrorRef$current.call(onErrorRef, {
+            code: 'FIRST_FRAME_TIMEOUT',
+            message: `First frame not received within ${firstFrameTimeout}ms`
+          });
+          SweeperP2pInstance.reDownloadStream('first_frame_timeout');
+        }
+      }, firstFrameTimeout);
+    }
+  }, [firstFrameTimeout, devId, enableCustomLog, onLogger, clearFirstFrameTimer]);
+  const handleReceiveMapData = useCallback(data => {
+    var _onReceiveMapDataRef$;
+    if (data && data.length > 0) {
+      clearFirstFrameTimer();
+    }
+    (_onReceiveMapDataRef$ = onReceiveMapDataRef.current) === null || _onReceiveMapDataRef$ === void 0 || _onReceiveMapDataRef$.call(onReceiveMapDataRef, data);
+  }, [clearFirstFrameTimer]);
+  const handleReceivePathData = useCallback(data => {
+    var _onReceivePathDataRef;
+    if (data && data.length > 0) {
+      clearFirstFrameTimer();
+    }
+    (_onReceivePathDataRef = onReceivePathDataRef.current) === null || _onReceivePathDataRef === void 0 || _onReceivePathDataRef.call(onReceivePathDataRef, data);
+  }, [clearFirstFrameTimer]);
   logP2PDataIfEnabled(enableCustomLog, devId, 'hooks_init', `useP2PDataStream initialized, traceId: ${traceId}`);
   const isInit = useRef(false);
   const offSessionStatusChange = useRef(null);
@@ -145,7 +199,8 @@ const useP2PDataStream = (devId, onReceiveMapData, onReceivePathData, opt) => {
       });
       isInit.current = true;
       logP2PDataIfEnabled(enableCustomLog, devId, 'start_observer_data', 'Starting to observe sweeper data by P2P');
-      SweeperP2pInstance.startObserverSweeperDataByP2P(1, devId, onReceiveMapData, onReceivePathData, onReceiveAIPicData, onReceiveAIPicHDData, onReceiveWifiMapData, onDefineStructuredMode);
+      startFirstFrameWatchdog();
+      SweeperP2pInstance.startObserverSweeperDataByP2P(1, devId, handleReceiveMapData, handleReceivePathData, onReceiveAIPicData, onReceiveAIPicHDData, onReceiveWifiMapData, onDefineStructuredMode);
       offSessionStatusChange.current = SweeperP2pInstance.onSessionStatusChange(SweeperP2pInstance.sessionStatusCallback);
     }, () => {
       logP2PDataIfEnabled(enableCustomLog, devId, 'connect_p2p_fail', 'P2P connection failed, attempting reconnect');
@@ -161,7 +216,8 @@ const useP2PDataStream = (devId, onReceiveMapData, onReceivePathData, opt) => {
           eventName: 'reconnectP2p'
         });
         logP2PDataIfEnabled(enableCustomLog, devId, 'start_observer_data_after_reconnect', 'Starting to observe sweeper data after reconnect');
-        SweeperP2pInstance.startObserverSweeperDataByP2P(1, devId, onReceiveMapData, onReceivePathData, onReceiveAIPicData, onReceiveAIPicHDData, onReceiveWifiMapData);
+        startFirstFrameWatchdog();
+        SweeperP2pInstance.startObserverSweeperDataByP2P(1, devId, handleReceiveMapData, handleReceivePathData, onReceiveAIPicData, onReceiveAIPicHDData, onReceiveWifiMapData, onDefineStructuredMode);
         // 这里失败重连需要注册断开重连的事件
         offSessionStatusChange.current = SweeperP2pInstance.onSessionStatusChange(SweeperP2pInstance.sessionStatusCallback);
       }, '');
@@ -177,6 +233,7 @@ const useP2PDataStream = (devId, onReceiveMapData, onReceivePathData, opt) => {
     }, onLogger);
     logP2PDataIfEnabled(enableCustomLog, devId, 'unmount_p2p', 'Unmounting P2P connection');
     isInit.current = false;
+    clearFirstFrameTimer();
     SweeperP2pInstance.stopObserverSweeperDataByP2P();
     if (offSessionStatusChange.current) {
       offSessionStatusChange.current();

package/lib/mqtt/createCommonOptions.d.ts

@@ -43,25 +43,7 @@ export interface CreateSetCommonParamsOutput {
     options: MqttOptions;
     /** 协议号 */
     protocol: ProtocolEnum;
+    /** 本次下发生成的 taskId（已拼进 message；LAN 场景 message 为 JSON 字符串，从这里取） */
+    taskId: string;
 }
-/**
- * 创建 MQTT 通用参数
- *
- * @param params - 参数对象
- * @param params.deviceId - 设备ID
- * @param params.reqType - 请求类型
- * @param params.message - 消息体（可选）
- * @param params.version - 版本号（可选，默认为 1.0.0）
- * @param params.options - 选项（可选）
- * @returns MQTT 通用参数对象
- *
- * @example
- * ```ts
- * const params = createSetCommonParams({
- *   deviceId: 'device123',
- *   reqType: 'devInfoQry',
- *   message: { customField: 'value' }
- * });
- * ```
- */
 export declare const createSetCommonParams: ({ deviceId, reqType, isLocalOnLine, message, version, options, }: CreateSetCommonParamsInput) => CreateSetCommonParamsOutput;

package/lib/mqtt/createCommonOptions.js

@@ -42,6 +42,13 @@ const DEFAULT_VERSION = '1.0.0';
  * });
  * ```
  */
+/**
+ * 同毫秒内的自增序号：保证并发下发（如双击连发）也能拿到互不相同的 taskId，
+ * 否则同一毫秒内的两条请求 taskId 相同，响应匹配无法区分。
+ * 固件侧 taskId 按不透明字符串暂存并原样带回（__mqtt_task_id_pack），追加后缀不影响协议。
+ */
+let taskSequence = 0;
+const createTaskId = () => `${Date.now()}_${++taskSequence}`;
 export const createSetCommonParams = _ref => {
   let {
     deviceId,
@@ -51,12 +58,16 @@ export const createSetCommonParams = _ref => {
     version = DEFAULT_VERSION,
     options = {}
   } = _ref;
-  const taskId = Date.now();
-  const messageData = _objectSpread({
+  const taskId = createTaskId();
+
+  // taskId 由本库统一生成并权威覆盖：message 先展开，避免调用方（或照协议文档抄示例的
+  // 定制开发者）在 message 里夹带 taskId 覆盖线上值——那会让回执与固件回显永远对不上，
+  // 双匹配直接退化成必然超时。回执 taskId 始终与线上 message.taskId 一致。
+  const messageData = _objectSpread(_objectSpread({}, message), {}, {
     reqType,
     version,
-    taskId: `${taskId}`
-  }, message);
+    taskId
+  });
   return {
     deviceId,
     message: !isLocalOnLine ? messageData : JSON.stringify({
@@ -64,6 +75,7 @@ export const createSetCommonParams = _ref => {
       reqType
     }),
     options,
-    protocol: ProtocolEnum.appToRobot
+    protocol: ProtocolEnum.appToRobot,
+    taskId
   };
 };

package/lib/mqtt/defineRobotCommand.d.ts

@@ -0,0 +1,52 @@
+import { BaseResponse } from './type/protocols/base';
+/**
+ * 指令声明配置
+ */
+export interface RobotCommandConfig {
+    /** 下发 reqType */
+    reqType: string;
+    /**
+     * 响应匹配的事件名（reqType）。
+     * 缺省与下发同名；set 类指令回复走 qry 事件名、
+     * 或回复 reqType 与下发不同名（如 aiObjectIgnoreSet → aiObjectIgnoreRst）时必填。
+     */
+    responseType?: string;
+    /** 协议版本号，默认 '1.0.0' */
+    version?: string;
+    /** 超时时间（毫秒），默认 10000 */
+    timeout?: number;
+}
+/**
+ * defineRobotCommand 的返回：两个独立 hook，在组件内分别调用
+ */
+export interface DefinedRobotCommand<TReq = Record<string, any>, TRes extends BaseResponse = BaseResponse> {
+    /**
+     * 发送 hook，与内置 hook 同构（Promise 命令函数、无 loading 态）。
+     * 固件侧指令标准化入库后，从 useSend 换成对应内置 useXxx ≈ 改一行 import。
+     */
+    useSend: () => {
+        send: (data: TReq) => Promise<TRes>;
+    };
+    /**
+     * 类型化监听 hook：订阅 responseType（缺省 reqType）的上报，
+     * 是 StreamDataNotificationCenter.on 的类型化薄包装。
+     * handler 随渲染更新，订阅本身只在挂载期间维持一份。
+     */
+    useResponse: (handler: (data: TRes) => void) => void;
+}
+/**
+ * 声明一条自定义指令。
+ *
+ * 面向定制面板：协议描述（reqType / 响应名 / 类型）归消费方，库只负责执行。
+ * 在模块顶层调用一次，组件内使用返回的 useSend / useResponse。
+ * 完整示例见 docs/reference/custom-commands.md。
+ *
+ * @example
+ * ```typescript
+ * export const peakValleyCharge = defineRobotCommand<SetPeakValleyData, PeakValleyResponse>({
+ *   reqType: 'peakValleyChargeSet',
+ *   responseType: 'peakValleyChargeQry',
+ * });
+ * ```
+ */
+export declare const defineRobotCommand: <TReq extends Record<string, any> = Record<string, any>, TRes extends BaseResponse = BaseResponse>(config: RobotCommandConfig) => DefinedRobotCommand<TReq, TRes>;

package/lib/mqtt/defineRobotCommand.js

@@ -0,0 +1,71 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+// 自定义指令声明工厂：把「一条指令 = reqType + 类型」固化成可复用的 hook 集
+import { useEffect, useRef } from 'react';
+import { emitter } from '../utils';
+import { normalizeResultFields, unwrapMqttResponse } from './promise';
+import { useCustomCommand } from './useCustomCommand';
+
+/**
+ * 指令声明配置
+ */
+
+/**
+ * defineRobotCommand 的返回：两个独立 hook，在组件内分别调用
+ */
+
+/**
+ * 声明一条自定义指令。
+ *
+ * 面向定制面板：协议描述（reqType / 响应名 / 类型）归消费方，库只负责执行。
+ * 在模块顶层调用一次，组件内使用返回的 useSend / useResponse。
+ * 完整示例见 docs/reference/custom-commands.md。
+ *
+ * @example
+ * ```typescript
+ * export const peakValleyCharge = defineRobotCommand<SetPeakValleyData, PeakValleyResponse>({
+ *   reqType: 'peakValleyChargeSet',
+ *   responseType: 'peakValleyChargeQry',
+ * });
+ * ```
+ */
+export const defineRobotCommand = config => {
+  const {
+    reqType,
+    responseType,
+    version,
+    timeout
+  } = config;
+  const listenType = responseType || reqType;
+  return {
+    useSend: () => {
+      const {
+        sendCustomCommand
+      } = useCustomCommand();
+      return {
+        send: data => sendCustomCommand(reqType, data, {
+          responseType,
+          version,
+          timeout
+        })
+      };
+    },
+    useResponse: handler => {
+      const handlerRef = useRef(handler);
+      useEffect(() => {
+        handlerRef.current = handler;
+      });
+      useEffect(() => {
+        // 与 normalResolve 同一套归一（unwrapMqttResponse + normalizeResultFields）：
+        // LAN socket 通道不经过 mqttProvider 归一，这里补齐，保证两条通道形状一致
+        const wrapped = message => {
+          const payload = unwrapMqttResponse(message);
+          handlerRef.current(_objectSpread(_objectSpread({}, payload), normalizeResultFields(payload)));
+        };
+        emitter.on(listenType, wrapped);
+        return () => {
+          emitter.off(listenType, wrapped);
+        };
+      }, [listenType]);
+    }
+  };
+};

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

@@ -5,7 +5,11 @@ import { BaseResponse } from '../type/protocols/base';
  * 提供统一的 sendMqttMessage 方法，自动从 Context 获取 devId 和配置
  */
 export declare const useStructuredMessage: () => {
-    sendStructuredMessage: <T extends BaseResponse>(reqType: string, message: Record<string, any> | undefined, resolve: (value: T) => void, reject: (reason?: any) => void, responseType?: string) => void;
+    sendStructuredMessage: <T extends BaseResponse>(reqType: string, message: Record<string, any> | undefined, resolve: (value: T) => void, reject: (reason?: any) => void, options?: {
+        responseType?: string;
+        timeout?: number;
+        version?: string;
+    }) => void;
 };
 /**
  * 错误处理工具函数

package/lib/mqtt/hooks/useStructuredMessage.js

@@ -91,12 +91,13 @@ export const useStructuredMessage = () => {
   };
 
   // 创建消息参数
-  const createMessageParams = (reqType, message, useLocal) => {
+  const createMessageParams = (reqType, message, useLocal, version) => {
     return createSetCommonParams({
       deviceId: devId,
       reqType,
       message,
-      isLocalOnLine: useLocal
+      isLocalOnLine: useLocal,
+      version
     });
   };
 
@@ -139,7 +140,12 @@ export const useStructuredMessage = () => {
   /**
    * 发送结构化消息
    */
-  const sendStructuredMessage = useCallback((reqType, message, resolve, reject, responseType) => {
+  const sendStructuredMessage = useCallback((reqType, message, resolve, reject, options) => {
+    const {
+      responseType,
+      timeout,
+      version
+    } = options !== null && options !== void 0 ? options : {};
     // 参数验证
     if (!devId) {
       reject(new Error('设备ID (devId) 为必填项'));
@@ -162,14 +168,24 @@ export const useStructuredMessage = () => {
         method,
         useLocal
       } = selectedMethod;
-      const messageParams = createMessageParams(reqType, message, useLocal);
+      const messageParams = createMessageParams(reqType, message, useLocal, version);
 
       // 成功回调
 
       // 失败回调
 
-      // 发送消息
-      method.send(messageParams, () => {
+      // 处理响应：先挂监听再发送，避免回复先于监听注册到达而丢响应；
+      // taskId 参与匹配，同 reqType 并发请求不会互相串包
+
+      normalResolve(responseType || reqType, messageParams.taskId, resolve, reject, timeout);
+
+      // 发送消息（taskId 是给调用方的回执，不进传输参数）
+      method.send({
+        deviceId: messageParams.deviceId,
+        message: messageParams.message,
+        options: messageParams.options,
+        protocol: messageParams.protocol
+      }, () => {
         const channelName = useLocal ? '局域网' : 'WiFi MQTT';
         const fallbackSuffix = method === mqttCommunication && preferredChannel === COMMUNICATION_CHANNELS.LAN ? ' (备用)' : '';
         logCommunication(LOG_LEVEL.INFO, reqType, `${channelName} 消息发送成功${fallbackSuffix}`, messageParams);
@@ -178,10 +194,6 @@ export const useStructuredMessage = () => {
           error: JSON.stringify(error)
         }));
       });
-
-      // 处理响应
-
-      normalResolve(responseType || reqType, resolve, reject);
     } catch (error) {
       logCommunication(LOG_LEVEL.ERROR, reqType, `发送消息时发生异常: ${error}`);
       reject(error);

package/lib/mqtt/index.d.ts

@@ -23,4 +23,10 @@ import { usePurifierSchedule } from './usePurifierSchedule';
 import { useCruise } from './useCruise';
 import { useSpotPolygons } from './useSpotPolygons';
 import { useMcsRoomInfo } from './useMcsRoomInfo';
-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, };
+import { useThreshold } from './useThreshold';
+import { useCustomCommand } from './useCustomCommand';
+import { defineRobotCommand } from './defineRobotCommand';
+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, useCustomCommand, defineRobotCommand, };
+export type { CustomCommandOptions, TSendCustomCommand } from './useCustomCommand';
+export type { RobotCommandConfig, DefinedRobotCommand } from './defineRobotCommand';
+export * from './type/protocols';

package/lib/mqtt/index.js

@@ -23,4 +23,14 @@ import { usePurifierSchedule } from './usePurifierSchedule';
 import { useCruise } from './useCruise';
 import { useSpotPolygons } from './useSpotPolygons';
 import { useMcsRoomInfo } from './useMcsRoomInfo';
-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 };
+import { useThreshold } from './useThreshold';
+import { useCustomCommand } from './useCustomCommand';
+import { defineRobotCommand } from './defineRobotCommand';
+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, useCustomCommand, defineRobotCommand };
+
+// 自定义指令相关类型
+
+// 内置指令的 payload / 响应类型公共导出：
+// 自定义指令在标准指令上加字段（手拼完整 payload 复用类型）、或包装内置 hook 时直接 import，
+// 不再需要手抄（此前消费方因未导出抄过 SetRoomPropertyData）
+export * from './type/protocols';

package/lib/mqtt/promise.d.ts

@@ -54,15 +54,30 @@ export interface MqttResponseMessage {
 export type PromiseWithRejection = Promise<any> & {
     reject: (reason?: MqttError) => void;
 };
+/**
+ * 拆掉响应外层的「信封」：仅当外层是纯信封形状（除 data / reqType 外没有别的字段，
+ * 且 data 为对象）才取内层——LAN 通道与部分固件的 set-ack 会把真实载荷包在 data 里。
+ * 业务 payload 自带 data 对象字段时不误拆，保证两条通道推出一致形状。
+ */
+export declare const unwrapMqttResponse: (message: any) => MqttResponseMessage;
+/**
+ * 归一 success / errCode：errCode 优先，缺省按 success 推导（success === false → -1，否则 0）。
+ */
+export declare const normalizeResultFields: (payload: MqttResponseMessage) => {
+    errCode: number;
+    success: boolean;
+};
 /**
  * 创建 MQTT 请求的 Promise，监听响应消息
  *
- * ⚠️ 注意：此函数不再使用 taskId 进行匹配，只要接收到对应 reqType 的响应就认为匹配
- * ⚠️ 风险：如果同时发起多个相同 reqType 的请求，可能会匹配到错误的响应
- * ⚠️ 建议：确保业务上不会同时发起多个相同类型的请求
+ * 匹配语义（taskId + reqType 双匹配）：
+ * - 事件按 reqType 订阅；
+ * - 下发方传了 taskId、且响应携带 taskId 时，必须等值才视为本次请求的响应，
+ *   其余响应忽略并继续等待——同 reqType 并发请求不会互相串包；
+ * - 响应缺 taskId（部分固件不回 echo）时放行，避免退化成必然超时。
  *
  * @param reqType 请求类型，用于匹配响应消息
- * @param taskId 任务ID（已废弃，保留参数以保持向后兼容）
+ * @param taskId 下发时生成的任务ID，用于并发区分；传 undefined 退化为 reqType 首响应匹配
  * @param resolve Promise 的 resolve 回调
  * @param reject Promise 的 reject 回调
  * @param timeout 超时时间（毫秒），默认 10 秒
@@ -70,9 +85,9 @@ export type PromiseWithRejection = Promise<any> & {
  * @example
  * ```typescript
  * return new Promise((resolve, reject) => {
- *   normalResolve('carpetQry', '', resolve, reject);
+ *   normalResolve('carpetQry', '1730375500113_1', resolve, reject);
  * });
  * ```
  */
-export declare function normalResolve(reqType: string, resolve: (value: any) => void, reject: (reason?: any) => void, timeout?: number): void;
+export declare function normalResolve(reqType: string, taskId: string | undefined, resolve: (value: any) => void, reject: (reason?: any) => void, timeout?: number): void;
 export type MyError = MqttError;

package/lib/mqtt/promise.js

@@ -1,3 +1,5 @@
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.every.js";
 import { emitter, logger } from '../utils';
 
 /**
@@ -86,15 +88,41 @@ export function dispatchUnhandledRejection(reason) {
  * Promise 扩展类型，支持手动拒绝
  */
 
+/**
+ * 拆掉响应外层的「信封」：仅当外层是纯信封形状（除 data / reqType 外没有别的字段，
+ * 且 data 为对象）才取内层——LAN 通道与部分固件的 set-ack 会把真实载荷包在 data 里。
+ * 业务 payload 自带 data 对象字段时不误拆，保证两条通道推出一致形状。
+ */
+export const unwrapMqttResponse = message => {
+  if (message != null && typeof message === 'object' && message.data != null && typeof message.data === 'object' && Object.keys(message).every(key => key === 'data' || key === 'reqType')) {
+    return message.data;
+  }
+  return message !== null && message !== void 0 ? message : {};
+};
+
+/**
+ * 归一 success / errCode：errCode 优先，缺省按 success 推导（success === false → -1，否则 0）。
+ */
+export const normalizeResultFields = payload => {
+  var _payload$errCode, _payload$success;
+  const errCode = (_payload$errCode = payload.errCode) !== null && _payload$errCode !== void 0 ? _payload$errCode : payload.success === false ? -1 : 0;
+  return {
+    errCode,
+    success: (_payload$success = payload.success) !== null && _payload$success !== void 0 ? _payload$success : errCode === 0
+  };
+};
+
 /**
  * 创建 MQTT 请求的 Promise，监听响应消息
  *
- * ⚠️ 注意：此函数不再使用 taskId 进行匹配，只要接收到对应 reqType 的响应就认为匹配
- * ⚠️ 风险：如果同时发起多个相同 reqType 的请求，可能会匹配到错误的响应
- * ⚠️ 建议：确保业务上不会同时发起多个相同类型的请求
+ * 匹配语义（taskId + reqType 双匹配）：
+ * - 事件按 reqType 订阅；
+ * - 下发方传了 taskId、且响应携带 taskId 时，必须等值才视为本次请求的响应，
+ *   其余响应忽略并继续等待——同 reqType 并发请求不会互相串包；
+ * - 响应缺 taskId（部分固件不回 echo）时放行，避免退化成必然超时。
  *
  * @param reqType 请求类型，用于匹配响应消息
- * @param taskId 任务ID（已废弃，保留参数以保持向后兼容）
+ * @param taskId 下发时生成的任务ID，用于并发区分；传 undefined 退化为 reqType 首响应匹配
  * @param resolve Promise 的 resolve 回调
  * @param reject Promise 的 reject 回调
  * @param timeout 超时时间（毫秒），默认 10 秒
@@ -102,12 +130,12 @@ export function dispatchUnhandledRejection(reason) {
  * @example
  * ```typescript
  * return new Promise((resolve, reject) => {
- *   normalResolve('carpetQry', '', resolve, reject);
+ *   normalResolve('carpetQry', '1730375500113_1', resolve, reject);
  * });
  * ```
  */
-export function normalResolve(reqType, resolve, reject) {
-  let timeout = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : DEFAULT_TIMEOUT;
+export function normalResolve(reqType, taskId, resolve, reject) {
+  let timeout = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : DEFAULT_TIMEOUT;
   let isResolved = false;
 
   // 设置超时定时器
@@ -123,14 +151,21 @@ export function normalResolve(reqType, resolve, reject) {
     }
   }, timeout);
   const handle = message => {
-    var _response$errCode;
-    const response = typeof message.data === 'object' ? message.data : message;
+    const response = unwrapMqttResponse(message);
 
     // 如果已经处理过，直接返回（避免重复处理）
     if (isResolved) {
       return;
     }
 
+    // taskId 匹配：响应携带 taskId 且与本次下发不一致时忽略，继续等待本请求的响应
+    if (taskId && response.taskId != null && `${response.taskId}` !== `${taskId}`) {
+      logger('info', {
+        msg: `${reqType} normalResolve: taskId mismatch, keep waiting (${response.taskId} != ${taskId})`
+      });
+      return;
+    }
+
     // 标记为已处理（防止其他监听器处理）
     isResolved = true;
     clearTimeout(timer);
@@ -140,9 +175,9 @@ export function normalResolve(reqType, resolve, reject) {
 
     // 移除监听器（使用函数引用确保移除正确的监听器）
     emitter.off(reqType, handle);
-
-    // 优先使用 errCode，如果没有则使用 success 字段判断
-    const errCode = (_response$errCode = response.errCode) !== null && _response$errCode !== void 0 ? _response$errCode : response.success === false ? -1 : 0;
+    const {
+      errCode
+    } = normalizeResultFields(response);
     if (errCode === 0) {
       resolve(response);
     } else {

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

@@ -38,6 +38,7 @@ export interface SetCarpetData {
 }
 export interface AddCarpetResponse extends BaseResponse {
     ids: StringOrNumber[];
+    mapId?: number;
 }
 export interface CarpetQueryResponse extends BaseResponse {
     num: number;
@@ -49,6 +50,7 @@ export interface CarpetQueryResponse extends BaseResponse {
     autoBoost?: number[];
     fineCleaning?: number[];
     sideBrushRotating?: number[];
+    mapId?: number;
 }
 export type TQueryCarpet = (data?: QueryCarpetData) => Promise<CarpetQueryResponse>;
 export type TAddCarpet = (data: AddCarpetData) => Promise<AddCarpetResponse>;

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

@@ -1,3 +1,4 @@
+export * from './base';
 export * from './scheduleProtocol';
 export * from './carpetProtocol';
 export * from './zoneCleanProtocol';
@@ -22,3 +23,4 @@ export * from './purifierScheduleProtocol';
 export * from './cruiseProtocol';
 export * from './spotPolygonsProtocol';
 export * from './mcsRoomInfoProtocol';
+export * from './thresholdProtocol';

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

@@ -1,3 +1,4 @@
+export * from './base';
 export * from './scheduleProtocol';
 export * from './carpetProtocol';
 export * from './zoneCleanProtocol';
@@ -21,4 +22,5 @@ export * from './roomPropertyProtocol';
 export * from './purifierScheduleProtocol';
 export * from './cruiseProtocol';
 export * from './spotPolygonsProtocol';
-export * from './mcsRoomInfoProtocol';
+export * from './mcsRoomInfoProtocol';
+export * from './thresholdProtocol';

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"

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";