@hangox/mg-cli 1.0.6 → 1.0.8

package/dist/{index-BCd-mD-X.d.ts → index-DmySkKst.d.ts}

@@ -61,6 +61,7 @@ declare enum MessageType {
     REGISTER = "register",
     REGISTER_ACK = "register_ack",
     GET_NODE_BY_ID = "get_node_by_id",
+    GET_PAGE_BY_ID = "get_page_by_id",
     GET_ALL_NODES = "get_all_nodes",
     GET_SELECTION = "get_selection",
     EXPORT_IMAGE = "export_image",
@@ -230,7 +231,139 @@ interface ConnectionInfo {
     /** 最后活跃时间 */
     lastActiveAt: Date;
 }
-/** 节点信息（简化版） */
+/**
+ * 节点信息
+ *
+ * 包含 MasterGo 节点的所有属性，根据节点类型不同，可用属性也不同。
+ *
+ * ## 通用属性 (所有节点)
+ * - `id`: 节点唯一标识
+ * - `name`: 节点名称
+ * - `type`: 节点类型 (FRAME, TEXT, RECTANGLE, ELLIPSE, POLYGON, STAR, LINE, PEN, COMPONENT, COMPONENT_SET, INSTANCE, GROUP, BOOLEAN_OPERATION, SLICE, CONNECTOR, SECTION)
+ * - `visible`: 是否可见
+ * - `isLocked`: 是否锁定
+ * - `slotInfo`: 插槽信息
+ * - `componentPropertyReferences`: 组件属性引用
+ * - `attachedConnectorIds`: 连接的连接线 ID 数组
+ *
+ * ## 布局属性 (LayoutMixin)
+ * - `x`, `y`: 坐标
+ * - `width`, `height`: 尺寸
+ * - `rotation`: 旋转角度
+ * - `absoluteTransform`: 绝对变换矩阵
+ * - `relativeTransform`: 相对变换矩阵
+ * - `absoluteRenderBounds`: 渲染边界（含阴影/外描边）
+ * - `absoluteBoundingBox`: 绝对边界框
+ * - `bound`: 边界
+ * - `minWidth`, `maxWidth`, `minHeight`, `maxHeight`: 尺寸约束
+ * - `constrainProportions`: 锁定宽高比
+ * - `layoutPositioning`: 布局定位方式 (AUTO | ABSOLUTE)
+ * - `alignSelf`: 交叉轴对齐 (STRETCH | INHERIT)
+ * - `flexGrow`: 弹性增长 (0 | 1)
+ * - `scaleFactor`: 缩放因子
+ *
+ * ## 混合属性 (BlendMixin)
+ * - `opacity`: 不透明度
+ * - `blendMode`: 混合模式
+ * - `isMask`: 是否蒙版
+ * - `isMaskOutline`: 轮廓蒙版
+ * - `isMaskVisible`: 蒙版可见
+ * - `effects`: 效果数组（阴影、模糊等）
+ * - `effectStyleId`: 效果样式 ID
+ *
+ * ## 几何属性 (GeometryMixin)
+ * - `fills`: 填充数组
+ * - `strokes`: 描边数组
+ * - `strokeWeight`: 描边粗细
+ * - `strokeAlign`: 描边对齐 (CENTER | INSIDE | OUTSIDE)
+ * - `strokeCap`: 端点装饰
+ * - `strokeJoin`: 拐角装饰
+ * - `strokeStyle`: 描边样式 (SOLID | DASH | CUSTOM)
+ * - `dashCap`: 虚线端点
+ * - `strokeDashes`: 虚线数组
+ * - `fillStyleId`: 填充样式 ID
+ * - `strokeFillStyleId`: 描边填充样式 ID
+ * - `strokeWidthStyleId`: 描边宽度样式 ID
+ * - `paddingStyleId`: 内边距样式 ID
+ * - `spacingStyleId`: 间距样式 ID
+ * - `cornerRadiusStyleId`: 圆角样式 ID
+ *
+ * ## 矩形描边属性 (RectangleStrokeWeightMixin)
+ * - `strokeTopWeight`, `strokeLeftWeight`, `strokeBottomWeight`, `strokeRightWeight`: 各边描边粗细
+ *
+ * ## 圆角属性 (CornerMixin)
+ * - `cornerSmooth`: 角平滑度
+ * - `cornerRadius`: 统一圆角
+ * - `topLeftRadius`, `topRightRadius`, `bottomLeftRadius`, `bottomRightRadius`: 各角圆角
+ *
+ * ## 约束属性 (ConstraintMixin)
+ * - `constraints`: 约束设置 { horizontal, vertical }
+ *
+ * ## 容器属性 (ContainerMixin)
+ * - `expanded`: 是否展开
+ *
+ * ## 自动布局属性 (FrameContainerMixin)
+ * - `flexMode`: 自动布局方向 (NONE | HORIZONTAL | VERTICAL)
+ * - `flexWrap`: 换行设置 (WRAP | NO_WRAP)
+ * - `itemSpacing`: 主轴间距
+ * - `crossAxisSpacing`: 交叉轴间距
+ * - `mainAxisAlignItems`: 主轴对齐
+ * - `crossAxisAlignItems`: 交叉轴对齐
+ * - `mainAxisSizingMode`: 主轴尺寸模式 (FIXED | AUTO)
+ * - `crossAxisSizingMode`: 交叉轴尺寸模式 (FIXED | AUTO)
+ * - `crossAxisAlignContent`: 多行对齐
+ * - `strokesIncludedInLayout`: 描边计入布局
+ * - `itemReverseZIndex`: 反转堆叠
+ * - `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`: 内边距
+ * - `clipsContent`: 裁剪内容
+ * - `layoutGrids`: 布局网格
+ * - `gridStyleId`: 网格样式 ID
+ * - `overflowDirection`: 溢出方向
+ *
+ * ## 原型交互属性 (ReactionMixin)
+ * - `reactions`: 原型交互数组
+ *
+ * ## 导出属性 (ExportMixin)
+ * - `exportSettings`: 导出设置数组
+ *
+ * ## TEXT 节点特有属性
+ * - `characters`: 文本内容
+ * - `hasMissingFont`: 缺失字体
+ * - `hyperlinks`: 超链接数组
+ * - `textAlignHorizontal`: 水平对齐
+ * - `textAlignVertical`: 垂直对齐
+ * - `textAutoResize`: 自动调整
+ * - `paragraphSpacing`: 段落间距
+ * - `textStyles`: 文本样式数组
+ * - `listStyles`: 列表样式数组
+ *
+ * ## COMPONENT/COMPONENT_SET 节点特有属性
+ * - `variantProperties`: 变体属性
+ * - `componentPropertyValues`: 组件属性值
+ * - `description`: 描述
+ * - `alias`: 别名
+ * - `documentationLinks`: 文档链接
+ * - `isExternal`: 是否团队库组件
+ * - `ukey`: 唯一键
+ * - `publishStatus`: 发布状态
+ *
+ * ## INSTANCE 节点特有属性
+ * - `componentProperties`: 组件属性
+ * - `exposedInstances`: 暴露的实例 ID 数组
+ * - `isExposedInstance`: 是否暴露的实例
+ * - `mainComponentId`: 主组件 ID
+ * - `mainComponentName`: 主组件名称
+ *
+ * ## 其他节点特有属性
+ * - ELLIPSE: `arcData`
+ * - POLYGON/STAR: `pointCount`
+ * - STAR: `innerRadius`
+ * - LINE: `leftStrokeCap`, `rightStrokeCap`
+ * - PEN: `penNetwork`, `penPaths`
+ * - BOOLEAN_OPERATION: `booleanOperation`
+ * - CONNECTOR: `connectorStart`, `connectorEnd`, `connectorStartStrokeCap`, `connectorEndStrokeCap`, `connectorText`
+ * - SLICE: `isPreserveRatio`
+ */
 interface NodeInfo {
     /** 节点 ID */
     id: string;
@@ -250,7 +383,7 @@ interface NodeInfo {
     height?: number;
     /** 子节点 */
     children?: NodeInfo[];
-    /** 其他属性 */
+    /** 其他属性（根据节点类型不同而不同） */
     [key: string]: unknown;
 }
 /** 空间节点信息（仅包含位置和尺寸，用于 AI 理解空间布局） */
@@ -281,6 +414,17 @@ interface GetNodeParams {
     /** 索引签名 */
     [key: string]: unknown;
 }
+/** 获取页面参数 */
+interface GetPageParams {
+    /** 页面 ID */
+    pageId: string;
+    /** 遍历深度 */
+    maxDepth?: number;
+    /** 是否包含不可见节点 */
+    includeInvisible?: boolean;
+    /** 索引签名 */
+    [key: string]: unknown;
+}
 /** 获取所有节点参数 */
 interface GetAllNodesParams {
     /** 遍历深度 */
@@ -532,7 +676,7 @@ interface ManagedWebSocket extends WebSocket {
  */
 declare class ConnectionManager {
     private logger;
-    /** Provider 连接（按页面 URL 索引） */
+    /** Provider 连接（按页面 URL 索引，支持同 URL 多个连接） */
     private providers;
     /** Consumer 连接 */
     private consumers;
@@ -566,7 +710,7 @@ declare class ConnectionManager {
      */
     updateLastActive(ws: ManagedWebSocket): void;
     /**
-     * 根据页面 URL 查找 Provider
+     * 根据页面 URL 查找 Provider（返回第一个可用的连接）
      */
     findProviderByPageUrl(pageUrl: string): ManagedWebSocket | undefined;
     /**
@@ -639,4 +783,4 @@ declare class RequestHandler {
     cleanupAll(): void;
 }
 
-export { ConnectionManager as $, type PongMessage as A, type BaseMessage as B, CONFIG_DIR as C, DEV_DEFAULT_PORT as D, ErrorCode as E, type ConnectionInfo as F, type GetNodeParams as G, HEARTBEAT_INTERVAL as H, IS_DEV_MODE as I, type GetAllNodesParams as J, type ExportImageParams as K, LOG_DIR as L, MAX_PORT_ATTEMPTS as M, type NodeInfo as N, type OutputFormatter as O, PROD_DEFAULT_PORT as P, type CliOptions as Q, REQUEST_TIMEOUT as R, type ServerInfo as S, type RGBA as T, type MgPageInfo as U, type AllPagesInfo as V, type ConnectedPageInfo as W, type ServerStatusResponse as X, MGServer as Y, createServer as Z, type ServerOptions as _, type SpaceNodeInfo as a, type ManagedWebSocket as a0, RequestHandler as a1, Logger as a2, createLogger as a3, LogLevel as a4, type LoggerOptions as a5, PROD_PORT_RANGE_START as b, PROD_PORT_RANGE_END as c, DEV_PORT_RANGE_START as d, DEV_PORT_RANGE_END as e, DEFAULT_PORT as f, PORT_RANGE_START as g, PORT_RANGE_END as h, PORT_SCAN_TIMEOUT as i, SERVER_INFO_FILE as j, SERVER_LOG_FILE as k, HEARTBEAT_TIMEOUT as l, SERVER_START_TIMEOUT as m, RETRY_INTERVALS as n, MAX_RETRY_COUNT as o, ConnectionType as p, MessageType as q, ErrorNames as r, ErrorMessages as s, MGError as t, createError as u, type RequestMessage as v, type ResponseMessage as w, type ErrorInfo as x, type RegisterMessage as y, type PingMessage as z };
+export { type ServerOptions as $, type PongMessage as A, type BaseMessage as B, CONFIG_DIR as C, DEV_DEFAULT_PORT as D, ErrorCode as E, type ConnectionInfo as F, type GetNodeParams as G, HEARTBEAT_INTERVAL as H, IS_DEV_MODE as I, type GetPageParams as J, type GetAllNodesParams as K, LOG_DIR as L, MessageType as M, type NodeInfo as N, type ExportImageParams as O, PROD_DEFAULT_PORT as P, type OutputFormatter as Q, REQUEST_TIMEOUT as R, type ServerInfo as S, type CliOptions as T, type RGBA as U, type MgPageInfo as V, type AllPagesInfo as W, type ConnectedPageInfo as X, type ServerStatusResponse as Y, MGServer as Z, createServer as _, type SpaceNodeInfo as a, ConnectionManager as a0, type ManagedWebSocket as a1, RequestHandler as a2, Logger as a3, createLogger as a4, LogLevel as a5, type LoggerOptions as a6, PROD_PORT_RANGE_START as b, PROD_PORT_RANGE_END as c, DEV_PORT_RANGE_START as d, DEV_PORT_RANGE_END as e, DEFAULT_PORT as f, PORT_RANGE_START as g, PORT_RANGE_END as h, MAX_PORT_ATTEMPTS as i, PORT_SCAN_TIMEOUT as j, SERVER_INFO_FILE as k, SERVER_LOG_FILE as l, HEARTBEAT_TIMEOUT as m, SERVER_START_TIMEOUT as n, RETRY_INTERVALS as o, MAX_RETRY_COUNT as p, ConnectionType as q, ErrorNames as r, ErrorMessages as s, MGError as t, createError as u, type RequestMessage as v, type ResponseMessage as w, type ErrorInfo as x, type RegisterMessage as y, type PingMessage as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as ServerInfo, N as NodeInfo, a as SpaceNodeInfo } from './index-BCd-mD-X.js';
-export { V as AllPagesInfo, B as BaseMessage, C as CONFIG_DIR, Q as CliOptions, W as ConnectedPageInfo, F as ConnectionInfo, $ as ConnectionManager, p as ConnectionType, f as DEFAULT_PORT, D as DEV_DEFAULT_PORT, e as DEV_PORT_RANGE_END, d as DEV_PORT_RANGE_START, E as ErrorCode, x as ErrorInfo, s as ErrorMessages, r as ErrorNames, K as ExportImageParams, J as GetAllNodesParams, G as GetNodeParams, H as HEARTBEAT_INTERVAL, l as HEARTBEAT_TIMEOUT, I as IS_DEV_MODE, L as LOG_DIR, a4 as LogLevel, a2 as Logger, a5 as LoggerOptions, M as MAX_PORT_ATTEMPTS, o as MAX_RETRY_COUNT, t as MGError, Y as MGServer, a0 as ManagedWebSocket, q as MessageType, U as MgPageInfo, O as OutputFormatter, h as PORT_RANGE_END, g as PORT_RANGE_START, i as PORT_SCAN_TIMEOUT, P as PROD_DEFAULT_PORT, c as PROD_PORT_RANGE_END, b as PROD_PORT_RANGE_START, z as PingMessage, A as PongMessage, R as REQUEST_TIMEOUT, n as RETRY_INTERVALS, T as RGBA, y as RegisterMessage, a1 as RequestHandler, v as RequestMessage, w as ResponseMessage, j as SERVER_INFO_FILE, k as SERVER_LOG_FILE, m as SERVER_START_TIMEOUT, _ as ServerOptions, X as ServerStatusResponse, u as createError, a3 as createLogger, Z as createServer } from './index-BCd-mD-X.js';
+import { S as ServerInfo, N as NodeInfo, a as SpaceNodeInfo, M as MessageType } from './index-DmySkKst.js';
+export { W as AllPagesInfo, B as BaseMessage, C as CONFIG_DIR, T as CliOptions, X as ConnectedPageInfo, F as ConnectionInfo, a0 as ConnectionManager, q as ConnectionType, f as DEFAULT_PORT, D as DEV_DEFAULT_PORT, e as DEV_PORT_RANGE_END, d as DEV_PORT_RANGE_START, E as ErrorCode, x as ErrorInfo, s as ErrorMessages, r as ErrorNames, O as ExportImageParams, K as GetAllNodesParams, G as GetNodeParams, J as GetPageParams, H as HEARTBEAT_INTERVAL, m as HEARTBEAT_TIMEOUT, I as IS_DEV_MODE, L as LOG_DIR, a5 as LogLevel, a3 as Logger, a6 as LoggerOptions, i as MAX_PORT_ATTEMPTS, p as MAX_RETRY_COUNT, t as MGError, Z as MGServer, a1 as ManagedWebSocket, V as MgPageInfo, Q as OutputFormatter, h as PORT_RANGE_END, g as PORT_RANGE_START, j as PORT_SCAN_TIMEOUT, P as PROD_DEFAULT_PORT, c as PROD_PORT_RANGE_END, b as PROD_PORT_RANGE_START, z as PingMessage, A as PongMessage, R as REQUEST_TIMEOUT, o as RETRY_INTERVALS, U as RGBA, y as RegisterMessage, a2 as RequestHandler, v as RequestMessage, w as ResponseMessage, k as SERVER_INFO_FILE, l as SERVER_LOG_FILE, n as SERVER_START_TIMEOUT, $ as ServerOptions, Y as ServerStatusResponse, u as createError, a4 as createLogger, _ as createServer } from './index-DmySkKst.js';
 import 'ws';
 
 /**
@@ -56,15 +56,18 @@ declare function isDesignPageUrl(url: string): boolean;
 /**
  * 解析 mgp:// 链接
  *
- * 支持的格式 (queryParams 格式，nodeId 需要 URL 编码):
+ * 支持的格式 (queryParams 格式，nodeId/pageId 需要 URL 编码):
  * - mgp://mastergo.netease.com/file/174135798361888?nodeId=123%3A456 (单个节点)
  * - mgp://mastergo.netease.com/file/174135798361888?nodeId=0%3A8633&nodePath=314%3A13190%2F0%3A8633 (带父节点路径)
+ * - mgp://mastergo.netease.com/file/174135798361888?pageId=0%3A1 (页面链接)
  *
  * 输出: { pageUrl: 'mastergo.netease.com/file/174135798361888', nodeId: '0:8633', nodePath: ['314:13190', '0:8633'] }
+ *       或 { pageUrl: 'mastergo.netease.com/file/174135798361888', pageId: '0:1' }
  */
 declare function parseMgpLink(link: string): {
     pageUrl: string;
-    nodeId: string;
+    nodeId?: string;
+    pageId?: string;
     nodePath?: string[];
 } | null;
 /**
@@ -75,6 +78,13 @@ declare function parseMgpLink(link: string): {
  * @param nodePath 可选的父节点路径（会被 URL 编码）
  */
 declare function generateMgpLink(pageUrl: string, nodeId: string, nodePath?: string[]): string;
+/**
+ * 生成 mgp:// 页面链接
+ *
+ * @param pageUrl 页面 URL（会被标准化）
+ * @param pageId 页面 ID（会被 URL 编码）
+ */
+declare function generatePageLink(pageUrl: string, pageId: string): string;
 /**
  * 格式化文件大小
  */
@@ -153,4 +163,53 @@ declare function trimNodeDefaults<T extends Record<string, unknown>>(node: T): T
  */
 declare function extractSpaceInfo(node: NodeInfo): SpaceNodeInfo;
 
-export { NODE_DEFAULTS, NodeInfo, ServerInfo, SpaceNodeInfo, deleteServerInfo, ensureConfigDir, ensureDir, ensureOutputDir, extractFileId, extractFileIdFromMgpLink, extractFileIdFromUrl, extractSpaceInfo, formatDuration, formatFileSize, formatLogTime, generateId, generateMgpLink, getCurrentISOTime, isDesignPageUrl, isProcessRunning, killProcess, normalizePageUrl, parseMgpLink, readServerInfo, resolveOutputPath, roundToOneDecimal, trimNodeDefaults, writeServerInfo };
+/**
+ * CLI 客户端
+ * 负责连接 Server 发送请求
+ */
+
+/** 客户端选项 */
+interface ClientOptions {
+    /** 禁用自动启动 Server */
+    noAutoStart?: boolean;
+    /** 禁用重试 */
+    noRetry?: boolean;
+}
+/**
+ * MG CLI 客户端
+ */
+declare class MGClient {
+    private ws;
+    private options;
+    constructor(options?: ClientOptions);
+    /**
+     * 连接到 Server
+     */
+    connect(): Promise<void>;
+    /**
+     * 尝试连接指定端口
+     */
+    private tryConnect;
+    /**
+     * 等待 Server 就绪
+     */
+    private waitForServer;
+    /**
+     * 注册为 Consumer
+     */
+    private register;
+    /**
+     * 发送请求并等待响应
+     */
+    request<T = unknown>(type: MessageType, params?: Record<string, unknown>, pageUrl?: string): Promise<T>;
+    /**
+     * 带重试的请求
+     */
+    requestWithRetry<T = unknown>(type: MessageType, params?: Record<string, unknown>, pageUrl?: string): Promise<T>;
+    /**
+     * 关闭连接
+     */
+    close(): void;
+}
+
+export { type ClientOptions, MGClient, MessageType, NODE_DEFAULTS, NodeInfo, ServerInfo, SpaceNodeInfo, deleteServerInfo, ensureConfigDir, ensureDir, ensureOutputDir, extractFileId, extractFileIdFromMgpLink, extractFileIdFromUrl, extractSpaceInfo, formatDuration, formatFileSize, formatLogTime, generateId, generateMgpLink, generatePageLink, getCurrentISOTime, isDesignPageUrl, isProcessRunning, killProcess, normalizePageUrl, parseMgpLink, readServerInfo, resolveOutputPath, roundToOneDecimal, trimNodeDefaults, writeServerInfo };