@yufengtadian/freedom-cli 1.13.1 → 1.13.2

package/README.md

@@ -1,16 +1,17 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.1）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.2）。
 
 基于自研 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 壳内存解密已有跨语言黄金向量与端到端互验（改名 / 篡改即拒绝运行）；
+- **运行时资源层回归**：壳从 exe 同目录 `resources/` 读取 `config.json`（窗口 / 后端配置覆盖）与前端页面，high 模式下前端页面、配置与 **`backend/**` 后端源码**统一封进加密 `app.bin`（FRDM2 容器：构建期随机盐 + PBKDF2 60 万次派生 + Encrypt-then-MAC 覆盖头部）+ `.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.13.2 反逆向加固（FRDM2）**：容器升 FRDM2（构建期随机盐 + PBKDF2 60 万次 + enc/mac 域分离 + MAC 覆盖容器头部），主密钥改为掩码表运行时组装（壳二进制 `strings` 直取不到），`backend/**` 后端源码一并入容器并在运行期解密到私有临时目录（退出即删、崩溃残留按 PID 回收），前端产物 `sourceMappingURL` 构建期抹除，anti-debug 扩到六道信号，本地与 CI 壳统一 `-trimpath -s -w`。**旧版本 CLI 产出的 FRDM1 资源包在新壳上明确拒绝运行（不静默降级），须重新 `freedom build`**；三平台壳随本版本经 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 壳的缺口。
 
@@ -169,6 +170,14 @@ export default {
   icon: undefined,       // 应用图标：Windows 用 .ico（推荐多尺寸），macOS 用 .icns
   outDir: 'dist',        // 产物目录：'dist'（默认）| '.'（项目根目录）| 任意路径
   // backend: { command: 'node', args: ['backend/main.mjs'] },  // 任意语言后端进程
+  // staticHtml: 'app.html', // 跳过 npm/vite，直接内嵌该单文件 HTML（零网络；纯静态页与 freedom 自举界面用）
+  // singleInstance: true,   // 二次启动转发参数给已运行实例后退出（前端收 app.secondInstance）
+  // dev: { command: 'npm run dev' },  // freedom dev 拉起的前端 dev server 命令
+  // updater: {                       // 应用自更新（freedom keygen 生成密钥，公钥填这里）
+  //   manifestURL: 'https://your.host/latest.json',
+  //   publicKey: '<freedom keygen 输出的 base64 公钥>',
+  //   requireSignature: false,       // true 时产物还须通过平台代码签名复核（仅 Windows）
+  // },
 };
 ```
 
@@ -185,7 +194,7 @@ export default {
 | --- | --- | --- | --- |
 | `none` | 明文 `index.html` + `config.json`（默认，兼容历史产物） | 解包即读 | 公开页面 / 调试 / 快速分发 |
 | `basic` | 同上明文，构建时额外输出加固建议 | 低 | 需要提示、暂不加密 |
-| `high` | 整体加密为 `resources/app.bin` + `.integrity`，磁盘**无任何明文** HTML/配置 | 高（需逆向壳 + 还原派生密钥） | 防源码提取、防资源篡改的正式分发 |
+| `high` | 前端 HTML + 配置 + **后端源码**整体加密为 `resources/app.bin` + `.integrity`，磁盘**无任何明文** | 高（需逆向壳 + 还原派生密钥） | 防源码提取、防资源篡改的正式分发 |
 
 **切换方式**（二选一，`--security` 可临时覆盖配置文件）：
 
@@ -195,16 +204,18 @@ freedom build --security high        # 单次构建生效（不改配置）
 freedom build                        # 读取配置中的 security 值
 ```
 
-**high 模式原理**：
-- 构建时：前端 HTML + 配置序列化后，用 **AES-256-CTR** 加密为 `app.bin`（容器头 `FRDM1` + 16B IV + 16B 认证标签），并生成 `.integrity` 完整性清单（`app.bin` 与 `backend/**` 各文件的 HMAC-SHA256）；
-- 加密密钥由 **PBKDF2-HMAC-SHA256**（6 万次迭代）按「应用可执行文件名」派生，不同应用密钥不同，暴力破解成本高；
-- 壳启动时：先校验 `.integrity`（防整体替换 / 篡改 / exe 改名），再恒定时间比对 HMAC 认证标签（Encrypt-then-MAC），最后内存中解密加载——**磁盘始终无明文**；
-- 解密 / 校验失败即拒绝运行（不静默回退明文，防降级攻击）；
-- 另内置 **anti-debug**（`IsDebuggerPresent` / `CheckRemoteDebuggerPresent` 命中即退出）与进程隐藏加固。
+**high 模式原理（FRDM2 容器）**：
+- 容器布局：`FRDM2`(5B) + `salt`(16B，**每次构建随机**) + `iv`(16B) + `tag`(16B) + 密文；密钥 = **PBKDF2-HMAC-SHA256**（60 万次迭代，主密钥经字节表掩码内置于壳与 CLI）按「应用可执行文件名 + 容器随机盐」派生，再由固定标签做 **HMAC 域分离**得到独立的加密钥与认证钥；
+- 认证为 **Encrypt-then-MAC 且覆盖容器头部**（magic/salt/iv 参与计算），故改盐、改 IV、翻转任意一字节都会认证失败；`.integrity` 清单绑定同一盐值，**整体替换成另一个合法容器**同样拒绝运行；
+- **后端源码不再明文落盘**：`backend/**`（含 POSIX 权限位）作为条目进入容器，磁盘上不再有 `resources/backend/`；壳启动解密到仅属主可访问的一次性临时目录（0700 / 文件 0600，执行位按容器记录还原）供子进程执行，进程退出即删除；若被强杀或崩溃来不及删，**下次启动会按目录名内嵌的 PID 自动回收残留**；
+- 构建期抹除前端产物中的 `sourceMappingURL` 引用（防 source map 还原源码），壳二进制一律 `-trimpath -ldflags "-s -w"`（Windows 另加 `-H windowsgui`）；
+- 解密 / 校验失败即拒绝运行（不静默回退明文，防降级攻击；旧版 `FRDM1` 容器明确报"版本不支持"）；
+- 另内置 **anti-debug**：`IsDebuggerPresent`、`CheckRemoteDebuggerPresent`、直读 `PEB.BeingDebugged`、`NtQueryInformationProcess` 的 `ProcessDebugPort` / `ProcessDebugObjectHandle` / `ProcessDebugFlags` 共六道独立信号，任一确证即静默退出（退出码 77），在资源解密前后各检测一次；所有探测遵循"取不到即视为未命中"，杜绝误杀；
+- 进程隐藏加固（`-H windowsgui`，无控制台窗口）。
 
-**加固上限说明**：`high` 大幅提高破解门槛，但**任何客户端可执行程序都无法做到绝对不可破解**——密钥最终存在于壳二进制与运行时内存中。更高强度建议：壳编译时设置 `-ldflags "-s -w"` 剥离符号表（CI 编译壳时已可选开启）、对核心业务保留服务端校验。若需"怎么都解不开"，请把真正敏感的密钥 / 逻辑放到你的后端。
+**加固上限说明**：`high` 大幅提高破解门槛，但**任何客户端可执行程序都无法做到绝对不可破解**——密钥最终存在于壳二进制与运行时内存中，反调试只抬升动态分析成本、不是不可绕过的墙。真正敏感的密钥与业务逻辑仍应留在服务端。
 
-**互斥规则**：切换安全模式重新构建时，CLI 会自动清理另一模式的遗留产物（`app.bin`/`.integrity` 与明文 `index.html`/`config.json` 只能存其一），避免壳误加载旧资源。
+**互斥规则**：切换安全模式重新构建时，CLI 会自动清理另一模式的遗留产物（`app.bin`/`.integrity` 与明文 `index.html`/`config.json`/`backend/` 只能存其一），避免壳误加载旧资源。
 
 ## 前端
 
@@ -226,21 +237,84 @@ window.freedom.window.minimize();                       // 窗口控制
 ## 命令
 
 ```
-freedom tui                          # 交互式终端界面
+freedom                              # 选择显示方式：终端 TUI / Freedom Desktop（图形界面）
+freedom tui                          # 直达交互式终端界面
+freedom desktop [--rebuild] [--no-launch]   # 直达 Freedom Desktop（图形界面，由 freedom 自身打包）
 freedom init <目录> [--force]
-freedom build [--platform win-x64|darwin-arm64|linux-x64|all] [--no-cache] [--security none|basic|high]
+freedom dev [--port <n>|--url <u>] [--command <cmd>]   # 热更开发流：拉起 vite 并把壳窗口指到 dev server
+freedom build [--platform win-x64|darwin-arm64|linux-x64|all] [--no-cache] [--security none|basic|high] [--installer]
 freedom titlebar <native|frameless>
 freedom security <none|basic|high>     # 设置安全模式（写入配置）
 freedom icon <path>                    # 设置应用图标（Windows 用 .ico，macOS 用 .icns）
 freedom config [get|set]
 freedom shell list|download <platform>|build <platform>
 freedom dmg [--platform <plat>]      # 在 macOS 上把 .app 打包为 .dmg
+freedom keygen [--force]             # 生成应用自更新 ed25519 密钥对（私钥留 .freedom/keys/，公钥进配置）
+freedom manifest --artifact <产物> --url <下载地址> [--version x] [--notes txt]  # 产出签名更新清单 dist/latest.json
+freedom agents [--home <dir>]         # Agent 集成支持矩阵（本机磁盘证据判定 ready/convention/unknown）
+freedom agents install --what <mcp|skill> --agent <key|all>   # 等价于下面两条
+freedom skill install --agent <key|all> [--dry-run] [--skills-dir <path>]
+freedom mcp install --agent <key|all> [--dry-run] [--config <path> --format json|toml|yaml]
+freedom mcp serve                    # stdio MCP 服务本体（一般由 agent 自动拉起）
 freedom version                     # 显示版本并检测最新版本
 freedom update                      # 检查新版本并给出升级命令（同 check-update）
 freedom tutorial
 freedom help
 ```
 
+## 两种显示：终端 TUI 与 Freedom Desktop
+
+裸跑 `freedom` 会先让你选显示方式：
+
+- **终端 TUI** —— 零依赖 ANSI 界面（`freedom tui` 直达），新建 / 打包 / 配置 / 壳管理。
+- **Freedom Desktop** —— 图形窗口（`freedom desktop` 直达）。它是 **freedom 自己打包出来的产品**：
+  模板在包内 `templates/desktop/`，首次运行同步到 `~/.freedom/desktop/`，再走与用户项目**同一条
+  `freedom build` 代码路径**产出 `freedom-desktop.exe`（壳 + `resources/`），随后拉起它。
+  前端是零构建的单文件页面（配置项 `staticHtml` 直通，**不跑 npm / vite，零网络**），
+  后端是零依赖 Node 进程（`resources/backend/desktop.mjs`，NDJSON/stdio），它再以子进程调起 `freedom` CLI——
+  因此**界面能力恒等于 CLI 能力**，CLI 升级界面即升级。
+  CLI 版本或模板内容变化时（stamp = CLI 版本 + 模板哈希）自动重打包，未变化则复用产物；
+  `--rebuild` 强制重建（需先关闭已开窗口，Windows 会锁定运行中的 exe），`--no-launch` 只准备产物。
+
+界面分区：概览 / 项目 / 打包 / 配置 / 壳与后端 / 发布 / Agent 集成，底部输出区实时滚动 CLI 与 dev server 日志。
+
+## Agent 集成：把 Freedom 交给编码 Agent
+
+- `freedom skill install --agent <key|all>`：把 `skill/freedom/SKILL.md`（框架架构、配置键表、SDK 面、
+  NDJSON 协议、CLI 命令、坑清单）复制进各 agent 的 skills 目录。
+- `freedom mcp install --agent <key|all>`：把 `freedom mcp serve` 注册进各 agent 的 MCP 配置。
+  MCP 工具面：`freedom_build / init / verify / config / shell / release / agents / guide`。
+- `freedom agents [--home <dir>]`：打印支持矩阵。**是否可写一律按本机磁盘证据判定**——
+  `ready`（配置文件已在，合并写入）/ `convention`（仅主目录在，按同族约定新建并明确提示）/
+  `unknown`（本机无足迹，只输出可粘贴片段，绝不凭记忆造路径）。`--home` 换一棵家目录树预览取证结果。
+- `freedom agents install --what <mcp|skill> --agent <key|all>`：上面两条安装入口的合并写法，
+  不带 `--what` 时默认 `mcp`；`agents <其它子命令>` 直接报错退出，不会静默回落成矩阵。
+- 写入是**幂等合并**：保留既有其它 server 条目，二次安装原地替换不产生重复；改前留 `<file>.bak` 备份；
+  `--dry-run` 只预览不落盘。未取证的 agent 用 `--config <真实路径> --format <json|toml|yaml>` 覆写。
+- 已按本机取证登记的 agent：Claude Code / Claude Desktop / Codex CLI / Qoder / CodeBuddy / Zcode / Cursor /
+  Hermes（YAML）等；其余（Trae、OpenCode、Gemini CLI、Pi、Tianshu、WorkBuddy、DeepSeek harness、Oh My Pi）
+  在无足迹的机器上一律降级为片段 + 覆写通道。
+
+## 开发热更（freedom dev）
+
+`freedom dev` 对标 `tauri dev` / `wails dev`：它拉起项目自己的前端 dev server（默认 `npm run dev`，可用配置 `dev.command` 或 `--command` 覆盖），
+从其输出里解析 `http://localhost:<port>`（也可用 `--port` / `--url` 直接指定），把随包通用壳复制到 `.freedom/dev/` 并写入
+`url` 模式的 `resources/config.json`（默认开开发者工具），随后拉起壳窗口——改代码由 vite HMR 直接反映到窗口里，不必反复重打包。
+`.freedom/dev/` 是开发临时目录，与正式产物 `dist/` 互不影响；配置了 `backend/` 时会一并镜像复制，任意语言后端同样能在 dev 流里联调。
+`Ctrl-C` 退出时会树杀 dev server 与壳进程（Windows 走 `taskkill /T /F`，不留孤儿子进程）。
+
+## 安装包与自更新发布环
+
+- `freedom build --installer`：每个目标平台额外产出 `<应用名>-<平台>-portable.zip`（解压即用的便携包）；
+  Windows 再产出已填充的 NSIS 脚本 `<应用名>-setup-<版本>.nsi`，本机装有 NSIS（`makensis` 在 PATH）时直接编译出
+  `<应用名>-setup-<版本>.exe`，否则给出指引让你在装有 NSIS 的机器上一条命令编译（缺 makensis 属环境能力而非产物缺陷）。
+- 应用自更新（对标 electron-updater / tauri updater）三步：
+  1. `freedom keygen` 生成 ed25519 密钥对，私钥存 `.freedom/keys/update_ed25519`（发布方资产，勿入库 / 勿分发）；
+  2. 公钥写入 `freedom.config.js` 的 `updater.publicKey`（连同 `manifestURL`），`freedom build` 会透传进产物的 `config.json`；
+  3. 发版时 `freedom manifest --artifact dist/<产物> --url https://.../<产物>` 产出签名清单 `dist/latest.json`，上传到 `manifestURL` 即可。
+  运行时前端用 `freedom.update.check()` / `freedom.update.install()`，清单验签（payload `freedom-update-v1\n<version>\n<url>\n<sha256>`）
+  与 sha256 校验都在壳内完成（`updater.go`），签名与 Go 侧验签有跨语言回归测试守着。
+
 ## 任意语言后端
 
 壳与后端进程通过 stdin/stdout 的 NDJSON/JSON-RPC 桥接（协议语言无关），因此后端可用任意语言实现（Node / Python / Rust / Go / C#…）。

package/lib/agents.js

@@ -0,0 +1,318 @@
+'use strict';
+
+// freedom agents / skill / mcp —— 把 Freedom 使用技能与 MCP 服务装进各家 Agent
+//
+// 设计纪律（铁律 19）：注册表只登记「候选路径 + 写入格式」，是否可写一律在安装时按磁盘
+// 证据判定——配置文件存在 = ready（合并写入，保留既有条目、写前 .bak 备份）；目录存在但
+// 配置文件缺失 = create（新建后写入）；皆无 = unverified，只打印可粘贴片段，绝不凭记忆
+// 造路径。未取证的 agent 与任意私有布局经 --config <path> --format <json|toml|yaml> 覆写。
+//
+// 幂等：同一 server 名 / 同一 skill 目录重复安装为原地替换，不产生重复条目。
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { packageRoot, copyDir } = require('./utils');
+const theme = require('./theme');
+const { paint, ok, err, warn, dim, bold, section, C } = theme;
+
+const SERVER_NAME = 'freedom';
+
+// mcp: { file: 相对 HOME 的配置文件, format: json|toml|yaml, path: JSON/YAML 容器键路径 }
+// skills: 相对 HOME 的 skill 根目录（每个 agent 一个）
+const AGENTS = [
+  { key: 'claude-code', name: 'Claude Code', mcp: { file: '.claude.json', format: 'json', path: ['mcpServers'] }, skills: '.claude/skills' },
+  { key: 'claude-desktop', name: 'Claude Desktop', mcp: { file: 'AppData/Roaming/Claude/claude_desktop_config.json', format: 'json', path: ['mcpServers'] }, skills: 'AppData/Roaming/Claude/skills' },
+  { key: 'codex', name: 'Codex CLI', mcp: { file: '.codex/config.toml', format: 'toml' }, skills: '.codex/skills' },
+  { key: 'qoder', name: 'Qoder', mcp: { file: '.qoder/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.qoder/skills' },
+  { key: 'codebuddy', name: 'CodeBuddy', mcp: { file: '.codebuddy/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.codebuddy/skills' },
+  { key: 'zcode', name: 'Zcode', mcp: { file: '.zcode/cli/config.json', format: 'json', path: ['mcp', 'servers'] }, skills: '.zcode/skills' },
+  { key: 'cursor', name: 'Cursor', mcp: { file: '.cursor/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.cursor/skills' },
+  { key: 'hermes', name: 'Hermes', mcp: { file: '.hermes/config.yaml', format: 'yaml', path: ['mcp_servers'] }, skills: '.hermes/skills' },
+  { key: 'tianshu', name: 'Tianshu Harness', mcp: { file: '.tianshu/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.tianshu/skills' },
+  { key: 'pi', name: 'Pi Agent', mcp: { file: '.pi/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.pi/skills' },
+  { key: 'workbuddy', name: 'WorkBuddy', mcp: { file: '.workbuddy/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.workbuddy/skills' },
+  { key: 'opencode', name: 'OpenCode', mcp: { file: '.config/opencode/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.opencode/skills' },
+  { key: 'gemini-cli', name: 'Gemini CLI', mcp: { file: '.gemini/settings.json', format: 'json', path: ['mcpServers'] }, skills: '.gemini/skills' },
+  { key: 'deepseek-harness', name: 'DeepSeek Harness', mcp: { file: '.deepseek/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.deepseek/skills' },
+  { key: 'oh-my-pi', name: 'Oh My Pi', mcp: { file: '.oh-my-pi/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.oh-my-pi/skills' },
+  { key: 'trae', name: 'Trae', mcp: { file: '.trae/mcp.json', format: 'json', path: ['mcpServers'] }, skills: '.trae/skills' },
+];
+
+function homeDir() {
+  return process.env.FREEDOM_AGENT_HOME || os.homedir();
+}
+
+function skillSource() {
+  return path.join(packageRoot(), 'skill', 'freedom');
+}
+
+// MCP 服务定义：stdio 拉起 `node <pkg>/bin/freedom.js mcp serve`
+function serverDef() {
+  return {
+    command: process.execPath,
+    args: [path.join(packageRoot(), 'bin', 'freedom.js'), 'mcp', 'serve'],
+  };
+}
+
+function agentByKey(key) {
+  return AGENTS.find((a) => a.key === key) || null;
+}
+
+function resolveAgentKeys(raw) {
+  const all = AGENTS.map((a) => a.key);
+  if (!raw || raw === 'all') return all;
+  const out = [];
+  for (const seg of String(raw).split(/[,，\s]+/)) {
+    if (!seg) continue;
+    if (!all.includes(seg)) throw new Error(`未知 agent：${seg}。可选：${all.join(' / ')} 或 all`);
+    if (!out.includes(seg)) out.push(seg);
+  }
+  if (!out.length) throw new Error('--agent 缺少取值。');
+  return out;
+}
+
+// ---- 状态探测（全部基于本轮磁盘证据） ----
+function probe(agent) {
+  const home = homeDir();
+  const mcpFile = path.join(home, agent.mcp.file);
+  const skillsDir = path.join(home, agent.skills);
+  // ready = 路径本机取证；convention = 仅 agent 主目录在（按同族约定新建，标注提示）；unknown = 无足迹（只给片段）
+  const mcpState = fs.existsSync(mcpFile) ? 'ready'
+    : (fs.existsSync(path.dirname(mcpFile)) ? 'convention' : 'unknown');
+  const skillState = fs.existsSync(skillsDir) ? 'ready'
+    : (fs.existsSync(path.dirname(skillsDir)) ? 'convention' : 'unknown');
+  return { mcpFile, skillsDir, mcpState, skillState };
+}
+
+function matrix() {
+  return AGENTS.map((a) => ({ key: a.key, name: a.name, ...probe(a) }));
+}
+
+// ---- JSON 配置：按键路径 upsert，保留其余条目 ----
+function upsertJson(text, containerPath, name, value) {
+  let obj;
+  try {
+    obj = text.trim() ? JSON.parse(text) : {};
+  } catch (e) {
+    throw new Error(`JSON 配置无法解析（拒绝覆盖以免损坏）：${e.message}`);
+  }
+  let node = obj;
+  for (const k of containerPath) {
+    if (node[k] === undefined) node[k] = {};
+    else if (typeof node[k] !== 'object' || node[k] === null) throw new Error(`配置键 ${k} 已存在且不是对象，拒绝改写。`);
+    node = node[k];
+  }
+  const had = name in node;
+  node[name] = value;
+  return { text: JSON.stringify(obj, null, 2) + '\n', had };
+}
+
+// ---- TOML：[mcp_servers.<name>] 块级替换 / 追加 ----
+function tomlValue(v) {
+  if (Array.isArray(v)) return `[${v.map(tomlValue).join(', ')}]`;
+  return JSON.stringify(v);
+}
+
+function tomlBlock(name, def) {
+  const lines = [`[mcp_servers.${name}]`];
+  for (const [k, v] of Object.entries(def)) lines.push(`${k} = ${tomlValue(v)}`);
+  return lines.join('\n') + '\n';
+}
+
+function upsertToml(text, name, def) {
+  const lines = text.split(/\r?\n/);
+  const header = `[mcp_servers.${name}]`;
+  const start = lines.findIndex((l) => l.trim() === header);
+  const had = start >= 0;
+  let out;
+  if (had) {
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end])) end++;
+    out = [...lines.slice(0, start), ...tomlBlock(name, def).trimEnd().split('\n'), ...lines.slice(end)];
+  } else {
+    out = [...lines, '', ...tomlBlock(name, def).trimEnd().split('\n')];
+  }
+  return { text: out.join('\n').replace(/\n*$/, '\n'), had };
+}
+
+// ---- YAML：mcp_servers: 下按缩进 upsert 一个条目 ----
+function yamlEntry(indent, name, def) {
+  const p = ' '.repeat(indent);
+  const lines = [`${p}${name}:`];
+  lines.push(`${p}  type: stdio`);
+  lines.push(`${p}  command: ${JSON.stringify(def.command)}`);
+  if (Array.isArray(def.args) && def.args.length) {
+    lines.push(`${p}  args:`);
+    for (const a of def.args) lines.push(`${p}    - ${JSON.stringify(a)}`);
+  }
+  lines.push(`${p}  enabled: true`);
+  return lines;
+}
+
+function upsertYaml(text, containerPath, name, def) {
+  const lines = text.split(/\r?\n/);
+  const key = containerPath[containerPath.length - 1];
+  const head = lines.findIndex((l) => new RegExp(`^${key}:\\s*$`).test(l));
+  const entry = (ownIndent) => yamlEntry(ownIndent, name, def);
+  if (head < 0) {
+    return { text: lines.join('\n').replace(/\n*$/, '\n') + `\n${key}:\n` + entry(2).join('\n') + '\n', had: false };
+  }
+  // 既有子条目缩进（取 head 之后第一条非空行）；无子条目时用 2
+  let own = 2;
+  for (let i = head + 1; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    const m = lines[i].match(/^(\s+)/);
+    own = m ? m[1].length : 0;
+    break;
+  }
+  const start = lines.findIndex((l, i) => i > head && new RegExp(`^ {${own}}${name}:`).test(l));
+  const had = start >= 0;
+  let out;
+  if (had) {
+    let end = start + 1;
+    while (end < lines.length && (!lines[end].trim() || indentOf(lines[end]) > own)) end++;
+    out = [...lines.slice(0, start), ...entry(own), ...lines.slice(end)];
+  } else {
+    out = [...lines.slice(0, head + 1), ...entry(own), ...lines.slice(head + 1)];
+  }
+  return { text: out.join('\n').replace(/\n*$/, '\n'), had };
+}
+
+function indentOf(line) {
+  const m = line.match(/^(\s+)/);
+  return m ? m[1].length : 0;
+}
+
+function backup(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!fs.existsSync(file)) return null;
+  const bak = `${file}.bak`;
+  fs.copyFileSync(file, bak);
+  return bak;
+}
+
+function snippet(agent, what) {
+  if (what === 'mcp') {
+    const body = JSON.stringify({ [SERVER_NAME]: serverDef() }, null, 2);
+    if (agent.mcp.format === 'toml') {
+      return [`  ${dim('# 无 mcp_servers 块，手工追加到 ~/.codex/config.toml：')}`, ...tomlBlock(SERVER_NAME, serverDef()).trimEnd().split('\n').map((l) => '  ' + dim(l))];
+    }
+    return [
+      `  ${dim('目标配置文件未取证，请把以下条目并入你的 MCP 配置（容器键通常是 mcpServers / mcp.servers）：')}`,
+      ...body.split('\n').map((l) => `  ${dim(l)}`),
+      `  ${dim(`或指定路径直接写入：freedom mcp install --agent ${agent.key} --config <path> --format json|toml|yaml`)}`,
+    ];
+  }
+  return [
+    `  ${dim('未发现该 agent 的 skill 目录，手工复制：')}`,
+    `  ${dim(`${skillSource()}  →  <agent skills 根目录>/freedom`)}`,
+    `  ${dim(`或指定目录直接安装：freedom skill install --agent ${agent.key} --skills-dir <path>`)}`,
+  ];
+}
+
+// ---- 安装主流程 ----
+function installMcpOne(agent, { config, format, dryRun }) {
+  const pr = probe(agent);
+  const file = config || pr.mcpFile;
+  const fmt = format || agent.mcp.format;
+  const cpath = agent.mcp.path || ['mcpServers'];
+
+  if (!config && pr.mcpState === 'unknown') {
+    return { agent, state: 'snippet', lines: [`  ${warn(`${agent.key}: 未找到配置目录 ${path.dirname(pr.mcpFile)}（未取证，不写入）`)}`, ...snippet(agent, 'mcp')] };
+  }
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : (fmt === 'json' ? '{}\n' : fmt === 'toml' ? '' : '');
+  const up = fmt === 'toml' ? upsertToml(text, SERVER_NAME, serverDef())
+    : fmt === 'yaml' ? upsertYaml(text, cpath, SERVER_NAME, serverDef())
+      : fmt === 'json' ? upsertJson(text, cpath, SERVER_NAME, serverDef())
+        : (() => { throw new Error(`不支持的 --format：${fmt}（可选 json|toml|yaml）`); })();
+
+  if (dryRun) {
+    return { agent, state: up.had ? 'replace(dry)' : 'add(dry)', lines: [`  ${dim(`${file} · ${fmt} · ${up.had ? '替换既有条目' : '新增条目'}`)}`] };
+  }
+  const bak = backup(file);
+  fs.writeFileSync(file, up.text, 'utf8');
+  return {
+    agent,
+    state: up.had ? 'replaced' : 'added',
+    lines: [`  ${ok(`${file}`)} ${dim(`· ${fmt} · ${up.had ? '已替换既有 freedom 条目' : '已写入'}${bak ? ` · 备份 ${path.basename(bak)}` : ''}`)}`,
+      ...(config || pr.mcpState === 'ready' ? [] : [`  ${warn('该路径按同族约定新建（本机未取证）；若该 agent 不读此文件，请用 --config 指定真实路径。')}`]),
+      `  ${dim(`重启 ${agent.name} 后生效；未自动信任前请在该 agent 内确认。`)}`],
+  };
+}
+
+function installSkillOne(agent, { skillsDir, dryRun }) {
+  const pr = probe(agent);
+  const src = skillSource();
+  if (!fs.existsSync(src)) throw new Error(`技能源缺失：${src}`);
+  const destBase = skillsDir || pr.skillsDir;
+  if (!skillsDir && pr.skillState === 'unknown') {
+    return { agent, state: 'snippet', lines: [`  ${warn(`${agent.key}: 未找到 skill 根目录 ${destBase}（未取证，不写入）`)}`, ...snippet(agent, 'skill')] };
+  }
+  const dest = path.join(destBase, 'freedom');
+  if (dryRun) return { agent, state: 'dry', lines: [`  ${dim(`${src} → ${dest}`)}`] };
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(src, dest);
+  return {
+    agent,
+    state: 'installed',
+    lines: [`  ${ok(dest)}`,
+      ...(skillsDir || pr.skillState === 'ready' ? [] : [`  ${warn('该 skill 根目录按同族约定新建（本机未取证）；若不被读取，请用 --skills-dir 指定真实目录。')}`])],
+  };
+}
+
+async function install({ what = 'mcp', agent = 'all', dryRun = false, config = null, format = null, skillsDir = null, home = null } = {}) {
+  const prevHome = process.env.FREEDOM_AGENT_HOME;
+  if (home) process.env.FREEDOM_AGENT_HOME = path.resolve(home);
+  let out;
+  try {
+    out = await installRun({ what, agent, dryRun, config, format, skillsDir });
+  } finally {
+    if (prevHome === undefined) delete process.env.FREEDOM_AGENT_HOME;
+    else process.env.FREEDOM_AGENT_HOME = prevHome;
+  }
+  return out;
+}
+
+async function installRun({ what, agent, dryRun, config, format, skillsDir }) {
+  if (config) config = path.resolve(config);
+  if (skillsDir) skillsDir = path.resolve(skillsDir);
+  const keys = resolveAgentKeys(agent);
+  if (config && keys.length > 1) throw new Error('--config 指向单一目标文件，只能配合 --agent <单个 key> 使用。');
+  const results = [];
+  console.log(section(what === 'skill' ? '安装 Freedom 使用技能' : '注册 Freedom MCP 服务'));
+  if (dryRun) console.log(`  ${warn('--dry-run 预览模式：不写任何文件')}`);
+  for (const key of keys) {
+    const a = agentByKey(key);
+    const fn = what === 'skill' ? installSkillOne : installMcpOne;
+    let r;
+    try {
+      r = fn(a, { config, format, dryRun, skillsDir });
+    } catch (e) {
+      r = { agent: a, state: 'failed', lines: [`  ${err(`${key}: ${e.message}`)}`] };
+    }
+    results.push({ key, state: r.state });
+    console.log(`${paint(`${r.state.padEnd(9)}`, C.fg.cyan, C.bold)} ${bold(a.name)} ${dim(`(${key})`)}`);
+    for (const l of r.lines) console.log(l);
+  }
+  const bad = results.filter((x) => x.state === 'failed').length;
+  console.log('');
+  console.log(`  ${dim('汇总：')}${results.length} 个 agent${bad ? `，${err(`${bad} 个失败`)}` : ''}${dryRun ? ` ${dim('（预览，未落盘）')}` : ''}`);
+  return { results, code: bad ? 1 : 0 };
+}
+
+// 打印支持矩阵（freedom agents）
+function printMatrix() {
+  console.log(section('Agent 集成支持矩阵'));
+  console.log(`  ${dim('ready=配置文件/技能目录已存在（合并写入）  convention=仅主目录在（按同族约定新建并提示）  unknown=本机未取证（仅打印片段）')}`);
+  console.log('');
+  for (const r of matrix()) {
+    const cell = (s) => (s === 'ready' ? `${ok('ready  ')}` : s === 'convention' ? `${paint('conventn ', C.fg.yellow)}` : dim('unknown'));
+    console.log(`  ${paint(r.key.padEnd(17), C.fg.cyan, C.bold)} MCP ${cell(r.mcpState)} ${dim(r.mcpFile)}  · SKILL ${cell(r.skillState)} ${dim(r.skillsDir)}`);
+  }
+  console.log('');
+  console.log(`  ${dim('用法：')}${paint('freedom skill install --agent all', C.fg.white)}  /  ${paint('freedom mcp install --agent <key> [--dry-run] [--config <path> --format <json|toml|yaml>]', C.fg.white)}`);
+  return 0;
+}
+
+module.exports = { install, printMatrix, upsertJson, upsertToml, upsertYaml };