@icyfenix-dmla/cli 2026.4.19-844 → 2026.4.19-845

package/README.md

@@ -0,0 +1,46 @@
+# @icyfenix-dmla/cli
+
+DMLA 沙箱服务命令行工具。
+
+## 安装
+
+```bash
+npm install -g @icyfenix-dmla/cli
+```
+
+## 使用
+
+```bash
+# 启动服务
+dmla start                 # 默认端口 3001
+dmla start --port 8080     # 自定义端口
+dmla start --gpu           # GPU 模式
+
+# 停止服务
+dmla stop
+
+# 查看状态
+dmla status
+
+# 安装镜像
+dmla install               # 安装所有镜像（默认从 Docker Hub）
+dmla install --cpu         # 仅 CPU 版本
+dmla install --gpu         # 仅 GPU 版本
+dmla install --registry acr  # 从阿里云 ACR 安装（国内加速）
+
+# 更新
+dmla update                # 更新 npm 包和镜像
+dmla update --registry acr
+
+# 环境诊断
+dmla doctor
+```
+
+## 要求
+
+- Node.js >= 18.0.0
+- Docker
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icyfenix-dmla/cli",
-  "version": "2026.4.19-844",
+  "version": "2026.4.19-845",
   "description": "DMLA 沙箱服务命令行工具",
   "type": "module",
   "main": "src/index.js",
@@ -9,8 +9,16 @@
   },
   "scripts": {
     "start": "node src/index.js",
+    "build": "node scripts/build.js",
+    "prepublishOnly": "npm run build",
     "test": "node --experimental-vm-modules $(npm root)/jest/bin/jest.js"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "README.md"
+  ],
   "dependencies": {
     "commander": "^12.1.0",
     "chalk": "^5.3.0",

package/scripts/build.js

@@ -0,0 +1,50 @@
+/**
+ * 构建脚本：将 local-server 代码复制到 CLI 包中
+ * 用于 npm 发布时包含完整的服务器代码
+ */
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const rootDir = path.resolve(__dirname, '../../..')
+const localServerSrc = path.resolve(rootDir, 'local-server/src')
+const cliServerDest = path.resolve(__dirname, '../src/server')
+
+console.log('📦 构建 CLI 包...')
+console.log(`   源目录: ${localServerSrc}`)
+console.log(`   目标目录: ${cliServerDest}`)
+
+// 递归复制目录
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.error(`❌ 源目录不存在: ${src}`)
+    process.exit(1)
+  }
+
+  // 创建目标目录
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true })
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      fs.copyFileSync(srcPath, destPath)
+      console.log(`   ✓ 复制: ${entry.name}`)
+    }
+  }
+}
+
+// 执行复制
+copyDir(localServerSrc, cliServerDest)
+
+console.log('✅ 服务器代码已复制到 CLI 包')

package/src/commands/server.js

@@ -6,7 +6,7 @@ import Docker from 'dockerode'
 import { spawn } from 'child_process'
 import http from 'http'
 import path from 'path'
-import { fileURLToPath } from 'url'
+import { fileURLToPath, pathToFileURL } from 'url'
 import fs from 'fs'
 
 const __filename = fileURLToPath(import.meta.url)
@@ -114,7 +114,106 @@ async function findServiceContainer() {
 }
 
 /**
- * 启动服务
+ * 查找服务器入口文件
+ */
+function findServerPath() {
+  // 开发环境路径：packages/cli/src/commands -> ../../../local-server/src/index.js
+  const serverPath = path.resolve(__dirname, '../../../local-server/src/index.js')
+  // npm 包路径：packages/cli/src/commands -> ../server/index.js
+  const standaloneServerPath = path.resolve(__dirname, '../server/index.js')
+
+  // 检查 __dirname 是否正确（调试用）
+  const cliPackageRoot = path.resolve(__dirname, '../..')
+  const expectedServerDir = path.resolve(cliPackageRoot, 'src/server')
+
+  if (fs.existsSync(serverPath)) {
+    return serverPath
+  }
+
+  if (fs.existsSync(standaloneServerPath)) {
+    return standaloneServerPath
+  }
+
+  // 调试输出：显示路径信息帮助诊断
+  console.log(chalk.yellow('⚠️ 服务入口文件查找失败'))
+  console.log(chalk.gray(`   __dirname: ${__dirname}`))
+  console.log(chalk.gray(`   开发路径: ${serverPath} (${fs.existsSync(serverPath) ? '存在' : '不存在'})`))
+  console.log(chalk.gray(`   npm路径: ${standaloneServerPath} (${fs.existsSync(standaloneServerPath) ? '存在' : '不存在'})`))
+  console.log(chalk.gray(`   CLI包根目录: ${cliPackageRoot}`))
+
+  // 检查 CLI 包根目录下的文件结构
+  const srcDir = path.resolve(cliPackageRoot, 'src')
+  if (fs.existsSync(srcDir)) {
+    console.log(chalk.gray(`   src目录内容: ${fs.readdirSync(srcDir).join(', ')}`))
+    if (fs.existsSync(expectedServerDir)) {
+      console.log(chalk.gray(`   server目录内容: ${fs.readdirSync(expectedServerDir).join(', ')}`))
+    }
+  }
+
+  return null
+}
+
+/**
+ * 同步启动服务（在当前进程运行，用于调试）
+ * @param {number} port - 服务端口
+ * @param {boolean} useGpu - 是否使用 GPU
+ */
+export async function startServerSync(port, useGpu = false) {
+  // 检查端口
+  const portAvailable = await checkPortAvailable(port)
+  if (!portAvailable) {
+    console.log(chalk.red(`❌ 端口 ${port} 已被占用`))
+    console.log(chalk.yellow('💡 提示: 使用 --port 选项指定其他端口'))
+    return
+  }
+
+  // 检查镜像
+  const imageType = useGpu ? 'gpu' : 'cpu'
+  const imageExists = await checkImageExists(imageType)
+  if (!imageExists) {
+    console.log(chalk.red(`❌ 镜像 ${useGpu ? CONFIG.imageGpu : CONFIG.imageCpu} 不存在`))
+    console.log(chalk.yellow('💡 提示: 运行 dmla install 安装镜像'))
+    return
+  }
+
+  // 检查服务是否已运行
+  const alreadyRunning = await checkServiceRunning(port)
+  if (alreadyRunning) {
+    console.log(chalk.green(`✅ 服务已在端口 ${port} 运行`))
+    return
+  }
+
+  // 查找服务器入口
+  const actualServerPath = findServerPath()
+  if (!actualServerPath) {
+    console.log(chalk.red('❌ 找不到服务入口文件'))
+    console.log(chalk.yellow('💡 提示: 确保正确安装了 @icyfenix-dmla/cli'))
+    return
+  }
+
+  console.log(chalk.gray('   同步模式启动...'))
+  console.log(chalk.gray(`   服务入口: ${actualServerPath}`))
+  console.log()
+
+  // 设置环境变量
+  process.env.PORT = port.toString()
+  process.env.USE_GPU = useGpu ? 'true' : 'false'
+  process.env.DMLA_SYNC_MODE = 'true'  // 标记同步模式，让服务器在 import 时启动
+
+  // 动态 import 服务器模块并直接运行
+  // 服务器模块会在 import 时自动启动（因为入口点检测逻辑）
+  // Windows 需要将路径转换为 file:// URL 格式
+  try {
+    const serverURL = pathToFileURL(actualServerPath).href
+    await import(serverURL)
+  } catch (error) {
+    console.log(chalk.red(`❌ 服务启动失败: ${error.message}`))
+    console.log(chalk.gray(error.stack))
+  }
+}
+
+/**
+ * 启动服务（异步模式，spawn 子进程）
  */
 export async function startServer(port, useGpu = false) {
   // 检查端口
@@ -145,14 +244,7 @@ export async function startServer(port, useGpu = false) {
   console.log(chalk.gray('   正在启动...'))
 
   try {
-    // 使用 spawn 启动 server 进程
-    const serverPath = path.resolve(__dirname, '../../../local-server/src/index.js')
-
-    // 如果 server 文件不存在，说明是独立安装模式，需要启动内置服务
-    const standaloneServerPath = path.resolve(__dirname, '../server/index.js')
-
-    const actualServerPath = fs.existsSync(serverPath) ? serverPath :
-                             fs.existsSync(standaloneServerPath) ? standaloneServerPath : null
+    const actualServerPath = findServerPath()
 
     if (!actualServerPath) {
       console.log(chalk.red('❌ 找不到服务入口文件'))
@@ -160,20 +252,61 @@ export async function startServer(port, useGpu = false) {
       return
     }
 
+    // 日志文件路径
+    const logDir = path.resolve(__dirname, '../../logs')
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true })
+    }
+    const logFile = path.join(logDir, 'server.log')
+    const errorLogFile = path.join(logDir, 'server-error.log')
+
+    console.log(chalk.gray(`   日志文件: ${logFile}`))
+
+    // 创建日志文件流
+    const logStream = fs.openSync(logFile, 'a')
+    const errorLogStream = fs.openSync(errorLogFile, 'a')
+
     const env = {
       ...process.env,
       PORT: port.toString(),
-      USE_GPU: useGpu ? 'true' : 'false'
+      USE_GPU: useGpu ? 'true' : 'false',
+      DMLA_LOG_FILE: logFile  // 传递日志文件路径给服务端
     }
 
+    // 写入启动日志
+    const timestamp = new Date().toISOString()
+    fs.writeSync(logStream, `[${timestamp}] Server starting...\n`)
+    fs.writeSync(logStream, `[${timestamp}] Server path: ${actualServerPath}\n`)
+    fs.writeSync(logStream, `[${timestamp}] Port: ${port}\n`)
+    fs.writeSync(logStream, `[${timestamp}] GPU: ${useGpu}\n`)
+
+    // 使用 spawn 启动 server 进程
+    // 重要：stdio 必须是 'ignore' 或管道，不能是 'inherit'
+    // 因为 'inherit' 会让子进程依赖父进程的 stdout，父进程退出后子进程也会退出
     const serverProcess = spawn('node', [actualServerPath], {
       env,
-      stdio: 'inherit',
-      detached: true
+      stdio: ['ignore', logStream, errorLogStream],  // stdin: ignore, stdout: log file, stderr: error log
+      detached: true,
+      windowsHide: true  // Windows 下隐藏窗口
+    })
+
+    // 监听子进程事件（调试用）
+    serverProcess.on('error', (err) => {
+      fs.writeSync(errorLogStream, `[${new Date().toISOString()}] Spawn error: ${err.message}\n`)
+    })
+
+    serverProcess.on('exit', (code, signal) => {
+      const msg = `[${new Date().toISOString()}] Process exited: code=${code}, signal=${signal}\n`
+      fs.writeSync(logStream, msg)
+      fs.writeSync(errorLogStream, msg)
     })
 
     serverProcess.unref()
 
+    // 关闭父进程中的文件描述符（子进程会保留自己的副本）
+    fs.closeSync(logStream)
+    fs.closeSync(errorLogStream)
+
     // 等待服务启动
     console.log(chalk.gray('   等待服务就绪...'))
     let attempts = 0
@@ -184,15 +317,19 @@ export async function startServer(port, useGpu = false) {
       if (running) {
         console.log(chalk.green(`✅ 服务已启动: http://localhost:${port}`))
         console.log(chalk.gray(`   健康检查: http://localhost:${port}/api/health`))
+        console.log(chalk.gray(`   日志查看: ${logFile}`))
         return
       }
       await new Promise(resolve => setTimeout(resolve, 500))
       attempts++
     }
 
-    console.log(chalk.yellow('⚠️ 服务启动超时，请检查日志'))
+    console.log(chalk.yellow('⚠️ 服务启动超时'))
+    console.log(chalk.gray(`   请查看日志: ${logFile}`))
+    console.log(chalk.gray(`   或使用 --sync 模式调试`))
   } catch (error) {
     console.log(chalk.red(`❌ 启动失败: ${error.message}`))
+    console.log(chalk.gray(error.stack))
   }
 }
 
@@ -200,7 +337,51 @@ export async function startServer(port, useGpu = false) {
  * 停止服务
  */
 export async function stopServer() {
-  // 查找运行中的容器
+  // 首先尝试通过 API 停止服务
+  const port = CONFIG.defaultPort
+  const running = await checkServiceRunning(port)
+
+  if (running) {
+    try {
+      // 调用 shutdown API
+      await new Promise((resolve, reject) => {
+        const req = http.request({
+          hostname: 'localhost',
+          port: port,
+          path: '/api/shutdown',
+          method: 'POST',
+          timeout: 5000
+        }, (res) => {
+          if (res.statusCode === 200) {
+            console.log(chalk.green('✅ 服务已停止'))
+            resolve()
+          } else {
+            reject(new Error(`HTTP ${res.statusCode}`))
+          }
+        })
+        req.on('error', (e) => reject(e))
+        req.on('timeout', () => {
+          req.destroy()
+          reject(new Error('Timeout'))
+        })
+        req.end()
+      })
+
+      // 等待服务完全关闭
+      let attempts = 0
+      while (attempts < 10) {
+        const stillRunning = await checkServiceRunning(port)
+        if (!stillRunning) break
+        await new Promise(r => setTimeout(r, 200))
+        attempts++
+      }
+      return
+    } catch (error) {
+      console.log(chalk.yellow(`⚠️ 通过 API 停止失败: ${error.message}`))
+    }
+  }
+
+  // 尝试查找并停止 Docker 容器
   const container = await findServiceContainer()
 
   if (container) {
@@ -208,14 +389,15 @@ export async function stopServer() {
       const containerObj = docker.getContainer(container.Id)
       await containerObj.stop()
       await containerObj.remove()
-      console.log(chalk.green('✅ 服务已停止'))
+      console.log(chalk.green('✅ 服务容器已停止'))
     } catch (error) {
-      console.log(chalk.red(`❌ 停止失败: ${error.message}`))
+      console.log(chalk.red(`❌ 停止容器失败: ${error.message}`))
     }
+  } else if (!running) {
+    console.log(chalk.gray('   服务未运行'))
   } else {
-    // 尝试通过端口查找进程
-    console.log(chalk.yellow('⚠️ 未找到运行中的服务容器'))
-    console.log(chalk.gray('   提示: 服务可能以非容器模式运行'))
+    console.log(chalk.yellow('⚠️ 无法停止服务'))
+    console.log(chalk.gray('   提示: 手动终止端口 3001 上的进程'))
   }
 }
 
@@ -228,7 +410,8 @@ export async function getStatus() {
   // 检查 npm 包版本
   console.log(chalk.bold('📦 npm 包版本'))
   try {
-    const pkgPath = path.resolve(__dirname, '../package.json')
+    // __dirname 是 src/commands，需要向上两级到包根目录
+    const pkgPath = path.resolve(__dirname, '../../package.json')
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
     console.log(chalk.gray(`   @icyfenix-dmla/cli: ${pkg.version}`))
   } catch {

package/src/index.js

@@ -2,18 +2,87 @@
  * DMLA CLI 入口
  * 沙箱服务命令行管理工具
  */
-import { program } from 'commander'
+import { program, Help } from 'commander'
 import chalk from 'chalk'
-import { startServer, stopServer, getStatus } from './commands/server.js'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import fs from 'fs'
+import { startServer, startServerSync, stopServer, getStatus } from './commands/server.js'
 import { updateAll, runDoctor } from './commands/manage.js'
 import { runInstallTUI } from '@icyfenix-dmla/install'
 
-const VERSION = '0.0.0' // 将在发布时由 workflow 更新
+// 从 package.json 读取版本号
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const pkgPath = path.resolve(__dirname, '../package.json')
+const VERSION = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version
+
+// 重写 Help 类的方法以输出中文标题
+Help.prototype.padWidth = function(cmd, helper) {
+  return 20
+}
+
+// 重写帮助信息格式化方法
+Help.prototype.formatHelp = function(cmd, helper) {
+  const indent = '  '
+  const itemIndent = '  '
+
+  let output = []
+
+  // 用法（中文）
+  output.push('用法:')
+  output.push(indent + helper.commandUsage(cmd))
+
+  // 说明（中文）
+  if (cmd.description()) {
+    output.push('')
+    output.push('说明:')
+    output.push(indent + cmd.description())
+  }
+
+  // 参数（中文）
+  const args = helper.visibleArguments(cmd)
+  if (args.length > 0) {
+    output.push('')
+    output.push('参数:')
+    args.forEach(arg => {
+      output.push(itemIndent + arg.name())
+    })
+  }
+
+  // 选项（中文）
+  const options = helper.visibleOptions(cmd)
+  if (options.length > 0) {
+    output.push('')
+    output.push('选项:')
+    options.forEach(opt => {
+      const term = helper.optionTerm(opt)
+      const description = helper.optionDescription(opt)
+      output.push(itemIndent + term.padEnd(20) + description)
+    })
+  }
+
+  // 命令（中文）
+  const commands = helper.visibleCommands(cmd)
+  if (commands.length > 0) {
+    output.push('')
+    output.push('命令:')
+    commands.forEach(subcmd => {
+      const term = helper.subcommandTerm(subcmd)
+      const description = helper.subcommandDescription(subcmd)
+      output.push(itemIndent + term.padEnd(20) + description)
+    })
+  }
+
+  return output.join('\n')
+}
 
 program
   .name('dmla')
   .description('DMLA 沙箱服务命令行管理工具')
-  .version(VERSION)
+  .version(VERSION, '-v, --version', '显示版本号')
+  .helpOption('-h, --help', '显示帮助信息')
+  .addHelpCommand('help [command]', '显示命令帮助信息')
 
 // ─────────────────────────────────────────────────────────────
 // start 命令
@@ -23,13 +92,24 @@ program
   .description('启动沙箱服务')
   .option('-p, --port <number>', '服务端口', '3001')
   .option('--gpu', '使用 GPU 镜像')
+  .option('--sync', '同步模式：在当前进程运行，日志直接输出（用于调试）')
   .action(async (options) => {
     const port = parseInt(options.port, 10)
     const useGpu = options.gpu
+    const sync = options.sync
+
     console.log(chalk.blue('🚀 启动 DMLA 沙箱服务...'))
     console.log(chalk.gray(`   端口: ${port}`))
     console.log(chalk.gray(`   镜像: ${useGpu ? 'GPU' : 'CPU'}`))
-    await startServer(port, useGpu)
+    if (sync) {
+      console.log(chalk.yellow(`   模式: 同步（调试模式）`))
+    }
+
+    if (sync) {
+      await startServerSync(port, useGpu)
+    } else {
+      await startServer(port, useGpu)
+    }
   })
 
 // ─────────────────────────────────────────────────────────────

package/src/server/index.js

@@ -0,0 +1,117 @@
+/**
+ * Design Machine Learning Applications 本地服务
+ * 提供 Python 代码沙箱执行 API
+ */
+import express from 'express'
+import cors from 'cors'
+import { fileURLToPath } from 'url'
+import { resolve } from 'path'
+import sandboxRouter from './routes/sandbox.js'
+
+export const app = express()
+const PORT = process.env.PORT || 3001
+
+// 日志函数
+function log(message) {
+  const timestamp = new Date().toISOString()
+  console.log(`[${timestamp}] ${message}`)
+}
+
+// 启动日志
+log('Server initializing...')
+log(`PORT: ${PORT}`)
+log(`NODE_VERSION: ${process.version}`)
+log(`PLATFORM: ${process.platform}`)
+log(`DMLA_SYNC_MODE: ${process.env.DMLA_SYNC_MODE || 'false'}`)
+
+// 中间件
+app.use(cors())
+app.use(express.json())
+
+// 请求日志中间件
+app.use((req, res, next) => {
+  log(`Request: ${req.method} ${req.path}`)
+  next()
+})
+
+// 健康检查
+app.get('/api/health', (req, res) => {
+  log('Health check request')
+  res.json({ status: 'ok', timestamp: new Date().toISOString() })
+})
+
+// 停止服务（用于 CLI stop 命令）
+app.post('/api/shutdown', (req, res) => {
+  log('Shutdown request received')
+  res.json({ status: 'shutting_down', timestamp: new Date().toISOString() })
+  // 延迟关闭，确保响应发送完成
+  setTimeout(() => {
+    log('Exiting due to shutdown request')
+    process.exit(0)
+  }, 100)
+})
+
+// 沙箱 API
+app.use('/api/sandbox', sandboxRouter)
+
+// 错误处理
+app.use((err, req, res, next) => {
+  log(`Error: ${err.message}`)
+  log(`Stack: ${err.stack}`)
+  res.status(500).json({
+    success: false,
+    error: err.message || 'Internal Server Error'
+  })
+})
+
+// 捕获未处理的异常
+process.on('uncaughtException', (err) => {
+  log(`UNCAUGHT EXCEPTION: ${err.message}`)
+  log(`Stack: ${err.stack}`)
+  process.exit(1)
+})
+
+// 捕获未处理的 Promise 拒绝
+process.on('unhandledRejection', (reason, promise) => {
+  log(`UNHANDLED REJECTION: ${reason}`)
+})
+
+// 捕获进程信号
+process.on('SIGTERM', () => {
+  log('Received SIGTERM')
+  process.exit(0)
+})
+
+process.on('SIGINT', () => {
+  log('Received SIGINT')
+  process.exit(0)
+})
+
+// 启动服务器
+// 条件1: 直接运行（入口点匹配）
+// 条件2: 同步模式（DMLA_SYNC_MODE 环境变量）
+const __filename = fileURLToPath(import.meta.url)
+const entryPoint = resolve(process.argv[1] || '')
+const shouldStart = __filename === entryPoint || process.env.DMLA_SYNC_MODE === 'true'
+
+log(`Entry point check: __filename=${__filename}, entryPoint=${entryPoint}, match=${__filename === entryPoint}`)
+
+if (shouldStart) {
+  const server = app.listen(PORT, () => {
+    log('Server started successfully')
+    log(`API: http://localhost:${PORT}`)
+    log(`Health: http://localhost:${PORT}/api/health`)
+  })
+
+  server.on('error', (err) => {
+    log(`Server error: ${err.message}`)
+  })
+
+  server.on('close', () => {
+    log('Server closed')
+  })
+} else {
+  log('Skipping server start (imported as module)')
+}
+
+export default app

package/src/server/routes/sandbox.js

@@ -0,0 +1,131 @@
+/**
+ * 沙箱 API 路由
+ */
+import { Router } from 'express'
+import sandbox, { runPythonCode, checkImageExists, checkGPUAvailable } from '../sandbox.js'
+
+const { SANDBOX_CONFIG } = sandbox
+
+const router = Router()
+
+/**
+ * 健康检查
+ */
+router.get('/health', async (req, res) => {
+  try {
+    const imageCpuExists = await checkImageExists(false)
+    const imageGpuExists = await checkImageExists(true)
+    const gpuAvailable = await checkGPUAvailable()
+
+    res.json({
+      status: 'ok',
+      images: {
+        cpu: imageCpuExists,
+        gpu: imageGpuExists
+      },
+      gpu: gpuAvailable
+    })
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      error: error.message
+    })
+  }
+})
+
+/**
+ * 执行代码
+ * POST /api/sandbox/run
+ * Body: { code: string, useGpu?: boolean }
+ */
+router.post('/run', async (req, res) => {
+  const { code, useGpu = false } = req.body
+
+  // 验证请求
+  if (!code || typeof code !== 'string') {
+    return res.status(400).json({
+      success: false,
+      error: 'Missing or invalid code parameter'
+    })
+  }
+
+  // 代码长度限制 (约 100KB)
+  if (code.length > 100000) {
+    return res.status(400).json({
+      success: false,
+      error: 'Code too long (max 100KB)'
+    })
+  }
+
+  try {
+    // 检查镜像是否存在，智能降级
+    // GPU镜像包含CPU的全部功能，如果CPU镜像不存在但GPU镜像存在，可以使用GPU镜像执行CPU代码
+    let actualUseGpu = useGpu
+    let actualImage = null  // 指定使用的镜像
+    let imageExists = await checkImageExists(useGpu)
+
+    if (!imageExists && !useGpu) {
+      // CPU镜像不存在，检查是否可以用GPU镜像替代
+      const gpuImageExists = await checkImageExists(true)
+      if (gpuImageExists) {
+        imageExists = true
+        actualUseGpu = false  // 不启用GPU设备
+        actualImage = SANDBOX_CONFIG.imageGpu  // 使用GPU镜像
+        console.log('[Sandbox] CPU镜像不存在，使用GPU镜像执行（不启用GPU设备）')
+      }
+    }
+
+    if (!imageExists) {
+      return res.status(503).json({
+        success: false,
+        error: useGpu
+          ? 'GPU 镜像未安装。请运行以下命令安装：\n\nnpm run build:sandbox:gpu\n\n或使用 dmla CLI：\n\ndmla install --gpu'
+          : '沙箱镜像未安装。请运行以下命令安装：\n\nnpm run build:sandbox:cpu\n\n或使用 dmla CLI：\n\ndmla install --cpu\n\n注意：如果您已安装 GPU 镜像，它也支持 CPU 执行'
+      })
+    }
+
+    // 如果请求 GPU，检查 GPU 是否可用
+    if (actualUseGpu) {
+      const gpuAvailable = await checkGPUAvailable()
+      if (!gpuAvailable) {
+        return res.status(503).json({
+          success: false,
+          error: `GPU 硬件不可用。请确保系统安装了 NVIDIA GPU 驱动和 nvidia-container-toolkit。\n\n诊断步骤：\n1. 运行 nvidia-smi 检查 GPU 状态\n2. 运行 docker run --rm --gpus all ${SANDBOX_CONFIG.imageGpu} nvidia-smi 测试 Docker GPU 支持\n\n或使用 dmla doctor 进行环境诊断`
+        })
+      }
+    }
+
+    // 执行代码（使用确定后的镜像）
+    const result = await runPythonCode(code, actualUseGpu, actualImage)
+
+    res.json(result)
+
+  } catch (error) {
+    console.error('Sandbox error:', error)
+    res.status(500).json({
+      success: false,
+      error: error.message || 'Internal sandbox error'
+    })
+  }
+})
+
+/**
+ * GPU 状态检查
+ */
+router.get('/gpu', async (req, res) => {
+  try {
+    const gpuAvailable = await checkGPUAvailable()
+
+    res.json({
+      available: gpuAvailable,
+      message: gpuAvailable ? 'GPU is available' : 'No GPU detected'
+    })
+  } catch (error) {
+    res.status(500).json({
+      available: false,
+      error: error.message
+    })
+  }
+})
+
+export default router

package/src/server/sandbox.js

@@ -0,0 +1,490 @@
+/**
+ * 沙箱管理模块
+ * 负责创建和管理 Docker 容器执行 Python 代码
+ */
+import Docker from 'dockerode'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import fs from 'fs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// 日志函数
+function log(message) {
+  const timestamp = new Date().toISOString()
+  console.log(`[${timestamp}] [Sandbox] ${message}`)
+}
+
+// 启动时记录
+log('Sandbox module initialized')
+
+// 检测运行模式并计算正确的路径
+// 开发模式: 从 local-server/src 运行，项目根目录在上两级
+// 独立模式: 从 packages/cli/src/server 运行，无 shared_modules 目录
+function detectProjectRoot() {
+  // 尝试向上两级查找 local-server 目录（开发模式）
+  const candidateRoot = path.resolve(__dirname, '..', '..')
+  const localServerPath = path.join(candidateRoot, 'local-server')
+  if (fs.existsSync(localServerPath)) {
+    return candidateRoot
+  }
+
+  // 尝试向上三级查找（独立模式下的项目根目录）
+  const standaloneRoot = path.resolve(__dirname, '..', '..', '..')
+  const standaloneLocalServer = path.join(standaloneRoot, 'local-server')
+  if (fs.existsSync(standaloneLocalServer)) {
+    return standaloneRoot
+  }
+
+  // 独立安装模式，无项目根目录
+  return null
+}
+
+const PROJECT_ROOT = detectProjectRoot()
+
+// 共享模块目录（仅开发模式可用）
+const DEFAULT_SHARED_MODULES_PATH = PROJECT_ROOT
+  ? path.join(PROJECT_ROOT, 'local-server', 'shared_modules')
+  : null
+
+// kernel_runner.py 路径（开发模式下可用）
+const DEFAULT_KERNEL_RUNNER_PATH = PROJECT_ROOT
+  ? path.join(PROJECT_ROOT, 'local-server', 'src', 'kernel_runner.py')
+  : null
+
+const docker = new Docker()
+
+// 沙箱配置
+const SANDBOX_CONFIG = {
+  imageCpu: 'dmla-sandbox:cpu',
+  imageGpu: 'dmla-sandbox:gpu',
+  timeout: 60000,           // 60 秒超时
+  memory: 4 * 1024 * 1024 * 1024  // 4GB 内存
+}
+
+/**
+ * 获取共享模块路径
+ */
+function getSharedModulesPath() {
+  // 优先使用环境变量指定的路径
+  if (process.env.SHARED_MODULES_PATH) {
+    return process.env.SHARED_MODULES_PATH
+  }
+  // 开发模式下的默认路径
+  return DEFAULT_SHARED_MODULES_PATH
+}
+
+/**
+ * 获取 kernel_runner.py 路径
+ */
+function getKernelRunnerPath() {
+  // 优先使用环境变量指定的路径
+  if (process.env.KERNEL_RUNNER_PATH) {
+    return process.env.KERNEL_RUNNER_PATH
+  }
+  // 开发模式下的默认路径
+  return DEFAULT_KERNEL_RUNNER_PATH
+}
+
+/**
+ * 检查是否启用 Volume Mount
+ */
+function shouldMountSharedModules() {
+  return process.env.MOUNT_SHARED_MODULES !== 'false'
+}
+
+/**
+ * 检查是否挂载本地 kernel_runner.py（开发模式）
+ */
+function shouldMountKernelRunner() {
+  return process.env.MOUNT_KERNEL_RUNNER !== 'false' && PROJECT_ROOT !== null
+}
+
+/**
+ * 检查 GPU 是否可用
+ * 使用已安装的 GPU 镜像运行 nvidia-smi 命令检测 GPU 状态
+ */
+export async function checkGPUAvailable() {
+  let container = null
+
+  try {
+    // 使用已配置的 GPU 镜像检测，而非硬编码的 nvidia/cuda 镜像
+    container = await docker.createContainer({
+      Image: SANDBOX_CONFIG.imageGpu,
+      Cmd: ['nvidia-smi', '-L'],
+      HostConfig: {
+        DeviceRequests: [{
+          Driver: 'nvidia',
+          Count: -1,  // 使用所有 GPU
+          Capabilities: [['gpu']]
+        }]
+      }
+    })
+
+    // 启动容器
+    await container.start()
+
+    // 等待执行完成
+    await container.wait()
+
+    // 获取输出日志
+    const logs = await container.logs({
+      stdout: true,
+      stderr: true
+    })
+
+    // 解析输出
+    const output = parseDockerLogs(logs)
+
+    // 检查输出是否包含 GPU 信息
+    return output.includes('GPU')
+  } catch {
+    // GPU 不可用或 Docker/nvidia-smi 执行失败
+    return false
+  } finally {
+    // 清理容器
+    if (container) {
+      try {
+        await container.remove({ force: true })
+      } catch {
+        // 忽略清理错误
+      }
+    }
+  }
+}
+
+/**
+ * 执行 Python 代码
+ * 使用 IPython Kernel 执行代码，支持富输出（图片、文本、错误等）
+ * @param {string} code - Python 代码
+ * @param {boolean} useGpu - 是否启用 GPU 设备
+ * @param {string|null} imageOverride - 可选，指定使用的镜像名称（覆盖默认选择）
+ * @returns {Promise<{success: boolean, outputs: Array, executionTime: number, gpuUsed: boolean}>}
+ */
+export async function runPythonCode(code, useGpu = false, imageOverride = null) {
+  const startTime = Date.now()
+
+  log(`runPythonCode called, useGpu=${useGpu}, code length=${code.length}, imageOverride=${imageOverride}`)
+
+  // 选择镜像：优先使用指定的镜像，否则根据 useGpu 选择
+  const image = imageOverride || (useGpu ? SANDBOX_CONFIG.imageGpu : SANDBOX_CONFIG.imageCpu)
+  log(`Using image: ${image}`)
+
+  // 创建容器配置 - 使用 kernel_runner.py 执行代码
+  const containerConfig = {
+    Image: image,
+    Cmd: ['python3', '/workspace/kernel_runner.py', '--code', code, '--timeout', String(Math.floor(SANDBOX_CONFIG.timeout / 1000))],
+    HostConfig: {
+      Memory: SANDBOX_CONFIG.memory,
+      AutoRemove: false  // 手动移除以获取日志
+    },
+    Env: [
+      'PYTHONUNBUFFERED=1'
+      // matplotlib 使用 IPython Kernel 的 inline 后端，自动发送 display_data
+    ]
+  }
+
+  log('Container config created')
+
+  // Volume Mount 配置
+  const useMount = shouldMountSharedModules()
+  const sharedModulesPath = getSharedModulesPath()
+  const mountKernelRunner = shouldMountKernelRunner()
+  const kernelRunnerPath = getKernelRunnerPath()
+
+  // 收集所有需要挂载的路径
+  const binds = []
+
+  // 挂载共享模块
+  if (useMount && sharedModulesPath && fs.existsSync(sharedModulesPath)) {
+    binds.push(`${sharedModulesPath}:/usr/local/lib/python3.11/site-packages/shared:ro`)
+    console.log(`[Sandbox] 共享模块 Volume Mount: ${sharedModulesPath}`)
+  } else if (useMount && sharedModulesPath) {
+    console.warn(`[Sandbox] 警告: 共享模块目录不存在: ${sharedModulesPath}`)
+  }
+
+  // 挂载 kernel_runner.py（开发模式调试）
+  if (mountKernelRunner && kernelRunnerPath && fs.existsSync(kernelRunnerPath)) {
+    binds.push(`${kernelRunnerPath}:/workspace/kernel_runner.py:ro`)
+    console.log(`[Sandbox] kernel_runner.py Volume Mount: ${kernelRunnerPath}`)
+  } else if (mountKernelRunner && kernelRunnerPath) {
+    console.warn(`[Sandbox] 警告: kernel_runner.py 不存在: ${kernelRunnerPath}`)
+  }
+
+  // 设置 Binds
+  if (binds.length > 0) {
+    containerConfig.HostConfig.Binds = binds
+  }
+
+  if (!PROJECT_ROOT) {
+    console.log('[Sandbox] 独立安装模式，无 Volume Mount')
+  }
+
+  // GPU 配置
+  if (useGpu) {
+    containerConfig.HostConfig.DeviceRequests = [{
+      Driver: 'nvidia',
+      Count: -1,  // 使用所有 GPU
+      Capabilities: [['gpu']]
+    }]
+  }
+
+  let container = null
+  let timeoutId = null
+
+  try {
+    // 创建容器
+    log('Creating container...')
+    container = await docker.createContainer(containerConfig)
+    log(`Container created: ${container.id}`)
+
+    // 设置超时
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        log('Execution timeout triggered')
+        reject(new Error('Execution timeout'))
+      }, SANDBOX_CONFIG.timeout + 10000)  // 额外 10 秒用于清理
+    })
+
+    // 启动容器
+    log('Starting container...')
+    await container.start()
+    log('Container started')
+
+    // 等待执行完成
+    log('Waiting for container to finish...')
+    const waitPromise = container.wait()
+
+    // 竞速: 超时 vs 正常完成
+    const result = await Promise.race([waitPromise, timeoutPromise])
+    log(`Container finished, result: ${JSON.stringify(result)}`)
+
+    // 清除超时
+    if (timeoutId) clearTimeout(timeoutId)
+
+    // 获取输出
+    log('Getting container logs...')
+    const logs = await container.logs({
+      stdout: true,
+      stderr: true
+    })
+
+    // 解析输出 - 分别处理 stdout 和 stderr
+    const { stdout, stderr } = parseDockerLogsSeparate(logs)
+    log(`Stdout length: ${stdout.length}`)
+    log(`Stderr length: ${stderr.length}`)
+
+    // stderr 可能包含调试信息
+    if (stderr.length > 0) {
+      log(`Stderr content preview: ${stderr.substring(0, 500)}`)
+    }
+
+    // stdout 可能包含 CUDA banner + JSON，需要提取 JSON 部分
+    // 找到第一个 '{' 作为 JSON 开始
+    const jsonStart = stdout.indexOf('{')
+    if (jsonStart === -1) {
+      log(`No JSON found in stdout`)
+      const executionTime = (Date.now() - startTime) / 1000
+      return {
+        success: false,
+        outputs: [{
+          type: 'error',
+          ename: 'OutputParseError',
+          evalue: 'No JSON output found',
+          traceback: [stdout.substring(0, 1000)]
+        }],
+        executionTime,
+        gpuUsed: useGpu
+      }
+    }
+
+    const rawOutput = stdout.substring(jsonStart)
+    log(`JSON extracted from position ${jsonStart}, length: ${rawOutput.length}`)
+
+    // 解析 JSON 输出
+    let parsedResult
+    try {
+      parsedResult = JSON.parse(rawOutput)
+      log('Output parsed successfully')
+    } catch (parseError) {
+      log(`JSON parse error: ${parseError.message}`)
+      // 如果 JSON 解析失败，返回原始输出作为错误
+      const executionTime = (Date.now() - startTime) / 1000
+      return {
+        success: false,
+        outputs: [{
+          type: 'error',
+          ename: 'OutputParseError',
+          evalue: 'Failed to parse kernel output',
+          traceback: [rawOutput]
+        }],
+        executionTime,
+        gpuUsed: useGpu
+      }
+    }
+
+    return {
+      success: parsedResult.success,
+      outputs: parsedResult.outputs || [],
+      executionTime: parsedResult.executionTime || (Date.now() - startTime) / 1000,
+      gpuUsed: useGpu
+    }
+
+  } catch (error) {
+    log(`Execution error: ${error.message}`)
+    log(`Error stack: ${error.stack}`)
+    // 清除超时
+    if (timeoutId) clearTimeout(timeoutId)
+
+    const executionTime = (Date.now() - startTime) / 1000
+
+    return {
+      success: false,
+      outputs: [{
+        type: 'error',
+        ename: error.name || 'ExecutionError',
+        evalue: error.message || 'Unknown error',
+        traceback: [error.message || 'Unknown error']
+      }],
+      executionTime,
+      gpuUsed: useGpu
+    }
+
+  } finally {
+    // 清理容器
+    log('Cleaning up container...')
+    if (container) {
+      try {
+        await container.remove({ force: true })
+        log('Container removed')
+      } catch (e) {
+        log(`Container cleanup error: ${e.message}`)
+      }
+    }
+  }
+}
+
+/**
+ * 解析 Docker 日志输出
+ * Docker 日志格式: [8字节头][数据]
+ */
+function parseDockerLogs(logs) {
+  if (!logs || logs.length === 0) return ''
+
+  // 如果是 Buffer
+  if (Buffer.isBuffer(logs)) {
+    let output = ''
+    let offset = 0
+
+    while (offset < logs.length) {
+      // 跳过 8 字节头
+      if (offset + 8 > logs.length) break
+
+      const streamType = logs[offset]
+      const length = logs.readUInt32BE(offset + 4)
+
+      offset += 8
+
+      if (offset + length > logs.length) break
+
+      const chunk = logs.slice(offset, offset + length).toString('utf8')
+      output += chunk
+      offset += length
+    }
+
+    return output
+  }
+
+  // 如果是字符串
+  return logs.toString()
+}
+
+/**
+ * 解析 Docker 日志输出，分别返回 stdout 和 stderr
+ * Docker 日志格式: [8字节头][数据]
+ * 头部第一个字节: 0=stdin, 1=stdout, 2=stderr
+ */
+function parseDockerLogsSeparate(logs) {
+  if (!logs || logs.length === 0) return { stdout: '', stderr: '' }
+
+  // 如果是 Buffer
+  if (Buffer.isBuffer(logs)) {
+    let stdout = ''
+    let stderr = ''
+    let offset = 0
+
+    while (offset < logs.length) {
+      // 跳过 8 字节头
+      if (offset + 8 > logs.length) break
+
+      const streamType = logs[offset]  // 1=stdout, 2=stderr
+      const length = logs.readUInt32BE(offset + 4)
+
+      offset += 8
+
+      if (offset + length > logs.length) break
+
+      const chunk = logs.slice(offset, offset + length).toString('utf8')
+
+      if (streamType === 1) {
+        stdout += chunk
+      } else if (streamType === 2) {
+        stderr += chunk
+      }
+
+      offset += length
+    }
+
+    return { stdout, stderr }
+  }
+
+  // 如果是字符串，无法区分，全部作为 stdout
+  return { stdout: logs.toString(), stderr: '' }
+}
+
+/**
+ * 检查沙箱镜像是否存在
+ */
+export async function checkImageExists(useGpu = false) {
+  const image = useGpu ? SANDBOX_CONFIG.imageGpu : SANDBOX_CONFIG.imageCpu
+
+  try {
+    await docker.getImage(image).inspect()
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 拉取沙箱镜像
+ */
+export async function pullImage(useGpu = false) {
+  const image = useGpu ? SANDBOX_CONFIG.imageGpu : SANDBOX_CONFIG.imageCpu
+
+  return new Promise((resolve, reject) => {
+    docker.pull(image, (err, stream) => {
+      if (err) {
+        reject(err)
+        return
+      }
+
+      docker.modem.followProgress(stream, (err, output) => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve(output)
+        }
+      })
+    })
+  })
+}
+
+export default {
+  runPythonCode,
+  checkGPUAvailable,
+  checkImageExists,
+  pullImage,
+  SANDBOX_CONFIG
+}

package/tests/cli.test.js

@@ -1,34 +0,0 @@
-/**
- * CLI 命令单元测试
- */
-import { describe, it, expect, beforeAll } from '@jest/globals'
-import { fileURLToPath } from 'url'
-import path from 'path'
-import fs from 'fs'
-
-// ESM 中获取 __dirname
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
-// 基础测试：确保模块可导入
-describe('CLI Module', () => {
-  beforeAll(() => {
-    // 设置测试环境
-  })
-
-  it('should have correct package.json', async () => {
-    const pkgPath = path.resolve(__dirname, '../package.json')
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-
-    expect(pkg.name).toBe('@icyfenix-dmla/cli')
-    expect(pkg.bin).toBeDefined()
-    expect(pkg.bin.dmla).toBe('./bin/dmla.js')
-  })
-
-  it('should have commander dependency', async () => {
-    const pkgPath = path.resolve(__dirname, '../package.json')
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-
-    expect(pkg.dependencies.commander).toBeDefined()
-  })
-})