@hangox/mg-cli 1.0.0

package/.eslintrc.cjs

@@ -0,0 +1,26 @@
+module.exports = {
+  root: true,
+  env: {
+    node: true,
+    es2022: true,
+  },
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  rules: {
+    // 允许使用 console（CLI 工具需要输出）
+    'no-console': 'off',
+    // TypeScript 相关
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+  ignorePatterns: ['dist', 'node_modules', '*.config.*'],
+}

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# MG CLI
+
+MasterGo Plugin 的命令行工具和 WebSocket 服务器。
+
+## 文档索引
+
+详细设计和开发指南请参阅 docs 目录：
+
+| 文档 | 说明 |
+|------|------|
+| [00-概述.md](../docs/roles/00-概述.md) | 项目总览、系统架构、测试方案 |
+| [01-MGPlugin-Server.md](../docs/roles/01-MGPlugin-Server.md) | Server 设计、守护进程、端口管理 |
+| [02-MG-Cli.md](../docs/roles/02-MG-Cli.md) | **CLI 完整文档** - 命令详解、开发指南、测试方案 |
+| [06-通用协议.md](../docs/roles/06-通用协议.md) | 消息协议、错误码、心跳机制 |
+
+## 快速开始
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发模式
+pnpm dev
+
+# 构建
+pnpm build
+
+# 链接到全局
+pnpm link --global
+
+# 测试命令
+mg-cli --help
+mg-cli server start
+mg-cli server status
+```
+
+## 一键检查
+
+```bash
+pnpm check    # typecheck + lint + test + build
+```
+
+**编写代码后务必运行 `pnpm check` 确保所有测试通过**

package/bin/mg-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// CLI 入口文件，加载编译后的 CLI 模块
+import '../dist/cli.js'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hangox/mg-cli",
+  "version": "1.0.0",
+  "description": "MasterGo Plugin CLI 工具和 WebSocket 服务器",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mg-cli": "./bin/mg-cli.js"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "vitest run --coverage --reporter=junit --outputFile=test-results.xml"
+  },
+  "keywords": [
+    "mastergo",
+    "cli",
+    "websocket",
+    "plugin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "@types/ws": "^8.5.13",
+    "@typescript-eslint/eslint-plugin": "^8.17.0",
+    "@typescript-eslint/parser": "^8.17.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^8.57.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/cli/client.ts

@@ -0,0 +1,266 @@
+/**
+ * CLI 客户端
+ * 负责连接 Server 发送请求
+ */
+
+import WebSocket from 'ws'
+import { readServerInfo, parseMgpLink } from '../shared/utils.js'
+import {
+  PORT_RANGE_START,
+  PORT_RANGE_END,
+  PORT_SCAN_TIMEOUT,
+  REQUEST_TIMEOUT,
+  SERVER_START_TIMEOUT,
+  RETRY_INTERVALS,
+  MAX_RETRY_COUNT,
+  ConnectionType,
+  MessageType,
+} from '../shared/constants.js'
+import { ErrorCode, MGError, ErrorMessages } from '../shared/errors.js'
+import { startServerDaemon } from '../server/daemon.js'
+import { generateId } from '../shared/utils.js'
+import type { RequestMessage, ResponseMessage } from '../shared/types.js'
+
+/** 客户端选项 */
+export interface ClientOptions {
+  /** 禁用自动启动 Server */
+  noAutoStart?: boolean
+  /** 禁用重试 */
+  noRetry?: boolean
+}
+
+/**
+ * MG CLI 客户端
+ */
+export class MGClient {
+  private ws: WebSocket | null = null
+  private options: ClientOptions
+
+  constructor(options: ClientOptions = {}) {
+    this.options = options
+  }
+
+  /**
+   * 连接到 Server
+   */
+  async connect(): Promise<void> {
+    // 1. 尝试从文件读取端口
+    const serverInfo = readServerInfo()
+    if (serverInfo) {
+      try {
+        await this.tryConnect(serverInfo.port)
+        return
+      } catch {
+        // 文件信息失效，继续扫描
+      }
+    }
+
+    // 2. 端口扫描
+    for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+      try {
+        await this.tryConnect(port)
+        return
+      } catch {
+        // 继续尝试下一个端口
+      }
+    }
+
+    // 3. 自动启动 Server
+    if (!this.options.noAutoStart) {
+      console.log('Server 未运行，正在自动启动...')
+      try {
+        const info = await startServerDaemon()
+        console.log(`Server 已启动，端口: ${info.port}`)
+
+        // 等待 Server 就绪
+        await this.waitForServer(info.port)
+        return
+      } catch (error) {
+        throw new MGError(
+          ErrorCode.SERVER_START_FAILED,
+          `自动启动 Server 失败: ${error instanceof Error ? error.message : error}`
+        )
+      }
+    }
+
+    throw new MGError(ErrorCode.CONNECTION_FAILED, ErrorMessages[ErrorCode.CONNECTION_FAILED])
+  }
+
+  /**
+   * 尝试连接指定端口
+   */
+  private tryConnect(port: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(`ws://localhost:${port}`)
+      const timer = setTimeout(() => {
+        ws.close()
+        reject(new Error('连接超时'))
+      }, PORT_SCAN_TIMEOUT)
+
+      ws.on('open', () => {
+        clearTimeout(timer)
+        this.ws = ws
+        // 注册为 Consumer
+        this.register()
+        resolve()
+      })
+
+      ws.on('error', (error) => {
+        clearTimeout(timer)
+        reject(error)
+      })
+    })
+  }
+
+  /**
+   * 等待 Server 就绪
+   */
+  private async waitForServer(port: number): Promise<void> {
+    const startTime = Date.now()
+    const interval = 500
+
+    while (Date.now() - startTime < SERVER_START_TIMEOUT) {
+      try {
+        await this.tryConnect(port)
+        return
+      } catch {
+        await new Promise((r) => setTimeout(r, interval))
+      }
+    }
+
+    throw new Error('等待 Server 启动超时')
+  }
+
+  /**
+   * 注册为 Consumer
+   */
+  private register(): void {
+    if (!this.ws) return
+
+    const message = {
+      type: MessageType.REGISTER,
+      data: {
+        connectionType: ConnectionType.CONSUMER,
+      },
+      timestamp: Date.now(),
+    }
+
+    this.ws.send(JSON.stringify(message))
+  }
+
+  /**
+   * 发送请求并等待响应
+   */
+  async request<T = unknown>(
+    type: MessageType,
+    params?: Record<string, unknown>,
+    pageUrl?: string
+  ): Promise<T> {
+    if (!this.ws) {
+      throw new MGError(ErrorCode.CONNECTION_FAILED, '未连接到 Server')
+    }
+
+    const requestId = generateId()
+    const message: RequestMessage = {
+      id: requestId,
+      type,
+      params,
+      pageUrl,
+      timestamp: Date.now(),
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new MGError(ErrorCode.REQUEST_TIMEOUT, ErrorMessages[ErrorCode.REQUEST_TIMEOUT]))
+      }, REQUEST_TIMEOUT)
+
+      const messageHandler = (data: WebSocket.Data) => {
+        try {
+          const response = JSON.parse(data.toString()) as ResponseMessage
+          if (response.id === requestId) {
+            clearTimeout(timer)
+            this.ws?.off('message', messageHandler)
+
+            if (response.success) {
+              resolve(response.data as T)
+            } else {
+              const error = response.error
+              reject(
+                new MGError(
+                  error?.code || ErrorCode.UNKNOWN_ERROR,
+                  error?.message || '未知错误'
+                )
+              )
+            }
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+
+      this.ws!.on('message', messageHandler)
+      this.ws!.send(JSON.stringify(message))
+    })
+  }
+
+  /**
+   * 带重试的请求
+   */
+  async requestWithRetry<T = unknown>(
+    type: MessageType,
+    params?: Record<string, unknown>,
+    pageUrl?: string
+  ): Promise<T> {
+    if (this.options.noRetry) {
+      return this.request<T>(type, params, pageUrl)
+    }
+
+    let lastError: Error | null = null
+
+    for (let attempt = 0; attempt <= MAX_RETRY_COUNT; attempt++) {
+      try {
+        return await this.request<T>(type, params, pageUrl)
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+
+        // 检查是否是可重试的错误
+        if (error instanceof MGError) {
+          const retryable = [ErrorCode.CONNECTION_LOST, ErrorCode.REQUEST_TIMEOUT]
+          if (!retryable.includes(error.code)) {
+            throw error
+          }
+        }
+
+        // 最后一次尝试不再等待
+        if (attempt < MAX_RETRY_COUNT) {
+          const delay = RETRY_INTERVALS[attempt] || RETRY_INTERVALS[RETRY_INTERVALS.length - 1]
+          await new Promise((r) => setTimeout(r, delay))
+
+          // 重新连接
+          try {
+            await this.connect()
+          } catch {
+            // 重连失败，继续重试
+          }
+        }
+      }
+    }
+
+    throw lastError || new MGError(ErrorCode.UNKNOWN_ERROR, '请求失败')
+  }
+
+  /**
+   * 关闭连接
+   */
+  close(): void {
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+  }
+}
+
+/**
+ * 解析 mgp:// 链接
+ */
+export { parseMgpLink }

package/src/cli/commands/execute-code.ts

@@ -0,0 +1,59 @@
+/**
+ * execute_code 命令
+ * 在 MasterGo 页面执行自定义 JavaScript 代码
+ */
+
+import { Command } from 'commander'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient } from '../client.js'
+
+interface ExecuteCodeOptions {
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/**
+ * 创建 execute_code 命令
+ */
+export function createExecuteCodeCommand(): Command {
+  return new Command('execute_code')
+    .description('在 MasterGo 页面执行自定义 JavaScript 代码。通过 mg 变量访问 MasterGo API，结果会被 JSON 序列化返回')
+    .argument('<code>', '要执行的代码。可使用 mg 变量，如 mg.currentPage.name、mg.currentPage.selection')
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (code: string, options: ExecuteCodeOptions) => {
+      await handleExecuteCode(code, options)
+    })
+}
+
+/**
+ * 处理 execute_code 命令
+ */
+async function handleExecuteCode(code: string, options: ExecuteCodeOptions): Promise<void> {
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 发送请求
+    const result = await client.requestWithRetry<unknown>(MessageType.EXECUTE_CODE, { code })
+
+    // 输出结果
+    if (result === null || result === undefined) {
+      console.log('执行完成（无返回值）')
+    } else if (typeof result === 'object') {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      console.log(result)
+    }
+  } catch (error) {
+    console.error(`错误: ${error instanceof Error ? error.message : error}`)
+    process.exit(1)
+  } finally {
+    client.close()
+  }
+}

package/src/cli/commands/export-image.ts

@@ -0,0 +1,193 @@
+/**
+ * export_image 命令
+ * 导出 MasterGo 节点为图片文件
+ */
+
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve, dirname, extname } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient, parseMgpLink } from '../client.js'
+import { MGError } from '../../shared/errors.js'
+import type { ExportImageParams } from '../../shared/types.js'
+
+type ImageFormat = 'PNG' | 'JPG' | 'SVG' | 'PDF' | 'WEBP'
+
+interface ExportImageOptions {
+  output?: string
+  link?: string
+  format?: string
+  scale?: string
+  width?: string
+  height?: string
+  useAbsoluteBounds?: boolean
+  useRenderBounds?: boolean
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/** 导出响应 */
+interface ExportResponse {
+  /** Base64 编码的图片数据 */
+  data: string
+  /** MIME 类型 */
+  mimeType: string
+  /** 文件名建议 */
+  filename?: string
+}
+
+/**
+ * 创建 export_image 命令
+ */
+export function createExportImageCommand(): Command {
+  return new Command('export_image')
+    .description('导出 MasterGo 节点为图片文件。强烈建议指定 --output，否则保存到临时目录可能被系统清理')
+    .option('--output <path>', '输出文件路径。强烈建议指定，否则保存到系统临时目录可能被清理')
+    .option('--link <mgp-link>', 'mgp:// 协议链接。不指定则导出当前选中节点')
+    .option('--format <type>', '导出格式：PNG（无损透明）、JPG（有损）、SVG（矢量）、PDF、WEBP', 'PNG')
+    .option('--scale <number>', '缩放倍率（如 1、2、3）。与 width/height 互斥')
+    .option('--width <number>', '固定宽度（像素）。与 scale/height 互斥')
+    .option('--height <number>', '固定高度（像素）。与 scale/width 互斥')
+    .option('--useAbsoluteBounds', '使用完整尺寸。true: 包含被裁剪部分，false: 只导出可见区域', false)
+    .option('--no-use-render-bounds', '不包含特效和外描边。默认包含阴影、外描边等')
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (options: ExportImageOptions) => {
+      await handleExportImage(options)
+    })
+}
+
+/**
+ * 处理 export_image 命令
+ */
+async function handleExportImage(options: ExportImageOptions): Promise<void> {
+  // 验证格式
+  const format = (options.format?.toUpperCase() || 'PNG') as ImageFormat
+  const validFormats: ImageFormat[] = ['PNG', 'JPG', 'SVG', 'PDF', 'WEBP']
+  if (!validFormats.includes(format)) {
+    console.error(`错误: 不支持的格式 "${options.format}"`)
+    console.error(`支持的格式: ${validFormats.join(', ')}`)
+    process.exit(1)
+  }
+
+  // 验证参数互斥
+  const sizeParams = [options.scale, options.width, options.height].filter(Boolean)
+  if (sizeParams.length > 1) {
+    console.error('错误: scale、width、height 三者互斥，只能指定其中一个')
+    process.exit(1)
+  }
+
+  // 解析 link 参数
+  let pageUrl: string | undefined
+  let nodeId: string | undefined
+
+  if (options.link) {
+    const linkInfo = parseMgpLink(options.link)
+    if (!linkInfo) {
+      console.error(`错误: 无效的 mgp:// 链接格式: ${options.link}`)
+      process.exit(1)
+    }
+    pageUrl = linkInfo.pageUrl
+    nodeId = linkInfo.nodeId
+  }
+
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 构建请求参数
+    const params: ExportImageParams = {
+      format,
+      useAbsoluteBounds: options.useAbsoluteBounds || false,
+      useRenderBounds: options.useRenderBounds !== false,
+    }
+
+    if (nodeId) {
+      params.nodeId = nodeId
+    }
+    if (options.scale) {
+      params.scale = parseFloat(options.scale)
+    }
+    if (options.width) {
+      params.width = parseInt(options.width, 10)
+    }
+    if (options.height) {
+      params.height = parseInt(options.height, 10)
+    }
+
+    // 发送请求（传入 pageUrl 以指定目标页面）
+    const response = await client.requestWithRetry<ExportResponse>(
+      MessageType.EXPORT_IMAGE,
+      params as Record<string, unknown>,
+      pageUrl
+    )
+
+    // 确定输出路径
+    const ext = getExtension(format)
+    let outputPath: string
+    if (options.output) {
+      outputPath = resolve(options.output)
+      // 如果没有扩展名，添加扩展名
+      if (!extname(outputPath)) {
+        outputPath = `${outputPath}${ext}`
+      }
+    } else {
+      // 使用临时目录
+      const filename = response.filename || `export_${Date.now()}${ext}`
+      outputPath = resolve(tmpdir(), filename)
+      console.log('警告: 未指定 --output，文件将保存到临时目录，可能会被系统清理')
+    }
+
+    // 确保目录存在
+    const outputDir = dirname(outputPath)
+    mkdirSync(outputDir, { recursive: true })
+
+    // 解码 Base64 并保存
+    const buffer = Buffer.from(response.data, 'base64')
+    writeFileSync(outputPath, buffer)
+
+    // 输出结果
+    const sizeKB = (buffer.length / 1024).toFixed(2)
+    console.log(`文件路径: ${outputPath}`)
+    if (options.link) {
+      console.log(`Link: ${options.link}`)
+    }
+    if (nodeId) {
+      console.log(`节点 ID: ${nodeId}`)
+    } else {
+      console.log('节点 ID: (选中的节点)')
+    }
+    console.log(`导出格式: ${format}`)
+    console.log(`文件大小: ${buffer.length.toLocaleString()} 字节 (约 ${sizeKB} KB)`)
+  } catch (error) {
+    if (error instanceof MGError) {
+      console.error(`错误 [${error.code}]: ${error.message}`)
+    } else {
+      console.error(`错误: ${error instanceof Error ? error.message : error}`)
+    }
+    process.exit(1)
+  } finally {
+    client.close()
+  }
+}
+
+/**
+ * 获取格式对应的文件扩展名
+ */
+function getExtension(format: ImageFormat): string {
+  const extensions: Record<ImageFormat, string> = {
+    PNG: '.png',
+    JPG: '.jpg',
+    SVG: '.svg',
+    PDF: '.pdf',
+    WEBP: '.webp',
+  }
+  return extensions[format]
+}