@yufengtadian/freedom-cli 1.13.1 → 1.13.3

package/lib/cli.js

@@ -5,7 +5,7 @@ const path = require('path');
 const { init } = require('./init');
 const { build } = require('./build');
 const { setConfig, showConfig } = require('./config');
-const { packageRoot, tutorialFile } = require('./utils');
+const { packageRoot, tutorialFile, normalizePlatform } = require('./utils');
 const theme = require('./theme');
 const update = require('./update');
 
@@ -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,17 @@ 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 toolchain', C.fg.cyan)}                ${dim('探测 Go / Rust / C++ 工具链是否就位（已配置好则走缓存、不重复探测）')}`);
+  L.push(`  ${paint('freedom toolchain install [go,rust,cpp|missing] [--apply]', C.fg.cyan)} ${dim('缺失时自动安装；缺省只打印命令，--apply 才真跑（联网 + 提权）')}`);
+  L.push(`  ${paint('freedom toolchain optimize [--apply]', C.fg.cyan)} ${dim('自动优化配置：Go GOPROXY 镜像、cargo 源换 rsproxy（幂等 + .bak）')}`);
+  L.push(`  ${paint('freedom toolchain status --refresh', C.fg.cyan)}  ${dim('强制重新探测并刷新缓存（默认缓存 7 天，PATH 变更即失效）')}`);
   L.push(section('版本'));
   L.push(`  ${paint('freedom version', C.fg.cyan)}             ${dim('显示版本并检测最新版本')}`);
   L.push(`  ${paint('freedom update', C.fg.cyan)}              ${dim('检查新版本并立即自动更新')}`);
@@ -66,9 +86,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 +133,52 @@ 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] [--force]')}`);
+        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 'toolchain':
+    case 'tc':
+      return toolchainCommand(rest);
+
+    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 +207,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 +294,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;
     }
@@ -344,21 +471,21 @@ async function runShell(rest) {
     case 'download': {
       const plat = rest[1];
       if (!plat) {
-        console.error(`${err('用法：')}${paint('freedom shell download <win-x64|darwin-arm64|linux-x64|linux-arm64>', C.fg.cyan)}`);
+        console.error(`${err('用法：')}${paint('freedom shell download <win|mac|linux|all 或 win-x64 / darwin-arm64 / linux-x64 / linux-arm64>', C.fg.cyan)}`);
         return 1;
       }
       const dest = await downloadShell(plat);
-      console.log(`${ok('已下载')} ${paint(plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
+      console.log(`${ok('已下载')} ${paint(normalizePlatform(plat) || plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
       return 0;
     }
     case 'build': {
       const plat = rest[1];
       if (!plat) {
-        console.error(`${err('用法：')}${paint('freedom shell build <win-x64|darwin-arm64|linux-x64|linux-arm64>', C.fg.cyan)}`);
+        console.error(`${err('用法：')}${paint('freedom shell build <win|mac|linux 或 win-x64 / darwin-arm64 / linux-x64 / linux-arm64>', C.fg.cyan)}`);
         return 1;
       }
       const dest = buildShell(plat);
-      console.log(`${ok('已编译')} ${paint(plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
+      console.log(`${ok('已编译')} ${paint(normalizePlatform(plat) || plat, C.fg.magenta, C.bold)} ${dim('壳：')}${paint(dest, C.fg.white)}`);
       console.log(`  ${dim('提示：壳已预编译随包分发，一般无需本地编译。')}`);
       return 0;
     }
@@ -368,6 +495,45 @@ 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] [--force]`, 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'),
+      force: rest.includes('--force'),
+      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');
@@ -407,6 +573,89 @@ async function runDmg(rest) {
   }
 }
 
+// freedom toolchain —— 工具链自动装配：探测（带缓存）/ 安装（默认只打印）/ 配置优化。
+function toolchainCommand(rest) {
+  const tc = require('./toolchain');
+  const flags = new Set();
+  const pos = [];
+  let homeArg;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--home') { homeArg = rest[++i]; continue; }
+    if (a.startsWith('--home=')) { homeArg = a.slice('--home='.length); continue; }
+    if (a.startsWith('--')) { flags.add(a); continue; }
+    pos.push(a);
+  }
+  const sub = pos[0];
+  const opts = {
+    refresh: flags.has('--refresh'),
+    apply: flags.has('--apply'),
+    home: homeArg ? path.resolve(homeArg) : undefined,
+  };
+  const out = [];
+  switch (sub) {
+    case undefined:
+    case 'status': {
+      const { rows, skipped } = tc.status(opts);
+      for (const r of rows) {
+        if (r.ok) out.push(`  ${ok('已就位')} ${paint(r.key, C.fg.cyan, C.bold)} ${dim(r.version + '  ' + r.exe)} ${r.cached ? dim('[缓存]') : dim('[探测]')}`);
+        else out.push(`  ${err('缺失')}   ${paint(r.key, C.fg.cyan, C.bold)} ${dim(r.reason || '未检测到')} ${dim('· ' + r.why)}`);
+      }
+      out.push('');
+      const cacheNote = skipped ? `本轮跳过 ${skipped} 次探测（缓存命中，PATH 变更或 --refresh 即失效）` : '本轮全部实探';
+      out.push(['  ', dim(cacheNote) + '；', dim('安装：'), paint('freedom toolchain install missing', C.fg.cyan),
+        dim('（默认只打印命令，加 --apply 才执行）')].join(' '));
+      console.log(out.join('\n'));
+      return 0;
+    }
+    case 'install': {
+      const res = tc.install(pos[1] || 'missing', opts);
+      for (const r of res.rows) {
+        if (r.action === 'skip') console.log(`  ${ok(`[${r.key}] 已就位`)} ${dim(r.version || '')}`);
+        else if (r.action === 'manual') console.log(`  ${warn(`[${r.key}] 本平台无自动安装方式`)} ${dim(r.note)}`);
+        else if (r.action === 'plan') {
+          console.log(`  ${warn(`[${r.key}] 待安装`)} ${dim('以下为将执行的命令：')}`);
+          for (const c of r.commands) console.log(`    ${paint(c, C.fg.white)}`);
+        } else if (r.action === 'applied') {
+          for (const s of r.ran) {
+            console.log(`  ${s.status === 0 ? ok('[完成]') : err('[失败]')} ${dim(s.command)} ${s.status === 0 ? '' : err(`退出码 ${s.status}`)}`);
+          }
+        }
+      }
+      if (res.dryRun) {
+        console.log('');
+        console.log(`  ${tip('确认无误后加 --apply 真正执行安装（联网、可能需要管理员权限）。')}`);
+      } else {
+        console.log(`  ${dim('安装后若 PATH 未刷新，重新打开终端或执行 freedom toolchain status --refresh。')}`);
+      }
+      return res.rows.some((r) => r.action === 'applied' && r.ran.some((s) => s.status !== 0)) ? 1 : 0;
+    }
+    case 'optimize': {
+      const res = tc.optimize(opts);
+      for (const r of res.rows) {
+        if (r.action === 'skip') console.log(`  ${ok(`[${r.key}] 无需优化`)} ${dim(r.note)}`);
+        else if (r.action === 'blocked') console.log(`  ${warn(`[${r.key}] 跳过`)} ${dim(r.note)}`);
+        else if (r.action === 'report') console.log(`  ${r.ok ? ok(`[${r.key}] 已就位`) : warn(`[${r.key}] 未就位`)} ${dim(r.note)}`);
+        else if (r.action === 'plan') {
+          console.log(`  ${warn(`[${r.key}] 将优化`)} ${dim(r.from ? `当前：${r.from}` : '')}`);
+          for (const c of (r.commands || [])) console.log(`    ${paint(c, C.fg.white)}`);
+          if (r.file) console.log(`    ${dim(r.file)} ${dim('（幂等合并，写前 .bak）')}`);
+        } else if (r.action === 'applied') {
+          console.log(`  ${ok(`[${r.key}] 已优化`)} ${dim(r.to || r.file || '')}${r.backup ? dim('  备份 ' + r.backup) : ''}${r.status ? err(`  退出码 ${r.status}`) : ''}`);
+        }
+      }
+      if (res.dryRun) console.log(`\n  ${tip('以上为拟写入内容，未改动任何文件；加 --apply 生效（写入前自动 .bak 备份）。')}`);
+      return 0;
+    }
+    case 'clear':
+      console.log(tc.clearCache(opts) ? `${ok('缓存已清除，下一次 status 将重新探测。')}` : `${dim('无缓存可清除。')}`);
+      return 0;
+    default:
+      console.error(`${err(`未知 toolchain 子命令：${sub}`)} ${dim('可用：status / install [go,rust,cpp|missing] / optimize / clear')}`);
+      return 1;
+  }
+}
+
 function openBrowser(file) {
   const { spawn } = require('child_process');
   const plat = process.platform;

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');
 }
 

package/lib/desktop.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// freedom desktop —— Freedom Desktop：用 freedom 自己打包出来的图形界面（自举）
+//
+// 链路：templates/desktop/* 同步到 ~/.freedom/desktop/ → 经与用户项目同一条 build()
+// 代码路径产出（staticHtml 直通，免 npm / 免 vite / 免网络）→ 拉起该壳。
+// 壳内前端通过 NDJSON 进程后端调起 freedom CLI 子进程，界面能力即 CLI 能力。
+//
+// stamp = CLI 版本 + 模板内容哈希；不匹配（或产物缺失、--rebuild）即自动重打包，幂等。
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { packageRoot, templateDir, nativePlatform, platformExeName } = require('./utils');
+
+const APP_NAME = 'freedom-desktop';
+const STAMP_FILE = '.freedom-desktop.json';
+
+function cliVersion() {
+  return require(path.join(packageRoot(), 'package.json')).version;
+}
+
+function desktopDir() {
+  return path.join(os.homedir(), '.freedom', 'desktop');
+}
+
+function templateRoot() {
+  return path.join(templateDir(), 'desktop');
+}
+
+function walk(root, rel = '', out = []) {
+  for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) walk(root, r, out);
+    else out.push(r);
+  }
+  return out.sort();
+}
+
+// 把模板文件拷入工作目录，并补齐两份运行时元数据：
+//   backend/cli-entry.json —— Desktop 后端据此以子进程方式定位 freedom CLI 入口
+//   package.json —— 声明 type:module（freedom.config.js 用 ESM 书写）与产物版本
+function sync(dir) {
+  const src = templateRoot();
+  if (!fs.existsSync(src)) throw new Error(`缺少 Desktop 模板目录：${src}`);
+  const files = walk(src);
+  for (const rel of files) {
+    const dest = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(src, rel), dest);
+  }
+  const entry = path.join(packageRoot(), 'bin', 'freedom.js');
+  writeIfChanged(path.join(dir, 'backend', 'cli-entry.json'),
+    JSON.stringify({ entry, root: packageRoot(), version: cliVersion() }, null, 2) + '\n');
+  writeIfChanged(path.join(dir, 'package.json'),
+    JSON.stringify({ name: APP_NAME, private: true, version: cliVersion(), type: 'module' }, null, 2) + '\n');
+  return files;
+}
+
+function writeIfChanged(file, content) {
+  let cur = null;
+  try { cur = fs.readFileSync(file, 'utf8'); } catch (e) { /* 首次写入 */ }
+  if (cur !== content) fs.writeFileSync(file, content, 'utf8');
+}
+
+function stampOf(files) {
+  const h = crypto.createHash('sha256');
+  h.update(`cli:${cliVersion()}\n`);
+  for (const rel of files) {
+    h.update(`${rel}\0`);
+    h.update(fs.readFileSync(path.join(templateRoot(), rel)));
+    h.update('\0');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+function resolveExe(dir, plat) {
+  if (plat.startsWith('darwin')) {
+    // mac 产物会升级为 .app bundle，可执行文件在 Contents/MacOS 下
+    return [path.join(dir, 'dist', `${APP_NAME}.app`, 'Contents', 'MacOS', APP_NAME),
+      path.join(dir, 'dist', APP_NAME)].find((p) => fs.existsSync(p)) || path.join(dir, 'dist', APP_NAME);
+  }
+  return path.join(dir, 'dist', platformExeName(plat, APP_NAME));
+}
+
+// 打包（幂等）：产物缺失 / stamp 变更 / rebuild 时执行，其余情况直接复用上次产物。
+async function ensure({ rebuild = false } = {}) {
+  const dir = desktopDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const files = sync(dir);
+  const stamp = stampOf(files);
+  const plat = nativePlatform();
+  const exe = resolveExe(dir, plat);
+  let prev = null;
+  try { prev = JSON.parse(fs.readFileSync(path.join(dir, STAMP_FILE), 'utf8')); } catch (e) { /* 未构建过 */ }
+
+  const stale = rebuild || !fs.existsSync(exe) || !prev || prev.stamp !== stamp;
+  if (stale) {
+    if (fs.existsSync(exe)) {
+      // Windows 下运行中的 exe 被系统锁定；先探测并给出可执行的指示，而不是抛底层 EBUSY/EPERM
+      try { fs.unlinkSync(exe); } catch (e) {
+        throw new Error(`正在运行的 Freedom Desktop 锁定了自身可执行文件（${exe}）：请先关闭其窗口，再执行 freedom desktop${rebuild ? ' --rebuild' : ''}。`);
+      }
+    }
+    process.stdout.write(`[freedom] ${fs.existsSync(exe) ? 'Desktop 模板或 CLI 版本已变更，重新打包中…' : '首次运行：正在用 freedom 打包 Freedom Desktop…'}\n`);
+    const { build } = require('./build');
+    await build(dir, { platform: plat, noCache: true });
+    fs.writeFileSync(path.join(dir, STAMP_FILE),
+      JSON.stringify({ stamp, version: cliVersion(), plat, builtAt: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+  }
+  return { dir, exe, plat, rebuilt: stale, version: cliVersion() };
+}
+
+function launch(exe, dir) {
+  const child = spawn(exe, [], {
+    cwd: path.dirname(exe),
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, FREEDOM_DESKTOP_DIR: dir },
+  });
+  child.unref();
+  return child.pid;
+}
+
+async function desktop({ rebuild = false, noLaunch = false } = {}) {
+  const r = await ensure({ rebuild });
+  if (noLaunch) return { ...r, launched: false };
+  return { ...r, launched: true, pid: launch(r.exe, r.dir) };
+}
+
+module.exports = { desktop };