@yufengtadian/freedom-cli 1.12.18 → 1.13.1

package/README.md

@@ -1,9 +1,17 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.17）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.1）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**v1.13.x 框架线回归 + 稳定性收口**（v1.13.0 功能，v1.13.1 为文档勘误发布）：
+- **freedom-cli 源码回归主仓库**：本 CLI 与框架源码同仓维护（`freedom-cli/` 目录，`templates/go` 为框架源码快照），npm 包与 GitHub Release 一一对应，历史"源码丢失停在 1.12.18"的断档已修复；
+- **三平台通用壳经 tag CI 自动发布**：推送 `vX.Y.Z` tag 即由 `build.yml` 在 win / mac（Apple Silicon）/ linux runner 上编译通用壳并自动创建 GitHub Release，资产命名 `freedom-shell-<plat>`；`freedom shell download <plat>` 直接拉取对应版本资产（默认定位 `v<包版本>`，可用 `FREEDOM_SHELL_TAG` 覆盖），包内另自带三平台壳兜底，均随包分发；
+- **运行时资源层回归**：壳从 exe 同目录 `resources/` 读取 `config.json`（窗口 / 后端配置覆盖）与前端页面，high 模式下为加密 `app.bin`（FRDM1 容器）+ `.integrity` 清单；JS 侧构建加密 → Go 壳内存解密已有跨语言黄金向量与端到端互验（改名 / 篡改即拒绝运行）；
+- **多窗口（M2）随 v1.13.0 壳可用**：前端 `window.freedom.window.create / close / list / focus` 开二级窗口，Go 侧 `App.NewWindow / Window.Close`；次级窗口独立消息泵、页面源支持内联 HTML / URL；
+- **销毁竞态收口**：修复 webview2 在 `Destroy` 中泵出滞留 dispatch 回调导致的随机崩溃（0xc0000005，多窗口 / 快速关闭场景），回收后所有排队回调按拆除旗标自我作废，并配套红绿回归测试；
+- **v1.13.1**：文档同步（本 README 更新至 v1.13.x 真实现状、壳 CI 章节勘误），无功能与壳二进制变更。
+
 **v1.12.17 安全模式全面落地**：三档安全模式 `freedom security <none|basic|high>` 正式随包分发——high 档把 resources 加密为 `app.bin`（AES-256-CTR + HMAC-SHA256 + PBKDF2 密钥派生），配合 `.integrity` 完整性校验、anti-debug 与进程隐藏，磁盘无明文、篡改即拒运行；三平台预编译壳经 CI 重建分发，补齐 v1.12.16 仅重编 win-x64 壳的缺口。
 
 **v1.12.16 自动更新 + 完整 CLI 模式 + 壳生命周期全面防御**：
@@ -45,7 +53,7 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 **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 资产上传；
+- `freedom shell download` 默认版本改为动态跟随包版本（`releaseTag()` 不再硬编码 v1.1.10），并新增三平台 CI 构建与 Release 资产上传流水线（自 v1.13.0 起并入 `build.yml` 的 tag 触发，见「预编译壳的来源与 CI」）；
 - 壳进程启用 DPI 感知，高 DPI 屏幕下窗口坐标 / 渲染 / 鼠标自动化定位一致，内容更清晰；
 - `freedom config set` 兼容双引号配置写法；依赖变更检测改用 `package-lock.json` 作基准。
 
@@ -127,7 +135,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（Apple Silicon）/ linux runner 上分别编译真实壳并上传到 GitHub Release，供 `freedom shell download` 拉取（Intel Mac 已不支持，见 `nativePlatform()` 的明确报错）。发布新版本时：先 `npm publish`，再创建同名 GitHub Release，手动触发 `build-shell` workflow（或直接发 Release 自动触发）即自动补齐各平台壳资产。
+**预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。自 v1.13.0 起由仓库 `.github/workflows/build.yml` 统一承担：推送 `vX.Y.Z` tag → 三平台 runner 编译通用壳 → `release` job 自动创建 GitHub Release 并上传资产 `freedom-shell-<plat>`，供 `freedom shell download` 按「`v<包版本>` tag + 同名资产」拉取（Intel Mac 已不支持，见 `nativePlatform()` 的明确报错）。发版顺序：先推 GitHub tag、等 Release 资产就绪，再 `npm publish` 同版本——保证 shell 下载默认源始终可用（紧急时可设 `FREEDOM_SHELL_TAG` 指向既有 tag）。
 
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 

package/lib/build.js

@@ -434,7 +434,7 @@ function appVersionFromPkg(dir) {
   }
 }
 
-// 渲染 resources/config.json（与壳 configfile.go 的 runtimeConfigFile 字段对齐）
+// 渲染 resources/config.json（与壳 resources.go 的 runtimeConfigFile 字段对齐）
 function renderConfigJSON(cfg, name) {
   const obj = {
     name,

package/lib/security.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// 安全加固模块（v1.13.10）
+// 安全加固模块（v1.13.0）
 //
 // 为 freedom build 提供两种安全模式：
 //   - basic（简单模式）：资源压缩 + 壳剥离符号建议，阻止"随手打开 resources/
@@ -16,7 +16,7 @@
 // 提取主密钥并复现派生算法"。真正"每应用唯一密钥"需要每应用独立编译壳
 // （破坏通用壳 + 零工具链架构），不在本模式范围内。
 //
-// ⚠️ 跨语言同步点：本文件与 templates/go/pkg/freedom/security.go 必须保持
+// ⚠️ 跨语言同步点：本文件与 templates/go/pkg/freedom/security.go（= 仓库根 security.go）必须保持
 //    MASTER_KEY / DERIVE_SALT / PBKDF2_ITER / KEY_LEN / APP_BIN_MAGIC
 //    以及加密算法（aes-256-ctr + hmac-sha256）完全一致。
 //    修改任一侧必须同步另一侧，否则 build 出的加密资源壳无法解密。

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.12.18",
+  "version": "1.13.1",
   "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YUfeng12TA/freedom.git"
+  },
   "keywords": [
     "desktop",
     "webview",

package/templates/go/go.mod

@@ -1,11 +1,5 @@
 module freedom-cli-shell
 
-go 1.22
+go 1.26.5
 
 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

package/templates/go/go.sum

@@ -1,2 +1,2 @@
-golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
-golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6 h1:VQpB2SpK88C6B5lPHTuSZKb2Qee1QWwiFlC5CKY4AW0=
+github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6/go.mod h1:yE65LFCeWf4kyWD5re+h4XNvOHJEXOCOuJZ4v8l5sgk=

package/templates/go/main.go

@@ -1,13 +1,27 @@
+// Freedom 通用壳源码模板（templates/go）。
+//
+// pkg/freedom 为框架源码快照（与 npm 包版本同步发布）；main 是预编译通用壳入口：
+// 应用内容全部来自 exe 同目录 resources/（CLI build 写入 index.html / config.json /
+// app.bin），运行时由框架 resources.go 覆盖到实际配置。
+//
+// 用途：`freedom shell build <plat>` 在本目录编译对应平台壳二进制（需 Go 工具链，
+// webview_go 依赖系统 WebView 框架，仅能编本机平台）；日常打包走
+// 包内 shell/<plat>/ 或 GitHub Releases 下载，无需本模板。
 package main
 
-import "freedom-cli-shell/pkg/freedom"
+import (
+	"flag"
+	"fmt"
+
+	"freedom-cli-shell/pkg/freedom"
+)
 
-// main 是 Freedom 壳层应用入口。
-// 窗口与标题栏配置来自 build 阶段生成的 gen_config.go（appConfig），
-// 前端页面运行时从 exe 同目录 resources/index.html 加载（build 阶段由 CLI
-// 把打包后的 index.html 与 config.json 写入该目录，壳 SetHtml 内存加载、不占端口）。
 func main() {
-	cfg := appConfig()
-	app := freedom.New(cfg)
-	app.Run()
+	showVersion := flag.Bool("version", false, "打印壳版本号并退出")
+	flag.Parse()
+	if *showVersion {
+		fmt.Println(freedom.Version)
+		return
+	}
+	freedom.New(freedom.Config{}).Run()
 }

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

@@ -2,7 +2,6 @@
 
 package freedom
 
-// 反调试（非 Windows 平台空实现）。
-// macOS/Linux 的调试器检测（ptrace / task_for_pid 等）依赖平台特定 API，
-// 本版本不做；如需加强可在对应平台文件扩展。
+// 反调试（非 Windows 平台空实现）。macOS/Linux 的调试器检测依赖
+// ptrace / task_for_pid 等平台特定 API，本版本不做；如需加强在对应平台文件扩展。
 func antiDebugCheck() {}

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

@@ -2,9 +2,9 @@
 
 package freedom
 
-// 反调试（Windows 实现）：high 安全模式下调用。
-// 检测常见用户态调试器，发现时静默退出，防止攻击者在调试器下
-// 单步追踪资源解密 / 密钥派生逻辑。
+// 反调试（Windows 实现）：high 安全模式下由 Run() 调用。
+// 检测常见调试器，命中时静默退出，防止攻击者在调试器下单步追踪
+// 资源解密 / 密钥派生逻辑。
 
 import (
 	"os"
@@ -13,27 +13,25 @@ import (
 )
 
 var (
-	kernel32dbg                      = syscall.NewLazyDLL("kernel32.dll")
-	procIsDebuggerPresent            = kernel32dbg.NewProc("IsDebuggerPresent")
-	procCheckRemoteDebuggerPresent   = kernel32dbg.NewProc("CheckRemoteDebuggerPresent")
+	kernel32AntiDebug              = syscall.NewLazyDLL("kernel32.dll")
+	procIsDebuggerPresent          = kernel32AntiDebug.NewProc("IsDebuggerPresent")
+	procCheckRemoteDebuggerPresent = kernel32AntiDebug.NewProc("CheckRemoteDebuggerPresent")
 )
 
 // antiDebugCheck 检测调试器；发现则立即退出进程（退出码 77，无提示）。
-// 仅在 high 安全模式启用时由 freedom.go Run() 调用。
 func antiDebugCheck() {
 	if isBeingDebugged() {
 		os.Exit(77)
 	}
 }
 
-// isBeingDebugged 同时检测本地调试器（IsDebuggerPresent）与远程/内核调试器
-// （CheckRemoteDebuggerPresent），任一命中即认为正在被调试。
+// isBeingDebugged 同时检测用户态调试器（IsDebuggerPresent）与远程/内核调试器
+// （CheckRemoteDebuggerPresent）。hProcess 用 GetCurrentProcess 伪句柄（-1）。
 func isBeingDebugged() bool {
-	r, _, _ := procIsDebuggerPresent.Call()
-	if r != 0 {
+	if r, _, _ := procIsDebuggerPresent.Call(); r != 0 {
 		return true
 	}
 	var present int32
-	procCheckRemoteDebuggerPresent.Call(uintptr(0), uintptr(unsafe.Pointer(&present)))
+	procCheckRemoteDebuggerPresent.Call(^uintptr(0), uintptr(unsafe.Pointer(&present)))
 	return present != 0
 }

package/templates/go/pkg/freedom/assets/{index.html → default.html}

@@ -45,7 +45,7 @@
     font-size: 13px;
   }
 
-  /* 无边框模式：前端自绘标题栏（frameless 时显示） */
+  /* 无边框模式：前端自绘标题栏（hidden / frameless 时显示） */
   .titlebar {
     display: none;
     height: 36px;

package/templates/go/pkg/freedom/assets/freedom.js

@@ -11,13 +11,27 @@
 
   var listeners = {};
 
+  // M1 异步桥接协议：__freedom_bridge(id, method, paramsJson) 只做投递（ack），
+  // Go 侧完成后经 freedom.__resolve(id, {ok,result|error}) 回写本表登记的 Promise。
+  var callSeq = 0;
+  var pendingCalls = {};
+
   function call(method) {
     var params = Array.prototype.slice.call(arguments, 1);
     var bridge = getBridge();
     if (!bridge) {
       return Promise.reject(new Error('[freedom] 未检测到原生桥接（__freedom_bridge），当前不在桌面壳内运行。'));
     }
-    return bridge(method, JSON.stringify(params));
+    var id = ++callSeq;
+    return new Promise(function (resolve, reject) {
+      pendingCalls[id] = { resolve: resolve, reject: reject };
+      Promise.resolve(bridge(id, method, JSON.stringify(params))).catch(function (e) {
+        if (pendingCalls[id]) {
+          delete pendingCalls[id];
+          reject(e);
+        }
+      });
+    });
   }
 
   function on(event, cb) {
@@ -32,6 +46,18 @@
     if (i >= 0) l.splice(i, 1);
   }
 
+  // 一次性订阅：触发一次后自动退订（对标 Tauri listen+unlisten）。
+  // 注意：必须用"注册进数组的那个 wrapper"退订——on() 返回的是 unlisten
+  // 闭包而非回调本身，拿它去 off() 删不掉监听器（旧 bug，tests/sdk-surface 锁定）。
+  function once(event, cb) {
+    if (typeof cb !== 'function') return function () {};
+    var fn = function (data) {
+      off(event, fn);
+      cb(data);
+    };
+    return on(event, fn);
+  }
+
   // 后端通过 app.Emit(event, data) 触发（Eval 调用本函数）。
   function emit(event, data) {
     var l = listeners[event] || [];
@@ -40,12 +66,24 @@
     }
   }
 
+  // Go 侧异步回写入口（dispatch.go 的 resolveJS 经 Eval 调用）。
+  // 拒绝值保持旧契约：webview_go 时代 catch 到的是错误消息字符串。
+  function resolveCall(id, env) {
+    var p = pendingCalls[id];
+    if (!p) return; // 页面已重载/回写迟到：静默丢弃
+    delete pendingCalls[id];
+    if (env && env.ok) p.resolve(env.result);
+    else p.reject((env && env.error) || '[freedom] call failed');
+  }
+
   var freedom = {
     call: call,
     invoke: call,
     on: on,
     off: off,
+    once: once,
     emit: emit,
+    __resolve: resolveCall,
     window: {
       // 窗口控制（无边框/隐藏标题栏模式下前端自绘按钮使用）。
       // 全部经桥接调用原生实现，返回 Promise。
@@ -53,12 +91,168 @@
       maximize: function () { return windowAction('maximize'); },
       unmaximize: function () { return windowAction('unmaximize'); },
       toggleMaximize: function () { return windowAction('toggleMaximize'); },
-      close: function () { return windowAction('close'); },
+      // close(force)：force=true 时绕过 interceptClose 拦截直接关闭。
+      close: function (force) { return windowAction('close', { force: !!force }); },
       isMaximized: function () { return windowAction('isMaximized'); },
       isFrameless: function () { return windowAction('isFrameless'); },
+      // —— W1 对标 Tauri：位置 / 尺寸（物理像素）——
+      setPosition: function (x, y) { return windowAction('setPosition', { x: x, y: y }); },
+      setSize: function (width, height) { return windowAction('setSize', { width: width, height: height }); },
+      getPosition: function () { return windowAction('getPosition'); },
+      getSize: function () { return windowAction('getSize'); },
+      innerSize: function () { return windowAction('innerSize'); },
+      center: function () { return windowAction('center'); },
+      setTitle: function (title) { return windowAction('setTitle', { title: String(title) }); },
+      // —— 可见性 / 层级 / 焦点 ——
+      show: function () { return windowAction('show'); },
+      hide: function () { return windowAction('hide'); },
+      focus: function () { return windowAction('focus'); },
+      isVisible: function () { return windowAction('isVisible'); },
+      isFocused: function () { return windowAction('isFocused'); },
+      isMinimized: function () { return windowAction('isMinimized'); },
+      setAlwaysOnTop: function (on) { return windowAction('setAlwaysOnTop', { on: !!on }); },
+      setSkipTaskbar: function (on) { return windowAction('setSkipTaskbar', { on: !!on }); },
+      // —— 行为开关 ——
+      setResizable: function (on) { return windowAction('setResizable', { on: !!on }); },
+      setMaximizable: function (on) { return windowAction('setMaximizable', { on: !!on }); },
+      setMinimizable: function (on) { return windowAction('setMinimizable', { on: !!on }); },
+      // —— 全屏 / 关闭拦截 ——
+      setFullscreen: function (on) { return windowAction('setFullscreen', { on: !!on }); },
+      enterFullscreen: function () { return windowAction('setFullscreen', { on: true }); },
+      exitFullscreen: function () { return windowAction('setFullscreen', { on: false }); },
+      isFullscreen: function () { return windowAction('isFullscreen'); },
+      // 拦截系统/按钮关闭：开启后关闭动作变为 window.closeRequested 事件，
+      // 前端处理后以 close(true) 放行或不做操作保持窗口存活。
+      interceptClose: function (on) { return windowAction('interceptClose', { on: !!on }); },
+      // 聚合信息：title/outerX/outerY/outerWidth/outerHeight/innerWidth/innerHeight/
+      // scaleFactor/visible/focused/maximized/minimized/alwaysOnTop/skipTaskbar/frameless/fullscreen。
+      getInfo: function () { return windowAction('getInfo'); },
+      // 显示器列表（经 sys 桥接）：[{x,y,width,height,workX,workY,workWidth,workHeight,scaleFactor,isPrimary}]
+      monitors: function () { return sysCall('window.monitors', {}); },
+      // 窗口视觉效果（Win11）：backdrop: auto|none|solid|mica|acrylic；corner: round|roundSmall|square|default；borderColor: 0x00BBGGRR
+      setBackdrop: function (mode) { return sysCall('window.backdrop', { mode: mode }); },
+      setCorner: function (mode) { return sysCall('window.corner', { mode: mode }); },
+      setBorderColor: function (color) { return sysCall('window.borderColor', { color: color }); },
+      // —— M2 多窗口 ——
+      // id()：本窗口标识（'main' 或 'w1'…）；create({title,width,height,center,url,html})：
+      // 异步拉起次级窗口返回 {id}；list() 全部存活窗口；closeWindow/focusWindow(id)。
+      // create 的页面来源三选一：url（外链）> html（内联字符串）> 复制主页面——
+      // 主页面含开窗脚本时务必给 url 或 html，避免级联。
+      // 注意：次级窗口无 sys/tray 桥，托盘/热键/状态记忆等平台单例只挂主窗口；
+      // 次级窗口里 window.close() 关闭的是它自己。
+      id: function () { return windowAction('id'); },
+      list: function () { return windowAction('list'); },
+      create: function (opts) { return windowAction('create', opts || {}); },
+      closeWindow: function (id) { return windowAction('closeWindow', { id: id }); },
+      focusWindow: function (id) { return windowAction('focusWindow', { id: id }); },
+    },
+    // ---- W2 系统集成命名空间（均经 __freedom_sys / __freedom_tray 桥接）----
+    sys: sysCall,
+    clipboard: {
+      readText: function () { return sysCall('clipboard.read', {}); },
+      writeText: function (text) { return sysCall('clipboard.write', { text: String(text) }); },
+    },
+    shell: {
+      // 用系统默认程序打开 URL/文件（openExternal）。
+      open: function (target) { return sysCall('shell.open', { target: String(target) }); },
+    },
+    notification: {
+      show: function (title, body) { return sysCall('notification.show', { title: String(title), body: String(body || '') }); },
+    },
+    shortcut: {
+      // combo 形如 "ctrl+alt+k"；触发时收到事件 freedom.on('shortcut.triggered', ({id}) => ...)。
+      register: function (id, combo) { return sysCall('shortcut.register', { id: id, combo: combo }); },
+      unregister: function (id) { return sysCall('shortcut.unregister', { id: id }); },
+      list: function () { return sysCall('shortcut.list', {}); },
+    },
+    autostart: {
+      isEnabled: function (name) { return sysCall('autostart.get', { name: name || '' }); },
+      set: function (enabled, opts) { return sysCall('autostart.set', { name: (opts && opts.name) || '', enabled: !!enabled, args: (opts && opts.args) || '' }); },
+      enable: function (opts) { return this.set(true, opts); },
+      disable: function (opts) { return this.set(false, opts); },
+    },
+    protocol: {
+      // URL Scheme 注册（deep link）；拉起参数经 'app.secondInstance' 事件或 app.launchArgs() 获取。
+      register: function (scheme, displayName) { return sysCall('protocol.register', { scheme: scheme, name: displayName || '' }); },
+      unregister: function (scheme) { return sysCall('protocol.unregister', { scheme: scheme }); },
+    },
+    app: {
+      launchArgs: function () { return sysCall('app.launchArgs', {}); },
+    },
+    // ---- W3 数据层（对标 Tauri path / store / os / process）----
+    // kind ∈ config|data|cache|temp|home|exe；name 省略时用 AppID（目录名已消毒）。
+    path: function (kind, name) { return sysCall('path.get', { kind: kind, name: name || '' }); },
+    store: {
+      // 命名 JSON KV，落盘 <dataDir>/<name>.store.json，set 即持久化。
+      load: function (name) { return sysCall('store.load', { store: name || '' }); },
+      get: function (key, name) { return sysCall('store.get', { store: name || '', key: key }); },
+      set: function (key, value, name) { return sysCall('store.set', { store: name || '', key: key, value: value }); },
+      delete: function (key, name) { return sysCall('store.delete', { store: name || '', key: key }); },
+      keys: function (name) { return sysCall('store.keys', { store: name || '' }); },
+    },
+    os: {
+      info: function () { return sysCall('os.info', {}); }, // {platform,arch,hostname,osVersion,goVersion,numCPU}
+    },
+    process: {
+      id: function () { return sysCall('process.id', {}); },
+      exit: function (code) { return sysCall('process.exit', { code: code || 0 }); },
+      restart: function () { return sysCall('process.restart', {}); }, // 拉起新实例后退出的安全重启
+    },
+    // ---- G4 自动更新（对标 Tauri updater）----
+    // 检查/安装是异步长任务：调用只发起，结果经事件回推——
+    //   'update.available'({version,url,sha256,notes}) / 'update.upToDate'({current})
+    //   / 'update.installed'({version,restartRequired}) / 'update.error'({message})
+    // install 只接受 check 时已通过 ed25519 验签的缓存条目；换装后需 process.restart 生效。
+    update: {
+      check: function () { return sysCall('update.check', {}); },
+      install: function () { return sysCall('update.install', {}); },
+      pending: function () { return sysCall('update.pending', {}); },
+      onAvailable: function (cb) { return on('update.available', cb); },
+      onUpToDate: function (cb) { return on('update.upToDate', cb); },
+      onInstalled: function (cb) { return on('update.installed', cb); },
+      onError: function (cb) { return on('update.error', cb); },
+    },
+    taskbar: {
+      setProgress: function (value) { return sysCall('taskbar.progress', { value: value }); },
+      setState: function (state) { return sysCall('taskbar.state', { state: state }); }, // normal|paused|error|indeterminate
+      clear: function () { return sysCall('taskbar.clear', {}); },
+      setOverlay: function (iconDataURL) { return sysCall('taskbar.overlay', { icon: iconDataURL }); },
+      clearOverlay: function () { return sysCall('taskbar.clearOverlay', {}); },
+    },
+    dialog: {
+      message: function (opts) { return sysCall('dialog.message', opts || {}); },
+      open: function (opts) { return sysCall('dialog.open', opts || {}); },
+      save: function (opts) { return sysCall('dialog.save', opts || {}); },
+    },
+    tray: {
+      // create({icon: dataURL, tooltip})；事件：tray:click / tray:double-click / tray:menu({id})。
+      create: function (opts) { return trayCall('tray.create', opts || {}); },
+      destroy: function () { return trayCall('tray.destroy', {}); },
+      setTooltip: function (text) { return trayCall('tray.tooltip', { tooltip: text }); },
+      setMenu: function (items) { return trayCall('tray.menu', { items: items }); },
+    },
+    menu: {
+      // 原生菜单栏（挂主窗口）：items 同 tray.setMenu 结构；点击走 'tray:menu' 事件。
+      set: function (items) { return trayCall('menu.set', { items: items }); },
     },
   };
 
+  function trayCall(method, args) {
+    if (typeof window.__freedom_tray !== 'function') {
+      return Promise.reject(new Error('[freedom] 未检测到托盘桥接。'));
+    }
+    return window.__freedom_tray(method, JSON.stringify(args || {}));
+  }
+
+  // sys 桥接：原生系统能力（taskbar.* / window.* / dialog.*）。
+  // W5 会扩展为 freedom.sys 命名空间，先行提供内部包装。
+  function sysCall(method, args) {
+    if (typeof window.__freedom_sys !== 'function') {
+      return Promise.reject(new Error('[freedom] 未检测到原生系统能力桥接。'));
+    }
+    return window.__freedom_sys(method, JSON.stringify(args || {}));
+  }
+
   // 前端自绘按钮的便捷绑定：把按钮 DOM 接到窗口控制。
   // freedom.window.bindButtons({ min: '#minBtn', max: '#maxBtn', close: '#closeBtn' })
   freedom.window.bindButtons = function (sel) {
@@ -75,12 +269,13 @@
     if (close) close.addEventListener('click', function () { self.close().catch(ignoreErr); });
   };
 
-  function windowAction(action) {
-    // __freedom_window 是 webview_go Bind 注入的异步全局函数（返回 Promise）
+  function windowAction(action, args) {
+    // __freedom_window 是 webview_go Bind 注入的异步全局函数（返回 Promise）。
+    // Go 侧签名为 (action, paramsJSON)，paramsJSON 恒为 JSON object 字符串。
     if (typeof window.__freedom_window !== 'function') {
       return Promise.reject(new Error('[freedom] 未检测到原生窗口控制桥接。'));
     }
-    return window.__freedom_window(action);
+    return window.__freedom_window(action, JSON.stringify(args || {}));
   }
 
   Object.defineProperty(freedom, 'isDesktop', {

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

@@ -2,20 +2,18 @@ package freedom
 
 import _ "embed"
 
-// jsSDK 是注入到每个前端页面的 Freedom 前端 SDK，暴露 window.freedom 全局对象。
-// 用法见 assets/freedom.js 顶部注释。
+// jsSDK 是注入到每个前端页面的 Freedom 前端 SDK。
+// 它暴露 window.freedom 全局对象：
 //
+//	window.freedom.call(method, ...args) -> Promise   // 调用后端方法
+//	window.freedom.invoke(...)                        // call 的别名
+//	window.freedom.on(event, cb) -> unsubscribe       // 订阅后端事件
+//	window.freedom.off(event, cb)                     // 取消订阅
+//	window.freedom.emit(event, data)                  // 应用内事件广播（后端 Eval 亦使用）
+//
+// bridge 由 go-webview2 的 Bind 机制注册，返回 Promise，Go 侧自动 JSON 编解码。
 //go:embed assets/freedom.js
 var jsSDK string
 
-// indexHTML 是内置的默认占位页。
-//
-// 预编译通用壳不嵌入应用专属页面：应用 HTML 来自 exe 同目录 resources/index.html
-//（freedom CLI build 时写入，见 resolveHTML 的加载优先级）。仅当外部页面缺失时
-// 回退到本占位页，保证"直接运行壳"也有可见 UI。
-//
-//go:embed assets/index.html
-var indexHTML string
-
-// defaultHTML 兼容框架默认占位页语义：无自定义前端时回退到 indexHTML。
-var defaultHTML = indexHTML
+//go:embed assets/default.html
+var defaultHTML string

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

@@ -0,0 +1,11 @@
+//go:build !windows
+
+package freedom
+
+import "fmt"
+
+// authenticodeCheck 非 Windows 平台不提供 Authenticode 校验能力。
+// RequireSignature 开启时更新流会因此显式失败——静默跳过等于谎报已验签。
+func authenticodeCheck(path string) error {
+	return fmt.Errorf("freedom: Authenticode 校验仅支持 Windows（当前平台无法完成 RequireSignature 验证）")
+}

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

@@ -0,0 +1,87 @@
+//go:build windows
+
+package freedom
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// M6 Authenticode 复核（wintrust!WinVerifyTrust）：sha256 之外的可选发布者身份
+// 二级信号——主信任锚仍是 manifest 的 ed25519 验签，此项属纵深防御
+// （持哈希而不知签名私钥的被攻陷源会被拒）。
+// 布局依 wintrust.h：WINTRUST_DATA / WINTRUST_FILE_INFO 字段序与自然对齐。
+
+type wintrustFileInfo struct {
+	cbStruct       uint32
+	pcwszFilePath  *uint16
+	hFile          uintptr
+	pgKnownSubject *syscall.GUID
+}
+
+type wintrustData struct {
+	cbStruct            uint32
+	pPolicyCallbackData uintptr
+	pSIPClientData      uintptr
+	dwUIChoice          uint32
+	fdwRevocationChecks uint32
+	dwUnionChoice       uint32
+	pFile               *wintrustFileInfo
+	dwStateAction       uint32
+	hWVTStateData       uintptr
+	pwszURLReference    *uint16
+	dwProvFlags         uint32
+	dwUIContext         uint32
+}
+
+const (
+	wtdUINone        = 2          // WTD_UI_NONE：全程不弹 UI
+	wtdRevokeNone    = 0x00000000 // 不检索吊销信息
+	wtdChoiceFile    = 1          // WTD_CHOICE_FILE
+	wtdRevCheckNone  = 0x00000010 // WTD_REVOCATION_CHECK_NONE（provFlags）
+	wtdStateClose    = 0x00000002 // WTD_STATEACTION_CLOSE
+	wtdUIContextExec = 0          // WTD_UICONTEXT_EXECUTE
+)
+
+var (
+	wintrustDLL        = syscall.NewLazyDLL("wintrust.dll")
+	procWinVerifyTrust = wintrustDLL.NewProc("WinVerifyTrust")
+	// WINTRUST_ACTION_GENERIC_VERIFY_V2 {00AAC56B-CD44-11d0-8CC2-006C9B2F61C7}
+	wtdActionGenericVerify = syscall.GUID{
+		Data1: 0x00AAC56B, Data2: 0xCD44, Data3: 0x11D0,
+		Data4: [8]byte{0x8C, 0xC2, 0x00, 0x6C, 0x9B, 0x2F, 0x61, 0xC7},
+	}
+)
+
+// authenticodeCheck 校验 PE 数字签名链。离线确定性由 WTD_REVOKE_NONE +
+// WTD_REVOCATION_CHECK_NONE 保证（吊销检查需外网，且主信任已由 ed25519 覆盖）。
+func authenticodeCheck(path string) error {
+	p, err := syscall.UTF16PtrFromString(path)
+	if err != nil {
+		return fmt.Errorf("freedom: 签名校验路径非法: %w", err)
+	}
+	fi := wintrustFileInfo{cbStruct: uint32(unsafe.Sizeof(wintrustFileInfo{})), pcwszFilePath: p}
+	wd := wintrustData{
+		cbStruct:            uint32(unsafe.Sizeof(wintrustData{})),
+		dwUIChoice:          wtdUINone,
+		fdwRevocationChecks: wtdRevokeNone,
+		dwUnionChoice:       wtdChoiceFile,
+		pFile:               &fi,
+		dwProvFlags:         wtdRevCheckNone,
+		dwUIContext:         wtdUIContextExec,
+	}
+	r, _, e := procWinVerifyTrust.Call(0,
+		uintptr(unsafe.Pointer(&wtdActionGenericVerify)),
+		uintptr(unsafe.Pointer(&wd)))
+	if wd.hWVTStateData != 0 { // 释放 verify 缓存的 provider 数据
+		wd.dwStateAction = wtdStateClose
+		procWinVerifyTrust.Call(0,
+			uintptr(unsafe.Pointer(&wtdActionGenericVerify)),
+			uintptr(unsafe.Pointer(&wd)))
+	}
+	if r != 0 {
+		return fmt.Errorf("freedom: Authenticode 校验未通过 (wintrust=0x%08X): %w", uint32(r), e)
+	}
+	return nil
+}