@hangox/mg-cli 1.0.0 → 1.0.1

package/dist/index-DNrszrq9.d.ts

@@ -0,0 +1,568 @@
+import { WebSocket } from 'ws';
+
+/**
+ * MG Plugin 常量定义
+ */
+/** 默认端口 */
+declare const DEFAULT_PORT = 9527;
+/** 端口范围：起始 */
+declare const PORT_RANGE_START = 9527;
+/** 端口范围：结束 */
+declare const PORT_RANGE_END = 9536;
+/** 最大尝试端口数 */
+declare const MAX_PORT_ATTEMPTS = 10;
+/** 端口扫描超时（毫秒） */
+declare const PORT_SCAN_TIMEOUT = 500;
+/** 配置目录 */
+declare const CONFIG_DIR: string;
+/** Server 状态文件 */
+declare const SERVER_INFO_FILE: string;
+/** 日志目录 */
+declare const LOG_DIR: string;
+/** Server 日志文件 */
+declare const SERVER_LOG_FILE: string;
+/** 心跳间隔（毫秒）- 30 秒 */
+declare const HEARTBEAT_INTERVAL = 30000;
+/** 心跳超时（毫秒）- 90 秒（3 次心跳） */
+declare const HEARTBEAT_TIMEOUT = 90000;
+/** 请求超时（毫秒）- 30 秒 */
+declare const REQUEST_TIMEOUT = 30000;
+/** Server 启动等待超时（毫秒）- 5 秒 */
+declare const SERVER_START_TIMEOUT = 5000;
+/** CLI 重试间隔（毫秒） */
+declare const RETRY_INTERVALS: number[];
+/** 最大重试次数 */
+declare const MAX_RETRY_COUNT = 3;
+/** 连接类型 */
+declare enum ConnectionType {
+    /** 获取端 (CLI/MCP) */
+    CONSUMER = "consumer",
+    /** 提供端 (Injector) */
+    PROVIDER = "provider"
+}
+/** WebSocket 消息类型 */
+declare 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"
+}
+
+/**
+ * MG Plugin 错误码定义
+ */
+/** 错误码枚举 */
+declare 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"
+}
+/** 错误码对应的错误名称 */
+declare const ErrorNames: Record<ErrorCode, string>;
+/** 错误码对应的默认消息 */
+declare const ErrorMessages: Record<ErrorCode, string>;
+/** MG Plugin 错误类 */
+declare class MGError extends Error {
+    /** 错误码 */
+    code: ErrorCode;
+    /** 错误名称 */
+    errorName: string;
+    /** 额外详情 */
+    details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message?: string, details?: Record<string, unknown>);
+    /** 转换为 JSON 格式 */
+    toJSON(): {
+        code: ErrorCode;
+        name: string;
+        message: string;
+        details: Record<string, unknown> | undefined;
+    };
+    /** 格式化输出 */
+    toString(): string;
+}
+/**
+ * 创建错误
+ */
+declare function createError(code: ErrorCode, message?: string, details?: Record<string, unknown>): MGError;
+
+/**
+ * MG Plugin 类型定义
+ */
+
+/** Server 运行信息 */
+interface ServerInfo {
+    /** 监听端口 */
+    port: number;
+    /** 进程 ID */
+    pid: number;
+    /** 启动时间 (ISO 8601) */
+    startedAt: string;
+}
+/** 基础消息结构 */
+interface BaseMessage {
+    /** 消息 ID */
+    id?: string;
+    /** 消息类型 */
+    type: MessageType | string;
+    /** 时间戳 */
+    timestamp?: number;
+}
+/** 请求消息 */
+interface RequestMessage extends BaseMessage {
+    /** 目标页面 URL（标准化后的） */
+    pageUrl?: string;
+    /** 请求参数 */
+    params?: Record<string, unknown>;
+}
+/** 响应消息 */
+interface ResponseMessage extends BaseMessage {
+    /** 对应请求的 ID */
+    id: string;
+    /** 是否成功 */
+    success: boolean;
+    /** 成功时的数据 */
+    data?: unknown;
+    /** 失败时的错误信息 */
+    error?: ErrorInfo | null;
+}
+/** 错误信息 */
+interface ErrorInfo {
+    /** 错误码 */
+    code: ErrorCode;
+    /** 错误名称 */
+    name: string;
+    /** 错误消息 */
+    message: string;
+    /** 额外详情 */
+    details?: Record<string, unknown>;
+}
+/** 注册消息 */
+interface RegisterMessage extends BaseMessage {
+    type: 'register';
+    data: {
+        /** 连接类型 */
+        connectionType: ConnectionType;
+        /** 页面 URL（Provider 必需） */
+        pageUrl?: string;
+        /** 页面唯一 ID */
+        pageId?: string;
+    };
+}
+/** 心跳消息 */
+interface PingMessage extends BaseMessage {
+    type: 'ping';
+    timestamp: number;
+}
+interface PongMessage extends BaseMessage {
+    type: 'pong';
+    timestamp: number;
+}
+/** 连接信息 */
+interface ConnectionInfo {
+    /** 连接 ID */
+    id: string;
+    /** 连接类型 */
+    type: ConnectionType;
+    /** 页面 URL（仅 Provider） */
+    pageUrl?: string;
+    /** 页面 ID（仅 Provider） */
+    pageId?: string;
+    /** 连接时间 */
+    connectedAt: Date;
+    /** 最后活跃时间 */
+    lastActiveAt: Date;
+}
+/** 节点信息（简化版） */
+interface NodeInfo {
+    /** 节点 ID */
+    id: string;
+    /** 节点名称 */
+    name: string;
+    /** 节点类型 */
+    type: string;
+    /** 是否可见 */
+    visible: boolean;
+    /** X 坐标 */
+    x?: number;
+    /** Y 坐标 */
+    y?: number;
+    /** 宽度 */
+    width?: number;
+    /** 高度 */
+    height?: number;
+    /** 子节点 */
+    children?: NodeInfo[];
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/** 获取节点参数 */
+interface GetNodeParams {
+    /** 节点 ID */
+    nodeId: string;
+    /** 遍历深度 */
+    maxDepth?: number;
+    /** 是否包含不可见节点 */
+    includeInvisible?: boolean;
+    /** 索引签名 */
+    [key: string]: unknown;
+}
+/** 获取所有节点参数 */
+interface GetAllNodesParams {
+    /** 遍历深度 */
+    maxDepth?: number;
+    /** 是否包含不可见节点 */
+    includeInvisible?: boolean;
+    /** 索引签名 */
+    [key: string]: unknown;
+}
+/** 导出图片参数 */
+interface ExportImageParams {
+    /** 节点 ID（可选，默认第一个选中节点） */
+    nodeId?: string;
+    /** 导出格式 */
+    format?: 'PNG' | 'JPG' | 'SVG' | 'PDF' | 'WEBP';
+    /** 缩放倍率 */
+    scale?: number;
+    /** 固定宽度 */
+    width?: number;
+    /** 固定高度 */
+    height?: number;
+    /** 是否使用完整尺寸 */
+    useAbsoluteBounds?: boolean;
+    /** 是否包含特效和外描边 */
+    useRenderBounds?: boolean;
+}
+/** CLI 输出格式化函数类型 */
+type OutputFormatter = (data: Record<string, unknown>) => void;
+/** CLI 命令选项 */
+interface CliOptions {
+    /** 输出文件路径 */
+    output?: string;
+    /** 遍历深度 */
+    maxDepth?: number;
+    /** 包含不可见节点 */
+    includeInvisible?: boolean;
+    /** 禁用自动重试 */
+    noRetry?: boolean;
+    /** 禁用自动启动 Server */
+    noAutoStart?: boolean;
+    /** Server 端口 */
+    port?: number;
+    /** 前台模式运行 */
+    foreground?: boolean;
+}
+/** RGBA 颜色 */
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** 单个页面信息 */
+interface MgPageInfo {
+    /** 页面 ID */
+    id: string;
+    /** 页面名称 */
+    name: string;
+    /** 页面背景色 */
+    bgColor?: RGBA;
+    /** 直接子节点数量 */
+    childCount: number;
+}
+/** 所有页面信息 */
+interface AllPagesInfo {
+    /** 文档 ID */
+    documentId: string;
+    /** 文档名称 */
+    documentName: string;
+    /** 页面列表 */
+    pages: MgPageInfo[];
+    /** 页面总数 */
+    totalCount: number;
+}
+
+/**
+ * 日志模块
+ */
+declare enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+interface LoggerOptions {
+    /** 是否输出到控制台 */
+    console?: boolean;
+    /** 是否输出到文件 */
+    file?: boolean;
+    /** 日志文件路径 */
+    filePath?: string;
+    /** 最小日志级别 */
+    minLevel?: LogLevel;
+}
+/**
+ * 日志记录器
+ */
+declare class Logger {
+    private options;
+    constructor(options?: LoggerOptions);
+    /**
+     * 记录日志
+     */
+    private log;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** 创建默认日志记录器 */
+declare function createLogger(options?: LoggerOptions): Logger;
+
+/**
+ * WebSocket 服务器
+ */
+
+interface ServerOptions {
+    /** 监听端口 */
+    port?: number;
+    /** 日志选项 */
+    logger?: Logger;
+}
+/**
+ * MG WebSocket 服务器
+ */
+declare class MGServer {
+    private wss;
+    private logger;
+    private connectionManager;
+    private requestHandler;
+    private port;
+    private isRunning;
+    constructor(options?: ServerOptions);
+    /**
+     * 启动服务器
+     */
+    start(): Promise<number>;
+    /**
+     * 查找可用端口
+     */
+    private findAvailablePort;
+    /**
+     * 检查端口是否可用
+     */
+    private isPortAvailable;
+    /**
+     * 处理新连接
+     */
+    private handleConnection;
+    /**
+     * 处理注册消息
+     */
+    private handleRegister;
+    /**
+     * 处理消息
+     */
+    private handleMessage;
+    /**
+     * 处理心跳
+     */
+    private handlePing;
+    /**
+     * 停止服务器
+     */
+    stop(): Promise<void>;
+    /**
+     * 获取运行状态
+     */
+    getStatus(): {
+        running: boolean;
+        port: number;
+        stats: {
+            providers: number;
+            consumers: number;
+            total: number;
+        };
+        connectedPages: string[];
+    };
+    /**
+     * 获取端口
+     */
+    getPort(): number;
+    /**
+     * 是否运行中
+     */
+    isServerRunning(): boolean;
+}
+/**
+ * 创建服务器实例
+ */
+declare function createServer(options?: ServerOptions): MGServer;
+
+/**
+ * 连接管理器
+ * 管理 Provider 和 Consumer 的 WebSocket 连接
+ */
+
+/** 带连接信息的 WebSocket */
+interface ManagedWebSocket extends WebSocket {
+    /** 连接 ID */
+    connectionId: string;
+    /** 连接信息 */
+    connectionInfo: ConnectionInfo;
+    /** 是否存活 */
+    isAlive: boolean;
+}
+/**
+ * 连接管理器
+ */
+declare class ConnectionManager {
+    private logger;
+    /** Provider 连接（按页面 URL 索引） */
+    private providers;
+    /** Consumer 连接 */
+    private consumers;
+    /** 所有连接（按 ID 索引） */
+    private allConnections;
+    /** 心跳检查定时器 */
+    private heartbeatTimer;
+    constructor(logger: Logger);
+    /**
+     * 启动心跳检查
+     */
+    startHeartbeatCheck(interval?: number): void;
+    /**
+     * 停止心跳检查
+     */
+    stopHeartbeatCheck(): void;
+    /**
+     * 检查所有连接的心跳
+     */
+    private checkHeartbeats;
+    /**
+     * 添加连接
+     */
+    addConnection(ws: WebSocket, type: ConnectionType, pageUrl?: string, pageId?: string): ManagedWebSocket;
+    /**
+     * 移除连接
+     */
+    removeConnection(ws: ManagedWebSocket): void;
+    /**
+     * 更新连接活跃时间
+     */
+    updateLastActive(ws: ManagedWebSocket): void;
+    /**
+     * 根据页面 URL 查找 Provider
+     */
+    findProviderByPageUrl(pageUrl: string): ManagedWebSocket | undefined;
+    /**
+     * 获取第一个可用的 Provider
+     */
+    getFirstProvider(): ManagedWebSocket | undefined;
+    /**
+     * 获取所有 Provider 信息
+     */
+    getAllProviders(): ConnectionInfo[];
+    /**
+     * 获取连接统计
+     */
+    getStats(): {
+        providers: number;
+        consumers: number;
+        total: number;
+    };
+    /**
+     * 获取所有已连接的页面 URL
+     */
+    getConnectedPageUrls(): string[];
+    /**
+     * 关闭所有连接
+     */
+    closeAll(): void;
+}
+
+/**
+ * 请求处理器
+ * 处理 Consumer 请求，转发给 Provider
+ */
+
+/**
+ * 请求处理器
+ */
+declare class RequestHandler {
+    private logger;
+    private connectionManager;
+    /** 待处理的请求 */
+    private pendingRequests;
+    constructor(connectionManager: ConnectionManager, logger: Logger);
+    /**
+     * 处理 Consumer 请求
+     */
+    handleRequest(consumer: ManagedWebSocket, message: RequestMessage): Promise<void>;
+    /**
+     * 处理 Provider 响应
+     */
+    handleResponse(response: ResponseMessage): void;
+    /**
+     * 处理请求超时
+     */
+    private handleTimeout;
+    /**
+     * 清理请求
+     */
+    private cleanupRequest;
+    /**
+     * 发送错误响应
+     */
+    private sendError;
+    /**
+     * 清理特定连接的所有待处理请求
+     */
+    cleanupConnectionRequests(connectionId: string): void;
+    /**
+     * 清理所有待处理请求
+     */
+    cleanupAll(): void;
+}
+
+export { type AllPagesInfo as A, type BaseMessage as B, CONFIG_DIR as C, DEFAULT_PORT as D, ErrorCode as E, MGServer as F, type GetNodeParams as G, HEARTBEAT_INTERVAL as H, createServer as I, type ServerOptions as J, ConnectionManager as K, LOG_DIR as L, MAX_PORT_ATTEMPTS as M, type NodeInfo as N, type OutputFormatter as O, PORT_RANGE_START as P, type ManagedWebSocket as Q, REQUEST_TIMEOUT as R, type ServerInfo as S, RequestHandler as T, Logger as U, createLogger as V, LogLevel as W, type LoggerOptions as X, PORT_RANGE_END as a, PORT_SCAN_TIMEOUT as b, SERVER_INFO_FILE as c, SERVER_LOG_FILE as d, HEARTBEAT_TIMEOUT as e, SERVER_START_TIMEOUT as f, RETRY_INTERVALS as g, MAX_RETRY_COUNT as h, ConnectionType as i, MessageType as j, ErrorNames as k, ErrorMessages as l, MGError as m, createError as n, type RequestMessage as o, type ResponseMessage as p, type ErrorInfo as q, type RegisterMessage as r, type PingMessage as s, type PongMessage as t, type ConnectionInfo as u, type GetAllNodesParams as v, type ExportImageParams as w, type CliOptions as x, type RGBA as y, type MgPageInfo as z };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { S as ServerInfo } from './index-DNrszrq9.js';
+export { A as AllPagesInfo, B as BaseMessage, C as CONFIG_DIR, x as CliOptions, u as ConnectionInfo, K as ConnectionManager, i as ConnectionType, D as DEFAULT_PORT, E as ErrorCode, q as ErrorInfo, l as ErrorMessages, k as ErrorNames, w as ExportImageParams, v as GetAllNodesParams, G as GetNodeParams, H as HEARTBEAT_INTERVAL, e as HEARTBEAT_TIMEOUT, L as LOG_DIR, W as LogLevel, U as Logger, X as LoggerOptions, M as MAX_PORT_ATTEMPTS, h as MAX_RETRY_COUNT, m as MGError, F as MGServer, Q as ManagedWebSocket, j as MessageType, z as MgPageInfo, N as NodeInfo, O as OutputFormatter, a as PORT_RANGE_END, P as PORT_RANGE_START, b as PORT_SCAN_TIMEOUT, s as PingMessage, t as PongMessage, R as REQUEST_TIMEOUT, g as RETRY_INTERVALS, y as RGBA, r as RegisterMessage, T as RequestHandler, o as RequestMessage, p as ResponseMessage, c as SERVER_INFO_FILE, d as SERVER_LOG_FILE, f as SERVER_START_TIMEOUT, J as ServerOptions, n as createError, V as createLogger, I as createServer } from './index-DNrszrq9.js';
+import 'ws';
+
+/**
+ * MG Plugin 工具函数
+ */
+
+/**
+ * 确保目录存在
+ */
+declare function ensureDir(dir: string): void;
+/**
+ * 确保配置目录存在
+ */
+declare function ensureConfigDir(): void;
+/**
+ * 读取 Server 信息文件
+ */
+declare function readServerInfo(): ServerInfo | null;
+/**
+ * 写入 Server 信息文件
+ */
+declare function writeServerInfo(info: ServerInfo): void;
+/**
+ * 删除 Server 信息文件
+ */
+declare function deleteServerInfo(): void;
+/**
+ * 解析输出路径（支持相对路径和绝对路径）
+ */
+declare function resolveOutputPath(outputPath: string): string;
+/**
+ * 确保输出路径的目录存在
+ */
+declare function ensureOutputDir(outputPath: string): void;
+/**
+ * 检查进程是否存在
+ */
+declare function isProcessRunning(pid: number): boolean;
+/**
+ * 终止进程
+ */
+declare function killProcess(pid: number): boolean;
+/**
+ * 标准化页面 URL
+ *
+ * 输入: https://mastergo.netease.com/file/174135798361888?fileOpenFrom=home&page_id=0%3A8347
+ * 输出: mastergo.netease.com/file/174135798361888
+ */
+declare function normalizePageUrl(url: string): string;
+/**
+ * 检查是否是设计页面 URL
+ */
+declare function isDesignPageUrl(url: string): boolean;
+/**
+ * 解析 mgp:// 链接
+ *
+ * 支持的格式 (queryParams 格式，nodeId 需要 URL 编码):
+ * - mgp://mastergo.netease.com/file/174135798361888?nodeId=123%3A456 (单个节点)
+ * - mgp://mastergo.netease.com/file/174135798361888?nodeId=0%3A8633&nodePath=314%3A13190%2F0%3A8633 (带父节点路径)
+ *
+ * 输出: { pageUrl: 'mastergo.netease.com/file/174135798361888', nodeId: '0:8633', nodePath: ['314:13190', '0:8633'] }
+ */
+declare function parseMgpLink(link: string): {
+    pageUrl: string;
+    nodeId: string;
+    nodePath?: string[];
+} | null;
+/**
+ * 生成 mgp:// 链接
+ *
+ * @param pageUrl 页面 URL（会被标准化）
+ * @param nodeId 节点 ID（会被 URL 编码）
+ * @param nodePath 可选的父节点路径（会被 URL 编码）
+ */
+declare function generateMgpLink(pageUrl: string, nodeId: string, nodePath?: string[]): string;
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 格式化时间间隔
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * 生成唯一 ID
+ */
+declare function generateId(): string;
+/**
+ * 获取当前时间的 ISO 格式字符串
+ */
+declare function getCurrentISOTime(): string;
+/**
+ * 格式化日期时间用于日志
+ */
+declare function formatLogTime(date?: Date): string;
+/**
+ * 从完整 URL 提取 fileId
+ *
+ * 支持格式:
+ * - https://mastergo.netease.com/file/174875497054651?page_id=321%3A11979
+ * - mastergo.netease.com/file/174875497054651
+ *
+ * @returns fileId 或 null
+ */
+declare function extractFileIdFromUrl(url: string): string | null;
+/**
+ * 从 mgp:// 链接提取 fileId
+ *
+ * 支持格式:
+ * - mgp://mastergo.netease.com/file/174875497054651?nodeId=xxx
+ *
+ * @returns fileId 或 null
+ */
+declare function extractFileIdFromMgpLink(link: string): string | null;
+/**
+ * 统一处理输入，提取 fileId
+ *
+ * 支持三种输入格式:
+ * 1. 完整 URL: https://mastergo.netease.com/file/174875497054651?page_id=xxx
+ * 2. mgp 协议: mgp://mastergo.netease.com/file/174875497054651?nodeId=xxx
+ * 3. 纯 fileId: 174875497054651
+ *
+ * @returns fileId 或 null
+ */
+declare function extractFileId(input: string): string | null;
+
+export { ServerInfo, deleteServerInfo, ensureConfigDir, ensureDir, ensureOutputDir, extractFileId, extractFileIdFromMgpLink, extractFileIdFromUrl, formatDuration, formatFileSize, formatLogTime, generateId, generateMgpLink, getCurrentISOTime, isDesignPageUrl, isProcessRunning, killProcess, normalizePageUrl, parseMgpLink, readServerInfo, resolveOutputPath, writeServerInfo };