@yufengtadian/freedom-cli 1.12.18 → 1.13.0

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

@@ -0,0 +1,257 @@
+//go:build windows
+
+package freedom
+
+import (
+	"fmt"
+	"runtime"
+	"sync"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+// 辅助消息窗口（W2）：独立线程上的隐藏窗口，承载全局热键（WM_HOTKEY）、
+// 单实例参数转发（WM_COPYDATA）等需要消息泵的能力。
+// 与托盘隐藏窗不同：托盘窗口依赖主 UI 线程泵消息且仅在 tray.create 后存在；
+// 本窗口在首次需要时创建、自带 GetMessage 循环，进程存续期间常驻。
+
+const (
+	wmDestroy  = 0x0002
+	wmHotkey   = 0x0312
+	wmCopyData = 0x004A
+)
+
+type copyDataStruct struct {
+	DwData uintptr
+	CbData uint32
+	_      uint32 // amd64 对齐
+	LpData uintptr
+}
+
+// validCopyData 入站 WM_COPYDATA 守卫：魔数、非空、指针有效、负载 ≤64KB。
+func validCopyData(dwData uintptr, cbData uint32, lpData uintptr) bool {
+	return dwData == forwardWindowMagic && cbData > 0 && cbData <= 64*1024 && lpData != 0
+}
+
+type msgWindow struct {
+	mu        sync.Mutex
+	hwnd      uintptr
+	ready     chan struct{}
+	created   bool
+	hotkeys   map[string]uint32 // 前端 id → 热键数值 id
+	nextHKID  uint32
+	onHotkey  func(id string)
+	onData    func(payload []byte)
+}
+
+var (
+	msgWindowOnce sync.Once
+	msgWindowInst *msgWindow
+	msgWndProcCB  uintptr
+)
+
+// ensureMsgWindow 惰性创建消息窗口线程并等待窗口就绪。
+// title 作为窗口标题：单实例模式以 appID 为标题，供 FindWindowW 定位主实例。
+func ensureMsgWindow(title string) (*msgWindow, error) {
+	var initErr error
+	msgWindowOnce.Do(func() {
+		mw := &msgWindow{
+			ready:   make(chan struct{}),
+			hotkeys: map[string]uint32{},
+		}
+		msgWindowInst = mw
+		go mw.runLoop(title)
+		select {
+		case <-mw.ready:
+		case <-time.After(3 * time.Second):
+			initErr = fmt.Errorf("freedom: 消息窗口创建超时")
+		}
+	})
+	if initErr != nil {
+		return nil, initErr
+	}
+	if msgWindowInst == nil {
+		return nil, fmt.Errorf("freedom: 消息窗口不可用")
+	}
+	msgWindowInst.mu.Lock()
+	created := msgWindowInst.created
+	msgWindowInst.mu.Unlock()
+	if !created {
+		return nil, fmt.Errorf("freedom: 消息窗口不可用")
+	}
+	return msgWindowInst, nil
+}
+
+// setTitle 更新窗口标题（单实例以 appID 为标题供 FindWindowW 定位；
+// 窗口可能先由热键等能力以默认标题创建，此时需纠正）。
+func (mw *msgWindow) setTitle(title string) {
+	mw.mu.Lock()
+	hwnd := mw.hwnd
+	mw.mu.Unlock()
+	if hwnd == 0 || title == "" {
+		return
+	}
+	if t, err := syscall.UTF16PtrFromString(title); err == nil {
+		procSetWindowText.Call(hwnd, uintptr(unsafe.Pointer(t)))
+	}
+}
+
+func msgWndProc(hwnd uintptr, msg uint32, wParam, lParam uintptr) uintptr {
+	mw := msgWindowInst
+	switch msg {
+	case wmHotkey:
+		if mw != nil {
+			mw.mu.Lock()
+			var key string
+			for id, hid := range mw.hotkeys {
+				if hid == uint32(wParam) {
+					key = id
+					break
+				}
+			}
+			cb := mw.onHotkey
+			mw.mu.Unlock()
+			if cb != nil && key != "" {
+				go cb(key)
+			}
+		}
+		return 0
+	case wmCopyData:
+		if mw != nil && lParam != 0 {
+			cds := (*copyDataStruct)(unsafe.Pointer(lParam))
+			// 校验魔数与长度：任意进程都可向本窗口投 COPYDATA，
+			// 未验 DwData 会把伪造内存当 JSON 解析，未限 CbData 可放大内存占用。
+			if validCopyData(cds.DwData, cds.CbData, cds.LpData) {
+				buf := make([]byte, cds.CbData)
+				copy(buf, unsafe.Slice((*byte)(unsafe.Pointer(cds.LpData)), cds.CbData))
+				mw.mu.Lock()
+				cb := mw.onData
+				mw.mu.Unlock()
+				if cb != nil {
+					go cb(buf)
+				}
+			}
+		}
+		return 0
+	case wmDestroy:
+		procPostQuitMessage.Call(0)
+	}
+	r, _, _ := procDefWindowProcW.Call(hwnd, uintptr(msg), wParam, lParam)
+	return r
+}
+
+// runLoop 在锁定线程上创建隐藏窗口并泵消息（窗口随进程存活，不销毁）。
+func (mw *msgWindow) runLoop(title string) {
+	runtime.LockOSThread()
+	className, _ := syscall.UTF16PtrFromString(siWndClass)
+	windowTitle := className
+	if title != "" {
+		t, err := syscall.UTF16PtrFromString(title)
+		if err == nil {
+			windowTitle = t
+		}
+	}
+	if msgWndProcCB == 0 {
+		msgWndProcCB = syscall.NewCallback(msgWndProc)
+	}
+	hInst := uintptr(0)
+	if m, _, _ := procGetModuleHandle.Call(0); m != 0 {
+		hInst = m
+	}
+	wc := wndClassExW{
+		CbSize:        uint32(unsafe.Sizeof(wndClassExW{})),
+		LpfnWndProc:   msgWndProcCB,
+		HInstance:     hInst,
+		LpszClassName: className,
+	}
+	procRegisterClassExW.Call(uintptr(unsafe.Pointer(&wc))) // 重复注册失败可忽略
+	hwnd, _, _ := procCreateWindowExW.Call(
+		0, uintptr(unsafe.Pointer(className)), uintptr(unsafe.Pointer(windowTitle)),
+		0, 0, 0, 0, 0, 0, 0, hInst, 0)
+	mw.mu.Lock()
+	mw.hwnd = hwnd
+	mw.created = hwnd != 0
+	mw.mu.Unlock()
+	close(mw.ready)
+	if hwnd == 0 {
+		return
+	}
+	// 标准消息循环：WM_HOTKEY / WM_COPYDATA 在此派发。
+	var msg struct {
+		HWnd    uintptr
+		Message uint32
+		WParam  uintptr
+		LParam  uintptr
+		Time    uint32
+		Pt      point
+	}
+	for {
+		r, _, _ := procGetMessageW.Call(uintptr(unsafe.Pointer(&msg)), 0, 0, 0)
+		if int32(r) == 0 || r == ^uintptr(0) { // WM_QUIT 或错误 → 退出
+			break
+		}
+		procTranslateMessage.Call(uintptr(unsafe.Pointer(&msg)))
+		procDispatchMessageW.Call(uintptr(unsafe.Pointer(&msg)))
+	}
+}
+
+// registerHotkey 注册全局热键（win/chord 组合，见 hotkeyKeys 表）。
+func (mw *msgWindow) registerHotkey(id, combo string) error {
+	mods, vk, err := parseHotkey(combo)
+	if err != nil {
+		return err
+	}
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	if _, dup := mw.hotkeys[id]; dup {
+		return fmt.Errorf("freedom: 热键 %q 已注册", id)
+	}
+	if mw.nextHKID == 0 {
+		mw.nextHKID = 0x4651 // "FQ"
+	}
+	hid := mw.nextHKID
+	mw.nextHKID++
+	r, _, e := procRegisterHotKey.Call(mw.hwnd, uintptr(hid), uintptr(mods), uintptr(vk))
+	if r == 0 {
+		return fmt.Errorf("freedom: RegisterHotKey(%s) 失败: %w", combo, e)
+	}
+	mw.hotkeys[id] = hid
+	return nil
+}
+
+func (mw *msgWindow) unregisterHotkey(id string) error {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	hid, ok := mw.hotkeys[id]
+	if !ok {
+		return fmt.Errorf("freedom: 热键 %q 未注册", id)
+	}
+	procUnregisterHotKey.Call(mw.hwnd, uintptr(hid))
+	delete(mw.hotkeys, id)
+	return nil
+}
+
+func (mw *msgWindow) hotkeyIDs() []string {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	out := make([]string, 0, len(mw.hotkeys))
+	for id := range mw.hotkeys {
+		out = append(out, id)
+	}
+	return out
+}
+
+// setOnHotkey 注册热键触发回调（WM_HOTKEY → 前端事件）。
+func (mw *msgWindow) setOnHotkey(fn func(id string)) {
+	mw.mu.Lock()
+	mw.onHotkey = fn
+	mw.mu.Unlock()
+}
+
+// setOnData 注册 WM_COPYDATA 负载回调（单实例参数转发）。
+func (mw *msgWindow) setOnData(fn func(payload []byte)) {
+	mw.mu.Lock()
+	mw.onData = fn
+	mw.mu.Unlock()
+}

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

@@ -0,0 +1,15 @@
+//go:build !windows
+
+package freedom
+
+// osVersionString 在非 Windows 平台返回空串（osInfo.osVersion 缺省，前端可用 platform 字段兜底）。
+func osVersionString() string { return "" }
+
+// webview2RuntimeVersion 非 Windows 无 WebView2 Runtime 概念（渲染内核不同），恒为空。
+func webview2RuntimeVersion() string { return "" }
+
+// stateOnScreen 非 Windows 无显示器枚举实现，恒为 true（保存路径本身是 no-op）。
+func stateOnScreen(st WindowState) bool { return true }
+
+// persistWindowState 非 Windows 平台的窗口几何读取未实现，no-op。
+func (a *App) persistWindowState(hwnd uintptr, dir string) {}

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

@@ -0,0 +1,121 @@
+//go:build windows
+
+package freedom
+
+import (
+	"strings"
+	"syscall"
+	"unsafe"
+)
+
+// osVersionString 经 ntdll!RtlGetVersion 取真实 Windows 版本
+// （GetVersionExW 受 manifest 兼容性垫片影响会谎报，RtlGetVersion 不受影响）。
+func osVersionString() string {
+	ntdll := syscall.NewLazyDLL("ntdll.dll")
+	proc := ntdll.NewProc("RtlGetVersion")
+	if proc.Find() != nil {
+		return ""
+	}
+	type osVersionInfoExW struct {
+		_len              uint32
+		major, minor      uint32
+		build, platformID uint32
+		csd               [128]uint16
+	}
+	var v osVersionInfoExW
+	v._len = uint32(unsafe.Sizeof(v))
+	if st, _, _ := proc.Call(uintptr(unsafe.Pointer(&v))); st != 0 { // NT_SUCCESS
+		return ""
+	}
+	return "Windows " + itoa(int(v.major)) + "." + itoa(int(v.minor)) + " build " + itoa(int(v.build))
+}
+
+// ---- WebView2 Runtime 探测（M6 运行时引导回显）----
+
+// Edge Evergreen 客户端注册表项 GUID；HKCU 用户级安装优先，HKLM 系统级兜底。
+const (
+	hkeyLocalMachine = uintptr(0x80000002)
+	webview2CUKey    = `Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}`
+	webview2LMKey    = `SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}`
+)
+
+// normalizeWebView2Version 过滤占位值："N/A"（Edge 随 OS 镜像的 MSIX 占位）与空白视为未检出。
+func normalizeWebView2Version(pv string) string {
+	pv = strings.TrimSpace(pv)
+	if pv == "" || pv == "N/A" {
+		return ""
+	}
+	return pv
+}
+
+// webview2RuntimeVersion 返回系统 WebView2 Runtime 版本号（"120.0.2210.91" 风格），
+// 未安装/不可探测返回 ""。前端经 os.info.webview2Runtime 预检运行环境（对标
+// Tauri webview_install 的引导前探测——本框架不自动下载 Runtime，只回显）。
+func webview2RuntimeVersion() string {
+	for _, q := range []struct {
+		base uintptr
+		path string
+	}{{hkeyCurrentUser, webview2CUKey}, {hkeyLocalMachine, webview2LMKey}} {
+		hk, err := regOpen(q.base, q.path, keyRead)
+		if err != nil {
+			continue
+		}
+		v, found, err := regQuerySz(hk, "pv")
+		procRegCloseKey.Call(hk)
+		if err != nil || !found {
+			continue
+		}
+		if s := normalizeWebView2Version(v); s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	var b [24]byte
+	i := len(b)
+	for n > 0 {
+		i--
+		b[i] = byte('0' + n%10)
+		n /= 10
+	}
+	return string(b[i:])
+}
+
+// stateOnScreen 判断保存的坐标是否仍落在某个显示器范围内（含 8px 容差）。
+func stateOnScreen(st WindowState) bool {
+	for _, m := range listMonitors() {
+		if st.X >= m.X-8 && st.Y >= m.Y-8 &&
+			st.X < m.X+m.Width-8 && st.Y < m.Y+m.Height-8 {
+			return true
+		}
+	}
+	return false
+}
+
+// persistWindowState 把当前窗口几何写入状态文件（store.go 的 RememberWindowState）。
+// 全屏中跳过：存的应是全屏前的几何（进入全屏前的最后一次 ExitSizeMove 已落过盘），
+// 全屏矩形落盘会在下次启动还原成一个占满屏幕的普通窗口。
+func (a *App) persistWindowState(hwnd uintptr, dir string) {
+	a.wsMu.Lock()
+	defer a.wsMu.Unlock()
+	if v, ok := windowRuntimes.Load(hwnd); ok {
+		if v.(*windowRuntime).getFullscreen() {
+			return
+		}
+	}
+	r, err := getWindowRect(hwnd)
+	if err != nil {
+		return
+	}
+	st := WindowState{
+		X: int(r.left), Y: int(r.top),
+		Width: int(r.right - r.left), Height: int(r.bottom - r.top),
+		Maximized: isZoomed(hwnd),
+	}
+	_ = saveWindowState(dir, st)
+}

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

@@ -7,8 +7,8 @@ import (
 	"syscall"
 )
 
-// hideWindow 让后端子进程（即使自身是控制台程序）不弹出 cmd 黑窗。
-// GUI 子系统父进程拉起 console 子进程时，Windows 默认会为其新建控制台窗口，
+// hideWindow 让后端子进程（即便是控制台程序）不弹出 cmd 黑窗。
+// GUI 子系统拉起 console 子进程时，Windows 默认会为其新建控制台窗口，
 // 设置 HideWindow 可使其在后台静默运行。
 func hideWindow(cmd *exec.Cmd) {
 	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}

package/templates/go/pkg/freedom/{configfile.go → resources.go}

@@ -1,14 +1,15 @@
 package freedom
 
-// 运行时外部资源（resources/）加载逻辑。
+// 运行时外部资源（resources/）加载层——预编译通用壳（cmd/shell）与源码构建应用共用。
 //
-// 通用壳二进制（预编译）本身不嵌入任何应用专属的前端与配置；
-// 应用内容来自 exe 同目录的 resources/ 目录：
+// 通用壳二进制本身不嵌入任何应用专属的前端与配置；应用内容来自 exe 同目录的
+// resources/ 目录：
 //   resources/index.html    前端页面（CLI build 写入）
 //   resources/config.json   窗口与后端配置（CLI build 写入）
+//   resources/app.bin       high 安全模式加密容器（config+html，见 security.go）
 //
-// 外部资源缺失时静默回退：配置使用编译期/默认值，页面使用内置占位页。
-// 因此同一份壳二进制可以复用于任意应用，且打包时无需任何语言工具链。
+// 外部资源缺失时静默回退：配置使用编译期/默认值，页面使用 cfg.HTML 或内置占位页。
+// 同一份壳二进制可复用于任意应用，最终用户打包时无需任何语言工具链。
 
 import (
 	"encoding/json"
@@ -33,27 +34,6 @@ func secureFatal(err error) error {
 	return &secureFatalError{err: err}
 }
 
-// loadRuntimeConfig 读取 exe 同目录 resources/config.json，将命中的字段覆盖到应用配置。
-// 文件不存在时视为未配置（返回 nil，保持编译期/默认配置不变）；
-// 文件存在但读取/解析失败时返回具体错误，由调用方打印告警，避免用户手改配置出错时无感知。
-func (a *App) loadRuntimeConfig() error {
-	// high 安全模式：配置与页面封装在加密容器 app.bin 内，优先内存解密加载。
-	if p, hit, err := loadSecureResources(); err != nil {
-		return secureFatal(err)
-	} else if hit {
-		var rc runtimeConfigFile
-		if err := json.Unmarshal([]byte(p.Config), &rc); err != nil {
-			return fmt.Errorf("parse encrypted config: %w", err)
-		}
-		a.applyRuntimeConfig(&rc)
-		// high 模式强制关闭 WebView 开发者工具，防止前端源码经 devtools 直接查看。
-		a.cfg.Debug = false
-		a.secure = true
-		return nil
-	}
-	return a.loadRuntimeConfigPlain()
-}
-
 // runtimeBackend 描述 config.json 中的后端进程配置（任意语言，经 stdio NDJSON 桥接）。
 type runtimeBackend struct {
 	Command string   `json:"command"`
@@ -61,7 +41,7 @@ type runtimeBackend struct {
 }
 
 // runtimeConfigFile 描述 resources/config.json 的磁盘结构。
-// 由 freedom CLI 在 build 阶段根据 freedom.config.js 生成。
+// 由 freedom CLI 在 build 阶段根据 freedom.config.js 生成；Name 仅作来源标记不应用。
 type runtimeConfigFile struct {
 	Name      string          `json:"name"`
 	Title     string          `json:"title"`
@@ -75,8 +55,14 @@ type runtimeConfigFile struct {
 	Backend   *runtimeBackend `json:"backend"`
 }
 
+// resourcesDirOverride 是单测缝：非空时替代 exe 同目录的 resources 定位。
+var resourcesDirOverride string
+
 // resourcesDir 返回 exe 同目录的 resources 目录绝对路径。
 func resourcesDir() (string, error) {
+	if resourcesDirOverride != "" {
+		return resourcesDirOverride, nil
+	}
 	exe, err := os.Executable()
 	if err != nil {
 		return "", err
@@ -84,6 +70,27 @@ func resourcesDir() (string, error) {
 	return filepath.Join(filepath.Dir(exe), "resources"), nil
 }
 
+// loadRuntimeConfig 读取 exe 同目录 resources/config.json，将命中的字段覆盖到应用配置。
+// 文件不存在时视为未配置（返回 nil，保持编译期/默认配置不变）；
+// 文件存在但读取/解析失败时返回具体错误，由调用方打印告警，避免用户手改配置出错时无感知。
+func (a *App) loadRuntimeConfig() error {
+	// high 安全模式：配置与页面封装在加密容器 app.bin 内，优先内存解密加载。
+	if p, hit, err := loadSecureResources(); err != nil {
+		return secureFatal(err)
+	} else if hit {
+		var rc runtimeConfigFile
+		if err := json.Unmarshal([]byte(p.Config), &rc); err != nil {
+			return fmt.Errorf("parse encrypted config: %w", err)
+		}
+		a.applyRuntimeConfig(&rc)
+		// high 模式强制关闭 WebView 开发者工具，防止前端源码经 devtools 直接查看。
+		a.cfg.Debug = false
+		a.secure = true
+		return nil
+	}
+	return a.loadRuntimeConfigPlain()
+}
+
 // loadRuntimeConfigPlain 明文配置路径（非 high 模式）：读取 resources/config.json。
 func (a *App) loadRuntimeConfigPlain() error {
 	dir, err := resourcesDir()
@@ -102,17 +109,13 @@ func (a *App) loadRuntimeConfigPlain() error {
 	if err := json.Unmarshal(data, &rc); err != nil {
 		return fmt.Errorf("parse %s: %w", cfgPath, err)
 	}
-	if err := a.applyRuntimeConfig(&rc); err != nil {
-		return err
-	}
+	a.applyRuntimeConfig(&rc)
 	return nil
 }
 
 // applyRuntimeConfig 把解析后的运行时配置覆盖到应用配置（明文与加密路径共用）。
-func (a *App) applyRuntimeConfig(rc *runtimeConfigFile) error {
+func (a *App) applyRuntimeConfig(rc *runtimeConfigFile) {
 	// 窗口标题：config.json 的 title 覆盖编译期默认（"Freedom App"）。
-	// 此前只解析未应用，导致改 freedom.config.js 的 name/title 无效、
-	// 打包产物窗口标题永远停留在默认值（"无法修改程序名字"）。
 	if rc.Title != "" {
 		a.cfg.Title = rc.Title
 	}
@@ -140,7 +143,8 @@ func (a *App) applyRuntimeConfig(rc *runtimeConfigFile) error {
 	if rc.Debug != nil {
 		a.cfg.Debug = *rc.Debug
 	}
-	// 外部后端进程配置：仅在壳未显式绑定后端时生效。
+	// 外部后端进程配置：仅在壳未显式绑定后端时生效（用户 Bind 过内嵌方法 =
+	// 显式内嵌后端，config.json 不得静默替换，否则其方法全部失效）。
 	// 工作目录设为 resources 目录，使相对路径参数（backend/main.mjs）按
 	// resources/ 解析（CLI 会把项目 backend/ 目录分发到 resources/backend/）。
 	if rc.Backend != nil && rc.Backend.Command != "" && !a.backendExplicit {
@@ -152,7 +156,6 @@ func (a *App) applyRuntimeConfig(rc *runtimeConfigFile) error {
 		a.cfg.Backend = pb
 		a.backend = pb
 	}
-	return nil
 }
 
 // loadRuntimeHTML 返回前端页面内容（high 模式：解密 app.bin 内的 html；

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

@@ -1,17 +1,17 @@
 package freedom
 
-// security.go — 安全加固：high 模式资源加密与完整性校验。
+// security.go — high 安全模式：资源加密容器（app.bin）与完整性校验。
 //
-// 与 lib/security.js 跨语言同步（改任一侧必须同步另一侧，否则无法解密）：
+// 与 freedom-cli lib/security.js 跨语言同步（改任一侧必须同步另一侧，否则 CLI
+// 加密的产物壳无法解密）：
 //   - securityMasterKey / securityDeriveSalt / securityPbkdf2Iter / securityKeyLen
 //   - securityMagic / securityIVLen / securityTagLen（app.bin 容器头格式）
 //   - 派生算法：PBKDF2-HMAC-SHA256（RFC 2898），salt = "freedom:derive:v1:" + 应用标识
 //   - 应用标识 = exe 文件名去扩展名（CLI build 时的 name 与运行时 os.Executable() 一致）
 //
-// 加密算法说明：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC），
-// 与 Node crypto 的 aes-256-ctr + createHmac('sha256') 跨语言一致。
-// （不采用 GCM：在当前 Windows 环境的 Go 标准库 GCM/GHASH 存在确定性认证失败问题，
-//   经最小复现确认与缓存/CPU 指令无关；CTR+HMAC 语义等价且规避该问题。）
+// 加密算法：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC），与 Node crypto 的
+// aes-256-ctr + createHmac('sha256') 跨语言一致。（不用 GCM：曾在 Windows 环境
+// 出现标准库 GHASH 确定性认证失败，CTR+HMAC 语义等价且规避该问题。）
 //
 // high 模式产物布局（CLI build 写入，与明文模式互斥）：
 //   resources/app.bin     加密容器：magic(5B FRDM1)+iv(16B)+tag(16B)+ciphertext
@@ -60,7 +60,7 @@ type integrityFile struct {
 
 // pbkdf2HMACSHA256 自实现 PBKDF2-HMAC-SHA256（RFC 2898），
 // 与 Node 的 crypto.pbkdf2Sync(password, salt, iter, keyLen, 'sha256') 结果一致。
-// 不引入 golang.org/x/crypto（go.mod 为 go 1.22，标准库未含 PBKDF2）。
+// 标准库至今未含 PBKDF2，且 go.mod 保持零外部依赖，故手写字面实现。
 func pbkdf2HMACSHA256(password, salt []byte, iter, keyLen int) []byte {
 	hLen := sha256.Size
 	numBlocks := (keyLen + hLen - 1) / hLen
@@ -87,15 +87,22 @@ func pbkdf2HMACSHA256(password, salt []byte, iter, keyLen int) []byte {
 	return dk[:keyLen]
 }
 
-// appIdentityName 返回应用标识：exe 文件名去扩展名（.exe / .app）。
+// appIdentityName 返回应用标识：exe 文件名去扩展名（.exe / .app，仅去最后一个后缀，
+// 与 lib/security.js appIdentityFor 的正则语义一致）。
 func appIdentityName(name string) string {
 	s := strings.TrimSuffix(name, ".exe")
 	s = strings.TrimSuffix(s, ".app")
 	return s
 }
 
+// appIdentityOverride 是单测缝：非空时替代 exe 文件名推导的应用标识。
+var appIdentityOverride string
+
 // appIdentity 返回运行时应用标识（当前进程 exe 文件名去扩展名）。
 func appIdentity() (string, error) {
+	if appIdentityOverride != "" {
+		return appIdentityName(appIdentityOverride), nil
+	}
 	exe, err := os.Executable()
 	if err != nil {
 		return "", err
@@ -103,8 +110,8 @@ func appIdentity() (string, error) {
 	return appIdentityName(filepath.Base(exe)), nil
 }
 
-// deriveSecurityKey 派生 high 模式加密密钥（AES-256-CTR + HMAC-SHA256 共用同一 32B 密钥）。
-// salt 引入应用标识，使不同应用密钥不同；PBKDF2 迭代增加暴力破解成本。
+// deriveSecurityKey 派生 high 模式加密密钥（AES-256-CTR 与 HMAC-SHA256 共用同一 32B 密钥）。
+// salt 引入应用标识使不同应用密钥不同；PBKDF2 迭代增加暴力破解成本。
 func deriveSecurityKey(appName string) []byte {
 	salt := []byte(securityDeriveSalt + ":" + appIdentityName(appName))
 	return pbkdf2HMACSHA256([]byte(securityMasterKey), salt, securityPbkdf2Iter, securityKeyLen)
@@ -129,7 +136,7 @@ func decryptAppBin(appName string, data []byte) (*securePayload, error) {
 
 	key := deriveSecurityKey(appName)
 
-	// 1) 认证：HMAC-SHA256(ct) 前 16 字节，与容器头 tag 恒定时间比对。
+	// 1) 认证：HMAC-SHA256(ct) 前 16 字节与容器头 tag 恒定时间比对。
 	mac := hmac.New(sha256.New, key)
 	mac.Write(ct)
 	if !hmac.Equal(tag, mac.Sum(nil)[:securityTagLen]) {
@@ -154,7 +161,7 @@ func decryptAppBin(appName string, data []byte) (*securePayload, error) {
 
 // verifyIntegrity 校验 resources/.integrity 清单（存在时）。
 // 比对 app.bin 与 backend/** 各文件 HMAC-SHA256，防整体替换/篡改。
-// 无 .integrity 文件（CLI 旧版产物）时跳过，保持向后兼容。
+// 无 .integrity 文件（旧产物）时跳过，保持向后兼容。
 func verifyIntegrity(dir, appName string, appBin []byte) error {
 	raw, err := os.ReadFile(filepath.Join(dir, ".integrity"))
 	if err != nil {

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

@@ -0,0 +1,10 @@
+//go:build !windows
+
+package freedom
+
+// RequestSingleInstance 在非 Windows 平台为无操作：始终视为唯一实例。
+// TODO(cross-platform): macOS 可用 NSRunningApplication、Linux 可用 D-Bus 单实例总线对齐该能力。
+func RequestSingleInstance(appID string) bool { return true }
+
+// OnSecondInstance 在非 Windows 平台不会被触发。
+func OnSecondInstance(fn func(args []string)) {}