@yufengtadian/freedom-cli 1.1.11 → 1.12.0

package/README.md

@@ -1,11 +1,46 @@
+---
+AIGC:
+    Label: "1"
+    ContentProducer: 001191440300708461136T1XGW3
+    ProduceID: 84e692d233baf4c4ebb909c06f044dd3_2d74bd4d9c4911f184de525400f8a581
+    ReservedCode1: xo2+Pdj5CsKT7YjGd4Rry/qknv3mVecOBHAw6HqFk7EuALvKYsLlY/JCDoqw3oHEfX+sRjzs+lLZfypsJxbkr73mtQrkuHrqQIZ8f4A7vIr7hTO5V+aMiCz29hrSmbNXeI0q5SXfE/orzUoL63JrdZc1HpZGj82RLwzxXZA/d59gHWK/oYb4EXzirS8=
+    ContentPropagator: 001191440300708461136T1XGW3
+    PropagateID: 84e692d233baf4c4ebb909c06f044dd3_2d74bd4d9c4911f184de525400f8a581
+    ReservedCode2: xo2+Pdj5CsKT7YjGd4Rry/qknv3mVecOBHAw6HqFk7EuALvKYsLlY/JCDoqw3oHEfX+sRjzs+lLZfypsJxbkr73mtQrkuHrqQIZ8f4A7vIr7hTO5V+aMiCz29hrSmbNXeI0q5SXfE/orzUoL63JrdZc1HpZGj82RLwzxXZA/d59gHWK/oYb4EXzirS8=
+---
+
+
+
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.1.11）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.0）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**v1.12.0 核心升级**：标题栏默认改为完全无边框（`frameless`）——标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘融入 UI（模板已内置自绘标题栏示例），不再依赖 Windows 原生按钮。`freedom titlebar` 仍可随时切回 `native` / `hidden`。
+
+**v1.12.x 修复与加固**：
+- 修复 close 按钮缺陷：窗口关闭改走 `PostMessage(WM_CLOSE)`（原 `CloseWindow` 语义为最小化，导致点关闭只最小化）；
+- 壳二进制平台校验：构建前校验壳文件头（PE / Mach-O / ELF），杜绝"Windows 壳冒充 mac/linux 壳"的假壳被静默分发；
+- `freedom shell download` 默认版本改为动态跟随包版本（`releaseTag()` 不再硬编码 v1.1.10），并新增 `.github/workflows/build-shell.yml` 三平台 CI 构建与 Release 资产上传；
+- 壳进程启用 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.10.12 核心升级**：macOS 产物升级为标准 .app 应用包，直接产出 `.app.zip`（mac 用户解压即得 `.app`，拖入 /Applications 即可使用）；在 macOS 上执行 `freedom dmg` 可再用系统 hdiutil 生成 `.dmg`。全程仍不依赖 Go 工具链。
+
 **v1.1.11 核心升级**：不再依赖 Go 工具链。壳层以预编译二进制随 npm 包分发（`shell/<platform>/`），`freedom build` 直接复制壳 + 写入前端与配置即可出包，Windows / macOS / Linux 三平台一次全出，任意前后端语言自由组合。
 
+**v1.11.0 新特性**：
+- 自定义应用图标：`icon` 配置 + `freedom icon <path>` 命令，Windows 构建时用 rcedit 注入 `.ico` 到 exe 资源（支持多尺寸，资源管理器 / 任务栏 / 快捷方式统一显示），macOS 构建时把 `.icns` 放入 `.app` 并写入 Info.plist；
+- 标题栏默认改为 `hidden`：默认隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮；仍可用 `freedom titlebar` 随时切回 `native` / `frameless`。
+
+**v1.10.12 新特性**：
+- macOS 产物打包为标准 `.app` bundle + `.app.zip`：壳复制进 `Contents/MacOS/`，resources 与前端/后端随包，解压即用，无需任何语言运行时；
+- `freedom dmg`：在 macOS 上用系统 hdiutil 把 `.app` 打成 `.dmg`（Windows / Linux 上运行会给出指引）；
+- TUI 壳管理去 Go 依赖感：「下载壳」标注无需 Go，「本地编译壳」明确为可选项（壳已预编译随包分发）。
+
 **v1.1.11 新特性**：
 - `freedom tui` 交互式终端界面：菜单化完成打包 / 新建项目 / 修改配置 / 壳管理 / 教程，零依赖、方向键 + 回车导航、支持搜索过滤与多选；
 - 前端构建缓存：源码无改动时跳过重复 `vite build`（秒级复用，典型加速 10 倍+），`--no-cache` 强制全量重建；
@@ -30,10 +65,13 @@ npm install
 # 2. 交互式终端界面（方向键 + 回车选择，q 返回）
 freedom tui
 
-# 3. 调整标题栏（可选，随时可改）
-freedom titlebar native      # 保留系统原生标题栏（默认）
+# 3. 调整标题栏（可选，随时可改；默认 frameless：标题栏不存在，关闭/最大化/最小化按钮由前端自绘融入 UI）
+freedom titlebar native      # 保留系统原生标题栏
 freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
-freedom titlebar frameless   # 完全无边框，按钮由前端自绘（模板已内置示例）
+freedom titlebar frameless   # 完全无边框，标题栏不存在，三按钮由前端自绘（默认，模板已内置示例）
+
+# 3.5 设置应用图标（可选；Windows 用 .ico，macOS 用 .icns）
+freedom icon icon.ico
 
 # 4. 打包
 freedom build                        # 默认当前平台
@@ -46,10 +84,28 @@ freedom build --no-cache             # 忽略前端构建缓存，强制重建
 
 构建产物默认输出到 `dist/`。`dist/<应用名>.exe`（或对应平台可执行文件）为壳层程序，运行时从 `dist/resources/` 加载前端页面与配置，不弹 cmd 黑窗。
 
+**macOS 产物（v1.10.12）**：`freedom build --platform mac` 除裸可执行文件外，额外生成标准 `.app` bundle 与 `<应用名>-<平台>.app.zip`：
+
+```
+dist/<应用名>.app/
+└── Contents/
+    ├── Info.plist
+    ├── MacOS/
+    │   ├── <应用名>            # 壳可执行文件
+    │   └── resources/          # 前端页面 + config.json + backend/
+    └── Resources/
+```
+
+mac 用户解压 `.app.zip` 即得 `.app`，拖入 `/Applications` 即可直接运行，无需安装任何语言运行时。如需 `.dmg` 安装映像，把产物拷到 macOS 上执行 `freedom dmg`（用系统 hdiutil 生成），或仅分发包内 `.app.zip`。
+
 **构建缓存**：CLI 会在 `.freedom/vite-dist/` 记录前端源码指纹，源码无改动时复用上次构建产物直接进入分发阶段（秒级完成）。修改了 `src/` / `index.html` / `vite.config.js` 等任一处会触发自动重建；需要强制全量时可加 `--no-cache`。
 
 **三平台打包**：壳层二进制随包分发，无需本机安装 Go 或交叉编译工具链。首次构建某平台时若本地缺少对应壳二进制，CLI 自动从 GitHub Releases 下载（`freedom shell download <platform>` 可手动补齐）；仅当你想用本机 Go 工具链亲自编译壳时才需要 `freedom shell build`（只产出本机平台）。多平台分发为并行执行，全平台打包耗时大幅缩短。
 
+**壳二进制平台校验**：`freedom 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 自动触发）即自动补齐各平台壳资产。
+
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
 ```bash
@@ -61,9 +117,9 @@ freedom config set outDir dist  # 恢复默认 dist/
 
 | 模式 | 说明 |
 | --- | --- |
-| `native` | 保留系统原生标题栏（默认） |
+| `native` | 保留系统原生标题栏 |
 | `hidden` | 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮（DWM 扩展实现） |
-| `frameless` | 完全无边框，客户区铺满窗口，最小化 / 最大化 / 关闭按钮由前端自绘 |
+| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例） |
 
 `hidden` / `frameless` 模式下，前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例。
 
@@ -78,12 +134,18 @@ export default {
   minHeight: 300,
   center: true,          // 启动居中
   debug: false,          // 开发者工具
-  titlebar: 'native',    // native | hidden | frameless
+  titlebar: 'frameless', // frameless（默认，标题栏不存在，三按钮由前端自绘）| native | hidden
+  icon: undefined,       // 应用图标：Windows 用 .ico（推荐多尺寸），macOS 用 .icns
   outDir: 'dist',        // 产物目录：'dist'（默认）| '.'（项目根目录）| 任意路径
   // backend: { command: 'node', args: ['backend/main.mjs'] },  // 任意语言后端进程
 };
 ```
 
+**图标说明**：
+- Windows：`.ico` 在构建时由 rcedit 注入 exe 资源（无需 VC 资源编译器），资源管理器 / 任务栏 / 快捷方式统一显示自定义图标；推荐含 16 / 32 / 48 / 256 多尺寸；
+- macOS：`.icns` 在构建时放入 `.app/Contents/Resources` 并写入 Info.plist 的 `CFBundleIconFile`；
+- 未配置时使用壳默认图标。`freedom icon <path>` 可直接写入该配置。
+
 ## 前端
 
 前端是标准 Vite 项目，`vite build` 时通过 `vite-plugin-singlefile` 内联为单个 HTML。壳层注入全局对象 `window.freedom`：
@@ -99,6 +161,7 @@ window.freedom.window.minimize();                       // 窗口控制
 - Node.js >= 18
 - 不需要 Go 工具链（壳层为随包分发的预编译二进制）
 - 可选：`freedom shell build` 需本机 Go（含 CGO，Windows 需 MSVC 编译环境），仅用于亲自编译壳
+- `.dmg` 打包需在 macOS 上执行（依赖系统 hdiutil）；`.app.zip` 在任意平台均可直接产出
 
 ## 命令
 
@@ -107,8 +170,10 @@ freedom tui                          # 交互式终端界面
 freedom init <目录> [--force]
 freedom build [--platform win-x64|mac-arm64|linux-x64|all] [--no-cache]
 freedom titlebar <native|hidden|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 tutorial
 freedom help
 ```
@@ -135,3 +200,5 @@ export default {
 ## License
 
 MIT
+*（内容由AI生成，仅供参考）*
+*（内容由AI生成，仅供参考）*

package/lib/build.js

@@ -11,6 +11,11 @@
 //      - 写 resources/config.json（窗口 + 后端配置，壳运行时读取）
 //      - 复制壳为 outDir/<app>[.exe]
 //      - 复制 backend/ 到 resources/backend/（配置了 backend 时）
+//   4. macOS 平台额外生成 .app bundle + .app.zip：
+//      outDir/<app>.app/Contents/{Info.plist, MacOS/<app>, MacOS/resources/}
+//      壳加载 exe 同目录 resources/，因此 .app 无需改壳即可运行；
+//      mac 用户解压 .app.zip 得 .app，拖入 /Applications 即可使用；
+//      如需 .dmg，在 macOS 上运行 freedom dmg 用系统 hdiutil 生成。
 //
 // 产物不嵌入 HTML，页面与配置均在 exe 同目录 resources/ 下，因此壳可复用、
 // 可跨平台分发、无需在目标机器安装任何语言运行时。
@@ -23,11 +28,12 @@ const { copyDir } = require('./utils');
 const {
   ALL_PLATFORMS,
   isWinPlat,
+  isMacPlat,
   platformExeName,
   nativePlatform,
   localShellPath,
 } = require('./utils');
-const { hasShell, downloadShell } = require('./shell');
+const { hasShell, downloadShell, validateLocalShell } = require('./shell');
 
 function run(cmd, args, opts = {}) {
   // Windows 下 npm 是 .cmd 批处理，必须经 shell 执行
@@ -69,6 +75,7 @@ async function build(projectDir, opts = {}) {
   const cfg = await loadConfig(dir);
 
   const name = (cfg.name || 'freedom-app').replace(/[^a-zA-Z0-9_.-]/g, '-');
+  const version = String(cfg.version || appVersionFromPkg(dir) || '1.0.0');
   const outDir = String(cfg.outDir || 'dist').trim() || 'dist';
   const outDirPath = path.resolve(dir, outDir);
   const platforms = parsePlatforms(opts.platform);
@@ -97,13 +104,17 @@ async function build(projectDir, opts = {}) {
   const backendDir = path.join(dir, cfg.backendDir || 'backend');
   const hasBackend = !!(cfg.backend && fs.existsSync(backendDir));
 
-  // 3) 逐平台分发（多平台并行，显著缩短全平台打包耗时）
+  // 3) 应用图标：cfg.icon（相对项目根或绝对路径）。Windows 注入 .ico 到 exe 资源，
+  //    macOS 把 .icns 放入 .app/Contents/Resources 并在 Info.plist 声明。
+  const icon = resolveIcon(dir, cfg.icon);
+
+  // 4) 逐平台分发（多平台并行，显著缩短全平台打包耗时）
   // 单平台直接输出到 outDir；多平台各自放到 outDir/<plat>/ 子目录，避免互相覆盖
   const multi = platforms.length > 1;
   const results = await Promise.all(
     platforms.map(async (plat) => {
       const targetDir = multi ? path.join(outDirPath, plat) : outDirPath;
-      const outFile = await emitPlatform({ plat, name, targetDir, html, configJSON, backendDir, hasBackend, autoDownload });
+      const outFile = await emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon });
       return { plat, outFile };
     })
   );
@@ -111,7 +122,7 @@ async function build(projectDir, opts = {}) {
   return { results };
 }
 
-async function emitPlatform({ plat, name, targetDir, html, configJSON, backendDir, hasBackend, autoDownload }) {
+async function emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon }) {
   // 取预编译壳二进制
   const shell = localShellPath(plat);
   if (!fs.existsSync(shell)) {
@@ -123,6 +134,12 @@ async function emitPlatform({ plat, name, targetDir, html, configJSON, backendDi
     }
     process.stdout.write(`[freedom] 本地无 ${plat} 壳，尝试自动下载...\n`);
     await downloadShell(plat);
+  } else {
+    // 壳格式校验：防止 mac/linux 平台误用 Windows 假壳被静默分发（历史缺陷：shell/<darwin-*>/<linux-*> 曾误填 Windows PE 副本）。
+    const formatIssue = validateLocalShell(plat);
+    if (formatIssue) {
+      throw new Error(formatIssue);
+    }
   }
 
   await fsp.mkdir(targetDir, { recursive: true });
@@ -135,6 +152,11 @@ async function emitPlatform({ plat, name, targetDir, html, configJSON, backendDi
     await fsp.chmod(outFile, 0o755);
   }
 
+  // 自定义 exe 图标（仅 Windows PE 支持嵌入 .ico 资源；mac 用 .icns 走 .app 分支）
+  if (isWinPlat(plat) && icon) {
+    await applyWindowsIcon(outFile, icon);
+  }
+
   // 写 resources：页面 + 配置 + 后端
   const resDir = path.join(targetDir, 'resources');
   await fsp.mkdir(resDir, { recursive: true });
@@ -144,15 +166,158 @@ async function emitPlatform({ plat, name, targetDir, html, configJSON, backendDi
     copyDir(backendDir, path.join(resDir, 'backend'));
   }
 
+  // macOS：额外生成 .app bundle + .app.zip（供 mac 用户解压即用）
+  // 壳加载 exe 同目录 resources/，故把 resources 放进 Contents/MacOS/ 即可运行，无需改壳。
+  if (isMacPlat(plat)) {
+    const appZip = createMacApp({ targetDir, name, plat, exeName, resDir, version, icon });
+    process.stdout.write(
+      `[freedom] macOS 产物已打包为 .app.zip：${path.relative(process.cwd(), appZip)}\n`
+    );
+  }
+
   return outFile;
 }
 
+// 把 .ico 图标注入到 Windows exe 的 PE 资源（RT_ICON + RT_GROUP_ICON）。
+// 依赖 rcedit（随 npm 包分发的预编译 rcedit-x64.exe，无需 Go/资源编译器）。
+async function applyWindowsIcon(exePath, iconPath) {
+  const ext = path.extname(iconPath).toLowerCase();
+  if (ext !== '.ico') {
+    process.stdout.write(
+      `[freedom] 提示：Windows exe 图标需 .ico 格式，已跳过（${iconPath}）。\n`
+    );
+    return;
+  }
+  if (process.platform !== 'win32') {
+    process.stdout.write(
+      '[freedom] 提示：exe 图标注入需在 Windows 本机执行，已跳过。\n'
+    );
+    return;
+  }
+  const rcedit = require('rcedit'); // 惰性加载，避免未配置 icon 时增加启动开销
+  await rcedit(exePath, { icon: iconPath });
+  process.stdout.write(`[freedom] 已注入 exe 图标：${iconPath}\n`);
+}
+
+// 解析 cfg.icon：相对项目根或绝对路径 -> 绝对路径；未配置返回 null。
+// 不校验格式，格式由各平台注入逻辑决定（win 需 .ico / mac 需 .icns）。
+function resolveIcon(dir, icon) {
+  if (!icon) return null;
+  const p = path.isAbsolute(icon) ? icon : path.resolve(dir, icon);
+  if (!fs.existsSync(p)) {
+    throw new Error(`未找到图标文件：${icon}（已尝试 ${p}）。请检查 freedom.config.js 的 icon 配置。`);
+  }
+  return p;
+}
+
+// 把已分发的裸产物升级为标准 .app bundle，并压缩为 .app.zip
+function createMacApp({ targetDir, name, plat, exeName, resDir, version, icon }) {
+  const appDir = path.join(targetDir, `${name}.app`);
+  const contents = path.join(appDir, 'Contents');
+  const macos = path.join(contents, 'MacOS');
+  const appRes = path.join(macos, 'resources');
+  fs.mkdirSync(macos, { recursive: true });
+  fs.mkdirSync(path.join(contents, 'Resources'), { recursive: true });
+
+  // 可执行文件：exe 名与 app 同名，放入 MacOS/
+  const exeDst = path.join(macos, name);
+  fs.copyFileSync(path.join(targetDir, exeName), exeDst);
+  fs.chmodSync(exeDst, 0o755);
+
+  // resources -> MacOS/resources（壳的运行时目录）
+  if (fs.existsSync(resDir)) {
+    copyDir(resDir, appRes);
+  }
+
+  // 自定义 .app 图标：icon 为 .icns 时放入 Resources/ 并在 Info.plist 声明
+  let icnsName = null;
+  if (icon && path.extname(icon).toLowerCase() === '.icns') {
+    icnsName = 'icon.icns';
+    fs.copyFileSync(icon, path.join(contents, 'Resources', icnsName));
+  } else if (icon) {
+    process.stdout.write(
+      `[freedom] 提示：macOS .app 图标需 .icns 格式，已跳过（${icon}）。\n`
+    );
+  }
+
+  // Info.plist
+  fs.writeFileSync(path.join(contents, 'Info.plist'), renderInfoPlist(name, version, icnsName), 'utf8');
+
+  // .app.zip：解压即得 .app，拖入 /Applications 即可使用
+  const zipPath = path.join(targetDir, `${name}-${plat}.app.zip`);
+  zipDir(zipPath, appDir);
+  return zipPath;
+}
+
+function renderInfoPlist(name, version, icnsName) {
+  const safe = String(name).replace(/&/g, '&amp;');
+  const bundleId = `com.freedom.app.${String(name).toLowerCase().replace(/[^a-z0-9.-]/g, '-')}`;
+  const iconEntry = icnsName
+    ? `  <key>CFBundleIconFile</key>\n  <string>${icnsName}</string>\n`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key>
+  <string>${safe}</string>
+  <key>CFBundleDisplayName</key>
+  <string>${safe}</string>
+${iconEntry}  <key>CFBundleExecutable</key>
+  <string>${safe}</string>
+  <key>CFBundleIdentifier</key>
+  <string>${bundleId}</string>
+  <key>CFBundleVersion</key>
+  <string>${version}</string>
+  <key>CFBundleShortVersionString</key>
+  <string>${version}</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>LSMinimumSystemVersion</key>
+  <string>10.13</string>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+  <key>NSAppTransportSecurity</key>
+  <dict>
+    <key>NSAllowsArbitraryLoads</key>
+    <true/>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+// 用系统 tar（Windows 为 bsdtar）把目录压成 zip：跨平台可用，无需额外依赖
+function zipDir(zipPath, dir) {
+  const parent = path.dirname(dir);
+  const base = path.basename(dir);
+  if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
+  const res = spawnSync('tar', ['-a', '-c', '-f', zipPath, base], { cwd: parent, encoding: 'utf8' });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      `打包 ${base} 为 zip 失败：${(res.stderr || res.stdout || '').trim() || res.error.message}`
+    );
+  }
+}
+
+// 从项目 package.json 取版本号（cfg.version 优先）
+function appVersionFromPkg(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch (e) {
+    return null;
+  }
+}
+
 // 渲染 resources/config.json（与壳 configfile.go 的 runtimeConfigFile 字段对齐）
 function renderConfigJSON(cfg, name) {
   const obj = {
     name,
     title: cfg.title || cfg.name || name,
-    titlebar: cfg.titlebar || 'native',
+    titlebar: cfg.titlebar || 'frameless',
     width: intVal(cfg.width, 1024),
     height: intVal(cfg.height, 720),
     minWidth: intVal(cfg.minWidth, 400),
@@ -230,18 +395,19 @@ function writeViteCacheMarker(dir) {
 }
 
 function ensureNodeModules(dir) {
-  // 缺陷修复：node_modules 存在但 package.json 更新过（依赖变更）时自动重装。
+  // 依赖变更检测：package.json 比 package-lock.json 新，说明依赖声明有更新，自动重装。
+  // 以 package-lock.json（npm install 后必然生成）为基准，比旧版依赖 node_modules/.package-lock.json 更可靠。
   const pkgFile = path.join(dir, 'package.json');
+  const lockFile = path.join(dir, 'package-lock.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)) {
+  if (fs.existsSync(pkgFile) && fs.existsSync(lockFile)) {
     const pkgMtime = fs.statSync(pkgFile).mtimeMs;
-    const lockMtime = fs.statSync(marker).mtimeMs;
+    const lockMtime = fs.statSync(lockFile).mtimeMs;
     if (pkgMtime > lockMtime + 1000) {
       process.stdout.write('[freedom] package.json 已更新，重新安装依赖...\n');
       const res = run('npm', ['install'], { cwd: dir, stdio: 'inherit' });

package/lib/cli.js

@@ -21,9 +21,11 @@ freedom - Freedom 桌面壳打包工具 v${VERSION}
       --no-cache                       忽略前端构建缓存，强制重新打包
   freedom titlebar <native|hidden|frameless>
                                        一键切换标题栏策略
+  freedom icon <path>                  设置应用图标（Windows 需 .ico，macOS 需 .icns）
   freedom shell list                   列出本地已就绪的预编译壳
-  freedom shell download <plat>        从 GitHub Releases 下载预编译壳
-  freedom shell build <plat>           本地用 Go 编译壳（需要 Go）
+  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>     修改单个配置项
@@ -34,10 +36,19 @@ freedom - Freedom 桌面壳打包工具 v${VERSION}
 平台（<p>/<plat>）：win-x64 / darwin-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    保留系统原生标题栏（默认）
+  native    保留系统原生标题栏
   hidden    隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
-  frameless 完全无边框，按钮由前端自绘（模板已内置示例）
+  frameless 完全无边框，标题栏不存在，关闭/最大化/最小化按钮由前端自绘（默认，模板已内置示例）
+
+图标说明：
+  Windows exe 图标：在 freedom.config.js 配置 icon（.ico 路径），构建时自动注入；
+  macOS .app 图标：icon 配置 .icns 路径即可；未配置则使用壳默认图标。
 `.trim();
 }
 
@@ -90,6 +101,10 @@ async function run(argv) {
       return await runShell(rest);
     }
 
+    case 'dmg': {
+      return await runDmg(rest);
+    }
+
     case 'titlebar': {
       const mode = rest[0];
       if (!['native', 'hidden', 'frameless'].includes(mode)) {
@@ -102,6 +117,20 @@ async function run(argv) {
       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 格式）');
+        return 1;
+      }
+      setConfig(process.cwd(), 'icon', iconPath);
+      console.log(`[freedom] icon 已设置为：${iconPath}`);
+      console.log('  运行 freedom build 重新打包生效。');
+      return 0;
+    }
+
     case 'config': {
       const sub = rest[0];
       if (sub === 'get') {
@@ -183,6 +212,7 @@ async function runShell(rest) {
       }
       const dest = buildShell(plat);
       console.log(`[freedom] 已编译 ${plat} 壳：${dest}`);
+      console.log('[freedom] 提示：壳已预编译随包分发，一般无需本地编译。');
       return 0;
     }
     default:
@@ -191,6 +221,45 @@ async function runShell(rest) {
   }
 }
 
+// freedom dmg：在 macOS 上把已构建的 .app 打包为 .dmg（依赖系统 hdiutil）
+async function runDmg(rest) {
+  const { loadConfig, nativePlatform } = require('./utils');
+  const { makeDmg } = require('./dmg');
+  const dir = process.cwd();
+  const cfg = await loadConfig(dir);
+  const name = (cfg.name || 'freedom-app').replace(/[^a-zA-Z0-9_.-]/g, '-');
+  const outDir = String(cfg.outDir || 'dist').trim() || 'dist';
+
+  const platArg = rest.find((a) => a.startsWith('--platform'));
+  const plat = platArg
+    ? (platArg.includes('=') ? platArg.split('=')[1] : rest[rest.indexOf(platArg) + 1])
+    : nativePlatform();
+  if (!plat || !plat.startsWith('darwin')) {
+    console.error('[freedom] dmg 仅支持 macOS 平台（darwin-x64 / darwin-arm64）。');
+    return 1;
+  }
+
+  const baseDir = path.resolve(dir, outDir);
+  // 兼容 build --platform all 的 outDir/<plat> 布局
+  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。');
+    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}`);
+    return 0;
+  } catch (e) {
+    console.error(`[freedom] ${e.message}`);
+    return 1;
+  }
+}
+
 function openBrowser(file) {
   const { spawn } = require('child_process');
   const plat = process.platform;

package/lib/config.js

@@ -13,7 +13,8 @@ const KNOWN_KEYS = {
   minHeight: 300,
   center: true,
   debug: false,
-  titlebar: 'native',
+  titlebar: 'frameless',
+  icon: undefined,
   outDir: 'dist',
 };
 
@@ -32,7 +33,8 @@ function setConfig(dir, key, value) {
     }
   }
 
-  const regex = new RegExp(`(${key}\\s*:\\s*)('[^']*'|\\d+|true|false|undefined|null)`, 'g');
+  // 同时兼容单引号与双引号字符串写法（模板统一单引号，用户手写可能用双引号）。
+  const regex = new RegExp(`(${key}\\s*:\\s*)(\"[^\"]*\"|'[^']*'|\\d+|true|false|undefined|null)`, 'g');
   if (!regex.test(text)) {
     throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到，请手动添加。`);
   }

package/lib/dmg.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// freedom dmg：把已构建的 .app bundle 打包为 .dmg（macOS 分发格式）
+//
+// 说明：.dmg 依赖 macOS 系统自带的 hdiutil，只能在 macOS 上生成。
+// Windows / Linux 上运行 freedom build 已直接产出 .app.zip（解压即得 .app，
+// 拖入 /Applications 即可使用），无需 dmg；如仍需 dmg，把产物拷到 Mac 上执行
+// freedom dmg 即可。
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+async function makeDmg(appDir, outPath, volName) {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      '.dmg 依赖 macOS 系统 hdiutil，只能在 macOS 上生成。\n' +
+        '  当前平台可直接分发 .app.zip（解压即得 .app，拖入 /Applications 即可使用）。\n' +
+        '  如需 .dmg，请把 .app 拷到 macOS 上运行：freedom dmg'
+    );
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  if (fs.existsSync(outPath)) fs.unlinkSync(outPath);
+
+  const args = [
+    'create',
+    '-volname',
+    String(volName || path.basename(appDir, '.app')),
+    '-srcfolder',
+    appDir,
+    '-ov',
+    '-format',
+    'UDZO',
+    outPath,
+  ];
+  const res = spawnSync('hdiutil', args, { encoding: 'utf8' });
+  if (res.error || res.status !== 0) {
+    throw new Error(`hdiutil 生成 dmg 失败：\n${(res.stderr || res.stdout || '').trim()}`);
+  }
+  return outPath;
+}
+
+module.exports = { makeDmg };

package/lib/shell.js

@@ -27,15 +27,75 @@ const {
 // GitHub Releases 下载源（可用环境变量覆盖）。
 // 资产命名约定：freedom-shell-<plat>（单文件二进制，不压缩）。
 function releaseRepo() {
-  return process.env.FREEDOM_SHELL_REPO || 'yufengtadian/freedom';
+  return process.env.FREEDOM_SHELL_REPO || 'YUfeng12TA/freedom';
+}
+
+// 远程壳下载的默认版本：与当前包版本保持一致。
+// 通过环境变量 FREEDOM_SHELL_TAG 可强制覆盖；默认动态读取 package.json 的 version，
+// 避免与包版本漂移（历史曾硬编码 v1.1.10 导致下载到旧壳）。
+function pkgVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' && pkg.version ? pkg.version : '1.1.10';
+  } catch (e) {
+    return '1.1.10';
+  }
 }
 function releaseTag() {
-  return process.env.FREEDOM_SHELL_TAG || 'v1.1.10';
+  return process.env.FREEDOM_SHELL_TAG || `v${pkgVersion()}`;
 }
 function releaseUrl(plat) {
   return `https://github.com/${releaseRepo()}/releases/download/${releaseTag()}/freedom-shell-${plat}`;
 }
 
+// ---- 壳二进制平台格式校验 ----
+// 读取二进制文件头判断真实平台格式，防止"用 Windows 壳冒充 mac/linux 壳"这类假壳
+// 被静默分发（历史缺陷：shell/<darwin-*>/<linux-*> 曾误填 Windows PE 副本）。
+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';
+  return 'unknown';
+}
+
+// 平台 key -> 期望的二进制格式族
+function expectedFormat(plat) {
+  if (plat.startsWith('win')) return 'win';
+  if (plat.startsWith('darwin')) return 'mac';
+  if (plat.startsWith('linux')) return 'linux';
+  return 'unknown';
+}
+
+// 校验本地壳二进制是否为目标平台的真实格式；不匹配返回错误说明，不抛错（供调用方决策）。
+function validateLocalShell(plat) {
+  const p = localShellPath(plat);
+  if (!fs.existsSync(p)) {
+    return null; // 壳不存在：不校验，由调用方决定下载/编译
+  }
+  let buf;
+  try {
+    buf = fs.readFileSync(p);
+  } catch (e) {
+    return `无法读取壳二进制 ${p}：${e.message}`;
+  }
+  const fmt = detectShellFormat(buf);
+  const want = expectedFormat(plat);
+  if (fmt === 'unknown') {
+    return `壳二进制 ${p} 不是可识别的 PE/Mach-O/ELF 格式（detect=${fmt}）。`;
+  }
+  if (fmt !== want) {
+    return `壳二进制 ${p} 格式与目标平台 ${plat} 不匹配：期望 ${want}，实际 ${fmt}。` +
+      `这是假壳（历史缺陷曾把 Windows 壳复制到 mac/linux 平台）。` +
+      `请运行 freedom shell build ${plat} 在 ${plat} 本机编译真实壳，` +
+      `或 freedom shell download ${plat} 拉取 CI 预编译产物。`;
+  }
+  return null;
+}
+
 // 列出本地已就绪的壳平台
 function listLocal() {
   const dir = shellDir();
@@ -136,4 +196,14 @@ function nativePlatformKey() {
   return `${plat}-${arch}`;
 }
 
-module.exports = { listLocal, hasShell, downloadShell, buildShell, releaseRepo, releaseTag };
+module.exports = {
+  listLocal,
+  hasShell,
+  downloadShell,
+  buildShell,
+  releaseRepo,
+  releaseTag,
+  detectShellFormat,
+  expectedFormat,
+  validateLocalShell,
+};

package/lib/tui.js

@@ -8,7 +8,9 @@ const readline = require('readline');
 const { init } = require('./init');
 const { build } = require('./build');
 const { setConfig, showConfig } = require('./config');
-const { tutorialFile, hasConfig, ALL_PLATFORMS } = require('./utils');
+const { tutorialFile, hasConfig, ALL_PLATFORMS, packageRoot } = require('./utils');
+
+const TUI_VERSION = require(path.join(packageRoot(), 'package.json')).version;
 
 // ---------------- ANSI ----------------
 const ESC = '\x1b';
@@ -75,7 +77,7 @@ class TUI {
     const pad = (s) => `  ${s}`;
     const lines = [
       '',
-      `  ${C.fgCyan}${C.bold}▚  F R E E D O M   T U I   ${C.fgGray}v1.1.10${C.reset}`,
+      `  ${C.fgCyan}${C.bold}▚  F R E E D O M   T U I   ${C.fgGray}v${TUI_VERSION}${C.reset}`,
       '',
       top,
       pad(titleMid),
@@ -191,6 +193,7 @@ const CONFIG_KEYS = [
   ['center', '启动居中（true/false）'],
   ['debug', '开发者工具（true/false）'],
   ['titlebar', '标题栏：native | hidden | frameless'],
+  ['icon', '应用图标：.ico（Windows）/ .icns（macOS）路径'],
   ['outDir', '产物目录：dist（默认）| .（项目根）| 任意路径'],
   ['backend', '任意语言后端进程（JSON）'],
 ];
@@ -259,7 +262,7 @@ async function configFlow(tui, cwd) {
 async function shellFlow(tui) {
   const { listLocal, downloadShell, buildShell } = require('./shell');
   for (;;) {
-    const items = ['查看已就绪壳', '下载壳', '本地编译壳', '返回'];
+    const items = ['查看已就绪壳', '下载壳（无需 Go）', '本地编译壳（可选·需 Go）', '返回'];
     const idx = await tui.menu('壳管理', items);
     if (idx === null || idx === items.length - 1) return;
 
@@ -277,7 +280,7 @@ async function shellFlow(tui) {
         console.log(`${C.fgGreen}[freedom]${C.reset} 已下载 ${ALL_PLATFORMS[p]} 壳：${dest}`);
       });
     } else {
-      const p = await tui.menu('选择要编译的壳平台（需 Go 且仅本机平台）', ALL_PLATFORMS);
+      const p = await tui.menu('选择要编译的壳平台（可选·需 Go，壳已预编译随包分发，一般无需编译）', ALL_PLATFORMS);
       if (p === null) continue;
       await tui.runTask(async () => {
         const dest = buildShell(ALL_PLATFORMS[p]);

package/lib/utils.js

@@ -42,6 +42,11 @@ function isWinPlat(plat) {
   return plat.startsWith('win');
 }
 
+// macOS 平台（darwin-*）：产物需升级为 .app bundle + .app.zip 供 mac 用户解压即用
+function isMacPlat(plat) {
+  return plat.startsWith('darwin');
+}
+
 // 平台 key -> 产物可执行文件名（Windows 带 .exe，其余无扩展名）
 function platformExeName(plat, appName) {
   return isWinPlat(plat) ? `${appName}.exe` : appName;
@@ -106,6 +111,7 @@ module.exports = {
   ALL_PLATFORMS,
   SHELL_EXE_NAME,
   isWinPlat,
+  isMacPlat,
   platformExeName,
   nativePlatform,
   localShellPath,

package/package.json

@@ -1,8 +1,16 @@
-{
+{
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.1.11",
+  "version": "1.12.0",
   "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"],
+  "keywords": [
+    "desktop",
+    "webview",
+    "electron-alternative",
+    "wails",
+    "tauri",
+    "frontend",
+    "cross-platform"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -24,5 +32,8 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "rcedit": "^4.0.1"
   }
 }

package/templates/go/gen_config.go

@@ -11,7 +11,7 @@ import "freedom-cli-shell/pkg/freedom"
 func appConfig() freedom.Config {
 	return freedom.Config{
 		Title:     "Freedom App",
-		TitleBar:  freedom.TitleBarNative,
+		TitleBar:  freedom.TitleBarFrameless,
 		Width:     1024,
 		Height:    720,
 		MinWidth:  400,

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

@@ -8,6 +8,20 @@ import (
 	"unsafe"
 )
 
+// 进程级 DPI 感知：让窗口坐标 / WebView 渲染统一按物理像素工作。
+// 若不设置，高 DPI 系统（如 125%/150% 缩放）下 GetWindowRect 返回逻辑坐标，
+// 与物理像素的鼠标坐标错位（UI 自动化难定位），且 WebView 内容渲染模糊。
+// 必须在窗口创建前生效，故放在 init()。
+func init() {
+	shcore := syscall.NewLazyDLL("shcore.dll")
+	procSetProcessDpiAwareness := shcore.NewProc("SetProcessDpiAwareness")
+	r, _, _ := procSetProcessDpiAwareness.Call(2) // PER_MONITOR_DPI_AWARE
+	if r != 0 {
+		// 回退到 user32 的旧版 API（Win 8 以下 / 调用失败时）
+		user32win.NewProc("SetProcessDPIAware").Call()
+	}
+}
+
 // Windows 平台原生窗口操作（user32 / dwmapi）。
 // 供标题栏策略（applyTitleBar）与前端 window.freedom.window.* 控制使用。
 
@@ -17,10 +31,10 @@ var (
 	procGetWindowLongPtr = user32win.NewProc("GetWindowLongPtrW")
 	procSetWindowLongPtr = user32win.NewProc("SetWindowLongPtrW")
 	procShowWindow       = user32win.NewProc("ShowWindow")
-	procCloseWindow      = user32win.NewProc("CloseWindow")
 	procIsZoomed         = user32win.NewProc("IsZoomed")
 	procSetWindowPos     = user32win.NewProc("SetWindowPos")
 	procSetWindowText    = user32win.NewProc("SetWindowTextW")
+	procPostMessage      = user32win.NewProc("PostMessageW")
 
 	dwmapi                     = syscall.NewLazyDLL("dwmapi.dll")
 	procDwmExtendFrameIntoArea = dwmapi.NewProc("DwmExtendFrameIntoClientArea")
@@ -31,6 +45,7 @@ const (
 	wsSysMenu   = 0x00080000
 	wsThickFrame = 0x00040000
 
+	wmClose     = 0x0010 // WM_CLOSE：请求窗口正常关闭（触发 GoWnd 的关闭回调）
 	swHide      = 0
 	swShow      = 5
 	swMinimize  = 6
@@ -89,7 +104,9 @@ func windowControl(hwnd uintptr, action string, mode TitleBarMode) (interface{},
 		}
 		return nil, nil
 	case "close":
-		procCloseWindow.Call(hwnd)
+		// 发送 WM_CLOSE 请求正常关闭（触发 GoWnd 关闭回调，释放 WebView 资源）。
+		// 注意：不能使用 user32.CloseWindow —— 该 API 语义是最小化窗口。
+		procPostMessage.Call(hwnd, wmClose, 0, 0)
 		return nil, nil
 	case "isMaximized":
 		return isZoomed(hwnd), nil

package/templates/project/freedom.config.js

@@ -19,11 +19,18 @@ export default {
   debug: false,
 
   // 标题栏策略，在终端随时可改，三选一：
-  //   'native'    - 保留系统原生标题栏（默认）
+  //   'native'    - 保留系统原生标题栏
   //   'hidden'    - 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮
-  //   'frameless' - 完全无边框，按钮由前端自绘（模板已内置自绘标题栏示例）
+  //   'frameless' - 完全无边框，标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘（模板已内置示例，默认）
   // 终端命令：freedom titlebar <native|hidden|frameless>
-  titlebar: 'native',
+  titlebar: 'frameless',
+
+  // 应用图标（可执行文件 / .app 的图标）：
+  //   Windows 需 .ico（推荐含 16/32/48/256 多尺寸），构建时注入 exe 资源；
+  //   macOS 需 .icns，构建时放入 .app/Contents/Resources 并写入 Info.plist。
+  //   值为相对项目根目录的路径或绝对路径，未配置则使用壳默认图标。
+  // 终端命令：freedom icon <path>（Windows 主用）
+  icon: undefined,
 
   // 产物输出目录（相对项目根目录或绝对路径）：
   //   'dist' - 输出到 dist/ 子目录（默认）