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

package/README.md

@@ -76,4 +76,26 @@ export default function Home() {
   );
 }
 
-```
+```
+
+## Custom Commands (extension point for customized firmware)
+
+Commands that only exist on a customized firmware fork do NOT belong in this library's built-in hooks. Declare, send and listen to them in your own repo:
+
+```typescript
+import { useCustomCommand, defineRobotCommand } from '@ray-js/robot-data-stream';
+
+// One-off send (any reqType; must be used within MqttProvider)
+const { sendCustomCommand } = useCustomCommand();
+await sendCustomCommand<Res>('peakValleyChargeQry');
+
+// Declarative: one file per command, returns { useSend, useResponse } shaped like built-in hooks
+export const peakValleyCharge = defineRobotCommand<Req, Res>({
+  reqType: 'peakValleyChargeSet',
+  responseType: 'peakValleyChargeQry',
+});
+```
+
+Key semantics: MQTT + LAN JSON socket channels only (no DP `command_trans`); reqType + taskId response matching (when firmware echoes taskId, concurrent same-reqType requests do not cross-wire; responses without taskId pass through, degrading to first-response matching in that case); `data`-envelope unwrapping and `success`/`errCode` normalization are handled by the library; built-in protocol payload/response types are exported from the package root for type reuse. No runtime validation, no loading/retry — same contract as built-in hooks.
+
+Full reference: `docs/reference/custom-commands.md`.

package/lib/api/p2pApi.d.ts

@@ -58,7 +58,9 @@ export default class P2pApi {
      * @param callback
      * @returns
      */
-    onP2pStreamPacketReceive: (callback: (...args: any[]) => void) => () => void;
+    onP2pStreamPacketReceive: (callback: {
+        (...args: any[]): void;
+    }) => () => void;
     /**
      * 开始下载文件
      * files : {"files":["filesname1", "filesname2", "filesname3" ]}
@@ -71,24 +73,32 @@ export default class P2pApi {
      * @param callback
      * @returns
      */
-    onDownloadProgressUpdate: (callback: (...args: any[]) => void) => () => void;
+    onDownloadProgressUpdate: (callback: {
+        (...args: any[]): void;
+    }) => () => void;
     /**
      * 注册多文件下载进度监听
      * @param callback
      * @returns
      */
-    onDownloadTotalProgressUpdate: (callback: (...args: any[]) => void) => () => void;
+    onDownloadTotalProgressUpdate: (callback: {
+        (...args: any[]): void;
+    }) => () => void;
     /**
      * 注册单文件下载进度完成监听
      * @param callback
      * @returns
      */
-    onFileDownloadComplete: (callback: (...args: any[]) => void) => () => void;
+    onFileDownloadComplete: (callback: {
+        (...args: any[]): void;
+    }) => () => void;
     /**
      * 注册设备因为其他异常断开连接的事件
      * @returns
      */
-    onSessionStatusChange: (callback: (...args: any[]) => void) => () => void;
+    onSessionStatusChange: (callback: {
+        (...args: any[]): void;
+    }) => () => void;
     /**
      * 取消进行下载
      * @returns

package/lib/api/sweeperP2p.d.ts

@@ -133,7 +133,7 @@ export declare class SweeperP2p extends P2pApi {
      * @param downloadType
      * 0: 下载断开 1: 持续下载
      */
-    startObserverSweeperDataByP2P: (downloadType: number, devId: string, onReceiveMapData: (data: string) => void, onReceivePathData: (data: string) => void, onReceiveAIPicData?: ((data: string) => void) | undefined, onReceiveAIPicHDData?: ((data: string) => void) | undefined, onReceiveWifiMapData?: ((data: string) => void) | undefined, onDefineStructuredMode?: ((isStructured: boolean) => void) | undefined) => Promise<void>;
+    startObserverSweeperDataByP2P: (downloadType: number, devId: string, onReceiveMapData: (data: string) => void, onReceivePathData: (data: string) => void, onReceiveAIPicData?: (data: string) => void, onReceiveAIPicHDData?: (data: string) => void, onReceiveWifiMapData?: (data: string) => void, onDefineStructuredMode?: (isStructured: boolean) => void) => Promise<void>;
     /**
      * 在下载过程中继续添加下载文件
      * @param files

package/lib/index.d.ts

@@ -1,15 +1,16 @@
 export * from './mqtt';
 export * from './mqtt/type/requestType';
+export { pointsToString, pickWaterFields } from './utils';
 type TOnLogger = (type: 'warn' | 'error' | 'info', data: string) => void;
 declare const useP2PDataStream: (devId: string, onReceiveMapData: (data: string) => void, onReceivePathData: (data: string) => void, opt?: {
-    logTag?: string | undefined;
-    enableCustomLog?: boolean | undefined;
-    onReceiveAIPicData?: ((data: string) => void) | undefined;
-    onReceiveAIPicHDData?: ((data: string) => void) | undefined;
-    onReceiveWifiMapData?: ((data: string) => void) | undefined;
-    onLogger?: TOnLogger | undefined;
-    onDefineStructuredMode?: ((isStructured: boolean) => void) | undefined;
-} | undefined) => {
+    logTag?: string;
+    enableCustomLog?: boolean;
+    onReceiveAIPicData?: (data: string) => void;
+    onReceiveAIPicHDData?: (data: string) => void;
+    onReceiveWifiMapData?: (data: string) => void;
+    onLogger?: TOnLogger;
+    onDefineStructuredMode?: (isStructured: boolean) => void;
+}) => {
     appendDownloadStreamDuringTask: (files: Array<string>, successCb?: () => void, failedCb?: () => void) => Promise<boolean> | void;
 };
 declare const StreamDataNotificationCenter: import("mitt").Emitter<Record<import("mitt").EventType, unknown>>;

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;

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

@@ -24,4 +24,9 @@ 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, };
+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

@@ -24,4 +24,13 @@ 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 };
+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';

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

@@ -1,3 +1,4 @@
+export * from './base';
 export * from './scheduleProtocol';
 export * from './carpetProtocol';
 export * from './zoneCleanProtocol';

package/lib/mqtt/useCarpet.js

@@ -78,7 +78,9 @@ export const useCarpet = () => {
           const sendData = pickBy(processedData, value => value !== undefined);
           sendStructuredMessage(CarpetEnum.update, {
             carpetInfo: sendData
-          }, resolve, error => reject(handleMqttError(error, 'Failed to update carpet')), CarpetEnum.update);
+          }, resolve, error => reject(handleMqttError(error, 'Failed to update carpet')), {
+            responseType: CarpetEnum.update
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to update carpet'));
         }
@@ -91,7 +93,9 @@ export const useCarpet = () => {
             carpetInfo: {
               ids: data.ids
             }
-          }, resolve, error => reject(handleMqttError(error, 'Failed to delete carpet')), CarpetEnum.delete);
+          }, resolve, error => reject(handleMqttError(error, 'Failed to delete carpet')), {
+            responseType: CarpetEnum.delete
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to delete carpet'));
         }
@@ -101,7 +105,9 @@ export const useCarpet = () => {
       let data = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
       return new Promise((resolve, reject) => {
         try {
-          sendStructuredMessage(CarpetEnum.query, data, resolve, error => reject(handleMqttError(error, 'Failed to query carpet')), CarpetEnum.query);
+          sendStructuredMessage(CarpetEnum.query, data, resolve, error => reject(handleMqttError(error, 'Failed to query carpet')), {
+            responseType: CarpetEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to query carpet'));
         }
@@ -121,7 +127,9 @@ export const useCarpet = () => {
             ids: carpetInfo.ids,
             type: carpetInfo.type
           };
-          sendStructuredMessage(CarpetEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set carpet')), CarpetEnum.query);
+          sendStructuredMessage(CarpetEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set carpet')), {
+            responseType: CarpetEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set carpet'));
         }

package/lib/mqtt/useCarpetClean.js

@@ -27,7 +27,9 @@ export const useCarpetClean = () => {
     requestCarpetClean: () => {
       return new Promise((resolve, reject) => {
         try {
-          sendStructuredMessage(CarpetCleanEnum.query, {}, resolve, error => reject(handleMqttError(error, 'Failed to request carpet clean')), CarpetCleanEnum.query);
+          sendStructuredMessage(CarpetCleanEnum.query, {}, resolve, error => reject(handleMqttError(error, 'Failed to request carpet clean')), {
+            responseType: CarpetCleanEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to request carpet clean'));
         }
@@ -38,7 +40,9 @@ export const useCarpetClean = () => {
         try {
           sendStructuredMessage(CarpetCleanEnum.set, {
             ids: data
-          }, resolve, error => reject(handleMqttError(error, 'Failed to set carpet clean')), CarpetCleanEnum.set);
+          }, resolve, error => reject(handleMqttError(error, 'Failed to set carpet clean')), {
+            responseType: CarpetCleanEnum.set
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set carpet clean'));
         }

package/lib/mqtt/useCruise.js

@@ -56,7 +56,9 @@ export const useCruise = () => {
             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
+          sendStructuredMessage(CruiseEnum.set, createCruisePayload(message), resolve, error => reject(handleMqttError(error, 'Failed to set cruise')), {
+            responseType: CruiseEnum.query
+          } // 响应类型是 query，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set cruise'));

package/lib/mqtt/useCustomCommand.d.ts

@@ -0,0 +1,39 @@
+import { BaseResponse } from './type/protocols/base';
+/**
+ * 自定义指令选项
+ */
+export interface CustomCommandOptions {
+    /**
+     * 响应匹配的事件名（reqType）。
+     * 缺省与下发 reqType 同名；set 类指令的回复走 qry 事件名、
+     * 或回复 reqType 与下发不同名（如 aiObjectIgnoreSet → aiObjectIgnoreRst）时必填。
+     */
+    responseType?: string;
+    /** 超时时间（毫秒），默认 10000 */
+    timeout?: number;
+    /** 协议版本号，默认 '1.0.0' */
+    version?: string;
+}
+/**
+ * 自定义指令发送函数类型
+ */
+export type TSendCustomCommand = <TRes extends BaseResponse = BaseResponse>(reqType: string, data?: Record<string, any>, options?: CustomCommandOptions) => Promise<TRes>;
+/**
+ * 自定义指令 Hook：在 MqttProvider 内任意组件使用，获得 sendCustomCommand。
+ *
+ * 与内置 hook 同一契约：返回 Promise 命令函数，loading / 重试 / toast 由业务侧自理。
+ * 走 MQTT + LAN JSON socket 双通道（复用 preferredChannel 策略）；
+ * DP command_trans 二进制路线不支持（useMqtt=false 时直接 reject）。
+ * 响应按 reqType + taskId 双匹配，同 reqType 并发下发不会互相串包。
+ *
+ * @example
+ * ```typescript
+ * const { sendCustomCommand } = useCustomCommand();
+ *
+ * // 下发查询并等待回复
+ * const res = await sendCustomCommand<PeakValleyResponse>('peakValleyChargeQry');
+ * ```
+ */
+export declare const useCustomCommand: () => {
+    sendCustomCommand: TSendCustomCommand;
+};

package/lib/mqtt/useCustomCommand.js

@@ -0,0 +1,45 @@
+// 自定义指令：不经过内置 hook 的任意 reqType 下发出口
+import { useCallback } from 'react';
+import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
+
+/**
+ * 自定义指令选项
+ */
+
+/**
+ * 自定义指令发送函数类型
+ */
+
+/**
+ * 自定义指令 Hook：在 MqttProvider 内任意组件使用，获得 sendCustomCommand。
+ *
+ * 与内置 hook 同一契约：返回 Promise 命令函数，loading / 重试 / toast 由业务侧自理。
+ * 走 MQTT + LAN JSON socket 双通道（复用 preferredChannel 策略）；
+ * DP command_trans 二进制路线不支持（useMqtt=false 时直接 reject）。
+ * 响应按 reqType + taskId 双匹配，同 reqType 并发下发不会互相串包。
+ *
+ * @example
+ * ```typescript
+ * const { sendCustomCommand } = useCustomCommand();
+ *
+ * // 下发查询并等待回复
+ * const res = await sendCustomCommand<PeakValleyResponse>('peakValleyChargeQry');
+ * ```
+ */
+export const useCustomCommand = () => {
+  const {
+    sendStructuredMessage
+  } = useStructuredMessage();
+  const sendCustomCommand = useCallback(function (reqType) {
+    let data = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    let options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    return new Promise((resolve, reject) => {
+      sendStructuredMessage(reqType, data,
+      // Promise 的 resolve 入参是 TRes 的超集（含 PromiseLike），收窄传给发送层
+      resolve, error => reject(handleMqttError(error, `Failed to send custom command ${reqType}`)), options);
+    });
+  }, [sendStructuredMessage]);
+  return {
+    sendCustomCommand
+  };
+};

package/lib/mqtt/useDeviceModel.js

@@ -36,7 +36,9 @@ export const useDeviceModel = () => {
         try {
           sendStructuredMessage(DeviceModelEnum.set, {
             modelInfos: data
-          }, resolve, error => reject(handleMqttError(error, 'Failed to set device model')), DeviceModelEnum.query);
+          }, resolve, error => reject(handleMqttError(error, 'Failed to set device model')), {
+            responseType: DeviceModelEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set device model'));
         }

package/lib/mqtt/useFurnitureModel.js

@@ -36,7 +36,9 @@ export const useFurnitureModel = () => {
         try {
           sendStructuredMessage(FurnitureModelEnum.set, {
             modelInfos: data
-          }, resolve, error => reject(handleMqttError(error, 'Failed to set furniture model')), FurnitureModelEnum.query);
+          }, resolve, error => reject(handleMqttError(error, 'Failed to set furniture model')), {
+            responseType: FurnitureModelEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set furniture model'));
         }

package/lib/mqtt/useHistoryMap.js

@@ -48,7 +48,9 @@ export const useHistoryMap = () => {
             if (useMqtt) {
               sendStructuredMessage(DeleteMapEnum.set, {
                 mapId
-              }, resolve, error => reject(handleMqttError(error, 'Failed to delete history map')), DeleteMapEnum.rst // 响应类型是 rst，不是 set
+              }, resolve, error => reject(handleMqttError(error, 'Failed to delete history map')), {
+                responseType: DeleteMapEnum.rst
+              } // 响应类型是 rst，不是 set
               );
               return;
             }
@@ -81,7 +83,9 @@ export const useHistoryMap = () => {
               urlLen: url.length
             };
             if (useMqtt) {
-              sendStructuredMessage(UseMapEnum.set, mapData, resolve, error => reject(handleMqttError(error, 'Failed to change current map')), UseMapEnum.query // 响应类型是 query，不是 set
+              sendStructuredMessage(UseMapEnum.set, mapData, resolve, error => reject(handleMqttError(error, 'Failed to change current map')), {
+                responseType: UseMapEnum.query
+              } // 响应类型是 query，不是 set
               );
               return;
             }
@@ -113,7 +117,9 @@ export const useHistoryMap = () => {
       return new Promise((resolve, reject) => {
         try {
           if (useMqtt) {
-            sendStructuredMessage(SaveCurrentMapEnum.set, data, resolve, error => reject(handleMqttError(error, 'Failed to save current map')), SaveCurrentMapEnum.query // 响应类型是 query，不是 set
+            sendStructuredMessage(SaveCurrentMapEnum.set, data, resolve, error => reject(handleMqttError(error, 'Failed to save current map')), {
+              responseType: SaveCurrentMapEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/usePartDivision.js

@@ -36,7 +36,9 @@ export const usePartDivision = () => {
             sendStructuredMessage(PartDivisionEnum.set, {
               lines: [pointStr],
               ids: [roomId]
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set part division')), PartDivisionEnum.query);
+            }, resolve, error => reject(handleMqttError(error, 'Failed to set part division')), {
+              responseType: PartDivisionEnum.query
+            });
             return;
           }
           const roomIdNumber = typeof roomId === 'string' ? Number(roomId) : roomId;

package/lib/mqtt/usePartMerge.js

@@ -31,7 +31,9 @@ export const usePartMerge = () => {
           if (useMqtt) {
             sendStructuredMessage(PartMergeEnum.set, {
               ids
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set part merge')), PartMergeEnum.query // 响应类型是 query，不是 set
+            }, resolve, error => reject(handleMqttError(error, 'Failed to set part merge')), {
+              responseType: PartMergeEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/usePassword.js

@@ -64,7 +64,9 @@ export const usePassword = () => {
             oldPassword: params.oldPassword ? md5(params.oldPassword).toString() : undefined,
             taskId: (_params$taskId = params.taskId) !== null && _params$taskId !== void 0 ? _params$taskId : String(Date.now())
           };
-          sendStructuredMessage(PasswordEnum.set, passwordData, resolve, error => reject(handleMqttError(error, 'Failed to set password')), PasswordEnum.rst // 响应类型是 rst，不是 set
+          sendStructuredMessage(PasswordEnum.set, passwordData, resolve, error => reject(handleMqttError(error, 'Failed to set password')), {
+            responseType: PasswordEnum.rst
+          } // 响应类型是 rst，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set password'));
@@ -86,7 +88,9 @@ export const usePassword = () => {
             password: md5(params.password).toString(),
             taskId: (_params$taskId2 = params.taskId) !== null && _params$taskId2 !== void 0 ? _params$taskId2 : String(Date.now())
           };
-          sendStructuredMessage(PasswordEnum.check, passwordData, resolve, error => reject(handleMqttError(error, 'Failed to check password')), PasswordEnum.checkRst // 响应类型是 checkRst，不是 check
+          sendStructuredMessage(PasswordEnum.check, passwordData, resolve, error => reject(handleMqttError(error, 'Failed to check password')), {
+            responseType: PasswordEnum.checkRst
+          } // 响应类型是 checkRst，不是 check
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to check password'));

package/lib/mqtt/usePurifierSchedule.js

@@ -55,7 +55,9 @@ export const usePurifierSchedule = () => {
           }
           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
+          }), resolve, error => reject(handleMqttError(error, 'Failed to set purifier schedule')), {
+            responseType: PurifierScheduleEnum.query
+          } // 响应类型是 query，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set purifier schedule'));

package/lib/mqtt/useQuiteHours.js

@@ -52,7 +52,9 @@ export const useQuiteHours = () => {
               time: [`${h0},${m0}`, `${h1},${m1}`],
               active,
               day
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set quiet hours')), QuietHoursEnum.query // 响应类型是 query，不是 set
+            }, resolve, error => reject(handleMqttError(error, 'Failed to set quiet hours')), {
+              responseType: QuietHoursEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useResetMap.js

@@ -28,7 +28,9 @@ export const useResetMap = () => {
       return new Promise((resolve, reject) => {
         try {
           if (useMqtt) {
-            sendStructuredMessage(ResetCurrMapEnum.set, {}, resolve, error => reject(handleMqttError(error, 'Failed to reset map')), ResetCurrMapEnum.query // 响应类型是 query，不是 set
+            sendStructuredMessage(ResetCurrMapEnum.set, {}, resolve, error => reject(handleMqttError(error, 'Failed to reset map')), {
+              responseType: ResetCurrMapEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useRoomProperty.js

@@ -73,7 +73,9 @@ export const useRoomProperty = () => {
           }), 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
+          sendStructuredMessage(RoomPropertyEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set room property')), {
+            responseType: RoomPropertyEnum.query
+          } // 响应类型是 query，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set room property'));

package/lib/mqtt/useSchedule.js

@@ -65,7 +65,9 @@ export const useSchedule = () => {
           if (useMqtt) {
             sendStructuredMessage(ScheduleEnum.set, _objectSpread(_objectSpread({}, message), {}, {
               list
-            }), resolve, error => reject(handleMqttError(error, 'Failed to set schedule')), ScheduleEnum.query // 响应类型是 query，不是 set
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set schedule')), {
+              responseType: ScheduleEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useSelectRoomClean.js

@@ -107,7 +107,9 @@ export const useSelectRoomClean = () => {
               routePreferences: prefs.map(p => p !== null && p !== void 0 ? p : 'standard')
             }), {}, {
               num: rooms.length
-            }), resolve, error => reject(handleMqttError(error, 'Failed to set room clean')), RoomCleanSetEnum.query // 响应类型是 query，不是 set
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set room clean')), {
+              responseType: RoomCleanSetEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useSpotClean.js

@@ -80,7 +80,9 @@ export const useSpotClean = () => {
               names
             }), spotNames && {
               spotNames
-            }), resolve, error => reject(handleMqttError(error, 'Failed to set spot clean')), SpotCleanEnum.query // 响应类型是 query，不是 set
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set spot clean')), {
+              responseType: SpotCleanEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useSpotPolygons.js

@@ -38,7 +38,9 @@ export const useSpotPolygons = () => {
             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);
+          sendStructuredMessage(SpotPolygonsEnum.set, createSpotPolygonsPayload(message), resolve, error => reject(handleMqttError(error, 'Failed to set spot polygons')), {
+            responseType: SpotPolygonsEnum.query
+          });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set spot polygons'));
         }

package/lib/mqtt/useThreshold.js

@@ -77,7 +77,9 @@ export const useThreshold = () => {
             polygons,
             types,
             names
-          }, resolve, error => reject(handleMqttError(error, 'Failed to set threshold')), ThresholdEnum.query // 响应类型是 query，不是 set
+          }, resolve, error => reject(handleMqttError(error, 'Failed to set threshold')), {
+            responseType: ThresholdEnum.query
+          } // 响应类型是 query，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set threshold'));

package/lib/mqtt/useVirtualArea.js

@@ -96,7 +96,9 @@ export const useVirtualArea = () => {
               num: data.length,
               modes: modes,
               names: names
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set virtual area')), VirtualAreaEnum.query // 响应类型是 query，不是 set
+            }, resolve, error => reject(handleMqttError(error, 'Failed to set virtual area')), {
+              responseType: VirtualAreaEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useVirtualWall.js

@@ -77,7 +77,9 @@ export const useVirtualWall = () => {
               points: data.map(points => pointsToString(points, origin)),
               num: data.length,
               mode: new Array(data.length).fill('0')
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set virtual wall')), VirtualWallEnum.query // 响应类型是 query，不是 set
+            }, resolve, error => reject(handleMqttError(error, 'Failed to set virtual wall')), {
+              responseType: VirtualWallEnum.query
+            } // 响应类型是 query，不是 set
             );
             return;
           }

package/lib/mqtt/useVoice.js

@@ -71,7 +71,9 @@ export const useVoice = () => {
             const sendData = _objectSpread(_objectSpread({}, message), {}, {
               urlLen: message.url.length
             });
-            sendStructuredMessage(VoiceLanguageEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set voice')), VoiceLanguageEnum.query);
+            sendStructuredMessage(VoiceLanguageEnum.set, sendData, resolve, error => reject(handleMqttError(error, 'Failed to set voice')), {
+              responseType: VoiceLanguageEnum.query
+            });
             return;
           }
 

package/lib/mqtt/useWifiMap.js

@@ -41,7 +41,9 @@ export const useWifiMap = () => {
             taskId: data.taskId || String(Date.now()),
             switch: (_data$switch = data.switch) !== null && _data$switch !== void 0 ? _data$switch : true
           };
-          sendStructuredMessage(WifiMapEnum.set, wifiMapData, resolve, error => reject(handleMqttError(error, 'Failed to set WiFi map')), WifiMapEnum.rst // 响应类型是 rst，不是 set
+          sendStructuredMessage(WifiMapEnum.set, wifiMapData, resolve, error => reject(handleMqttError(error, 'Failed to set WiFi map')), {
+            responseType: WifiMapEnum.rst
+          } // 响应类型是 rst，不是 set
           );
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set WiFi map'));

package/lib/mqtt/useZoneClean.js

@@ -131,7 +131,9 @@ export const useZoneClean = () => {
               polygons
             }, commonFields), {}, {
               names
-            }), resolve, error => reject(handleMqttError(error, 'Failed to set zone clean')), ZoneCleanEnum.query);
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set zone clean')), {
+              responseType: ZoneCleanEnum.query
+            });
             return;
           }
 

package/lib/utils/index.d.ts

@@ -6,27 +6,27 @@ export declare const emitter: import("mitt").Emitter<Record<import("mitt").Event
 export declare const pointsToString: (points: Point[], origin?: Point) => string;
 export declare const isJSONString: (str: any) => boolean;
 export declare const parseJSON: (str: any) => any;
-export declare const logger: (type: 'warn' | 'error' | 'info', params: {
-    [key: string]: any;
+export declare const logger: (type: "warn" | "error" | "info", params: {
     msg: string;
-}, onLogger?: ((type: 'warn' | 'error' | 'info', v: string) => void) | undefined) => void;
+    [key: string]: any;
+}, onLogger?: (type: "warn" | "error" | "info", v: string) => void) => void;
 /**
  * 创建绑定了 onLogger 的 logger 函数
  * @param onLogger - 可选的日志回调函数
  * @returns 返回一个简化的 logger 函数
  */
-export declare const createLogger: (onLogger?: ((type: 'warn' | 'error' | 'info', v: string) => void) | undefined) => {
+export declare const createLogger: (onLogger?: (type: "warn" | "error" | "info", v: string) => void) => {
     info: (params: {
-        [key: string]: any;
         msg: string;
+        [key: string]: any;
     }) => void;
     warn: (params: {
-        [key: string]: any;
         msg: string;
+        [key: string]: any;
     }) => void;
     error: (params: {
-        [key: string]: any;
         msg: string;
+        [key: string]: any;
     }) => void;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/robot-data-stream",
-  "version": "0.0.17-beta.10",
+  "version": "0.0.17-beta.12",
   "description": "扫地机P2P数据流标准化组件",
   "main": "lib/index",
   "files": [
@@ -17,6 +17,8 @@
   ],
   "scripts": {
     "lint": "eslint src --ext .js,.jsx,.ts,.tsx --fix",
+    "test": "vitest --run",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
     "build": "patch-package && ray build --type=component",
     "watch": "ray start --type=component --output ./example/src/lib",
     "build:tuya": "ray build ./example",
@@ -63,6 +65,8 @@
     "patch-package": "^8.0.0",
     "prettier": "^3.8.0",
     "standard-version": "9.3.2",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.4",
     "vitepress": "^1.6.4"
   },
   "husky": {