@rowger_go/chatu 0.1.3

package/src/sdk/adapters/websocket.ts

@@ -0,0 +1,378 @@
+/******************************************************************
+ * Channel SDK - WebSocket Adapter
+ * 
+ * OpenClaw Channel SDK 的 WebSocket 连接适配器
+ * 
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ ******************************************************************/
+
+import type {
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+  ConnectionConfig,
+  ConnectionStatus,
+  ChannelStats,
+} from '../types/channel';
+import type { ConnectionAdapter, MessageCallback, StatusCallback } from '../types/adapters';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * WebSocket 消息帧 [Channel SDK 标准]
+ */
+interface WebSocketFrame {
+  type: 'message' | 'heartbeat' | 'ack' | 'error' | 'open' | 'close';
+  channelId: string;
+  timestamp: number;
+  payload?: unknown;
+}
+
+/**
+ * WebSocket 连接适配器 [Channel SDK 标准]
+ * 
+ * 使用 WebSocket 进行实时通信
+ * 
+ * @example
+ * ```typescript
+ * const adapter = new WebSocketAdapter({
+ *   channelId: 'wh_ch_xxx',
+ *   accessToken: 'token_xxx',
+ * });
+ * 
+ * adapter.connect();
+ * adapter.onMessage((msg) => console.log(msg));
+ * ```
+ */
+export class WebSocketAdapter implements ConnectionAdapter {
+  /** 配置 [Channel SDK 标准] */
+  public config: ConnectionConfig;
+  
+  /** WebSocket 实例 [Channel SDK 标准] */
+  private ws: WebSocket | null = null;
+  
+  /** 当前状态 [Channel SDK 标准] */
+  private _status: ConnectionStatus = 'disconnected';
+  
+  /** 消息回调 [Channel SDK 标准] */
+  private messageCallbacks: Set<MessageCallback> = new Set();
+  
+  /** 状态回调 [Channel SDK 标准] */
+  private statusCallbacks: Set<StatusCallback> = new Set();
+  
+  /** 待确认消息 [Channel SDK 标准] */
+  private pendingMessages: Map<string, { timestamp: number; retryCount: number }> = new Map();
+  
+  /** 最后心跳时间 [Channel SDK 标准] */
+  private lastHeartbeat: number = 0;
+  
+  /** 心跳定时器 [Channel SDK 标准] */
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  
+  /** 重连定时器 [Channel SDK 标准] */
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  
+  /** 重连次数 [Channel SDK 标准] */
+  private reconnectAttempts: number = 0;
+
+  /** Plugin-Channel Realtime: whether first connect has succeeded */
+  private _wasConnected: boolean = false;
+
+  /** Plugin-Channel Realtime: callbacks fired on every successful reconnect (not initial connect) */
+  private reconnectedCallbacks: Set<() => void> = new Set();
+  
+  /** 统计 [Channel SDK 标准] */
+  private stats: ChannelStats = {
+    messagesSent: 0,
+    messagesReceived: 0,
+    connectedDuration: 0,
+    lastActiveAt: Date.now(),
+  };
+  
+  /**
+   * 创建 WebSocket 适配器 [Channel SDK 标准]
+   */
+  constructor(config: ConnectionConfig) {
+    this.config = {
+      heartbeatInterval: 30000,
+      heartbeatTimeout: 10000,
+      // Plugin-Channel Realtime: Infinity = unlimited retries (prod default)
+      maxReconnectAttempts: Infinity,
+      ...config,
+    };
+  }
+  
+  /** 当前状态 [Channel SDK 标准] */
+  get status(): ConnectionStatus {
+    return this._status;
+  }
+  
+  /**
+   * 建立连接 [Channel SDK 标准]
+   */
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // 使用 webhubUrl 构建 WebSocket URL
+      const webhubUrl = this.config.webhubUrl || 'wss://example.com/ws';
+      const url = new URL(webhubUrl);
+      url.searchParams.set('channelId', this.config.channelId);
+      url.searchParams.set('token', this.config.accessToken);
+      
+      this.ws = new WebSocket(url.toString());
+      
+      this.ws.onopen = () => {
+        this._status = 'connected';
+        this.reconnectAttempts = 0;
+        this.stats.connectedDuration = Date.now();
+        this.startHeartbeat();
+        this.notifyStatus('connected');
+        // Plugin-Channel Realtime: fire onReconnected on reconnect (not initial connect)
+        if (this._wasConnected) {
+          this.reconnectedCallbacks.forEach(cb => cb());
+        }
+        this._wasConnected = true;
+        resolve();
+      };
+      
+      this.ws.onmessage = (event) => {
+        try {
+          const frame = JSON.parse(event.data) as WebSocketFrame;
+          this.handleFrame(frame);
+        } catch (error) {
+          console.error('解析消息失败:', error);
+        }
+      };
+      
+      this.ws.onclose = () => {
+        this._status = 'disconnected';
+        this.stopHeartbeat();
+        this.notifyStatus('disconnected');
+        this.attemptReconnect();
+      };
+      
+      this.ws.onerror = (error: Event) => {
+        this._status = 'error';
+        this.notifyStatus('error', new Error('WebSocket error'));
+        reject(error);
+      };
+    });
+  }
+  
+  /**
+   * 断开连接 [Channel SDK 标准]
+   */
+  async disconnect(): Promise<void> {
+    this.stopHeartbeat();
+    this.stopReconnect();
+    
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    
+    this._status = 'disconnected';
+    this.notifyStatus('disconnected');
+  }
+  
+  /**
+   * 发送消息 [Channel SDK 标准]
+   */
+  async send(message: OutboundMessage): Promise<SendResult> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return {
+        messageId: message.messageId || uuidv4(),
+        success: false,
+        timestamp: Date.now(),
+        error: {
+          code: 'NOT_CONNECTED',
+          message: 'WebSocket 未连接',
+        },
+      };
+    }
+    
+    const messageId = message.messageId || uuidv4();
+    const frame: WebSocketFrame = {
+      type: 'message',
+      channelId: this.config.channelId,
+      timestamp: Date.now(),
+      payload: {
+        messageId,
+        ...message,
+      },
+    };
+    
+    // 加入待确认队列
+    this.pendingMessages.set(messageId, {
+      timestamp: Date.now(),
+      retryCount: 0,
+    });
+    
+    this.ws.send(JSON.stringify(frame));
+    
+    return {
+      messageId,
+      success: true,
+      timestamp: Date.now(),
+    };
+  }
+  
+  /**
+   * 订阅消息 [Channel SDK 标准]
+   */
+  onMessage(callback: MessageCallback): void {
+    this.messageCallbacks.add(callback);
+  }
+  
+  /**
+   * Plugin-Channel Realtime: Register a callback fired on every successful reconnect.
+   * Alias for onopen after the first connection. Use this for cache flush.
+   */
+  onReconnected(callback: () => void): void {
+    this.reconnectedCallbacks.add(callback);
+  }
+
+  /**
+   * 订阅状态变化 [Channel SDK 标准]
+   */
+  onStatusChange(callback: StatusCallback): void {
+    this.statusCallbacks.add(callback);
+  }
+  
+  /**
+   * 获取统计 [Channel SDK 标准]
+   */
+  async getStats(): Promise<ChannelStats> {
+    return { ...this.stats };
+  }
+  
+  /**
+   * 处理消息帧 [Channel SDK 标准]
+   */
+  private handleFrame(frame: WebSocketFrame): void {
+    switch (frame.type) {
+      case 'message':
+        this.handleMessage(frame);
+        break;
+      case 'heartbeat':
+        this.handleHeartbeat(frame);
+        break;
+      case 'ack':
+        this.handleAck(frame);
+        break;
+      case 'error':
+        this.handleError(frame);
+        break;
+    }
+  }
+  
+  /**
+   * 处理消息 [Channel SDK 标准]
+   */
+  private handleMessage(frame: WebSocketFrame): void {
+    const message = frame.payload as InboundMessage;
+    this.stats.messagesReceived++;
+    this.messageCallbacks.forEach((cb) => cb(message));
+  }
+  
+  /**
+   * 处理心跳 [Channel SDK 标准]
+   */
+  private handleHeartbeat(frame: WebSocketFrame): void {
+    this.lastHeartbeat = Date.now();
+    this.notifyStatus('connected');
+  }
+  
+  /**
+   * 处理确认 [Channel SDK 标准]
+   */
+  private handleAck(frame: WebSocketFrame): void {
+    const payload = frame.payload as { messageId?: string };
+    if (payload.messageId) {
+      this.pendingMessages.delete(payload.messageId);
+    }
+  }
+  
+  /**
+   * 处理错误 [Channel SDK 标准]
+   */
+  private handleError(frame: WebSocketFrame): void {
+    const error = frame.payload as { message?: string };
+    const err = new Error(error.message || '未知错误');
+    this.notifyStatus('error', err);
+  }
+  
+  /**
+   * 启动心跳 [Channel SDK 标准]
+   */
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeat();
+    }, this.config.heartbeatInterval);
+  }
+  
+  /**
+   * 停止心跳 [Channel SDK 标准]
+   */
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  
+  /**
+   * 发送心跳 [Channel SDK 标准]
+   */
+  private async sendHeartbeat(): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    
+    const frame: WebSocketFrame = {
+      type: 'heartbeat',
+      channelId: this.config.channelId,
+      timestamp: Date.now(),
+    };
+    
+    this.ws.send(JSON.stringify(frame));
+  }
+  
+  /**
+   * 尝试重连 [Channel SDK 标准]
+   */
+  private attemptReconnect(): void {
+    const maxAttempts = this.config.maxReconnectAttempts ?? Infinity;
+    // Plugin-Channel Realtime: support Infinity (unlimited retries)
+    if (maxAttempts !== Infinity && this.reconnectAttempts >= maxAttempts) {
+      this._status = 'error';
+      this.notifyStatus('error', new Error('重连次数过多'));
+      return;
+    }
+    
+    this.reconnectAttempts++;
+    // T008 Plugin-Channel SSE: exponential backoff with ±20% jitter
+    // delay = min(1000 × 2^n, 30000) × (0.8 + random × 0.4)
+    const baseDelay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
+    const delay = Math.round(baseDelay * (0.8 + Math.random() * 0.4));
+    
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch(() => {});
+    }, delay);
+  }
+  
+  /**
+   * 停止重连 [Channel SDK 标准]
+   */
+  private stopReconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+  
+  /**
+   * 通知状态变化 [Channel SDK 标准]
+   */
+  private notifyStatus(status: ConnectionStatus, error?: Error): void {
+    this.statusCallbacks.forEach((cb) => cb(status, error));
+  }
+}

package/src/sdk/core/channel.ts

@@ -0,0 +1,230 @@
+/******************************************************************
+ * Channel SDK - Channel Class
+ * 
+ * OpenClaw Channel SDK 的核心 Channel 类
+ * 
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ ******************************************************************/
+
+import {
+  InboundMessage,
+  OutboundMessage,
+  SendResult,
+  ConnectionConfig,
+  ConnectionStatus,
+  ChannelStats,
+  ChannelCapabilities,
+  TargetType,
+} from '../types/channel';
+import type {
+  ConnectionAdapter,
+  MessageCallback,
+  StatusCallback,
+  AdapterFactory,
+} from '../types/adapters';
+import { createDefaultFactory } from '../adapters/default';
+
+/**
+ * Channel 配置 [Channel SDK 标准]
+ */
+export interface ChannelOptions {
+  /** 连接配置 [Channel SDK 标准] */
+  config: ConnectionConfig;
+  
+  /** 适配器工厂 [Channel SDK 标准] */
+  adapterFactory?: AdapterFactory;
+  
+  /** 自动重连 [Channel SDK 标准] */
+  autoReconnect?: boolean;
+  
+  /** 自动发送心跳 [Channel SDK 标准] */
+  autoHeartbeat?: boolean;
+}
+
+/**
+ * Channel 类 [Channel SDK 标准]
+ * 
+ * Channel 的核心管理类，处理连接、消息收发等
+ * 
+ * @example
+ * ```typescript
+ * const channel = new Channel({
+ *   config: {
+ *     channelId: 'wh_ch_xxx',
+ *     accessToken: 'token_xxx',
+ *   }
+ * });
+ * 
+ * channel.connect();
+ * channel.onMessage((msg) => {
+ *   console.log('收到消息:', msg);
+ * });
+ * ```
+ */
+export class Channel {
+  /** 连接配置 [Channel SDK 标准] */
+  public readonly config: ConnectionConfig;
+  
+  /** 适配器工厂 [Channel SDK 标准] */
+  public readonly adapterFactory: AdapterFactory;
+  
+  /** 连接适配器 [Channel SDK 标准] */
+  private connectionAdapter: ConnectionAdapter;
+  
+  /** 消息回调列表 [Channel SDK 标准] */
+  private messageCallbacks: Set<MessageCallback>;
+  
+  /** 状态回调列表 [Channel SDK 标准] */
+  private statusCallbacks: Set<StatusCallback>;
+  
+  /** 是否已连接 [Channel SDK 标准] */
+  public get isConnected(): boolean {
+    return this.connectionAdapter.status === 'connected';
+  }
+  
+  /** 当前状态 [Channel SDK 标准] */
+  public get status(): ConnectionStatus {
+    return this.connectionAdapter.status;
+  }
+  
+  /** 统计信息 [Channel SDK 标准] */
+  private _stats: ChannelStats = {
+    messagesSent: 0,
+    messagesReceived: 0,
+    connectedDuration: 0,
+    lastActiveAt: Date.now(),
+  };
+  
+  /**
+   * 创建 Channel 实例 [Channel SDK 标准]
+   */
+  constructor(options: ChannelOptions) {
+    this.config = {
+      heartbeatInterval: 30000,
+      heartbeatTimeout: 10000,
+      maxReconnectAttempts: 3,
+      ...options.config,
+    };
+    
+    this.adapterFactory = options.adapterFactory || createDefaultFactory();
+    this.connectionAdapter = this.adapterFactory.createConnectionAdapter(this.config);
+    
+    this.messageCallbacks = new Set();
+    this.statusCallbacks = new Set();
+    
+    // 设置回调
+    this.connectionAdapter.onMessage((message) => {
+      this._stats.messagesReceived++;
+      this._stats.lastActiveAt = Date.now();
+      this.messageCallbacks.forEach((cb) => cb(message));
+    });
+    
+    this.connectionAdapter.onStatusChange((status, error) => {
+      this.statusCallbacks.forEach((cb) => cb(status, error));
+    });
+  }
+  
+  /**
+   * 连接到 Channel 服务 [Channel SDK 标准]
+   */
+  async connect(): Promise<void> {
+    await this.connectionAdapter.connect();
+  }
+  
+  /**
+   * 断开连接 [Channel SDK 标准]
+   */
+  async disconnect(): Promise<void> {
+    await this.connectionAdapter.disconnect();
+  }
+  
+  /**
+   * 发送消息 [Channel SDK 标准]
+   */
+  async send(message: OutboundMessage): Promise<SendResult> {
+    const result = await this.connectionAdapter.send(message);
+    
+    if (result.success) {
+      this._stats.messagesSent++;
+      this._stats.lastActiveAt = Date.now();
+    }
+    
+    return result;
+  }
+  
+  /**
+   * 发送文本消息 [Channel SDK 标准]
+   */
+  async sendText(
+    targetId: string,
+    text: string,
+    options?: {
+      type?: TargetType;
+      replyTo?: string;
+    }
+  ): Promise<SendResult> {
+    return this.send({
+      target: {
+        type: options?.type || TargetType.USER,
+        id: targetId,
+      },
+      content: {
+        text,
+        format: 'plain',
+      },
+      replyTo: options?.replyTo,
+    });
+  }
+  
+  /**
+   * 订阅消息 [Channel SDK 标准]
+   */
+  onMessage(callback: MessageCallback): () => void {
+    this.messageCallbacks.add(callback);
+    
+    // 返回取消订阅函数
+    return () => {
+      this.messageCallbacks.delete(callback);
+    };
+  }
+  
+  /**
+   * 订阅状态变化 [Channel SDK 标准]
+   */
+  onStatusChange(callback: StatusCallback): () => void {
+    this.statusCallbacks.add(callback);
+    
+    return () => {
+      this.statusCallbacks.delete(callback);
+    };
+  }
+  
+  /**
+   * 获取统计信息 [Channel SDK 标准]
+   */
+  async getStats(): Promise<ChannelStats> {
+    const adapterStats = await this.connectionAdapter.getStats();
+    
+    return {
+      ...this._stats,
+      ...adapterStats,
+    };
+  }
+  
+  /**
+   * 获取能力 [Channel SDK 标准]
+   */
+  async getCapabilities(): Promise<ChannelCapabilities> {
+    const adapter = this.adapterFactory.createCapabilitiesAdapter();
+    return adapter.getCapabilities();
+  }
+  
+  /**
+   * 销毁 Channel [Channel SDK 标准]
+   */
+  async destroy(): Promise<void> {
+    await this.disconnect();
+    this.messageCallbacks.clear();
+    this.statusCallbacks.clear();
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,36 @@
+/******************************************************************
+ * Channel SDK - Entry Point
+ * 
+ * OpenClaw Channel SDK 入口文件
+ * 
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ ******************************************************************/
+
+// 导出类型
+export * from './types/channel';
+export * from './types/adapters';
+
+// 导出核心类
+export * from './core/channel';
+
+// 导出适配器
+export * from './adapters/websocket';
+export * from './adapters/default';
+export * from './adapters/webhub';
+
+/******************************************************************
+ * Channel SDK - Message Class (Placeholder)
+ ******************************************************************/
+
+export interface Message {
+  id: string;
+  content: string;
+}
+
+/******************************************************************
+ * Channel SDK - Connection Class (Placeholder)
+ ******************************************************************/
+
+export interface Connection {
+  status: string;
+}