@yufengtadian/freedom-cli 1.0.0 → 1.1.11

package/README.md

@@ -1,8 +1,15 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.1.11）。
 
-基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件，前端页面内存加载，不占本地端口。
+基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
+
+**v1.1.11 核心升级**：不再依赖 Go 工具链。壳层以预编译二进制随 npm 包分发（`shell/<platform>/`），`freedom build` 直接复制壳 + 写入前端与配置即可出包，Windows / macOS / Linux 三平台一次全出，任意前后端语言自由组合。
+
+**v1.1.11 新特性**：
+- `freedom tui` 交互式终端界面：菜单化完成打包 / 新建项目 / 修改配置 / 壳管理 / 教程，零依赖、方向键 + 回车导航、支持搜索过滤与多选；
+- 前端构建缓存：源码无改动时跳过重复 `vite build`（秒级复用，典型加速 10 倍+），`--no-cache` 强制全量重建；
+- 多平台分发并行化：`--platform all` 各平台同时复制分发，全平台打包耗时显著缩短。
 
 ## 安装
 
@@ -20,16 +27,28 @@ freedom init my-app
 cd my-app
 npm install
 
-# 2. 调整标题栏（可选，随时可改）
+# 2. 交互式终端界面（方向键 + 回车选择，q 返回）
+freedom tui
+
+# 3. 调整标题栏（可选，随时可改）
 freedom titlebar native      # 保留系统原生标题栏（默认）
 freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
 freedom titlebar frameless   # 完全无边框，按钮由前端自绘（模板已内置示例）
 
-# 3. 打包
-freedom build
+# 4. 打包
+freedom build                        # 默认当前平台
+freedom build --platform all         # 三平台全量（win + mac + linux）
+freedom build --platform win-x64     # 仅 Windows
+freedom build --platform mac-arm64   # 仅 macOS Apple Silicon
+freedom build --platform linux-x64   # 仅 Linux
+freedom build --no-cache             # 忽略前端构建缓存，强制重建
 ```
 
-构建产物默认输出到 `dist/`，Windows 下为 `dist/<应用名>.exe`。产物为 GUI 子系统程序，运行时不会弹出 cmd 黑窗。
+构建产物默认输出到 `dist/`。`dist/<应用名>.exe`（或对应平台可执行文件）为壳层程序，运行时从 `dist/resources/` 加载前端页面与配置，不弹 cmd 黑窗。
+
+**构建缓存**：CLI 会在 `.freedom/vite-dist/` 记录前端源码指纹，源码无改动时复用上次构建产物直接进入分发阶段（秒级完成）。修改了 `src/` / `index.html` / `vite.config.js` 等任一处会触发自动重建；需要强制全量时可加 `--no-cache`。
+
+**三平台打包**：壳层二进制随包分发，无需本机安装 Go 或交叉编译工具链。首次构建某平台时若本地缺少对应壳二进制，CLI 自动从 GitHub Releases 下载（`freedom shell download <platform>` 可手动补齐）；仅当你想用本机 Go 工具链亲自编译壳时才需要 `freedom shell build`（只产出本机平台）。多平台分发为并行执行，全平台打包耗时大幅缩短。
 
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
@@ -78,19 +97,37 @@ window.freedom.window.minimize();                       // 窗口控制
 ## 构建要求
 
 - Node.js >= 18
-- Go 工具链（编译壳层，需支持 CGO；Windows 下需要 MSVC 编译环境与 WebView2 运行时，Win10/11 自带）
+- 不需要 Go 工具链（壳层为随包分发的预编译二进制）
+- 可选：`freedom shell build` 需本机 Go（含 CGO，Windows 需 MSVC 编译环境），仅用于亲自编译壳
 
 ## 命令
 
 ```
+freedom tui                          # 交互式终端界面
 freedom init <目录> [--force]
-freedom build
+freedom build [--platform win-x64|mac-arm64|linux-x64|all] [--no-cache]
 freedom titlebar <native|hidden|frameless>
 freedom config [get|set]
+freedom shell list|download <platform>|build <platform>
 freedom tutorial
 freedom help
 ```
 
+## 任意语言后端
+
+壳与后端进程通过 stdin/stdout 的 NDJSON/JSON-RPC 桥接（协议语言无关），因此后端可用任意语言实现（Node / Python / Rust / Go / C#…）。
+
+在 `freedom.config.js` 中声明后端进程，`freedom build` 会把你的 `backend/` 目录原样分发到 `dist/resources/backend/`，壳启动时自动以 `resources/` 为工作目录拉起后端进程（Windows 下后端黑窗同样隐藏）：
+
+```js
+export default {
+  ...
+  backend: { command: 'node', args: ['backend/main.mjs'] },
+};
+```
+
+后端只需读写 stdin/stdout，示例见模板注释与 `tutorial` 教程。
+
 ## 关于生成产物
 
 本工具生成的所有文件（含模板与构建产物）均干净整洁，无任何冗余尾注，可直接作为交付物使用。

package/lib/build.js

@@ -1,16 +1,33 @@
 'use strict';
 
+// freedom build：前端打包 + 通用壳分发（v1.1.10，零语言工具链）
+//
+// 流程（不再调用 go build / 不依赖 Go）：
+//   1. 前端打包：npm install（如缺依赖）+ vite build -> .freedom/vite-dist/index.html
+//   2. 选择目标平台：--platform <win|mac|linux|all>（默认当前平台）
+//   3. 每个平台：
+//      - 取预编译通用壳二进制（包内 shell/<plat>/，缺失自动从 GitHub Releases 下载）
+//      - 写 resources/index.html（前端单文件页）
+//      - 写 resources/config.json（窗口 + 后端配置，壳运行时读取）
+//      - 复制壳为 outDir/<app>[.exe]
+//      - 复制 backend/ 到 resources/backend/（配置了 backend 时）
+//
+// 产物不嵌入 HTML，页面与配置均在 exe 同目录 resources/ 下，因此壳可复用、
+// 可跨平台分发、无需在目标机器安装任何语言运行时。
+
 const fs = require('fs');
+const fsp = fs.promises;
 const path = require('path');
-const os = require('os');
 const { spawnSync } = require('child_process');
-const { goTemplateDir, copyDir, goJSONString } = require('./utils');
-
-const TITLEBAR_MAP = {
-  native: 'freedom.TitleBarNative',
-  hidden: 'freedom.TitleBarHidden',
-  frameless: 'freedom.TitleBarFrameless',
-};
+const { copyDir } = require('./utils');
+const {
+  ALL_PLATFORMS,
+  isWinPlat,
+  platformExeName,
+  nativePlatform,
+  localShellPath,
+} = require('./utils');
+const { hasShell, downloadShell } = require('./shell');
 
 function run(cmd, args, opts = {}) {
   // Windows 下 npm 是 .cmd 批处理，必须经 shell 执行
@@ -29,12 +46,17 @@ function run(cmd, args, opts = {}) {
   return res;
 }
 
-function checkGo() {
-  const res = run('go', ['version']);
-  if (res.status !== 0) {
-    throw new Error('未检测到 Go 工具链。请先安装 Go（https://go.dev/dl/），并确保 go 命令在 PATH 中。');
-  }
-  return res.stdout.trim();
+// --platform 解析：win|mac|linux|all 或平台 key（win-x64 等）
+function parsePlatforms(raw) {
+  if (!raw) return [nativePlatform()];
+  const v = String(raw).toLowerCase();
+  if (v === 'all') return ALL_PLATFORMS;
+  const keyMap = { win: 'win-x64', mac: 'darwin-x64', linux: 'linux-x64' };
+  if (keyMap[v]) return [keyMap[v]];
+  if (ALL_PLATFORMS.includes(v)) return [v];
+  throw new Error(
+    `未知平台：${raw}。可选：win / mac / linux / all，或 ${ALL_PLATFORMS.join(' / ')}`
+  );
 }
 
 async function build(projectDir, opts = {}) {
@@ -47,118 +69,185 @@ async function build(projectDir, opts = {}) {
   const cfg = await loadConfig(dir);
 
   const name = (cfg.name || 'freedom-app').replace(/[^a-zA-Z0-9_.-]/g, '-');
-  const titlebar = TITLEBAR_MAP[cfg.titlebar] || 'freedom.TitleBarNative';
-
-  // 产物目录：默认 dist，可配置为 '.'（项目根目录，即 dist 的上级）或任意相对/绝对目录。
   const outDir = String(cfg.outDir || 'dist').trim() || 'dist';
   const outDirPath = path.resolve(dir, outDir);
-  const exeName = os.platform() === 'win32' ? `${name}.exe` : name;
-  const outFile = path.join(outDirPath, exeName);
+  const platforms = parsePlatforms(opts.platform);
+  const autoDownload = opts.autoDownload !== false;
 
-  checkGo();
-
-  // 1) 前端打包：npm install（如缺依赖）+ vite build -> .freedom/vite-dist/index.html
+  // 1) 前端打包（带缓存：源码未变更时复用上次 vite 产物，跳过 npm run build）
   ensureNodeModules(dir);
-  const vite = run('npm', ['run', 'build'], { cwd: dir });
-  if (vite.status !== 0) {
-    throw new Error(`前端打包失败：\n${vite.stdout}\n${vite.stderr}`);
+  const useCache = opts.noCache !== true;
+  if (useCache && !viteNeedsRebuild(dir)) {
+    process.stdout.write('[freedom] 前端源码无改动，复用构建缓存...\n');
+  } else {
+    const vite = run('npm', ['run', 'build'], { cwd: dir });
+    if (vite.status !== 0) {
+      throw new Error(`前端打包失败：\n${vite.stdout}\n${vite.stderr}`);
+    }
+    writeViteCacheMarker(dir);
   }
   const distHtml = path.join(dir, '.freedom', 'vite-dist', 'index.html');
   if (!fs.existsSync(distHtml)) {
     throw new Error(`前端打包完成但未找到 ${distHtml}，请检查 vite 配置（vite-plugin-singlefile）。`);
   }
+  const html = fs.readFileSync(distHtml, 'utf8');
+  const configJSON = renderConfigJSON(cfg, name);
 
-  // 2) 组装壳层构建目录
-  const buildDir = path.join(dir, '.freedom', 'build');
-  fs.rmSync(buildDir, { recursive: true, force: true });
-  fs.mkdirSync(buildDir, { recursive: true });
-  copyDir(goTemplateDir(), buildDir);
-
-  // 3) 写入前端产物与后端
-  fs.copyFileSync(distHtml, path.join(buildDir, 'pkg', 'freedom', 'assets', 'index.html'));
+  // 2) 后端目录（若配置了 backend 进程）
   const backendDir = path.join(dir, cfg.backendDir || 'backend');
-  if (cfg.backend && fs.existsSync(backendDir)) {
-    copyDir(backendDir, path.join(buildDir, 'backend'));
+  const hasBackend = !!(cfg.backend && fs.existsSync(backendDir));
+
+  // 3) 逐平台分发（多平台并行，显著缩短全平台打包耗时）
+  // 单平台直接输出到 outDir；多平台各自放到 outDir/<plat>/ 子目录，避免互相覆盖
+  const multi = platforms.length > 1;
+  const results = await Promise.all(
+    platforms.map(async (plat) => {
+      const targetDir = multi ? path.join(outDirPath, plat) : outDirPath;
+      const outFile = await emitPlatform({ plat, name, targetDir, html, configJSON, backendDir, hasBackend, autoDownload });
+      return { plat, outFile };
+    })
+  );
+
+  return { results };
+}
+
+async function emitPlatform({ plat, name, targetDir, html, configJSON, backendDir, hasBackend, autoDownload }) {
+  // 取预编译壳二进制
+  const shell = localShellPath(plat);
+  if (!fs.existsSync(shell)) {
+    if (!autoDownload) {
+      throw new Error(
+        `缺少平台 ${plat} 的壳二进制：${shell}\n` +
+          `可运行 freedom shell download ${plat} 下载，或 freedom shell build ${plat} 本地编译。`
+      );
+    }
+    process.stdout.write(`[freedom] 本地无 ${plat} 壳，尝试自动下载...\n`);
+    await downloadShell(plat);
   }
 
-  // 4) 生成 gen_config.go
-  const genConfig = renderGenConfig(cfg, name, titlebar);
-  fs.writeFileSync(path.join(buildDir, 'gen_config.go'), genConfig, 'utf8');
+  await fsp.mkdir(targetDir, { recursive: true });
 
-  // 5) 编译壳层
-  fs.mkdirSync(outDirPath, { recursive: true });
-  if (process.env.FREEDOM_SKIP_CGO) {
-    console.log(`[freedom] FREEDOM_SKIP_CGO=1，跳过 CGO 编译，壳层源码保留在 .freedom/build。`);
-    return { outFile: null, buildDir };
+  // 壳二进制 -> 应用可执行文件
+  const exeName = platformExeName(plat, name);
+  const outFile = path.join(targetDir, exeName);
+  await fsp.copyFile(shell, outFile);
+  if (!isWinPlat(plat)) {
+    await fsp.chmod(outFile, 0o755);
   }
-  const tidy = run('go', ['mod', 'tidy'], { cwd: buildDir });
-  if (tidy.status !== 0) {
-    throw new Error(`go mod tidy 失败：\n${tidy.stdout}\n${tidy.stderr}`);
+
+  // 写 resources：页面 + 配置 + 后端
+  const resDir = path.join(targetDir, 'resources');
+  await fsp.mkdir(resDir, { recursive: true });
+  await fsp.writeFile(path.join(resDir, 'index.html'), html, 'utf8');
+  await fsp.writeFile(path.join(resDir, 'config.json'), configJSON, 'utf8');
+  if (hasBackend) {
+    copyDir(backendDir, path.join(resDir, 'backend'));
   }
-  // Windows 用 GUI 子系统编译（-H windowsgui），运行时不弹出 cmd 黑窗。
-  // 注意：go 的 flag 必须在位置参数（'.'）之前，否则会被当作 import path。
-  const ldflags = process.platform === 'win32' ? ['-ldflags', '-H windowsgui'] : [];
-  const buildRes = run('go', ['build', ...ldflags, '-o', outFile, '.'], {
-    cwd: buildDir,
-    env: { ...process.env, CGO_ENABLED: '1' },
-  });
-  if (buildRes.status !== 0) {
-    throw new Error(`Go 编译失败：\n${buildRes.stdout}\n${buildRes.stderr}`);
+
+  return outFile;
+}
+
+// 渲染 resources/config.json（与壳 configfile.go 的 runtimeConfigFile 字段对齐）
+function renderConfigJSON(cfg, name) {
+  const obj = {
+    name,
+    title: cfg.title || cfg.name || name,
+    titlebar: cfg.titlebar || 'native',
+    width: intVal(cfg.width, 1024),
+    height: intVal(cfg.height, 720),
+    minWidth: intVal(cfg.minWidth, 400),
+    minHeight: intVal(cfg.minHeight, 300),
+    center: typeof cfg.center === 'boolean' ? cfg.center : true,
+    debug: typeof cfg.debug === 'boolean' ? cfg.debug : false,
+  };
+  if (cfg.backend && Array.isArray(cfg.backend.command) && cfg.backend.command.length > 0) {
+    // 兼容 command 为数组形式：command=[cmd, ...args]
+    obj.backend = { command: cfg.backend.command[0], args: cfg.backend.command.slice(1) };
+  } else if (cfg.backend && typeof cfg.backend.command === 'string' && cfg.backend.command) {
+    obj.backend = {
+      command: cfg.backend.command,
+      args: Array.isArray(cfg.backend.args) ? cfg.backend.args : [],
+    };
   }
+  return JSON.stringify(obj, null, 2);
+}
 
-  // 6) 产物分发到 outDir：
-  //    - exe：已输出到 outDir；
-  //    - 单文件 index.html：outDir 非项目根目录时才写入（避免覆盖项目源文件）；
-  //    - backend：随应用一起分发。
-  if (path.resolve(outDirPath) !== dir) {
-    fs.copyFileSync(distHtml, path.join(outDirPath, 'index.html'));
+// ---- 前端构建缓存 ----
+// 追踪影响前端产物的源文件（index.html / vite.config.* / src/**）的最新 mtime，
+// 与上次 vite build 记录值比较：未变更则跳过 npm run build，直接复用 .freedom/vite-dist 产物。
+
+function collectViteSources(dir) {
+  const files = [];
+  const roots = ['index.html', 'vite.config.js', 'vite.config.mjs', 'vite.config.ts', 'vite.config.cjs'];
+  for (const r of roots) {
+    const p = path.join(dir, r);
+    if (fs.existsSync(p)) files.push(p);
   }
-  if (cfg.backend && fs.existsSync(backendDir)) {
-    fs.mkdirSync(path.join(outDirPath, 'backend'), { recursive: true });
-    copyDir(backendDir, path.join(outDirPath, 'backend'));
+  const src = path.join(dir, 'src');
+  if (fs.existsSync(src)) {
+    const walk = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const p = path.join(d, entry.name);
+        if (entry.isDirectory()) walk(p);
+        else files.push(p);
+      }
+    };
+    walk(src);
   }
+  return files;
+}
 
-  return { outFile, buildDir };
+function maxMtime(files) {
+  return files.reduce((m, f) => {
+    try {
+      const t = fs.statSync(f).mtimeMs;
+      return t > m ? t : m;
+    } catch (e) {
+      return m;
+    }
+  }, 0);
 }
 
-function ensureNodeModules(dir) {
-  if (fs.existsSync(path.join(dir, 'node_modules'))) return;
-  const res = run('npm', ['install'], { cwd: dir, stdio: 'inherit' });
-  if (res.status !== 0) {
-    throw new Error('npm install 失败。');
-  }
+function viteCacheMarker(dir) {
+  return path.join(dir, '.freedom', 'vite-dist', '.cache-mtime');
+}
+
+function viteNeedsRebuild(dir) {
+  const distHtml = path.join(dir, '.freedom', 'vite-dist', 'index.html');
+  const marker = viteCacheMarker(dir);
+  if (!fs.existsSync(distHtml) || !fs.existsSync(marker)) return true;
+  let recorded = 0;
+  try {
+    recorded = Number(fs.readFileSync(marker, 'utf8'));
+  } catch (e) { return true; }
+  // 留 1s 容差避免文件系统时间精度抖动
+  return maxMtime(collectViteSources(dir)) > recorded + 1000;
 }
 
-function renderGenConfig(cfg, name, titlebar) {
-  const backendBlock = renderBackend(cfg);
-  const lines = [];
-  lines.push('package main');
-  lines.push('');
-  lines.push('import "freedom-cli-shell/pkg/freedom"');
-  lines.push('');
-  lines.push('// appConfig 返回应用窗口配置。');
-  lines.push('// 本文件由 freedom CLI 在 build 阶段根据 freedom.config.js 生成，');
-  lines.push('// 不要手动修改（手动修改会在下次 build 时被覆盖）。');
-  lines.push('func appConfig() freedom.Config {');
-  lines.push('    return freedom.Config{');
-  lines.push(`        Title:     ${goJSONString(cfg.name || name)},`);
-  lines.push(`        TitleBar:  ${titlebar},`);
-  lines.push(`        Width:     ${intVal(cfg.width, 1024)},`);
-  lines.push(`        Height:    ${intVal(cfg.height, 720)},`);
-  lines.push(`        MinWidth:  ${intVal(cfg.minWidth, 0)},`);
-  lines.push(`        MinHeight: ${intVal(cfg.minHeight, 0)},`);
-  lines.push(`        Center:    ${boolVal(cfg.center, true)},`);
-  lines.push(`        Debug:     ${boolVal(cfg.debug, false)},`);
-  lines.push('    }');
-  lines.push('}');
-  lines.push('');
-  return lines.join('\n');
+function writeViteCacheMarker(dir) {
+  fs.mkdirSync(path.join(dir, '.freedom', 'vite-dist'), { recursive: true });
+  fs.writeFileSync(viteCacheMarker(dir), String(maxMtime(collectViteSources(dir))), 'utf8');
 }
 
-function renderBackend(cfg) {
-  // 当前版本：后端进程方式由用户在 main 模板内手动接线；
-  // gen_config 仅承载窗口配置。此处预留注释说明。
-  return '';
+function ensureNodeModules(dir) {
+  // 缺陷修复：node_modules 存在但 package.json 更新过（依赖变更）时自动重装。
+  const pkgFile = path.join(dir, 'package.json');
+  const nmDir = path.join(dir, 'node_modules');
+  const marker = path.join(nmDir, '.package-lock.json');
+  if (!fs.existsSync(nmDir)) {
+    const res = run('npm', ['install'], { cwd: dir, stdio: 'inherit' });
+    if (res.status !== 0) throw new Error('npm install 失败。');
+    return;
+  }
+  if (fs.existsSync(pkgFile) && fs.existsSync(marker)) {
+    const pkgMtime = fs.statSync(pkgFile).mtimeMs;
+    const lockMtime = fs.statSync(marker).mtimeMs;
+    if (pkgMtime > lockMtime + 1000) {
+      process.stdout.write('[freedom] package.json 已更新，重新安装依赖...\n');
+      const res = run('npm', ['install'], { cwd: dir, stdio: 'inherit' });
+      if (res.status !== 0) throw new Error('npm install 失败。');
+    }
+  }
 }
 
 function intVal(v, dft) {
@@ -166,8 +255,4 @@ function intVal(v, dft) {
   return Number.isFinite(n) && n >= 0 ? n : dft;
 }
 
-function boolVal(v, dft) {
-  return typeof v === 'boolean' ? v : dft;
-}
-
-module.exports = { build };
+module.exports = { build, parsePlatforms };

package/lib/cli.js

@@ -14,10 +14,16 @@ function help() {
 freedom - Freedom 桌面壳打包工具 v${VERSION}
 
 用法：
+  freedom tui                           进入交互式 TUI 界面（新建/打包/配置/壳管理）
   freedom init [目录] [--force]        在当前/指定目录新建项目模板
-  freedom build                        前端打包并编译出桌面应用（产物在 dist/）
+  freedom build [--platform <p>]       前端打包并分发桌面应用（默认当前平台）
+      --platform win|mac|linux|all     指定目标平台（all = 三平台全量）
+      --no-cache                       忽略前端构建缓存，强制重新打包
   freedom titlebar <native|hidden|frameless>
                                        一键切换标题栏策略
+  freedom shell list                   列出本地已就绪的预编译壳
+  freedom shell download <plat>        从 GitHub Releases 下载预编译壳
+  freedom shell build <plat>           本地用 Go 编译壳（需要 Go）
   freedom config                       查看当前配置
   freedom config get <key>             读取单个配置项
   freedom config set <key> <value>     修改单个配置项
@@ -25,6 +31,9 @@ freedom - Freedom 桌面壳打包工具 v${VERSION}
   freedom help                         显示本帮助
   freedom version                      显示版本
 
+平台（<p>/<plat>）：win-x64 / darwin-x64 / darwin-arm64 / linux-x64 / linux-arm64，
+快捷别名：win / mac / linux / all。
+
 标题栏策略说明：
   native    保留系统原生标题栏（默认）
   hidden    隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
@@ -49,6 +58,9 @@ async function run(argv) {
       console.log(VERSION);
       return 0;
 
+    case 'tui':
+      return await require('./tui').tui(process.cwd());
+
     case 'init': {
       const force = rest.includes('--force');
       const dirArg = rest.filter((a) => a !== '--force')[0];
@@ -62,13 +74,22 @@ async function run(argv) {
     }
 
     case 'build': {
-      const { outFile } = await build(process.cwd());
-      if (outFile) {
-        console.log(`[freedom] 构建完成：${outFile}`);
+      const platArg = rest.find((a) => a.startsWith('--platform') || a.startsWith('-p'));
+      let platform;
+      if (platArg) {
+        platform = platArg.includes('=') ? platArg.split('=')[1] : rest[rest.indexOf(platArg) + 1];
+      }
+      const { results } = await build(process.cwd(), { platform, noCache: rest.includes('--no-cache') });
+      for (const r of results) {
+        console.log(`[freedom] [${r.plat}] 构建完成：${r.outFile}`);
       }
       return 0;
     }
 
+    case 'shell': {
+      return await runShell(rest);
+    }
+
     case 'titlebar': {
       const mode = rest[0];
       if (!['native', 'hidden', 'frameless'].includes(mode)) {
@@ -127,6 +148,49 @@ function coerce(value) {
   return value;
 }
 
+async function runShell(rest) {
+  const { listLocal, downloadShell, buildShell } = require('./shell');
+  const { ALL_PLATFORMS } = require('./utils');
+  const sub = rest[0];
+  switch (sub) {
+    case undefined:
+    case 'list': {
+      const ready = listLocal();
+      if (ready.length === 0) {
+        console.log('[freedom] 本地暂无预编译壳。');
+      } else {
+        console.log('[freedom] 本地已就绪的壳平台：');
+        for (const p of ready) console.log(`  ${p}`);
+      }
+      console.log(`[freedom] 可选平台：${ALL_PLATFORMS.join(' / ')}`);
+      return 0;
+    }
+    case 'download': {
+      const plat = rest[1];
+      if (!plat) {
+        console.error('[freedom] 用法：freedom shell download <win-x64|darwin-x64|darwin-arm64|linux-x64|linux-arm64>');
+        return 1;
+      }
+      const dest = await downloadShell(plat);
+      console.log(`[freedom] 已下载 ${plat} 壳：${dest}`);
+      return 0;
+    }
+    case 'build': {
+      const plat = rest[1];
+      if (!plat) {
+        console.error('[freedom] 用法：freedom shell build <win-x64|darwin-x64|darwin-arm64|linux-x64|linux-arm64>');
+        return 1;
+      }
+      const dest = buildShell(plat);
+      console.log(`[freedom] 已编译 ${plat} 壳：${dest}`);
+      return 0;
+    }
+    default:
+      console.error(`[freedom] 未知 shell 子命令：${sub}`);
+      return 1;
+  }
+}
+
 function openBrowser(file) {
   const { spawn } = require('child_process');
   const plat = process.platform;