@yufengtadian/freedom-cli 1.0.0 → 1.1.10

package/README.md

@@ -1,8 +1,10 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.1.10）。
 
-基于自研 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.10 核心升级**：不再依赖 Go 工具链。壳层以预编译二进制随 npm 包分发（`shell/<platform>/`），`freedom build` 直接复制壳 + 写入前端与配置即可出包，Windows / macOS / Linux 三平台一次全出，任意前后端语言自由组合。
 
 ## 安装
 
@@ -26,10 +28,16 @@ freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生
 freedom titlebar frameless   # 完全无边框，按钮由前端自绘（模板已内置示例）
 
 # 3. 打包
-freedom build
+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
 ```
 
-构建产物默认输出到 `dist/`，Windows 下为 `dist/<应用名>.exe`。产物为 GUI 子系统程序，运行时不会弹出 cmd 黑窗。
+构建产物默认输出到 `dist/`。`dist/<应用名>.exe`（或对应平台可执行文件）为壳层程序，运行时从 `dist/resources/` 加载前端页面与配置，不弹 cmd 黑窗。
+
+**三平台打包**：壳层二进制随包分发，无需本机安装 Go 或交叉编译工具链。首次构建某平台时若本地缺少对应壳二进制，CLI 自动从 GitHub Releases 下载（`freedom shell download <platform>` 可手动补齐）；仅当你想用本机 Go 工具链亲自编译壳时才需要 `freedom shell build`（只产出本机平台）。
 
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
@@ -78,19 +86,36 @@ window.freedom.window.minimize();                       // 窗口控制
 ## 构建要求
 
 - Node.js >= 18
-- Go 工具链（编译壳层，需支持 CGO；Windows 下需要 MSVC 编译环境与 WebView2 运行时，Win10/11 自带）
+- 不需要 Go 工具链（壳层为随包分发的预编译二进制）
+- 可选：`freedom shell build` 需本机 Go（含 CGO，Windows 需 MSVC 编译环境），仅用于亲自编译壳
 
 ## 命令
 
 ```
 freedom init <目录> [--force]
-freedom build
+freedom build [--platform win-x64|mac-arm64|linux-x64|all]
 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,32 @@
 '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 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 +45,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,17 +68,12 @@ 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);
-
-  checkGo();
+  const platforms = parsePlatforms(opts.platform);
+  const autoDownload = opts.autoDownload !== false;
 
-  // 1) 前端打包：npm install（如缺依赖）+ vite build -> .freedom/vite-dist/index.html
+  // 1) 前端打包
   ensureNodeModules(dir);
   const vite = run('npm', ['run', 'build'], { cwd: dir });
   if (vite.status !== 0) {
@@ -67,98 +83,106 @@ async function build(projectDir, opts = {}) {
   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 = [];
+  for (const plat of platforms) {
+    const targetDir = multi ? path.join(outDirPath, plat) : outDirPath;
+    const outFile = await emitPlatform({ plat, name, targetDir, html, configJSON, backendDir, hasBackend, autoDownload });
+    results.push({ plat, outFile });
   }
 
-  // 4) 生成 gen_config.go
-  const genConfig = renderGenConfig(cfg, name, titlebar);
-  fs.writeFileSync(path.join(buildDir, 'gen_config.go'), genConfig, 'utf8');
+  return { results };
+}
 
-  // 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 tidy = run('go', ['mod', 'tidy'], { cwd: buildDir });
-  if (tidy.status !== 0) {
-    throw new Error(`go mod tidy 失败：\n${tidy.stdout}\n${tidy.stderr}`);
-  }
-  // 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}`);
+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);
   }
 
-  // 6) 产物分发到 outDir：
-  //    - exe：已输出到 outDir；
-  //    - 单文件 index.html：outDir 非项目根目录时才写入（避免覆盖项目源文件）；
-  //    - backend：随应用一起分发。
-  if (path.resolve(outDirPath) !== dir) {
-    fs.copyFileSync(distHtml, path.join(outDirPath, 'index.html'));
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // 壳二进制 -> 应用可执行文件
+  const exeName = platformExeName(plat, name);
+  const outFile = path.join(targetDir, exeName);
+  fs.copyFileSync(shell, outFile);
+  if (!isWinPlat(plat)) {
+    fs.chmodSync(outFile, 0o755);
   }
-  if (cfg.backend && fs.existsSync(backendDir)) {
-    fs.mkdirSync(path.join(outDirPath, 'backend'), { recursive: true });
-    copyDir(backendDir, path.join(outDirPath, 'backend'));
+
+  // 写 resources：页面 + 配置 + 后端
+  const resDir = path.join(targetDir, 'resources');
+  fs.mkdirSync(resDir, { recursive: true });
+  fs.writeFileSync(path.join(resDir, 'index.html'), html, 'utf8');
+  fs.writeFileSync(path.join(resDir, 'config.json'), configJSON, 'utf8');
+  if (hasBackend) {
+    copyDir(backendDir, path.join(resDir, 'backend'));
   }
 
-  return { outFile, buildDir };
+  return outFile;
 }
 
-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 失败。');
+// 渲染 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);
 }
 
-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 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 +190,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

@@ -15,9 +15,13 @@ freedom - Freedom 桌面壳打包工具 v${VERSION}
 
 用法：
   freedom init [目录] [--force]        在当前/指定目录新建项目模板
-  freedom build                        前端打包并编译出桌面应用（产物在 dist/）
+  freedom build [--platform <p>]       前端打包并分发桌面应用（默认当前平台）
+      --platform win|mac|linux|all     指定目标平台（all = 三平台全量）
   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 +29,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 原生最小化/最大化/关闭按钮
@@ -62,13 +69,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 });
+      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 +143,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;

package/lib/shell.js

@@ -0,0 +1,139 @@
+'use strict';
+
+// 预编译壳管理：list / download / build
+//
+// 自 v1.1.10 起，Freedom 采用"通用预编译壳"架构：
+//   壳二进制（freedom-shell）是三平台预编译产物，应用内容通过 exe 同目录
+//   resources/（index.html + config.json）外部加载，因此打包时用户无需任何
+//   Go / CGO / 系统编译工具链。
+//
+// 壳二进制的三种来源（按优先级）：
+//   1. 包内自带  shell/<plat>/freedom-shell[.exe]（随 npm 包分发）
+//   2. 远程下载  GitHub Releases 资产（freedom shell download <plat>）
+//   3. 本地编译  freedom shell build <plat>（需要 Go + 对应平台编译环境）
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+const {
+  shellDir,
+  goTemplateDir,
+  ALL_PLATFORMS,
+  SHELL_EXE_NAME,
+  localShellPath,
+} = require('./utils');
+
+// GitHub Releases 下载源（可用环境变量覆盖）。
+// 资产命名约定：freedom-shell-<plat>（单文件二进制，不压缩）。
+function releaseRepo() {
+  return process.env.FREEDOM_SHELL_REPO || 'yufengtadian/freedom';
+}
+function releaseTag() {
+  return process.env.FREEDOM_SHELL_TAG || 'v1.1.10';
+}
+function releaseUrl(plat) {
+  return `https://github.com/${releaseRepo()}/releases/download/${releaseTag()}/freedom-shell-${plat}`;
+}
+
+// 列出本地已就绪的壳平台
+function listLocal() {
+  const dir = shellDir();
+  const ready = [];
+  if (fs.existsSync(dir)) {
+    for (const name of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!name.isDirectory() || !ALL_PLATFORMS.includes(name.name)) continue;
+      const exe = SHELL_EXE_NAME[name.name] || 'freedom-shell';
+      if (fs.existsSync(path.join(dir, name.name, exe))) {
+        ready.push(name.name);
+      }
+    }
+  }
+  return ready;
+}
+
+// 是否存在指定平台本地壳
+function hasShell(plat) {
+  return fs.existsSync(localShellPath(plat));
+}
+
+// 下载指定平台壳到包内 shell/<plat>/
+// 返回下载后的绝对路径；失败抛错。
+async function downloadShell(plat) {
+  if (!ALL_PLATFORMS.includes(plat)) {
+    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
+  }
+  const url = releaseUrl(plat);
+  const dest = localShellPath(plat);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
+  let res;
+  try {
+    // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
+    res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
+  } catch (e) {
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+      throw new Error(`下载壳 ${plat} 超时（30s）。请检查网络后重试，或手动将壳二进制放入 ${localShellPath(plat)}。`);
+    }
+    throw new Error(`下载壳 ${plat} 失败：${e.message}。请检查网络，或手动将壳二进制放入 ${localShellPath(plat)}。`);
+  }
+  if (!res.ok) {
+    throw new Error(
+      `下载壳失败：HTTP ${res.status}。请确认 GitHub 仓库 ${releaseRepo()} 已发布 ` +
+        `${releaseTag()} 的资产 freedom-shell-${plat}，或手动将壳二进制放入 ${localShellPath(plat)}。`
+    );
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  fs.writeFileSync(dest, buf);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(dest, 0o755);
+  }
+  return dest;
+}
+
+// 本地用 Go 编译指定平台壳（需要 Go + 该平台编译环境）。
+// Windows 产物以 GUI 子系统编译（-H windowsgui），运行时无 cmd 黑窗。
+function buildShell(plat) {
+  if (!ALL_PLATFORMS.includes(plat)) {
+    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
+  }
+  const res = spawnSync('go', ['version'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) {
+    throw new Error('未检测到 Go 工具链。请先安装 Go（https://go.dev/dl/），或改用 freedom shell download。');
+  }
+  const dest = localShellPath(plat);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  // 本机只能编译本机平台（webview_go 依赖系统 WebView 框架，无法交叉编译）。
+  const native = nativePlatformKey();
+  if (plat !== native) {
+    throw new Error(
+      `无法在本机（${native}）交叉编译 ${plat}：webview_go 依赖系统 WebView 框架。` +
+        `请在目标平台执行 freedom shell build ${plat}，或用 freedom shell download ${plat} 拉取 CI 预编译产物。`
+    );
+  }
+
+  const buildDir = goTemplateDir();
+  const ldflags = plat.startsWith('win') ? ['-ldflags', '-H windowsgui'] : [];
+  const build = spawnSync('go', ['build', ...ldflags, '-o', dest, '.'], {
+    cwd: buildDir,
+    encoding: 'utf8',
+    env: { ...process.env, CGO_ENABLED: '1' },
+  });
+  if (build.error || build.status !== 0) {
+    throw new Error(`Go 编译失败：\n${build.stdout}\n${build.stderr}`);
+  }
+  return dest;
+}
+
+function nativePlatformKey() {
+  const plat = process.platform;
+  const arch = process.arch;
+  if (plat === 'win32') return 'win-x64';
+  if (plat === 'darwin') return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  if (plat === 'linux') return arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+  return `${plat}-${arch}`;
+}
+
+module.exports = { listLocal, hasShell, downloadShell, buildShell, releaseRepo, releaseTag };

package/lib/utils.js

@@ -21,6 +21,46 @@ function goTemplateDir() {
   return path.join(templateDir(), 'go');
 }
 
+function shellDir() {
+  return path.join(PKG_ROOT, 'shell');
+}
+
+// 平台矩阵：key -> { exe 文件名（壳二进制名） }
+// 通用壳为三平台预编译二进制，应用内容通过 exe 同目录 resources/ 外部加载，
+// 因此同一壳可复用于任意应用，打包时无需任何语言工具链。
+const ALL_PLATFORMS = ['win-x64', 'darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64'];
+
+const SHELL_EXE_NAME = {
+  'win-x64': 'freedom-shell.exe',
+  'darwin-x64': 'freedom-shell',
+  'darwin-arm64': 'freedom-shell',
+  'linux-x64': 'freedom-shell',
+  'linux-arm64': 'freedom-shell',
+};
+
+function isWinPlat(plat) {
+  return plat.startsWith('win');
+}
+
+// 平台 key -> 产物可执行文件名（Windows 带 .exe，其余无扩展名）
+function platformExeName(plat, appName) {
+  return isWinPlat(plat) ? `${appName}.exe` : appName;
+}
+
+// 把 node 的 process.platform / process.arch 映射为平台 key
+function nativePlatform() {
+  const plat = process.platform;
+  const arch = process.arch;
+  if (plat === 'win32') return 'win-x64';
+  if (plat === 'darwin') return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  if (plat === 'linux') return arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+  return `${plat}-${arch}`;
+}
+
+function localShellPath(plat) {
+  return path.join(shellDir(), plat, SHELL_EXE_NAME[plat] || 'freedom-shell');
+}
+
 function tutorialFile() {
   return path.join(PKG_ROOT, 'tutorial', 'tutorial.html');
 }
@@ -62,6 +102,13 @@ module.exports = {
   templateDir,
   projectTemplateDir,
   goTemplateDir,
+  shellDir,
+  ALL_PLATFORMS,
+  SHELL_EXE_NAME,
+  isWinPlat,
+  platformExeName,
+  nativePlatform,
+  localShellPath,
   tutorialFile,
   loadConfig,
   hasConfig,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.0.0",
-  "description": "Freedom WebView desktop shell packaging tool - embed any web frontend into a cross-platform desktop app",
-  "keywords": ["desktop", "webview", "electron-alternative", "wails", "tauri", "go", "frontend"],
+  "version": "1.1.10",
+  "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
+  "keywords": ["desktop", "webview", "electron-alternative", "wails", "tauri", "frontend", "cross-platform"],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -13,6 +13,7 @@
   "files": [
     "bin",
     "lib",
+    "shell",
     "templates",
     "tutorial",
     "postinstall.js",

package/templates/go/gen_config.go

@@ -2,9 +2,12 @@ package main
 
 import "freedom-cli-shell/pkg/freedom"
 
-// appConfig 返回应用窗口配置。
-// 本文件由 freedom CLI 在 build 阶段根据 freedom.config.js 重新生成，
-// 不要手动修改（手动修改会在下次 build 时被覆盖）。
+// appConfig 返回应用窗口配置（编译期默认值）。
+//
+// 通用壳在运行时还会读取 exe 同目录 resources/config.json（由 freedom CLI build
+// 阶段根据 freedom.config.js 生成），其中的字段会覆盖本默认值。因此：
+//   - 使用预编译通用壳时，本文件中的值只是兜底，无需手动修改；
+//   - 若通过 go build 直接编译本项目（不使用 CLI），此处即为最终配置。
 func appConfig() freedom.Config {
 	return freedom.Config{
 		Title:     "Freedom App",

package/templates/go/go.sum

@@ -0,0 +1,2 @@
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6 h1:VQpB2SpK88C6B5lPHTuSZKb2Qee1QWwiFlC5CKY4AW0=
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6/go.mod h1:yE65LFCeWf4kyWD5re+h4XNvOHJEXOCOuJZ4v8l5sgk=

package/templates/go/pkg/freedom/assets/index.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Freedom</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { height: 100%; }
+  body {
+    font-family: -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+    background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%);
+    color: #e2e8f0;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    user-select: none;
+    overflow: hidden;
+  }
+  .main {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 18px;
+  }
+  .logo {
+    width: 84px; height: 84px;
+    border-radius: 22px;
+    background: linear-gradient(135deg, #6366f1, #8b5cf6);
+    display: flex; align-items: center; justify-content: center;
+    font-size: 40px; font-weight: 800; color: #fff;
+    box-shadow: 0 18px 40px rgba(99,102,241,.35);
+  }
+  h1 { font-size: 26px; font-weight: 700; letter-spacing: 1px; }
+  .sub { color: #94a3b8; font-size: 14px; }
+  .status {
+    margin-top: 8px;
+    padding: 8px 16px;
+    border-radius: 999px;
+    background: rgba(99,102,241,.15);
+    border: 1px solid rgba(99,102,241,.4);
+    color: #a5b4fc;
+    font-size: 13px;
+  }
+
+  /* 无边框模式：前端自绘标题栏（hidden / frameless 时显示） */
+  .titlebar {
+    display: none;
+    height: 36px;
+    flex: 0 0 36px;
+    background: rgba(15, 23, 42, .92);
+    border-bottom: 1px solid rgba(148,163,184,.12);
+    align-items: center;
+    justify-content: space-between;
+    padding-left: 12px;
+    -webkit-app-region: drag;   /* WebView2 支持：整条标题栏可拖拽窗口 */
+  }
+  .titlebar .tb-title { font-size: 13px; color: #cbd5e1; letter-spacing: .5px; }
+  .tb-btns { display: flex; height: 100%; -webkit-app-region: no-drag; }
+  .tb-btn {
+    width: 46px; height: 100%;
+    display: flex; align-items: center; justify-content: center;
+    border: none; background: transparent;
+    color: #cbd5e1; font-size: 12px; cursor: default;
+    font-family: "Segoe MDL2 Assets", "Segoe UI Symbol", sans-serif;
+  }
+  .tb-btn:hover { background: rgba(148,163,184,.18); color: #fff; }
+  .tb-btn.close:hover { background: #e81123; color: #fff; }
+  body.freedom-frameless .titlebar { display: flex; }
+</style>
+</head>
+<body>
+  <div class="titlebar" id="titlebar">
+    <div class="tb-title" id="tbTitle">Freedom</div>
+    <div class="tb-btns">
+      <button class="tb-btn" id="minBtn" title="最小化">&#xE921;</button>
+      <button class="tb-btn" id="maxBtn" title="最大化">&#xE922;</button>
+      <button class="tb-btn close" id="closeBtn" title="关闭">&#xE8BB;</button>
+    </div>
+  </div>
+  <div class="main">
+    <div class="logo">F</div>
+    <h1>Freedom</h1>
+    <div class="sub">WebView 桌面壳子框架 · 默认占位页</div>
+    <div class="status" id="status">初始化中...</div>
+  </div>
+  <script>
+    // 无边框模式：显示自绘标题栏并绑定窗口控制
+    if (window.freedom && window.freedom.window) {
+      window.freedom.window.isFrameless().then(function (frameless) {
+        if (frameless) {
+          document.body.classList.add('freedom-frameless');
+          window.freedom.window.bindButtons({ min: '#minBtn', max: '#maxBtn', close: '#closeBtn' });
+        }
+      }).catch(function () { /* 非桌面环境忽略 */ });
+    }
+
+    // 验证 IPC 双向桥接链路（框架内置 __freedom__ping）
+    window.freedom.call('__freedom__ping').then(function (r) {
+      document.getElementById('status').textContent = '桥接正常 · ' + r;
+    }).catch(function (e) {
+      document.getElementById('status').textContent = '桥接异常：' + e;
+    });
+  </script>
+</body>
+</html>

package/templates/go/pkg/freedom/assets_embed.go

@@ -8,8 +8,11 @@ import _ "embed"
 //go:embed assets/freedom.js
 var jsSDK string
 
-// indexHTML 是前端打包产物（Vite 单文件 HTML），build 阶段写入 assets/index.html，
-// 运行时通过 SetHtml 从内存加载。
+// indexHTML 是内置的默认占位页。
+//
+// 预编译通用壳不嵌入应用专属页面：应用 HTML 来自 exe 同目录 resources/index.html
+//（freedom CLI build 时写入，见 resolveHTML 的加载优先级）。仅当外部页面缺失时
+// 回退到本占位页，保证"直接运行壳"也有可见 UI。
 //
 //go:embed assets/index.html
 var indexHTML string

package/templates/go/pkg/freedom/backend_proc.go

@@ -70,6 +70,16 @@ func NewProcBackend(command ...string) *ProcBackend {
 	}
 }
 
+// SetDir 设置后端进程的工作目录。
+// 相对路径参数（如 "backend/main.mjs"）将相对该目录解析。
+// 通用壳在加载 resources/config.json 时自动设为 resources 目录。
+func (p *ProcBackend) SetDir(dir string) *ProcBackend {
+	if dir != "" {
+		p.cmd.Dir = dir
+	}
+	return p
+}
+
 // SetTimeout 设置单次调用的最大等待时间（默认 60s）。<=0 表示不超时。
 func (p *ProcBackend) SetTimeout(d time.Duration) *ProcBackend {
 	p.timeout = d

package/templates/go/pkg/freedom/configfile.go

@@ -0,0 +1,121 @@
+package freedom
+
+// 运行时外部资源（resources/）加载逻辑。
+//
+// 通用壳二进制（预编译）本身不嵌入任何应用专属的前端与配置；
+// 应用内容来自 exe 同目录的 resources/ 目录：
+//   resources/index.html    前端页面（CLI build 写入）
+//   resources/config.json   窗口与后端配置（CLI build 写入）
+//
+// 外部资源缺失时静默回退：配置使用编译期/默认值，页面使用内置占位页。
+// 因此同一份壳二进制可以复用于任意应用，且打包时无需任何语言工具链。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+)
+
+// runtimeBackend 描述 config.json 中的后端进程配置（任意语言，经 stdio NDJSON 桥接）。
+type runtimeBackend struct {
+	Command string   `json:"command"`
+	Args    []string `json:"args"`
+}
+
+// runtimeConfigFile 描述 resources/config.json 的磁盘结构。
+// 由 freedom CLI 在 build 阶段根据 freedom.config.js 生成。
+type runtimeConfigFile struct {
+	Name      string          `json:"name"`
+	Title     string          `json:"title"`
+	TitleBar  string          `json:"titlebar"`
+	Width     int             `json:"width"`
+	Height    int             `json:"height"`
+	MinWidth  int             `json:"minWidth"`
+	MinHeight int             `json:"minHeight"`
+	Center    *bool           `json:"center"`
+	Debug     *bool           `json:"debug"`
+	Backend   *runtimeBackend `json:"backend"`
+}
+
+// resourcesDir 返回 exe 同目录的 resources 目录绝对路径。
+func resourcesDir() (string, error) {
+	exe, err := os.Executable()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(filepath.Dir(exe), "resources"), nil
+}
+
+// loadRuntimeConfig 读取 exe 同目录 resources/config.json，将命中的字段覆盖到应用配置。
+// 文件不存在或内容非法时静默回退（返回 nil），保持编译期/默认配置不变。
+func (a *App) loadRuntimeConfig() error {
+	dir, err := resourcesDir()
+	if err != nil {
+		return nil
+	}
+	data, err := os.ReadFile(filepath.Join(dir, "config.json"))
+	if err != nil {
+		return nil
+	}
+	var rc runtimeConfigFile
+	if err := json.Unmarshal(data, &rc); err != nil {
+		return nil
+	}
+	if rc.Title != "" {
+		a.cfg.Title = rc.Title
+	} else if rc.Name != "" {
+		a.cfg.Title = rc.Name
+	}
+	switch rc.TitleBar {
+	case "native":
+		a.cfg.TitleBar = TitleBarNative
+	case "hidden":
+		a.cfg.TitleBar = TitleBarHidden
+	case "frameless":
+		a.cfg.TitleBar = TitleBarFrameless
+	}
+	if rc.Width > 0 {
+		a.cfg.Width = rc.Width
+	}
+	if rc.Height > 0 {
+		a.cfg.Height = rc.Height
+	}
+	if rc.MinWidth > 0 {
+		a.cfg.MinWidth = rc.MinWidth
+	}
+	if rc.MinHeight > 0 {
+		a.cfg.MinHeight = rc.MinHeight
+	}
+	if rc.Center != nil {
+		a.cfg.Center = *rc.Center
+	}
+	if rc.Debug != nil {
+		a.cfg.Debug = *rc.Debug
+	}
+	// 外部后端进程配置：仅在壳未显式绑定后端时生效。
+	// 工作目录设为 resources 目录，使相对路径参数（backend/main.mjs）按
+	// resources/ 解析（CLI 会把项目 backend/ 目录分发到 resources/backend/）。
+	if rc.Backend != nil && rc.Backend.Command != "" && !a.backendExplicit {
+		args := append([]string{rc.Backend.Command}, rc.Backend.Args...)
+		pb := NewProcBackend(args...)
+		if dir, err := resourcesDir(); err == nil && dir != "" {
+			pb.SetDir(dir)
+		}
+		a.cfg.Backend = pb
+		a.backend = pb
+	}
+	return nil
+}
+
+// loadRuntimeHTML 读取 exe 同目录 resources/index.html；文件不存在时返回空串。
+func loadRuntimeHTML() (string, error) {
+	dir, err := resourcesDir()
+	if err != nil {
+		return "", err
+	}
+	data, err := os.ReadFile(filepath.Join(dir, "index.html"))
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}

package/templates/go/pkg/freedom/freedom.go

@@ -65,10 +65,11 @@ type Config struct {
 
 // App 是 Freedom 应用实例。
 type App struct {
-	cfg     Config
-	view    webview.WebView
-	backend Backend
-	onReady func(a *App)
+	cfg             Config
+	view            webview.WebView
+	backend         Backend
+	backendExplicit bool // 调用方是否显式指定了后端（外部 config.json 不应覆盖显式绑定）
+	onReady         func(a *App)
 }
 
 // New 创建并初始化一个 Freedom 应用。调用 Run() 之前不会显示窗口。
@@ -85,10 +86,11 @@ func New(cfg Config) *App {
 	if cfg.Height <= 0 {
 		cfg.Height = 768
 	}
-	if cfg.Backend == nil {
+	explicit := cfg.Backend != nil
+	if !explicit {
 		cfg.Backend = NewEmbedBackend()
 	}
-	return &App{cfg: cfg, backend: cfg.Backend}
+	return &App{cfg: cfg, backend: cfg.Backend, backendExplicit: explicit}
 }
 
 // OnReady 注册一个回调，在窗口与桥接层就绪、页面加载前执行。
@@ -121,6 +123,10 @@ func (a *App) Unbind(name string) {
 
 // Run 启动窗口并进入主事件循环，阻塞直到窗口被关闭。
 func (a *App) Run() {
+	// 通用壳：先加载 exe 同目录 resources/config.json 覆盖窗口与后端配置
+	//（CLI build 时写入；缺失则使用编译期/默认配置）。
+	_ = a.loadRuntimeConfig()
+
 	html, err := a.resolveHTML()
 	if err != nil {
 		fmt.Printf("freedom: failed to resolve HTML: %v\n", err)
@@ -249,7 +255,11 @@ func (a *App) windowControl(action string) (interface{}, error) {
 }
 
 // resolveHTML 依据配置返回页面内容。
+// 优先级：exe 同目录 resources/index.html（预编译通用壳，CLI build 写入）> cfg.HTML > 内置占位页。
 func (a *App) resolveHTML() (string, error) {
+	if html, err := loadRuntimeHTML(); err == nil && html != "" {
+		return html, nil
+	}
 	if a.cfg.HTML != nil {
 		return a.cfg.HTML()
 	}

package/tutorial/tutorial.html

@@ -55,8 +55,13 @@ npm install</code></pre>
   <p>也可以直接编辑 <code>freedom.config.js</code> 里的 <code>titlebar</code> 字段。</p>
 
   <h2>3. 打包</h2>
-  <pre><code>freedom build</code></pre>
-  <p>前端会先经 Vite 打成单文件 HTML，再嵌入 Go 壳层编译出可执行文件。产物默认在 <code>dist/</code> 目录，且以 GUI 子系统编译，运行时不会弹出 cmd 黑窗。</p>
+  <pre><code>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</code></pre>
+  <p>前端经 Vite 打成单文件 HTML 后写入 <code>dist/resources/</code>，与随包分发的预编译壳二进制合并出可执行文件。不再依赖本机 Go 工具链，任一平台都能一键产出三平台产物。产物以 GUI 子系统运行，不会弹出 cmd 黑窗。</p>
+  <p><code>resources/</code> 内含壳运行时加载的前端页面 <code>index.html</code> 与配置 <code>config.json</code>；声明了 <code>backend</code> 时 <code>backend/</code> 目录会被原样分发到 <code>resources/backend/</code>，壳启动后自动以 <code>resources/</code> 为工作目录拉起后端进程（黑窗同样隐藏）。</p>
 
   <h2>3.5 调整产物目录（终端一键切换）</h2>
   <pre><code>freedom config set outDir .     # 输出到项目根目录（dist 的上级）