@yufengtadian/freedom-cli 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# freedom-cli
+
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用。
+
+基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件，前端页面内存加载，不占本地端口。
+
+## 安装
+
+```bash
+npm install -g @yufengtadian/freedom-cli
+```
+
+安装完成后会自动弹出使用教程；之后随时可用 `freedom tutorial` 重新查看。
+
+## 快速开始
+
+```bash
+# 1. 新建项目
+freedom init my-app
+cd my-app
+npm install
+
+# 2. 调整标题栏（可选，随时可改）
+freedom titlebar native      # 保留系统原生标题栏（默认）
+freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
+freedom titlebar frameless   # 完全无边框，按钮由前端自绘（模板已内置示例）
+
+# 3. 打包
+freedom build
+```
+
+构建产物默认输出到 `dist/`，Windows 下为 `dist/<应用名>.exe`。产物为 GUI 子系统程序，运行时不会弹出 cmd 黑窗。
+
+产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
+
+```bash
+freedom config set outDir .     # 产物直接输出到项目根目录
+freedom config set outDir dist  # 恢复默认 dist/
+```
+
+## 标题栏策略
+
+| 模式 | 说明 |
+| --- | --- |
+| `native` | 保留系统原生标题栏（默认） |
+| `hidden` | 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮（DWM 扩展实现） |
+| `frameless` | 完全无边框，客户区铺满窗口，最小化 / 最大化 / 关闭按钮由前端自绘 |
+
+`hidden` / `frameless` 模式下，前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例。
+
+## 配置（freedom.config.js）
+
+```js
+export default {
+  name: 'my-app',       // 应用名 / 窗口标题 / exe 文件名
+  width: 1024,
+  height: 720,
+  minWidth: 400,
+  minHeight: 300,
+  center: true,          // 启动居中
+  debug: false,          // 开发者工具
+  titlebar: 'native',    // native | hidden | frameless
+  outDir: 'dist',        // 产物目录：'dist'（默认）| '.'（项目根目录）| 任意路径
+  // backend: { command: 'node', args: ['backend/main.mjs'] },  // 任意语言后端进程
+};
+```
+
+## 前端
+
+前端是标准 Vite 项目，`vite build` 时通过 `vite-plugin-singlefile` 内联为单个 HTML。壳层注入全局对象 `window.freedom`：
+
+```js
+const r = await window.freedom.call('__freedom__ping'); // 调用后端方法
+window.freedom.on('event', (data) => {});               // 订阅后端事件
+window.freedom.window.minimize();                       // 窗口控制
+```
+
+## 构建要求
+
+- Node.js >= 18
+- Go 工具链（编译壳层，需支持 CGO；Windows 下需要 MSVC 编译环境与 WebView2 运行时，Win10/11 自带）
+
+## 命令
+
+```
+freedom init <目录> [--force]
+freedom build
+freedom titlebar <native|hidden|frameless>
+freedom config [get|set]
+freedom tutorial
+freedom help
+```
+
+## 关于生成产物
+
+本工具生成的所有文件（含模板与构建产物）均干净整洁，无任何冗余尾注，可直接作为交付物使用。
+
+## License
+
+MIT

package/bin/freedom.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../lib/cli');
+
+run(process.argv.slice(2)).then((code) => {
+  process.exit(code || 0);
+}).catch((err) => {
+  console.error('[freedom] 执行失败：', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/lib/build.js

@@ -0,0 +1,173 @@
+'use strict';
+
+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',
+};
+
+function run(cmd, args, opts = {}) {
+  // Windows 下 npm 是 .cmd 批处理，必须经 shell 执行
+  const isNpmWin = process.platform === 'win32' && cmd === 'npm';
+  const realCmd = isNpmWin ? 'npm.cmd' : cmd;
+  const res = spawnSync(realCmd, args, {
+    stdio: opts.stdio === 'inherit' ? 'inherit' : 'pipe',
+    encoding: 'utf8',
+    env: process.env,
+    shell: isNpmWin,
+    ...opts,
+  });
+  if (res.error) {
+    throw new Error(`执行 ${cmd} 失败：${res.error.message}`);
+  }
+  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();
+}
+
+async function build(projectDir, opts = {}) {
+  const dir = path.resolve(projectDir || '.');
+  const cfgPath = path.join(dir, 'freedom.config.js');
+  if (!fs.existsSync(cfgPath)) {
+    throw new Error(`未找到 ${cfgPath}，请先运行 freedom init 初始化项目。`);
+  }
+  const { loadConfig } = require('./utils');
+  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();
+
+  // 1) 前端打包：npm install（如缺依赖）+ vite build -> .freedom/vite-dist/index.html
+  ensureNodeModules(dir);
+  const vite = run('npm', ['run', 'build'], { cwd: dir });
+  if (vite.status !== 0) {
+    throw new Error(`前端打包失败：\n${vite.stdout}\n${vite.stderr}`);
+  }
+  const distHtml = path.join(dir, '.freedom', 'vite-dist', 'index.html');
+  if (!fs.existsSync(distHtml)) {
+    throw new Error(`前端打包完成但未找到 ${distHtml}，请检查 vite 配置（vite-plugin-singlefile）。`);
+  }
+
+  // 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'));
+  const backendDir = path.join(dir, cfg.backendDir || 'backend');
+  if (cfg.backend && fs.existsSync(backendDir)) {
+    copyDir(backendDir, path.join(buildDir, 'backend'));
+  }
+
+  // 4) 生成 gen_config.go
+  const genConfig = renderGenConfig(cfg, name, titlebar);
+  fs.writeFileSync(path.join(buildDir, 'gen_config.go'), genConfig, 'utf8');
+
+  // 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}`);
+  }
+
+  // 6) 产物分发到 outDir：
+  //    - exe：已输出到 outDir；
+  //    - 单文件 index.html：outDir 非项目根目录时才写入（避免覆盖项目源文件）；
+  //    - backend：随应用一起分发。
+  if (path.resolve(outDirPath) !== dir) {
+    fs.copyFileSync(distHtml, path.join(outDirPath, 'index.html'));
+  }
+  if (cfg.backend && fs.existsSync(backendDir)) {
+    fs.mkdirSync(path.join(outDirPath, 'backend'), { recursive: true });
+    copyDir(backendDir, path.join(outDirPath, 'backend'));
+  }
+
+  return { outFile, buildDir };
+}
+
+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 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 intVal(v, dft) {
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n >= 0 ? n : dft;
+}
+
+function boolVal(v, dft) {
+  return typeof v === 'boolean' ? v : dft;
+}
+
+module.exports = { build };

package/lib/cli.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { init } = require('./init');
+const { build } = require('./build');
+const { setConfig, showConfig } = require('./config');
+const { packageRoot, tutorialFile } = require('./utils');
+
+const VERSION = require(path.join(packageRoot(), 'package.json')).version;
+
+function help() {
+  return `
+freedom - Freedom 桌面壳打包工具 v${VERSION}
+
+用法：
+  freedom init [目录] [--force]        在当前/指定目录新建项目模板
+  freedom build                        前端打包并编译出桌面应用（产物在 dist/）
+  freedom titlebar <native|hidden|frameless>
+                                       一键切换标题栏策略
+  freedom config                       查看当前配置
+  freedom config get <key>             读取单个配置项
+  freedom config set <key> <value>     修改单个配置项
+  freedom tutorial                     再次打开安装教程
+  freedom help                         显示本帮助
+  freedom version                      显示版本
+
+标题栏策略说明：
+  native    保留系统原生标题栏（默认）
+  hidden    隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
+  frameless 完全无边框，按钮由前端自绘（模板已内置示例）
+`.trim();
+}
+
+async function run(argv) {
+  const [cmd, ...rest] = argv;
+
+  switch (cmd) {
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(help());
+      return 0;
+
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log(VERSION);
+      return 0;
+
+    case 'init': {
+      const force = rest.includes('--force');
+      const dirArg = rest.filter((a) => a !== '--force')[0];
+      const dir = init(dirArg || '.', { force });
+      console.log(`[freedom] 项目已创建：${dir}`);
+      console.log('  下一步：');
+      console.log(`    cd ${dir}`);
+      console.log('    npm install');
+      console.log('    freedom build');
+      return 0;
+    }
+
+    case 'build': {
+      const { outFile } = await build(process.cwd());
+      if (outFile) {
+        console.log(`[freedom] 构建完成：${outFile}`);
+      }
+      return 0;
+    }
+
+    case 'titlebar': {
+      const mode = rest[0];
+      if (!['native', 'hidden', 'frameless'].includes(mode)) {
+        console.error('[freedom] 用法：freedom titlebar <native|hidden|frameless>');
+        return 1;
+      }
+      setConfig(process.cwd(), 'titlebar', mode);
+      console.log(`[freedom] titlebar 已切换为：${mode}`);
+      console.log('  运行 freedom build 重新打包生效。');
+      return 0;
+    }
+
+    case 'config': {
+      const sub = rest[0];
+      if (sub === 'get') {
+        const cfg = await showConfig(process.cwd());
+        console.log(cfg);
+        return 0;
+      }
+      if (sub === 'set') {
+        const key = rest[1];
+        const value = rest[2];
+        if (!key || value === undefined) {
+          console.error('[freedom] 用法：freedom config set <key> <value>');
+          return 1;
+        }
+        setConfig(process.cwd(), key, coerce(value));
+        console.log(`[freedom] ${key} = ${coerce(value)}`);
+        return 0;
+      }
+      console.log(await showConfig(process.cwd()));
+      return 0;
+    }
+
+    case 'tutorial': {
+      const file = tutorialFile();
+      openBrowser(file);
+      console.log(`[freedom] 教程已打开：${file}`);
+      return 0;
+    }
+
+    default:
+      console.error(`[freedom] 未知命令：${cmd}\n`);
+      console.log(help());
+      return 1;
+  }
+}
+
+function coerce(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  const num = Number(value);
+  if (value !== '' && Number.isFinite(num) && String(num) === value.trim()) {
+    return num;
+  }
+  return value;
+}
+
+function openBrowser(file) {
+  const { spawn } = require('child_process');
+  const plat = process.platform;
+  const url = `file://${file.replace(/\\/g, '/')}`;
+  try {
+    if (plat === 'win32') {
+      spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    } else if (plat === 'darwin') {
+      spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    } else {
+      spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+    }
+  } catch (e) { /* 打开失败静默 */ }
+}
+
+module.exports = { run };

package/lib/config.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig, hasConfig } = require('./utils');
+
+// 配置文件中可安全写入的字段及其默认值（用于渲染或回填）。
+const KNOWN_KEYS = {
+  name: 'freedom-app',
+  width: 1024,
+  height: 720,
+  minWidth: 400,
+  minHeight: 300,
+  center: true,
+  debug: false,
+  titlebar: 'native',
+  outDir: 'dist',
+};
+
+// 把配置写回 freedom.config.js（保留注释，只替换已知键的取值）。
+function setConfig(dir, key, value) {
+  const cfgPath = path.join(dir, 'freedom.config.js');
+  if (!fs.existsSync(cfgPath)) {
+    throw new Error('未找到 freedom.config.js。');
+  }
+  const text = fs.readFileSync(cfgPath, 'utf8');
+
+  if (key === 'titlebar') {
+    const modes = ['native', 'hidden', 'frameless'];
+    if (!modes.includes(value)) {
+      throw new Error(`titlebar 取值必须为：${modes.join(' / ')}。`);
+    }
+  }
+
+  const regex = new RegExp(`(${key}\\s*:\\s*)('[^']*'|\\d+|true|false|undefined|null)`, 'g');
+  if (!regex.test(text)) {
+    throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到，请手动添加。`);
+  }
+
+  let rendered = String(value);
+  if (typeof value === 'string') {
+    rendered = `'${value.replace(/'/g, "\\'")}'`;
+  }
+
+  const updated = text.replace(regex, `$1${rendered}`);
+  fs.writeFileSync(cfgPath, updated, 'utf8');
+  return value;
+}
+
+async function getConfig(dir) {
+  if (!hasConfig(dir)) {
+    throw new Error('当前目录不是 Freedom 项目（缺少 freedom.config.js）。');
+  }
+  const cfg = await loadConfig(dir);
+  return cfg;
+}
+
+async function showConfig(dir) {
+  const cfg = await loadConfig(dir);
+  const lines = Object.keys(KNOWN_KEYS).map((k) => {
+    const v = cfg[k] === undefined ? KNOWN_KEYS[k] : cfg[k];
+    return `  ${k}: ${JSON.stringify(v)}`;
+  });
+  lines.push(`  backend: ${cfg.backend ? JSON.stringify(cfg.backend) : 'undefined'}`);
+  return lines.join('\n');
+}
+
+module.exports = { setConfig, getConfig, showConfig, KNOWN_KEYS };

package/lib/init.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { projectTemplateDir, copyDir } = require('./utils');
+
+function init(targetDir, opts = {}) {
+  const dir = targetDir || '.';
+  const abs = path.resolve(dir);
+
+  if (fs.existsSync(abs) && fs.readdirSync(abs).length > 0 && !opts.force) {
+    throw new Error(`目标目录 ${abs} 非空，请使用空目录，或加 --force 覆盖。`);
+  }
+
+  fs.mkdirSync(abs, { recursive: true });
+  copyDir(projectTemplateDir(), abs);
+
+  // 项目名替换到 package.json 与 freedom.config.js
+  const name = opts.name || path.basename(abs);
+  patchName(abs, name);
+
+  return abs;
+}
+
+function patchName(dir, name) {
+  const safeName = String(name).replace(/[^a-zA-Z0-9_.-]/g, '-').toLowerCase();
+
+  const pkgPath = path.join(dir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.name = safeName || 'freedom-app';
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  }
+
+  const cfgPath = path.join(dir, 'freedom.config.js');
+  if (fs.existsSync(cfgPath)) {
+    let text = fs.readFileSync(cfgPath, 'utf8');
+    text = text.replace(/name:\s*'[^']*'/, `name: '${safeName || 'freedom-app'}'`);
+    fs.writeFileSync(cfgPath, text, 'utf8');
+  }
+}
+
+module.exports = { init };

package/lib/utils.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function packageRoot() {
+  return PKG_ROOT;
+}
+
+function templateDir() {
+  return path.join(PKG_ROOT, 'templates');
+}
+
+function projectTemplateDir() {
+  return path.join(templateDir(), 'project');
+}
+
+function goTemplateDir() {
+  return path.join(templateDir(), 'go');
+}
+
+function tutorialFile() {
+  return path.join(PKG_ROOT, 'tutorial', 'tutorial.html');
+}
+
+async function loadConfig(dir) {
+  const cfgPath = path.join(dir, 'freedom.config.js');
+  if (!fs.existsSync(cfgPath)) {
+    throw new Error('未找到 freedom.config.js，请先在项目根目录运行 freedom init 或创建该文件。');
+  }
+  // 动态 import 以兼容 ESM / CJS 两种书写方式，带时间戳防缓存
+  const url = require('url').pathToFileURL(cfgPath).href + '?t=' + Date.now();
+  const mod = await import(url);
+  return mod.default || mod;
+}
+
+function hasConfig(dir) {
+  return fs.existsSync(path.join(dir, 'freedom.config.js'));
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function goJSONString(v) {
+  return JSON.stringify(String(v));
+}
+
+module.exports = {
+  packageRoot,
+  templateDir,
+  projectTemplateDir,
+  goTemplateDir,
+  tutorialFile,
+  loadConfig,
+  hasConfig,
+  copyDir,
+  goJSONString,
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "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"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "freedom": "bin/freedom.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "tutorial",
+    "postinstall.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/postinstall.js

@@ -0,0 +1,36 @@
+// 安装后脚本：首次安装自动弹出 Freedom CLI 使用教程。
+// 环境变量 FREEDOM_NO_TUTORIAL=1 可跳过（CI 或脚本化安装场景）。
+'use strict';
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+if (process.env.FREEDOM_NO_TUTORIAL === '1') {
+  process.exit(0);
+}
+
+const file = path.join(__dirname, 'tutorial', 'tutorial.html');
+const url = 'file://' + file.replace(/\\/g, '/');
+const plat = process.platform;
+
+function tryOpen(cmd, args) {
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+  } catch (e) { /* 打开失败静默 */ }
+}
+
+if (plat === 'win32') {
+  tryOpen('cmd', ['/c', 'start', '', url]);
+} else if (plat === 'darwin') {
+  tryOpen('open', [url]);
+} else {
+  tryOpen('xdg-open', [url]);
+}
+
+console.log('');
+console.log('Freedom CLI 已安装。教程窗口已打开，也可以随时运行 freedom tutorial 重新查看。');
+console.log('快速开始：');
+console.log('  freedom init my-app && cd my-app && npm install && freedom build');
+console.log('');