@thejrsoft/subway-protocol 1.3.0

package/dist/protocol-utils.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 协议工具类 - 提供状态转换、类型判断和请求引用管理功能
+ */
+import { CommandStatus, Priority, ClientType, AnyMessage, CommandMessage, ProgressUpdateMessage, ProgramMessage } from './index';
+/**
+ * 协议工具类
+ */
+export declare class ProtocolUtils {
+    /**
+     * 将 CommandStatus 枚举转换为字符串
+     */
+    static statusToString(status: CommandStatus): string;
+    /**
+     * 将字符串转换为 CommandStatus 枚举
+     * @throws {Error} 如果字符串不是有效的状态值
+     */
+    static stringToStatus(status: string): CommandStatus;
+    /**
+     * 将字符串转换为 Priority 枚举
+     * @throws {Error} 如果字符串不是有效的优先级值
+     */
+    static priorityToEnum(priority: string): Priority;
+    /**
+     * 将 Priority 枚举转换为字符串
+     */
+    static enumToPriority(priority: Priority): string;
+    /**
+     * 将字符串转换为 ClientType 枚举
+     * @throws {Error} 如果字符串不是有效的客户端类型
+     */
+    static clientTypeToEnum(clientType: string): ClientType;
+    /**
+     * 将 ClientType 枚举转换为字符串
+     */
+    static enumToClientType(clientType: ClientType): string;
+    /**
+     * 检查消息是否为命令消息
+     * 增强版本：不仅检查类型，还验证结构
+     */
+    static isCommandMessage(message: any): message is CommandMessage;
+    /**
+     * 检查消息是否为进度更新消息
+     * 增强版本：包含额外的结构验证
+     */
+    static isProgressUpdate(message: any): message is ProgressUpdateMessage;
+    /**
+     * 检查消息是否为程序消息
+     * 增强版本：包含额外的结构验证
+     */
+    static isProgramMessage(message: any): message is ProgramMessage;
+    /**
+     * 从任意消息中提取请求引用
+     * @returns 请求引用，如果消息类型不包含请求引用则返回 undefined
+     */
+    static extractRequestRef(message: AnyMessage): string | undefined;
+    /**
+     * 生成唯一的请求引用 ID
+     * @param prefix 可选的前缀，用于标识请求来源
+     * @returns 格式为 "prefix-timestamp-random" 或 "timestamp-random"
+     */
+    static generateRequestRef(prefix?: string): string;
+    /**
+     * 生成带有特定格式的请求引用
+     * @param service 服务名称
+     * @param operation 操作名称
+     * @returns 格式为 "service:operation:timestamp:random"
+     */
+    static generateStructuredRequestRef(service: string, operation: string): string;
+    /**
+     * 安全的枚举转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParseStatus(status: string): CommandStatus | null;
+    /**
+     * 安全的优先级转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParsePriority(priority: string): Priority | null;
+    /**
+     * 安全的客户端类型转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParseClientType(clientType: string): ClientType | null;
+    /**
+     * 从请求引用中解析信息
+     * @returns 解析后的组件，如果格式不匹配则返回 null
+     */
+    static parseRequestRef(requestRef: string): {
+        prefix?: string;
+        timestamp?: number;
+        random?: string;
+        service?: string;
+        operation?: string;
+    } | null;
+    /**
+     * 获取消息的类型名称（友好的字符串格式）
+     */
+    static getMessageTypeName(message: AnyMessage): string;
+    /**
+     * 检查是否为请求消息（需要响应的消息）
+     */
+    static isRequestMessage(message: AnyMessage): boolean;
+    /**
+     * 检查是否为响应消息
+     */
+    static isResponseMessage(message: AnyMessage): boolean;
+}
+//# sourceMappingURL=protocol-utils.d.ts.map

package/dist/protocol-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-utils.d.ts","sourceRoot":"","sources":["../src/protocol-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EAEV,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EASf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM;IAIpD;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAYpD;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAUjD;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM;IAIjD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU;IAUvD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAIvD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,cAAc;IAgBhE;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,qBAAqB;IAgBvE;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,cAAc;IAkBhE;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAgCjE;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAalD;;;;;OAKG;IACH,MAAM,CAAC,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAS/E;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAQ3D;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAQ1D;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAQhE;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG;QAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAkCR;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM;IAmBtD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO;IAYrD;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO;CAWvD"}

package/dist/protocol-utils.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * 协议工具类 - 提供状态转换、类型判断和请求引用管理功能
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolUtils = void 0;
+const index_1 = require("./index");
+/**
+ * 协议工具类
+ */
+class ProtocolUtils {
+    /**
+     * 将 CommandStatus 枚举转换为字符串
+     */
+    static statusToString(status) {
+        return status.toString();
+    }
+    /**
+     * 将字符串转换为 CommandStatus 枚举
+     * @throws {Error} 如果字符串不是有效的状态值
+     */
+    static stringToStatus(status) {
+        // 处理大小写和空格
+        const normalizedStatus = status.trim().toUpperCase();
+        // 检查是否是有效的枚举值
+        if (!Object.values(index_1.CommandStatus).includes(normalizedStatus)) {
+            throw new Error(`Invalid command status: ${status}. Valid values are: ${Object.values(index_1.CommandStatus).join(', ')}`);
+        }
+        return normalizedStatus;
+    }
+    /**
+     * 将字符串转换为 Priority 枚举
+     * @throws {Error} 如果字符串不是有效的优先级值
+     */
+    static priorityToEnum(priority) {
+        const normalizedPriority = priority.trim().toUpperCase();
+        if (!Object.values(index_1.Priority).includes(normalizedPriority)) {
+            throw new Error(`Invalid priority: ${priority}. Valid values are: ${Object.values(index_1.Priority).join(', ')}`);
+        }
+        return normalizedPriority;
+    }
+    /**
+     * 将 Priority 枚举转换为字符串
+     */
+    static enumToPriority(priority) {
+        return priority.toString();
+    }
+    /**
+     * 将字符串转换为 ClientType 枚举
+     * @throws {Error} 如果字符串不是有效的客户端类型
+     */
+    static clientTypeToEnum(clientType) {
+        const normalizedType = clientType.trim().toUpperCase();
+        if (!Object.values(index_1.ClientType).includes(normalizedType)) {
+            throw new Error(`Invalid client type: ${clientType}. Valid values are: ${Object.values(index_1.ClientType).join(', ')}`);
+        }
+        return normalizedType;
+    }
+    /**
+     * 将 ClientType 枚举转换为字符串
+     */
+    static enumToClientType(clientType) {
+        return clientType.toString();
+    }
+    /**
+     * 检查消息是否为命令消息
+     * 增强版本：不仅检查类型，还验证结构
+     */
+    static isCommandMessage(message) {
+        if (!(0, index_1.isCommandMessage)(message)) {
+            return false;
+        }
+        // 额外的结构验证
+        return !!(message.requestRef &&
+            message.targetClientId &&
+            message.command &&
+            message.priority &&
+            message.timeout !== undefined &&
+            message.callback);
+    }
+    /**
+     * 检查消息是否为进度更新消息
+     * 增强版本：包含额外的结构验证
+     */
+    static isProgressUpdate(message) {
+        if (!(0, index_1.isProgressUpdateMessage)(message)) {
+            return false;
+        }
+        // 额外的结构验证
+        return !!(message.requestRef &&
+            message.status &&
+            message.phase &&
+            typeof message.progress === 'number' &&
+            message.sourceType &&
+            (message.sourceType === 'COMMAND' || message.sourceType === 'SYSTEM'));
+    }
+    /**
+     * 检查消息是否为程序消息
+     * 增强版本：包含额外的结构验证
+     */
+    static isProgramMessage(message) {
+        if (!(0, index_1.isProgramMessage)(message)) {
+            return false;
+        }
+        // 额外的结构验证
+        return !!(message.requestRef &&
+            message.targetClientId &&
+            message.command &&
+            message.command.commandCode === 'UPLOAD_PROGRAM' &&
+            message.command.parameters &&
+            message.priority &&
+            message.timeout !== undefined &&
+            message.callback);
+    }
+    /**
+     * 从任意消息中提取请求引用
+     * @returns 请求引用，如果消息类型不包含请求引用则返回 undefined
+     */
+    static extractRequestRef(message) {
+        switch (message.type) {
+            // 包含 requestRef 的消息类型
+            case index_1.MessageType.COMMAND:
+            case index_1.MessageType.COMMAND_RESPONSE:
+            case index_1.MessageType.PROGRAM:
+            case index_1.MessageType.PROGRAM_RESPONSE:
+            case index_1.MessageType.PROGRESS_UPDATE:
+                return message.requestRef;
+            // ERROR 消息可能在 context 中包含 requestRef
+            case index_1.MessageType.ERROR:
+                const errorMsg = message;
+                if (errorMsg.context && typeof errorMsg.context === 'object') {
+                    return errorMsg.context.requestRef;
+                }
+                return undefined;
+            // 其他消息类型不包含 requestRef
+            case index_1.MessageType.REGISTER:
+            case index_1.MessageType.REGISTER_ACK:
+            case index_1.MessageType.UNREGISTER:
+            case index_1.MessageType.UNREGISTER_ACK:
+            case index_1.MessageType.HEARTBEAT:
+            case index_1.MessageType.HEARTBEAT_ACK:
+                return undefined;
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * 生成唯一的请求引用 ID
+     * @param prefix 可选的前缀，用于标识请求来源
+     * @returns 格式为 "prefix-timestamp-random" 或 "timestamp-random"
+     */
+    static generateRequestRef(prefix) {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substr(2, 9);
+        if (prefix) {
+            // 清理前缀，只保留字母数字和连字符
+            const cleanPrefix = prefix.replace(/[^a-zA-Z0-9-]/g, '');
+            return `${cleanPrefix}-${timestamp}-${random}`;
+        }
+        return `${timestamp}-${random}`;
+    }
+    /**
+     * 生成带有特定格式的请求引用
+     * @param service 服务名称
+     * @param operation 操作名称
+     * @returns 格式为 "service:operation:timestamp:random"
+     */
+    static generateStructuredRequestRef(service, operation) {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substr(2, 6);
+        const cleanService = service.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+        const cleanOperation = operation.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+        return `${cleanService}:${cleanOperation}:${timestamp}:${random}`;
+    }
+    /**
+     * 安全的枚举转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParseStatus(status) {
+        try {
+            return this.stringToStatus(status);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 安全的优先级转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParsePriority(priority) {
+        try {
+            return this.priorityToEnum(priority);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 安全的客户端类型转换（不抛出异常）
+     * @returns 枚举值或 null
+     */
+    static tryParseClientType(clientType) {
+        try {
+            return this.clientTypeToEnum(clientType);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 从请求引用中解析信息
+     * @returns 解析后的组件，如果格式不匹配则返回 null
+     */
+    static parseRequestRef(requestRef) {
+        // 尝试解析结构化格式 "service:operation:timestamp:random"
+        const structuredMatch = requestRef.match(/^([a-z]+):([a-z]+):(\d+):([a-z0-9]+)$/);
+        if (structuredMatch) {
+            return {
+                service: structuredMatch[1],
+                operation: structuredMatch[2],
+                timestamp: parseInt(structuredMatch[3], 10),
+                random: structuredMatch[4]
+            };
+        }
+        // 尝试解析带前缀格式 "prefix-timestamp-random"
+        const prefixMatch = requestRef.match(/^([a-zA-Z0-9-]+)-(\d+)-([a-z0-9]+)$/);
+        if (prefixMatch) {
+            return {
+                prefix: prefixMatch[1],
+                timestamp: parseInt(prefixMatch[2], 10),
+                random: prefixMatch[3]
+            };
+        }
+        // 尝试解析简单格式 "timestamp-random"
+        const simpleMatch = requestRef.match(/^(\d+)-([a-z0-9]+)$/);
+        if (simpleMatch) {
+            return {
+                timestamp: parseInt(simpleMatch[1], 10),
+                random: simpleMatch[2]
+            };
+        }
+        return null;
+    }
+    /**
+     * 获取消息的类型名称（友好的字符串格式）
+     */
+    static getMessageTypeName(message) {
+        const typeNames = {
+            [index_1.MessageType.REGISTER]: 'Register',
+            [index_1.MessageType.REGISTER_ACK]: 'Register Acknowledgment',
+            [index_1.MessageType.UNREGISTER]: 'Unregister',
+            [index_1.MessageType.UNREGISTER_ACK]: 'Unregister Acknowledgment',
+            [index_1.MessageType.HEARTBEAT]: 'Heartbeat',
+            [index_1.MessageType.HEARTBEAT_ACK]: 'Heartbeat Acknowledgment',
+            [index_1.MessageType.COMMAND]: 'Command',
+            [index_1.MessageType.COMMAND_RESPONSE]: 'Command Response',
+            [index_1.MessageType.PROGRAM]: 'Program Upload',
+            [index_1.MessageType.PROGRAM_RESPONSE]: 'Program Response',
+            [index_1.MessageType.PROGRESS_UPDATE]: 'Progress Update',
+            [index_1.MessageType.ERROR]: 'Error'
+        };
+        return typeNames[message.type] || 'Unknown';
+    }
+    /**
+     * 检查是否为请求消息（需要响应的消息）
+     */
+    static isRequestMessage(message) {
+        const requestTypes = [
+            index_1.MessageType.REGISTER,
+            index_1.MessageType.UNREGISTER,
+            index_1.MessageType.HEARTBEAT,
+            index_1.MessageType.COMMAND,
+            index_1.MessageType.PROGRAM
+        ];
+        return requestTypes.includes(message.type);
+    }
+    /**
+     * 检查是否为响应消息
+     */
+    static isResponseMessage(message) {
+        const responseTypes = [
+            index_1.MessageType.REGISTER_ACK,
+            index_1.MessageType.UNREGISTER_ACK,
+            index_1.MessageType.HEARTBEAT_ACK,
+            index_1.MessageType.COMMAND_RESPONSE,
+            index_1.MessageType.PROGRAM_RESPONSE
+        ];
+        return responseTypes.includes(message.type);
+    }
+}
+exports.ProtocolUtils = ProtocolUtils;
+//# sourceMappingURL=protocol-utils.js.map

package/dist/protocol-utils.js.map

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

package/docs/01-protocol/README.md

@@ -0,0 +1,45 @@
+# 协议规范文档
+
+本目录包含 JRSoft Subway WebSocket 协议的核心规范文档。
+
+## 📚 文档列表
+
+### [协议规范](./specification.md)
+完整的 WebSocket 协议定义，包括：
+- 消息格式和类型
+- 客户端类型定义
+- 命令系统设计
+- 错误处理机制
+- 协议版本管理
+
+### [消息类型详解](./message-types.md)
+所有消息类型的详细说明：
+- register - 客户端注册
+- command - 命令请求
+- command_response - 命令响应
+- progress_update - 进度更新
+- program - 节目上传
+- program_response - 节目响应
+- heartbeat - 心跳保活
+- error - 错误消息
+
+### [设计理念](./design-rationale.md)
+协议设计的核心理念和决策：
+- 为什么选择 WebSocket
+- 消息格式设计考量
+- 命令系统架构决策
+- 扩展性和兼容性设计
+
+## 🚀 快速开始
+
+如果您是第一次接触本协议，建议按以下顺序阅读：
+
+1. 先阅读[设计理念](./design-rationale.md)了解协议的设计思想
+2. 然后查看[协议规范](./specification.md)掌握整体结构
+3. 最后深入[消息类型详解](./message-types.md)了解具体实现
+
+## 🔗 相关文档
+
+- [命令系统文档](../02-commands/) - 了解不同类型的命令
+- [架构文档](../03-architecture/) - 了解系统架构和消息流
+- [集成指南](../04-integration/) - 如何集成协议到您的系统

package/docs/01-protocol/design-rationale.md

@@ -0,0 +1,198 @@
+# JRSoft Subway 协议设计理念
+
+本文档记录了 JRSoft Subway WebSocket 协议的核心设计决策和理念。
+
+## 目录
+
+- [总体设计理念](#总体设计理念)
+- [长时间运行操作](#长时间运行操作)
+- [消息类型设计](#消息类型设计)
+- [进度上报机制](#进度上报机制)
+- [错误处理策略](#错误处理策略)
+
+## 总体设计理念
+
+### 1. 分层架构设计
+
+系统采用严格的分层架构：
+- **Backend** → **Gateway** → **Edge** → **Device**
+- Gateway 作为中央路由器，管理所有 Edge 连接
+- Edge 作为设备接入点，管理本地设备连接
+- 设备不直接连接 Gateway，确保架构清晰
+
+### 2. 渐进式复杂度
+
+协议采用渐进式设计，从简单到复杂：
+- **Simple命令**：一次请求，一次响应
+- **Batch命令**：一次请求，批量执行，汇总响应
+- **Complex命令**：一次请求，多次进度更新，最终响应
+
+### 3. 明确的生命周期
+
+每个操作都有清晰的开始和结束：
+- 开始：特定的请求消息（command、program）
+- 过程：可选的进度更新（progress_update）
+- 结束：明确的响应消息（command_response、program_response）
+
+## 长时间运行操作
+
+### Complex命令设计
+
+**为什么需要Complex类型？**
+- 某些操作需要执行多个步骤，每个步骤都有独立的结果
+- 客户端需要实时了解执行进度
+- 传统的请求-响应模式无法满足需求
+
+**设计决策：**
+1. 复用现有的 `command` 消息结构，通过 `commandType: 'complex'` 区分
+2. 使用 `progress_update` 报告中间结果，保持消息格式统一
+3. 最终通过 `command_response` 结束，确保有明确的终止信号
+
+**典型应用场景：**
+- 健康检查：需要检查多个组件状态
+- 系统诊断：逐步执行多项测试
+- 状态监控：持续报告状态变化
+
+### 批量命令新设计（借鉴Complex模式）
+
+**为什么要重新设计批量命令？**
+- 当前设计要求设备理解批量概念，增加了复杂度
+- 设备需要处理范围解析、批量执行等逻辑
+- 难以实时跟踪每个设备的执行状态
+
+**新的设计理念：**
+1. 批量命令由 Gateway/Edge 处理向下游传递到 Device
+2. Device 将批量命令分解为多个 Simple 命令
+3. 每个设备的响应通过 `progress_update` 实时上报
+4. 最终通过 `command_response` 返回汇总结果
+
+**优势：**
+- **设备端简化**：只需实现 Simple 命令
+- **更好的可观察性**：实时看到每个设备状态
+- **灵活的执行策略**：Gateway 可控制并发、失败处理等
+- **协议统一**：批量和 Complex 都使用相同的进度机制
+
+### 程序上传设计
+
+**为什么程序上传独立于命令系统？**
+- 程序上传是特殊的业务流程，不是简单的命令执行
+- 需要携带大量元数据（任务ID、程序ID、发布时间等）
+- 上传过程涉及多个明确的阶段
+
+**设计决策：**
+1. 使用专门的 `program` 和 `program_response` 消息类型
+2. 引入 `context` 确保每个进度更新都能关联到具体程序
+3. `program_response` 简化设计，仅作为流程结束标志
+
+**阶段划分理由：**
+- **downloading**：网络传输阶段
+- **decompressing**：文件处理阶段
+- **preprocessing**：内容验证阶段
+- **createFrames**：数据转换阶段
+- **uploading**：设备写入阶段
+- **statistics**：结果统计阶段
+
+## 消息类型设计
+
+### 为什么不合并program和command？
+
+虽然两者都支持进度更新，但本质不同：
+- **命令**：执行设备操作，关注操作结果
+- **程序上传**：传输和安装内容，关注传输进度
+
+保持分离的好处：
+1. 语义清晰，易于理解
+2. 可以独立演进，互不影响
+3. 便于实现不同的业务逻辑
+
+### progress_update的通用性
+
+`progress_update` 设计为通用的进度报告机制，可用于：
+- Batch命令、Complex命令的中间结果
+- 程序上传的阶段进度
+- 未来其他长时间操作
+
+关键设计：
+- `sourceType` 区分来源类型
+- `report` 提供结构化日志
+- `command` 记录设备操作
+- `context` 关联程序信息
+
+## 进度上报机制
+
+### 状态管理
+
+六种状态覆盖所有场景：
+- **pending**：等待开始
+- **in_progress**：执行中
+- **paused**：已暂停
+- **completed**：成功完成
+- **failed**：执行失败
+- **cancelled**：已取消
+
+### 日志结构化
+
+统一的 `ReportMessage` 结构：
+```typescript
+{
+  level: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+  message: string;      // 必需的消息内容
+  code?: string;        // 可选的标准化代码
+  data?: object;        // 可选的附加数据
+}
+```
+
+优势：
+- 便于日志分级处理
+- 支持错误代码标准化
+- 可携带结构化数据
+
+## 错误处理策略
+
+### 分层错误处理
+
+1. **传输层错误**：WebSocket连接问题，由Gateway处理
+2. **协议层错误**：消息格式错误，返回error消息
+3. **业务层错误**：命令执行失败，在响应中体现
+
+### 错误信息设计
+
+- 使用 `report` 结构统一错误信息
+- `code` 用于错误分类
+- `data` 携带错误详情
+- `retryable` 标记是否可重试
+
+## 设计权衡
+
+### 1. 简单性 vs 功能性
+
+选择：优先简单性，通过可选字段扩展功能
+- 基础功能保持简单
+- 高级功能通过可选字段实现
+- 避免过度设计
+
+### 2. 统一性 vs 特殊性
+
+选择：在统一框架下支持特殊需求
+- 统一的消息基础结构
+- 统一的进度上报机制
+- 特殊需求通过扩展字段满足
+
+### 3. 同步 vs 异步
+
+选择：支持两种模式
+- Simple命令：同步模式
+- Complex命令和程序上传：异步模式
+- 通过消息类型自然区分
+
+## 未来扩展性
+
+协议设计考虑了未来扩展：
+1. 版本字段支持协议演进
+2. 可选字段支持功能扩展
+3. 新的消息类型可以无缝添加
+4. 向后兼容性通过版本协商实现
+
+---
+
+*本文档会随着协议演进持续更新*