@ynhcj/xiaoyi-channel 0.0.1-beta

package/dist/src/heartbeat.d.ts

@@ -0,0 +1,39 @@
+import WebSocket from "ws";
+export interface HeartbeatConfig {
+    interval: number;
+    timeout: number;
+    message: string;
+}
+/**
+ * Manages heartbeat for a WebSocket connection.
+ * Supports both application-level (30s) and protocol-level (20s) heartbeats.
+ */
+export declare class HeartbeatManager {
+    private ws;
+    private config;
+    private onTimeout;
+    private serverName;
+    private onHeartbeatSuccess?;
+    private intervalTimer;
+    private timeoutTimer;
+    private lastPongTime;
+    private log;
+    private error;
+    constructor(ws: WebSocket, config: HeartbeatConfig, onTimeout: () => void, serverName?: string, logFn?: (msg: string, ...args: any[]) => void, errorFn?: (msg: string, ...args: any[]) => void, onHeartbeatSuccess?: () => void);
+    /**
+     * Start heartbeat monitoring.
+     */
+    start(): void;
+    /**
+     * Stop heartbeat monitoring.
+     */
+    stop(): void;
+    /**
+     * Send a heartbeat ping.
+     */
+    private sendHeartbeat;
+    /**
+     * Check if connection is healthy based on last pong time.
+     */
+    isHealthy(): boolean;
+}

package/dist/src/heartbeat.js

@@ -0,0 +1,102 @@
+// Heartbeat management for WebSocket connections
+import WebSocket from "ws";
+/**
+ * Manages heartbeat for a WebSocket connection.
+ * Supports both application-level (30s) and protocol-level (20s) heartbeats.
+ */
+export class HeartbeatManager {
+    ws;
+    config;
+    onTimeout;
+    serverName;
+    onHeartbeatSuccess;
+    intervalTimer = null;
+    timeoutTimer = null;
+    lastPongTime = 0;
+    // Logging functions following feishu pattern
+    log;
+    error;
+    constructor(ws, config, onTimeout, serverName = "unknown", logFn, errorFn, onHeartbeatSuccess // ✅ 新增：心跳成功回调
+    ) {
+        this.ws = ws;
+        this.config = config;
+        this.onTimeout = onTimeout;
+        this.serverName = serverName;
+        this.onHeartbeatSuccess = onHeartbeatSuccess;
+        this.log = logFn ?? console.log;
+        this.error = errorFn ?? console.error;
+    }
+    /**
+     * Start heartbeat monitoring.
+     */
+    start() {
+        this.stop(); // Clear any existing timers
+        this.lastPongTime = Date.now();
+        // Setup ping/pong for protocol-level heartbeat
+        this.ws.on("pong", () => {
+            this.lastPongTime = Date.now();
+            if (this.timeoutTimer) {
+                clearTimeout(this.timeoutTimer);
+                this.timeoutTimer = null;
+            }
+            // ✅ Report health: heartbeat successful
+            this.onHeartbeatSuccess?.();
+        });
+        // Start interval timer
+        this.intervalTimer = setInterval(() => {
+            this.sendHeartbeat();
+        }, this.config.interval);
+        this.log(`[DEBUG] Heartbeat started for ${this.serverName}: interval=${this.config.interval}ms`);
+    }
+    /**
+     * Stop heartbeat monitoring.
+     */
+    stop() {
+        if (this.intervalTimer) {
+            clearInterval(this.intervalTimer);
+            this.intervalTimer = null;
+        }
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+        this.log(`[DEBUG] Heartbeat stopped for ${this.serverName}`);
+    }
+    /**
+     * Send a heartbeat ping.
+     */
+    sendHeartbeat() {
+        if (this.ws.readyState !== WebSocket.OPEN) {
+            console.warn(`Cannot send heartbeat for ${this.serverName}: WebSocket not open`);
+            return;
+        }
+        try {
+            // Send application-level heartbeat message
+            console.log(`[WS-${this.serverName}-SEND] Sending heartbeat frame:`, this.config.message);
+            this.ws.send(this.config.message);
+            console.log(`[WS-${this.serverName}-SEND] Heartbeat message sent, size: ${this.config.message.length} bytes`);
+            // Send protocol-level ping
+            this.ws.ping();
+            console.log(`[WS-${this.serverName}-SEND] Protocol-level ping sent`);
+            // Setup timeout timer
+            this.timeoutTimer = setTimeout(() => {
+                this.error(`Heartbeat timeout for ${this.serverName}`);
+                this.onTimeout();
+            }, this.config.timeout);
+            this.log(`[DEBUG] Heartbeat sent for ${this.serverName}`);
+        }
+        catch (error) {
+            this.error(`Failed to send heartbeat for ${this.serverName}:`, error);
+        }
+    }
+    /**
+     * Check if connection is healthy based on last pong time.
+     */
+    isHealthy() {
+        if (this.lastPongTime === 0) {
+            return true; // Not started yet
+        }
+        const timeSinceLastPong = Date.now() - this.lastPongTime;
+        return timeSinceLastPong < this.config.interval + this.config.timeout;
+    }
+}

package/dist/src/monitor.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+export type MonitorXYOpts = {
+    config?: any;
+    runtime?: RuntimeEnv;
+    abortSignal?: AbortSignal;
+    accountId?: string;
+    setStatus?: (status: {
+        lastEventAt?: number;
+        lastInboundAt?: number;
+        connected?: boolean;
+    }) => void;
+};
+/**
+ * Monitor XY channel WebSocket connections.
+ * Keeps the connection alive until abortSignal is triggered.
+ */
+export declare function monitorXYProvider(opts?: MonitorXYOpts): Promise<void>;

package/dist/src/monitor.js

@@ -0,0 +1,191 @@
+import { resolveXYConfig } from "./config.js";
+import { getXYWebSocketManager, diagnoseAllManagers, cleanupOrphanConnections, removeXYWebSocketManager } from "./client.js";
+import { handleXYMessage } from "./bot.js";
+/**
+ * Per-session serial queue that ensures messages from the same session are processed
+ * in arrival order while allowing different sessions to run concurrently.
+ * Following feishu/monitor.account.ts pattern.
+ */
+function createSessionQueue() {
+    const queues = new Map();
+    return (sessionId, task) => {
+        const prev = queues.get(sessionId) ?? Promise.resolve();
+        const next = prev.then(task, task);
+        queues.set(sessionId, next);
+        void next.finally(() => {
+            if (queues.get(sessionId) === next) {
+                queues.delete(sessionId);
+            }
+        });
+        return next;
+    };
+}
+/**
+ * Monitor XY channel WebSocket connections.
+ * Keeps the connection alive until abortSignal is triggered.
+ */
+export async function monitorXYProvider(opts = {}) {
+    const cfg = opts.config;
+    if (!cfg) {
+        throw new Error("Config is required for XY monitor");
+    }
+    const runtime = opts.runtime;
+    const log = runtime?.log ?? console.log;
+    const error = runtime?.error ?? console.error;
+    const account = resolveXYConfig(cfg);
+    if (!account.enabled) {
+        throw new Error(`XY account is disabled`);
+    }
+    const accountId = opts.accountId ?? "default";
+    // Create trackEvent function to report health to OpenClaw framework
+    const trackEvent = opts.setStatus
+        ? () => {
+            opts.setStatus({ lastEventAt: Date.now(), lastInboundAt: Date.now() });
+        }
+        : undefined;
+    // 🔍 Diagnose WebSocket managers before gateway start
+    console.log("🔍 [DIAGNOSTICS] Checking WebSocket managers before gateway start...");
+    diagnoseAllManagers();
+    // Get WebSocket manager (cached)
+    const wsManager = getXYWebSocketManager(account);
+    // ✅ Set health event callback for heartbeat reporting
+    if (trackEvent) {
+        wsManager.setHealthEventCallback(trackEvent);
+    }
+    // Track logged servers to avoid duplicate logs
+    const loggedServers = new Set();
+    // Track active message processing to detect duplicates
+    const activeMessages = new Set();
+    // Create session queue for ordered message processing
+    const enqueue = createSessionQueue();
+    // Health check interval
+    let healthCheckInterval = null;
+    return new Promise((resolve, reject) => {
+        // Event handlers (defined early so they can be referenced in cleanup)
+        const messageHandler = (message, sessionId, serverId) => {
+            const messageKey = `${sessionId}::${message.id}`;
+            log(`[MONITOR-HANDLER] ####### messageHandler triggered: serverId=${serverId}, sessionId=${sessionId}, messageId=${message.id} #######`);
+            // ✅ Report health: received a message
+            trackEvent?.();
+            // Check for duplicate message handling
+            if (activeMessages.has(messageKey)) {
+                error(`[MONITOR-HANDLER] ⚠️ WARNING: Duplicate message detected! messageKey=${messageKey}, this may cause duplicate dispatchers!`);
+            }
+            activeMessages.add(messageKey);
+            log(`[MONITOR-HANDLER] 📝 Active messages count: ${activeMessages.size}, messageKey: ${messageKey}`);
+            const task = async () => {
+                try {
+                    log(`[MONITOR-HANDLER] 🚀 Starting handleXYMessage for messageKey=${messageKey}`);
+                    await handleXYMessage({
+                        cfg,
+                        runtime,
+                        message,
+                        accountId, // ✅ Pass accountId ("default")
+                    });
+                    log(`[MONITOR-HANDLER] ✅ Completed handleXYMessage for messageKey=${messageKey}`);
+                }
+                catch (err) {
+                    // ✅ Only log error, don't re-throw to prevent gateway restart
+                    error(`XY gateway: error handling message from ${serverId}: ${String(err)}`);
+                }
+                finally {
+                    // Remove from active messages when done
+                    activeMessages.delete(messageKey);
+                    log(`[MONITOR-HANDLER] 🧹 Cleaned up messageKey=${messageKey}, remaining active: ${activeMessages.size}`);
+                }
+            };
+            void enqueue(sessionId, task).catch((err) => {
+                // Error already logged in task, this is for queue failures
+                error(`XY gateway: queue processing failed for session ${sessionId}: ${String(err)}`);
+                activeMessages.delete(messageKey);
+            });
+        };
+        const connectedHandler = (serverId) => {
+            if (!loggedServers.has(serverId)) {
+                log(`XY gateway: ${serverId} connected`);
+                loggedServers.add(serverId);
+            }
+            // ✅ Report health: connection established
+            trackEvent?.();
+            opts.setStatus?.({ connected: true });
+        };
+        const disconnectedHandler = (serverId) => {
+            console.warn(`XY gateway: ${serverId} disconnected`);
+            loggedServers.delete(serverId);
+            // ✅ Report disconnection status (only if all servers disconnected)
+            if (loggedServers.size === 0) {
+                opts.setStatus?.({ connected: false });
+            }
+        };
+        const errorHandler = (err, serverId) => {
+            error(`XY gateway: ${serverId} error: ${String(err)}`);
+        };
+        const cleanup = () => {
+            log("XY gateway: cleaning up...");
+            // 🔍 Diagnose before cleanup
+            console.log("🔍 [DIAGNOSTICS] Checking WebSocket managers before cleanup...");
+            diagnoseAllManagers();
+            // Stop health check interval
+            if (healthCheckInterval) {
+                clearInterval(healthCheckInterval);
+                healthCheckInterval = null;
+                console.log("⏸️  Stopped periodic health check");
+            }
+            // Remove event handlers to prevent duplicate calls on gateway restart
+            wsManager.off("message", messageHandler);
+            wsManager.off("connected", connectedHandler);
+            wsManager.off("disconnected", disconnectedHandler);
+            wsManager.off("error", errorHandler);
+            // ✅ Disconnect the wsManager to prevent connection leaks
+            // This is safe because each gateway lifecycle should have clean connections
+            wsManager.disconnect();
+            // ✅ Remove manager from cache to prevent reusing dirty state
+            removeXYWebSocketManager(account);
+            loggedServers.clear();
+            activeMessages.clear();
+            log(`[MONITOR-HANDLER] 🧹 Cleanup complete, cleared active messages`);
+            // 🔍 Diagnose after cleanup
+            console.log("🔍 [DIAGNOSTICS] Checking WebSocket managers after cleanup...");
+            diagnoseAllManagers();
+        };
+        const handleAbort = () => {
+            log("XY gateway: abort signal received, stopping");
+            // cleanup();
+            // log("XY gateway stopped");
+            resolve();
+        };
+        if (opts.abortSignal?.aborted) {
+            // cleanup();
+            resolve();
+            return;
+        }
+        opts.abortSignal?.addEventListener("abort", handleAbort, { once: true });
+        // Register event handlers (handlers are defined above in cleanup scope)
+        wsManager.on("message", messageHandler);
+        wsManager.on("connected", connectedHandler);
+        wsManager.on("disconnected", disconnectedHandler);
+        wsManager.on("error", errorHandler);
+        // Start periodic health check (every 5 minutes)
+        console.log("🏥 Starting periodic health check (every 5 minutes)...");
+        healthCheckInterval = setInterval(() => {
+            console.log("🏥 [HEALTH CHECK] Periodic WebSocket diagnostics...");
+            diagnoseAllManagers();
+            // Auto-cleanup orphan connections
+            const cleaned = cleanupOrphanConnections();
+            if (cleaned > 0) {
+                console.log(`🧹 [HEALTH CHECK] Auto-cleaned ${cleaned} manager(s) with orphan connections`);
+            }
+        }, 5 * 60 * 1000); // 5 minutes
+        // Connect to WebSocket servers
+        wsManager.connect()
+            .then(() => {
+            log("XY gateway: started successfully");
+        })
+            .catch((err) => {
+            // Connection failed but don't reject - continue monitoring for reconnection
+            error(`XY gateway: initial connection failed: ${String(err)}`);
+            // Still resolve successfully so plugin starts
+            resolve();
+        });
+    });
+}

package/dist/src/onboarding.d.ts

@@ -0,0 +1,6 @@
+import type { ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+/**
+ * XY Channel Onboarding Adapter
+ * Implements the ChannelOnboardingAdapter interface for OpenClaw's onboarding system
+ */
+export declare const xyOnboardingAdapter: ChannelOnboardingAdapter;

package/dist/src/onboarding.js

@@ -0,0 +1,173 @@
+const channel = "xiaoyi-channel";
+/**
+ * Check if XY channel is properly configured with required fields
+ */
+function isXYConfigured(cfg) {
+    try {
+        const xyConfig = cfg.channels?.["xiaoyi-channel"];
+        if (!xyConfig) {
+            return false;
+        }
+        // Check required fields
+        const requiredFields = ["apiKey", "agentId", "uid", "apiId", "pushId"];
+        for (const field of requiredFields) {
+            if (!xyConfig[field] || (typeof xyConfig[field] === "string" && !xyConfig[field].trim())) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get current status of XY channel configuration
+ */
+async function getStatus({ cfg }) {
+    const configured = isXYConfigured(cfg);
+    const xyConfig = cfg.channels?.["xiaoyi-channel"];
+    const statusLines = [];
+    if (configured) {
+        const wsUrl1 = xyConfig?.wsUrl1 || "ws://localhost:8765/ws/link";
+        const wsUrl2 = xyConfig?.wsUrl2 || "ws://localhost:8768/ws/link";
+        statusLines.push(`XY: configured (双 WebSocket: ${wsUrl1}, ${wsUrl2})`);
+    }
+    else {
+        statusLines.push("XY: 需要配置 (需要 apiKey, agentId, uid, apiId, pushId)");
+    }
+    return {
+        channel,
+        configured,
+        statusLines,
+        selectionHint: configured ? "configured" : "需要配置",
+        quickstartScore: configured ? 5 : 0,
+    };
+}
+/**
+ * Configure XY channel through interactive prompts
+ */
+async function configure({ cfg, prompter, }) {
+    // Note current configuration status
+    const currentConfig = cfg.channels?.["xiaoyi-channel"];
+    const isUpdate = Boolean(currentConfig);
+    await prompter.note([
+        "XY Channel - 小艺 A2A 协议配置",
+        "",
+        "XY 是小艺智能助手的 A2A (Agent-to-Agent) 协议集成，",
+        "需要配置双 WebSocket 连接和相关认证信息。",
+        "",
+        isUpdate ? "当前配置将被更新。" : "首次配置 XY channel。",
+    ].join("\n"), "XY Channel 配置");
+    // Prompt for WebSocket URLs
+    const wsUrl1 = await prompter.text({
+        message: "WebSocket URL 1 (主连接)",
+        initialValue: currentConfig?.wsUrl1 || "ws://localhost:8765/ws/link",
+        placeholder: "ws://localhost:8765/ws/link",
+    });
+    const wsUrl2 = await prompter.text({
+        message: "WebSocket URL 2 (辅助连接)",
+        initialValue: currentConfig?.wsUrl2 || "ws://localhost:8768/ws/link",
+        placeholder: "ws://localhost:8768/ws/link",
+    });
+    // Prompt for required authentication fields
+    const apiKey = await prompter.text({
+        message: "API Key (必需)",
+        initialValue: currentConfig?.apiKey || "",
+        placeholder: "输入小艺 API Key",
+        validate: (value) => (value.trim() ? undefined : "API Key 不能为空"),
+    });
+    const uid = await prompter.text({
+        message: "UID - 用户ID (必需)",
+        initialValue: currentConfig?.uid || "",
+        placeholder: "输入用户 ID",
+        validate: (value) => (value.trim() ? undefined : "UID 不能为空"),
+    });
+    const agentId = await prompter.text({
+        message: "Agent ID - 智能体ID (必需)",
+        initialValue: currentConfig?.agentId || "",
+        placeholder: "agent5336cca603f941ee9b112f711805e866",
+        validate: (value) => (value.trim() ? undefined : "Agent ID 不能为空"),
+    });
+    const apiId = await prompter.text({
+        message: "API ID (必需)",
+        initialValue: currentConfig?.apiId || "",
+        placeholder: "输入 API ID",
+        validate: (value) => (value.trim() ? undefined : "API ID 不能为空"),
+    });
+    const pushId = await prompter.text({
+        message: "Push ID (必需)",
+        initialValue: currentConfig?.pushId || "",
+        placeholder: "输入 Push ID",
+        validate: (value) => (value.trim() ? undefined : "Push ID 不能为空"),
+    });
+    // Optional fields
+    const fileUploadUrl = await prompter.text({
+        message: "File Upload URL (文件上传服务)",
+        initialValue: currentConfig?.fileUploadUrl || "http://localhost:8767",
+        placeholder: "http://localhost:8767",
+    });
+    const pushUrl = await prompter.text({
+        message: "Push URL (推送服务，可选)",
+        initialValue: currentConfig?.pushUrl || "",
+        placeholder: "留空使用默认值",
+    });
+    // Update configuration
+    const updatedConfig = {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            "xiaoyi-channel": {
+                enabled: true,
+                wsUrl1: wsUrl1.trim(),
+                wsUrl2: wsUrl2.trim(),
+                apiKey: apiKey.trim(),
+                uid: uid.trim(),
+                agentId: agentId.trim(),
+                apiId: apiId.trim(),
+                pushId: pushId.trim(),
+                fileUploadUrl: fileUploadUrl.trim(),
+                ...(pushUrl?.trim() ? { pushUrl: pushUrl.trim() } : {}),
+            },
+        },
+    };
+    // Show confirmation
+    await prompter.note([
+        "✅ XY Channel 配置完成",
+        "",
+        `主连接: ${wsUrl1}`,
+        `辅助连接: ${wsUrl2}`,
+        `Agent ID: ${agentId}`,
+        `UID: ${uid}`,
+        "",
+        "运行以下命令启动 gateway:",
+        "  openclaw gateway restart",
+        "",
+        "查看日志:",
+        "  openclaw logs --follow",
+    ].join("\n"), "配置成功");
+    return {
+        cfg: updatedConfig,
+        accountId: "default",
+    };
+}
+/**
+ * XY Channel Onboarding Adapter
+ * Implements the ChannelOnboardingAdapter interface for OpenClaw's onboarding system
+ */
+export const xyOnboardingAdapter = {
+    channel,
+    getStatus,
+    configure,
+    // Optional: disable the channel
+    disable: (cfg) => ({
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            "xiaoyi-channel": {
+                ...(cfg.channels?.["xiaoyi-channel"] || {}),
+                enabled: false,
+            },
+        },
+    }),
+};

package/dist/src/outbound.d.ts

@@ -0,0 +1,6 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+/**
+ * Outbound adapter for sending messages from OpenClaw to XY.
+ * Uses Push service for direct message delivery.
+ */
+export declare const xyOutbound: ChannelOutboundAdapter;