@hangox/mg-cli 1.0.0

package/src/server/request-handler.ts

@@ -0,0 +1,192 @@
+/**
+ * 请求处理器
+ * 处理 Consumer 请求，转发给 Provider
+ */
+
+import type { ManagedWebSocket } from './connection-manager.js'
+import { ConnectionManager } from './connection-manager.js'
+import { Logger } from './logger.js'
+import { MessageType, REQUEST_TIMEOUT } from '../shared/constants.js'
+import { ErrorCode, MGError } from '../shared/errors.js'
+import type { RequestMessage, ResponseMessage } from '../shared/types.js'
+import { generateId } from '../shared/utils.js'
+
+/** 待处理的请求 */
+interface PendingRequest {
+  /** 请求 ID */
+  id: string
+  /** Consumer WebSocket */
+  consumer: ManagedWebSocket
+  /** 超时定时器 */
+  timer: NodeJS.Timeout
+  /** 请求时间 */
+  timestamp: number
+}
+
+/**
+ * 请求处理器
+ */
+export class RequestHandler {
+  private logger: Logger
+  private connectionManager: ConnectionManager
+
+  /** 待处理的请求 */
+  private pendingRequests = new Map<string, PendingRequest>()
+
+  constructor(connectionManager: ConnectionManager, logger: Logger) {
+    this.connectionManager = connectionManager
+    this.logger = logger
+  }
+
+  /**
+   * 处理 Consumer 请求
+   */
+  async handleRequest(consumer: ManagedWebSocket, message: RequestMessage): Promise<void> {
+    const requestId = message.id || generateId()
+    const { type, pageUrl, params } = message
+
+    this.logger.info(`收到请求: ${type} (${requestId})`, { pageUrl })
+
+    // 查找目标 Provider
+    let provider: ManagedWebSocket | undefined
+
+    if (pageUrl) {
+      provider = this.connectionManager.findProviderByPageUrl(pageUrl)
+      if (!provider) {
+        this.sendError(consumer, requestId, ErrorCode.PAGE_NOT_FOUND, `未找到页面: ${pageUrl}`)
+        return
+      }
+    } else {
+      // 没有指定 pageUrl，使用第一个可用的 Provider
+      provider = this.connectionManager.getFirstProvider()
+      if (!provider) {
+        this.sendError(consumer, requestId, ErrorCode.NO_PAGE_CONNECTED, '没有页面连接到 Server')
+        return
+      }
+    }
+
+    // 创建超时定时器
+    const timer = setTimeout(() => {
+      this.handleTimeout(requestId)
+    }, REQUEST_TIMEOUT)
+
+    // 保存待处理请求
+    this.pendingRequests.set(requestId, {
+      id: requestId,
+      consumer,
+      timer,
+      timestamp: Date.now(),
+    })
+
+    // 转发请求给 Provider
+    const forwardMessage: RequestMessage = {
+      id: requestId,
+      type,
+      pageUrl: pageUrl || provider.connectionInfo.pageUrl,
+      params,
+      timestamp: Date.now(),
+    }
+
+    try {
+      provider.send(JSON.stringify(forwardMessage))
+      this.logger.info(`请求转发: ${type} -> ${provider.connectionInfo.pageUrl}`)
+    } catch {
+      this.cleanupRequest(requestId)
+      this.sendError(consumer, requestId, ErrorCode.CONNECTION_FAILED, '转发请求失败')
+    }
+  }
+
+  /**
+   * 处理 Provider 响应
+   */
+  handleResponse(response: ResponseMessage): void {
+    const { id } = response
+    const pending = this.pendingRequests.get(id)
+
+    if (!pending) {
+      this.logger.warn(`收到未知请求的响应: ${id}`)
+      return
+    }
+
+    this.cleanupRequest(id)
+
+    // 转发响应给 Consumer
+    try {
+      pending.consumer.send(JSON.stringify(response))
+      this.logger.info(
+        `响应返回: ${id} (${response.success ? '成功' : '失败'})`
+      )
+    } catch (error) {
+      this.logger.error(`响应转发失败: ${id}`, error)
+    }
+  }
+
+  /**
+   * 处理请求超时
+   */
+  private handleTimeout(requestId: string): void {
+    const pending = this.pendingRequests.get(requestId)
+    if (!pending) return
+
+    this.logger.warn(`请求超时: ${requestId}`)
+    this.cleanupRequest(requestId)
+
+    this.sendError(pending.consumer, requestId, ErrorCode.REQUEST_TIMEOUT, '请求超时')
+  }
+
+  /**
+   * 清理请求
+   */
+  private cleanupRequest(requestId: string): void {
+    const pending = this.pendingRequests.get(requestId)
+    if (pending) {
+      clearTimeout(pending.timer)
+      this.pendingRequests.delete(requestId)
+    }
+  }
+
+  /**
+   * 发送错误响应
+   */
+  private sendError(
+    consumer: ManagedWebSocket,
+    requestId: string,
+    code: ErrorCode,
+    message: string
+  ): void {
+    const error = new MGError(code, message)
+    const response: ResponseMessage = {
+      id: requestId,
+      type: MessageType.ERROR,
+      success: false,
+      data: null,
+      error: error.toJSON(),
+    }
+
+    try {
+      consumer.send(JSON.stringify(response))
+    } catch (err) {
+      this.logger.error(`发送错误响应失败: ${requestId}`, err)
+    }
+  }
+
+  /**
+   * 清理特定连接的所有待处理请求
+   */
+  cleanupConnectionRequests(connectionId: string): void {
+    for (const [requestId, pending] of this.pendingRequests) {
+      if (pending.consumer.connectionId === connectionId) {
+        this.cleanupRequest(requestId)
+      }
+    }
+  }
+
+  /**
+   * 清理所有待处理请求
+   */
+  cleanupAll(): void {
+    for (const [requestId] of this.pendingRequests) {
+      this.cleanupRequest(requestId)
+    }
+  }
+}

package/src/server/websocket-server.ts

@@ -0,0 +1,297 @@
+/**
+ * WebSocket 服务器
+ */
+
+import { WebSocketServer, WebSocket } from 'ws'
+import type { IncomingMessage } from 'node:http'
+import {
+  ConnectionType,
+  MessageType,
+  DEFAULT_PORT,
+  PORT_RANGE_START,
+  PORT_RANGE_END,
+  HEARTBEAT_INTERVAL,
+} from '../shared/constants.js'
+import { ErrorCode, MGError } from '../shared/errors.js'
+import type { BaseMessage, RegisterMessage, ResponseMessage } from '../shared/types.js'
+import { Logger, createLogger } from './logger.js'
+import { ConnectionManager, ManagedWebSocket } from './connection-manager.js'
+import { RequestHandler } from './request-handler.js'
+
+export interface ServerOptions {
+  /** 监听端口 */
+  port?: number
+  /** 日志选项 */
+  logger?: Logger
+}
+
+/**
+ * MG WebSocket 服务器
+ */
+export class MGServer {
+  private wss: WebSocketServer | null = null
+  private logger: Logger
+  private connectionManager: ConnectionManager
+  private requestHandler: RequestHandler
+
+  private port: number
+  private isRunning = false
+
+  constructor(options: ServerOptions = {}) {
+    this.port = options.port || DEFAULT_PORT
+    this.logger = options.logger || createLogger()
+    this.connectionManager = new ConnectionManager(this.logger)
+    this.requestHandler = new RequestHandler(this.connectionManager, this.logger)
+  }
+
+  /**
+   * 启动服务器
+   */
+  async start(): Promise<number> {
+    if (this.isRunning) {
+      throw new MGError(ErrorCode.SERVER_ALREADY_RUNNING, 'Server 已在运行中')
+    }
+
+    // 尝试绑定端口
+    const port = await this.findAvailablePort()
+
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({ port })
+
+      this.wss.on('listening', () => {
+        this.port = port
+        this.isRunning = true
+        this.logger.info(`Server 启动成功，监听端口: ${port}`)
+
+        // 启动心跳检查
+        this.connectionManager.startHeartbeatCheck(HEARTBEAT_INTERVAL)
+
+        resolve(port)
+      })
+
+      this.wss.on('error', (error: NodeJS.ErrnoException) => {
+        this.logger.error('Server 错误:', error)
+        reject(error)
+      })
+
+      this.wss.on('connection', (ws: WebSocket, request: IncomingMessage) => {
+        this.handleConnection(ws, request)
+      })
+    })
+  }
+
+  /**
+   * 查找可用端口
+   */
+  private async findAvailablePort(): Promise<number> {
+    for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+      const available = await this.isPortAvailable(port)
+      if (available) {
+        return port
+      }
+      this.logger.debug(`端口 ${port} 被占用，尝试下一个`)
+    }
+
+    throw new MGError(
+      ErrorCode.PORT_EXHAUSTED,
+      `端口 ${PORT_RANGE_START}-${PORT_RANGE_END} 均被占用`
+    )
+  }
+
+  /**
+   * 检查端口是否可用
+   */
+  private isPortAvailable(port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      const testServer = new WebSocketServer({ port })
+
+      testServer.on('listening', () => {
+        testServer.close()
+        resolve(true)
+      })
+
+      testServer.on('error', () => {
+        resolve(false)
+      })
+    })
+  }
+
+  /**
+   * 处理新连接
+   */
+  private handleConnection(ws: WebSocket, _request: IncomingMessage): void {
+    this.logger.info('新连接建立')
+
+    // 等待注册消息
+    const registerTimeout = setTimeout(() => {
+      this.logger.warn('连接注册超时，关闭连接')
+      ws.close()
+    }, 5000)
+
+    ws.on('message', (data) => {
+      try {
+        const message = JSON.parse(data.toString()) as BaseMessage
+
+        // 处理注册消息
+        if (message.type === MessageType.REGISTER) {
+          clearTimeout(registerTimeout)
+          this.handleRegister(ws, message as RegisterMessage)
+          return
+        }
+
+        // 其他消息需要已注册
+        const managedWs = ws as ManagedWebSocket
+        if (!managedWs.connectionId) {
+          this.logger.warn('未注册的连接发送消息，忽略')
+          return
+        }
+
+        this.handleMessage(managedWs, message)
+      } catch (error) {
+        this.logger.error('消息解析失败:', error)
+      }
+    })
+
+    ws.on('close', () => {
+      clearTimeout(registerTimeout)
+      const managedWs = ws as ManagedWebSocket
+      if (managedWs.connectionId) {
+        this.requestHandler.cleanupConnectionRequests(managedWs.connectionId)
+        this.connectionManager.removeConnection(managedWs)
+      }
+    })
+
+    ws.on('error', (error) => {
+      this.logger.error('WebSocket 错误:', error)
+    })
+  }
+
+  /**
+   * 处理注册消息
+   */
+  private handleRegister(ws: WebSocket, message: RegisterMessage): void {
+    const { connectionType, pageUrl, pageId } = message.data
+
+    const managedWs = this.connectionManager.addConnection(
+      ws,
+      connectionType,
+      pageUrl,
+      pageId
+    )
+
+    // 发送注册确认
+    const ack: ResponseMessage = {
+      id: message.id || '',
+      type: MessageType.REGISTER_ACK,
+      success: true,
+      data: {
+        connectionId: managedWs.connectionId,
+        pageUrl,
+      },
+    }
+
+    ws.send(JSON.stringify(ack))
+  }
+
+  /**
+   * 处理消息
+   */
+  private handleMessage(ws: ManagedWebSocket, message: BaseMessage): void {
+    this.connectionManager.updateLastActive(ws)
+
+    switch (message.type) {
+      case MessageType.PING:
+        this.handlePing(ws, message)
+        break
+
+      case MessageType.RESPONSE:
+      case MessageType.ERROR:
+        // Provider 返回的响应
+        this.requestHandler.handleResponse(message as ResponseMessage)
+        break
+
+      default:
+        // Consumer 发送的请求
+        if (ws.connectionInfo.type === ConnectionType.CONSUMER) {
+          this.requestHandler.handleRequest(ws, message as any)
+        }
+        break
+    }
+  }
+
+  /**
+   * 处理心跳
+   */
+  private handlePing(ws: ManagedWebSocket, message: BaseMessage): void {
+    const pong = {
+      type: MessageType.PONG,
+      timestamp: (message as any).timestamp || Date.now(),
+    }
+    ws.send(JSON.stringify(pong))
+  }
+
+  /**
+   * 停止服务器
+   */
+  async stop(): Promise<void> {
+    if (!this.isRunning || !this.wss) {
+      return
+    }
+
+    this.logger.info('正在停止 Server...')
+
+    // 清理所有请求
+    this.requestHandler.cleanupAll()
+
+    // 关闭所有连接
+    this.connectionManager.closeAll()
+
+    // 关闭服务器
+    return new Promise((resolve) => {
+      this.wss!.close(() => {
+        this.isRunning = false
+        this.wss = null
+        this.logger.info('Server 已停止')
+        resolve()
+      })
+    })
+  }
+
+  /**
+   * 获取运行状态
+   */
+  getStatus(): {
+    running: boolean
+    port: number
+    stats: { providers: number; consumers: number; total: number }
+    connectedPages: string[]
+  } {
+    return {
+      running: this.isRunning,
+      port: this.port,
+      stats: this.connectionManager.getStats(),
+      connectedPages: this.connectionManager.getConnectedPageUrls(),
+    }
+  }
+
+  /**
+   * 获取端口
+   */
+  getPort(): number {
+    return this.port
+  }
+
+  /**
+   * 是否运行中
+   */
+  isServerRunning(): boolean {
+    return this.isRunning
+  }
+}
+
+/**
+ * 创建服务器实例
+ */
+export function createServer(options?: ServerOptions): MGServer {
+  return new MGServer(options)
+}

package/src/shared/constants.ts

@@ -0,0 +1,90 @@
+/**
+ * MG Plugin 常量定义
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// ==================== 端口配置 ====================
+
+/** 默认端口 */
+export const DEFAULT_PORT = 9527
+
+/** 端口范围：起始 */
+export const PORT_RANGE_START = 9527
+
+/** 端口范围：结束 */
+export const PORT_RANGE_END = 9536
+
+/** 最大尝试端口数 */
+export const MAX_PORT_ATTEMPTS = 10
+
+/** 端口扫描超时（毫秒） */
+export const PORT_SCAN_TIMEOUT = 500
+
+// ==================== 路径配置 ====================
+
+/** 配置目录 */
+export const CONFIG_DIR = join(homedir(), '.mg-plugin')
+
+/** Server 状态文件 */
+export const SERVER_INFO_FILE = join(CONFIG_DIR, 'server.json')
+
+/** 日志目录 */
+export const LOG_DIR = join(CONFIG_DIR, 'logs')
+
+/** Server 日志文件 */
+export const SERVER_LOG_FILE = join(LOG_DIR, 'server.log')
+
+// ==================== 超时配置 ====================
+
+/** 心跳间隔（毫秒）- 30 秒 */
+export const HEARTBEAT_INTERVAL = 30000
+
+/** 心跳超时（毫秒）- 90 秒（3 次心跳） */
+export const HEARTBEAT_TIMEOUT = 90000
+
+/** 请求超时（毫秒）- 30 秒 */
+export const REQUEST_TIMEOUT = 30000
+
+/** Server 启动等待超时（毫秒）- 5 秒 */
+export const SERVER_START_TIMEOUT = 5000
+
+/** CLI 重试间隔（毫秒） */
+export const RETRY_INTERVALS = [1000, 2000, 4000]
+
+/** 最大重试次数 */
+export const MAX_RETRY_COUNT = 3
+
+// ==================== 连接类型 ====================
+
+/** 连接类型 */
+export enum ConnectionType {
+  /** 获取端 (CLI/MCP) */
+  CONSUMER = 'consumer',
+  /** 提供端 (Injector) */
+  PROVIDER = 'provider',
+}
+
+// ==================== 消息类型 ====================
+
+/** WebSocket 消息类型 */
+export enum MessageType {
+  // 系统消息
+  PING = 'ping',
+  PONG = 'pong',
+  REGISTER = 'register',
+  REGISTER_ACK = 'register_ack',
+
+  // 业务消息
+  GET_NODE_BY_ID = 'get_node_by_id',
+  GET_ALL_NODES = 'get_all_nodes',
+  GET_SELECTION = 'get_selection',
+  EXPORT_IMAGE = 'export_image',
+  EXECUTE_CODE = 'execute_code',
+  GET_ALL_PAGES = 'get_all_pages',
+
+  // 响应
+  RESPONSE = 'response',
+  ERROR = 'error',
+}

package/src/shared/errors.ts

@@ -0,0 +1,131 @@
+/**
+ * MG Plugin 错误码定义
+ */
+
+/** 错误码枚举 */
+export enum ErrorCode {
+  /** 无法连接到 MG Server */
+  CONNECTION_FAILED = 'E001',
+  /** 连接超时 */
+  CONNECTION_TIMEOUT = 'E002',
+  /** 没有 MasterGo 页面连接到 Server */
+  NO_PAGE_CONNECTED = 'E003',
+  /** 未找到匹配的页面 */
+  PAGE_NOT_FOUND = 'E004',
+  /** 节点不存在 */
+  NODE_NOT_FOUND = 'E005',
+  /** 没有选中任何节点 */
+  NO_SELECTION = 'E006',
+  /** mg 对象不可用 */
+  MG_UNAVAILABLE = 'E007',
+  /** 导出图片失败 */
+  EXPORT_FAILED = 'E008',
+  /** 文件写入失败 */
+  FILE_WRITE_FAILED = 'E009',
+  /** 无效的 mgp:// 链接格式 */
+  INVALID_LINK = 'E010',
+  /** 参数校验失败 */
+  INVALID_PARAMS = 'E011',
+  /** 请求超时 */
+  REQUEST_TIMEOUT = 'E012',
+  /** 所有备选端口均被占用 */
+  PORT_EXHAUSTED = 'E013',
+  /** 无法发现 Server (端口扫描失败) */
+  SERVER_DISCOVERY_FAILED = 'E014',
+  /** 自动启动 Server 失败 */
+  SERVER_START_FAILED = 'E015',
+  /** Server 已在运行中 */
+  SERVER_ALREADY_RUNNING = 'E016',
+  /** 连接断开 */
+  CONNECTION_LOST = 'E017',
+  /** 未知错误 */
+  UNKNOWN_ERROR = 'E099',
+}
+
+/** 错误码对应的错误名称 */
+export const ErrorNames: Record<ErrorCode, string> = {
+  [ErrorCode.CONNECTION_FAILED]: 'CONNECTION_FAILED',
+  [ErrorCode.CONNECTION_TIMEOUT]: 'CONNECTION_TIMEOUT',
+  [ErrorCode.NO_PAGE_CONNECTED]: 'NO_PAGE_CONNECTED',
+  [ErrorCode.PAGE_NOT_FOUND]: 'PAGE_NOT_FOUND',
+  [ErrorCode.NODE_NOT_FOUND]: 'NODE_NOT_FOUND',
+  [ErrorCode.NO_SELECTION]: 'NO_SELECTION',
+  [ErrorCode.MG_UNAVAILABLE]: 'MG_UNAVAILABLE',
+  [ErrorCode.EXPORT_FAILED]: 'EXPORT_FAILED',
+  [ErrorCode.FILE_WRITE_FAILED]: 'FILE_WRITE_FAILED',
+  [ErrorCode.INVALID_LINK]: 'INVALID_LINK',
+  [ErrorCode.INVALID_PARAMS]: 'INVALID_PARAMS',
+  [ErrorCode.REQUEST_TIMEOUT]: 'REQUEST_TIMEOUT',
+  [ErrorCode.PORT_EXHAUSTED]: 'PORT_EXHAUSTED',
+  [ErrorCode.SERVER_DISCOVERY_FAILED]: 'SERVER_DISCOVERY_FAILED',
+  [ErrorCode.SERVER_START_FAILED]: 'SERVER_START_FAILED',
+  [ErrorCode.SERVER_ALREADY_RUNNING]: 'SERVER_ALREADY_RUNNING',
+  [ErrorCode.CONNECTION_LOST]: 'CONNECTION_LOST',
+  [ErrorCode.UNKNOWN_ERROR]: 'UNKNOWN_ERROR',
+}
+
+/** 错误码对应的默认消息 */
+export const ErrorMessages: Record<ErrorCode, string> = {
+  [ErrorCode.CONNECTION_FAILED]: '无法连接到 MG Server',
+  [ErrorCode.CONNECTION_TIMEOUT]: '连接超时',
+  [ErrorCode.NO_PAGE_CONNECTED]: '没有 MasterGo 页面连接到 Server',
+  [ErrorCode.PAGE_NOT_FOUND]: '未找到匹配的页面',
+  [ErrorCode.NODE_NOT_FOUND]: '节点不存在',
+  [ErrorCode.NO_SELECTION]: '没有选中任何节点',
+  [ErrorCode.MG_UNAVAILABLE]: 'mg 对象不可用',
+  [ErrorCode.EXPORT_FAILED]: '导出图片失败',
+  [ErrorCode.FILE_WRITE_FAILED]: '文件写入失败',
+  [ErrorCode.INVALID_LINK]: '无效的 mgp:// 链接格式',
+  [ErrorCode.INVALID_PARAMS]: '参数校验失败',
+  [ErrorCode.REQUEST_TIMEOUT]: '请求超时',
+  [ErrorCode.PORT_EXHAUSTED]: '所有备选端口均被占用',
+  [ErrorCode.SERVER_DISCOVERY_FAILED]: '无法发现 Server (端口扫描失败)',
+  [ErrorCode.SERVER_START_FAILED]: '自动启动 Server 失败',
+  [ErrorCode.SERVER_ALREADY_RUNNING]: 'Server 已在运行中',
+  [ErrorCode.CONNECTION_LOST]: '连接断开',
+  [ErrorCode.UNKNOWN_ERROR]: '未知错误',
+}
+
+/** MG Plugin 错误类 */
+export class MGError extends Error {
+  /** 错误码 */
+  code: ErrorCode
+  /** 错误名称 */
+  errorName: string
+  /** 额外详情 */
+  details?: Record<string, unknown>
+
+  constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>) {
+    super(message || ErrorMessages[code])
+    this.name = 'MGError'
+    this.code = code
+    this.errorName = ErrorNames[code]
+    this.details = details
+  }
+
+  /** 转换为 JSON 格式 */
+  toJSON() {
+    return {
+      code: this.code,
+      name: this.errorName,
+      message: this.message,
+      details: this.details,
+    }
+  }
+
+  /** 格式化输出 */
+  toString() {
+    return `错误 [${this.code}]: ${this.message}`
+  }
+}
+
+/**
+ * 创建错误
+ */
+export function createError(
+  code: ErrorCode,
+  message?: string,
+  details?: Record<string, unknown>
+): MGError {
+  return new MGError(code, message, details)
+}

package/src/shared/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 共享模块导出
+ */
+
+export * from './constants.js'
+export * from './errors.js'
+export * from './types.js'
+export * from './utils.js'