@kira905/dsh-butler-install 0.1.0 → 0.2.1

package/README.md

@@ -30,6 +30,56 @@ node <dsh-butler-core 仓根>/selfcheck-replica.mjs --manifest suite-manifest.js
 > （只跑它内置的那几项判据）。本仓的 `suite-manifest.json` 的字段是**为它将来接清单准备的**
 > —— 字段含义见下文「清单字段」一节。别把它当成"已经能按清单跑了"。
 
+## 想要个界面？`--ui`：挂在 DSH 外面的只读向导页
+
+觉得命令行清单不好对？加 `--ui` 起一个本地网页，每一行写清**装没装 / 什么版本 / 期望区间**，
+按钮只帮你**复制命令**：
+
+```powershell
+# 起向导页（不会装任何东西、不会重启你的 DSH）
+npx @kira905/dsh-butler-install --ui
+
+# 换端口（默认 45080；被占会自动往后挑一个并打印实际地址）
+npx @kira905/dsh-butler-install --ui --port 45090
+```
+
+打开它打印的地址（形如 `http://127.0.0.1:45080/`）就能看到清单表。页面上只有两个动作：
+
+| 按钮 | 干什么 | 不干什么 |
+|---|---|---|
+| **复制命令** | 把这件要跑的**那一行**放进剪贴板 —— 与 `--dry-run` 打印的是**同一行**（同一个函数产出） | 不替你执行；你仍然要在终端里自己跑 |
+| **重查** | 重跑一遍探测、把最新读数写回同一张表 | 不改任何状态、不安装、不写文件 |
+
+### 为什么挂在 DSH 外面，而不是做成插件侧边栏页
+
+这是设计前提，不是偷懒：
+
+| | 插件侧边栏页（最初的想法） | 宿主外的本地页面（现在这样） |
+|---|---|---|
+| 要装插件 / 重启 DSH | 要（`dsh.bundle` + `cordis.patch.yml` + 重启） | **不要** |
+| DSH 升级会不会崩 | 会（往页面里注入 client DOM，宿主一改就可能失效） | **不会**（它根本不进宿主） |
+| 装 DSH 之前能不能用 | 不能 | **能** —— 还没装宿主时，向导正好可以告诉你"你得先装 DSH" |
+| 成本 | 约 8h | **约 4h** |
+| 代价 | 写入口的风险面大 | 要监听一个本地端口（所以**只许 `127.0.0.1`**） |
+
+### 安全边界（写死的，不是可选项）
+
+- 🔴 **只绑 `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**。
+- 端口被占：自动往后挑一个（最多 20 个），都不行就让系统分配，并**打印实际地址**。
+
+### 「按顺序装」是什么意思
+
+页面会给你**建议顺序 + 为什么这么建议**，但请看清它的含义：
+
+> **组件之间没有代码依赖，谁先装谁后装都能装上。** 真正有先后的只有三格：
+> Node（≥22）→ `dsh` 主包 → profile。下面的"顺序"是**给人看的排查路径**，不是成功的前提。
+> 看到"必须按 1→2→3 才能成功"这种话，那是假的仪式。
+
+
 ## 它只做两件事，且只用两个原语
 
 | 原语 | 用来装什么 |
@@ -140,6 +190,8 @@ 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`） |
+| `--port <n>` | 向导页端口（只在 `--ui` 时有用），默认 `45080`；被占用会自动换一个并打印实际地址 |
 
 ## 它在 Windows 上怎么跑子进程
 
@@ -157,6 +209,8 @@ npx -p @kira905/dsh-butler-install dsh-butler-install-probe-scan <某仓根或
   挂载判据记"跳过"。
 - 不判"运行时会不会崩"：`--dump-config` 只证明组合树里有这一行。真要验运行时，得自己起一次服务看日志。
 - 不替你决定"要不要装某一件"，也不做"装完自动起服务"。
+- 🔴 向导页**故意不能"点一下就装"**：那需要开一个能替你执行命令的写入口，风险面比省下的两次复制大得多。
+  页面给的是命令，装的动作永远在终端里、由你按下回车。
 
 ## 夹具
 
@@ -168,7 +222,26 @@ npm test
 不读也不写真实数据根。覆盖：清单校验（每条错误都带文件名 + 行号）· 版本区间三态 ·
 探针三分支（含"标了 `help` 但该命令没实现 ⇒ 拒执行且不产生任何执行"）· 组合树三条计数判据
 （各自独立可触发）· 快照回放与核对 · 演练档零副作用（目录指纹必须一模一样）· 退出码 0/3/4 ·
-步级与整批回滚的差别 · 卸载。
+步级与整批回滚的差别 · 卸载 · 向导页（监听地址只许 `127.0.0.1` / 除两个 `GET` 外全 405 / 页面数据与
+`--dry-run` 同源 / 每请求零 spawn / 端口冲突自动换 / 不给 `--ui` 时输出逐字节不变）·
+以及**变异测试**：把监听地址改成 `0.0.0.0`、或把路由表放开非 `GET`、或让命令字符串不带期望区间，
+夹具必须**变红**（改坏了还绿 ⇒ 这条夹具是假的）。
+
+### 清单漂移判据（`test/range-drift.mjs`）
+
+清单是单一真相，但真相会烂：写清单那天按当天的 latest 填区间，之后某个包跨了 0.x 的小版本
+（0 阶段里这就是大版本），caret 的上界就把新版挡在门外 —— 照清单装一遍拿到旧一套，而且装后自检
+**照样绿**（它读同一份清单）。所以这条判据对着清单外面的世界核，而不是自己核自己：
+
+```powershell
+node test/range-drift.mjs                                    # npm view，真网络
+node test/range-drift.mjs --offline test/fixtures/npm-latest-snapshot.json   # 读快照，零网络
+node test/range-drift.mjs --json --manifest <别的清单>
+```
+
+退出码：`0` 全部接受 · `3` 有漂移（照清单装会拿到旧版）· `4` 取数失败/无法判定（**绝不当通过**）·
+`2` 用法错或清单读不进来。`test/run-all.mjs` 里那一格走仓内快照、零网络；快照的 `capturedAt`
+是这份数据"什么时候是真的"的凭据，刷新清单区间时记得一起刷。
 
 ## 许可
 

package/bin/dsh-butler-install.mjs

@@ -9,6 +9,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs, HELP_TEXT, EXIT } from '../lib/cli-args.mjs';
 import { runSuite } from '../lib/run.mjs';
+import { runUiCli } from '../lib/ui-server.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -33,6 +34,9 @@ if (options.help) {
   for (const e of errors) process.stderr.write(`✖ ${e}\n`);
   process.stderr.write('用 --help 看可用参数。\n');
   process.exitCode = EXIT.USAGE;
+} else if (options.ui) {
+  // 向导页：只读、只绑 127.0.0.1、只有 GET。起完就挂着，Ctrl+C 结束（不留后台服务）
+  process.exitCode = await runUiCli(options);
 } else {
   const { exitCode, summary } = await runSuite(options);
   if (options.json) {

package/lib/cli-args.mjs

@@ -30,6 +30,10 @@ export const HELP_TEXT = `dsh-butler-install —— 大管家全家桶薄壳安
   --timeout <秒>          单步超时，默认 120
   --budget <秒>           整批墙钟上限，默认 300；超了停下并回滚本批
   --snapshot-dir <dir>    快照目录，默认 <数据根>/butler-install/snapshots/<时间戳>
+  --ui                    起一个**只读**的本地向导页（挂在 DSH 外面：不用装插件、不用重启）。
+                          只绑 127.0.0.1、只有 GET、服务端一条命令都不执行；页面只给你"复制命令 + 重查"。
+                          用它的时候 --profile 可省（默认 web）
+  --port <n>              向导页端口（只在 --ui 时有用），默认 45080；被占了会自动往后挑一个并打印实际地址
   --json                  只输出一份 JSON 汇总（人读的输出改走 stderr）
   --dry-run               显式写"演练"（与默认行为相同，便于脚本表达意图）
   -h, --help              看这份说明
@@ -43,6 +47,7 @@ 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\` 是例外中的例外：它连装都不装，只念一遍"该在终端里跑什么"，然后一直只读地重查。
 `;
 
 const VALUE_FLAGS = new Set([
@@ -55,9 +60,11 @@ const VALUE_FLAGS = new Set([
   '--timeout',
   '--budget',
   '--snapshot-dir',
+  '--port',
 ]);
 
-const BOOL_FLAGS = new Set(['--apply', '--upgrade', '--uninstall', '--json', '--dry-run', '--help', '-h', '--version', '-V', '--rollback']);
+const BOOL_FLAGS = new Set(['--apply', '--upgrade', '--uninstall', '--json', '--dry-run', '--help', '-h', '--version', '-V', '--rollback', '--ui']);
+
 
 export function parseArgs(argv) {
   const options = {
@@ -75,6 +82,8 @@ export function parseArgs(argv) {
     budgetMs: 300000,
     snapshotDir: null,
     json: false,
+    ui: false,
+    uiPort: null,
     help: false,
     version: false,
   };
@@ -116,6 +125,7 @@ export function parseArgs(argv) {
         if (flag === '--upgrade') options.upgrade = true;
         if (flag === '--uninstall') options.uninstall = true;
         if (flag === '--json') options.json = true;
+        if (flag === '--ui') options.ui = true;
         if (flag === '--help' || flag === '-h') options.help = true;
         if (flag === '--version' || flag === '-V') options.version = true;
         continue;
@@ -128,7 +138,18 @@ export function parseArgs(argv) {
     errors.push(`多余的位置参数：${token}`);
   }
 
-  if (!options.help && !options.version && !options.profile) errors.push('缺 --profile；用法：dsh-butler-install --profile <name> [--apply]');
+  if (options.help || options.version) return { options, errors };
+
+  // --ui = 只读向导页。它和"真装"是两码事，混着给就报错（免得有人以为页面会自己装）
+  if (options.ui) {
+    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）');
+  }
+
+  if (!options.profile) errors.push('缺 --profile；用法：dsh-butler-install --profile <name> [--apply]');
   return { options, errors };
 }
 
@@ -148,6 +169,10 @@ function applyValue(options, flag, value, errors) {
     options.home = value;
   } else if (flag === '--snapshot-dir') {
     options.snapshotDir = value;
+  } else if (flag === '--port') {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) errors.push(`--port 要 0–65535 的整数（0 = 让系统挑；现在读到 ${JSON.stringify(value)}）`);
+    else options.uiPort = n;
   } else if (flag === '--timeout') {
     const n = Number(value);
     if (!Number.isFinite(n) || n <= 0) errors.push(`--timeout 要正数秒（现在读到 ${JSON.stringify(value)}）`);

package/lib/plan.mjs

@@ -0,0 +1,354 @@
+/**
+ * 计划层 = 「清单 → 选中 → 现状 → 每项要跑的命令」的**唯一**出产地。
+ *
+ * 为什么要有这一层（2026-10-30 加 --ui 时抽出来的）：
+ * 向导页与 `--dry-run` 必须说同一句话。只要"页面自己拼一行命令"存在，两者迟早漂移，
+ * 而漂移的后果是用户复制到的那行**不是**安装器真正会跑的那行 —— 这类假一致比没有界面更坏。
+ * 所以命令字符串只在这里生成一次（`formatCommandLine` + `installStepFor`），
+ * 文本演练（lib/run.mjs）与 JSON（GET /state）都只做"渲染"，不做"拼接"。
+ *
+ * 本层是**纯读**：读清单、读 profile/全局前缀里的文件、扫 PATH。唯一可能起进程的是
+ * `npm config get prefix`（见 lib/state.mjs，只读且失败可回退）；`--ui` 会在启动时解析一次
+ * 再传进来（见 options.npmResolved），于是**每个请求零 spawn**。
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadManifest, formatManifestError, describeItem } from './manifest.mjs';
+import { satisfies, parseRange, describeRange } from './semver.mjs';
+import {
+  resolveHome,
+  readProfile,
+  profileInstalledVersion,
+  globalInstalledVersion,
+  resolveNpmPrefix,
+  findExistingBin,
+  findOnPath,
+  readInstalledDshDecl,
+} from './state.mjs';
+import { formatCommandLine } from './exec.mjs';
+import { EXIT } from './cli-args.mjs';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const DEFAULT_MANIFEST = path.join(PKG_ROOT, 'suite-manifest.json');
+
+export function shortName(name) {
+  const parts = String(name).split('/');
+  return parts[parts.length - 1];
+}
+
+/** 按 --only / --skip 选条目；组名、包名、短名、别名都认 */
+export function selectItems(manifest, { only = [], skip = [] } = {}) {
+  const items = manifest.items;
+  const errors = [];
+  const groups = [...new Set(items.map((i) => i.group))];
+  const resolve = (token) => items.filter((i) => (
+    i.name === token
+    || shortName(i.name) === token
+    || i.group === token
+    || (Array.isArray(i.aliases) && i.aliases.includes(token))
+  ));
+
+  let selected = items.slice();
+  if (only.length) {
+    const picked = new Set();
+    for (const token of only) {
+      const hits = resolve(token);
+      if (!hits.length) {
+        errors.push(`--only 里的 ${JSON.stringify(token)} 没匹配到任何条目（可选组：${groups.join(' / ')}；也可以直接写包名或别名）`);
+        continue;
+      }
+      for (const h of hits) picked.add(h.name);
+    }
+    selected = items.filter((i) => picked.has(i.name));
+  }
+
+  const dropped = new Set();
+  for (const token of skip) {
+    const hits = resolve(token);
+    if (!hits.length) errors.push(`--skip 里的 ${JSON.stringify(token)} 没匹配到任何条目`);
+    for (const h of hits) dropped.add(h.name);
+  }
+
+  return { items: selected.filter((i) => !dropped.has(i.name)), errors, groups };
+}
+
+export function installStepFor(item, { profile, npmPrefix }) {
+  // 装的时候把**清单里的期望区间**一起点名（`<包>@^x.y.z`）。
+  // 为什么必须带上：不带区间时拿到的是注册表 `latest` 标签指的那个版本，而它未必在
+  // 我们期望的区间里（实测踩过：latest 标签指着的版本与最高版本号不是一回事）。
+  // 带区间 = 让解析器只能落进期望区间，落不进去就报错，而不是"装了个别的版本还报成功"。
+  const spec = `${item.name}@${item.versionRange}`;
+  if (item.type === 'plugin') {
+    return { file: 'dsh', args: ['plugin', '--profile', profile, 'add', spec], env: {} };
+  }
+  return { file: 'npm', args: ['i', '-g', spec], env: npmPrefix ? { npm_config_prefix: npmPrefix } : {} };
+}
+
+export function uninstallStepFor(item, { profile, npmPrefix }) {
+  if (item.type === 'plugin') {
+    return { file: 'dsh', args: ['plugin', '--profile', profile, 'remove', item.name], env: {} };
+  }
+  return { file: 'npm', args: ['rm', '-g', item.name], env: npmPrefix ? { npm_config_prefix: npmPrefix } : {} };
+}
+
+/** 判定某一项"现在是否已满足"，纯读文件 */
+export function assessItem(item, ctx, profile, { upgrade = false } = {}) {
+  const mount = item.mount || (item.type === 'plugin' ? 'auto' : 'none');
+  if (item.type === 'plugin') {
+    const version = profileInstalledVersion(ctx.home, ctx.profile, item.name);
+    const depDeclared = Object.prototype.hasOwnProperty.call(profile.deps || {}, item.name);
+    const bundleRegistered = (profile.bundles || []).includes(item.name);
+    const range = version ? satisfies(item.versionRange, version) : 'no';
+    const decl = readInstalledDshDecl(ctx.home, ctx.profile, item.name);
+    // 该不该进组合列表：**以包实体的声明为准**。本版没声明 bundle 的包，
+    // 不登记也是正确状态（登记反而是空的），所以这里不拿"没登记"判它未满足。
+    const mountOk = mount !== 'auto' || bundleRegistered || !decl.hasBundle;
+    const satisfied = Boolean(version) && depDeclared && mountOk && (range === 'yes' || range === 'unknown');
+    return {
+      item,
+      type: 'plugin',
+      mount,
+      version,
+      depDeclared,
+      bundleRegistered,
+      range,
+      satisfied,
+      action: satisfied && !upgrade ? 'skip' : 'install',
+    };
+  }
+  const version = globalInstalledVersion(ctx.npmPrefix, item.name);
+  const binFile = item.probe && item.probe.cmd
+    ? findExistingBin({ cmd: item.probe.cmd, home: ctx.home, profile: ctx.profile, npmPrefix: ctx.npmPrefix })
+    : null;
+  const range = version ? satisfies(item.versionRange, version) : 'no';
+  const satisfied = Boolean(version) && Boolean(binFile) && (range === 'yes' || range === 'unknown');
+  return {
+    item,
+    type: 'cli',
+    mount: 'none',
+    version,
+    binFile,
+    range,
+    satisfied,
+    action: satisfied && !upgrade ? 'skip' : 'install',
+  };
+}
+
+/** 每一项装完拿什么判据（演练档与向导页共用同一句话） */
+export function criteriaText(item) {
+  const parts = [];
+  const kind = (item.probe && item.probe.kind) || 'existence';
+  if (kind === 'existence') {
+    parts.push(item.type === 'plugin'
+      ? `profile 的 node_modules/${item.name}/package.json 存在（只查文件，不执行）`
+      : `命令文件 ${item.probe.cmd} 在 .bin 或全局前缀下存在（只查文件，不执行）`);
+  } else if (kind === 'help') {
+    parts.push(`先静态核 ${item.probe.cmd} 源码里确有 --help 分支，再跑 ${item.probe.cmd} --help`);
+  } else {
+    parts.push(`跑 ${item.probe.cmd} ${(item.probe.argv || []).join(' ')}（清单声明只读：${item.probe.readonlyBecause}）`);
+  }
+  parts.push(`实体版本落在 ${describeRange(parseRange(item.versionRange))}`);
+  if (item.type === 'plugin' && (item.mount || 'auto') === 'auto') {
+    parts.push('dump-config 里组合头恰好 1 行、条目 name 恰好 1 条、该 id 在整棵树里恰好 1 次');
+  }
+  if (item.type === 'plugin' && item.mount === 'manual') {
+    parts.push('挂载不判（本包按设计不进组合列表）');
+  }
+  return parts.join(' · ');
+}
+
+/**
+ * 「建议顺序」= 阅读/排查顺序，**不是**技术依赖（方案 §5.3 的硬口径）。
+ * 组名 → 为什么建议排在这。没写到的组用兜底理由，绝不编一个假依赖出来。
+ */
+const GROUP_ORDER_WHY = {
+  核心: '先装面板：后面装的东西对不对，靠它看。',
+  界面: '界面增强，彼此之间没有先后，装完刷新页面就能看到。',
+  记忆: '它要占"记忆"这个位置，与官方记忆插件二选一；建议单独一步，装完自己确认组合列表里没有官方那份。',
+  CLI: '纯命令行工具，可以最后一批装。装完用"命令文件在不在"验，不跑 --help —— 这批命令里有不少会把未知参数当普通参数、照常干活。',
+  体检: '体检 / 急救类命令，最后装也行；平时用不到它们，不影响前几类。',
+};
+
+const ORDER_FALLBACK_WHY = '与其它组之间没有代码依赖，什么时候装都行；这里只是建议顺序。';
+
+export const ORDER_NOTES = [
+  '真正的技术顺序只有三格：Node ≥22 → dsh 主包 → profile（首次 `dsh plugin` 会自动建）→ 各组件。',
+  '组件之间没有代码依赖：谁先谁后都能装上。下面给的是**建议顺序 + 为什么这么建议** —— 换句话说，这里的"顺序"是给人看的排查路径，不是成功的前提。',
+];
+
+function buildOrder(groups, items) {
+  const out = [];
+  for (const group of groups) {
+    const inGroup = items.filter((i) => i.group === group);
+    if (!inGroup.length) continue;
+    out.push({
+      step: out.length + 1,
+      group,
+      why: GROUP_ORDER_WHY[group] || ORDER_FALLBACK_WHY,
+      items: inGroup.map((i) => i.name),
+    });
+  }
+  return out;
+}
+
+/**
+ * 唯一入口：产出「这次会做什么」的全部数据（文本演练与 /state 共用）。
+ *
+ * @param {object} options  与 CLI 选项同形（至少 profile / manifest / only / skip / upgrade / home / npmPrefix）
+ * @param {object} [pre]    `{ npm }`：已解析好的全局前缀，传了就不再 spawn（--ui 用它保证每请求零 spawn）
+ * @returns {Promise<{ok:boolean, exitCode:number, log:string[], summary:object, plan?:Array, state?:object}>}
+ */
+export async function buildSuiteState(options, pre = {}) {
+  const log = [];
+  const say = (text = '') => log.push(text);
+  const summary = {
+    mode: options.uninstall ? 'uninstall' : options.apply ? 'apply' : 'dry-run',
+    profile: options.profile,
+    home: null,
+    npmPrefix: null,
+    manifest: null,
+    items: [],
+    warnings: [],
+    excluded: [],
+    rollback: null,
+    exitCode: null,
+  };
+  const fail = (exitCode, errors) => ({ ok: false, exitCode, log, summary, errors: errors || log.slice() });
+
+  // ── 1. 清单 ────────────────────────────────────────────────
+  const manifestPath = options.manifest || DEFAULT_MANIFEST;
+  let manifest;
+  try {
+    manifest = loadManifest(manifestPath);
+  } catch (err) {
+    say(formatManifestError(err, path.basename(manifestPath)));
+    summary.exitCode = EXIT.USAGE;
+    return fail(EXIT.USAGE);
+  }
+  summary.manifest = manifest.path;
+  summary.excluded = manifest.excluded.map((e) => ({ id: e.id, reason: e.reason }));
+
+  // ── 2. 选条目 ──────────────────────────────────────────────
+  const selection = selectItems(manifest, options);
+  if (selection.errors.length) {
+    for (const e of selection.errors) say(`✖ ${e}`);
+    summary.exitCode = EXIT.USAGE;
+    return fail(EXIT.USAGE);
+  }
+  if (!selection.items.length) {
+    say('✖ 选完之后没有任何条目可做（检查 --only / --skip）');
+    summary.exitCode = EXIT.USAGE;
+    return fail(EXIT.USAGE);
+  }
+
+  // ── 3. 上下文 ──────────────────────────────────────────────
+  const home = resolveHome(options.home);
+  const profile = readProfile(home, options.profile);
+  const npm = pre.npm || await resolveNpmPrefix(options.npmPrefix);
+  const ctx = { home, profile: options.profile, npmPrefix: npm.prefix };
+  summary.home = home;
+  summary.npmPrefix = npm.prefix;
+
+  say(`清单：${manifest.path}`);
+  say(`共 ${manifest.items.length} 项，本次选中 ${selection.items.length} 项（组：${[...new Set(selection.items.map((i) => i.group))].join(' / ')}）`);
+  say(`数据根：${home}`);
+  say(`profile：${options.profile}（${profile.exists ? '已存在' : '尚不存在，真装时由宿主自动创建'}）`);
+  say(`全局包落点：${npm.prefix}（来源：${npm.source}）`);
+  if (manifest.excluded.length) {
+    for (const entry of manifest.excluded) {
+      say(`⏭ 不可安装项 ${entry.id}：${entry.reason}`);
+    }
+  }
+  say('');
+
+  // 前置：dsh 与 npm 两条原语都得在（只查文件存在，不执行）
+  const dshPath = findOnPath('dsh') || findExistingBin({ cmd: 'dsh', home, profile: options.profile, npmPrefix: npm.prefix });
+  const npmPath = findOnPath('npm');
+  const preflight = [];
+  if (!dshPath) preflight.push('找不到 dsh 命令（PATH 与全局前缀两处都查过）⇒ 插件类无从安装，也无法核对挂载');
+  if (!npmPath) preflight.push('找不到 npm 命令 ⇒ 命令行类无从安装');
+
+  // ── 4. 计划 ────────────────────────────────────────────────
+  const plan = selection.items.map((item) => assessItem(item, ctx, profile, { upgrade: options.upgrade }));
+  // 命令字符串只在这里生成一次：演练文案与 /state 都是它的渲染，不许别处再拼一遍
+  for (const entry of plan) {
+    const installStep = installStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
+    const uninstallStep = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
+    entry.command = formatCommandLine(installStep.file, installStep.args);
+    entry.commandUninstall = formatCommandLine(uninstallStep.file, uninstallStep.args);
+    entry.criteria = criteriaText(entry.item);
+  }
+  summary.items = plan.map((p) => ({
+    name: p.item.name,
+    type: p.item.type,
+    group: p.item.group,
+    mount: p.mount,
+    installedVersion: p.version,
+    inRange: p.range,
+    satisfied: p.satisfied,
+    action: p.action,
+  }));
+
+  const toInstall = plan.filter((p) => p.action === 'install');
+  const skipped = plan.filter((p) => p.action === 'skip');
+
+  if (!options.uninstall) {
+    say(`建议顺序（组件之间没有代码依赖，"顺序"只是排查建议）：先装面板 → 界面增强 → 记忆 → 命令行工具一批。`);
+    say('');
+  }
+
+  // ── 5. 给渲染层用的结构化快照（/state 就是它，加字段只加在这里） ─────
+  const items = plan.map((entry, index) => {
+    const d = describeItem(entry.item);
+    return {
+      step: index + 1,
+      name: d.name,
+      shortName: shortName(d.name),
+      type: d.type,
+      group: d.group,
+      mount: d.mount,
+      versionRange: entry.item.versionRange,
+      rangeText: d.rangeText,
+      aliases: Array.isArray(entry.item.aliases) ? entry.item.aliases : [],
+      note: typeof entry.item.note === 'string' ? entry.item.note : '',
+      installed: Boolean(entry.version),
+      installedVersion: entry.version,
+      inRange: entry.range,
+      satisfied: entry.satisfied,
+      action: entry.action,
+      probeKind: d.probeKind,
+      // 已满足的项 CLI 什么都不跑（不加 --upgrade 时）⇒ 命令就是 null，页面也就复制不到假命令
+      command: entry.action === 'install' ? entry.command : null,
+      commandUninstall: entry.commandUninstall,
+      criteria: entry.action === 'install' ? entry.criteria : null,
+    };
+  });
+
+  const state = {
+    ok: true,
+    exitCode: EXIT.OK,
+    generatedAt: new Date().toISOString(),
+    mode: summary.mode,
+    suite: manifest.meta && manifest.meta.suite ? manifest.meta.suite : null,
+    manifest: manifest.path,
+    home,
+    profile: options.profile,
+    profileExists: profile.exists,
+    npmPrefix: npm.prefix,
+    npmPrefixSource: npm.source,
+    upgrade: Boolean(options.upgrade),
+    counts: {
+      total: manifest.items.length,
+      selected: selection.items.length,
+      install: toInstall.length,
+      skip: skipped.length,
+    },
+    preflight,
+    excluded: summary.excluded.map((e) => ({ ...e })),
+    order: buildOrder([...new Set(plan.map((p) => p.item.group))], plan.map((p) => p.item)),
+    orderNotes: ORDER_NOTES.slice(),
+    items,
+  };
+
+  return { ok: true, exitCode: EXIT.OK, log, summary, plan, state, ctx, profile, preflight, npm, toInstall, skipped };
+}