@kira905/dsh-butler-install 0.2.1 → 0.3.0

package/README.md

@@ -30,33 +30,43 @@ node <dsh-butler-core 仓根>/selfcheck-replica.mjs --manifest suite-manifest.js
 > （只跑它内置的那几项判据）。本仓的 `suite-manifest.json` 的字段是**为它将来接清单准备的**
 > —— 字段含义见下文「清单字段」一节。别把它当成"已经能按清单跑了"。
 
-## 想要个界面？`--ui`：挂在 DSH 外面的只读向导页
+## 想要个界面？`--ui`：挂在 DSH 外面的本地向导页（**能在页面上点着装**）
 
-觉得命令行清单不好对？加 `--ui` 起一个本地网页，每一行写清**装没装 / 什么版本 / 期望区间**，
-按钮只帮你**复制命令**：
+觉得命令行清单不好对？加 `--ui` 起一个本地网页：每一行写清**装没装 / 什么版本 / 期望区间**，
+而且**能在页面上点着装** —— 点了才装，不点不装。
 
 ```powershell
-# 起向导页（不会装任何东西、不会重启你的 DSH）
+# 起向导页（起来的时候什么都不装；点了【确认，开始】才装）
 npx @kira905/dsh-butler-install --ui
 
 # 换端口（默认 45080；被占会自动往后挑一个并打印实际地址）
 npx @kira905/dsh-butler-install --ui --port 45090
 ```
 
-打开它打印的地址（形如 `http://127.0.0.1:45080/`）就能看到清单表。页面上只有两个动作：
+打开它打印的地址（形如 `http://127.0.0.1:45080/`）就能看到清单表。页面上的动作：
 
 | 按钮 | 干什么 | 不干什么 |
 |---|---|---|
-| **复制命令** | 把这件要跑的**那一行**放进剪贴板 —— 与 `--dry-run` 打印的是**同一行**（同一个函数产出） | 不替你执行；你仍然要在终端里自己跑 |
+| **开始安装** | 算一遍"将对哪个 profile 做哪几件事"，把 16 项、profile 名、回滚点位置逐条念给你看 | **那一步一条命令都不跑、一个文件都不写** |
+| **确认，开始** | 真装。逐项显示 待装 / 安装中 / 成功 / 跳过 / 失败 | 不替你重启 DSH（装完要你自己重启，见下） |
+| **取消** | 杀掉当前那条命令的进程树 | **不是干净撤回**：已经装好的项会留着；页面会明说"已取消，装了一半" |
+| **卸载这次装的**（推荐） | 把这一轮装上去的真的卸掉：插件从 profile 摘掉、全局命令行包从全局前缀删掉 ⇒ 重查会真的变回"未装" | 不覆盖任何文件，所以你随后在侧边栏另装的插件不受影响 |
+| **只恢复配置文件到装前** | 只把这些声明层还到开跑前那一份 | `node_modules` 实体与全局 CLI 包**还在**，所以重开仍显示"已装"；期间有别的程序改过这些文件就**拒动** |
+| **复制命令** | 把这一行放进剪贴板 —— 与 `--dry-run` 打印的是**同一行**（同一个函数产出） | 不替你执行 |
 | **重查** | 重跑一遍探测、把最新读数写回同一张表 | 不改任何状态、不安装、不写文件 |
 
+> 🔴 **装完第 ⑥ 步：要重启 DSH，插件才会出现在侧边栏。** 宿主只在启动时读一次组合列表，
+> 不重启侧边栏不会多出任何东西 —— 这是最容易让人以为"装了没用、被骗了"的地方。
+> 顺手那行「复制命令」给的是**单项**原语命令；要整批自己跑，用页面上那条
+> **带 `--apply` 的整批命令**（不带 `--apply` 的那条只是演练，跑完什么都不装）。
+
 ### 为什么挂在 DSH 外面，而不是做成插件侧边栏页
 
 这是设计前提，不是偷懒：
 
 | | 插件侧边栏页（最初的想法） | 宿主外的本地页面（现在这样） |
 |---|---|---|
-| 要装插件 / 重启 DSH | 要（`dsh.bundle` + `cordis.patch.yml` + 重启） | **不要** |
+| 要装插件 / 重启 DSH 才能**打开这个向导页** | 要（`dsh.bundle` + `cordis.patch.yml` + 重启） | **不要** |
 | DSH 升级会不会崩 | 会（往页面里注入 client DOM，宿主一改就可能失效） | **不会**（它根本不进宿主） |
 | 装 DSH 之前能不能用 | 不能 | **能** —— 还没装宿主时，向导正好可以告诉你"你得先装 DSH" |
 | 成本 | 约 8h | **约 4h** |
@@ -65,10 +75,18 @@ npx @kira905/dsh-butler-install --ui --port 45090
 ### 安全边界（写死的，不是可选项）
 
 - 🔴 **只绑 `127.0.0.1`**：同一局域网的别的机器连不上。没有 `0.0.0.0` 开关，也不读环境变量改它。
-- 🔴 **只有两个 `GET`**：`GET /`（页面）与 `GET /state`（与 `--dry-run` 同源的 JSON）。
-  任何 `POST` / `PUT` / `DELETE` / `PATCH` / `OPTIONS` / `HEAD` 一律 **405** + `Allow: GET`，其余路径 404。
-- 🔴 **服务端一条命令都不执行**：没有写入口，页面也不会替你跑 `dsh` / `npm`。
-  启动时只做一次只读的 `npm config get prefix` 来定位全局包落点，之后**每个请求零 spawn**。
+- 🔴 **写入口只有四条**，全是 `POST`：`/install/preview`（算一遍，不装）、`/install/start`（真装，必须带 `confirm:true`）、
+  `/install/cancel`、`/install/rollback`（撤回的两个动作）。除这四条之外的任何写方法一律 **405**，未知路径 404；
+  `Allow` 响应头按路径给（写路径 `POST`、读路径 `GET`），不再是一刀切的 `Allow: GET`。
+- 🔴 **每个写入口都要过两道闸**：**安装令牌**（进程级，启动时生成一次、印在控制台、也内嵌在页面 meta 里；
+  只从页面读、绝不拼进 URL —— 拼进 URL 就落进历史记录与代理日志）**+ 同源校验**
+  （`Origin` 的 `host:port` 逐字等于 `server.address()` 的 `address:port`；端口是动态的，`--port 0` 也照样对）。
+  `Sec-Fetch-Site` **存在才校验**：Chrome 76+ / Safari 16.4+ 才有这个头，双击入口打开的是系统默认浏览器
+  （可能是 360 兼容模式），硬要求它等于给所有按钮静默 403。
+- 🔴 **这条要如实说**：它**防不住本机、同一个 Windows 用户下的其他程序** —— 那些程序读得到这个页面、
+  也调得到这些接口。它是一个"给本机同一个人用的安装器"，不是多用户隔离的服务，别当成后者。
+- 双击两次 `.cmd` 不会起两个服务：新入口先探 `127.0.0.1:45080`，认（`GET /state` 里的 `service` 标记）
+  是自家服务就把浏览器指过去 ⇒ 两个标签看同一个服务，天然单实例。
 - 端口被占：自动往后挑一个（最多 20 个），都不行就让系统分配，并**打印实际地址**。
 
 ### 「按顺序装」是什么意思
@@ -80,6 +98,59 @@ npx @kira905/dsh-butler-install --ui --port 45090
 > 看到"必须按 1→2→3 才能成功"这种话，那是假的仪式。
 
 
+## 不想碰命令？下载 exe 版（给完全不会命令行的人）
+
+上面那套都要敲命令。**连 PowerShell 都不想开**的话，下载一个 exe 就行：
+
+> **下载地址**：\[网盘链接 · 待填\]（作者挂到网盘后填这里；文件名形如
+> `dsh-butler-install-0.2.1-win-x64.exe`，约 89 MB）
+
+用法就三步：
+
+1. 下载 → **双击**。
+2. 会弹出一个黑窗口，它先体检（`dsh` 在不在、`npm` 在不在），然后**自动打开浏览器** ——
+   浏览器里那个页面就是上面说的安装向导，点两下就装完了。
+3. 装完直接关掉黑窗口（关窗口 = 关掉向导页；装到一半别关）。
+
+### 🔴 第一次运行会被 Windows 拦一下（这里必须说清楚）
+
+没有买代码签名证书（约 ¥1000+/年，暂时不买），所以 Windows SmartScreen 会弹：
+
+> **Windows 已保护你的电脑**
+
+十个人里有九个以为中病毒就关掉了。正确做法：
+
+1. 点弹窗里的 **「更多信息」**；
+2. 再点 **「仍要运行」**。
+
+（这拦的是"没有数字签名的程序"，不是"这个程序有毒"。看不放心就别装，用上面的 `npx` 命令版。）
+
+### 这个 exe 的前提
+
+- **这台电脑上已经装好了 DSH**（`dsh --version` 能打出版本号）。exe **不负责装 DSH**、也不装 Node；
+  缺了它会在黑窗口里用大字告诉你缺什么、怎么装，然后停住等你按任意键（不会一闪就没）。
+- 只有 Windows x64 版。**自带 node 运行时**所以 89 MB —— 好处是你机器上 node 不在 PATH 也能起界面。
+
+### exe 里到底跑了什么
+
+它就是同一个安装向导：界面 HTML 内嵌在 exe 里、清单 `suite-manifest.json` 也内嵌在 exe 里，
+所以**把 exe 单独拷到空目录也照样能起界面**（不读旁边任何文件）。命令行的行为也一模一样 —— 页面上
+「复制命令」给你的，就是 CLI 真会跑的那一行。
+
+### 自己造一个（仓里只留"怎么造"，exe 不进仓）
+
+```bash
+npm install                 # esbuild + postject（devDependencies）
+npm run build:exe           # → dist/dsh-butler-install-<版本>-win-x64.exe
+```
+
+实现是三步（`scripts/build-exe.mjs`，改路线前先看每步的注释）：esbuild 打单文件 CJS →
+`node --experimental-sea-config` 生成 blob → 复制本机 `node.exe` + postject 注入。
+`dist/` 在 `.gitignore` 里：exe 走网盘分发，进 git 只会把仓撑爆。
+
+> 这一版**不改** npm 包的行为：`dsh-butler-install`、`--ui`、`--apply`、退出码、参数一个都没动。
+> 会敲命令的人继续用上面那些；exe 只是同一套东西的"双击壳"。
+
 ## 它只做两件事，且只用两个原语
 
 | 原语 | 用来装什么 |
@@ -92,7 +163,8 @@ npx @kira905/dsh-butler-install --ui --port 45090
 - **不写** `dsh.profile.bundles` —— 那是宿主的活；本工具只调 `dsh plugin add`，让宿主自己登记。
 - **不写** `cordis.patch.yml` —— 需要手工 insert 的包，本工具只告诉你"它要手工挂"，不代劳。
 - **不碰** `node_modules` —— 不自己下载、不解包、不建链接。代码里没有第二条装包路径。
-- **不重启**你的 DSH，不改别的仓，不帮你决定要不要装。
+- **不替你重启** DSH，不改别的仓，不帮你决定要不要装。
+  ⚠️ 但**插件装完你确实要自己重启 DSH**，不然侧边栏不会出现它们 —— 这不是本工具偷懒，是宿主只在启动时读组合列表。
 
 删掉本工具，一切照旧：它没有留下任何自己的运行时状态（只有回滚快照，见下）。
 
@@ -113,6 +185,31 @@ npx @kira905/dsh-butler-install --ui --port 45090
 | `3` | 有步骤失败，但**已回滚干净** |
 | `4` | 有步骤失败，且**回滚不干净**（要人看：报告里会指出哪份文件对不上、快照在哪） |
 
+## 失败时那段英文是什么意思（人话归因）
+
+失败时**原始报错仍然原样打印**（一个字都不改），人话归因**追加在它后面**：
+
+```
+  ❌ 安装命令退出码 1：…（原始 stderr 首行，原样）
+    💡 这不是包坏了：你的安全软件（360 / EDR）拦了 pnpm 往 store 里建符号链接。
+       …（为什么）
+       怎么办：① 在安全软件里给 pnpm / node 放行（或暂时退出）  ② 换个不会被拦的位置做数据根（--home 指到别处）  ③ 直接重试一次（这类拦截是间歇的）
+```
+
+认得出的**环境障碍**（实现见 `lib/explain-failure.mjs`：纯函数，不跑命令、不读盘、不发网络）：
+
+| 归因 | 原始报错里长什么样 | 一句话 |
+|---|---|---|
+| `blocked-symlink` | `EPERM … symlink`（同一行）或栈里有 `registerProject` | 安全软件（360 / EDR）拦了 pnpm 建符号链接 —— **不是包坏了**；放行 / 换位置 / 重试 |
+| `store-mismatch` | `ERR_PNPM_UNEXPECTED_STORE` | 这个 profile 的 `node_modules` 是用**另一处 pnpm store** 装的，两边对不上；用回原来那处 / 在那个 profile 重装 / 换干净数据根 |
+| `unknown-pnpm` | 任何 `ERR_PNPM_<码>` | 确定是 pnpm 自己报的错，但这个码还没收录 ⇒ 把原码带走，去搜 / 贴给维护者 |
+
+**认不出来就一个字都不加**（不猜）。归因只做展示：**不参与判据**，也不改退出码（`0/2/3/4` 口径不变）。
+`--ui` 页面与 exe 走同一条路：页面进度里另有一条摘要行（`💡 …｜怎么办：…`），失败项的详情里也带这一句。
+
+退出码本身也写人话：Windows 上子进程被信号/异常结束时退出码是**无符号**的，
+会看到 `退出码 4294963248（= -4048，0xFFFFF030）` —— 原始数值仍在最前面，括号里是等价写法。
+
 ## 回滚：两级，别只做一级
 
 失败时默认**只退失败那一步**（前面已装好的几步保留，不用全重来）：
@@ -190,7 +287,7 @@ npx -p @kira905/dsh-butler-install dsh-butler-install-probe-scan <某仓根或
 | `--timeout` / `--budget` | 单步超时（默认 120s）/ 整批墙钟上限（默认 300s，超了就停下并回滚本批） |
 | `--snapshot-dir <dir>` | 快照目录，默认 `<数据根>/butler-install/snapshots/<时间戳>` |
 | `--json` | 只输出一份 JSON 汇总（人读的输出改走 stderr） |
-| `--ui` | 起一个**只读**的本地向导页（`127.0.0.1`、只有 `GET`、零执行），见上文。用它时 `--profile` 可省（默认 `web`） |
+| `--ui` | 起一个本地向导页，**能在页面上点着装**（点了才装、不点不装）：只绑 `127.0.0.1`、写入口四条都得令牌 + 同源。装完要重启 DSH 才在侧边栏出现。见上文。用它时 `--profile` 可省（默认 `web`） |
 | `--port <n>` | 向导页端口（只在 `--ui` 时有用），默认 `45080`；被占用会自动换一个并打印实际地址 |
 
 ## 它在 Windows 上怎么跑子进程
@@ -209,8 +306,11 @@ npx -p @kira905/dsh-butler-install dsh-butler-install-probe-scan <某仓根或
   挂载判据记"跳过"。
 - 不判"运行时会不会崩"：`--dump-config` 只证明组合树里有这一行。真要验运行时，得自己起一次服务看日志。
 - 不替你决定"要不要装某一件"，也不做"装完自动起服务"。
-- 🔴 向导页**故意不能"点一下就装"**：那需要开一个能替你执行命令的写入口，风险面比省下的两次复制大得多。
-  页面给的是命令，装的动作永远在终端里、由你按下回车。
+- 🔴 向导页**能装，但它防不住本机同用户的其它程序**（见上文安全边界）。要更严的隔离，就别在本机跑第三方程序。
+- 向导页的**取消不是干净撤回**：已装好的项留着，当前那一项可能只装了一半 —— 页面会直说，并给撤回入口。
+- 向导页的**「只恢复配置文件到装前」只还声明层**：`node_modules` 实体与全局 CLI 包还在；期间有别的程序改过那几份文件就拒动。
+- 向导页**不落自己的状态**：进度只在内存里。关掉窗口 = 这一批断了；重开页面按"现在装着什么"**现跑**给真实读数
+  （这比读一份可能过时的状态文件更准）。
 
 ## 夹具
 
@@ -222,10 +322,11 @@ npm test
 不读也不写真实数据根。覆盖：清单校验（每条错误都带文件名 + 行号）· 版本区间三态 ·
 探针三分支（含"标了 `help` 但该命令没实现 ⇒ 拒执行且不产生任何执行"）· 组合树三条计数判据
 （各自独立可触发）· 快照回放与核对 · 演练档零副作用（目录指纹必须一模一样）· 退出码 0/3/4 ·
-步级与整批回滚的差别 · 卸载 · 向导页（监听地址只许 `127.0.0.1` / 除两个 `GET` 外全 405 / 页面数据与
-`--dry-run` 同源 / 每请求零 spawn / 端口冲突自动换 / 不给 `--ui` 时输出逐字节不变）·
-以及**变异测试**：把监听地址改成 `0.0.0.0`、或把路由表放开非 `GET`、或让命令字符串不带期望区间，
-夹具必须**变红**（改坏了还绿 ⇒ 这条夹具是假的）。
+步级与整批回滚的差别 · 卸载 · 向导页（监听地址只许 `127.0.0.1` / **写入口只有那四条、其余 405** /
+令牌与同源两道闸 / 两步确认 / 进度轮询 / 撤回两条路与前置核对 / 页面数据与 `--dry-run` 同源 /
+每请求零 spawn / 端口冲突自动换 / 不给 `--ui` 时输出逐字节不变）·
+以及**变异测试（4 条）**：把监听地址改成 `0.0.0.0`、去掉令牌校验、把 `POST` 白名单放开到任意路径、
+去掉同源校验 —— 每一条都必须让夹具**变红在指定判据上**（改坏了还绿 ⇒ 这条夹具是假的）。
 
 ### 清单漂移判据（`test/range-drift.mjs`）
 

package/bin/install-ui.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * 双击入口（方案 §11.6 · B4：**第 0 步**）—— 先探、再起、然后自己开浏览器。
+ *
+ * 为什么"探测"能替代锁文件：
+ *  双击两次 `.cmd` = 两个进程。`listenLoopback()` 会很规矩地各自绑到 45080 / 45081，
+ *  于是两个页面都能点【开始安装】，同时对同一个 profile 跑 `dsh plugin add` + `npm i -g`。
+ *  与其落盘一把锁（还要处理陈旧锁、跨进程），不如先问一句"45080 上是不是已经有一个我们自己"：
+ *  是 ⇒ **不再起第二个服务**，把浏览器指过去。双击两次 = 两个标签看同一个服务，天然单实例。
+ *
+ * 🔴 为什么不在核心 CLI 上加 `--open`：
+ *  `lib/cli-args.mjs` 的纪律是"未知参数一律报错退出"，加参数 = 改对外契约。
+ *  而且"谁开浏览器"是 shell 行为，不该塞进核心 CLI（`dsh-butler-install --ui` 仍是"起服务 + 打印地址"）。
+ *
+ * 边界如实登记：用户显式 `--port <别的端口>` 时会探那个端口（不会去探 45080）；
+ * `--port 0` 时无从探测 ⇒ 直接起一个新的（这就是"我想要第二个实例"的显式表达）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseArgs, HELP_TEXT, EXIT } from '../lib/cli-args.mjs';
+import {
+  startUiServer,
+  uiBannerLines,
+  installExitHooks,
+  resolvePort,
+} from '../lib/ui-server.mjs';
+import { killAllRunningSync } from '../lib/exec.mjs';
+// 探测与开浏览器住在 lib 层（2026-10-31 拆的）：exe 入口要复用同一份实现，而它不能 import
+// 本文件（本文件顶层有 `await runEntry()`，ESM 打不成单文件 CJS）。对外导出名与语义一个没变。
+import { probeExistingUi, openBrowser } from '../lib/ui-probe.mjs';
+
+export { probeExistingUi, openBrowser };
+export { PROBE_TIMEOUT_MS } from '../lib/ui-probe.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * 入口本体（可注入：夹具要能在不起浏览器、也能不真起服务的前提下验"第二次只得到一个服务"）。
+ *
+ * @param {object} [io]
+ * @param {string[]} [io.argv]           参数（缺省 process.argv.slice(2)）
+ * @param {{write:(s:string)=>any}} [io.out]
+ * @param {(url:string) => boolean} [io.openBrowser]
+ * @param {Function} [io.startServer]    缺省 = lib/ui-server.mjs#startUiServer
+ * @param {boolean} [io.waitForShutdown] 缺省 true；夹具传 false（不然它会一直挂到 Ctrl+C）
+ * @returns {Promise<{exitCode:number, action:'help'|'version'|'error'|'reuse'|'start'|'closed', url?:string, port?:number}>}
+ */
+export async function runEntry({
+  argv = process.argv.slice(2),
+  out = process.stdout,
+  openBrowser: opener = openBrowser,
+  startServer = startUiServer,
+  waitForShutdown = true,
+} = {}) {
+  // 本入口等价于 `--ui`：用户不用知道这个开关（但给了也不冲突）
+  const args = argv.includes('--ui') ? argv.slice() : ['--ui', ...argv];
+  const { options, errors } = parseArgs(args);
+
+  if (options.help) {
+    out.write(HELP_TEXT);
+    return { exitCode: EXIT.OK, action: 'help' };
+  }
+  if (options.version) {
+    out.write(`${pkgVersion()}\n`);
+    return { exitCode: EXIT.OK, action: 'version' };
+  }
+  if (errors.length) {
+    for (const e of errors) out.write(`✖ ${e}\n`);
+    out.write('用 --help 看可用参数。\n');
+    return { exitCode: EXIT.USAGE, action: 'error' };
+  }
+
+  const port = resolvePort(options.uiPort);
+  if (port > 0) {
+    const found = await probeExistingUi({ port });
+    if (found.ok) {
+      out.write(`已经有一个向导页在 ${found.url} 跑着了（profile=${found.profile || '?'}）。\n`);
+      out.write('  不再起第二个：两个标签看同一个服务，天然单实例（这样不会同时对同一个 profile 装两遍）。\n');
+      opener(found.url);
+      return { exitCode: EXIT.OK, action: 'reuse', url: found.url, port };
+    }
+    out.write(`端口 ${port} 上没有我们自己的向导页（${found.reason}）⇒ 现在起一个。\n`);
+  }
+
+  const started = await startServer({ options, port: options.uiPort });
+  if (!started.ok) {
+    for (const line of started.log) out.write(`${line}\n`);
+    return { exitCode: started.exitCode, action: 'error' };
+  }
+  if (started.portChanged) {
+    out.write(`⚠ 端口 ${started.requestedPort} 被占了，已改用 ${started.port}\n`);
+  }
+  for (const line of uiBannerLines(started)) out.write(`${line}\n`);
+  installExitHooks({ out });
+  opener(started.url);
+  if (!waitForShutdown) {
+    return { exitCode: EXIT.OK, action: 'start', url: started.url, port: started.port };
+  }
+  await new Promise((resolve) => {
+    process.once('SIGINT', () => resolve());
+    process.once('SIGTERM', () => resolve());
+  });
+  killAllRunningSync();
+  await started.close();
+  out.write('\n向导页已关。\n');
+  return { exitCode: EXIT.OK, action: 'closed', url: started.url, port: started.port };
+}
+
+/** 直接跑（不是被 import）时才算主程序 —— junction 下面 argv[1] 是逻辑路径、import.meta.url 是物理路径，两边都取 realpath 再比 */
+function isMain() {
+  try {
+    const self = fs.realpathSync(fileURLToPath(import.meta.url));
+    const arg = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+    return Boolean(arg) && self === arg;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const result = await runEntry();
+  process.exitCode = result.exitCode;
+}

package/install-ui.cmd

@@ -0,0 +1,61 @@
+@echo off
+rem ============================================================================
+rem  DSH butler suite - double-click installer (web wizard)
+rem  ---------------------------------------------------------------------------
+rem  This file must stay PURE ASCII. A .cmd with CJK text gets parsed as GBK and
+rem  can break the command line. All Chinese copy lives on the web page.
+rem
+rem  What it does (three things only):
+rem    1) check node
+rem    2) hand off to bin/install-ui.mjs  (which probes for an already running
+rem       wizard, starts one if needed, and opens the browser by itself)
+rem    3) keep the window open on error so the message can be read
+rem
+rem  Why npx: the user only needs THIS file. No npm install, no clone.
+rem ============================================================================
+setlocal
+title DSH butler suite - installer
+echo.
+echo   ============================================
+echo    DSH butler suite - installer
+echo   ============================================
+echo.
+
+where node >nul 2>&1
+if errorlevel 1 goto nonode
+
+echo   [1/2] node found. Checking the installer page...
+echo   [2/2] The browser opens by itself when the page is ready.
+echo         Keep this window open while installing (Ctrl+C stops it).
+echo.
+
+npx -y -p "@kira905/dsh-butler-install@^0.3.0" dsh-butler-install-ui %*
+if errorlevel 1 goto failed
+goto done
+
+:nonode
+echo   [X] Node.js was not found.
+echo.
+echo       The installer needs Node.js 22 or newer.
+echo       Download:  https://nodejs.org/en/download
+echo       Install it, then double-click this file again.
+echo.
+pause
+exit /b 1
+
+:failed
+echo.
+echo   [X] The installer stopped with an error (exit code %ERRORLEVEL%).
+echo       Read the messages above - they say which package or which port failed.
+echo.
+pause
+exit /b 1
+
+:done
+echo.
+echo   The wizard is closed. If it was still installing, the log above shows
+echo   where it stopped. Nothing was changed silently.
+echo.
+pause
+endlocal
+exit /b 0

package/lib/cli-args.mjs

@@ -30,8 +30,12 @@ export const HELP_TEXT = `dsh-butler-install —— 大管家全家桶薄壳安
   --timeout <秒>          单步超时，默认 120
   --budget <秒>           整批墙钟上限，默认 300；超了停下并回滚本批
   --snapshot-dir <dir>    快照目录，默认 <数据根>/butler-install/snapshots/<时间戳>
-  --ui                    起一个**只读**的本地向导页（挂在 DSH 外面：不用装插件、不用重启）。
-                          只绑 127.0.0.1、只有 GET、服务端一条命令都不执行；页面只给你"复制命令 + 重查"。
+  --ui                    起一个本地向导页（挂在 DSH 外面：不用装插件、不用重启 DSH 就能开）。
+                          **页面能装**：点【开始安装】只把"要做什么"算一遍，再点【确认，开始】才真装；
+                          **不点那个确认，一条命令都不会跑**。
+                          安全边界（写死的）：只绑 127.0.0.1；每个写入口都要安装令牌 + 同源校验。
+                          🔴 它防不住本机同一个 Windows 用户下的其它程序（那些程序读得到页面、也调得到接口）。
+                          ⚠️ 插件装完要**重启 DSH** 才会出现在侧边栏 —— 本工具不替你重启。
                           用它的时候 --profile 可省（默认 web）
   --port <n>              向导页端口（只在 --ui 时有用），默认 45080；被占了会自动往后挑一个并打印实际地址
   --json                  只输出一份 JSON 汇总（人读的输出改走 stderr）
@@ -47,7 +51,9 @@ export const HELP_TEXT = `dsh-butler-install —— 大管家全家桶薄壳安
 
 只用两个原语：\`dsh plugin --profile <p> add|remove …\` 与 \`npm i -g|npm rm -g …\`。
 本工具**不写** dsh.profile.bundles、**不写** cordis.patch.yml、**不碰** node_modules —— 那些是宿主的事。
-\`--ui\` 是例外中的例外：它连装都不装，只念一遍"该在终端里跑什么"，然后一直只读地重查。
+\`--ui\` 的写入口只有四条：POST /install/preview、/start、/cancel、/rollback。
+每条都要安装令牌 + 同源校验；它跑的还是上面那两个原语，命令字符串与命令行模式由同一个函数生成
+—— 页面不是第二套安装逻辑，只是按按钮的壳。
 `;
 
 const VALUE_FLAGS = new Set([
@@ -140,10 +146,10 @@ export function parseArgs(argv) {
 
   if (options.help || options.version) return { options, errors };
 
-  // --ui = 只读向导页。它和"真装"是两码事，混着给就报错（免得有人以为页面会自己装）
+  // --ui = 向导页（装的动作在页面上点）：它和"命令行真装"是两条路，混着给就报错
   if (options.ui) {
-    if (options.apply) errors.push('--ui 是只读向导页（它一条命令都不执行），不能和 --apply 一起用：要真装请去掉 --ui');
-    if (options.uninstall) errors.push('--ui 是只读向导页（它一条命令都不执行），不能和 --uninstall 一起用');
+    if (options.apply) errors.push('--ui 是向导页（装的动作在页面上点【确认，开始】，不在命令行），不能和 --apply 一起用：要命令行真装请去掉 --ui');
+    if (options.uninstall) errors.push('--ui 是向导页（卸载用页面上的【卸载这次装的】），不能和 --uninstall 一起用');
     if (!options.profile) options.profile = 'web';
   } else if (options.uiPort !== null) {
     errors.push('--port 只在 --ui 时有用（现在没给 --ui）');

package/lib/dump.mjs

@@ -10,6 +10,10 @@
  *   # == <bundle 名>, patched by <包名>   ← 被 patch 的 bundle，别把这行算成"包里出现了"
  *   - id: <entry id>
  *     name: '<包名 或 内部模块名>'
+ *
+ * 条目的 name 有两种合法写法：包名本身（`@scope/pkg`），或**子包路径**
+ * （`@scope/pkg/内部模块`，实测 memory-toolkit 就是 `@kira905/dsh-memory-toolkit/dsh-memory-local`）。
+ * 后者曾被误判成"没挂上"（2026-10-31），匹配规则见 `mountMatches`。
  */
 export function analyzeDump(text) {
   const bundles = [];
@@ -48,19 +52,63 @@ export function analyzeDump(text) {
   return { bundles, entries, idCounts, nameCounts };
 }
 
-/** 某个包在组合树里的三条计数判据 */
+/**
+ * 一个条目是否属于某个包的挂载。
+ *
+ * 两种合法形态：
+ *   `name: '@scope/pkg'`               ← 包自身当条目（老形态）
+ *   `name: '@scope/pkg/内部模块'`      ← 子包路径挂载（宿主认的就是这个，实测
+ *                                        `@kira905/dsh-memory-toolkit/dsh-memory-local`）
+ * 前缀必须带 `/` 才算子路径：`@scope/dsh-foo` 不许命中包 `@scope/dsh-foo-bar`，
+ * 反过来 `@scope/dsh-foobar` 也不许命中包 `@scope/dsh-foo`。
+ */
+export function mountMatches(entryName, pkgName) {
+  if (!entryName || !pkgName) return false;
+  return entryName === pkgName || entryName.startsWith(`${pkgName}/`);
+}
+
+/**
+ * 某个包在组合树里的计数判据。
+ *
+ * 为什么要数次数：同一份实现被挂两次时宿主**不报错**、只多打一行 —— 用户装完一路
+ * 绿灯，实际用的是哪一份谁也说不清。所以防线是"每个 name 在整棵树里恰好 1 次"，
+ * 不是"出现过就算"。
+ *
+ * 为什么命中条目不是"恰好 1 条"：一个包可以**有意识地**挂多个内部模块，那时命中
+ * 条目是 2 条以上，每条 name 各 1 次 —— 这是合法形态，不许判死；真该红的是同一个
+ * name 出现两次（见上一条）。
+ */
 export function checkMounted(analysis, pkgName) {
   const bundleLines = analysis.bundles.filter((b) => b === pkgName).length;
-  const matching = analysis.entries.filter((e) => e.name === pkgName);
+  const matching = analysis.entries.filter((e) => mountMatches(e.name, pkgName));
+  const names = matching.map((e) => e.name);
+  const nameCounts = names.map((n) => analysis.nameCounts.get(n) || 0);
   const ids = matching.map((e) => e.id);
   const idCounts = ids.map((id) => analysis.idCounts.get(id) || 0);
   const problems = [];
   if (bundleLines !== 1) problems.push(`组合头 "# == ${pkgName}" 出现 ${bundleLines} 次（应为 1）（packages: ${analysis.bundles.filter((b)=>b.includes(pkgName)).join(' | ') || '无'}）`);
-  if (matching.length !== 1) problems.push(`条目 name=${pkgName} 出现 ${matching.length} 次（应为 1）`);
+  if (matching.length === 0) problems.push(`条目 name=${pkgName}（或子包路径 ${pkgName}/<内部模块>）出现 0 次（应至少 1 次）`);
+  const blamedNames = new Set();
+  for (let i = 0; i < names.length; i += 1) {
+    if (nameCounts[i] === 1 || blamedNames.has(names[i])) continue;
+    blamedNames.add(names[i]);
+    problems.push(`条目 name=${names[i]} 在整棵树里出现 ${nameCounts[i]} 次（应为 1）—— 同一份实现被挂两次时宿主不报错，只多打一行`);
+  }
   for (let i = 0; i < ids.length; i += 1) {
     if (idCounts[i] !== 1) problems.push(`条目 id=${ids[i]} 在整棵树里出现 ${idCounts[i]} 次（应为 1）—— 撞 id 时宿主不报错，只静默保留一份`);
   }
-  return { ok: problems.length === 0, bundleLines, nameCount: matching.length, ids, idCounts, problems };
+  return {
+    ok: problems.length === 0,
+    bundleLines,
+    entryCount: matching.length,
+    // 兼容老读数：nameCount 一直表示"命中条目数"，语义没变，只是门槛从 ===1 变成 >=1
+    nameCount: matching.length,
+    names,
+    nameCounts,
+    ids,
+    idCounts,
+    problems,
+  };
 }
 
 /** dump 的 stderr 里"某个 bundle 被跳过"的行（能归因时为安装器所用） */