rol-websocket-channel 1.4.8 → 1.4.9

package/dist/index.js

@@ -1,617 +1,623 @@
-// extensions/rol-websocket-channel/index.ts
-// WebSocket Channel 插件实现
-// 提供基于 WebSocket 的双向通信能力，支持 AI 回复和主动消息
-import { messageHandler } from "./message-handler.js";
-import { GlobalMqttClient } from "./src/mqtt/mqtt-client.js";
-import * as ConnectionManager from "./src/mqtt/connection-manager.js";
-// ============================================
-// 3. 全局状态
-// ============================================
-import { getContext, initializeContext } from "./src/shared/context.js";
-let pluginRuntime = null;
-export function getPluginRuntime() {
-    return pluginRuntime;
-}
-// ============================================
-// 4. 插件主体定义
-// ============================================
-const WebSocketChannel = {
-    id: "rol-websocket-channel",
-    meta: {
-        id: "rol-websocket-channel",
-        label: "Websocket Channel",
-        selectionLabel: "Websocket Channel (Custom)",
-        docsPath: "/channels/rol-websocket-channel",
-        blurb: "WebSocket based messaging channel.",
-        aliases: ["ws"],
-    },
-    capabilities: {
-        chatTypes: ["direct", "group"],
-        media: {
-            maxSizeBytes: 10 * 1024 * 1024,
-            supportedTypes: ["image/jpeg", "image/png", "video/mp4"],
-        },
-        supports: {
-            threads: true,
-            reactions: false,
-            mentions: true,
-        },
-    },
-    configSchema: {
-        schema: {
-            type: "object",
-            additionalProperties: false,
-            properties: {
-                enabled: { type: "boolean" },
-                dmPolicy: {
-                    type: "string",
-                    enum: ["pairing", "allowlist", "open", "disabled"],
-                },
-                allowFrom: {
-                    type: "array",
-                    items: { type: "string" },
-                },
-                pairing: {
-                    type: "object",
-                    additionalProperties: false,
-                    properties: {
-                        paired: { type: "boolean" },
-                        pairedAt: { type: "string" },
-                        pairingKeyLast4: { type: "string" },
-                        userId: { type: "string" },
-                        rawValue: { type: "string" },
-                    },
-                },
-                apiCoreBot: {
-                    type: "object",
-                    additionalProperties: false,
-                    properties: {
-                        baseUrl: { type: "string" },
-                        authToken: { type: "string" },
-                    },
-                },
-                pairingEndpoint: { type: "string" },
-                config: {
-                    type: "object",
-                    additionalProperties: false,
-                    properties: {
-                        enabled: { type: "boolean" },
-                        pairingEndpoint: { type: "string" },
-                        mqttUrl: { type: "string" },
-                        mqttTopic: { type: "string" },
-                        groupPolicy: {
-                            type: "string",
-                            enum: ["pairing", "allowlist", "open", "disabled"],
-                        },
-                    },
-                    required: ["mqttUrl"],
-                },
-            },
-        },
-        uiHints: {
-            enabled: { label: "Enabled", description: "Enable MQTT Channel" },
-            dmPolicy: {
-                label: "DM Policy",
-                description: "Pairing/allowlist/open policy for direct messages",
-            },
-            allowFrom: {
-                label: "Allow From",
-                description: "Allowed sender IDs when using allowlist or pairing mode",
-            },
-            pairing: {
-                label: "Pairing",
-                description: "Pairing status and resolved identity info",
-            },
-            apiCoreBot: {
-                label: "API Core Bot",
-                description: "Backend API endpoint and auth token used by the plugin",
-            },
-            pairingEndpoint: {
-                label: "Pairing Endpoint",
-                description: "Optional pairing API endpoint or base URL for staging/local environments",
-            },
-            config: {
-                label: "Configuration",
-                description: "MQTT connection configuration",
-            },
-            "config.pairingEndpoint": {
-                label: "Pairing Endpoint",
-                description: "Optional pairing API endpoint or base URL for staging/local environments",
-            },
-            "config.enabled": {
-                label: "Enabled",
-                description: "Enable this configuration",
-            },
-            "config.mqttUrl": {
-                label: "MQTT Broker URL",
-                placeholder: "ws://192.168.1.152:8083/mqtt",
-                help: "MQTT broker WebSocket URL",
-            },
-            "config.mqttTopic": {
-                label: "MQTT Topic",
-                placeholder: "announcement/tester",
-                help: "MQTT topic to subscribe/publish",
-            },
-            "config.groupPolicy": {
-                label: "Group Policy",
-                description: "Message policy for group chats",
-            },
-        },
-    },
-    config: {
-        listAccountIds: (cfg) => {
-            const channelCfg = cfg.channels?.["rol-websocket-channel"];
-            if (!channelCfg || !channelCfg.config || !channelCfg.config.mqttUrl) {
-                return [];
-            }
-            return ["default"];
-        },
-        resolveAccount: (cfg, accountId) => {
-            const channelCfg = cfg.channels?.["rol-websocket-channel"];
-            if (!channelCfg || !channelCfg.config) {
-                return undefined;
-            }
-            const config = channelCfg.config;
-            return {
-                accountId: "default",
-                mqttUrl: config.mqttUrl || "ws://192.168.1.152:8083/mqtt",
-                mqttTopic: config.mqttTopic || "announcement/tester",
-                enabled: config.enabled !== false,
-                dmPolicy: channelCfg.dmPolicy || config.groupPolicy || "open",
-                allowFrom: Array.isArray(channelCfg.allowFrom)
-                    ? channelCfg.allowFrom
-                    : [],
-                groupPolicy: config.groupPolicy || "open",
-            };
-        },
-        isConfigured: async (account, cfg) => {
-            return Boolean(account.mqttUrl && account.mqttUrl.trim() !== "");
-        },
-    },
-    status: {
-        defaultRuntime: {
-            accountId: "default",
-            running: false,
-            connected: false,
-            mqttUrl: null,
-            mqttTopic: null,
-            groupPolicy: null,
-            lastStartAt: null,
-            lastStopAt: null,
-            lastError: null,
-        },
-        buildChannelSummary: ({ snapshot }) => ({
-            mqttUrl: snapshot.mqttUrl ?? null,
-            mqttTopic: snapshot.mqttTopic ?? null,
-            connected: snapshot.connected ?? null,
-            groupPolicy: snapshot.groupPolicy ?? null,
-        }),
-        buildAccountSnapshot: ({ account, runtime }) => ({
-            accountId: account.accountId,
-            enabled: account.enabled,
-            configured: account.configured,
-            mqttUrl: account.mqttUrl,
-            mqttTopic: account.mqttTopic,
-            running: runtime?.running ?? false,
-            connected: runtime?.connected ?? false,
-            groupPolicy: runtime?.groupPolicy ?? null,
-            lastStartAt: runtime?.lastStartAt ?? null,
-            lastStopAt: runtime?.lastStopAt ?? null,
-            lastError: runtime?.lastError ?? null,
-        }),
-    },
-    outbound: {
-        deliveryMode: "direct",
-        sendText: async ({ to, text }) => {
-            const conn = ConnectionManager.getGlobalConnection();
-            if (!conn || !conn.ws || !conn.ws.connected) {
-                return { ok: false, error: "No MQTT connection" };
-            }
-            const message = JSON.stringify({
-                type: "message",
-                to,
-                content: text,
-                timestamp: Date.now(),
-            });
-            conn.ws.publish(conn.topic, message);
-            return { ok: true };
-        },
-        sendMedia: async ({ to, text, mediaUrl }) => {
-            const conn = ConnectionManager.getGlobalConnection();
-            if (!conn || !conn.ws || !conn.ws.connected) {
-                return { ok: false, error: "No MQTT connection" };
-            }
-            const message = JSON.stringify({
-                type: "media",
-                to,
-                content: text,
-                mediaUrl,
-                timestamp: Date.now(),
-            });
-            conn.ws.publish(conn.topic, message);
-            return { ok: true };
-        },
-    },
-    gateway: {
-        startAccount: async (ctx) => {
-            const { log, account, abortSignal, cfg } = ctx;
-            const runtime = pluginRuntime;
-            console.log(`[MQTT] startAccount(${account.accountId}): starting...`);
-            log?.info(`[rol-websocket-channel] Starting MQTT Channel for ${account.accountId}`);
-            // 检查是否已有活跃连接，防止重复启动
-            if (ConnectionManager.isGlobalConnected()) {
-                console.log(`[MQTT] startAccount(${account.accountId}): already connected, skipping`);
-                return;
-            }
-            if (!runtime?.channel?.reply?.withReplyDispatcher) {
-                console.error(`[MQTT] startAccount(${account.accountId}): Runtime API not available`);
-                throw new Error("Runtime API not available");
-            }
-            const mqttUrl = account.mqttUrl || "ws://192.168.1.152:8083/mqtt";
-            const mqttTopic = account.mqttTopic || "announcement/tester";
-            console.log(`[MQTT] startAccount(${account.accountId}): url=${mqttUrl}, topic=${mqttTopic}`);
-            ctx.setStatus({
-                accountId: account.accountId,
-                mqttUrl,
-                mqttTopic,
-                running: true,
-                connected: false,
-                groupPolicy: account.groupPolicy || "open",
-            });
-            // 创建 MQTT 客户端
-            console.log(`[MQTT] startAccount(${account.accountId}): creating GlobalMqttClient...`);
-            const client = new GlobalMqttClient({
-                mqttUrl,
-                mqttTopic,
-                abortSignal,
-                onConnect: () => {
-                    console.log(`[MQTT] startAccount(${account.accountId}): onConnect - setting status to connected`);
-                    ctx.setStatus({
-                        accountId: account.accountId,
-                        connected: true,
-                    });
-                },
-                onDisconnect: () => {
-                    console.log(`[MQTT] startAccount(${account.accountId}): onDisconnect - setting status to disconnected`);
-                    ctx.setStatus({
-                        accountId: account.accountId,
-                        connected: false,
-                    });
-                },
-                onError: (err) => {
-                    console.error(`[MQTT] startAccount(${account.accountId}): onError - ${err.message}`);
-                    log?.error(`[rol-websocket-channel] MQTT error: ${err.message}`);
-                },
-                onMessage: async (topic, payload) => {
-                    console.log(`[MQTT] startAccount(${account.accountId}): onMessage received`);
-                    await handleIncomingMessage(payload, account, cfg, runtime, log, mqttTopic);
-                },
-            });
-            // 启动连接
-            console.log(`[MQTT] startAccount(${account.accountId}): calling GlobalMqttClient.connect()...`);
-            await client.connect();
-            console.log(`[MQTT] startAccount(${account.accountId}): GlobalMqttClient.connect() returned`);
-        },
-        stopAccount: async (ctx) => {
-            const { log, account } = ctx;
-            console.log(`[MQTT] stopAccount(${account.accountId}): stopping...`);
-            log?.info(`[rol-websocket-channel] Stopping MQTT Channel for ${account.accountId}`);
-            ConnectionManager.closeGlobalConnection();
-            console.log(`[MQTT] stopAccount(${account.accountId}): stopped`);
-        },
-    },
-    security: {
-        getDmPolicy: (account) => account.dmPolicy ?? "open",
-        getAllowFrom: (account) => account.allowFrom ?? [],
-        checkGroupAccess: (account, groupId) => {
-            const groups = account.groups ?? {};
-            return "*" in groups || groupId in groups;
-        },
-    },
-};
-// ============================================
-// 5. 消息处理函数
-// ============================================
-async function handleIncomingMessage(payload, account, cfg, runtime, log, mqttTopic) {
-    try {
-        const rawData = payload.toString();
-        const eventData = JSON.parse(rawData);
-        const msgType = eventData.type || "sender";
-        const innerData = eventData.data || {};
-        const traceId = eventData.trace_id || eventData.traceId || `${Date.now()}`;
-        // 忽略 receiver 类型的消息
-        if (msgType === "receiver") {
-            return;
-        }
-        // 处理非标准消息类型
-        if (msgType !== "sender") {
-            await handleCustomMessageType(msgType, innerData, traceId, account.accountId, mqttTopic);
-            return;
-        }
-        // 构造标准消息格式
-        const attachments = (innerData.attachments || []).map((att) => ({
-            url: att.url,
-            type: att.type || "application/octet-stream",
-            name: att.name || "file",
-            size: att.size,
-        }));
-        const normalizedMessage = {
-            id: `${eventData.source || "mqtt"}-${Date.now()}`,
-            channel: "rol-websocket-channel",
-            accountId: account.accountId,
-            senderId: innerData.source || eventData.source || "unknown",
-            senderName: innerData.source || eventData.source || "Unknown",
-            text: innerData.content || innerData.text || "",
-            timestamp: innerData.timestamp || new Date().toISOString(),
-            isGroup: false,
-            groupId: undefined,
-            attachments,
-            metadata: { mqttTopic, traceId },
-        };
-        const targetAgentId = innerData.agentId ?? innerData.agent_id ?? null;
-        const targetSessionId = innerData.sessionKey ?? innerData.session_key ?? null;
-        log?.info(`[rol-websocket-channel] 📨 Received: "${normalizedMessage.text}" from ${normalizedMessage.senderId}` +
-            (targetAgentId ? ` → agent:${targetAgentId}` : "") +
-            (targetSessionId ? ` → session:${targetSessionId}` : ""));
-        // 解析路由
-        const route = runtime.channel.routing.resolveAgentRoute({
-            cfg,
-            channel: "rol-websocket-channel",
-            accountId: account.accountId,
-            peer: { kind: "direct", id: normalizedMessage.senderId },
-        });
-        // 用户传参覆盖自动路由结果
-        const resolvedAccountId = targetAgentId ?? route.accountId;
-        const resolvedSessionKey = targetSessionId ?? route.sessionKey;
-        // 构建消息上下文
-        const ctxPayload = runtime.channel.reply.finalizeInboundContext({
-            Body: normalizedMessage.text,
-            BodyForAgent: normalizedMessage.text,
-            From: normalizedMessage.senderId,
-            To: undefined,
-            SessionKey: resolvedSessionKey,
-            AccountId: resolvedAccountId,
-            ChatType: "direct",
-            SenderName: normalizedMessage.senderName,
-            SenderId: normalizedMessage.senderId,
-            Provider: "rol-websocket-channel",
-            Surface: "rol-websocket-channel",
-            MessageSid: normalizedMessage.id,
-            Timestamp: Date.now(),
-        });
-        // 调度回复
-        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-            ctx: ctxPayload,
-            cfg,
-            dispatcherOptions: {
-                deliver: async (payload) => {
-                    const conn = ConnectionManager.getGlobalConnection();
-                    if (!conn || !conn.ws || !conn.ws.connected) {
-                        throw new Error("No MQTT connection available");
-                    }
-                    const replyMessage = {
-                        type: "receiver",
-                        trace_id: traceId,
-                        source: "ai",
-                        meta: {
-                            'agentId': resolvedAccountId,
-                            'sessionKey': resolvedSessionKey
-                        },
-                        data: payload,
-                        timestamp: Date.now(),
-                    };
-                    // 根据 source_type 修改 topic 末尾的 #
-                    let targetTopic = mqttTopic;
-                    const sourceType = innerData?.source_type;
-                    if (targetTopic.endsWith("#")) {
-                        const replacement = sourceType === "device" ? "device" : "bot";
-                        targetTopic = targetTopic.slice(0, -1) + replacement;
-                    }
-                    conn.ws.publish(targetTopic, JSON.stringify(replyMessage));
-                },
-                onError: (err) => {
-                    log?.error(`[rol-websocket-channel] Delivery error: ${err.message}`);
-                },
-            },
-        });
-    }
-    catch (err) {
-        log?.error(`[rol-websocket-channel] Failed to process message: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-async function handleCustomMessageType(msgType, innerData, traceId, accountId, mqttTopic) {
-    const isSkillInstallFlow = msgType === "skillsInstallFromClawHub" || msgType === "skillsUpdateFromClawHub";
-    const response = {
-        type: "receiver",
-        trace_id: traceId,
-        source: "system",
-        timestamp: Date.now(),
-    };
-    if (isSkillInstallFlow) {
-        console.log(`[rol-websocket-channel] custom message start: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, accountId=${accountId}, topic=${mqttTopic}`);
-    }
-    const handlerMethod = messageHandler[msgType];
-    if (typeof handlerMethod === "function") {
-        try {
-            const methodResult = await handlerMethod.call(messageHandler, innerData);
-            // 兼容两种返回格式：
-            // 1. { ok, result, error } 格式（新的 admin 方法）
-            // 2. 直接返回数据格式（原有的 ping、echo、status 方法）
-            if (typeof methodResult === "object" &&
-                methodResult !== null &&
-                "ok" in methodResult) {
-                // 新格式：{ ok, result, error }
-                response.success = methodResult.ok;
-                response.data = methodResult.result;
-                if (!methodResult.ok) {
-                    response.error = methodResult.error?.message || "Unknown error";
-                    if (isSkillInstallFlow) {
-                        console.error(`[rol-websocket-channel] custom message failed: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, error=${response.error}, detail=${JSON.stringify(methodResult.error?.data ?? {})}`);
-                    }
-                }
-                else if (isSkillInstallFlow) {
-                    console.log(`[rol-websocket-channel] custom message success: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}`);
-                }
-            }
-            else {
-                // 旧格式：直接返回数据
-                response.success = true;
-                response.data = methodResult;
-                if (isSkillInstallFlow) {
-                    console.log(`[rol-websocket-channel] custom message success: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}`);
-                }
-            }
-        }
-        catch (handlerErr) {
-            response.success = false;
-            response.error = handlerErr.message;
-            if (isSkillInstallFlow) {
-                console.error(`[rol-websocket-channel] custom message threw: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, error=${handlerErr?.message ?? String(handlerErr)}`);
-            }
-        }
-    }
-    else {
-        response.success = false;
-        response.error = `Unknown message type: ${msgType}`;
-    }
-    const conn = ConnectionManager.getGlobalConnection();
-    if (conn && conn.ws && conn.ws.connected) {
-        // 根据 source_type 修改 topic 末尾的 #
-        let targetTopic = mqttTopic;
-        const sourceType = innerData?.source_type;
-        if (targetTopic.endsWith("#")) {
-            const replacement = sourceType === "device" ? "device" : "bot";
-            targetTopic = targetTopic.slice(0, -1) + replacement;
-        }
-        conn.ws.publish(targetTopic, JSON.stringify(response));
-    }
-}
-// ============================================
-// 6. 插件注册入口
-// ============================================
-let isPluginRegistered = false;
-export default function register(api) {
-    console.log("[mqtt] Register rol-websocket-channel");
-    if (isPluginRegistered) {
-        return;
-    }
-    console.log("[mqtt] Register rol-websocket-channel real");
-    isPluginRegistered = true;
-    pluginRuntime = api.runtime;
-    // 初始化共享 context
-    initializeContext();
-    // 注册 Channel
-    api.registerChannel({ plugin: WebSocketChannel });
-    // 注册 CLI（保留供外部调用）
-    registerAdminBridgeCli(api);
-}
-// ============================================
-// 7. CLI 注册（保留供外部调用）
-// ============================================
-function registerAdminBridgeCli(api) {
-    api.registerCli(({ program }) => {
-        const root = program
-            .command("admin-bridge")
-            .description("OpenClaw admin bridge utilities")
-            .addHelpText("after", () => "\nCommands return JSON to stdout for Python or shell orchestration.\n");
-        // 这里可以添加 CLI 命令，但现在先保持简单
-        // 如果需要完整的 CLI，可以从 openclaw-ts/index.ts 复制过来
-        root
-            .command("ping")
-            .description("Test admin bridge connection")
-            .action(async () => {
-            try {
-                const { ping } = await import("./src/admin/methods/system.js");
-                const { getContext } = await import("./src/shared/context.js");
-                const result = await ping(undefined, getContext());
-                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
-            }
-            catch (error) {
-                process.exitCode = 1;
-                process.stderr.write(JSON.stringify({
-                    ok: false,
-                    error: {
-                        message: error instanceof Error ? error.message : String(error),
-                    },
-                }, null, 2) + "\n");
-            }
-        });
-        root
-            .command("pair <key>")
-            .description("Pair rol-websocket-channel and write OpenClaw configuration")
-            .option("--endpoint <url>", "Pair exchange endpoint")
-            .option("--auth <token>", "Authorization header value for pair exchange")
-            .action(async (key, options) => {
-            try {
-                const { pairWithKey } = await import("./src/admin/methods/pairing.js");
-                const result = await pairWithKey({
-                    key,
-                    endpoint: options.endpoint,
-                    auth: options.auth,
-                }, getContext());
-                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
-            }
-            catch (error) {
-                process.exitCode = 1;
-                process.stderr.write(JSON.stringify({
-                    ok: false,
-                    error: {
-                        message: error instanceof Error ? error.message : String(error),
-                        code: error?.data?.code,
-                    },
-                }, null, 2) + "\n");
-            }
-        });
-        const mem9 = root
-            .command("mem9")
-            .description("Mem9 installer and reconnect utilities");
-        mem9
-            .command("install")
-            .description("Install mem9 plugin, create cloud key, write config, and restart gateway")
-            .action(async () => {
-            try {
-                const { installMem9 } = await import("./src/admin/methods/mem9.js");
-                const result = await installMem9(getContext());
-                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
-            }
-            catch (error) {
-                process.exitCode = 1;
-                process.stderr.write(JSON.stringify({
-                    ok: false,
-                    error: {
-                        message: error instanceof Error ? error.message : String(error),
-                        code: error?.data?.code,
-                    },
-                }, null, 2) + "\n");
-            }
-        });
-        mem9
-            .command("reconnect <key>")
-            .description("Replace mem9 apiKey, update config, and restart gateway")
-            .action(async (key) => {
-            try {
-                const { reconnectMem9 } = await import("./src/admin/methods/mem9.js");
-                const result = await reconnectMem9(key, getContext());
-                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
-            }
-            catch (error) {
-                process.exitCode = 1;
-                process.stderr.write(JSON.stringify({
-                    ok: false,
-                    error: {
-                        message: error instanceof Error ? error.message : String(error),
-                        code: error?.data?.code,
-                    },
-                }, null, 2) + "\n");
-            }
-        });
-    }, {
-        descriptors: [
-            {
-                name: "admin-bridge",
-                description: "OpenClaw admin bridge commands",
-                hasSubcommands: true,
-            },
-        ],
-    });
-}
+// extensions/rol-websocket-channel/index.ts
+// WebSocket Channel 插件实现
+// 提供基于 WebSocket 的双向通信能力，支持 AI 回复和主动消息
+import { messageHandler } from "./message-handler.js";
+import { GlobalMqttClient } from "./src/mqtt/mqtt-client.js";
+import * as ConnectionManager from "./src/mqtt/connection-manager.js";
+// ============================================
+// 3. 全局状态
+// ============================================
+import { getContext, initializeContext } from "./src/shared/context.js";
+let pluginRuntime = null;
+export function getPluginRuntime() {
+    return pluginRuntime;
+}
+// ============================================
+// 4. 插件主体定义
+// ============================================
+const WebSocketChannel = {
+    id: "rol-websocket-channel",
+    meta: {
+        id: "rol-websocket-channel",
+        label: "Websocket Channel",
+        selectionLabel: "Websocket Channel (Custom)",
+        docsPath: "/channels/rol-websocket-channel",
+        blurb: "WebSocket based messaging channel.",
+        aliases: ["ws"],
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        media: {
+            maxSizeBytes: 10 * 1024 * 1024,
+            supportedTypes: ["image/jpeg", "image/png", "video/mp4"],
+        },
+        supports: {
+            threads: true,
+            reactions: false,
+            mentions: true,
+        },
+    },
+    configSchema: {
+        schema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                enabled: { type: "boolean" },
+                dmPolicy: {
+                    type: "string",
+                    enum: ["pairing", "allowlist", "open", "disabled"],
+                },
+                allowFrom: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                pairing: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        paired: { type: "boolean" },
+                        pairedAt: { type: "string" },
+                        pairingKeyLast4: { type: "string" },
+                        userId: { type: "string" },
+                        rawValue: { type: "string" },
+                    },
+                },
+                apiCoreBot: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        baseUrl: { type: "string" },
+                        authToken: { type: "string" },
+                    },
+                },
+                pairingEndpoint: { type: "string" },
+                config: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        enabled: { type: "boolean" },
+                        pairingEndpoint: { type: "string" },
+                        mqttUrl: { type: "string" },
+                        mqttTopic: { type: "string" },
+                        groupPolicy: {
+                            type: "string",
+                            enum: ["pairing", "allowlist", "open", "disabled"],
+                        },
+                    },
+                    required: ["mqttUrl"],
+                },
+            },
+        },
+        uiHints: {
+            enabled: { label: "Enabled", description: "Enable MQTT Channel" },
+            dmPolicy: {
+                label: "DM Policy",
+                description: "Pairing/allowlist/open policy for direct messages",
+            },
+            allowFrom: {
+                label: "Allow From",
+                description: "Allowed sender IDs when using allowlist or pairing mode",
+            },
+            pairing: {
+                label: "Pairing",
+                description: "Pairing status and resolved identity info",
+            },
+            apiCoreBot: {
+                label: "API Core Bot",
+                description: "Backend API endpoint and auth token used by the plugin",
+            },
+            pairingEndpoint: {
+                label: "Pairing Endpoint",
+                description: "Optional pairing API endpoint or base URL for staging/local environments",
+            },
+            config: {
+                label: "Configuration",
+                description: "MQTT connection configuration",
+            },
+            "config.pairingEndpoint": {
+                label: "Pairing Endpoint",
+                description: "Optional pairing API endpoint or base URL for staging/local environments",
+            },
+            "config.enabled": {
+                label: "Enabled",
+                description: "Enable this configuration",
+            },
+            "config.mqttUrl": {
+                label: "MQTT Broker URL",
+                placeholder: "ws://192.168.1.152:8083/mqtt",
+                help: "MQTT broker WebSocket URL",
+            },
+            "config.mqttTopic": {
+                label: "MQTT Topic",
+                placeholder: "announcement/tester",
+                help: "MQTT topic to subscribe/publish",
+            },
+            "config.groupPolicy": {
+                label: "Group Policy",
+                description: "Message policy for group chats",
+            },
+        },
+    },
+    config: {
+        listAccountIds: (cfg) => {
+            const channelCfg = cfg.channels?.["rol-websocket-channel"];
+            if (!channelCfg || !channelCfg.config || !channelCfg.config.mqttUrl) {
+                return [];
+            }
+            return ["default"];
+        },
+        resolveAccount: (cfg, accountId) => {
+            const channelCfg = cfg.channels?.["rol-websocket-channel"];
+            if (!channelCfg || !channelCfg.config) {
+                return undefined;
+            }
+            const config = channelCfg.config;
+            return {
+                accountId: "default",
+                mqttUrl: config.mqttUrl || "ws://192.168.1.152:8083/mqtt",
+                mqttTopic: config.mqttTopic || "announcement/tester",
+                enabled: config.enabled !== false,
+                dmPolicy: channelCfg.dmPolicy || config.groupPolicy || "open",
+                allowFrom: Array.isArray(channelCfg.allowFrom)
+                    ? channelCfg.allowFrom
+                    : [],
+                groupPolicy: config.groupPolicy || "open",
+            };
+        },
+        isConfigured: async (account, cfg) => {
+            return Boolean(account.mqttUrl && account.mqttUrl.trim() !== "");
+        },
+    },
+    status: {
+        defaultRuntime: {
+            accountId: "default",
+            running: false,
+            connected: false,
+            mqttUrl: null,
+            mqttTopic: null,
+            groupPolicy: null,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+        buildChannelSummary: ({ snapshot }) => ({
+            mqttUrl: snapshot.mqttUrl ?? null,
+            mqttTopic: snapshot.mqttTopic ?? null,
+            connected: snapshot.connected ?? null,
+            groupPolicy: snapshot.groupPolicy ?? null,
+        }),
+        buildAccountSnapshot: ({ account, runtime }) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            mqttUrl: account.mqttUrl,
+            mqttTopic: account.mqttTopic,
+            running: runtime?.running ?? false,
+            connected: runtime?.connected ?? false,
+            groupPolicy: runtime?.groupPolicy ?? null,
+            lastStartAt: runtime?.lastStartAt ?? null,
+            lastStopAt: runtime?.lastStopAt ?? null,
+            lastError: runtime?.lastError ?? null,
+        }),
+    },
+    outbound: {
+        deliveryMode: "direct",
+        sendText: async ({ to, text }) => {
+            const conn = ConnectionManager.getGlobalConnection();
+            if (!conn || !conn.ws || !conn.ws.connected) {
+                return { ok: false, error: "No MQTT connection" };
+            }
+            const message = JSON.stringify({
+                type: "message",
+                to,
+                content: text,
+                timestamp: Date.now(),
+            });
+            conn.ws.publish(conn.topic, message);
+            return { ok: true };
+        },
+        sendMedia: async ({ to, text, mediaUrl }) => {
+            const conn = ConnectionManager.getGlobalConnection();
+            if (!conn || !conn.ws || !conn.ws.connected) {
+                return { ok: false, error: "No MQTT connection" };
+            }
+            const message = JSON.stringify({
+                type: "media",
+                to,
+                content: text,
+                mediaUrl,
+                timestamp: Date.now(),
+            });
+            conn.ws.publish(conn.topic, message);
+            return { ok: true };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const { log, account, abortSignal, cfg } = ctx;
+            const runtime = pluginRuntime;
+            console.log(`[MQTT] startAccount(${account.accountId}): starting...`);
+            log?.info(`[rol-websocket-channel] Starting MQTT Channel for ${account.accountId}`);
+            // 检查是否已有活跃连接，防止重复启动
+            if (ConnectionManager.isGlobalConnected()) {
+                console.log(`[MQTT] startAccount(${account.accountId}): already connected, skipping`);
+                return;
+            }
+            if (!runtime?.channel?.reply?.withReplyDispatcher) {
+                console.error(`[MQTT] startAccount(${account.accountId}): Runtime API not available`);
+                throw new Error("Runtime API not available");
+            }
+            const mqttUrl = account.mqttUrl || "ws://192.168.1.152:8083/mqtt";
+            const mqttTopic = account.mqttTopic || "announcement/tester";
+            console.log(`[MQTT] startAccount(${account.accountId}): url=${mqttUrl}, topic=${mqttTopic}`);
+            ctx.setStatus({
+                accountId: account.accountId,
+                mqttUrl,
+                mqttTopic,
+                running: true,
+                connected: false,
+                groupPolicy: account.groupPolicy || "open",
+            });
+            // 创建 MQTT 客户端
+            console.log(`[MQTT] startAccount(${account.accountId}): creating GlobalMqttClient...`);
+            const client = new GlobalMqttClient({
+                mqttUrl,
+                mqttTopic,
+                abortSignal,
+                onConnect: () => {
+                    console.log(`[MQTT] startAccount(${account.accountId}): onConnect - setting status to connected`);
+                    ctx.setStatus({
+                        accountId: account.accountId,
+                        connected: true,
+                    });
+                },
+                onDisconnect: () => {
+                    console.log(`[MQTT] startAccount(${account.accountId}): onDisconnect - setting status to disconnected`);
+                    ctx.setStatus({
+                        accountId: account.accountId,
+                        connected: false,
+                    });
+                },
+                onError: (err) => {
+                    console.error(`[MQTT] startAccount(${account.accountId}): onError - ${err.message}`);
+                    log?.error(`[rol-websocket-channel] MQTT error: ${err.message}`);
+                },
+                onMessage: async (topic, payload) => {
+                    console.log(`[MQTT] startAccount(${account.accountId}): onMessage received`);
+                    await handleIncomingMessage(payload, account, cfg, runtime, log, mqttTopic);
+                },
+            });
+            // 启动连接
+            console.log(`[MQTT] startAccount(${account.accountId}): calling GlobalMqttClient.connect()...`);
+            await client.connect();
+            console.log(`[MQTT] startAccount(${account.accountId}): GlobalMqttClient.connect() returned`);
+        },
+        stopAccount: async (ctx) => {
+            const { log, account } = ctx;
+            console.log(`[MQTT] stopAccount(${account.accountId}): stopping...`);
+            log?.info(`[rol-websocket-channel] Stopping MQTT Channel for ${account.accountId}`);
+            ConnectionManager.closeGlobalConnection();
+            console.log(`[MQTT] stopAccount(${account.accountId}): stopped`);
+        },
+    },
+    security: {
+        getDmPolicy: (account) => account.dmPolicy ?? "open",
+        getAllowFrom: (account) => account.allowFrom ?? [],
+        checkGroupAccess: (account, groupId) => {
+            const groups = account.groups ?? {};
+            return "*" in groups || groupId in groups;
+        },
+    },
+};
+// ============================================
+// 5. 消息处理函数
+// ============================================
+async function handleIncomingMessage(payload, account, cfg, runtime, log, mqttTopic) {
+    try {
+        const rawData = payload.toString();
+        const eventData = JSON.parse(rawData);
+        const msgType = eventData.type || "sender";
+        const innerData = eventData.data || {};
+        const traceId = eventData.trace_id || eventData.traceId || `${Date.now()}`;
+        // 忽略 receiver 类型的消息
+        if (msgType === "receiver") {
+            return;
+        }
+        // 处理非标准消息类型
+        if (msgType !== "sender") {
+            await handleCustomMessageType(msgType, innerData, traceId, account.accountId, mqttTopic);
+            return;
+        }
+        // 构造标准消息格式
+        const attachments = (innerData.attachments || []).map((att) => ({
+            url: att.url,
+            type: att.type || "application/octet-stream",
+            name: att.name || "file",
+            size: att.size,
+        }));
+        const normalizedMessage = {
+            id: `${eventData.source || "mqtt"}-${Date.now()}`,
+            channel: "rol-websocket-channel",
+            accountId: account.accountId,
+            senderId: innerData.source || eventData.source || "unknown",
+            senderName: innerData.source || eventData.source || "Unknown",
+            text: innerData.content || innerData.text || "",
+            timestamp: innerData.timestamp || new Date().toISOString(),
+            isGroup: false,
+            groupId: undefined,
+            attachments,
+            metadata: { mqttTopic, traceId },
+        };
+        const targetAgentId = innerData.agentId ?? innerData.agent_id ?? null;
+        const targetSessionId = innerData.sessionKey ?? innerData.session_key ?? null;
+        log?.info(`[rol-websocket-channel] 📨 Received: "${normalizedMessage.text}" from ${normalizedMessage.senderId}` +
+            (targetAgentId ? ` → agent:${targetAgentId}` : "") +
+            (targetSessionId ? ` → session:${targetSessionId}` : ""));
+        // 解析路由
+        const route = runtime.channel.routing.resolveAgentRoute({
+            cfg,
+            channel: "rol-websocket-channel",
+            accountId: account.accountId,
+            peer: { kind: "direct", id: normalizedMessage.senderId },
+        });
+        // 用户传参覆盖自动路由结果
+        const resolvedAccountId = targetAgentId ?? route.accountId;
+        const resolvedSessionKey = targetSessionId ?? route.sessionKey;
+        // 构建消息上下文
+        const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+            Body: normalizedMessage.text,
+            BodyForAgent: normalizedMessage.text,
+            From: normalizedMessage.senderId,
+            To: undefined,
+            SessionKey: resolvedSessionKey,
+            AccountId: resolvedAccountId,
+            ChatType: "direct",
+            SenderName: normalizedMessage.senderName,
+            SenderId: normalizedMessage.senderId,
+            Provider: "rol-websocket-channel",
+            Surface: "rol-websocket-channel",
+            MessageSid: normalizedMessage.id,
+            Timestamp: Date.now(),
+        });
+        // 调度回复
+        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg,
+            dispatcherOptions: {
+                deliver: async (payload) => {
+                    const conn = ConnectionManager.getGlobalConnection();
+                    if (!conn || !conn.ws || !conn.ws.connected) {
+                        throw new Error("No MQTT connection available");
+                    }
+                    const replyMessage = {
+                        type: "receiver",
+                        trace_id: traceId,
+                        source: "ai",
+                        meta: {
+                            'agentId': resolvedAccountId,
+                            'sessionKey': resolvedSessionKey
+                        },
+                        data: payload,
+                        timestamp: Date.now(),
+                    };
+                    // 根据 source_type 修改 topic 末尾的 #
+                    let targetTopic = mqttTopic;
+                    const sourceType = innerData?.source_type;
+                    if (targetTopic.endsWith("#")) {
+                        const replacement = sourceType === "device" ? "device" : "bot";
+                        targetTopic = targetTopic.slice(0, -1) + replacement;
+                    }
+                    conn.ws.publish(targetTopic, JSON.stringify(replyMessage));
+                },
+                onError: (err) => {
+                    log?.error(`[rol-websocket-channel] Delivery error: ${err.message}`);
+                },
+            },
+        });
+    }
+    catch (err) {
+        log?.error(`[rol-websocket-channel] Failed to process message: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function handleCustomMessageType(msgType, innerData, traceId, accountId, mqttTopic) {
+    const isSkillInstallFlow = msgType === "skillsInstallFromClawHub" || msgType === "skillsUpdateFromClawHub";
+    const response = {
+        type: "receiver",
+        trace_id: traceId,
+        source: "system",
+        timestamp: Date.now(),
+    };
+    if (isSkillInstallFlow) {
+        console.log(`[rol-websocket-channel] custom message start: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, accountId=${accountId}, topic=${mqttTopic}`);
+    }
+    const handlerMethod = messageHandler[msgType];
+    if (typeof handlerMethod === "function") {
+        try {
+            const methodResult = await handlerMethod.call(messageHandler, innerData);
+            // 兼容两种返回格式：
+            // 1. { ok, result, error } 格式（新的 admin 方法）
+            // 2. 直接返回数据格式（原有的 ping、echo、status 方法）
+            if (typeof methodResult === "object" &&
+                methodResult !== null &&
+                "ok" in methodResult) {
+                // 新格式：{ ok, result, error }
+                response.success = methodResult.ok;
+                response.data = methodResult.result;
+                if (!methodResult.ok) {
+                    response.error = methodResult.error?.message || "Unknown error";
+                    if (isSkillInstallFlow) {
+                        console.error(`[rol-websocket-channel] custom message failed: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, error=${response.error}, detail=${JSON.stringify(methodResult.error?.data ?? {})}`);
+                    }
+                }
+                else if (isSkillInstallFlow) {
+                    console.log(`[rol-websocket-channel] custom message success: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}`);
+                }
+            }
+            else {
+                // 旧格式：直接返回数据
+                response.success = true;
+                response.data = methodResult;
+                if (isSkillInstallFlow) {
+                    console.log(`[rol-websocket-channel] custom message success: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}`);
+                }
+            }
+        }
+        catch (handlerErr) {
+            response.success = false;
+            response.error = handlerErr.message;
+            if (isSkillInstallFlow) {
+                console.error(`[rol-websocket-channel] custom message threw: type=${msgType}, traceId=${traceId}, slug=${innerData?.slug ?? ""}, error=${handlerErr?.message ?? String(handlerErr)}`);
+            }
+        }
+    }
+    else {
+        response.success = false;
+        response.error = `Unknown message type: ${msgType}`;
+    }
+    const conn = ConnectionManager.getGlobalConnection();
+    if (conn && conn.ws && conn.ws.connected) {
+        // 根据 source_type 修改 topic 末尾的 #
+        let targetTopic = mqttTopic;
+        const sourceType = innerData?.source_type;
+        if (targetTopic.endsWith("#")) {
+            const replacement = sourceType === "device" ? "device" : "bot";
+            targetTopic = targetTopic.slice(0, -1) + replacement;
+        }
+        conn.ws.publish(targetTopic, JSON.stringify(response));
+    }
+}
+// ============================================
+// 6. 插件注册入口
+// ============================================
+let isPluginRegistered = false;
+export default function register(api) {
+    console.log("[mqtt] Register rol-websocket-channel");
+    if (isPluginRegistered) {
+        return;
+    }
+    console.log("[mqtt] Register rol-websocket-channel real");
+    isPluginRegistered = true;
+    pluginRuntime = api.runtime;
+    // 初始化共享 context
+    initializeContext();
+    // 注册 Channel
+    api.registerChannel({ plugin: WebSocketChannel });
+    // 注册 CLI（保留供外部调用）
+    registerAdminBridgeCli(api);
+}
+// ============================================
+// 7. CLI 注册（保留供外部调用）
+// ============================================
+function registerAdminBridgeCli(api) {
+    api.registerCli(({ program }) => {
+        const root = program
+            .command("admin-bridge")
+            .alias("rol-websocket-channel")
+            .description("OpenClaw admin bridge utilities")
+            .addHelpText("after", () => "\nCommands return JSON to stdout for Python or shell orchestration.\n");
+        // 这里可以添加 CLI 命令，但现在先保持简单
+        // 如果需要完整的 CLI，可以从 openclaw-ts/index.ts 复制过来
+        root
+            .command("ping")
+            .description("Test admin bridge connection")
+            .action(async () => {
+            try {
+                const { ping } = await import("./src/admin/methods/system.js");
+                const { getContext } = await import("./src/shared/context.js");
+                const result = await ping(undefined, getContext());
+                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                }, null, 2) + "\n");
+            }
+        });
+        root
+            .command("pair <key>")
+            .description("Pair rol-websocket-channel and write OpenClaw configuration")
+            .option("--endpoint <url>", "Pair exchange endpoint")
+            .option("--auth <token>", "Authorization header value for pair exchange")
+            .action(async (key, options) => {
+            try {
+                const { pairWithKey } = await import("./src/admin/methods/pairing.js");
+                const result = await pairWithKey({
+                    key,
+                    endpoint: options.endpoint,
+                    auth: options.auth,
+                }, getContext());
+                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                        code: error?.data?.code,
+                    },
+                }, null, 2) + "\n");
+            }
+        });
+        const mem9 = root
+            .command("mem9")
+            .description("Mem9 installer and reconnect utilities");
+        mem9
+            .command("install")
+            .description("Install mem9 plugin, create cloud key, write config, and restart gateway")
+            .action(async () => {
+            try {
+                const { installMem9 } = await import("./src/admin/methods/mem9.js");
+                const result = await installMem9(getContext());
+                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                        code: error?.data?.code,
+                    },
+                }, null, 2) + "\n");
+            }
+        });
+        mem9
+            .command("reconnect <key>")
+            .description("Replace mem9 apiKey, update config, and restart gateway")
+            .action(async (key) => {
+            try {
+                const { reconnectMem9 } = await import("./src/admin/methods/mem9.js");
+                const result = await reconnectMem9(key, getContext());
+                process.stdout.write(JSON.stringify({ ok: true, result }, null, 2) + "\n");
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    error: {
+                        message: error instanceof Error ? error.message : String(error),
+                        code: error?.data?.code,
+                    },
+                }, null, 2) + "\n");
+            }
+        });
+    }, {
+        descriptors: [
+            {
+                name: "admin-bridge",
+                description: "OpenClaw admin bridge commands",
+                hasSubcommands: true,
+            },
+            {
+                name: "rol-websocket-channel",
+                description: "OpenClaw admin bridge commands",
+                hasSubcommands: true,
+            },
+        ],
+    });
+}