@hangox/mg-cli 1.0.0

package/src/cli/commands/get-all-nodes.ts

@@ -0,0 +1,81 @@
+/**
+ * get_all_nodes 命令
+ * 获取当前页面的所有节点树
+ */
+
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient } from '../client.js'
+import type { GetAllNodesParams, NodeInfo } from '../../shared/types.js'
+
+interface GetAllNodesOptions {
+  output: string
+  maxDepth?: string
+  includeInvisible?: boolean
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/**
+ * 创建 get_all_nodes 命令
+ */
+export function createGetAllNodesCommand(): Command {
+  return new Command('get_all_nodes')
+    .description('获取当前页面的所有节点树。警告：深度每增加 1，数据量可能呈指数级增长。建议从 maxDepth=1 开始')
+    .requiredOption('--output <path>', '输出 JSON 文件路径。支持绝对路径或相对路径')
+    .option('--maxDepth <number>', '最大深度，默认 1。深度 2 可能产生 100KB-500KB，深度 3 可能超过 1MB', '1')
+    .option('--includeInvisible', '包含不可见节点（visible: false），默认不包含', false)
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (options: GetAllNodesOptions) => {
+      await handleGetAllNodes(options)
+    })
+}
+
+/**
+ * 处理 get_all_nodes 命令
+ */
+async function handleGetAllNodes(options: GetAllNodesOptions): Promise<void> {
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 发送请求
+    const params: GetAllNodesParams = {
+      maxDepth: parseInt(options.maxDepth || '1', 10),
+      includeInvisible: options.includeInvisible || false,
+    }
+
+    const data = await client.requestWithRetry<NodeInfo[]>(MessageType.GET_ALL_NODES, params)
+
+    // 保存到文件
+    const outputPath = resolve(options.output)
+    const outputDir = dirname(outputPath)
+    mkdirSync(outputDir, { recursive: true })
+
+    const jsonContent = JSON.stringify(data, null, 2)
+    writeFileSync(outputPath, jsonContent, 'utf-8')
+
+    // 输出结果
+    const size = jsonContent.length
+    const sizeKB = (size / 1024).toFixed(2)
+    const nodeCount = Array.isArray(data) ? data.length : 1
+    console.log(`文件路径: ${outputPath}`)
+    console.log(`节点数量: ${nodeCount}`)
+    console.log(`数据大小: ${size.toLocaleString()} 字符 (约 ${sizeKB} KB)`)
+    console.log(`节点深度: ${params.maxDepth}`)
+  } catch (error) {
+    console.error(`错误: ${error instanceof Error ? error.message : error}`)
+    process.exit(1)
+  } finally {
+    client.close()
+  }
+}

package/src/cli/commands/get-all-pages.ts

@@ -0,0 +1,118 @@
+/**
+ * get_all_pages 命令
+ * 获取 MasterGo 文档的所有页面信息
+ */
+
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient } from '../client.js'
+import { extractFileId } from '../../shared/utils.js'
+import type { AllPagesInfo } from '../../shared/types.js'
+
+interface GetAllPagesOptions {
+  link?: string
+  fileId?: string
+  output?: string
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/**
+ * 创建 get_all_pages 命令
+ */
+export function createGetAllPagesCommand(): Command {
+  return new Command('get_all_pages')
+    .description('获取 MasterGo 文档的所有页面信息。不指定 --output 时保存到系统临时目录')
+    .option('--link <url>', '页面链接。支持完整 URL 或 mgp:// 协议')
+    .option('--fileId <id>', '文件 ID（纯数字）。从 URL 中 /file/ 后面的数字')
+    .option('--output <path>', '输出 JSON 文件路径。不指定则保存到系统临时目录')
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (options: GetAllPagesOptions) => {
+      await handleGetAllPages(options)
+    })
+}
+
+/**
+ * 处理 get_all_pages 命令
+ */
+async function handleGetAllPages(options: GetAllPagesOptions): Promise<void> {
+  // 提取 fileId
+  let fileId: string | null = null
+  
+  if (options.fileId) {
+    fileId = options.fileId
+  } else if (options.link) {
+    fileId = extractFileId(options.link)
+    if (!fileId) {
+      console.error('错误: 无法从链接中提取 fileId')
+      console.error('支持的格式:')
+      console.error('  - 完整 URL: https://mastergo.netease.com/file/174875497054651')
+      console.error('  - mgp 协议: mgp://mastergo.netease.com/file/174875497054651')
+      console.error('  - 纯 fileId: 174875497054651')
+      process.exit(1)
+    }
+  } else {
+    // 没有提供参数，获取当前连接页面的所有页面
+    console.log('未提供 --link 或 --fileId，将获取当前连接页面的所有页面信息')
+  }
+
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 构建 pageUrl（如果有 fileId）
+    let pageUrl: string | undefined
+    if (fileId) {
+      // 构建标准化的 pageUrl
+      pageUrl = `mastergo.netease.com/file/${fileId}`
+    }
+
+    // 发送请求
+    const data = await client.requestWithRetry<AllPagesInfo>(
+      MessageType.GET_ALL_PAGES,
+      {},
+      pageUrl
+    )
+
+    // 确定输出路径
+    let outputPath: string
+    if (options.output) {
+      outputPath = resolve(options.output)
+    } else {
+      // 使用系统临时目录
+      const filename = `pages_${fileId || 'current'}_${Date.now()}.json`
+      outputPath = resolve(tmpdir(), filename)
+    }
+
+    // 确保目录存在
+    const outputDir = dirname(outputPath)
+    mkdirSync(outputDir, { recursive: true })
+
+    // 保存到文件
+    const jsonContent = JSON.stringify(data, null, 2)
+    writeFileSync(outputPath, jsonContent, 'utf-8')
+
+    // 输出结果
+    const size = jsonContent.length
+    const sizeKB = (size / 1024).toFixed(2)
+    console.log(`文件路径: ${outputPath}`)
+    console.log(`文档名称: ${data.documentName}`)
+    console.log(`页面数量: ${data.totalCount}`)
+    console.log(`数据大小: ${size.toLocaleString()} 字符 (约 ${sizeKB} KB)`)
+  } catch (error) {
+    console.error(`错误: ${error instanceof Error ? error.message : error}`)
+    process.exit(1)
+  } finally {
+    client.close()
+  }
+}

package/src/cli/commands/get-node-by-id.ts

@@ -0,0 +1,83 @@
+/**
+ * get_node_by_id 命令
+ * 根据节点 ID 获取节点详细信息
+ */
+
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient } from '../client.js'
+import type { GetNodeParams, NodeInfo } from '../../shared/types.js'
+
+interface GetNodeByIdOptions {
+  nodeId: string
+  output: string
+  maxDepth?: string
+  includeInvisible?: boolean
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/**
+ * 创建 get_node_by_id 命令
+ */
+export function createGetNodeByIdCommand(): Command {
+  return new Command('get_node_by_id')
+    .description('根据节点 ID 获取节点详细信息。数据保存到指定 JSON 文件，返回文件路径和大小信息')
+    .requiredOption('--nodeId <id>', '节点 ID，格式如 123:456。可从 MasterGo 浮窗链接中获取')
+    .requiredOption('--output <path>', '输出 JSON 文件路径。支持绝对路径或相对路径')
+    .option('--maxDepth <number>', '遍历深度，默认 1。增加深度会显著增加数据量', '1')
+    .option('--includeInvisible', '包含不可见节点（visible: false），默认不包含', false)
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (options: GetNodeByIdOptions) => {
+      await handleGetNodeById(options)
+    })
+}
+
+/**
+ * 处理 get_node_by_id 命令
+ */
+async function handleGetNodeById(options: GetNodeByIdOptions): Promise<void> {
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 发送请求
+    const params: GetNodeParams = {
+      nodeId: options.nodeId,
+      maxDepth: parseInt(options.maxDepth || '1', 10),
+      includeInvisible: options.includeInvisible || false,
+    }
+
+    const data = await client.requestWithRetry<NodeInfo>(MessageType.GET_NODE_BY_ID, params)
+
+    // 保存到文件
+    const outputPath = resolve(options.output)
+    const outputDir = dirname(outputPath)
+    mkdirSync(outputDir, { recursive: true })
+
+    const jsonContent = JSON.stringify(data, null, 2)
+    writeFileSync(outputPath, jsonContent, 'utf-8')
+
+    // 输出结果
+    const size = jsonContent.length
+    const sizeKB = (size / 1024).toFixed(2)
+    console.log(`文件路径: ${outputPath}`)
+    console.log(`节点 ID: ${options.nodeId}`)
+    console.log(`数据大小: ${size.toLocaleString()} 字符 (约 ${sizeKB} KB)`)
+    console.log(`节点深度: ${params.maxDepth}`)
+  } catch (error) {
+    console.error(`错误: ${error instanceof Error ? error.message : error}`)
+    process.exit(1)
+  } finally {
+    client.close()
+  }
+}

package/src/cli/commands/get-node-by-link.ts

@@ -0,0 +1,105 @@
+/**
+ * get_node_by_link 命令
+ * 解析 mgp:// 协议链接并获取节点信息
+ */
+
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { MessageType } from '../../shared/constants.js'
+import { MGClient, parseMgpLink } from '../client.js'
+import { ErrorCode, MGError } from '../../shared/errors.js'
+import type { GetNodeParams, NodeInfo } from '../../shared/types.js'
+
+interface GetNodeByLinkOptions {
+  link: string
+  output: string
+  maxDepth?: string
+  includeInvisible?: boolean
+  noAutoStart?: boolean
+  noRetry?: boolean
+}
+
+/**
+ * 创建 get_node_by_link 命令
+ */
+export function createGetNodeByLinkCommand(): Command {
+  return new Command('get_node_by_link')
+    .description('解析 mgp:// 协议链接并获取节点信息')
+    .requiredOption('--link <url>', 'mgp:// 协议链接')
+    .requiredOption('--output <path>', '输出 JSON 文件路径')
+    .option('--maxDepth <number>', '遍历深度', '1')
+    .option('--includeInvisible', '包含不可见节点', false)
+    .option('--no-auto-start', '禁用自动启动 Server')
+    .option('--no-retry', '禁用自动重试')
+    .action(async (options: GetNodeByLinkOptions) => {
+      await handleGetNodeByLink(options)
+    })
+}
+
+/**
+ * 处理 get_node_by_link 命令
+ */
+async function handleGetNodeByLink(options: GetNodeByLinkOptions): Promise<void> {
+  // 解析 mgp:// 链接
+  const parsed = parseMgpLink(options.link)
+  if (!parsed) {
+    console.error(`错误 [${ErrorCode.INVALID_LINK}]: 无效的 mgp:// 链接格式`)
+    console.error(`提供的链接: ${options.link}`)
+    console.error(`期望格式: mgp://[mastergo_page_url]/nodeId`)
+    process.exit(1)
+  }
+
+  const { pageUrl, nodeId } = parsed
+
+  const client = new MGClient({
+    noAutoStart: options.noAutoStart,
+    noRetry: options.noRetry,
+  })
+
+  try {
+    // 连接 Server
+    await client.connect()
+
+    // 发送请求
+    const params: GetNodeParams = {
+      nodeId,
+      maxDepth: parseInt(options.maxDepth || '1', 10),
+      includeInvisible: options.includeInvisible || false,
+    }
+
+    const data = await client.requestWithRetry<NodeInfo>(
+      MessageType.GET_NODE_BY_ID,
+      params,
+      pageUrl
+    )
+
+    // 保存到文件
+    const outputPath = resolve(options.output)
+    const outputDir = dirname(outputPath)
+    mkdirSync(outputDir, { recursive: true })
+
+    const jsonContent = JSON.stringify(data, null, 2)
+    writeFileSync(outputPath, jsonContent, 'utf-8')
+
+    // 输出结果
+    const size = jsonContent.length
+    const sizeKB = (size / 1024).toFixed(2)
+    console.log(`文件路径: ${outputPath}`)
+    console.log(`Link: ${options.link}`)
+    console.log(`页面 URL: ${pageUrl}`)
+    console.log(`节点 ID: ${nodeId}`)
+    console.log(`数据大小: ${size.toLocaleString()} 字符 (约 ${sizeKB} KB)`)
+    console.log(`节点深度: ${params.maxDepth}`)
+  } 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()
+  }
+}

package/src/cli/commands/server.ts

@@ -0,0 +1,130 @@
+/**
+ * Server 管理命令
+ */
+
+import { Command } from 'commander'
+import {
+  startServerForeground,
+  startServerDaemon,
+  stopServer,
+  restartServer,
+  getServerStatus,
+} from '../../server/daemon.js'
+
+/**
+ * 创建 server 命令组
+ */
+export function createServerCommand(): Command {
+  const serverCmd = new Command('server')
+    .description('Server 管理命令')
+
+  // server start
+  serverCmd
+    .command('start')
+    .description('启动 MG Server')
+    .option('--port <number>', '指定启动端口', (value) => parseInt(value, 10))
+    .option('--foreground', '前台模式运行（不作为守护进程）', false)
+    .action(async (options) => {
+      try {
+        if (options.foreground) {
+          await startServerForeground(options.port)
+        } else {
+          const info = await startServerDaemon(options.port)
+          console.log('MG Server 启动成功')
+          console.log(`监听端口: ${info.port}`)
+          console.log(`进程 PID: ${info.pid}`)
+          console.log(`运行模式: 守护进程`)
+        }
+      } catch (error: any) {
+        console.error(`错误: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  // server stop
+  serverCmd
+    .command('stop')
+    .description('停止 MG Server')
+    .action(() => {
+      try {
+        const { stopped, info } = stopServer()
+
+        if (stopped && info) {
+          console.log('MG Server 已停止')
+          console.log(`PID: ${info.pid}`)
+
+          // 计算运行时长
+          const uptimeMs = Date.now() - new Date(info.startedAt).getTime()
+          const seconds = Math.floor(uptimeMs / 1000)
+          const minutes = Math.floor(seconds / 60)
+          const hours = Math.floor(minutes / 60)
+
+          let uptime = ''
+          if (hours > 0) {
+            uptime = `${hours} 小时 ${minutes % 60} 分钟`
+          } else if (minutes > 0) {
+            uptime = `${minutes} 分钟 ${seconds % 60} 秒`
+          } else {
+            uptime = `${seconds} 秒`
+          }
+
+          console.log(`运行时长: ${uptime}`)
+        } else {
+          console.log('MG Server 未运行')
+        }
+      } catch (error: any) {
+        console.error(`错误: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  // server restart
+  serverCmd
+    .command('restart')
+    .description('重启 MG Server')
+    .option('--port <number>', '重启后使用的端口', (value) => parseInt(value, 10))
+    .action(async (options) => {
+      try {
+        const status = getServerStatus()
+
+        if (status.running) {
+          console.log(`正在停止 MG Server (PID: ${status.pid})...`)
+        }
+
+        const info = await restartServer(options.port)
+
+        console.log('MG Server 已重启')
+        console.log(`监听端口: ${info.port}`)
+        console.log(`新进程 PID: ${info.pid}`)
+      } catch (error: any) {
+        console.error(`错误: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  // server status
+  serverCmd
+    .command('status')
+    .description('查看 Server 运行状态')
+    .action(() => {
+      try {
+        const status = getServerStatus()
+
+        if (status.running) {
+          console.log('MG Server 状态: 运行中 ✓')
+          console.log(`监听端口: ${status.port}`)
+          console.log(`进程 PID: ${status.pid}`)
+          console.log(`启动时间: ${status.startedAt}`)
+          console.log(`运行时长: ${status.uptime}`)
+        } else {
+          console.log('MG Server 状态: 未运行 ✗')
+          console.log("提示: 使用 'mg-cli server start' 启动 Server")
+        }
+      } catch (error: any) {
+        console.error(`错误: ${error.message}`)
+        process.exit(1)
+      }
+    })
+
+  return serverCmd
+}

package/src/cli/index.ts

@@ -0,0 +1,33 @@
+/**
+ * MG CLI 入口
+ */
+
+import { Command } from 'commander'
+import { createServerCommand } from './commands/server.js'
+import { createGetNodeByIdCommand } from './commands/get-node-by-id.js'
+import { createGetNodeByLinkCommand } from './commands/get-node-by-link.js'
+import { createGetAllNodesCommand } from './commands/get-all-nodes.js'
+import { createExportImageCommand } from './commands/export-image.js'
+import { createExecuteCodeCommand } from './commands/execute-code.js'
+import { createGetAllPagesCommand } from './commands/get-all-pages.js'
+
+const program = new Command()
+
+program
+  .name('mg-cli')
+  .description('MasterGo CLI 工具 - 用于 Claude Code 与 MasterGo 通信')
+  .version('1.0.0')
+
+// 添加 server 命令组
+program.addCommand(createServerCommand())
+
+// 添加业务命令
+program.addCommand(createGetNodeByIdCommand())
+program.addCommand(createGetNodeByLinkCommand())
+program.addCommand(createGetAllNodesCommand())
+program.addCommand(createExportImageCommand())
+program.addCommand(createExecuteCodeCommand())
+program.addCommand(createGetAllPagesCommand())
+
+// 解析命令行参数
+program.parse()

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * MG CLI 包入口
+ */
+
+// 导出共享模块
+export * from './shared/index.js'
+
+// 导出 Server 模块
+export * from './server/index.js'