@yufengtadian/freedom-cli 1.13.0 → 1.13.2

package/lib/build.js

@@ -107,27 +107,39 @@ async function build(projectDir, opts = {}) {
   const autoDownload = opts.autoDownload !== false;
 
   // 1) 前端打包（带缓存：源码未变更时复用上次 vite 产物，跳过 npm run build）
-  ensureNodeModules(dir);
-  const useCache = opts.noCache !== true;
-  if (useCache && !viteNeedsRebuild(dir)) {
-    process.stdout.write('[freedom] 前端源码无改动，复用构建缓存...\n');
+  // cfg.staticHtml：静态单文件页面直通——不跑 npm install / vite，用于 freedom 自己的
+  // Desktop 界面自举打包（以及纯静态页项目），零网络、零依赖。
+  let html;
+  if (cfg.staticHtml) {
+    const staticPath = path.resolve(dir, String(cfg.staticHtml));
+    if (!fs.existsSync(staticPath)) {
+      throw new Error(`staticHtml 指向的文件不存在：${staticPath}（freedom.config.js 配置项）`);
+    }
+    html = fs.readFileSync(staticPath, 'utf8');
+    warnIfNotSingleFile(html, staticPath);
   } else {
-    process.stdout.write('[freedom] 前端打包中（npm run build）...\n');
-    // 全量构建时 npm/vite 输出必须实时透传（stdio: inherit），
-    // 此前 pipe 缓冲会吞掉构建全程输出，Node 主线程被 spawnSync 同步阻塞，
-    // 大前端全量构建时终端长时间零输出，表现如"未响应/卡死"。
-    const vite = run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
-    if (vite.status !== 0) {
-      throw new Error(`前端打包失败（退出码 ${vite.status}），详见上方构建输出。`);
+    ensureNodeModules(dir);
+    const useCache = opts.noCache !== true;
+    if (useCache && !viteNeedsRebuild(dir)) {
+      process.stdout.write('[freedom] 前端源码无改动，复用构建缓存...\n');
+    } else {
+      process.stdout.write('[freedom] 前端打包中（npm run build）...\n');
+      // 全量构建时 npm/vite 输出必须实时透传（stdio: inherit），
+      // 此前 pipe 缓冲会吞掉构建全程输出，Node 主线程被 spawnSync 同步阻塞，
+      // 大前端全量构建时终端长时间零输出，表现如"未响应/卡死"。
+      const vite = run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
+      if (vite.status !== 0) {
+        throw new Error(`前端打包失败（退出码 ${vite.status}），详见上方构建输出。`);
+      }
+      writeViteCacheMarker(dir);
     }
-    writeViteCacheMarker(dir);
-  }
-  const distHtml = path.join(dir, '.freedom', 'vite-dist', 'index.html');
-  if (!fs.existsSync(distHtml)) {
-    throw new Error(`前端打包完成但未找到 ${distHtml}，请检查 vite 配置（vite-plugin-singlefile）。`);
+    const distHtml = path.join(dir, '.freedom', 'vite-dist', 'index.html');
+    if (!fs.existsSync(distHtml)) {
+      throw new Error(`前端打包完成但未找到 ${distHtml}，请检查 vite 配置（vite-plugin-singlefile）。`);
+    }
+    html = fs.readFileSync(distHtml, 'utf8');
+    warnIfNotSingleFile(html, distHtml);
   }
-  const html = fs.readFileSync(distHtml, 'utf8');
-  warnIfNotSingleFile(html, distHtml);
   const configJSON = renderConfigJSON(cfg, name);
   // 安全模式：--security 优先于 freedom.config.js 的 security 字段，默认 none。
   //   none  = 明文资源（默认，兼容历史产物）
@@ -149,8 +161,8 @@ async function build(projectDir, opts = {}) {
   const results = await Promise.all(
     platforms.map(async (plat) => {
       const targetDir = multi ? path.join(outDirPath, plat) : outDirPath;
-      const outFile = await emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon, security });
-      return { plat, outFile };
+      const emitted = await emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon, security, installer: opts.installer === true });
+      return { plat, ...emitted };
     })
   );
 
@@ -184,7 +196,7 @@ async function build(projectDir, opts = {}) {
   return { results };
 }
 
-async function emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon, security }) {
+async function emitPlatform({ plat, name, version, targetDir, html, configJSON, backendDir, hasBackend, autoDownload, icon, security, installer }) {
   // 取预编译壳二进制
   const shell = localShellPath(plat);
   if (!fs.existsSync(shell)) {
@@ -233,14 +245,24 @@ async function emitPlatform({ plat, name, version, targetDir, html, configJSON,
       const p = path.join(resDir, legacy);
       if (fs.existsSync(p)) await fsp.rm(p, { force: true });
     }
-    const appBin = encryptApp(name, html, configJSON);
-    await fsp.writeFile(path.join(resDir, 'app.bin'), appBin);
-    const backendRelMap = {};
+    // 后端源码同样进容器：high 模式磁盘上不留 resources/backend 明文目录，
+    // 壳启动时把容器内 backend/* 解密到一次性临时目录（退出即删）。
+    const legacyBackend = path.join(resDir, 'backend');
+    if (fs.existsSync(legacyBackend)) await fsp.rm(legacyBackend, { recursive: true, force: true });
+    const backendFiles = {};
     if (hasBackend && fs.existsSync(backendDir)) {
-      collectDirFiles(backendDir, '', backendRelMap);
+      for (const [rel, buf] of Object.entries(collectDirFiles(backendDir, '', {}))) {
+        backendFiles['backend/' + rel] = { data: buf, mode: fileMode(path.join(backendDir, rel)) };
+      }
+    }
+    // 加密前先抹掉 source map 引用：内联 sourceMappingURL 里往往直接嵌着前端原始源码，
+    // 容器解密即还原，等于给 high 模式留了个明文后门。
+    const { html: secureHtml, stripped } = stripSourceMapRefs(html);
+    if (stripped > 0) {
+      process.stdout.write(`[freedom] high 模式：已抹去前端页内 ${stripped} 处 source map 引用（可能含原始源码）。\n`);
     }
-    const integrityText = renderIntegrity(buildIntegrity(name, appBin, backendRelMap));
-    await fsp.writeFile(path.join(resDir, '.integrity'), integrityText, 'utf8');
+    const appBin = encryptApp(name, secureHtml, configJSON, backendFiles);    await fsp.writeFile(path.join(resDir, 'app.bin'), appBin);
+    await fsp.writeFile(path.join(resDir, '.integrity'), renderIntegrity(buildIntegrity(name, appBin)), 'utf8');
   } else {
     for (const legacy of ['app.bin', '.integrity']) {
       const p = path.join(resDir, legacy);
@@ -256,10 +278,14 @@ async function emitPlatform({ plat, name, version, targetDir, html, configJSON,
       );
     }
   }
-  if (hasBackend) {
+  if (hasBackend && security !== 'high') {
     copyDir(backendDir, path.join(resDir, 'backend'));
   }
 
+  // --installer：便携 zip + Windows NSIS 安装器。先于 mac 的 .app 生成，
+  // 使 zip 内容只含「exe + resources」，不把 .app 与 .app.zip 二次打包进去。
+  const installers = installer ? await buildInstaller({ plat, name, version, targetDir, exeName }) : [];
+
   // macOS：额外生成 .app bundle + .app.zip（供 mac 用户解压即用）
   // 壳加载 exe 同目录 resources/，故把 resources 放进 Contents/MacOS/ 即可运行，无需改壳。
   if (isMacPlat(plat)) {
@@ -269,7 +295,7 @@ async function emitPlatform({ plat, name, version, targetDir, html, configJSON,
     );
   }
 
-  return outFile;
+  return { outFile, installers };
 }
 
 // 把 .ico 图标注入到 Windows exe 的 PE 资源（RT_ICON + RT_GROUP_ICON），
@@ -290,7 +316,16 @@ async function applyWindowsIcon(exePath, iconPath, name, version) {
     );
     return;
   }
-  const rcedit = require('rcedit'); // 惰性加载，避免未配置 icon 时增加启动开销
+  let rcedit;
+  try {
+    rcedit = require('rcedit'); // 惰性加载，避免未配置 icon 时增加启动开销
+  } catch (e) {
+    throw new Error(
+      'exe 图标注入需要依赖 rcedit，但未能加载（npm 安装不完整）。'
+      + '请在 freedom-cli 安装目录执行 npm install 后重试；'
+      + '或临时移除 freedom.config.js 的 icon 配置以跳过注入。'
+    );
+  }
   const info = { icon: iconPath };
   // rcedit 4.x 参数结构：FileDescription/ProductName 等字符串必须走
   // version-string（--set-version-string 键值对），file-version/product-version
@@ -402,21 +437,25 @@ ${iconEntry}  <key>CFBundleExecutable</key>
 }
 
 // 把目录压成 .zip：跨平台零额外依赖（历史 bug B27）
-// - Windows：系统 tar 为 bsdtar，`-a` 按扩展名自动选 zip 压缩器，可用；
-// - Linux/macOS：GNU tar 的 `-a` 不支持 .zip（仅 gzip/bzip2/xz 等），
-//   改用系统 zip 命令（Linux/macOS 自带或常见，缺失时给出安装提示）。
+// - Windows：bsdtar 的 `-a` 按扩展名自动选 zip 压缩器，可用；但必须绝对路径锁定系统
+//   tar.exe —— Git Bash / MSYS 会把 GNU tar 塞进 PATH 前面，GNU tar 不认 `-a` 且把
+//   `D:\...` 当远程主机（`Cannot connect to D: resolve failed`）。
+// - Linux/macOS：GNU tar 的 `-a` 不支持 .zip，改用系统 zip 命令（缺失时给出安装提示）。
 function zipDir(zipPath, dir) {
   const parent = path.dirname(dir);
   const base = path.basename(dir);
   if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
-  let res;
+  let cmd = 'zip';
+  let args = ['-r', '-q', zipPath, base];
   if (process.platform === 'win32') {
-    res = spawnSync('tar', ['-a', '-c', '-f', zipPath, base], { cwd: parent, encoding: 'utf8' });
-  } else {
-    res = spawnSync('zip', ['-r', '-q', zipPath, base], { cwd: parent, encoding: 'utf8' });
+    const sysRoot = process.env.SystemRoot || 'C:\\Windows';
+    const bsdtar = path.join(sysRoot, 'System32', 'tar.exe');
+    cmd = fs.existsSync(bsdtar) ? bsdtar : 'tar';
+    args = ['-a', '-c', '-f', zipPath, base];
   }
+  const res = spawnSync(cmd, args, { cwd: parent, encoding: 'utf8', windowsHide: true });
   if (res.error || res.status !== 0) {
-    const detail = (res.stderr || res.stdout || '').trim() || res.error.message;
+    const detail = (res.stderr || res.stdout || (res.error && res.error.message) || '').trim();
     const hint = process.platform !== 'win32'
       ? '\n（Linux/macOS 打包 zip 需要 zip 命令：Ubuntu: sudo apt install zip / macOS: brew install zip）'
       : '';
@@ -424,6 +463,62 @@ function zipDir(zipPath, dir) {
   }
 }
 
+// --installer 产物：便携 zip 恒产出；Windows 额外填充 NSIS 模板，本机有 makensis
+// 时直接编译 setup.exe，无则产出已填充的 .nsi（缺 makensis 属环境能力而非代码缺陷）。
+// 顺序即排除策略：先压 zip 再写 .nsi/setup.exe，免维护"排除安装器中间物"清单。
+async function buildInstaller({ plat, name, version, targetDir, exeName }) {
+  const artifacts = [];
+
+  const zipPath = path.join(targetDir, `${name}-${plat}-portable.zip`);
+  const tmpPath = path.join(path.dirname(targetDir), `.freedom-portable-${process.pid}.zip`);
+  zipDir(tmpPath, targetDir);
+  await fsp.rename(tmpPath, zipPath);
+  artifacts.push(zipPath);
+
+  if (!isWinPlat(plat)) return artifacts;
+
+  const tplPath = path.join(__dirname, '..', 'templates', 'installer', 'app.nsi');
+  if (!fs.existsSync(tplPath)) {
+    process.stdout.write(`[freedom] 提示：缺少安装包模板 ${tplPath}，已跳过 NSIS。\n`);
+    return artifacts;
+  }
+  const fill = (s) =>
+    s.replace(/@NAME@/g, name)
+      .replace(/@VERSION@/g, version)
+      .replace(/@SRC@/g, targetDir)
+      .replace(/@OUT@/g, targetDir)
+      .replace(/@EXE@/g, exeName);
+  // NSIS 3 对无 BOM 的 UTF-8 脚本按代码页解释，模板含中文注释与 SimpChinese 文案，
+  // 故补 BOM（与 build.ps1 的 [Text.Encoding]::UTF8 写出行为一致）。
+  const body = fill(fs.readFileSync(tplPath, 'utf8'));
+  const nsiPath = path.join(targetDir, `${name}-setup-${version}.nsi`);
+  await fsp.writeFile(nsiPath, Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(body, 'utf8')]));
+  artifacts.push(nsiPath);
+
+  if (!hasTool('makensis')) {
+    process.stdout.write(
+      '[freedom] 未检测到 makensis（NSIS）：已产出填充好的 .nsi，在装有 NSIS 的机器上执行\n' +
+      `          makensis "${nsiPath}" 即可编译安装器。\n`
+    );
+    return artifacts;
+  }
+  const res = spawnSync('makensis', ['-V2', nsiPath], { encoding: 'utf8' });
+  if (res.status !== 0) {
+    const detail = (res.stderr || res.stdout || '').trim().slice(0, 600);
+    throw new Error(`makensis 编译失败（退出码 ${res.status}）：${detail}`);
+  }
+  const setupPath = path.join(targetDir, `${name}-setup-${version}.exe`);
+  process.stdout.write(`[freedom] NSIS 安装器已生成：${setupPath}\n`);
+  artifacts.push(setupPath);
+  return artifacts;
+}
+
+// 外部命令可用性探测（不影响主流程，仅决定是否尝试调用）。
+function hasTool(cmd) {
+  const res = spawnSync(cmd, ['-VERSION'], { encoding: 'utf8', windowsHide: true });
+  return !res.error;
+}
+
 // 从项目 package.json 取版本号（cfg.version 优先）
 function appVersionFromPkg(dir) {
   try {
@@ -456,6 +551,17 @@ function renderConfigJSON(cfg, name) {
       args: Array.isArray(cfg.backend.args) ? cfg.backend.args : [],
     };
   }
+  // 能力透传（与壳 resources.go 对齐）：URL 直载 / 单实例 / 自动更新。
+  if (typeof cfg.url === 'string' && cfg.url) obj.url = cfg.url;
+  if (cfg.singleInstance === true) obj.singleInstance = true;
+  if (cfg.updater && typeof cfg.updater.manifestURL === 'string' && typeof cfg.updater.publicKey === 'string'
+      && cfg.updater.manifestURL && cfg.updater.publicKey) {
+    obj.updater = {
+      manifestURL: cfg.updater.manifestURL,
+      publicKey: cfg.updater.publicKey,
+      requireSignature: cfg.updater.requireSignature === true ? true : undefined,
+    };
+  }
   return JSON.stringify(obj, null, 2);
 }
 
@@ -579,7 +685,7 @@ function warnIfNotSingleFile(html, distHtml) {
   }
 }
 
-// 递归收集目录内所有文件：relPath（POSIX 相对路径）-> Buffer 内容，供 .integrity 完整性清单使用。
+// 递归收集目录内所有文件：relPath（POSIX 相对路径）-> Buffer 内容，供 high 模式入容器。
 function collectDirFiles(dir, prefix, out) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const abs = path.join(dir, entry.name);
@@ -592,4 +698,27 @@ function collectDirFiles(dir, prefix, out) {
   return out;
 }
 
+// 文件权限位（POSIX mode 低 12 位）：进容器后由壳在临时目录还原（执行位决定后端能否直接跑）。
+function fileMode(abs) {
+  try {
+    return fs.statSync(abs).mode & 0o7777;
+  } catch (e) {
+    return 0o644;
+  }
+}
+
+// 抹掉前端页内的 source map 引用（JS 的 //# sourceMappingURL=…、CSS 的 /*# … */）。
+// 返回 { html, stripped }。
+function stripSourceMapRefs(html) {
+  let stripped = 0;
+  const out = String(html).replace(
+    /\/\/[#@]\s*sourceMappingURL=[^\r\n]*|\/\*#\s*sourceMappingURL=[\s\S]*?\*\//g,
+    () => {
+      stripped += 1;
+      return '';
+    },
+  );
+  return { html: out, stripped };
+}
+
 module.exports = { build, parsePlatforms };

package/lib/cli.js

@@ -19,8 +19,11 @@ function help() {
   L.push(`  ${paint('用法：', C.bold, C.fg.white)} ${paint('freedom <command> [options]', C.fg.cyan, C.bold)}`);
   L.push('');
   L.push(section('交互式界面'));
-  L.push(`  ${paint('freedom', C.fg.cyan, C.bold)}                  ${dim('进入完整 CLI 模式（交互式菜单，新建 / 打包 / 配置 / 壳管理）')}`);
-  L.push(`  ${paint('freedom tui', C.fg.cyan, C.bold)}              ${dim('同上（兼容写法，显式进入交互式模式）')}`);
+  L.push(`  ${paint('freedom', C.fg.cyan, C.bold)}                  ${dim('选择显示方式：终端 TUI / Freedom Desktop（图形界面）')}`);
+  L.push(`  ${paint('freedom tui', C.fg.cyan, C.bold)}              ${dim('直达终端 TUI（交互式菜单，新建 / 打包 / 配置 / 壳管理）')}`);
+  L.push(`  ${paint('freedom desktop', C.fg.cyan, C.bold)}          ${dim('直达 Freedom Desktop：图形界面由 freedom 自己打包产出，模板或版本变更时自动重打包')}`);
+  L.push(`      ${dim('--rebuild')}                       ${dim('强制重新打包 Desktop 并拉起（需先关闭已开窗口）')}`);
+  L.push(`      ${dim('--no-launch')}                     ${dim('只准备 / 重打包产物，不拉起窗口')}`);
   L.push(section('项目'));
   L.push(`  ${paint('freedom init [目录] [--force] [--template full|minimal]', C.fg.cyan)}  ${dim('新建项目模板（默认 full：含自绘标题栏示例；minimal：极简无自绘标题栏）')}`);
   L.push(`  ${paint('freedom tutorial', C.fg.cyan)}                 ${dim('再次打开安装教程')}`);
@@ -28,8 +31,14 @@ function help() {
   L.push(`  ${paint('freedom build [--platform <p>]', C.fg.cyan)}   ${dim('前端打包并分发桌面应用（默认当前平台）')}`);
   L.push(`      ${dim('--platform win|mac|linux|all')}    ${dim('指定目标平台（all = 三平台全量）')}`);
   L.push(`      ${dim('--no-cache')}                      ${dim('忽略前端构建缓存，强制重新打包')}`);
+  L.push(`      ${dim('--security <none|basic|high>')}    ${dim('资源安全模式（high = resources 加密为 app.bin）')}`);
+  L.push(`      ${dim('--installer')}                     ${dim('附带安装包产物：便携 zip + Windows NSIS 安装器（有 makensis 时编译 setup.exe，否则产出已填充的 .nsi）')}`);
   L.push(`  ${paint('freedom verify [--platform <p>]', C.fg.cyan)}   ${dim('校验已构建产物完整性并打印产物结构（CI 可依赖退出码）')}`);
   L.push(`  ${paint('freedom dmg [--platform <plat>]', C.fg.cyan)}  ${dim('将已构建的 .app 打包为 .dmg（需 macOS）')}`);
+  L.push(section('开发与更新'));
+  L.push(`  ${paint('freedom dev [--port <n>|--url <u>] [--command <cmd>]', C.fg.cyan)} ${dim('dev server 联调壳窗口：HMR 热更，改码免重打包')}`);
+  L.push(`  ${paint('freedom keygen', C.fg.cyan)}              ${dim('生成应用自更新 ed25519 密钥对（公钥进配置，私钥发布方保管）')}`);
+  L.push(`  ${paint('freedom manifest --artifact <产物> --url <下载地址> [--version x]', C.fg.cyan)} ${dim('产出签名的更新清单 latest.json')}`);
   L.push(section('外观'));
   L.push(`  ${paint('freedom titlebar <native|frameless>', C.fg.cyan)} ${dim('一键切换标题栏策略')}`);
   L.push(`  ${paint('freedom icon <path>', C.fg.cyan)}     ${dim('设置应用图标（Win .ico / mac .icns）')}`);
@@ -41,6 +50,12 @@ function help() {
   L.push(`  ${paint('freedom config', C.fg.cyan)}              ${dim('查看当前配置')}`);
   L.push(`  ${paint('freedom config get <key>', C.fg.cyan)}    ${dim('读取单个配置项')}`);
   L.push(`  ${paint('freedom config set <key> <value>', C.fg.cyan)} ${dim('修改单个配置项')}`);
+  L.push(section('Agent 集成'));
+  L.push(`  ${paint('freedom agents [--home <dir>]', C.fg.cyan)}          ${dim('打印 Agent 支持矩阵（按本机磁盘证据判定 ready / convention / unknown）')}`);
+  L.push(`  ${paint('freedom agents install --what <mcp|skill> --agent <key|all>', C.fg.cyan)} ${dim('等价于下面两条的合并入口')}`);
+  L.push(`  ${paint('freedom skill install --agent <key|all> [--dry-run] [--skills-dir <path>]', C.fg.cyan)} ${dim('把 Freedom 使用技能装入 agent 的 skills 目录')}`);
+  L.push(`  ${paint('freedom mcp install --agent <key|all> [--dry-run] [--config <path> --format json|toml|yaml]', C.fg.cyan)} ${dim('把 Freedom MCP 服务写入 agent 的 MCP 配置（幂等合并、写前 .bak 备份）')}`);
+  L.push(`  ${paint('freedom mcp serve', C.fg.cyan)}        ${dim('stdio MCP 服务本体（一般由 agent 自动拉起，无需手敲）')}`);
   L.push(section('版本'));
   L.push(`  ${paint('freedom version', C.fg.cyan)}             ${dim('显示版本并检测最新版本')}`);
   L.push(`  ${paint('freedom update', C.fg.cyan)}              ${dim('检查新版本并立即自动更新')}`);
@@ -66,9 +81,10 @@ async function run(argv) {
 
   switch (cmd) {
     case undefined: {
-      // 无参数：交互式终端进入完整 CLI 模式（TUI）；管道 / 脚本环境打印帮助，避免卡死
+      // 无参数：交互式终端先选择显示方式（终端 TUI / Freedom Desktop）；
+      // 管道 / 脚本环境打印帮助，避免卡死
       if (process.stdin.isTTY && process.stdout.isTTY) {
-        return await require('./tui').tui(process.cwd());
+        return await require('./tui').pickDisplay(process.cwd());
       }
       console.log(help());
       return 0;
@@ -112,6 +128,48 @@ async function run(argv) {
     case 'tui':
       return await require('./tui').tui(process.cwd());
 
+    case 'desktop': {
+      const { desktop } = require('./desktop');
+      try {
+        const r = await desktop({
+          rebuild: rest.includes('--rebuild'),
+          noLaunch: rest.includes('--no-launch'),
+        });
+        console.log(`${ok(r.rebuilt ? '已重新打包 Freedom Desktop：' : '复用已有产物：')}${paint(r.exe, C.fg.cyan, C.bold)}`);
+        console.log(`  ${dim(`项目目录：${r.dir} · CLI v${r.version}`)}`);
+        if (r.launched) console.log(`  ${ok(`窗口已拉起（pid ${r.pid}）`)}`);
+        else console.log(`  ${dim('未拉起窗口（--no-launch）；执行 freedom desktop 即可打开。')}`);
+        return 0;
+      } catch (e) {
+        console.error(`${err(e.message)}`);
+        return 1;
+      }
+    }
+
+    case 'agents': {
+      const sub = rest[0] && !rest[0].startsWith('--') ? rest[0] : undefined;
+      const flags = sub ? rest.slice(1) : rest;
+      const hi = flags.indexOf('--home');
+      const home = flags.find((a) => a.startsWith('--home=')) || (hi >= 0 ? flags[hi + 1] : undefined);
+      if (home && !home.startsWith('--')) process.env.FREEDOM_AGENT_HOME = path.resolve(home.replace(/^--home=/, ''));
+      if (!sub || sub === 'list') return require('./agents').printMatrix();
+      if (sub !== 'install') {
+        console.error(`${err(`未知 agents 子命令：${sub}`)} ${dim('可用：list / install --what <mcp|skill> --agent <key|all> [--dry-run]')}`);
+        return 1;
+      }
+      const wi = flags.indexOf('--what');
+      const what = (flags.find((a) => a.startsWith('--what=')) || '').split('=')[1] || flags[wi + 1];
+      if (what && what !== 'mcp' && what !== 'skill') {
+        console.error(`${err(`不支持的 --what：${what}`)} ${dim('（可选 mcp|skill）')}`);
+        return 1;
+      }
+      return await runAgents(what === 'skill' ? 'skill' : 'mcp', ['install', ...flags]);
+    }
+
+    case 'skill':
+    case 'mcp':
+      return await runAgents(cmd, rest);
+
     case 'init': {
       const force = rest.includes('--force');
       const tmplArg = rest.find((a) => a.startsWith('--template'));
@@ -140,6 +198,62 @@ async function run(argv) {
       return 0;
     }
 
+    case 'dev': {
+      const optVal = (name) => {
+        const a = rest.find((x) => x.startsWith(`--${name}=`));
+        if (a) return a.split('=')[1];
+        const i = rest.indexOf(`--${name}`);
+        return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : undefined;
+      };
+      const url = optVal('url');
+      const port = optVal('port');
+      const { dev: runDev } = require('./dev');
+      try {
+        const done = await runDev({ dir: process.cwd(), url, port: port ? Number(port) : undefined, command: optVal('command') });
+        console.log(`${ok(String(done))}`);
+      } catch (e) {
+        console.error(`${err(e.message)}`);
+        return 1;
+      }
+      return 0;
+    }
+
+    case 'keygen': {
+      const { keygen } = require('./release');
+      try {
+        console.log(await keygen({ dir: process.cwd(), force: rest.includes('--force') }));
+      } catch (e) {
+        console.error(`${err(e.message)}`);
+        return 1;
+      }
+      return 0;
+    }
+
+    case 'manifest': {
+      const optVal = (name) => {
+        const a = rest.find((x) => x.startsWith(`--${name}=`));
+        if (a) return a.split('=')[1];
+        const i = rest.indexOf(`--${name}`);
+        return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : undefined;
+      };
+      const { manifest } = require('./release');
+      try {
+        console.log(await manifest({
+          dir: process.cwd(),
+          artifact: optVal('artifact'),
+          url: optVal('url'),
+          version: optVal('version'),
+          notes: optVal('notes'),
+          key: optVal('key'),
+          out: optVal('out'),
+        }));
+      } catch (e) {
+        console.error(`${err(e.message)}`);
+        return 1;
+      }
+      return 0;
+    }
+
     case 'build': {
       const platArg = rest.find((a) => a.startsWith('--platform') || a.startsWith('-p'));
       let platform;
@@ -171,9 +285,13 @@ async function run(argv) {
         platform,
         noCache: rest.includes('--no-cache'),
         security,
+        installer: rest.includes('--installer'),
       });
       for (const r of results) {
         console.log(`${ok('构建完成')} ${paint(`[${r.plat}]`, C.fg.magenta, C.bold)} ${paint(r.outFile, C.fg.white)}`);
+        for (const p of r.installers || []) {
+          console.log(`  ${dim('安装包产物：')}${paint(p, C.fg.white)}`);
+        }
       }
       return 0;
     }
@@ -368,6 +486,44 @@ async function runShell(rest) {
   }
 }
 
+// freedom skill / mcp —— Agent 集成安装与 MCP 服务
+async function runAgents(cmd, rest) {
+  const sub = rest[0];
+  const optVal = (name) => {
+    const a = rest.find((x) => x.startsWith(`--${name}=`));
+    if (a) return a.split('=')[1];
+    const i = rest.indexOf(`--${name}`);
+    return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : undefined;
+  };
+  if (cmd === 'mcp' && sub === 'serve') {
+    return await require('./mcp').serve();
+  }
+  if (sub !== 'install') {
+    console.error(`${err('用法：')}${paint(`freedom ${cmd} install --agent <key|all> [--dry-run]`, C.fg.cyan)}`);
+    if (cmd === 'mcp') {
+      console.error(`     ${paint('freedom mcp serve', C.fg.cyan)} ${dim('（stdio MCP 服务，通常由 agent 配置自动拉起）')}`);
+    }
+    console.error(`  ${dim('可选 agent 与本机取证状态见：')}${paint('freedom agents', C.fg.white)}`);
+    return 1;
+  }
+  const { install } = require('./agents');
+  try {
+    const r = await install({
+      what: cmd === 'skill' ? 'skill' : 'mcp',
+      agent: optVal('agent') || 'all',
+      dryRun: rest.includes('--dry-run'),
+      config: optVal('config'),
+      format: optVal('format'),
+      skillsDir: optVal('skills-dir'),
+      home: optVal('home'),
+    });
+    return r.code;
+  } catch (e) {
+    console.error(`${err(e.message)}`);
+    return 1;
+  }
+}
+
 // freedom dmg：在 macOS 上把已构建的 .app 打包为 .dmg（依赖系统 hdiutil）
 async function runDmg(rest) {
   const { loadConfig, nativePlatform } = require('./utils');

package/lib/config.js

@@ -17,6 +17,8 @@ const KEY_TYPES = {
   security: 'security',
   icon: 'string',
   outDir: 'string',
+  url: 'string',
+  singleInstance: 'bool',
 };
 
 // 把 CLI/TUI 传入的值规范化为配置语义上的目标值；非法即抛错。
@@ -115,7 +117,21 @@ function setConfig(dir, key, value) {
     break;
   }
   if (!replaced) {
-    throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到（注释行不参与修改），请手动添加。`);
+    // 模板里的新能力键（url / singleInstance）默认是注释示例，用户不必先手动取消注释：
+    // 找不到未注释的键就在结尾 `};` 前插入一行，仍保持 `freedom config set` 一条命令可用。
+    let endIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (/^\s*\}\s*;?\s*$/.test(lines[i])) {
+        endIdx = i;
+        break;
+      }
+    }
+    if (endIdx < 0) {
+      throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到（注释行不参与修改），请手动添加。`);
+    }
+    lines.splice(endIdx, 0, `  ${key}: ${rendered},`);
+    fs.writeFileSync(cfgPath, lines.join('\n'), 'utf8');
+    return norm;
   }
   fs.writeFileSync(cfgPath, lines.join('\n'), 'utf8');
   return norm;
@@ -143,6 +159,8 @@ const KNOWN_KEYS = {
   security: 'none',
   icon: undefined,
   outDir: 'dist',
+  url: undefined,
+  singleInstance: false,
 };
 
 async function showConfig(dir) {
@@ -152,6 +170,7 @@ async function showConfig(dir) {
     return `  ${k}: ${JSON.stringify(v)}`;
   });
   lines.push(`  backend: ${cfg.backend ? JSON.stringify(cfg.backend) : 'undefined'}`);
+  lines.push(`  updater: ${cfg.updater ? JSON.stringify(cfg.updater) : 'undefined'}`);
   return lines.join('\n');
 }