@yufengtadian/freedom-cli 1.13.2 → 1.14.0-preview

package/LICENSE

@@ -0,0 +1,40 @@
+Freedom —— 专有软件许可（Proprietary License）
+
+Copyright (c) 2026 YUfeng12TA（邮箱与 GitHub 账号见仓库 https://github.com/YUfeng12TA/freedom ）
+
+本仓库（下称「本软件」）为闭源专有软件：**不适用 MIT、Apache、GPL 等任何开源许可**。
+本文件同时随 npm 包 `@yufengtadian/freedom-cli` 分发（包目录内 `LICENSE` 与本文件同文）。
+
+## 1. 授权范围（你可以做什么）
+
+- 安装与使用本软件（CLI、Freedom Desktop、预编译壳）于任意数量的个人 / 团队 / 商用设备。
+- 用本软件打包、签名、分发、销售**你自己的应用**：你的前端代码、后端代码、`resources/`
+  内容与应用数据归你所有，无需就产物向许可方付费、开源或署名。
+- 出于自身部署、审计与安全研究目的**阅读**随包分发的源码（见第 4 条的边界）。
+
+## 2. 限制（未经许可方书面同意不得做什么）
+
+- 再分发本软件源码、预编译壳、npm 包内容物，或任何衍生 / 修改版本（第 4 条的第三方组件除外）。
+- 移除、遮盖或改动版权声明、许可文本与完整性校验信息。
+- 将本软件或其副本作为独立产品对外销售、托管、转许可或用于构建竞争性打包工具。
+- 绕过 FRDM2 加密容器与反调试机制，对他人分发的产物提取源码，或将该成果对外发布
+  （安全研究请走 `SECURITY.md` 的披露通道）。
+
+## 3. 第三方组件不受本文件改写
+
+- `third_party/webview_go/`（及其在 `freedom-cli/templates/go/` 下的镜像副本）为
+  [webview_go](https://github.com/webview/webview_go) 的上游补丁副本，沿用其 **MIT** 许可
+  （原文见该目录 `LICENSE`），改动记录见同目录 `FREEDOM-PATCH.md`。
+- Go、Node.js、WebView2 SDK、WebKitGTK/GTK、NSIS、rcedit 等各自按其许可证使用。
+- 本文件不对这些组件施加任何额外限制。
+
+## 4. 免责与无担保
+
+本软件按「现状」提供，不含任何明示或暗示的担保。FRDM2 容器、完整性清单与反调试检测的设计
+目标是**提高逆向成本**，不是可信执行环境，不构成「不可逆向」的承诺（详见 `SECURITY.md`）。
+在适用法律允许的最大范围内，许可方不对因使用或无法使用本软件造成的任何损害承担责任。
+
+## 5. 条款变更与联系
+
+许可条款可能在新版本中调整，以你所获得版本随附的本文件为准。商用授权、白标或源码买断等
+需求，请通过仓库 GitHub Issues 与许可方联系。

package/README.md

@@ -1,17 +1,20 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.2）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.14.0-preview）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**v1.14.0-preview 加密代际断代（FRDM2 → FRDM3）+ 发布密钥体系**：① `.integrity` 改为 **ed25519 签名的 v3 清单**，签名对象覆盖 `app.bin` 摘要、应用标识、容器盐与 exe 自身摘要，公钥构建期注入壳——没有发布方私钥就签不出合法清单；② 容器主密钥从"随 npm 包分发的全域常量"改为**每产物随机密钥**（`.freedom/keys/<app>.key`，`freedom keygen` 生成，永不进包），1.13.x 那条"持有 CLI 者可离线解密任意产物"的结构缺陷（台账 B-20260925-054）就此封堵；③ **high 收为 Tier B 专属**——加密产物必须由本机现编的应用专属壳承载（需 Go 工具链、不支持交叉编译），零工具链通用壳（Tier A）请用 `basic`；④ 安全校验失败从"打印告警后返回"改为**退出码 70**，脚本与 CI 从此能区分"拒跑"与"正常退出"；⑤ `freedom keygen` 支持 `--dir <项目目录>`（此前静默按 cwd 写，会把密钥落到错误位置）。**FRDM1/FRDM2 旧产物在新壳上明确拒绝运行（不静默降级），须用 1.14.0-preview 重新 `freedom build`**；三平台壳随本版本经 CI 重编发布。
+
 **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 模式下前端页面、配置与 **`backend/**` 后端源码**统一封进加密 `app.bin`（FRDM2 容器：构建期随机盐 + PBKDF2 60 万次派生 + Encrypt-then-MAC 覆盖头部）+ `.integrity` 清单，磁盘不留明文后端源码；JS 侧构建加密 → Go 壳内存解密已有跨语言黄金向量与端到端互验（改名 / 篡改 / 整体替换即拒绝运行）；
+- **运行时资源层回归**：壳从 exe 同目录 `resources/` 读取 `config.json`（窗口 / 后端配置覆盖）与前端页面，high 模式下前端页面、配置与 **`backend/**` 后端源码**统一封进加密 `app.bin`（FRDM3 容器：构建期随机盐 + PBKDF2 60 万次派生 + Encrypt-then-MAC 覆盖头部）+ **ed25519 签名的 `.integrity` 清单**，磁盘不留明文后端源码；JS 侧构建加密 → Go 壳内存解密已有跨语言黄金向量与端到端互验（改名 / 篡改 / 整体替换 / 换公钥文件即拒绝运行，退出码 70）。**边界如实说明**：high 是"每产物专属密钥 + 发布方私钥签名"的加密加固，强度目标是"读不到明文、改不动内容、重打包跑不起来"，不是 DRM 也不是访问控制——运行期密钥仍在壳进程内存里，能读内存或愿意自编壳的对手不在防护范围内（详见根仓库 [SECURITY.md](../SECURITY.md) 的 Tier A / Tier B 表）；
 - **多窗口（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.13.3 内置工具链扩展 + 加固与健壮性收口**：新增 `freedom toolchain status|install|optimize|clear`，探测 / 安装 / 优化 C++（MSVC / MinGW / clang）、Rust、Go 三条工具链并按平台映射到 winget / brew / apt；探测结论缓存（绑 PATH 指纹 + 7 天 TTL）**只缓存成功**，即「检测到配置好就不再实探」，刚装好的工具当场可识别，`install` 默认只打印命令、`--apply` 才执行。同轮收口：Windows 第七道反调试信号（`DR0–DR3` 硬件断点）、SIGTERM / `CTRL_CLOSE_EVENT` 退出清扫通道（临时目录不再等下次启动回收）、`.integrity` 缺失即拒绝启动、Linux WebKitGTK 4.1 构建路径自动注入 `-tags=webkit2_41`、`shell build` / `shell download` 成功却非零退出的退出码修正、产物自检不再把 `.integrity` 大小说成 0 B。许可改为闭源专有许可（详见根 `LICENSE`）。
 
 **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 壳的缺口。
 
@@ -138,6 +141,15 @@ mac 用户解压 `.app.zip` 即得 `.app`，拖入 `/Applications` 即可直接
 
 **预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。自 v1.13.0 起由仓库 `.github/workflows/build.yml` 统一承担：推送 `vX.Y.Z` tag → 三平台 runner 编译通用壳 → `release` job 自动创建 GitHub Release 并上传资产 `freedom-shell-<plat>`，供 `freedom shell download` 按「`v<包版本>` tag + 同名资产」拉取（Intel Mac 已不支持，见 `nativePlatform()` 的明确报错）。发版顺序：先推 GitHub tag、等 Release 资产就绪，再 `npm publish` 同版本——保证 shell 下载默认源始终可用（紧急时可设 `FREEDOM_SHELL_TAG` 指向既有 tag）。
 
+**发布代际预检（`npm publish` 前置门）**：`package.json` 的 `prepublishOnly` 会跑 `lib/shell.js` 的 `preflightBundledShells()`——任一随包壳（`shell/<plat>`）的生成时间早于 `templates/go` 内最新框架源即**拒绝发布**。防的是「改了框架源、忘了重新同步壳」这类混合代 tarball：新 CLI 产的 FRDM3 产物会被旧壳直接拒跑（`npm publish --ignore-scripts` 可绕过，仅限确知安全时）。
+
+**平台名写法与下载回退**：`--platform` 与 `freedom shell download/build` 接受别名与架构后缀——
+`win` / `windows` / `mac` / `macos` / `osx` / `ubuntu` / `linux-x86_64` / `mac-arm64` 等统一归一到
+`win-x64` / `darwin-arm64` / `linux-x64`；无法支持的组合（`win-x86`、`darwin-x64`、`plan9`）直接报「未知平台」并给出可选值，不做猜测。
+下载有两条路径：先试直连 `releases/download`，不通（超时 / 代理 / 网络策略）时自动回退 GitHub Release API 资产端点；
+两条都不通则错误信息分别给出两端点与手工放置目录（`FREEDOM_SHELL_DIR` 可覆写壳目录，私有镜像另见 `FREEDOM_SHELL_REPO` / `FREEDOM_SHELL_BASE` / `FREEDOM_GITHUB_API`），
+GitHub 限流时可带 `FREEDOM_GITHUB_TOKEN`。
+
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
 ```bash
@@ -194,7 +206,18 @@ export default {
 | --- | --- | --- | --- |
 | `none` | 明文 `index.html` + `config.json`（默认，兼容历史产物） | 解包即读 | 公开页面 / 调试 / 快速分发 |
 | `basic` | 同上明文，构建时额外输出加固建议 | 低 | 需要提示、暂不加密 |
-| `high` | 前端 HTML + 配置 + **后端源码**整体加密为 `resources/app.bin` + `.integrity`，磁盘**无任何明文** | 高（需逆向壳 + 还原派生密钥） | 防源码提取、防资源篡改的正式分发 |
+| `high` | 前端 HTML + 配置 + **后端源码**整体加密为 `resources/app.bin` + **签名** `.integrity`，磁盘**无任何明文** | 高（需逆向壳 + 拿到发布方私钥与每产物主密钥） | 防源码提取、防重打包的正式分发；**仅 Tier B（自编译壳）** |
+
+**两档壳，强度不同（1.14.0-preview 起的口径，务必对号入座）**：
+
+| 档 | 壳怎么来 | 能跑 `high` 产物吗 | 说明 |
+| --- | --- | --- | --- |
+| **Tier A** | 通用预编译壳（`freedom build` 零工具链，`none` / `basic` 用的就是它：随包分发或按需下载） | ❌ | 壳是公共二进制，没有构建期注入点 ⇒ 每产物主密钥与验签公钥无处安放，硬放进产物等于让攻击者自签自验 |
+| **Tier B** | 本应用自编译壳（`freedom build --security high` 自动走这条：内部调 `freedom shell build` 现编，需 Go 工具链） | ✅ | 主密钥与 ed25519 公钥编译期内嵌进**这个应用专属的壳**，签名清单与它一一绑定 |
+
+所以 `high` 一档自带三个门槛，缺一个即拒绝构建（不静默降级）：`.freedom/keys/<app>.key` 每产物主密钥、
+`.freedom/keys/update_ed25519` 签名私钥（两者由 `freedom keygen` 生成）、以及**在本机为目标平台编译**
+（webview_go 依赖目标平台系统 WebView，无法交叉编译，跨平台 high 会直接报明）。
 
 **切换方式**（二选一，`--security` 可临时覆盖配置文件）：
 
@@ -204,16 +227,27 @@ freedom build --security high        # 单次构建生效（不改配置）
 freedom build                        # 读取配置中的 security 值
 ```
 
-**high 模式原理（FRDM2 容器）**：
-- 容器布局：`FRDM2`(5B) + `salt`(16B，**每次构建随机**) + `iv`(16B) + `tag`(16B) + 密文；密钥 = **PBKDF2-HMAC-SHA256**（60 万次迭代，主密钥经字节表掩码内置于壳与 CLI）按「应用可执行文件名 + 容器随机盐」派生，再由固定标签做 **HMAC 域分离**得到独立的加密钥与认证钥；
-- 认证为 **Encrypt-then-MAC 且覆盖容器头部**（magic/salt/iv 参与计算），故改盐、改 IV、翻转任意一字节都会认证失败；`.integrity` 清单绑定同一盐值，**整体替换成另一个合法容器**同样拒绝运行；
+**high 模式原理（FRDM3 容器 + 签名清单）**：
+- 容器布局：`FRDM3`(5B) + `salt`(16B，**每次构建随机**) + `iv`(16B) + `tag`(16B) + 密文；密钥 = **PBKDF2-HMAC-SHA256**（60 万次迭代）以「**每产物主密钥**（`.freedom/keys/<app>.key`，32B 随机，`freedom keygen` 生成；不进 npm 包、不以明文落进 `resources/`，只以"本产物专属装配码"的形式编进本应用专属壳（见下））+ 应用标识 + 容器随机盐」派生，再由固定标签做 **HMAC 域分离**得到独立的加密钥与认证钥；
+- 完整性为 **Encrypt-then-MAC 且覆盖容器头部**（magic/salt/iv 参与计算），故改盐、改 IV、翻转任意一字节都会认证失败；`resources/.integrity` 是 **ed25519 签名的 v3 清单**（签名对象是清单里 base64 那段确切的字节，跨语言不做 JSON 规范化）， claims 绑定 `app.bin` 摘要、应用标识、容器盐与 **exe 自身摘要**——换内容、换身份、换盐、**给 exe 改名**全部当场拒；
+- **验签顺序不可换**：先比对清单公钥与壳内信任锚（锚必须在被校验对象之外，否则攻击者换对钥匙即自证合法）→ 验签 → 复查 claims 绑定 → exe 自摘要 → 才解密；
 - **后端源码不再明文落盘**：`backend/**`（含 POSIX 权限位）作为条目进入容器，磁盘上不再有 `resources/backend/`；壳启动解密到仅属主可访问的一次性临时目录（0700 / 文件 0600，执行位按容器记录还原）供子进程执行，进程退出即删除；若被强杀或崩溃来不及删，**下次启动会按目录名内嵌的 PID 自动回收残留**；
-- 构建期抹除前端产物中的 `sourceMappingURL` 引用（防 source map 还原源码），壳二进制一律 `-trimpath -ldflags "-s -w"`（Windows 另加 `-H windowsgui`）；
-- 解密 / 校验失败即拒绝运行（不静默回退明文，防降级攻击；旧版 `FRDM1` 容器明确报"版本不支持"）；
+- **运行期明文只有一份、派生钥不驻留**：一份产物在进程内**只解密一次**（配置与页面两处加载共用同一份已校验载荷；验签链每次照跑，缓存不参与判定），
+  PBKDF2 派生出的加密钥与认证钥**只在解密那几毫秒内存在、返回即抹零**，不写进任何跨调用缓存——
+  否则对手只要做一次内存取样拿到派生钥，就能对磁盘上的 `app.bin` 永久离线解密（容器盐与 IV 都在容器头里，除派生钥外无第二个秘密输入）；
+  后端源文写进私有临时目录后，其在内存里的那份副本同样立即抹零。诚实边界：前端页面与配置的明文必须交给 webview，
+  **必然常驻内存**，这一层擦不掉；
+- 构建期抹除前端产物中的 `sourceMappingURL` 引用（防 source map 还原源码），壳二进制一律 `-trimpath -ldflags "-s -w"`（Windows 另加 `-H windowsgui`）；**主密钥没有 `-X` 通道**：每次 `freedom build --security high` 现场生成一份**只属于本产物**的装配码（`keyslot_<tag>.go`，分片数 / 切法 / 变换 / 参数全随机），经 `go build -overlay` 虚拟进壳的包目录后随编译落入 exe、临时文件即删（`strings` 与十六进制扫描都定位不到那 32 字节，且从 A 产物逆出的提取流程对 B 产物无效）；
+- 解密 / 校验失败即**拒绝运行并以退出码 70 结束**（不静默回退明文，防降级攻击；拒跑必须非零，否则脚本与 CI 眼里"拒跑"与"正常退出"同形）；旧代际 `FRDM1`/`FRDM2` 容器明确报"旧代际、请重新打包"；
 - 另内置 **anti-debug**：`IsDebuggerPresent`、`CheckRemoteDebuggerPresent`、直读 `PEB.BeingDebugged`、`NtQueryInformationProcess` 的 `ProcessDebugPort` / `ProcessDebugObjectHandle` / `ProcessDebugFlags` 共六道独立信号，任一确证即静默退出（退出码 77），在资源解密前后各检测一次；所有探测遵循"取不到即视为未命中"，杜绝误杀；
 - 进程隐藏加固（`-H windowsgui`，无控制台窗口）。
 
-**加固上限说明**：`high` 大幅提高破解门槛，但**任何客户端可执行程序都无法做到绝对不可破解**——密钥最终存在于壳二进制与运行时内存中，反调试只抬升动态分析成本、不是不可绕过的墙。真正敏感的密钥与业务逻辑仍应留在服务端。
+**加固上限说明**：`high` 大幅提高破解门槛，但**任何客户端可执行程序都无法做到绝对不可破解**——密钥最终存在于壳二进制与运行时内存中，反调试只抬升动态分析成本、不是不可绕过的墙；Tier B 也挡不住"攻击者自换一对密钥再编一份自己的壳"（那已经是整个应用归攻击者，再上一层只有 OS 级出版商信任 / Authenticode）。真正敏感的密钥与业务逻辑仍应留在服务端。
+两条当前已知边界（如实列出，勿当作"已修"）：① 主密钥的装配码在壳里、生成器在公开源里，故静态逆向出某个壳的人可以拼回那把主密钥——但 1.14.0-preview 起装配码**每个产物一份**（分片与变换随机），针对 A 产物得到的脱壳流程不能直接复用到 B 产物，抬的是自动化与批量脱壳的成本，不是"逆向就是拿不到"；② 前端页面与配置的明文必须交给 webview，能读进程内存者始终看得到那一份（后端源码已在物化后擦除，见上）。
+**密钥即发布权**：`.freedom/keys/`（每产物主密钥 + ed25519 私钥）丢失后**无法再为该应用产出可运行的 high 产物**（既有产物不受影响），请把它们当作发布证书备份；反之它们一旦外泄，拿到者就能为你的应用签出合法篡改清单——勿入库、勿分发（`freedom keygen` 会自动往 `.gitignore` 补行）。**误报可关**：反调试在 CI、自动化测试、远程桌面、部分虚拟化环境可能把正常运行判成被附加调试器
+（命中即静默退出，码 77）。这类场景设 `FREEDOM_DISABLE_ANTIDEBUG=1`，或在壳层源码里 `Config{DisableAntiDebug: true}`
+后 `freedom shell build`——只关探测，容器解密与 `.integrity` 完整性校验照旧生效（那两道才是源码保护的本体）。
+`resources/config.json` 里刻意不提供此开关：打包产物里的配置运行期可被第三方替换，给开关等于递刀。
 
 **互斥规则**：切换安全模式重新构建时，CLI 会自动清理另一模式的遗留产物（`app.bin`/`.integrity` 与明文 `index.html`/`config.json`/`backend/` 只能存其一），避免壳误加载旧资源。
 
@@ -231,7 +265,10 @@ window.freedom.window.minimize();                       // 窗口控制
 
 - Node.js >= 18
 - 不需要 Go 工具链（壳层为随包分发的预编译二进制）
-- 可选：`freedom shell build` 需本机 Go（含 CGO，Windows 需 MSVC 编译环境），仅用于亲自编译壳
+- 可选：`freedom shell build` 需本机 Go（含 CGO，Windows 需 MSVC 编译环境），仅用于亲自编译壳。
+  Linux 侧需 WebKitGTK + GTK3 开发库，`4.0` 与 `4.1` 二选一（Ubuntu 24.04+/Debian 13+ 只有 4.1：
+  `sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev`）；
+  仅有 4.1 时 `freedom shell build` 会自动为编译加 `-tags webkit2_41`，无需手工干预（探测见 `lib/webkit.js`）。
 - `.dmg` 打包需在 macOS 上执行（依赖系统 hdiutil）；`.app.zip` 在任意平台均可直接产出
 
 ## 命令
@@ -248,13 +285,17 @@ freedom security <none|basic|high>     # 设置安全模式（写入配置）
 freedom icon <path>                    # 设置应用图标（Windows 用 .ico，macOS 用 .icns）
 freedom config [get|set]
 freedom shell list|download <platform>|build <platform>
+freedom toolchain status [--refresh] [--home <dir>]        # 探测 Go / Rust / C++ 工具链（成功结论才缓存，绑 PATH 指纹）
+freedom toolchain install [go,rust,cpp|missing] [--apply]  # 默认只打印安装命令，加 --apply 才执行
+freedom toolchain optimize [--apply]                       # 国内网络迹象下换 Go/Rust 镜像源（改配置前留 .bak）
+freedom toolchain clear                                   # 清空探测缓存（~/.freedom/toolchain-cache.json）
 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 [--home <dir>]         # Agent 集成支持矩阵（本机磁盘证据判定「是否安装 + 目标文件状态」）
 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 skill install --agent <key|all> [--dry-run] [--force] [--skills-dir <path>]
+freedom mcp install --agent <key|all> [--dry-run] [--force] [--config <path> --format json|toml|toml-aot|yaml]
 freedom mcp serve                    # stdio MCP 服务本体（一般由 agent 自动拉起）
 freedom version                     # 显示版本并检测最新版本
 freedom update                      # 检查新版本并给出升级命令（同 check-update）
@@ -284,16 +325,22 @@ freedom help
   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 [--home <dir>]`：打印支持矩阵。**安装检测门（v1.13.2 起）**——只有本机检出该
+  agent 的**安装足迹**（配置文件在 / 注册表声明的专属目录在 / PATH 里有它的可执行）才允许写入；
+  未检出即 `not-installed`，只输出可粘贴片段，**绝不新建目录、绝不凭记忆造路径**。
+  「父目录存在」不算证据（HOME 与 `AppData/Roaming` 恒在，据此写入＝往没装的东西里写）。
+  `--home` 换一棵家目录树预览取证结果。
+- 逃生通道两条：`--force`（明知该 agent 装着但足迹未被覆盖，强行写入并显式告警）、
+  `--config <真实路径>` / `--skills-dir <真实目录>`（按你指定的路径写，绕开候选路径推断）。
 - `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）
-  在无足迹的机器上一律降级为片段 + 覆写通道。
+  `--dry-run` 只预览不落盘。
+- 已登记的 agent（17 个）：Claude Code / Claude Desktop / Codex CLI / Qoder / CodeBuddy / Zcode / Cursor /
+  Hermes（YAML）/ Tianshu / Pi / WorkBuddy / OpenCode / Gemini CLI / DeepSeek Harness / Oh My Pi / Trae /
+  **Reasonix**。其中 **Reasonix** 的 MCP 配置是 TOML **数组表** `[[plugins]]`（按 `name = "freedom"` 定位条目，
+  与既有 `computer-use` 等插件共存），格式取自本机 `%APPDATA%/reasonix/config.toml` 实况；
+  技能装在 `~/.reasonix/skills/freedom`。未被登记或无足迹的布局用 `--format <json|toml|toml-aot|yaml>` 覆写。
 
 ## 开发热更（freedom dev）
 
@@ -336,5 +383,11 @@ export default {
 
 ## License
 
-MIT
+本工具与其源码为**闭源专有软件**，完整条款见包内 `LICENSE`（不适用 MIT）。要点：
+
+- 你可以自由安装使用，并用它打包 / 销售你自己的应用——**你的前端、后端与产物归你所有**，无需开源或署名；
+- 未经许可方书面同意，不得再分发本包内容物、源码或衍生版本，也不得移除版权与许可声明；
+- 唯一沿用开源许可的部分是内嵌第三方 `webview_go`（MIT，见 `templates/go/third_party/webview_go/LICENSE`）。
+
+商用授权与定制需求请通过仓库 GitHub Issues 联系。
 

package/lib/agents.js

@@ -3,9 +3,14 @@
 // freedom agents / skill / mcp —— 把 Freedom 使用技能与 MCP 服务装进各家 Agent
 //
 // 设计纪律（铁律 19）：注册表只登记「候选路径 + 写入格式」，是否可写一律在安装时按磁盘
-// 证据判定——配置文件存在 = ready（合并写入，保留既有条目、写前 .bak 备份）；目录存在但
-// 配置文件缺失 = create（新建后写入）；皆无 = unverified，只打印可粘贴片段，绝不凭记忆
-// 造路径。未取证的 agent 与任意私有布局经 --config <path> --format <json|toml|yaml> 覆写。
+// 证据判定。安装检测门（R4 起，用户裁定）：**只有检出该 agent 确实装在本机**（配置文件在
+// / agent 家目录在 / PATH 里有它的可执行 / 注册表声明的额外足迹）才允许写入；仅凭「父目录
+// 在」不构成证据——HOME 与 AppData/Roaming 恒在，按同族约定新建等于往没装的东西里写。
+// 未检出的 agent 一律 skipped(not-installed)，只打印可粘贴片段，绝不凭记忆造路径。
+// 覆写通道：--force（明知在但足迹未覆盖）、--config / --skills-dir（用户指定真实路径）。
+//
+// 写入档位：配置文件存在 = ready（合并写入，保留既有条目、写前 .bak 备份）；
+// 目录不存在则按需创建后再合并。
 //
 // 幂等：同一 server 名 / 同一 skill 目录重复安装为原地替换，不产生重复条目。
 
@@ -18,31 +23,91 @@ const { paint, ok, err, warn, dim, bold, section, C } = theme;
 
 const SERVER_NAME = 'freedom';
 
-// mcp: { file: 相对 HOME 的配置文件, format: json|toml|yaml, path: JSON/YAML 容器键路径 }
+// mcp: { file: 相对 HOME 的配置文件, format: json|toml|yaml|toml-aot, path: JSON/YAML 容器键路径,
+//        section: toml-aot 的数组表名, key: toml-aot 用于定位条目的字段 }
 // skills: 相对 HOME 的 skill 根目录（每个 agent 一个）
+// home / evidence: 该 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: 'claude-desktop', name: 'Claude Desktop', home: 'AppData/Roaming/Claude', mcp: { file: 'AppData/Roaming/Claude/claude_desktop_config.json', format: 'json', path: ['mcpServers'] }, skills: 'AppData/Roaming/Claude/skills' },
+  { key: 'codex', name: 'Codex CLI', bin: 'codex', 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: 'zcode', name: 'Zcode', home: '.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: 'opencode', name: 'OpenCode', home: '.config/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' },
+  // Reasonix（本机取证 2026-09-25：%APPDATA%/reasonix/config.toml 第 288 行起
+  // 「External MCP servers …」+ [[plugins]] name/type/command 实例；该文件注释明示
+  // command/args/env/url/headers 支持 ${VAR} 展开 → args 字段存在）。
+  {
+    key: 'reasonix',
+    name: 'Reasonix',
+    home: 'AppData/Roaming/reasonix',
+    mcp: { file: 'AppData/Roaming/reasonix/config.toml', format: 'toml-aot', section: 'plugins', key: 'name' },
+    skills: '.reasonix/skills',
+    evidence: ['AppData/Roaming/reasonix-studio.exe', '.reasonix'],
+  },
 ];
 
 function homeDir() {
   return process.env.FREEDOM_AGENT_HOME || os.homedir();
 }
 
+// PATH 探测（每轮安装只扫一次，缓存于 Map）：返回命中的可执行全路径或 null
+function makeWhich() {
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.PS1').split(';').concat([''])
+    : [''];
+  const cache = new Map();
+  return (names) => {
+    for (const n of names) {
+      if (cache.has(n)) {
+        const hit = cache.get(n);
+        if (hit) return hit;
+        continue;
+      }
+      let found = null;
+      for (const d of dirs) {
+        for (const e of exts) {
+          const cand = path.join(d, n + e);
+          try { if (fs.statSync(cand).isFile()) { found = cand; break; } } catch (err) { /* 不在该目录 */ }
+        }
+        if (found) break;
+      }
+      cache.set(n, found);
+      if (found) return found;
+    }
+    return null;
+  };
+}
+
+// 安装检测门：该 agent 是否真的装在本机（只认真实足迹，不认「父目录恒在」）
+// home / evidence 为显式声明的专属目录与足迹，不做推断——'AppData/Roaming' 这类公共父目录恒在，
+// 推断即假阳性（未安装也被判为已安装）。
+function detect(agent, which) {
+  const home = homeDir();
+  const ev = [];
+  if (fs.existsSync(path.join(home, agent.mcp.file))) ev.push(`配置文件 ${agent.mcp.file}`);
+  if (agent.home && fs.existsSync(path.join(home, agent.home))) ev.push(`目录 ${agent.home}`);
+  for (const rel of agent.evidence || []) {
+    if (fs.existsSync(path.join(home, rel))) ev.push(`足迹 ${rel}`);
+  }
+  if (agent.bin) {
+    const exe = which([agent.bin]);
+    if (exe) ev.push(`PATH ${path.basename(exe)}`);
+  }
+  return { installed: ev.length > 0, evidence: ev };
+}
+
 function skillSource() {
   return path.join(packageRoot(), 'skill', 'freedom');
 }
@@ -73,20 +138,19 @@ function resolveAgentKeys(raw) {
 }
 
 // ---- 状态探测（全部基于本轮磁盘证据） ----
-function probe(agent) {
+function probe(agent, which) {
   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 };
+  // ready = 目标文件本机取证；create = 目录不在（安装时新建后合并写入）
+  const mcpState = fs.existsSync(mcpFile) ? 'ready' : 'create';
+  const skillState = fs.existsSync(skillsDir) ? 'ready' : 'create';
+  return { mcpFile, skillsDir, mcpState, skillState, detected: detect(agent, which) };
 }
 
 function matrix() {
-  return AGENTS.map((a) => ({ key: a.key, name: a.name, ...probe(a) }));
+  const which = makeWhich();
+  return AGENTS.map((a) => ({ key: a.key, name: a.name, ...probe(a, which) }));
 }
 
 // ---- JSON 配置：按键路径 upsert，保留其余条目 ----
@@ -136,6 +200,47 @@ function upsertToml(text, name, def) {
   return { text: out.join('\n').replace(/\n*$/, '\n'), had };
 }
 
+// ---- TOML 数组表：[[section]] 条目按 key 字段定位（Reasonix 的 [[plugins]] 用 name） ----
+function aotBlock(section, def) {
+  const lines = [`[[${section}]]`];
+  for (const [k, v] of Object.entries(def)) lines.push(`${k} = ${tomlValue(v)}`);
+  return lines;
+}
+
+function upsertTomlAoT(text, section, keyField, keyVal, def) {
+  const lines = text.split(/\r?\n/);
+  const header = `[[${section}]]`;
+  const starts = [];
+  for (let i = 0; i < lines.length; i++) if (lines[i].trim() === header) starts.push(i);
+  const blockEnd = (i) => {
+    let j = i + 1;
+    while (j < lines.length && !/^\s*\[/.test(lines[j])) j++;
+    return j;
+  };
+  const keyRe = new RegExp(`^\\s*${keyField}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|(.+?))\\s*$`);
+  for (const s of starts) {
+    let hit = false;
+    for (let i = s + 1; i < blockEnd(s); i++) {
+      const m = lines[i].match(keyRe);
+      if (!m) continue;
+      const raw = m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3];
+      if (String(raw).trim() === keyVal) hit = true;
+    }
+    if (!hit) continue;
+    const out = [...lines.slice(0, s), ...aotBlock(section, def), ...lines.slice(blockEnd(s))];
+    return { text: out.join('\n').replace(/\n*$/, '\n'), had: true };
+  }
+  let out;
+  if (starts.length) {
+    const last = starts[starts.length - 1];
+    const end = blockEnd(last);
+    out = [...lines.slice(0, end), '', ...aotBlock(section, def), ...lines.slice(end)];
+  } else {
+    out = [...lines, '', ...aotBlock(section, def)];
+  }
+  return { text: out.join('\n').replace(/\n*$/, '\n'), had: false };
+}
+
 // ---- YAML：mcp_servers: 下按缩进 upsert 一个条目 ----
 function yamlEntry(indent, name, def) {
   const p = ' '.repeat(indent);
@@ -194,41 +299,59 @@ function backup(file) {
 
 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))];
+    const fmt = agent.mcp.format;
+    if (fmt === 'toml') {
+      return [`  ${dim(`手工追加到 ${agent.mcp.file}：`)}`, ...tomlBlock(SERVER_NAME, serverDef()).trimEnd().split('\n').map((l) => '  ' + dim(l))];
     }
+    if (fmt === 'toml-aot') {
+      const block = aotBlock(agent.mcp.section || 'plugins', { name: SERVER_NAME, type: 'stdio', ...serverDef() });
+      return [`  ${dim(`手工追加到 ${agent.mcp.file}（数组表按 ${agent.mcp.key || 'name'} 定位条目）：`)}`, ...block.map((l) => '  ' + dim(l))];
+    }
+    const body = JSON.stringify({ [SERVER_NAME]: serverDef() }, null, 2);
     return [
-      `  ${dim('目标配置文件未取证，请把以下条目并入你的 MCP 配置（容器键通常是 mcpServers / mcp.servers）：')}`,
+      `  ${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('手工复制技能目录：')}`,
+    `  ${dim(`${skillSource()}  →  ${path.join(homeDir(), agent.skills)}${'\\'}freedom`)}`,
     `  ${dim(`或指定目录直接安装：freedom skill install --agent ${agent.key} --skills-dir <path>`)}`,
   ];
 }
 
+// 安装检测门裁定：显式覆写通道 / --force / 足迹命中，三者皆无则不写
+function gateOf(agent, pr, explicit, force) {
+  if (explicit) return { pass: true, reason: '' };
+  if (force) return { pass: true, reason: `${warn(`未检出安装足迹（${[
+    path.join(homeDir(), agent.mcp.file), path.join(homeDir(), agent.skills),
+  ].join(' / ')}），按 --force 强行写入；若该 agent 并未安装，请自行删除。`)}` };
+  if (pr.detected.installed) return { pass: true, reason: dim(`已检出：${pr.detected.evidence.join('；')}`) };
+  return { pass: false, reason: '' };
+}
+
 // ---- 安装主流程 ----
-function installMcpOne(agent, { config, format, dryRun }) {
-  const pr = probe(agent);
+function installMcpOne(agent, { config, format, dryRun, force, which }) {
+  const pr = probe(agent, which);
+  const gate = gateOf(agent, pr, config, force);
+  if (!gate.pass) {
+    return { agent, state: 'not-installed', lines: [`  ${warn(`${agent.key}: 本机未检出安装足迹 → 依检测门不写入（只给可粘贴片段）`)}`, ...snippet(agent, 'mcp')] };
+  }
   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 text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : (fmt === 'json' ? '{}\n' : '');
   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）`); })();
+    : fmt === 'toml-aot' ? upsertTomlAoT(text, agent.mcp.section || 'plugins', agent.mcp.key || 'name', SERVER_NAME,
+      { name: SERVER_NAME, type: 'stdio', ...serverDef() })
+      : fmt === 'yaml' ? upsertYaml(text, cpath, SERVER_NAME, serverDef())
+        : fmt === 'json' ? upsertJson(text, cpath, SERVER_NAME, serverDef())
+          : (() => { throw new Error(`不支持的 --format：${fmt}（可选 json|toml|toml-aot|yaml）`); })();
 
   if (dryRun) {
-    return { agent, state: up.had ? 'replace(dry)' : 'add(dry)', lines: [`  ${dim(`${file} · ${fmt} · ${up.had ? '替换既有条目' : '新增条目'}`)}`] };
+    return { agent, state: up.had ? 'replace(dry)' : 'add(dry)', lines: [`  ${dim(`${file} · ${fmt} · ${up.had ? '替换既有条目' : '新增条目'}`)} ${gate.reason}`] };
   }
   const bak = backup(file);
   fs.writeFileSync(file, up.text, 'utf8');
@@ -236,37 +359,38 @@ function installMcpOne(agent, { config, format, dryRun }) {
     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 指定真实路径。')}`]),
+      ...(gate.reason ? [`  ${gate.reason}`] : []),
       `  ${dim(`重启 ${agent.name} 后生效；未自动信任前请在该 agent 内确认。`)}`],
   };
 }
 
-function installSkillOne(agent, { skillsDir, dryRun }) {
-  const pr = probe(agent);
+function installSkillOne(agent, { skillsDir, dryRun, force, which }) {
+  const pr = probe(agent, which);
   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 gate = gateOf(agent, pr, skillsDir, force);
+  if (!gate.pass) {
+    return { agent, state: 'not-installed', lines: [`  ${warn(`${agent.key}: 本机未检出安装足迹 → 依检测门不写入（只给可粘贴片段）`)}`, ...snippet(agent, 'skill')] };
   }
+  const destBase = skillsDir || pr.skillsDir;
   const dest = path.join(destBase, 'freedom');
-  if (dryRun) return { agent, state: 'dry', lines: [`  ${dim(`${src} → ${dest}`)}`] };
+  if (dryRun) return { agent, state: 'dry', lines: [`  ${dim(`${src} → ${dest}`)} ${gate.reason}`] };
   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 指定真实目录。')}`])],
+      ...(gate.reason ? [`  ${gate.reason}`] : [])],
   };
 }
 
-async function install({ what = 'mcp', agent = 'all', dryRun = false, config = null, format = null, skillsDir = null, home = null } = {}) {
+async function install({ what = 'mcp', agent = 'all', dryRun = false, config = null, format = null, skillsDir = null, force = false, 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 });
+    out = await installRun({ what, agent, dryRun, config, format, skillsDir, force });
   } finally {
     if (prevHome === undefined) delete process.env.FREEDOM_AGENT_HOME;
     else process.env.FREEDOM_AGENT_HOME = prevHome;
@@ -274,7 +398,7 @@ async function install({ what = 'mcp', agent = 'all', dryRun = false, config = n
   return out;
 }
 
-async function installRun({ what, agent, dryRun, config, format, skillsDir }) {
+async function installRun({ what, agent, dryRun, config, format, skillsDir, force }) {
   if (config) config = path.resolve(config);
   if (skillsDir) skillsDir = path.resolve(skillsDir);
   const keys = resolveAgentKeys(agent);
@@ -282,37 +406,43 @@ async function installRun({ what, agent, dryRun, config, format, skillsDir }) {
   const results = [];
   console.log(section(what === 'skill' ? '安装 Freedom 使用技能' : '注册 Freedom MCP 服务'));
   if (dryRun) console.log(`  ${warn('--dry-run 预览模式：不写任何文件')}`);
+  const which = makeWhich();
   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 });
+      r = fn(a, { config, format, dryRun, skillsDir, force, which });
     } 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})`)}`);
+    results.push({ key, state: r.state, detected: probe(a, which).detected.installed });
+    console.log(`${paint(`${r.state.padEnd(13)}`, 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;
+  const skipped = results.filter((x) => x.state === 'not-installed').length;
   console.log('');
-  console.log(`  ${dim('汇总：')}${results.length} 个 agent${bad ? `，${err(`${bad} 个失败`)}` : ''}${dryRun ? ` ${dim('（预览，未落盘）')}` : ''}`);
+  console.log(`  ${dim('汇总：')}${results.length} 个 agent${skipped ? `，${paint(`${skipped} 个未检出安装（未写入）`, C.fg.yellow)}` : ''}${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(`  ${dim('安装门=本机是否检出该 agent 的足迹（配置文件／声明目录／PATH 可执行）；未检出只打印片段、不写入（可 --force 覆写）')}`);
+  console.log(`  ${dim('MCP/SKILL 列：ready=目标已存在（合并写入）  create=安装时新建目录后写入')}`);
   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)}`);
+    const cell = (s) => (s === 'ready' ? `${ok('ready ')}` : paint('create ', C.fg.yellow));
+    const gate = r.detected.installed ? ok('已安装') : dim('未检出');
+    const basis = r.detected.installed ? dim(`（${r.detected.evidence.join('；')}）`) : dim('（需 --force 或 --config/--skills-dir）');
+    console.log(`  ${paint(r.key.padEnd(17), C.fg.cyan, C.bold)} ${gate} ${basis}`);
+    console.log(`  ${' '.repeat(18)}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)}`);
+  console.log(`  ${dim('用法：')}${paint('freedom skill install --agent all', C.fg.white)}  /  ${paint('freedom mcp install --agent <key> [--dry-run] [--force] [--config <path> --format <json|toml|toml-aot|yaml>]', C.fg.white)}`);
   return 0;
 }
 
-module.exports = { install, printMatrix, upsertJson, upsertToml, upsertYaml };
+module.exports = { install, printMatrix, upsertJson, upsertToml, upsertTomlAoT, upsertYaml, detect, makeWhich };