@yufengtadian/freedom-cli 1.12.1 → 1.12.13

package/README.md

@@ -1,10 +1,27 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.1）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.13）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
-**v1.12.0 核心升级**：标题栏默认改为完全无边框（`frameless`）——标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘融入 UI（模板已内置自绘标题栏示例），不再依赖 Windows 原生按钮。`freedom titlebar` 仍可随时切回 `native` / `hidden`。
+**v1.12.13 CLI 界面升级与版本检测**：
+- CLI 交互界面升级为 Claude Code 风格：彩色分组帮助菜单、徽章化命令反馈（✓ / ✗ / ⚠ / ➜）、品牌横幅与版本信息卡；非 TTY（管道 / 重定向）或 `NO_COLOR` 下自动降级为纯文本，脚本调用与 CI 输出不受影响；
+- 新增版本检测：`freedom version` / `freedom update` 实时查询 npm registry 对比最新版本，发现新版本即给出 `npm install -g @yufengtadian/freedom-cli@latest` 升级命令；每次命令执行后静默检测一次（24 小时缓存，离线不打扰、不阻塞），有新版本自动提示升级；
+- TUI 主菜单新增「检查更新」入口，可随时在界面内查看当前版本与最新版本。
+
+**v1.12.12 三平台 frameless 彻底修复**：macOS / Linux 无边框窗口不再残留原生标题栏——
+- 壳层向 webview_go 新增 `set_decorated` / `window_control` 原生窗口控制 API（GTK 走 `gtk_window_set_decorated` / `gtk_window_*`，Cocoa 走隐藏标题栏 + `performMiniaturize:` / `zoom:` / `performClose:` / `isZoomed`），mac/linux 的 frameless 从"空实现回退原生标题栏"修复为真无边框，UI 上方不再残留未清理的原生标题栏；
+- 自绘三按钮（最小化 / 最大化 / 关闭）在 macOS / Linux 上接入原生窗口控制，双击最大化 / 还原、`isMaximized` 状态查询真实可用（此前 mac/linux 窗口控制为静默空转、`isMaximized` 恒 false）；
+- 最大化语义统一为"铺满工作区"的正常窗口最大化：Windows 经 `WM_GETMINMAXINFO` 限定到监视器工作区（rcWork），macOS 走 `zoom:`、Linux 走 `gtk_window_maximize`，均非 F11 式整屏全屏；
+- 打包流程全程仍不依赖 Go 工具链（`freedom build` 直接复制预编译壳，详见 v1.1.11 说明）。
+
+**v1.12.11 标题栏优化**：自绘标题栏（frameless）增强——
+- 标题栏左侧显示应用图标，图标直接从 exe 内嵌图标（PE 资源 ID=1）提取为 PNG data URL，**不再依赖 resources 资源文件夹**里的任何图标文件，跨平台无 resources 依赖；
+- 双击标题栏空白区最大化 / 还原；
+- 右键标题栏弹出系统菜单（还原 / 最小化 / 最大化 / 关闭），并按窗口状态自动置灰；
+- 标题栏拖动改由 `window.freedom.window.startDrag()` 原生发起，保留双击与右键事件（`-webkit-app-region: drag` 会吞掉页面事件）。
+
+**v1.12.0 核心升级**：标题栏默认改为完全无边框（`frameless`）——标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘融入 UI（模板已内置自绘标题栏示例），不再依赖 Windows 原生按钮。`freedom titlebar` 仍可随时切回 `native`。
 
 **v1.12.x 修复与加固**：
 - 修复 close 按钮缺陷：窗口关闭改走 `PostMessage(WM_CLOSE)`（原 `CloseWindow` 语义为最小化，导致点关闭只最小化）；
@@ -13,7 +30,7 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 - 壳进程启用 DPI 感知，高 DPI 屏幕下窗口坐标 / 渲染 / 鼠标自动化定位一致，内容更清晰；
 - `freedom config set` 兼容双引号配置写法；依赖变更检测改用 `package-lock.json` 作基准。
 
-**v1.11.0 核心升级**：支持自定义应用图标 + 默认隐藏 Windows 原生标题栏。配置 `freedom.config.js` 的 `icon`（Windows 用 `.ico`，macOS 用 `.icns`），`freedom build` 时自动把图标注入到 exe 的 PE 资源（RT_ICON / RT_GROUP_ICON）或 `.app/Contents/Resources`，无需任何资源编译器；`freedom icon <path>` 可一键设置。标题栏默认值由 `native` 调整为 `hidden`——保留 Windows 原生最小化 / 最大化 / 关闭按钮，隐藏标题栏视觉（DWM 扩展实现），默认不再占用窗口顶部空间。
+**v1.11.0 核心升级**：支持自定义应用图标 + 无边框标题栏。配置 `freedom.config.js` 的 `icon`（Windows 用 `.ico`，macOS 用 `.icns`），`freedom build` 时自动把图标注入到 exe 的 PE 资源（RT_ICON / RT_GROUP_ICON）或 `.app/Contents/Resources`，无需任何资源编译器；`freedom icon <path>` 可一键设置。标题栏默认使用无边框（`frameless`），窗口控制按钮由前端自绘，不再占用窗口顶部空间。
 
 **v1.10.12 核心升级**：macOS 产物升级为标准 .app 应用包，直接产出 `.app.zip`（mac 用户解压即得 `.app`，拖入 /Applications 即可使用）；在 macOS 上执行 `freedom dmg` 可再用系统 hdiutil 生成 `.dmg`。全程仍不依赖 Go 工具链。
 
@@ -21,7 +38,7 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 
 **v1.11.0 新特性**：
 - 自定义应用图标：`icon` 配置 + `freedom icon <path>` 命令，Windows 构建时用 rcedit 注入 `.ico` 到 exe 资源（支持多尺寸，资源管理器 / 任务栏 / 快捷方式统一显示），macOS 构建时把 `.icns` 放入 `.app` 并写入 Info.plist；
-- 标题栏默认改为 `hidden`：默认隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮；仍可用 `freedom titlebar` 随时切回 `native` / `frameless`。
+- 标题栏默认无边框（`frameless`）：标题栏与 Windows 原生最小化 / 最大化 / 关闭按钮均不存在，由前端自绘；仍可用 `freedom titlebar` 随时切回 `native`。
 
 **v1.10.12 新特性**：
 - macOS 产物打包为标准 `.app` bundle + `.app.zip`：壳复制进 `Contents/MacOS/`，resources 与前端/后端随包，解压即用，无需任何语言运行时；
@@ -54,7 +71,6 @@ freedom tui
 
 # 3. 调整标题栏（可选，随时可改；默认 frameless：标题栏不存在，关闭/最大化/最小化按钮由前端自绘融入 UI）
 freedom titlebar native      # 保留系统原生标题栏
-freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
 freedom titlebar frameless   # 完全无边框，标题栏不存在，三按钮由前端自绘（默认，模板已内置示例）
 
 # 3.5 设置应用图标（可选；Windows 用 .ico，macOS 用 .icns）
@@ -64,7 +80,7 @@ freedom icon icon.ico
 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 darwin-arm64   # 仅 macOS Apple Silicon
 freedom build --platform linux-x64   # 仅 Linux
 freedom build --no-cache             # 忽略前端构建缓存，强制重建
 ```
@@ -91,7 +107,7 @@ mac 用户解压 `.app.zip` 即得 `.app`，拖入 `/Applications` 即可直接
 
 **壳二进制平台校验**：`freedom build` 在分发前会读取壳二进制文件头，校验其确为目标平台的真实格式（Windows PE / macOS Mach-O / Linux ELF）。若某平台壳缺失或格式不匹配（例如误用其它平台的二进制顶替），会**明确报错并给出修复指引**，绝不静默产出无法运行的假产物。
 
-**预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。仓库已提供 `.github/workflows/build-shell.yml`：在 win / mac（Intel / Apple Silicon）/ linux runner 上分别编译真实壳并上传到 GitHub Release，供 `freedom shell download` 拉取。发布新版本时：先 `npm publish`，再创建同名 GitHub Release，手动触发 `build-shell` workflow（或直接发 Release 自动触发）即自动补齐各平台壳资产。
+**预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。仓库已提供 `.github/workflows/build-shell.yml`：在 win / mac（Apple Silicon）/ linux runner 上分别编译真实壳并上传到 GitHub Release，供 `freedom shell download` 拉取（Intel Mac 已不支持，见 `nativePlatform()` 的明确报错）。发布新版本时：先 `npm publish`，再创建同名 GitHub Release，手动触发 `build-shell` workflow（或直接发 Release 自动触发）即自动补齐各平台壳资产。
 
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
@@ -104,11 +120,10 @@ freedom config set outDir dist  # 恢复默认 dist/
 
 | 模式 | 说明 |
 | --- | --- |
-| `native` | 保留系统原生标题栏 |
-| `hidden` | 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮（DWM 扩展实现） |
-| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例） |
+| `native` | 保留系统原生标题栏，标题栏图标与 exe 图标一致 |
+| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例）。当前仅 Windows 完整实现；macOS / Linux 由系统窗口管理器托管，回退为原生标题栏且窗口控制动作返回明确错误 |
 
-`hidden` / `frameless` 模式下，前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例。
+`frameless` 模式下（Windows），前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例；macOS / Linux 上这些动作会 reject，前端应捕获并提示。
 
 ## 配置（freedom.config.js）
 
@@ -121,7 +136,7 @@ export default {
   minHeight: 300,
   center: true,          // 启动居中
   debug: false,          // 开发者工具
-  titlebar: 'frameless', // frameless（默认，标题栏不存在，三按钮由前端自绘）| native | hidden
+  titlebar: 'frameless', // frameless（默认，标题栏不存在，三按钮由前端自绘）| native
   icon: undefined,       // 应用图标：Windows 用 .ico（推荐多尺寸），macOS 用 .icns
   outDir: 'dist',        // 产物目录：'dist'（默认）| '.'（项目根目录）| 任意路径
   // backend: { command: 'node', args: ['backend/main.mjs'] },  // 任意语言后端进程
@@ -155,12 +170,14 @@ window.freedom.window.minimize();                       // 窗口控制
 ```
 freedom tui                          # 交互式终端界面
 freedom init <目录> [--force]
-freedom build [--platform win-x64|mac-arm64|linux-x64|all] [--no-cache]
-freedom titlebar <native|hidden|frameless>
+freedom build [--platform win-x64|darwin-arm64|linux-x64|all] [--no-cache]
+freedom titlebar <native|frameless>
 freedom icon <path>                    # 设置应用图标（Windows 用 .ico，macOS 用 .icns）
 freedom config [get|set]
 freedom shell list|download <platform>|build <platform>
 freedom dmg [--platform <plat>]      # 在 macOS 上把 .app 打包为 .dmg
+freedom version                     # 显示版本并检测最新版本
+freedom update                      # 检查新版本并给出升级命令（同 check-update）
 freedom tutorial
 freedom help
 ```

package/bin/freedom.js

@@ -2,8 +2,12 @@
 'use strict';
 
 const { run } = require('../lib/cli');
+const { maybeNotifyUpdate } = require('../lib/update');
 
-run(process.argv.slice(2)).then((code) => {
+run(process.argv.slice(2)).then(async (code) => {
+  if (code === 0 && process.argv[2] !== 'tui') {
+    try { await maybeNotifyUpdate(); } catch (e) { /* 检测失败静默 */ }
+  }
   process.exit(code || 0);
 }).catch((err) => {
   console.error('[freedom] 执行失败：', err && err.message ? err.message : err);

package/lib/build.js

@@ -27,6 +27,7 @@ const { spawnSync } = require('child_process');
 const { copyDir } = require('./utils');
 const {
   ALL_PLATFORMS,
+  DIST_PLATFORMS,
   isWinPlat,
   isMacPlat,
   platformExeName,
@@ -52,17 +53,34 @@ function run(cmd, args, opts = {}) {
   return res;
 }
 
-// --platform 解析：win|mac|linux|all 或平台 key（win-x64 等）
+// --platform 解析：支持逗号 / 中英文逗号 / 空白分隔多平台；win|mac|linux|all 或平台 key（win-x64 等）。
+// 多平台去重保留顺序。all 仅取可分发平台（DIST_PLATFORMS）：linux-arm64 无 CI 资产，
+// 若列入 all 会在 build 时 404 拖垮整个全量构建（历史 bug B41）。
 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-arm64', 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(' / ')}`
-  );
+  const seen = [];
+  const push = (p) => {
+    if (!ALL_PLATFORMS.includes(p)) {
+      throw new Error(
+        `未知平台：${p}。可选：win / mac / linux / all，或 ${ALL_PLATFORMS.join(' / ')}`
+      );
+    }
+    if (!seen.includes(p)) seen.push(p);
+  };
+  for (const seg of String(raw).split(/[,，\s]+/)) {
+    const v = String(seg).toLowerCase();
+    if (!v) continue;
+    if (v === 'all') {
+      for (const p of DIST_PLATFORMS) push(p);
+    } else {
+      push(keyMap[v] || v);
+    }
+  }
+  if (seen.length === 0) {
+    throw new Error(`未知平台：${raw}。可选：win / mac / linux / all，或 ${ALL_PLATFORMS.join(' / ')}`);
+  }
+  return seen;
 }
 
 async function build(projectDir, opts = {}) {
@@ -98,6 +116,7 @@ async function build(projectDir, opts = {}) {
     throw new Error(`前端打包完成但未找到 ${distHtml}，请检查 vite 配置（vite-plugin-singlefile）。`);
   }
   const html = fs.readFileSync(distHtml, 'utf8');
+  warnIfNotSingleFile(html, distHtml);
   const configJSON = renderConfigJSON(cfg, name);
 
   // 2) 后端目录（若配置了 backend 进程）
@@ -421,4 +440,26 @@ function intVal(v, dft) {
   return Number.isFinite(n) && n >= 0 ? n : dft;
 }
 
+// 非 singlefile 产物检测（历史 bug B47）：壳只 SetHtml 单页内存加载，HTML 里引用
+// 的外部 <script src> / <link href>（相对路径或 / 根路径）在无服务器环境下必然失效，
+// 导致页面 JS/CSS 丢失静默空白。检测到此类引用时明确告警，避免用户无感知翻车。
+function warnIfNotSingleFile(html, distHtml) {
+  const refs = [];
+  const re = /<(?:script|link)\b[^>]*(?:src|href)\s*=\s*["']([^"']+)["']/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    const url = m[1];
+    // data: / blob: / http(s): / file: 可正常工作，跳过；其余（相对、/ 根路径、// 协议相对）均会失效
+    if (/^(?:data:|blob:|https?:|file:)/i.test(url)) continue;
+    refs.push(url);
+  }
+  if (refs.length > 0) {
+    console.warn(
+      `[freedom] 警告：${path.basename(distHtml)} 引用了外部资源（${refs.join(', ')}）。` +
+        `壳在内存加载单页时这些引用会失效，导致页面空白。` +
+        `请在 vite.config.js 启用 vite-plugin-singlefile 将 JS/CSS 内联进 HTML。`
+    );
+  }
+}
+
 module.exports = { build, parsePlatforms };

package/lib/cli.js

@@ -6,50 +6,57 @@ const { init } = require('./init');
 const { build } = require('./build');
 const { setConfig, showConfig } = require('./config');
 const { packageRoot, tutorialFile } = require('./utils');
+const theme = require('./theme');
+const update = require('./update');
 
 const VERSION = require(path.join(packageRoot(), 'package.json')).version;
+const { paint, ok, err, warn, info, tip, dim, bold, section, banner, versionCard, C } = theme;
 
 function help() {
-  return `
-freedom - Freedom 桌面壳打包工具 v${VERSION}
-
-用法：
-  freedom tui                           进入交互式 TUI 界面（新建/打包/配置/壳管理）
-  freedom init [目录] [--force]        在当前/指定目录新建项目模板
-  freedom build [--platform <p>]       前端打包并分发桌面应用（默认当前平台）
-      --platform win|mac|linux|all     指定目标平台（all = 三平台全量）
-      --no-cache                       忽略前端构建缓存，强制重新打包
-  freedom titlebar <native|hidden|frameless>
-                                       一键切换标题栏策略
-  freedom icon <path>                  设置应用图标（Windows 需 .ico，macOS 需 .icns）
-  freedom shell list                   列出本地已就绪的预编译壳
-  freedom shell download <plat>        从 GitHub Releases 下载预编译壳（无需 Go）
-  freedom shell build <plat>           本地用 Go 编译壳（可选，壳已预编译一般无需）
-  freedom dmg [--platform <plat>]      将已构建的 .app 打包为 .dmg（需在 macOS 上执行）
-  freedom config                       查看当前配置
-  freedom config get <key>             读取单个配置项
-  freedom config set <key> <value>     修改单个配置项
-  freedom tutorial                     再次打开安装教程
-  freedom help                         显示本帮助
-  freedom version                      显示版本
-
-平台（<p>/<plat>）：win-x64 / darwin-arm64 / linux-x64 / linux-arm64，
-快捷别名：win / mac / linux / all。
-
-macOS 产物说明：
-  freedom build --platform mac 直接产出 <app>.app.zip（解压即得 .app，
-  拖入 /Applications 即可使用，无需安装任何语言运行时）；如需 .dmg，
-  在 macOS 上执行 freedom dmg 用系统 hdiutil 生成。
-
-标题栏策略说明：
-  native    保留系统原生标题栏
-  hidden    隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
-  frameless 完全无边框，标题栏不存在，关闭/最大化/最小化按钮由前端自绘（默认，模板已内置示例）
-
-图标说明：
-  Windows exe 图标：在 freedom.config.js 配置 icon（.ico 路径），构建时自动注入；
-  macOS .app 图标：icon 配置 .icns 路径即可；未配置则使用壳默认图标。
-`.trim();
+  const L = [];
+  L.push(banner(VERSION));
+  L.push('');
+  L.push(`  ${paint('用法：', C.bold, C.fg.white)} ${paint('freedom <command> [options]', C.fg.cyan, C.bold)}`);
+  L.push('');
+  L.push(section('交互式界面'));
+  L.push(`  ${paint('freedom tui', C.fg.cyan, C.bold)}              ${dim('进入交互式 TUI（新建 / 打包 / 配置 / 壳管理）')}`);
+  L.push(section('项目'));
+  L.push(`  ${paint('freedom init [目录] [--force]', C.fg.cyan)}    ${dim('在当前 / 指定目录新建项目模板')}`);
+  L.push(`  ${paint('freedom tutorial', C.fg.cyan)}                 ${dim('再次打开安装教程')}`);
+  L.push(section('打包'));
+  L.push(`  ${paint('freedom build [--platform <p>]', C.fg.cyan)}   ${dim('前端打包并分发桌面应用（默认当前平台）')}`);
+  L.push(`      ${dim('--platform win|mac|linux|all')}    ${dim('指定目标平台（all = 三平台全量）')}`);
+  L.push(`      ${dim('--no-cache')}                      ${dim('忽略前端构建缓存，强制重新打包')}`);
+  L.push(`  ${paint('freedom dmg [--platform <plat>]', C.fg.cyan)}  ${dim('将已构建的 .app 打包为 .dmg（需 macOS）')}`);
+  L.push(section('外观'));
+  L.push(`  ${paint('freedom titlebar <native|frameless>', C.fg.cyan)} ${dim('一键切换标题栏策略')}`);
+  L.push(`  ${paint('freedom icon <path>', C.fg.cyan)}     ${dim('设置应用图标（Win .ico / mac .icns）')}`);
+  L.push(section('壳管理'));
+  L.push(`  ${paint('freedom shell list', C.fg.cyan)}      ${dim('列出本地已就绪的预编译壳')}`);
+  L.push(`  ${paint('freedom shell download <plat>', C.fg.cyan)} ${dim('从 GitHub Releases 下载预编译壳')}`);
+  L.push(`  ${paint('freedom shell build <plat>', C.fg.cyan)}   ${dim('本地用 Go 编译壳（可选，一般无需）')}`);
+  L.push(section('配置'));
+  L.push(`  ${paint('freedom config', C.fg.cyan)}              ${dim('查看当前配置')}`);
+  L.push(`  ${paint('freedom config get <key>', C.fg.cyan)}    ${dim('读取单个配置项')}`);
+  L.push(`  ${paint('freedom config set <key> <value>', C.fg.cyan)} ${dim('修改单个配置项')}`);
+  L.push(section('版本'));
+  L.push(`  ${paint('freedom version', C.fg.cyan)}             ${dim('显示版本并检测最新版本')}`);
+  L.push(`  ${paint('freedom update', C.fg.cyan)}              ${dim('检查新版本并给出升级命令')}`);
+  L.push(`  ${paint('freedom help', C.fg.cyan)}                ${dim('显示本帮助')}`);
+  L.push('');
+  L.push(section('平台'));
+  L.push(`  ${dim('<p> / <plat>：win-x64 / darwin-arm64 / linux-x64 / linux-arm64，快捷别名：win / mac / linux / all。')}`);
+  L.push(section('macOS 产物'));
+  L.push(`  ${dim('freedom build --platform mac 直接产出 <app>.app.zip（解压即得 .app，拖入 /Applications 即可，无需语言运行时）；')}`);
+  L.push(`  ${dim('如需 .dmg，在 macOS 上执行 freedom dmg 用系统 hdiutil 生成。')}`);
+  L.push(section('标题栏策略'));
+  L.push(`  ${paint('native', C.fg.white)}    ${dim('保留系统原生标题栏，标题栏图标与 exe 图标一致')}`);
+  L.push(`  ${paint('frameless', C.fg.white)} ${dim('完全无边框，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例）')}`);
+  L.push(section('图标'));
+  L.push(`  ${dim('Windows exe 图标：freedom.config.js 配置 icon（.ico 路径），构建时自动注入；')}`);
+  L.push(`  ${dim('macOS .app 图标：icon 配置 .icns 路径即可；未配置则使用壳默认图标。')}`);
+  L.push('');
+  return L.join('\n');
 }
 
 async function run(argv) {
@@ -65,9 +72,31 @@ async function run(argv) {
 
     case 'version':
     case '--version':
-    case '-v':
-      console.log(VERSION);
+    case '-v': {
+      const r = await update.checkUpdate({ force: true });
+      console.log(versionCard(r.current, r.latest, r.hasUpdate));
+      if (r.hasUpdate && r.latest) {
+        console.log(`  ${tip('升级命令：')}${paint(`npm install -g ${update.PKG_NAME}@latest`, C.fg.cyan, C.bold)}`);
+        console.log('');
+      }
+      return 0;
+    }
+
+    case 'update':
+    case 'check-update': {
+      const r = await update.checkUpdate({ force: true });
+      console.log(versionCard(r.current, r.latest, r.hasUpdate));
+      if (r.hasUpdate && r.latest) {
+        console.log(`  ${tip('检测到新版本，执行以下命令升级：')}`);
+        console.log(`    ${paint(`npm install -g ${update.PKG_NAME}@latest`, C.fg.cyan, C.bold)}`);
+        console.log('');
+      } else if (r.latest) {
+        console.log(`  ${ok('当前已是最新版本。')}`);
+      } else {
+        console.log(`  ${warn('检查失败：网络不可用或 npm registry 未响应，请稍后重试。')}`);
+      }
       return 0;
+    }
 
     case 'tui':
       return await require('./tui').tui(process.cwd());
@@ -76,11 +105,11 @@ async function run(argv) {
       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');
+      console.log(`${ok('项目已创建：')}${paint(dir, C.fg.cyan, C.bold)}`);
+      console.log(`  ${dim('下一步：')}`);
+      console.log(`    ${paint(`cd ${dir}`, C.fg.white)}`);
+      console.log(`    ${paint('npm install', C.fg.white)}`);
+      console.log(`    ${paint('freedom build', C.fg.white)}`);
       return 0;
     }
 
@@ -92,42 +121,40 @@ async function run(argv) {
       }
       const { results } = await build(process.cwd(), { platform, noCache: rest.includes('--no-cache') });
       for (const r of results) {
-        console.log(`[freedom] [${r.plat}] 构建完成：${r.outFile}`);
+        console.log(`${ok('构建完成')} ${paint(`[${r.plat}]`, C.fg.magenta, C.bold)} ${paint(r.outFile, C.fg.white)}`);
       }
       return 0;
     }
 
-    case 'shell': {
+    case 'shell':
       return await runShell(rest);
-    }
 
-    case 'dmg': {
+    case 'dmg':
       return await runDmg(rest);
-    }
 
     case 'titlebar': {
       const mode = rest[0];
-      if (!['native', 'hidden', 'frameless'].includes(mode)) {
-        console.error('[freedom] 用法：freedom titlebar <native|hidden|frameless>');
+      if (!['native', 'frameless'].includes(mode)) {
+        console.error(`${err('用法：')}${paint('freedom titlebar <native|frameless>', C.fg.cyan)}`);
         return 1;
       }
       setConfig(process.cwd(), 'titlebar', mode);
-      console.log(`[freedom] titlebar 已切换为：${mode}`);
-      console.log('  运行 freedom build 重新打包生效。');
+      console.log(`${ok('titlebar 已切换为：')}${paint(mode, C.fg.cyan, C.bold)}`);
+      console.log(`  ${dim('运行')} ${paint('freedom build', C.fg.cyan)} ${dim('重新打包生效。')}`);
       return 0;
     }
 
     case 'icon': {
       const iconPath = rest[0];
       if (!iconPath) {
-        console.error('[freedom] 用法：freedom icon <path>');
-        console.error('  示例：freedom icon icon.ico    （Windows exe 图标，.ico 格式）');
-        console.error('        freedom icon icon.icns   （macOS .app 图标，.icns 格式）');
+        console.error(`${err('用法：')}${paint('freedom icon <path>', C.fg.cyan)}`);
+        console.error(`  ${dim('示例：freedom icon icon.ico  （Windows exe 图标，.ico 格式）')}`);
+        console.error(`        ${dim('freedom icon icon.icns （macOS .app 图标，.icns 格式）')}`);
         return 1;
       }
       setConfig(process.cwd(), 'icon', iconPath);
-      console.log(`[freedom] icon 已设置为：${iconPath}`);
-      console.log('  运行 freedom build 重新打包生效。');
+      console.log(`${ok('icon 已设置为：')}${paint(iconPath, C.fg.cyan, C.bold)}`);
+      console.log(`  ${dim('运行')} ${paint('freedom build', C.fg.cyan)} ${dim('重新打包生效。')}`);
       return 0;
     }
 
@@ -142,11 +169,11 @@ async function run(argv) {
         const key = rest[1];
         const value = rest[2];
         if (!key || value === undefined) {
-          console.error('[freedom] 用法：freedom config set <key> <value>');
+          console.error(`${err('用法：')}${paint('freedom config set <key> <value>', C.fg.cyan)}`);
           return 1;
         }
         setConfig(process.cwd(), key, coerce(value));
-        console.log(`[freedom] ${key} = ${coerce(value)}`);
+        console.log(`${ok('已设置')} ${paint(key, C.fg.cyan, C.bold)} = ${paint(JSON.stringify(coerce(value)), C.fg.white)}`);
         return 0;
       }
       console.log(await showConfig(process.cwd()));
@@ -156,12 +183,12 @@ async function run(argv) {
     case 'tutorial': {
       const file = tutorialFile();
       openBrowser(file);
-      console.log(`[freedom] 教程已打开：${file}`);
+      console.log(`${ok('教程已打开：')}${paint(file, C.fg.cyan)}`);
       return 0;
     }
 
     default:
-      console.error(`[freedom] 未知命令：${cmd}\n`);
+      console.error(`${err('未知命令：')}${paint(cmd, C.fg.red, C.bold)}\n`);
       console.log(help());
       return 1;
   }
@@ -186,37 +213,37 @@ async function runShell(rest) {
     case 'list': {
       const ready = listLocal();
       if (ready.length === 0) {
-        console.log('[freedom] 本地暂无预编译壳。');
+        console.log(`${dim('本地暂无预编译壳。')}`);
       } else {
-        console.log('[freedom] 本地已就绪的壳平台：');
-        for (const p of ready) console.log(`  ${p}`);
+        console.log(`${ok('本地已就绪的壳平台：')}`);
+        for (const p of ready) console.log(`  ${paint('✓', C.fg.green)} ${paint(p, C.fg.cyan, C.bold)}`);
       }
-      console.log(`[freedom] 可选平台：${ALL_PLATFORMS.join(' / ')}`);
+      console.log(`${dim('可选平台：')}${paint(ALL_PLATFORMS.join(' / '), C.fg.gray)}`);
       return 0;
     }
     case 'download': {
       const plat = rest[1];
       if (!plat) {
-        console.error('[freedom] 用法：freedom shell download <win-x64|darwin-arm64|linux-x64|linux-arm64>');
+        console.error(`${err('用法：')}${paint('freedom shell download <win-x64|darwin-arm64|linux-x64|linux-arm64>', C.fg.cyan)}`);
         return 1;
       }
       const dest = await downloadShell(plat);
-      console.log(`[freedom] 已下载 ${plat} 壳：${dest}`);
+      console.log(`${ok('已下载')} ${paint(plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
       return 0;
     }
     case 'build': {
       const plat = rest[1];
       if (!plat) {
-        console.error('[freedom] 用法：freedom shell build <win-x64|darwin-arm64|linux-x64|linux-arm64>');
+        console.error(`${err('用法：')}${paint('freedom shell build <win-x64|darwin-arm64|linux-x64|linux-arm64>', C.fg.cyan)}`);
         return 1;
       }
       const dest = buildShell(plat);
-      console.log(`[freedom] 已编译 ${plat} 壳：${dest}`);
-      console.log('[freedom] 提示：壳已预编译随包分发，一般无需本地编译。');
+      console.log(`${ok('已编译')} ${paint(plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
+      console.log(`  ${dim('提示：壳已预编译随包分发，一般无需本地编译。')}`);
       return 0;
     }
     default:
-      console.error(`[freedom] 未知 shell 子命令：${sub}`);
+      console.error(`${err('未知 shell 子命令：')}${paint(sub, C.fg.red, C.bold)}`);
       return 1;
   }
 }
@@ -235,7 +262,7 @@ async function runDmg(rest) {
     ? (platArg.includes('=') ? platArg.split('=')[1] : rest[rest.indexOf(platArg) + 1])
     : nativePlatform();
   if (!plat || !plat.startsWith('darwin')) {
-    console.error('[freedom] dmg 仅支持 macOS 平台（darwin-arm64）。');
+    console.error(`${err('dmg 仅支持 macOS 平台（darwin-arm64）。')}`);
     return 1;
   }
 
@@ -244,18 +271,18 @@ async function runDmg(rest) {
   const candidates = [path.join(baseDir, `${name}.app`), path.join(baseDir, plat, `${name}.app`)];
   const appDir = candidates.find((p) => fs.existsSync(p));
   if (!appDir) {
-    console.error(`[freedom] 未找到 ${name}.app（已检查 ${candidates.join(' / ')}）。`);
-    console.error('  请先在 macOS 上运行 freedom build --platform mac 生成 .app。');
+    console.error(`${err('未找到')} ${paint(`${name}.app`, C.fg.cyan)} ${dim(`（已检查 ${candidates.join(' / ')}）。`)}`);
+    console.error(`  ${dim('请先在 macOS 上运行')} ${paint('freedom build --platform mac', C.fg.cyan)} ${dim('生成 .app。')}`);
     return 1;
   }
 
   const outPath = path.join(path.dirname(appDir), `${name}-${plat}.dmg`);
   try {
     const dmgPath = await makeDmg(appDir, outPath, name);
-    console.log(`[freedom] 已生成 dmg：${dmgPath}`);
+    console.log(`${ok('已生成 dmg：')}${paint(dmgPath, C.fg.white)}`);
     return 0;
   } catch (e) {
-    console.error(`[freedom] ${e.message}`);
+    console.error(`${err(e.message)}`);
     return 1;
   }
 }