@thejrsoft/subway-protocol 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## [1.6.1] - 2026-05-13
+
+### Added (零破坏，向后兼容)
+
+- `EXPLICIT_META` 新增 2 个终态 code：`EDGE_COMMAND_REJECTED` / `EDGE_PROGRAM_REJECTED`
+- 用于 Edge 代理层合成终态消息（设备未响应时合成 "as-if device error response"）
+- 失败具体原因通过 `data.error.{phase, step, category, detail}` 表达
+
+### Migration
+
+Edge `edge-proxy.manager.ts` 中 9 处错误响应合成调用迁移到 `dispatchMessage`：
+
+```typescript
+// Before (v1.6.0 旧 Factory 调用)
+MessageFactory.createCommandResponseMessage(
+  edgeId, requestRef, MessageStatus.FAILED, { error: '...' }
+);
+
+// After (v1.6.1 推荐)
+MessageFactory.dispatchMessage({
+  clientId: edgeId, requestRef,
+  code: 'EDGE_COMMAND_REJECTED',
+  message: '...',
+  error: { phase: 'BATCH_EXECUTE', step: '...', category: 'TRANSPORT', detail: '...' },
+});
+```
+
+---
+
+## [1.6.0] - 2026-05-13
+
+### ⚠️ BREAKING CHANGES — 硬切，零兼容（系统未上线）
+
+#### 1. CodeMeta 单一信息源 — status / level 由 report.code 派生
+
+新设计：所有协议消息的 `status` 和 `level` 字段由 `report.code` 通过 `CodeMeta` 表自动派生。
+集成方收到消息后调用 `resolveCodeMeta(code)` 查表得到 `semantic` / `requiresErrorBlock` 等元数据。
+
+```typescript
+import { resolveCodeMeta } from '@thejrsoft/subway-protocol';
+
+const meta = resolveCodeMeta(msg.report.code);
+// meta: { isTerminal, status, level, semantic, requiresErrorBlock }
+switch (meta.semantic) {
+  case 'success': /* ALL_SUCCESS / ALL_ONLINE 等 */ break;
+  case 'partial': /* PARTIAL_SUCCESS / PARTIAL_ONLINE */ break;
+  case 'failure': /* ALL_FAILED / UPLOAD_FAILED */    break;
+  case 'busy':    /* BUSY 并发拒绝 */                break;
+  case 'cancel':  /* CANCELLED */                    break;
+  case 'no-op':   /* NO_PROGRAMS */                  break;
+  // 进度语义: phase_start / phase_end / phase_failed / step_success ...
+}
+```
+
+#### 2. MessageStatus 单一 enum 取代 CommandStatus / ProgressStatus
+
+```typescript
+// v1.5.0 (已删)
+enum CommandStatus  { COMPLETED, FAILED, TIMEOUT, CANCELLED, IN_PROGRESS }  ← 删
+enum ProgressStatus { PENDING, IN_PROGRESS, PAUSED, COMPLETED, FAILED, CANCELLED } ← 删
+
+// v1.6.0 (新)
+enum MessageStatus { IN_PROGRESS, COMPLETED, FAILED, CANCELLED }
+```
+
+**删除的死代码值**:
+- `ProgressStatus.PENDING` / `PAUSED`（v1.5.0 内 0 引用）
+- `CommandStatus.TIMEOUT` 语义迁移到 `status=FAILED + data.error.category='TIMEOUT'`
+
+#### 3. dispatchMessage 统一发消息接口
+
+替代旧 `MessageFactory.createCommandResponseMessage` / `createProgramResponseMessage` /
+`createProgressUpdateMessage`：
+
+```typescript
+MessageFactory.dispatchMessage({
+  clientId, requestRef,
+  code: 'PROGRAM_COMPLETED',  // 单一信息源
+  message: 'Program upload completed',
+  data: { totalPrograms: 5, successCount: 5 },
+  // status / level / 消息类型由 CodeMeta 自动推导
+});
+```
+
+设备端只填 `code` 和业务字段，违反 META 决策矩阵的风险归零。
+
+#### 4. 拆分歧义 code — 一码一义原则
+
+`PROGRAM_UPLOAD_FAILED` v1.5.0 既表 FAILED 又表 BUSY → v1.6.0 拆分：
+- `PROGRAM_UPLOAD_FAILED`：仅表异常中断（status=FAILED + level=ERROR）
+- `PROGRAM_UPLOAD_BUSY`：独立 code，表并发拒绝（status=FAILED + level=WARNING）
+
+### 新增
+
+- `MessageStatus` enum（4 值）
+- `CodeMeta` interface（5 字段）
+- `CodeSemantic` 联合类型（15 值，覆盖终态 + 进度）
+- `EXPLICIT_META` 终态显式表（~14 entries）
+- `SUFFIX_RULES` 进度后缀规则（9 条）
+- `resolveCodeMeta(code)` / `isKnownCode(code)` 工具函数
+- `MessageFactory.dispatchMessage(params)` 统一发消息接口
+
+### 删除
+
+- ✂️ `enum CommandStatus`（v1.5.0 5 值）
+- ✂️ `enum ProgressStatus`（v1.5.0 6 值）
+- ✂️ `CommandStatus.TIMEOUT`（合并到 data.error.category）
+- ✂️ `ProgressStatus.PENDING` / `PAUSED`（0 引用死代码）
+
+### Migration
+
+```typescript
+// v1.5.0
+import { CommandStatus, ProgressStatus, MessageFactory } from '@thejrsoft/subway-protocol';
+const msg = MessageFactory.createCommandResponseMessage(
+  clientId, requestRef, CommandStatus.COMPLETED, result, message,
+);
+
+// v1.6.0
+import { MessageStatus, MessageFactory } from '@thejrsoft/subway-protocol';
+const msg = MessageFactory.dispatchMessage({
+  clientId, requestRef,
+  code: 'SYNC_FUNCTIONS_SWITCH_WRITE_SUCCESS',  // 单一信息源
+  message: 'Switch set to On',
+  result,
+});
+// status (COMPLETED) + level (INFO) 自动从 code 派生
+```
+
+### 协议设计依据
+
+完整设计原则、决策回放（CodeMeta 设计奇点、status 合并理由、为什么 semantic 不进消息等）
+见 `claude-docs/protocol-upgrade-proposal-v1.6.0.md`。
+
+---
+
 ## [1.5.0] - 2026-05-12
 
 ### ⚠️ BREAKING CHANGES — 无兼容、无 fallback（系统未上线）

package/dist/asyncapi-sync.js

@@ -15,7 +15,7 @@ function generateAsyncApiEnums() {
         ClientType: Object.values(index_1.ClientType),
         OperationType: Object.values(index_1.OperationType),
         Priority: Object.values(index_1.Priority),
-        CommandStatus: Object.values(index_1.CommandStatus)
+        MessageStatus: Object.values(index_1.MessageStatus)
     };
     return `
 # AsyncAPI Enum Definitions
@@ -39,9 +39,9 @@ components:
       type: string
       enum: ${JSON.stringify(enums.Priority)}
     
-    CommandStatus:
+    MessageStatus:
       type: string
-      enum: ${JSON.stringify(enums.CommandStatus)}
+      enum: ${JSON.stringify(enums.MessageStatus)}
   `;
 }
 /**

package/dist/code-meta.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CodeMeta — v1.6.0 协议核心
+ *
+ * report.code 是业务命运的单一信息源；status / level / semantic 全部由此派生。
+ *
+ * 设备端调用 dispatchMessage(code, data) 时，协议层自动按 code 推导 status / level，
+ * 集成方接收消息后调用 resolveCodeMeta(code) 查表得到 semantic / requiresErrorBlock 等。
+ *
+ * 设计依据：claude-docs/protocol-upgrade-proposal-v1.6.0.md
+ */
+import type { ReportLevel } from './index';
+/** v1.6.0：单一 status enum，合并 v1.5.0 的 CommandStatus + ProgressStatus */
+export declare enum MessageStatus {
+    IN_PROGRESS = "IN_PROGRESS",
+    COMPLETED = "COMPLETED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED"
+}
+/** 业务语义分类——终态语义 + 进度语义 */
+export type CodeSemantic = 'success' | 'partial' | 'failure' | 'no-op' | 'cancel' | 'busy' | 'phase_start' | 'phase_end' | 'phase_failed' | 'step_success' | 'step_skipped' | 'step_progress' | 'retry' | 'retry_pending' | 'warning';
+/**
+ * 单一 code 的元数据描述符
+ *
+ * 派生字段（status / level）会序列化进消息；
+ * 客户端字段（semantic / requiresErrorBlock / isTerminal）仅供查表，不进消息。
+ */
+export interface CodeMeta {
+    isTerminal: boolean;
+    status: MessageStatus;
+    level: ReportLevel;
+    semantic: CodeSemantic;
+    requiresErrorBlock: boolean;
+}
+/**
+ * 终态 code 显式 META 表
+ *
+ * 这些 code 是业务命运决断点，每个语义都是独特的，**不能用后缀规则推导**。
+ * 设备端发送终态消息时，dispatchMessage 在此表查询，自动填充消息字段。
+ */
+export declare const EXPLICIT_META: Record<string, CodeMeta>;
+/**
+ * 单一 code 解析入口
+ *
+ * 解析顺序：
+ *   1. 终态显式表（EXPLICIT_META） — 30 个 closed enum
+ *   2. 后缀规则（SUFFIX_RULES） — 9 条规则覆盖数百个进度 code
+ *   3. 兜底（FALLBACK_META） — 未知 code 降级
+ *
+ * @param code report.code 字符串
+ * @returns CodeMeta — status / level / semantic / requiresErrorBlock / isTerminal
+ */
+export declare function resolveCodeMeta(code: string): CodeMeta;
+/**
+ * 判断 code 是否已知（命中显式表或后缀规则，不走兜底）
+ */
+export declare function isKnownCode(code: string): boolean;
+//# sourceMappingURL=code-meta.d.ts.map

package/dist/code-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-meta.d.ts","sourceRoot":"","sources":["../src/code-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,uEAAuE;AACvE,oBAAY,aAAa;IACvB,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,0BAA0B;AAC1B,MAAM,MAAM,YAAY,GAEpB,SAAS,GACT,SAAS,GACT,SAAS,GACT,OAAO,GACP,QAAQ,GACR,MAAM,GAEN,aAAa,GACb,WAAW,GACX,cAAc,GACd,cAAc,GACd,cAAc,GACd,eAAe,GACf,OAAO,GACP,eAAe,GACf,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA2HlD,CAAC;AAoHF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAatD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD"}

package/dist/code-meta.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * CodeMeta — v1.6.0 协议核心
+ *
+ * report.code 是业务命运的单一信息源；status / level / semantic 全部由此派生。
+ *
+ * 设备端调用 dispatchMessage(code, data) 时，协议层自动按 code 推导 status / level，
+ * 集成方接收消息后调用 resolveCodeMeta(code) 查表得到 semantic / requiresErrorBlock 等。
+ *
+ * 设计依据：claude-docs/protocol-upgrade-proposal-v1.6.0.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLICIT_META = exports.MessageStatus = void 0;
+exports.resolveCodeMeta = resolveCodeMeta;
+exports.isKnownCode = isKnownCode;
+/** v1.6.0：单一 status enum，合并 v1.5.0 的 CommandStatus + ProgressStatus */
+var MessageStatus;
+(function (MessageStatus) {
+    MessageStatus["IN_PROGRESS"] = "IN_PROGRESS";
+    MessageStatus["COMPLETED"] = "COMPLETED";
+    MessageStatus["FAILED"] = "FAILED";
+    MessageStatus["CANCELLED"] = "CANCELLED";
+})(MessageStatus || (exports.MessageStatus = MessageStatus = {}));
+/**
+ * 终态 code 显式 META 表
+ *
+ * 这些 code 是业务命运决断点，每个语义都是独特的，**不能用后缀规则推导**。
+ * 设备端发送终态消息时，dispatchMessage 在此表查询，自动填充消息字段。
+ */
+exports.EXPLICIT_META = {
+    // ═══════════ PROGRAM 节目部署 ═══════════
+    PROGRAM_COMPLETED: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'INFO',
+        semantic: 'success',
+        requiresErrorBlock: false,
+    },
+    PROGRAM_PARTIALLY_SUCCEEDED: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'WARNING',
+        semantic: 'partial',
+        requiresErrorBlock: false,
+    },
+    PROGRAM_ALL_FAILED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    PROGRAM_NO_PROGRAMS: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'INFO',
+        semantic: 'no-op',
+        requiresErrorBlock: false,
+    },
+    PROGRAM_UPLOAD_FAILED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    PROGRAM_UPLOAD_BUSY: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'WARNING',
+        semantic: 'busy',
+        requiresErrorBlock: true,
+    },
+    PROGRAM_UPLOAD_CANCELLED: {
+        isTerminal: true,
+        status: MessageStatus.CANCELLED,
+        level: 'WARNING',
+        semantic: 'cancel',
+        requiresErrorBlock: true,
+    },
+    // ═══════════ QUICKLY_DETECTION 一键检测 ═══════════
+    QUICK_DETECTION_ALL_ONLINE: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'INFO',
+        semantic: 'success',
+        requiresErrorBlock: false,
+    },
+    QUICK_DETECTION_PARTIAL_ONLINE: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'WARNING',
+        semantic: 'partial',
+        requiresErrorBlock: false,
+    },
+    QUICK_DETECTION_ALL_OFFLINE: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    QUICK_DETECTION_FAILED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    QUICK_DETECTION_BUSY: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'WARNING',
+        semantic: 'busy',
+        requiresErrorBlock: true,
+    },
+    // ═══════════ SYNC_MONITORING_TABLE 监播导出 ═══════════
+    SYNC_MONITORING_TABLE_READ_SUCCESS: {
+        isTerminal: true,
+        status: MessageStatus.COMPLETED,
+        level: 'INFO',
+        semantic: 'success',
+        requiresErrorBlock: false,
+    },
+    SYNC_MONITORING_TABLE_READ_FAILED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    // ═══════════ EDGE 代理层合成的终态拒绝 ═══════════
+    // 当 Edge 在转发命令到设备的过程中失败（设备不在线、命令格式错、转发失败等），
+    // Edge 合成一个终态消息发回 Gateway 让命令生命周期闭环。
+    // 具体失败原因通过 data.error.{phase, step, category, detail} 表达。
+    EDGE_COMMAND_REJECTED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+    EDGE_PROGRAM_REJECTED: {
+        isTerminal: true,
+        status: MessageStatus.FAILED,
+        level: 'ERROR',
+        semantic: 'failure',
+        requiresErrorBlock: true,
+    },
+};
+const SUFFIX_RULES = [
+    {
+        suffix: '_FAILED',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'ERROR',
+            semantic: 'phase_failed',
+            requiresErrorBlock: true,
+        },
+    },
+    {
+        suffix: '_RETRY_PENDING',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'WARNING',
+            semantic: 'retry_pending',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_RETRY',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'WARNING',
+            semantic: 'retry',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        // 后缀或中缀都命中：例 PROGRAM_UPLOAD_WARN_CAN_BUS_ALARM
+        infix: '_WARN',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'WARNING',
+            semantic: 'warning',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_SKIPPED',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'INFO',
+            semantic: 'step_skipped',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_COMPLETED',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'INFO',
+            semantic: 'phase_end',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_START',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'INFO',
+            semantic: 'phase_start',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_PROGRESS',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'INFO',
+            semantic: 'step_progress',
+            requiresErrorBlock: false,
+        },
+    },
+    {
+        suffix: '_SUCCESS',
+        meta: {
+            status: MessageStatus.IN_PROGRESS,
+            level: 'INFO',
+            semantic: 'step_success',
+            requiresErrorBlock: false,
+        },
+    },
+];
+/**
+ * 兜底 META（未知 code 时返回）
+ *
+ * 接收方收到未知 code 时降级到 step_progress，避免阻塞协议处理。
+ */
+const FALLBACK_META = {
+    isTerminal: false,
+    status: MessageStatus.IN_PROGRESS,
+    level: 'INFO',
+    semantic: 'step_progress',
+    requiresErrorBlock: false,
+};
+/**
+ * 单一 code 解析入口
+ *
+ * 解析顺序：
+ *   1. 终态显式表（EXPLICIT_META） — 30 个 closed enum
+ *   2. 后缀规则（SUFFIX_RULES） — 9 条规则覆盖数百个进度 code
+ *   3. 兜底（FALLBACK_META） — 未知 code 降级
+ *
+ * @param code report.code 字符串
+ * @returns CodeMeta — status / level / semantic / requiresErrorBlock / isTerminal
+ */
+function resolveCodeMeta(code) {
+    if (exports.EXPLICIT_META[code]) {
+        return exports.EXPLICIT_META[code];
+    }
+    for (const rule of SUFFIX_RULES) {
+        if (rule.suffix && code.endsWith(rule.suffix)) {
+            return { isTerminal: false, ...rule.meta };
+        }
+        if (rule.infix && code.includes(rule.infix)) {
+            return { isTerminal: false, ...rule.meta };
+        }
+    }
+    return FALLBACK_META;
+}
+/**
+ * 判断 code 是否已知（命中显式表或后缀规则，不走兜底）
+ */
+function isKnownCode(code) {
+    if (exports.EXPLICIT_META[code])
+        return true;
+    for (const rule of SUFFIX_RULES) {
+        if (rule.suffix && code.endsWith(rule.suffix))
+            return true;
+        if (rule.infix && code.includes(rule.infix))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=code-meta.js.map

package/dist/code-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-meta.js","sourceRoot":"","sources":["../src/code-meta.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,7 +6,10 @@
  * 1. 统一消息格式定义
  * 2. 支持设备注册、命令执行、心跳等核心功能
  * 3. 支持 Edge 代理模式
+ *
+ * v1.6.0：单一 MessageStatus + CodeMeta + dispatchMessage（详见 code-meta.ts）
  */
+import { MessageStatus } from './code-meta';
 export declare enum MessageType {
     REGISTER = "REGISTER",
     REGISTER_ACK = "REGISTER_ACK",
@@ -48,13 +51,7 @@ export declare enum Priority {
     CRITICAL = "CRITICAL",
     EMERGENCY = "EMERGENCY"
 }
-export declare enum CommandStatus {
-    COMPLETED = "COMPLETED",
-    FAILED = "FAILED",
-    TIMEOUT = "TIMEOUT",
-    CANCELLED = "CANCELLED",
-    IN_PROGRESS = "IN_PROGRESS"
-}
+export { MessageStatus, type CodeMeta, type CodeSemantic, resolveCodeMeta, isKnownCode, EXPLICIT_META } from './code-meta';
 export interface BaseMessage {
     type: MessageType;
     timestamp: string;
@@ -212,7 +209,7 @@ export interface CommandResponseMessage extends BaseMessage {
     type: MessageType.COMMAND_RESPONSE;
     clientId: string;
     requestRef: string;
-    status: CommandStatus;
+    status: MessageStatus;
     result?: CommandResult;
     report?: ReportMessage;
     executionTime?: number;
@@ -288,7 +285,7 @@ export interface ProgramResponseMessage extends BaseMessage {
     type: MessageType.PROGRAM_RESPONSE;
     clientId: string;
     requestRef: string;
-    status: CommandStatus;
+    status: MessageStatus;
     context?: ProgramContext;
     report?: ReportMessage;
     executionTime?: number;
@@ -338,14 +335,6 @@ export interface DeviceOperationRecord {
     operationType: OperationType;
     result?: Record<string, any>;
 }
-export declare enum ProgressStatus {
-    PENDING = "PENDING",
-    IN_PROGRESS = "IN_PROGRESS",
-    PAUSED = "PAUSED",
-    COMPLETED = "COMPLETED",
-    FAILED = "FAILED",
-    CANCELLED = "CANCELLED"
-}
 export interface ProgramContext {
     taskId: string;
     programId: string;
@@ -361,8 +350,8 @@ export declare enum ReportLevel {
     CRITICAL = "CRITICAL"
 }
 export type ErrorCategory = 'TRANSPORT' | 'TIMEOUT' | 'RESOURCE' | 'BUSINESS' | 'CONFIGURATION' | 'PROTOCOL' | 'AUTHORIZATION';
-export type ErrorPhase = 'PROGRAM_INIT' | 'PROGRAM_FETCH' | 'PROGRAM_EXTRACT' | 'PROGRAM_PREPROCESS' | 'PROGRAM_COMPILE' | 'PROGRAM_UPLOAD' | 'PROGRAM_STATS' | 'PROGRAM_COMPLETE' | 'DETECT_INIT' | 'SWITCH_DETECT' | 'SWITCH_CONFIG_READ' | 'SYNC_DETECT' | 'BARGRAPH_DETECT' | 'RATER_DETECT' | 'SYNC_RECOVER' | 'DETECT_COMPLETE' | 'SYNC_EXPORT' | 'BATCH_EXECUTE';
-export type ErrorStep = 'ValidateParameters' | 'PrepareResources' | 'LoadConfig' | 'CheckConcurrency' | 'Download' | 'VerifyChecksum' | 'ExtractZip' | 'ResizeImage' | 'AdjustColor' | 'GammaCorrect' | 'Histogram' | 'RGBCorrection' | 'CompileFrame' | 'MoveFrame' | 'VerifyFrameCount' | 'DeviceCheck' | 'DataTransfer' | 'ForbiddenTable' | 'StatusRecovery' | 'RetryLimitExceeded' | 'CloudReport';
+export type ErrorPhase = 'PROGRAM_INIT' | 'PROGRAM_FETCH' | 'PROGRAM_EXTRACT' | 'PROGRAM_PREPROCESS' | 'PROGRAM_COMPILE' | 'PROGRAM_UPLOAD' | 'PROGRAM_STATS' | 'PROGRAM_COMPLETE' | 'DETECT_INIT' | 'SWITCH_DETECT' | 'SWITCH_CONFIG_READ' | 'SYNC_DETECT' | 'BARGRAPH_DETECT' | 'RATER_DETECT' | 'SYNC_RECOVER' | 'DETECT_COMPLETE' | 'SYNC_EXPORT' | 'BATCH_EXECUTE' | 'EDGE_PROXY';
+export type ErrorStep = 'ValidateParameters' | 'PrepareResources' | 'LoadConfig' | 'CheckConcurrency' | 'Download' | 'VerifyChecksum' | 'ExtractZip' | 'ResizeImage' | 'AdjustColor' | 'GammaCorrect' | 'Histogram' | 'RGBCorrection' | 'CompileFrame' | 'MoveFrame' | 'VerifyFrameCount' | 'DeviceCheck' | 'DataTransfer' | 'ForbiddenTable' | 'StatusRecovery' | 'RetryLimitExceeded' | 'CloudReport' | 'ValidateCommandFormat' | 'CheckDeviceOnline' | 'DispatchToDevice' | 'AwaitDeviceResponse';
 export interface ErrorInfo {
     phase: ErrorPhase;
     step: ErrorStep;
@@ -384,7 +373,7 @@ export interface ProgressUpdateMessage extends BaseMessage {
     type: MessageType.PROGRESS_UPDATE;
     clientId: string;
     requestRef: string;
-    status: ProgressStatus;
+    status: MessageStatus;
     phase: ProgressPhase | string;
     progress: number;
     sourceType: ProgressSourceType;
@@ -474,7 +463,7 @@ export declare class MessageFactory {
      * 创建进度更新消息
      */
     static createProgressUpdateMessage(clientId: string, // 添加：上报设备标识
-    requestRef: string, phase: ProgressPhase | string, progress: number, message?: string, status?: ProgressStatus, options?: {
+    requestRef: string, phase: ProgressPhase | string, progress: number, message?: string, status?: MessageStatus, options?: {
         level?: ReportLevel;
         code?: string;
         data?: Record<string, any>;
@@ -485,7 +474,7 @@ export declare class MessageFactory {
      * 创建命令响应消息 (Backend 急需)
      */
     static createCommandResponseMessage(clientId: string, // 添加：响应设备标识
-    requestRef: string, status: CommandStatus, result: any, message?: string, options?: {
+    requestRef: string, status: MessageStatus, result: any, message?: string, options?: {
         executionTime?: number;
         report?: ReportMessage;
         version?: string;
@@ -495,7 +484,7 @@ export declare class MessageFactory {
      * 创建程序响应消息
      */
     static createProgramResponseMessage(clientId: string, // 添加：响应设备标识
-    requestRef: string, status: CommandStatus, result: any, message?: string, options?: {
+    requestRef: string, status: MessageStatus, result: any, message?: string, options?: {
         executionTime?: number;
         programStartTime?: number;
     }): ProgramResponseMessage;
@@ -542,9 +531,47 @@ export declare class MessageFactory {
      */
     static createUpdateRoutesAckMessage(clientId: string, // 改为 clientId，统一命名
     success: boolean, message?: string, routeCount?: number): UpdateRoutesAckMessage;
+    /**
+     * v1.6.0: 统一消息派发接口
+     *
+     * 设备端发送终态消息（COMMAND_RESPONSE / PROGRAM_RESPONSE）或进度消息（PROGRESS_UPDATE）时，
+     * 只需要提供 code 和业务字段，协议层通过 CodeMeta 自动推导 status / level / 消息类型。
+     *
+     * 替代旧的 createCommandResponseMessage / createProgramResponseMessage / createProgressUpdateMessage。
+     *
+     * @param params dispatch 参数
+     * @returns 完整的协议消息（具体类型由 code 派生的 isTerminal 决定）
+     * @throws Error 当 code 要求 data.error 但 params.error 缺失时
+     */
+    static dispatchMessage(params: {
+        clientId: string;
+        requestRef: string;
+        code: string;
+        message: string;
+        /** 终态消息：result 块；进度消息：业务平铺字段 */
+        data?: Record<string, any>;
+        /** v1.5.0 失败 schema — 当 code 要求时必填 */
+        error?: {
+            phase: string;
+            step: string;
+            category: string;
+            detail: string;
+        };
+        /** 仅进度消息：phase 与 progress */
+        phase?: ProgressPhase | string;
+        progress?: number;
+        /** 进度消息 sourceType（默认 COMMAND）*/
+        sourceType?: ProgressSourceType;
+        /** 终态消息 result 块（COMMAND_RESPONSE）*/
+        result?: any;
+        /** 终态消息 context（PROGRAM_RESPONSE）*/
+        context?: ProgramContext;
+        /** 终态消息 executionTime */
+        executionTime?: number;
+    }): CommandResponseMessage | ProgramResponseMessage | ProgressUpdateMessage;
 }
 export type AnyMessage = RegisterMessage | RegisterAckMessage | UnregisterMessage | UnregisterAckMessage | CommandMessage | CommandResponseMessage | ProgramMessage | ProgramResponseMessage | HeartbeatMessage | HeartbeatAckMessage | ProgressUpdateMessage | UpdateRoutesMessage | UpdateRoutesAckMessage | RegisterPendingMessage | AuthorizationGrantedMessage | AuthorizationRejectedMessage | DeviceApprovalRequestMessage | DeviceApprovalResponseMessage | ErrorMessage;
-export declare const PROTOCOL_VERSION = "1.5.0";
+export declare const PROTOCOL_VERSION = "1.6.1";
 export declare const DEFAULT_TIMEOUT = 10000;
 export declare const DEFAULT_PRIORITY = Priority.NORMAL;
 export * from './command-types';