@yufengtadian/freedom-cli 1.12.12 → 1.12.13

package/README.md

@@ -1,9 +1,14 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.0）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.13）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**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）；
@@ -171,6 +176,8 @@ freedom icon <path>                    # 设置应用图标（Windows 用 .ico
 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|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    保留系统原生标题栏，标题栏图标与 exe 图标一致
-  frameless 完全无边框，标题栏与 Windows 原生最小化/最大化/关闭按钮均不存在，
-            关闭/最大化/最小化按钮由前端自绘（默认，模板已内置示例）
-
-图标说明：
-  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', 'frameless'].includes(mode)) {
-        console.error('[freedom] 用法：freedom titlebar <native|frameless>');
+        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;
   }
 }

package/lib/config.js

@@ -134,13 +134,6 @@ const KNOWN_KEYS = {
   outDir: 'dist',
 };
 
-async function getConfig(dir) {
-  if (!hasConfig(dir)) {
-    throw new Error('当前目录不是 Freedom 项目（缺少 freedom.config.js）。');
-  }
-  return loadConfig(dir);
-}
-
 async function showConfig(dir) {
   const cfg = await loadConfig(dir);
   const lines = Object.keys(KNOWN_KEYS).map((k) => {

package/lib/shell.js

@@ -22,6 +22,7 @@ const {
   ALL_PLATFORMS,
   SHELL_EXE_NAME,
   localShellPath,
+  nativePlatform,
 } = require('./utils');
 
 // GitHub Releases 下载源（可用环境变量覆盖）。
@@ -49,27 +50,63 @@ function releaseUrl(plat) {
 }
 
 // ---- 壳二进制平台格式校验 ----
-// 读取二进制文件头判断真实平台格式，防止"用 Windows 壳冒充 mac/linux 壳"这类假壳
+// 读取二进制头识别真实平台（含架构），防止"用 Windows 壳冒充 mac/linux 壳"这类假壳
 // 被静默分发（历史缺陷：shell/<darwin-*>/<linux-*> 曾误填 Windows PE 副本）。
+// 返回精确平台 key（win-x64 / win-arm64 / mac-x64 / mac-arm64 / linux-x64 / linux-arm64）、
+// 仅格式族（win / mac / linux，老壳 / 未知架构）或 'unknown'。
 function detectShellFormat(buf) {
-  if (!buf || buf.length < 4) return 'unknown';
-  // Windows PE：MZ
-  if (buf[0] === 0x4d && buf[1] === 0x5a) return 'win';
-  // Mach-O 64 位：CF FA ED FE（32 位为 CE FA ED FE，本项目仅 64 位）
-  if (buf[0] === 0xcf && buf[1] === 0xfa && buf[2] === 0xed && buf[3] === 0xfe) return 'mac';
-  // ELF：7F 45 4C 46
-  if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46) return 'linux';
+  if (!buf || buf.length < 64) return 'unknown';
+  // Windows PE：MZ；e_lfanew @0x3C (4 LE) -> "PE\0\0"，machine @+4 (2 LE)
+  if (buf[0] === 0x4d && buf[1] === 0x5a) {
+    const peOff = buf.readUInt32LE(0x3c);
+    if (peOff + 6 <= buf.length && buf.readUInt32LE(peOff) === 0x00004550) {
+      const machine = buf.readUInt16LE(peOff + 4);
+      if (machine === 0x8664) return 'win-x64';
+      if (machine === 0xaa64) return 'win-arm64';
+    }
+    return 'win';
+  }
+  // Mach-O 64 位：CF FA ED FE（magic 0xfeedfacf 小端）；cputype @4 (4 LE)
+  if (buf[0] === 0xcf && buf[1] === 0xfa && buf[2] === 0xed && buf[3] === 0xfe) {
+    const cpu = buf.readUInt32LE(4);
+    if (cpu === 0x01000007) return 'mac-x64';
+    if (cpu === 0x0100000c) return 'mac-arm64';
+    return 'mac';
+  }
+  // ELF：7F 45 4C 46；e_machine @18 (2 LE)：62=x86_64，183=aarch64
+  if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46) {
+    const machine = buf.readUInt16LE(18);
+    if (machine === 62) return 'linux-x64';
+    if (machine === 183) return 'linux-arm64';
+    return 'linux';
+  }
   return 'unknown';
 }
 
-// 平台 key -> 期望的二进制格式族
+// 平台 key -> 期望的二进制平台 key（含架构）
 function expectedFormat(plat) {
-  if (plat.startsWith('win')) return 'win';
-  if (plat.startsWith('darwin')) return 'mac';
-  if (plat.startsWith('linux')) return 'linux';
+  if (plat.startsWith('win')) {
+    return plat === 'win-x64' || plat === 'win-arm64' ? plat : 'win';
+  }
+  if (plat.startsWith('darwin')) {
+    if (plat === 'darwin-x64') return 'mac-x64';
+    if (plat === 'darwin-arm64') return 'mac-arm64';
+    return 'mac';
+  }
+  if (plat.startsWith('linux')) {
+    return plat === 'linux-x64' || plat === 'linux-arm64' ? plat : 'linux';
+  }
   return 'unknown';
 }
 
+// 格式族（win / mac / linux）
+function formatFamily(s) {
+  if (s.startsWith('win')) return 'win';
+  if (s.startsWith('mac')) return 'mac';
+  if (s.startsWith('linux')) return 'linux';
+  return s;
+}
+
 // 校验本地壳二进制是否为目标平台的真实格式；不匹配返回错误说明，不抛错（供调用方决策）。
 function validateLocalShell(plat) {
   const p = localShellPath(plat);
@@ -87,12 +124,21 @@ function validateLocalShell(plat) {
   if (fmt === 'unknown') {
     return `壳二进制 ${p} 不是可识别的 PE/Mach-O/ELF 格式（detect=${fmt}）。`;
   }
-  if (fmt !== want) {
+  if (formatFamily(fmt) !== formatFamily(want)) {
     return `壳二进制 ${p} 格式与目标平台 ${plat} 不匹配：期望 ${want}，实际 ${fmt}。` +
       `这是假壳（历史缺陷曾把 Windows 壳复制到 mac/linux 平台）。` +
       `请运行 freedom shell build ${plat} 在 ${plat} 本机编译真实壳，` +
       `或 freedom shell download ${plat} 拉取 CI 预编译产物。`;
   }
+  if (fmt !== want) {
+    if (!fmt.includes('-')) {
+      // 老壳仅能识别格式族、无架构信息：降级通过并提示（历史二进制）
+      console.warn(`[freedom] 警告：壳二进制 ${p} 仅识别为 ${formatFamily(fmt)} 格式（架构未知，detect=${fmt}），按目标 ${plat} 使用。`);
+      return null;
+    }
+    return `壳二进制 ${p} 架构与目标平台 ${plat} 不匹配：期望 ${want}，实际 ${fmt}（如 linux-x64 与 linux-arm64 不能混用）。` +
+      `请运行 freedom shell download ${plat} 拉取正确的预编译壳。`;
+  }
   return null;
 }
 
@@ -145,6 +191,16 @@ async function downloadShell(plat) {
     );
   }
   const buf = Buffer.from(await res.arrayBuffer());
+  // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
+  const fmt = detectShellFormat(buf);
+  const want = expectedFormat(plat);
+  if (fmt === 'unknown' || formatFamily(fmt) !== formatFamily(want)) {
+    throw new Error(
+      `下载的壳格式异常：期望 ${want}（${plat}），实际 detect=${fmt}。` +
+        `下载地址 ${url} 可能返回了错误页或非本平台假壳，请检查 GitHub Release 资产 ` +
+        `${releaseRepo()} 的 ${releaseTag()}。已放弃本次写入。`
+    );
+  }
   fs.writeFileSync(dest, buf);
   if (process.platform !== 'win32') {
     fs.chmodSync(dest, 0o755);
@@ -166,7 +222,8 @@ function buildShell(plat) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
 
   // 本机只能编译本机平台（webview_go 依赖系统 WebView 框架，无法交叉编译）。
-  const native = nativePlatformKey();
+  // 统一走 utils.nativePlatform：Intel Mac 会明确抛"已不支持"，避免两套映射语义不一（B44）。
+  const native = nativePlatform();
   if (plat !== native) {
     throw new Error(
       `无法在本机（${native}）交叉编译 ${plat}：webview_go 依赖系统 WebView 框架。` +
@@ -188,12 +245,8 @@ function buildShell(plat) {
 }
 
 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}`;
+  // 已废弃：统一使用 utils.nativePlatform（B44），本函数保留仅作内部兜底，勿再调用。
+  return nativePlatform();
 }
 
 module.exports = {

package/lib/theme.js

@@ -0,0 +1,105 @@
+'use strict';
+
+// Claude Code 风格终端 UI 主题：零依赖 ANSI 渲染
+// 非 TTY（管道 / 重定向）或 NO_COLOR 环境变量时自动降级为纯文本，不影响脚本输出解析。
+
+const ESC = '\x1b';
+
+const C = {
+  reset: `${ESC}[0m`,
+  bold: `${ESC}[1m`,
+  dim: `${ESC}[2m`,
+  italic: `${ESC}[3m`,
+  underline: `${ESC}[4m`,
+  fg: {
+    black: `${ESC}[30m`,
+    red: `${ESC}[31m`,
+    green: `${ESC}[32m`,
+    yellow: `${ESC}[33m`,
+    blue: `${ESC}[34m`,
+    magenta: `${ESC}[35m`,
+    cyan: `${ESC}[36m`,
+    white: `${ESC}[37m`,
+    gray: `${ESC}[90m`,
+  },
+  bg: {
+    red: `${ESC}[41m`,
+    green: `${ESC}[42m`,
+    yellow: `${ESC}[43m`,
+    magenta: `${ESC}[45m`,
+    cyan: `${ESC}[46m`,
+    gray: `${ESC}[100m`,
+  },
+};
+
+const COLOR = Boolean(process.stdout.isTTY && process.env.NO_COLOR === undefined);
+
+function paint(text, ...codes) {
+  if (!COLOR) return text;
+  return codes.join('') + text + C.reset;
+}
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+// 符号徽章（Claude Code 风格）：✓ / ✗ / ⚠ / ℹ / ➜
+function ok(text) { return paint('✓ ', C.fg.green, C.bold) + text; }
+function err(text) { return paint('✗ ', C.fg.red, C.bold) + text; }
+function warn(text) { return paint('⚠ ', C.fg.yellow, C.bold) + text; }
+function info(text) { return paint('ℹ ', C.fg.cyan, C.bold) + text; }
+function tip(text) { return paint('➜ ', C.fg.magenta, C.bold) + text; }
+function dim(text) { return paint(text, C.fg.gray); }
+function bold(text, color) { return paint(text, C.bold, color ? C.fg[color] : ''); }
+
+// 行内标签：[freedom] 加粗
+function tag() { return paint('[freedom]', C.fg.blue, C.bold); }
+
+// 水平分隔线
+function rule(ch = '─', color = 'gray') {
+  const w = Math.max(8, (process.stdout.columns || 80) - 2);
+  return paint(ch.repeat(w), C.fg[color]);
+}
+
+// 帮助分组标题：── 分组名 ──
+function section(title) {
+  return `  ${paint('──', C.fg.gray)} ${paint(title, C.bold, C.fg.cyan)} ${paint('──', C.fg.gray)}`;
+}
+
+// 品牌横幅（ASCII 标识 + 版本徽章）
+function banner(version, extra) {
+  const lines = [
+    '',
+    `  ${paint('▚▚', C.fg.cyan, C.bold)} ${paint('F R E E D O M', C.bold, C.fg.white)}  ${paint(`v${version}`, C.fg.gray)}`,
+    `  ${paint('│', C.fg.cyan)}  Freedom 桌面壳打包工具 · Web 前端一键出三平台桌面应用`,
+  ];
+  if (extra) lines.push(`  ${paint('│', C.fg.cyan)}  ${extra}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// 版本信息卡
+function versionCard(current, latest, hasUpdate) {
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${paint('⚡', C.fg.magenta)} ${paint('freedom', C.bold)} ${paint(`v${current}`, C.fg.white, C.bold)}`);
+  lines.push(rule('─'));
+  if (hasUpdate && latest) {
+    lines.push(
+      `  ${paint('➜ 当前版本：', C.fg.gray)}${paint(current, C.fg.white, C.bold)}` +
+      `  ${paint('➜ 最新版本：', C.fg.gray)}${paint(latest, C.fg.green, C.bold)}  ${paint('（有新版本可升级）', C.fg.yellow)}`
+    );
+  } else if (latest) {
+    lines.push(`  ${paint('➜ 当前版本：', C.fg.gray)}${paint(current, C.fg.white, C.bold)}  ${paint('（已是最新版本）', C.fg.green)}`);
+  } else {
+    lines.push(`  ${paint('➜ 当前版本：', C.fg.gray)}${paint(current, C.fg.white, C.bold)}  ${paint('（离线，未检测到最新版本）', C.fg.gray)}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  C, COLOR, paint, stripAnsi,
+  ok, err, warn, info, tip, dim, bold, tag,
+  rule, section, banner, versionCard,
+};

package/lib/tui.js

@@ -296,6 +296,23 @@ async function tutorialFlow(tui) {
   await tui.message('教程', [{ text: C.fgGreen + `  已打开：${file}` + C.reset }]);
 }
 
+async function updateFlow(tui) {
+  const { checkUpdate, PKG_NAME } = require('./update');
+  const r = await checkUpdate({ force: true });
+  const lines = [
+    { text: C.fgWhite + C.bold + `  当前版本：v${r.current}` + C.reset },
+  ];
+  if (r.latest) {
+    lines.push({ text: C.fgCyan + `  最新版本：v${r.latest}` + C.reset });
+    lines.push({ text: r.hasUpdate
+      ? C.fgYellow + `  发现新版本，可执行：npm install -g ${PKG_NAME}@latest` + C.reset
+      : C.fgGreen + `  已是最新版本` + C.reset });
+  } else {
+    lines.push({ text: C.fgGray + `  检查失败：网络不可用，请稍后重试` + C.reset });
+  }
+  await tui.message('检查版本更新', lines);
+}
+
 function coerce(value) {
   if (value === 'true') return true;
   if (value === 'false') return false;
@@ -313,7 +330,7 @@ async function tui(cwd) {
   app.enter();
   let keep = true;
   while (keep) {
-    const items = ['打包桌面应用', '新建项目', '修改配置', '壳管理', '打开教程', '退出'];
+    const items = ['打包桌面应用', '新建项目', '修改配置', '壳管理', '打开教程', '检查更新', '退出'];
     const idx = await app.menu('主菜单', items, {
       footer: `工作目录：${cwd}   ↑ ↓ 选择 · Enter 确认 · q 退出`,
     });
@@ -324,7 +341,8 @@ async function tui(cwd) {
       case 2: await configFlow(app, cwd); break;
       case 3: await shellFlow(app); break;
       case 4: await tutorialFlow(app); break;
-      case 5: keep = false; break;
+      case 5: await updateFlow(app); break;
+      case 6: keep = false; break;
     }
   }
   app.exit();

package/lib/update.js

@@ -0,0 +1,109 @@
+'use strict';
+
+// 版本检测：零依赖（https 内置），查询 npm registry 最新版本并对比本地版本。
+// - 结果缓存到 ~/.freedom/update-cache.json，24h 内不重复联网（离线不打扰）
+// - compareVersions 手写 semver 比较（仅处理 x.y.z 数字前缀，满足语义版本场景）
+// - 所有联网失败均静默降级，绝不阻塞主流程
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+const { packageRoot } = require('./utils');
+
+const PKG_NAME = '@yufengtadian/freedom-cli';
+const REGISTRY = `https://registry.npmjs.org/${encodeURIComponent(PKG_NAME)}/latest`;
+const CACHE_FILE = path.join(os.homedir(), '.freedom', 'update-cache.json');
+const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 小时
+const REQUEST_TIMEOUT = 4000;
+
+function currentVersion() {
+  return require(path.join(packageRoot(), 'package.json')).version;
+}
+
+// semver 简单比较：返回 1 / -1 / 0
+function compareVersions(a, b) {
+  const pa = String(a || '').replace(/[^\d.]/g, '').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '').replace(/[^\d.]/g, '').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+function readCache() {
+  try {
+    const j = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (j && j.latest && Date.now() - j.ts < CACHE_TTL) return j;
+  } catch (e) { /* 无缓存或损坏，忽略 */ }
+  return null;
+}
+
+function writeCache(data) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ ...data, ts: Date.now() }));
+  } catch (e) { /* 写缓存失败静默 */ }
+}
+
+// 从 npm registry 拉取 latest 版本；失败 / 超时返回 null
+function fetchLatest(timeout = REQUEST_TIMEOUT) {
+  return new Promise((resolve) => {
+    const req = https.get(REGISTRY, {
+      headers: { 'user-agent': 'freedom-cli', accept: 'application/json' },
+      timeout,
+    }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return resolve(null);
+      }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(body).version || null);
+        } catch (e) {
+          resolve(null);
+        }
+      });
+    });
+    req.on('timeout', () => req.destroy());
+    req.on('error', () => resolve(null));
+  });
+}
+
+// 检查更新：force=true 强制联网（忽略缓存）；否则优先读缓存
+async function checkUpdate({ force = false } = {}) {
+  const current = currentVersion();
+  const cache = force ? null : readCache();
+  let latest = cache ? cache.latest : null;
+  if (!latest) {
+    latest = await fetchLatest();
+    if (latest) writeCache({ latest });
+  }
+  const hasUpdate = Boolean(latest && compareVersions(latest, current) > 0);
+  return { current, latest, hasUpdate };
+}
+
+// 静默异步通知：仅在检测到新版本时打印一行升级提示，不阻塞调用方
+async function maybeNotifyUpdate() {
+  try {
+    const r = await checkUpdate();
+    if (r.hasUpdate && r.latest) {
+      const theme = require('./theme');
+      console.log('');
+      console.log(`  ${theme.paint('➜', theme.C.fg.magenta, theme.C.bold)} ${theme.paint(`新版本可用 ${r.latest}（当前 ${r.current}）`, theme.C.fg.yellow)}`);
+      console.log(`    ${theme.dim('运行')} ${theme.paint(`npm install -g ${PKG_NAME}@latest`, theme.C.fg.cyan)} ${theme.dim('升级，或')} ${theme.paint('freedom update', theme.C.fg.cyan)} ${theme.dim('查看详情')}`);
+      console.log('');
+    }
+  } catch (e) { /* 检测失败静默 */ }
+}
+
+module.exports = {
+  PKG_NAME, REGISTRY, CACHE_FILE, CACHE_TTL,
+  currentVersion, compareVersions, checkUpdate, maybeNotifyUpdate,
+};

package/lib/utils.js

@@ -28,8 +28,14 @@ function shellDir() {
 // 平台矩阵：key -> { exe 文件名（壳二进制名） }
 // 通用壳为三平台预编译二进制，应用内容通过 exe 同目录 resources/ 外部加载，
 // 因此同一壳可复用于任意应用，打包时无需任何语言工具链。
+// 全部平台 key（含暂无预编译资产来源的 linux-arm64，仅支持显式指定 / 本地编译）。
 const ALL_PLATFORMS = ['win-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64'];
 
+// 可分发平台（有预编译壳资产，CI 已产出）：--platform all 的取值集合。
+// linux-arm64 无 CI runner 与 GitHub 资产，若列入 all 会在 build 时 404 拖垮整个
+// 全量构建（历史 bug B41）；故 all 仅包含以下三平台，linux-arm64 需显式指定。
+const DIST_PLATFORMS = ['win-x64', 'darwin-arm64', 'linux-x64'];
+
 const SHELL_EXE_NAME = {
   'win-x64': 'freedom-shell.exe',
   'darwin-arm64': 'freedom-shell',
@@ -55,7 +61,13 @@ function platformExeName(plat, appName) {
 function nativePlatform() {
   const plat = process.platform;
   const arch = process.arch;
-  if (plat === 'win32') return 'win-x64';
+  if (plat === 'win32') {
+    if (arch !== 'x64') {
+      // ARM64 Windows 没有独立的 win-arm64 壳，x64 壳经系统仿真可运行；给出提示而非静默。
+      console.error(`[freedom] 注意：当前为 ${arch} 架构 Windows，将使用 win-x64 壳（x64 仿真运行）。`);
+    }
+    return 'win-x64';
+  }
   if (plat === 'darwin') {
     if (arch !== 'arm64') {
       throw new Error('已不支持 Intel Mac（darwin-x64）：请改用 Apple Silicon Mac 构建 darwin-arm64，或直接使用 darwin-arm64 产物。');
@@ -113,6 +125,7 @@ module.exports = {
   goTemplateDir,
   shellDir,
   ALL_PLATFORMS,
+  DIST_PLATFORMS,
   SHELL_EXE_NAME,
   isWinPlat,
   isMacPlat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.12.12",
+  "version": "1.12.13",
   "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
   "keywords": [
     "desktop",

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

@@ -134,12 +134,12 @@ func (p *ProcBackend) Handle(method string, params []json.RawMessage) (interface
 	id := p.nextID
 	ch := make(chan procResp, 1)
 	p.pending[id] = ch
-	msg := procMessage{ID: id, Method: method, Params: paramsJSON}
-	line, _ := json.Marshal(msg)
-	_, err = p.stdin.Write(append(line, '\n'))
+	w := p.stdin // 锁内取引用，锁外写，避免持锁阻塞（后端不消费 stdin 时 Write 可能挂起）
 	p.mu.Unlock()
 
-	if err != nil {
+	msg := procMessage{ID: id, Method: method, Params: paramsJSON}
+	line, _ := json.Marshal(msg)
+	if _, err := w.Write(append(line, '\n')); err != nil {
 		p.cancel(id, fmt.Errorf("freedom: proc backend write: %w", err))
 		return nil, err
 	}

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

@@ -12,6 +12,8 @@ package freedom
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 )
@@ -47,19 +49,24 @@ func resourcesDir() (string, error) {
 }
 
 // loadRuntimeConfig 读取 exe 同目录 resources/config.json，将命中的字段覆盖到应用配置。
-// 文件不存在或内容非法时静默回退（返回 nil），保持编译期/默认配置不变。
+// 文件不存在时视为未配置（返回 nil，保持编译期/默认配置不变）；
+// 文件存在但读取/解析失败时返回具体错误，由调用方打印告警，避免用户手改配置出错时无感知。
 func (a *App) loadRuntimeConfig() error {
 	dir, err := resourcesDir()
 	if err != nil {
-		return nil
+		return err
 	}
-	data, err := os.ReadFile(filepath.Join(dir, "config.json"))
+	cfgPath := filepath.Join(dir, "config.json")
+	data, err := os.ReadFile(cfgPath)
 	if err != nil {
-		return nil
+		if errors.Is(err, os.ErrNotExist) {
+			return nil // 未配置：正常回退默认
+		}
+		return fmt.Errorf("read %s: %w", cfgPath, err)
 	}
 	var rc runtimeConfigFile
 	if err := json.Unmarshal(data, &rc); err != nil {
-		return nil
+		return fmt.Errorf("parse %s: %w", cfgPath, err)
 	}
 	if rc.Title != "" {
 		a.cfg.Title = rc.Title

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

@@ -122,7 +122,10 @@ func (a *App) Unbind(name string) {
 func (a *App) Run() {
 	// 通用壳：先加载 exe 同目录 resources/config.json 覆盖窗口与后端配置
 	//（CLI build 时写入；缺失则使用编译期/默认配置）。
-	_ = a.loadRuntimeConfig()
+	// 配置存在但非法时打印告警（不中断启动），避免用户手改配置出错时静默无感。
+	if err := a.loadRuntimeConfig(); err != nil {
+		fmt.Printf("freedom: warning: %v\n", err)
+	}
 
 	html, err := a.resolveHTML()
 	if err != nil {
@@ -209,6 +212,13 @@ func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage,
 		}
 	}
 
+	// 框架内置方法特判：__freedom__ping 由 webview Bind 注册为全局函数
+	// window.__freedom__ping()，同时兼容经 freedom.call()/__freedom_bridge 路由的旧写法，
+	// 避免模板"测试桥接"自检报"method not bound"。
+	if method == "__freedom__ping" {
+		return json.RawMessage(`"pong"`), nil
+	}
+
 	raw, err := a.backend.Handle(method, params)
 	if err != nil {
 		return nil, err

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

@@ -57,8 +57,12 @@ func windowControl(a *App, action string) (interface{}, error) {
 		// macOS / Linux 暂不提供 exe 内嵌图标提取，前端隐藏标题栏图标。
 		return "", nil
 	case "startDrag":
-		// macOS / Linux 上无边框窗口通过 WebKit 的 -webkit-app-region: drag 拖动，
-		// 前端已在 CSS 中声明拖动区域；此处无需原生实现。
+		// 无边框窗口拖动：GTK 走 gtk_window_begin_move_drag（root_x/y=-1 用当前指针），
+		// Cocoa 走 performWindowDragWithEvent:（用当前鼠标位置合成事件）。
+		// 与 Windows 的 WM_NCLBUTTONDOWN+HTCAPTION 语义等价，保留页面双击/右键事件。
+		if a.view.BeginMoveDrag() != 0 {
+			return nil, fmt.Errorf("window drag is not supported on this platform")
+		}
 		return nil, nil
 	default:
 		return nil, fmt.Errorf("unknown window action %q", action)

package/templates/go/webview_go/libs/webview/include/webview.h

@@ -293,6 +293,7 @@ typedef enum webview_window_action {
  * @param action The action to execute (see webview_window_action_t).
  */
 WEBVIEW_API int webview_window_control(webview_t w, webview_window_action_t action);
+WEBVIEW_API int webview_window_begin_move_drag(webview_t w);
 
 /**
  * Navigates webview to the given URL. URL may be a properly encoded data URI.
@@ -1041,6 +1042,7 @@ if (status === 0) {\
   // 供前端自绘标题栏三按钮使用。action 取值见 webview_window_action_t。
   // 返回 0 表示成功；-1 表示该平台/动作不支持；isMaximized 返回 1/0。
   int window_control(int action) { return window_control_impl(action); }
+  int begin_move_drag() { return begin_move_drag_impl(); }
 
   void set_size(int width, int height, webview_hint_t hints) {
     set_size_impl(width, height, hints);
@@ -1062,6 +1064,7 @@ protected:
   virtual void set_size_impl(int width, int height, webview_hint_t hints) = 0;
   virtual void set_decorated_impl(bool decorated) = 0;
   virtual int window_control_impl(int action) = 0;
+  virtual int begin_move_drag_impl() = 0;
   virtual void set_html_impl(const std::string &html) = 0;
   virtual void init_impl(const std::string &js) = 0;
   virtual void eval_impl(const std::string &js) = 0;
@@ -1418,6 +1421,14 @@ public:
     }
   }
 
+  // 无边框窗口拖动：root_x/root_y=-1 表示用当前指针位置，由窗口管理器接管拖动。
+  // 与 Windows 的 WM_NCLBUTTONDOWN+HTCAPTION 语义等价，保留页面双击/右键事件。
+  int begin_move_drag_impl() override {
+    gtk_window_begin_move_drag(GTK_WINDOW(m_window), GDK_BUTTON_PRESS, -1, -1,
+                               gtk_get_current_event_time());
+    return 0;
+  }
+
   void set_size_impl(int width, int height, webview_hint_t hints) override {
     gtk_window_set_resizable(GTK_WINDOW(m_window), hints != WEBVIEW_HINT_FIXED);
     if (hints == WEBVIEW_HINT_NONE) {
@@ -1824,6 +1835,21 @@ public:
       return -1;
     }
   }
+
+  // 无边框窗口拖动：用当前鼠标屏幕位置合成 NSLeftMouseDragged 事件，
+  // 调 performWindowDragWithEvent: 进入 AppKit 原生窗口拖动循环。
+  int begin_move_drag_impl() override {
+    objc::autoreleasepool arp;
+    auto loc = objc::msg_send<CGPoint>("NSEvent"_cls, "mouseLocation"_sel);
+    auto wnum = objc::msg_send<NSInteger>(m_window, "windowNumber"_sel);
+    auto evt = objc::msg_send<id>(
+        "NSEvent"_cls,
+        "mouseEventWithType:location:modifierFlags:timestamp:windowNumber:context:eventNumber:clickCount:pressure:"_sel,
+        (NSUInteger)1 /*NSLeftMouseDragged*/, loc, (NSUInteger)0, (double)0.0,
+        wnum, (id)nullptr, (NSInteger)0, (NSInteger)1, (float)1.0);
+    objc::msg_send<void>(m_window, "performWindowDragWithEvent:"_sel, evt);
+    return 0;
+  }
   void navigate_impl(const std::string &url) override {
     objc::autoreleasepool arp;
 
@@ -3495,6 +3521,7 @@ public:
   // Windows 窗口控制（min/max/close）由 freedom 壳层 window_windows.go
   // 直接调 user32 处理，webview 层不参与。
   int window_control_impl(int action) override { (void)action; return -1; }
+  int begin_move_drag_impl() override { return -1; }
 
   void set_size_impl(int width, int height, webview_hint_t hints) override {
     auto style = GetWindowLong(m_window, GWL_STYLE);
@@ -3794,6 +3821,10 @@ WEBVIEW_API int webview_window_control(webview_t w, webview_window_action_t acti
       static_cast<int>(action));
 }
 
+WEBVIEW_API int webview_window_begin_move_drag(webview_t w) {
+  return static_cast<webview::webview *>(w)->begin_move_drag();
+}
+
 WEBVIEW_API void webview_navigate(webview_t w, const char *url) {
   static_cast<webview::webview *>(w)->navigate(url);
 }

package/templates/go/webview_go/webview.go

@@ -118,6 +118,10 @@ type WebView interface {
 	// 供前端自绘标题栏三按钮调用。Windows 上由 freedom 壳层处理，此处返回 -1。
 	WindowControl(action WindowAction) int
 
+	// BeginMoveDrag 发起无边框窗口的原生拖动（macOS/Linux）。
+	// Windows 由 freedom 壳层用 WM_NCLBUTTONDOWN 处理，此处返回 -1。
+	BeginMoveDrag() int
+
 	// SetSize updates native window size. See Hint constants.
 	SetSize(w int, h int, hint Hint)
 
@@ -232,6 +236,10 @@ func (w *webview) WindowControl(action WindowAction) int {
 	return int(C.webview_window_control(w.w, C.webview_window_action_t(action)))
 }
 
+func (w *webview) BeginMoveDrag() int {
+	return int(C.webview_window_begin_move_drag(w.w))
+}
+
 func (w *webview) SetSize(width int, height int, hint Hint) {
 	C.webview_set_size(w.w, C.int(width), C.int(height), C.webview_hint_t(hint))
 }

package/templates/project/src/main.js

@@ -6,8 +6,8 @@
 
 // 无边框模式：显示自绘标题栏并绑定按钮。
 // 壳桥接（__freedom_window）注入时机与页面脚本加载先后不定，早期调用可能被 reject 吞掉导致标题栏不显示，
-// 因此先轮询等待桥接就绪（最多 100 次 × 100ms）再初始化。
-function waitForBridge(tries = 100, interval = 100) {
+// 因此先轮询等待桥接就绪（最多 150 次 × 100ms = 15s）再初始化；超时后明确告警而非静默失效。
+function waitForBridge(tries = 150, interval = 100) {
   return new Promise((resolve) => {
     const check = () => {
       if (window.freedom && window.freedom.window && typeof window.__freedom_window === 'function') {
@@ -47,7 +47,11 @@ async function syncMaxState(w) {
 }
 
 async function initFrameless() {
-  if (!(await waitForBridge())) return;
+  const ready = await waitForBridge();
+  if (!ready) {
+    console.warn('[freedom] 桥接 15s 未就绪，无边框标题栏未初始化（窗口仍可正常使用）。');
+    return;
+  }
   try {
     const frameless = await window.freedom.window.isFrameless();
     if (!frameless) return;
@@ -148,11 +152,14 @@ function initTitlebarMenu() {
 initTitlebarMenu();
 initFrameless();
 
-// 桥接自检。
+// 桥接自检：__freedom__ping 是壳注入的全局函数，优先直调；
+// 低版本壳不存在时回退经 bridge 路由（壳层 bridge 对 ping 特判兼容）。
 document.getElementById('pingBtn').addEventListener('click', async () => {
   const el = document.getElementById('result');
   try {
-    const r = await window.freedom.call('__freedom__ping');
+    const r = (typeof window.__freedom__ping === 'function')
+      ? await window.__freedom__ping()
+      : await window.freedom.call('__freedom__ping');
     el.textContent = '桥接正常：' + r;
   } catch (e) {
     el.textContent = '桥接异常：' + e.message;

package/templates/go/err.txt

@@ -1,2 +0,0 @@
-# freedom-cli-shell/pkg/freedom
-pkg\freedom\freedom.go:212:16: cannot use a.backend.Handle(method, params) (value of type interface{}) as json.RawMessage value in assignment: need type assertion

package/templates/go/err4.txt

@@ -1 +0,0 @@
-github.com/webview/webview_go: build constraints exclude all Go files in D:\dev\自研desktop exe打包框架\freedom-cli\templates\go\webview_go

package/templates/go/go.mod.bak_gbk

@@ -1,11 +0,0 @@
-module freedom-cli-shell
-
-go 1.22
-
-require github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6
-
-require golang.org/x/sys v0.28.0
-
-// Freedom fork: 使用随包分发的本地 webview_go（标题栏图标与 exe 图标一致等定制），
-// 避免拉取上游被覆盖。
-replace github.com/webview/webview_go => ./webview_go