@yufengtadian/freedom-cli 1.13.1 → 1.13.2

package/lib/security.js

@@ -1,43 +1,53 @@
 'use strict';
 
-// 安全加固模块（v1.13.0）
+// 安全加固模块
 //
 // 为 freedom build 提供两种安全模式：
 //   - basic（简单模式）：资源压缩 + 壳剥离符号建议，阻止"随手打开 resources/
 //     就能看到前端源码"的随手破解，成本低、完全向后兼容。
-//   - high（高危模式）：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC）加密资源为
-//     单一容器 resources/app.bin，运行时由壳在内存中解密（磁盘无明文）；
-//     配套 HMAC 完整性校验防篡改；密钥不落盘（由 exe 文件名派生），
-//     并强制关闭 WebView2 devtools。
+//   - high（高危模式）：AES-256-CTR + HMAC-SHA256（Encrypt-then-MAC）把前端、配置
+//     与后端源码加密为单一容器 resources/app.bin，运行时由壳在内存中解密（磁盘无明文）；
+//     配套 HMAC 完整性校验防篡改；密钥不落盘，并强制关闭 WebView2 devtools。
 //
 // 架构说明（重要）：通用壳 = 所有应用共用一份预编译 freedom-shell 二进制，
 // 因此密钥派生所需的"主密钥常量"编译在通用壳内，天然被所有应用共享；
 // high 模式的对抗目标是把攻击者从"直接读明文"抬升到"必须逆向壳二进制、
-// 提取主密钥并复现派生算法"。真正"每应用唯一密钥"需要每应用独立编译壳
-// （破坏通用壳 + 零工具链架构），不在本模式范围内。
+// 提取主密钥并复现派生算法"。客户端加密做不到不可逆，本模式不这样宣称。
 //
 // ⚠️ 跨语言同步点：本文件与 templates/go/pkg/freedom/security.go（= 仓库根 security.go）必须保持
-//    MASTER_KEY / DERIVE_SALT / PBKDF2_ITER / KEY_LEN / APP_BIN_MAGIC
+//    MASTER_KEY_CIPHER 字节表与掩码算法 out[i] ^= (i*7+0x5A)
+//    DERIVE_SALT / MAC_LABEL / PBKDF2_ITER / KEY_LEN / APP_BIN_MAGIC
+//    salt/iv/tag 长度、容器头顺序、载荷 JSON 结构（html/config/backend.d/m）
 //    以及加密算法（aes-256-ctr + hmac-sha256）完全一致。
 //    修改任一侧必须同步另一侧，否则 build 出的加密资源壳无法解密。
+//    回归锁：tests/security-frdm2.test.mjs 与 Go security_test.go 互为对方产物的夹具。
 
 const crypto = require('crypto');
-const path = require('path');
 
 const SECURITY_MODES = ['none', 'basic', 'high'];
 
 // ---- 密钥派生参数（必须与 Go security.go 同步）----
-// 固定常量主密钥：参与 PBKDF2 派生，编译进通用壳。此处为 CLI 侧同值。
-const MASTER_KEY = 'freedom-shell::kdf-master::v1::7f4e8c2a9b1d6e3f';
-const DERIVE_SALT = 'freedom:derive:v1';
-const PBKDF2_ITER = 60000;
+
+// 主密钥明文与位置相关掩码异或后的字节表：使 npm 包与壳二进制里都搜不到完整密钥明文。
+const MASTER_KEY_CIPHER = Buffer.from([
+  60, 19, 13, 10, 18, 18, 233, 166, 225, 241, 197, 203, 194, 143, 134, 168,
+  174, 183, 245, 178, 135, 158, 128, 158, 112, 51, 42, 97, 44, 31, 22, 10,
+  89, 117, 46, 125, 97, 60, 1, 90, 22, 65, 226, 179, 189, 240, 172,
+]);
+
+const DERIVE_SALT = 'freedom:derive:v2';
+const MAC_LABEL = 'freedom:mac:v2';
+const PBKDF2_ITER = 600000;
 const KEY_LEN = 32;
 
-// resources/app.bin 容器头：magic(5B 'FRDM1') + iv(16B) + tag(16B) + ciphertext
-// 算法：AES-256-CTR 加密 + HMAC-SHA256(密文) 截断 16B 认证标签。
-const APP_BIN_MAGIC = 'FRDM1';
+// resources/app.bin 容器：magic(5B 'FRDM2') + salt(16B) + iv(16B) + tag(16B) + ciphertext
+// tag = HMAC-SHA256(macKey, magic+salt+iv+密文) 截 16B（Encrypt-then-MAC，头部一并认证）。
+const APP_BIN_MAGIC = 'FRDM2';
+const CTR_SALT_LEN = 16;
 const CTR_IV_LEN = 16;
 const CTR_TAG_LEN = 16;
+const APP_BIN_HEADER_LEN = APP_BIN_MAGIC.length + CTR_SALT_LEN + CTR_IV_LEN + CTR_TAG_LEN;
+const APP_BIN_AUTH_LEN = APP_BIN_MAGIC.length + CTR_SALT_LEN + CTR_IV_LEN;
 
 // ---- 模式解析 ----
 
@@ -61,53 +71,101 @@ function resolveSecurity(cliValue, cfgValue) {
 
 // 应用标识：exe 文件名（去扩展名）。
 // CLI build 时 = 目标 exe 名去掉扩展名；壳运行时 = os.Executable() basename 去扩展名。
-// 两侧使用同一派生算法，故 exe 事后被重命名会导致 high 模式无法解密（视为防篡改特性）。
+// 两侧算法一致（Go strings.TrimSuffix 大小写敏感），故 exe 事后被重命名会导致
+// high 模式无法解密（视为防篡改特性）。
 function appIdentityFor(name) {
-  return String(name).replace(/\.(exe|app)$/i, '');
+  let s = String(name);
+  if (s.endsWith('.exe')) s = s.slice(0, -4);
+  if (s.endsWith('.app')) s = s.slice(0, -4);
+  return s;
 }
 
-// 与 Go security.go deriveKey 保持一致的 PBKDF2-HMAC-SHA256 派生。
-// 输入 salt = DERIVE_SALT + ':' + appName（避免仅按 exe 名可枚举碰撞）。
-function deriveKey(appName) {
-  const salt = Buffer.from(DERIVE_SALT + ':' + appIdentityFor(appName), 'utf8');
-  return crypto.pbkdf2Sync(MASTER_KEY, salt, PBKDF2_ITER, KEY_LEN, 'sha256');
+// masterSecret 还原主密钥（PBKDF2 的 password），与 Go masterSecret() 同式。
+function masterSecret() {
+  const out = Buffer.alloc(MASTER_KEY_CIPHER.length);
+  for (let i = 0; i < MASTER_KEY_CIPHER.length; i++) {
+    out[i] = MASTER_KEY_CIPHER[i] ^ ((i * 7 + 0x5a) & 0xff);
+  }
+  return out;
+}
+
+// 容器密钥对：加密与认证分开，避免同一密钥同时服务 AES-CTR 与 HMAC。
+// 与 Go deriveSecurityKey 一致：KEK = PBKDF2(master, DERIVE_SALT:app + 容器随机盐)，
+// macKey = HMAC-SHA256(KEK, MAC_LABEL)。
+function deriveKeys(appName, salt) {
+  const base = Buffer.concat([
+    Buffer.from(DERIVE_SALT + ':' + appIdentityFor(appName), 'utf8'),
+    salt,
+  ]);
+  const enc = crypto.pbkdf2Sync(masterSecret(), base, PBKDF2_ITER, KEY_LEN, 'sha256');
+  const mac = crypto.createHmac('sha256', enc).update(MAC_LABEL).digest();
+  return { enc, mac };
 }
 
 // ---- 加密 / 解密（high 模式）----
 
-// 载荷结构：{ html: <string>, config: <string> }（config 为 config.json 原文 JSON 字符串）。
+// 载荷结构：{ html, config, backend: { <rel>: { d: base64, m: mode } } }
+// backend 为可选的后端源码表（键 = 相对 resources 的斜杠路径），high 模式下
+// 后端源码进容器，磁盘不再留 resources/backend 明文目录。
 // 返回 app.bin 完整字节。
-// 算法：AES-256-CTR 加密 → HMAC-SHA256(密文) 截 16B 认证标签（Encrypt-then-MAC）。
-function encryptApp(name, html, configJSON) {
-  const key = deriveKey(name);
-  const payload = Buffer.from(JSON.stringify({ html, config: configJSON }), 'utf8');
+function encryptApp(name, html, configJSON, backend) {
+  const salt = crypto.randomBytes(CTR_SALT_LEN);
   const iv = crypto.randomBytes(CTR_IV_LEN);
-  const cipher = crypto.createCipheriv('aes-256-ctr', key, iv);
+  const k = deriveKeys(name, salt);
+  const payloadObj = { html, config: configJSON };
+  if (backend && Object.keys(backend).length > 0) {
+    payloadObj.backend = {};
+    for (const [rel, entry] of Object.entries(backend)) {
+      if (!isSafeRelPath(rel)) throw new Error(`后端路径非法，拒绝入容器：${rel}`);
+      const buf = Buffer.isBuffer(entry) ? entry : entry.data;
+      const mode = Buffer.isBuffer(entry) ? 0o644 : (((entry.mode ?? 0o644)) & 0o7777);
+      payloadObj.backend[rel] = { d: buf.toString('base64'), m: mode };
+    }
+  }
+  const payload = Buffer.from(JSON.stringify(payloadObj), 'utf8');
+  const cipher = crypto.createCipheriv('aes-256-ctr', k.enc, iv);
   const ct = Buffer.concat([cipher.update(payload), cipher.final()]);
-  const tag = crypto.createHmac('sha256', key).update(ct).digest().subarray(0, CTR_TAG_LEN);
-  return Buffer.concat([Buffer.from(APP_BIN_MAGIC, 'ascii'), iv, tag, ct]);
+  const header = Buffer.concat([Buffer.from(APP_BIN_MAGIC, 'ascii'), salt, iv]);
+  const tag = crypto.createHmac('sha256', k.mac)
+    .update(header).update(ct).digest().subarray(0, CTR_TAG_LEN);
+  return Buffer.concat([header, tag, ct]);
 }
 
-// 解密 app.bin（供单测验证 / 未来壳调试工具复用）。返回 { html, config }。
-function decryptApp(name, buf) {
-  const key = deriveKey(name);
+// 拆分并校验容器头；旧版 FRDM1 等不兼容版本明确拒绝（不静默降级）。
+function splitAppBin(buf) {
   const magic = Buffer.from(APP_BIN_MAGIC, 'ascii');
-  if (buf.length < magic.length + CTR_IV_LEN + CTR_TAG_LEN || !buf.subarray(0, magic.length).equals(magic)) {
-    throw new Error('app.bin 头无效：不是 FRDM1 加密容器');
+  if (buf.length < APP_BIN_HEADER_LEN) {
+    throw new Error('app.bin 长度不足容器头');
+  }
+  if (!buf.subarray(0, magic.length).equals(magic)) {
+    throw new Error(
+      `app.bin 容器版本不受支持（头为 "${buf.subarray(0, magic.length).toString('ascii')}"，要求 ${APP_BIN_MAGIC}）`);
   }
   let off = magic.length;
+  const salt = buf.subarray(off, off + CTR_SALT_LEN); off += CTR_SALT_LEN;
   const iv = buf.subarray(off, off + CTR_IV_LEN); off += CTR_IV_LEN;
   const tag = buf.subarray(off, off + CTR_TAG_LEN); off += CTR_TAG_LEN;
   const ct = buf.subarray(off);
+  return { salt, iv, tag, ct, headerLen: APP_BIN_AUTH_LEN };
+}
+
+// 判定容器内相对路径可安全落盘（与 Go isSafeRelPath 同式）。
+function isSafeRelPath(rel) {
+  if (rel === '' || rel.includes('\\') || rel.startsWith('/')) return false;
+  if (rel.length >= 2 && rel[1] === ':') return false;
+  return rel.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
 
-  // 1) 认证：HMAC-SHA256(ct) 前 16 字节与容器头 tag 恒定时间比对。
-  const expect = crypto.createHmac('sha256', key).update(ct).digest().subarray(0, CTR_TAG_LEN);
+// 解密 app.bin（供跨语言回归测试与 CLI 自检复用）。返回 { html, config, backend? }。
+function decryptApp(name, buf) {
+  const { salt, iv, tag, ct, headerLen } = splitAppBin(buf);
+  const k = deriveKeys(name, salt);
+  const expect = crypto.createHmac('sha256', k.mac)
+    .update(buf.subarray(0, headerLen)).update(ct).digest().subarray(0, CTR_TAG_LEN);
   if (!crypto.timingSafeEqual(tag, expect)) {
-    throw new Error('app.bin 认证失败（exe 被重命名或资源被篡改？）');
+    throw new Error('app.bin 认证失败（exe 被重命名、资源被篡改，或壳与 CLI 版本不匹配）');
   }
-
-  // 2) 解密：AES-256-CTR。
-  const decipher = crypto.createDecipheriv('aes-256-ctr', key, iv);
+  const decipher = crypto.createDecipheriv('aes-256-ctr', k.enc, iv);
   const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
   const obj = JSON.parse(plain.toString('utf8'));
   if (typeof obj.html !== 'string' || typeof obj.config !== 'string') {
@@ -118,17 +176,13 @@ function decryptApp(name, buf) {
 
 // ---- 完整性清单（high 模式）----
 
-// 生成 resources/.integrity：记录 app.bin 与 backend/ 各文件的 HMAC-SHA256，
-// 壳启动时校验，防止 resources 被整体替换/篡改。
-// 返回 { v, appBin, backend }。
-function buildIntegrity(appName, appBin, backendRelMap) {
-  const key = deriveKey(appName);
-  const hmac = (buf) => crypto.createHmac('sha256', key).update(buf).digest('hex');
-  const backend = {};
-  for (const [rel, buf] of Object.entries(backendRelMap || {})) {
-    backend[rel] = hmac(buf);
-  }
-  return { v: 1, appBin: hmac(appBin), backend };
+// 生成 resources/.integrity：记录 app.bin 的 HMAC-SHA256，壳启动时校验，
+// 防容器被整体替换。backend 已进容器，其完整性由容器认证标签一并保证。
+function buildIntegrity(appName, appBin) {
+  const { salt } = splitAppBin(appBin);
+  const k = deriveKeys(appName, salt);
+  const hmac = (buf) => crypto.createHmac('sha256', k.mac).update(buf).digest('hex');
+  return { v: 2, appBin: hmac(appBin) };
 }
 
 // 生成 .integrity 文件文本。
@@ -139,12 +193,17 @@ function renderIntegrity(integrity) {
 module.exports = {
   SECURITY_MODES,
   APP_BIN_MAGIC,
+  APP_BIN_HEADER_LEN,
+  CTR_SALT_LEN,
   parseSecurity,
   resolveSecurity,
   appIdentityFor,
-  deriveKey,
+  masterSecret,
+  deriveKeys,
   encryptApp,
   decryptApp,
+  splitAppBin,
+  isSafeRelPath,
   buildIntegrity,
   renderIntegrity,
 };

package/lib/shell.js

@@ -316,8 +316,11 @@ function buildShell(plat) {
   }
 
   const buildDir = goTemplateDir();
-  const ldflags = plat.startsWith('win') ? ['-ldflags', '-H windowsgui'] : [];
-  const build = spawnSync('go', ['build', ...ldflags, '-o', dest, '.'], {
+  // 剥离符号与调试信息（-s -w）+ 抹掉构建期绝对路径（-trimpath）：
+  // 通用壳里编译进了 high 模式的密钥派生逻辑，函数名/DWARF 是给逆向者的地图。
+  const ldflags = ['-s', '-w'];
+  if (plat.startsWith('win')) ldflags.push('-H', 'windowsgui');
+  const build = spawnSync('go', ['build', '-trimpath', '-ldflags', ldflags.join(' '), '-o', dest, '.'], {
     cwd: buildDir,
     encoding: 'utf8',
     env: { ...process.env, CGO_ENABLED: '1' },

package/lib/tui.js

@@ -372,4 +372,40 @@ async function tui(cwd) {
   return 0;
 }
 
-module.exports = { tui, TUI };
+// 裸 `freedom` 的显示方式选择器：终端 TUI 或 Freedom Desktop（图形窗口）。
+// 先退出 raw mode 再拉起窗口 / 再进主菜单，避免两个界面抢同一个终端。
+async function pickDisplay(cwd) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error('[freedom] 当前非交互式终端，请改用具体子命令（freedom help 查看全部命令）。');
+    return 1;
+  }
+  const app = new TUI();
+  app.enter();
+  let idx;
+  try {
+    idx = await app.menu('选择显示方式', ['终端 TUI（纯文本菜单）', 'Freedom Desktop（图形窗口，由 freedom 自身打包）'], {
+      footer: '↑ ↓ 选择 · Enter 确认 · q 退出',
+    });
+  } finally {
+    app.exit();
+  }
+  if (idx === null) return 0;
+  if (idx === 1) return desktopFlow(cwd);
+  return await tui(cwd);
+}
+
+async function desktopFlow(cwd) {
+  const { desktop } = require('./desktop');
+  const theme = require('./theme');
+  try {
+    const r = await desktop({});
+    process.stdout.write(`${theme.ok('Freedom Desktop 已拉起：')}${r.exe}\n`);
+    if (r.rebuilt) process.stdout.write(`${theme.dim(`（本次已重新打包，CLI v${r.version}）`)}\n`);
+    return 0;
+  } catch (e) {
+    process.stdout.write(`\n${theme.err(e.message)}\n`);
+    return 1;
+  }
+}
+
+module.exports = { tui, pickDisplay, TUI };

package/lib/verify.js

@@ -10,6 +10,7 @@
 const fs = require('fs');
 const path = require('path');
 const { isWinPlat, platformExeName } = require('./utils');
+const { APP_BIN_MAGIC, decryptApp, buildIntegrity } = require('./security');
 
 // ---- 产物定位 ----
 
@@ -107,6 +108,7 @@ function checkPlatformProduct({ targetDir, plat, appName, hasBackend }) {
   const hasIntegrity = fs.existsSync(path.join(resDir, '.integrity'));
   const hasHtml = fs.existsSync(path.join(resDir, 'index.html'));
   const hasConfig = fs.existsSync(path.join(resDir, 'config.json'));
+  let securePayload = null;
   if (hasBin) {
     if (hasHtml || hasConfig) {
       fail('资源形态', 'high 模式残留明文 index.html/config.json（互斥被破坏）');
@@ -115,13 +117,35 @@ function checkPlatformProduct({ targetDir, plat, appName, hasBackend }) {
     }
     if (!hasIntegrity) fail('完整性清单', '缺失 .integrity');
     else okc('完整性清单', '.integrity 存在');
-    // app.bin 容器头校验（FRDM1）
-    let head = '';
+    // app.bin 容器头校验（FRDM2）
+    let bin = Buffer.alloc(0);
     try {
-      head = fs.readFileSync(path.join(resDir, 'app.bin')).subarray(0, 5).toString('latin1');
+      bin = fs.readFileSync(path.join(resDir, 'app.bin'));
     } catch (e) { /* 读取失败按不通过处理 */ }
-    if (head === 'FRDM1') okc('app.bin 容器', 'FRDM1 头有效');
-    else fail('app.bin 容器', '容器头不是 FRDM1，文件损坏或非本工具产物');
+    const head = bin.subarray(0, APP_BIN_MAGIC.length).toString('latin1');
+    if (head !== APP_BIN_MAGIC) {
+      fail('app.bin 容器', `容器头不是 ${APP_BIN_MAGIC}（实际 "${head}"），文件损坏、非本工具产物或旧版产物`);
+    } else {
+      okc('app.bin 容器', `${APP_BIN_MAGIC} 头有效（${fmtSize(bin.length)}）`);
+      // 真解一次容器：认证失败 = 产物被篡改或 name 与容器不匹配；同时拿到 backend 供后端检查。
+      try {
+        securePayload = decryptApp(appName, bin);
+        okc('容器解密', `认证通过，html ${fmtSize(securePayload.html.length)} / config ${fmtSize(securePayload.config.length)}`);
+      } catch (e) {
+        fail('容器解密', e.message);
+      }
+      // .integrity 与容器一致（防整体替换：清单值由构建期容器盐派生密钥签名）
+      if (hasIntegrity) {
+        try {
+          const list = JSON.parse(fs.readFileSync(path.join(resDir, '.integrity'), 'utf8'));
+          const want = buildIntegrity(appName, bin).appBin;
+          if (list.appBin !== want) fail('完整性清单', '.integrity 与 app.bin 不一致（产物可能被替换）');
+          else okc('完整性清单', '.integrity 与 app.bin 一致');
+        } catch (e) {
+          fail('完整性清单', e.message);
+        }
+      }
+    }
   } else {
     if (hasIntegrity) {
       fail('资源形态', '明文模式残留 high 产物（.integrity）');
@@ -148,10 +172,21 @@ function checkPlatformProduct({ targetDir, plat, appName, hasBackend }) {
     }
   }
 
-  // 4) 后端目录
+  // 4) 后端：明文模式看 resources/backend 目录；high 模式看容器内 backend 条目
+  //    （容器模式下磁盘不得有明文后端目录，运行时由壳解密到临时目录）。
   if (hasBackend) {
-    if (fs.existsSync(path.join(resDir, 'backend'))) okc('后端进程', 'resources/backend 存在');
-    else fail('后端进程', '配置了 backend 但 resources/backend 缺失');
+    if (hasBin) {
+      const n = securePayload && securePayload.backend ? Object.keys(securePayload.backend).length : 0;
+      if (n === 0) fail('后端进程', 'high 模式容器内无 backend 条目（后端源码未入容器）');
+      else okc('后端进程', `容器内 ${n} 个后端文件（磁盘无明文）`);
+      if (fs.existsSync(path.join(resDir, 'backend'))) {
+        fail('后端进程', 'high 模式残留明文 resources/backend（与容器互斥被破坏）');
+      }
+    } else if (fs.existsSync(path.join(resDir, 'backend'))) {
+      okc('后端进程', 'resources/backend 存在');
+    } else {
+      fail('后端进程', '配置了 backend 但 resources/backend 缺失');
+    }
   }
 
   return checks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.13.1",
+  "version": "1.13.2",
   "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
   "repository": {
     "type": "git",
@@ -26,6 +26,7 @@
     "bin",
     "lib",
     "shell",
+    "skill",
     "templates",
     "tutorial",
     "postinstall.js",

package/skill/freedom/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: freedom
+description: 用 Freedom（Go 通用 WebView 桌面壳 + freedom CLI）把任意前端与任意语言后端打包成 Windows/macOS/Linux 桌面应用。当任务涉及 freedom.config.js、freedom build/verify/dev、单文件前端内嵌、NDJSON stdio 后端协议、freedom.invoke / freedom.sys / resources/config.json、FRDM1 资源加密、应用自更新清单（keygen/manifest）或桌面壳选型/排障时使用。
+---
+
+# Freedom 桌面壳使用指南
+
+Freedom = 预编译通用壳（Go + 系统 WebView）+ 外部 `resources/` 资源层 + `freedom` CLI。
+前端构建成**单文件 HTML** 后由壳在内存加载（`SetHtml`），后端可以是**任意语言的子进程**，
+经 NDJSON over stdio 通信。打包不需要 Go / Rust / Node 工具链在目标机器上存在。
+
+## 1. 最小项目形态
+
+```
+my-app/
+├─ package.json            # 必须 "type":"module"（freedom.config.js 用 ESM 书写）
+├─ freedom.config.js       # 唯一配置入口
+├─ index.html  src/        # 前端（vite + vite-plugin-singlefile 产单文件）
+└─ backend/                # 可选：进程后端脚本，构建时整体拷进 resources/backend/
+```
+
+`freedom init <目录> [--template full|minimal]` 生成骨架；`freedom build` 打包；
+`freedom verify` 校验产物（CI 用退出码）。
+
+### freedom.config.js 可用键
+
+| 键 | 含义 |
+|----|------|
+| `name` `title` | 产物文件名 / 窗口标题 |
+| `width` `height` `minWidth` `minHeight` `center` `debug` | 窗口几何与调试 |
+| `titlebar` | `frameless`（默认，前端自绘按钮）/ `native` |
+| `icon` | Win `.ico` / mac `.icns`，构建期注入 |
+| `outDir` | 产物目录，默认 `dist` |
+| `security` | `none` / `basic` / `high`（high = resources 加密为 `app.bin` + `.integrity`） |
+| `backend` | `{ command:'node', args:['backend/x.mjs'] }`；缺省为内嵌 Go 后端模式 |
+| `backendDir` | 后端目录名，默认 `backend` |
+| `staticHtml` | **跳过 npm/vite**，直接内嵌指定单文件 HTML（自举与纯静态页用，零网络） |
+| `url` | 壳改为 `Navigate(url)`（http/https 白名单）——`freedom dev` 热更走这条 |
+| `singleInstance` | `true` 时以 `CreateMutexW` 为权威锁做单实例 |
+| `updater` | `{ manifestURL, publicKey, requireSignature }` 应用自更新 |
+
+CLI 侧可用 `freedom config set <key> <value>` 修改；改完必须重新 `freedom build` 生效。
+
+## 2. 前端 SDK（壳自动注入，无需 import）
+
+```js
+// 调用后端方法（内嵌 Go 绑定名 或 进程后端 method 名），参数按 JSON 数组透传
+const sum = await freedom.invoke('Add', 1, 2);
+
+freedom.on('tick', (data) => ...)        // 订阅后端 Emit 的事件，返回 unlisten
+freedom.once('ready', cb)                // 一次性
+freedom.off('tick', cb);  freedom.emit(event, data)
+
+freedom.window.minimize() / maximize() / setSize(w,h) / setTitle(t) / setAlwaysOnTop(true)
+freedom.window.close(true)               // force 跳过关闭拦截
+freedom.window.create({title,url,html,width,height}) / list() / focusWindow(id) / closeWindow(id)
+
+// 系统能力：任意能力名走同一个桥
+freedom.sys('os.info', {});  freedom.sys('clipboard.read', {})
+freedom.clipboard.readText() / writeText(t)
+freedom.shell.open(target)               // 白名单：仅 http(s)/mailto 与显式放行项
+freedom.notification.show(title, body)
+freedom.shortcut.register('id','Ctrl+Alt+K')
+freedom.autostart.enable({name}) / isEnabled()
+freedom.protocol.register('myapp')
+freedom.path('data'|'config'|'cache'|'temp', name)
+freedom.store.set(k,v) / get(k) / load() / keys()
+freedom.process.id() / exit(0) / restart()
+freedom.update.check() / install() / pending() / onAvailable(cb)
+freedom.taskbar.setProgress(0.4) / setState('error') / setOverlay(dataURL)
+freedom.dialog.message({title,message,buttons})
+freedom.tray.create({icon: dataURL, tooltip}) / setMenu([...])
+freedom.isDesktop                          // 是否在壳内（浏览器打开为 false）
+```
+
+`window.go.backend.call(...)` 是 Wails 迁移别名。判断"未在桌面壳内"应给出浏览器降级，
+而不是让 Promise 直接炸页面。
+
+## 3. 进程后端协议（NDJSON over stdio）
+
+换行分隔 JSON，UTF-8，**stdout 只能写协议帧**（日志请写 stderr 或文件）。
+
+```jsonc
+// 壳 → 后端（请求）
+{"id":1,"method":"Add","params":[1,2]}
+// 后端 → 壳（响应：error 为空串表示成功）
+{"id":1,"result":3,"error":""}
+// 后端 → 壳（主动推送，触发前端 freedom.on）
+{"event":"tick","data":{"count":1}}
+```
+
+后端进程工作目录 = `resources/`，环境变量注入 `FREEDOM_BACKEND=1`、`FREEDOM_IPC=stdio`。
+最小 Node 实现（零依赖）：
+
+```js
+import readline from 'node:readline';
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('close', () => process.exit(0));              // 壳关闭 stdin 即优雅退出，别等超时
+rl.on('line', (line) => {
+  const r = JSON.parse(line);
+  const [a, b] = r.params ?? [];
+  process.stdout.write(JSON.stringify({ id: r.id, result: a + b, error: '' }) + '\n');
+});
+```
+
+Go / Python / Rust 同构实现见 `examples/multiproc/backends/`。Rust 侧零依赖单文件、
+`rustc -O` 直编，不走 cargo。
+
+## 4. CLI 命令
+
+```
+freedom                     # 选择显示方式：终端 TUI / Freedom Desktop
+freedom tui | desktop       # 直达对应显示（desktop 会按需自动重打包再拉起）
+freedom init [dir] [--template full|minimal] [--force]
+freedom build [--platform win|mac|linux|all] [--security none|basic|high] [--installer] [--no-cache]
+freedom verify [--platform <p>]        # 产物完整性校验，非零退出码 = 有问题
+freedom dev [--port <n>|--url <u>|--command <cmd>]   # HMR 联调壳窗口，改码免重打包
+freedom dmg [--platform darwin-arm64]  # macOS 上产出 .dmg（hdiutil）
+freedom config [get <k>|set <k> <v>]
+freedom titlebar <native|frameless> | icon <path> | security <mode>
+freedom shell list|download <plat>|build <plat>
+freedom keygen               # 生成自更新 ed25519 密钥对（私钥只在发布方）
+freedom manifest --artifact <产物> --url <下载地址> [--version x] [--notes y]
+freedom agents                          # Agent 集成支持矩阵（本机证据判定）
+freedom skill install --agent all [--dry-run]
+freedom mcp install --agent <key> [--config <path> --format json|toml|yaml]
+freedom mcp serve                       # stdio MCP 服务（一般由 agent 拉起，不手敲）
+freedom update | version | tutorial | help
+```
+
+自动化/脚本环境请设 `FREEDOM_AUTO_UPDATE=0`，否则 npm 相关命令可能触发自动升级。
+
+## 5. 产物与发布
+
+- 单平台：`dist/<name>[.exe]` + `dist/resources/{index.html,config.json,backend/}`；多平台落 `dist/<plat>/`。
+- macOS：`--platform mac` 直接产出 `<name>.app.zip`（解压即用）；Linux 同理为目录形态。
+- `--installer`：便携 zip 恒产出；Windows 且有 `makensis` 时额外编译 `setup.exe`，否则产出已填充的 `.nsi`。
+- `--security high`：resources 整体加密为 `app.bin`（PBKDF2-HMAC-SHA256 按 exe 名派生密钥 +
+  AES-256-CTR + Encrypt-then-MAC）+ `.integrity` 清单；磁盘无明文，校验失败壳拒绝运行。
+  参数与 Go 侧 `security.go` 跨语言同步，**改一侧必须改另一侧**。
+- 自更新：`freedom keygen` → 公钥写进 `updater.publicKey` → 发版用 `freedom manifest` 签
+  `latest.json` → 壳内 `freedom.update.check()`。清单签名串固定为
+  `freedom-update-v1\n{version}\n{url}\n{sha256小写}`。
+
+## 6. 坑清单（都真实踩过）
+
+1. **前端必须单文件**：壳只读一个 `index.html`，资源请内联（vite-plugin-singlefile）。
+2. **stdout 污染**：进程后端往 stdout 打日志 = 协议解析失败。日志走 stderr。
+3. **后端不退出**：stdin EOF 时必须 `process.exit(0)` / 等价处理，否则每次关窗都等满超时被强杀。
+4. **Bind 回调是异步的**：`freedom.invoke` 的 handler 跑在 worker goroutine，可并发、完成序不保证；
+   壳内置的 `__freedom_window/sys/tray` 桥仍跑在 UI 消息泵内，其中涉及子进程/文件 IO 需自行异步化。
+5. **平台面不对齐**：Windows 独有能力（taskbar 进度、原生对话框、托盘）在 Linux 会明确报
+   not supported，macOS 部分能力仍在路上——UI 要先 `freedom.sys('os.info')` 判平台再摆按钮。
+6. **PowerShell 脚本**：含中文必须存带 BOM 的 UTF-8，`param()` 必须是首条可执行语句；
+   原生命令失败要显式查 `$LASTEXITCODE`。
+7. **Windows 打 zip**：必须用 `%SystemRoot%\System32\tar.exe`（bsdtar）。Git Bash 的 GNU tar
+   会抢 PATH，且不认 `-a`、把 `D:\` 当远程主机。
+8. **能力模型**：`Config.Capabilities{Allow,Deny}`（`path.Match`）在 sys/tray/window 派发前判定，
+   拒绝零副作用；默认全开。