@kira905/dsh-butler-install 0.3.5 → 0.3.7

package/README.md

@@ -1,10 +1,10 @@
 # dsh-butler-install
 
 > ### 这是什么
-> **上面那一整套的一键安装器**：一条命令装 16 个包，装完逐项自检，装坏了整批回滚。
+> **上面那一整套的一键安装器**：一条命令装 17 个包，装完逐项自检，装坏了整批回滚。
 >
 > ### 它解决什么
-> 一套东西散成十几个包，最容易死在「装一半」：有的装上了、有的没有，报错还只说 `ERR_PNPM_`。这个安装器给三件东西 —— ① **清单驱动**（16 项一次装齐，缺一项就算失败）② **整批回滚**（不是只撤最后一个）③ **失败说人话**（把 pnpm 的环境障碍翻成「安全软件拦了建链接」「store 不在同一块盘」）。
+> 一套东西散成十几个包，最容易死在「装一半」：有的装上了、有的没有，报错还只说 `ERR_PNPM_`。这个安装器给三件东西 —— ① **清单驱动**（17 项一次装齐，缺一项就算失败）② **整批回滚**（不是只撤最后一个）③ **失败说人话**（把 pnpm 的环境障碍翻成「安全软件拦了建链接」「store 不在同一块盘」）。
 >
 > ### 一条命令跑起来
 > ```powershell
@@ -25,6 +25,15 @@
 >
 > 另有一个 Windows exe（双击出界面）。它**自带 node 运行时**，所以 exe 自己不用你先装 Node；
 > 但**这台电脑上仍然得先有 DSH 和 npm** —— exe 只装大管家组件，不装 DSH 本身。
+>
+> **桌面版（Electron）DSH：能装，但要认对门。**
+> 桌面版把 `desktop` 这个 profile 留给了自己 —— npm 装的 CLI 去改它会被宿主直接拒绝
+> （`error: profile "desktop" is managed exclusively by the Electron application`，rc=1）。
+> 但桌面版**自带一条命令** `<安装目录>\resources\runtime\cli\bin\dsh.cmd`，用它加 `--profile desktop` 是能成的。
+> 本工具会自己认：数据根里有 `profiles/desktop`，或者能在常见安装目录 / 正在运行的桌面版进程里
+> 找到那条自带命令 ⇒ 用 `--profile desktop` 时**自动改用它**（命令原语不变，只是换了一条壳）。
+> 找不到自带命令时**不会硬来**：直接停手（rc=2），并告诉你怎么指路（`DSH_DESKTOP_DIR`）。
+> ⚠️ 桌面版只加载 `desktop` 这一个 profile；往 `--profile web` 里装 = 装了看不见。
 
 ---
 
@@ -33,7 +42,11 @@
 > 卖点不是"一键"，是"一键之后的可验证性"。
 > 一个包"装完 rc=0 但其实没生效"是这套生态里真实存在过的坑（宿主只会吐一行
 > `declares no dsh.bundle` 警告，然后把它装成普通依赖）。本工具逐包核对**包实体在不在、
-> 版本落不落在期望区间、插件到底有没有进组合列表**，任一条不过就判这一步失败。
+> 版本落不落在期望区间、装上来的是不是这个区间里现在能拿到的最新、插件到底有没有进组合列表**，
+> 任一条不过就判这一步失败。
+> 第四条"是不是最新"是 0.3.7 加的：只查"落在区间内"时，"装成了区间下界"也会绿 ——
+> 全批 rc=0，实际上装的全是旧版。取不到注册表（离线 / 私有源）时**不冒充通过**：
+> 汇总里单列一行「N 项没核是否落后」，或者用 `--no-registry` 显式关掉这条判据。
 
 ## 30 秒上手
 
@@ -75,7 +88,7 @@ npx @kira905/dsh-butler-install --ui --port 45090
 
 | 按钮 | 干什么 | 不干什么 |
 |---|---|---|
-| **开始安装** | 算一遍"将对哪个 profile 做哪几件事"，把 16 项、profile 名、回滚点位置逐条念给你看 | **那一步一条命令都不跑、一个文件都不写** |
+| **开始安装** | 算一遍"将对哪个 profile 做哪几件事"，把 17 项、profile 名、回滚点位置逐条念给你看 | **那一步一条命令都不跑、一个文件都不写** |
 | **确认，开始** | 真装。逐项显示 待装 / 安装中 / 成功 / 跳过 / 失败 | 不替你重启 DSH（装完要你自己重启，见下） |
 | **取消** | 杀掉当前那条命令的进程树 | **不是干净撤回**：已经装好的项会留着；页面会明说"已取消，装了一半" |
 | **卸载这次装的**（推荐） | 把这一轮装上去的真的卸掉：插件从 profile 摘掉、全局命令行包从全局前缀删掉 ⇒ 重查会真的变回"未装" | 不覆盖任何文件，所以你随后在侧边栏另装的插件不受影响 |
@@ -160,9 +173,10 @@ npx @kira905/dsh-butler-install --ui --port 45090
 - **这台电脑上已经装好了 DSH，并且有 npm** —— `dsh --version` 与 `npm --version` 都能打出版本号。
   exe **不负责装 DSH、也不负责装 npm**：开界面之前它先体检这两件事，缺哪个就在黑窗口里用大字
   说清楚、停住等你按任意键（不会一闪就没）。
-- **装的是「桌面版 / 图形版」DSH 的话，它可能没带命令行** —— 那种情况下装不上大管家（exe 走的是
-  `dsh plugin` 这条命令）。需要再装一个命令行版：`npm i -g @deepseek-ai/dsh`；
-  `dsh --version` 能打出版本号，再双击 exe。
+- **装的是「桌面版 / 图形版」DSH 的话**：用 `--profile desktop`。桌面版自带一条命令行
+  （`<安装目录>\resources\runtime\cli\bin\dsh.cmd`），本工具会自己找到它并用它装；
+  找不到时会停手告诉你用 `DSH_DESKTOP_DIR` 指一下安装目录。**别用 `--profile web`** ——
+  桌面版不加载那个 profile，装了看不见。同一个 `dsh --version` 能打出版本号说明 CLI 版也在。
 - 只有 Windows x64 版。**自带 node 运行时**所以 89 MB —— 省的是「**exe 自己**不用装 node 就能跑起来」
   （exe 里已经打了一份 node.exe）。但请别读成「全流程不依赖本机 node」：**装插件那一步仍然要调这台电脑的 npm**。
 

package/lib/cli-args.mjs

@@ -18,6 +18,10 @@ export const HELP_TEXT = `dsh-butler-install —— 大管家全家桶薄壳安
   dsh-butler-install --profile <profile> [选项]
 
   --profile <name>        要操作的 profile（必填）。宿主会用它定位 <数据根>/profiles/<name>
+                          ⚠️ 桌面版（Electron 版）用户请写 desktop：本工具会改用桌面版自带的
+                          dsh.cmd 去装（npm 装的 CLI 改不动那个 profile，宿主会直接拒绝）
+  --no-registry           不去注册表核"装上来的是不是最新合规版"（离线/私有源取不到时用；
+                          关掉之后判据只剩"落在区间内"，报告里会明说没核过是否落后）
   --manifest <path>       清单文件，默认用包内自带的 suite-manifest.json
   --apply                 真装。**不加就是演练档**：只打印将要执行的命令与每步判据，一条命令都不跑
   --only <列表>           只装这些：组名 / 包名 / 别名，逗号分隔，可重复给
@@ -69,12 +73,14 @@ const VALUE_FLAGS = new Set([
   '--port',
 ]);
 
-const BOOL_FLAGS = new Set(['--apply', '--upgrade', '--uninstall', '--json', '--dry-run', '--help', '-h', '--version', '-V', '--rollback', '--ui']);
+const BOOL_FLAGS = new Set(['--apply', '--upgrade', '--uninstall', '--json', '--dry-run', '--help', '-h', '--version', '-V', '--rollback', '--ui', '--no-registry']);
 
 
 export function parseArgs(argv) {
   const options = {
     profile: null,
+    // profile 是"用户亲手点的名"还是"默认填的名"（--ui 默认 web）：桌面版自动切 profile 要用它
+    profileExplicit: false,
     manifest: null,
     apply: false,
     only: [],
@@ -90,6 +96,7 @@ export function parseArgs(argv) {
     json: false,
     ui: false,
     uiPort: null,
+    noRegistry: false,
     help: false,
     version: false,
   };
@@ -132,6 +139,7 @@ export function parseArgs(argv) {
         if (flag === '--uninstall') options.uninstall = true;
         if (flag === '--json') options.json = true;
         if (flag === '--ui') options.ui = true;
+        if (flag === '--no-registry') options.noRegistry = true;
         if (flag === '--help' || flag === '-h') options.help = true;
         if (flag === '--version' || flag === '-V') options.version = true;
         continue;
@@ -163,6 +171,7 @@ function applyValue(options, flag, value, errors) {
   if (flag === '--profile') {
     if (!/^[A-Za-z0-9._-]+$/.test(value)) errors.push(`--profile 只接受字母数字与 . _ -（现在读到 ${JSON.stringify(value)}）`);
     options.profile = value;
+    options.profileExplicit = true;
   } else if (flag === '--manifest') {
     options.manifest = value;
   } else if (flag === '--only') {

package/lib/desktop.mjs

@@ -0,0 +1,218 @@
+/**
+ * 桌面版（Electron 版 DSH）的识别与它自带命令的定位。
+ *
+ * 为什么要单独一层（2026-11-06 真机实测，见
+ * `docs\交付报告-桌面端适配与骨架装机实测-20261106.md` §2.5）：
+ *  - 桌面版把 `~/.dsh/profiles/desktop` 当**自己的** profile，用 npm 装的 CLI 去改它，
+ *    宿主会直接拒绝：`error: profile "desktop" is managed exclusively by the Electron application`（rc=1）；
+ *  - 但桌面版**自带一条命令** `<安装目录>\resources\runtime\cli\bin\dsh.cmd`，
+ *    用它加 `--profile desktop` 是**能成**的（实测 rc=0，dependencies 与 dsh.profile.bundles 都登记）；
+ *  - 反过来，往桌面版用户的机器上用 `--profile web` 装插件 = 那套界面永远不加载 = 假绿。
+ *
+ * 所以这里只做两件事：认出来，找到它自带的命令。**找不到就如实说找不到**，
+ * 由上层决定硬拒绝（绝不偷偷退回用 CLI 版去改桌面版 profile）。
+ *
+ * 探测只看三个来源，全都不写盘：① 桌面版自建的 profile ② 已知安装路径 ③ 运行中的进程。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnCommand } from './exec.mjs';
+
+/** 桌面版自带的命令行入口在安装目录里的固定相对位置 */
+export const DESKTOP_CLI_REL = path.join('resources', 'runtime', 'cli', 'bin', 'dsh.cmd');
+const DESKTOP_EXE = 'DeepSeek Harness.exe';
+
+function isFile(file) {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** `<root>` 下面是否真的有一套桌面版（主程序 + 自带命令都在位） */
+export function looksLikeDesktopRoot(root) {
+  if (!root) return null;
+  const exe = path.join(root, DESKTOP_EXE);
+  const cli = path.join(root, DESKTOP_CLI_REL);
+  if (isFile(exe) && isFile(cli)) return { root, exe, cli };
+  return null;
+}
+
+/** 已知安装目录（Windows 上安装器默认落在 %LOCALAPPDATA%\Programs 或用户指定的盘） */
+export function desktopRootCandidates(env = process.env, platform = process.platform) {
+  const out = [];
+  const push = (dir) => { if (dir) out.push(path.resolve(dir)); };
+  if (env.DSH_DESKTOP_DIR) push(env.DSH_DESKTOP_DIR);
+  if (platform !== 'win32') {
+    push('/Applications/DSH Desktop.app/Contents/Resources/..');
+    return out;
+  }
+  const local = env.LOCALAPPDATA || '';
+  const roaming = env.APPDATA || '';
+  if (local) {
+    push(path.join(local, 'Programs', 'DSH Desktop'));
+    push(path.join(local, 'Programs', 'DSH-Desktop'));
+    push(path.join(local, 'DSH Desktop'));
+    // %LOCALAPPDATA%\Programs 下常见一批 Electron 应用：按名字捞一遍（只 readdir 一层）
+    try {
+      for (const name of fs.readdirSync(path.join(local, 'Programs'), { withFileTypes: true })) {
+        if (!name.isDirectory()) continue;
+        if (/dsh|deepseek/i.test(name.name)) push(path.join(local, 'Programs', name.name));
+      }
+    } catch { /* 目录不存在是常态 */ }
+  }
+  if (roaming) push(path.join(roaming, 'DSH Desktop'));
+  for (const key of ['ProgramFiles', 'ProgramW6432', 'ProgramFiles(x86)']) {
+    if (env[key]) {
+      push(path.join(env[key], 'DSH Desktop'));
+      push(path.join(env[key], 'DSH-Desktop'));
+    }
+  }
+  // 用户的安装器允许挑盘：只查存在的盘符，名字就两种写法，成本是几十次 existsSync
+  for (const letter of 'CDEFGHIJKLMNOPQRSTUVWXYZ') {
+    const driveRoot = `${letter}:\\`;
+    try {
+      if (!fs.existsSync(driveRoot)) continue;
+    } catch { continue; }
+    push(path.join(driveRoot, 'DSH Desktop'));
+    push(path.join(driveRoot, 'DSH-Desktop'));
+  }
+  return out;
+}
+
+/**
+ * 从运行中的桌面版进程反查安装目录。**只在这台机器上真的跑着桌面版时才有结果**，
+ * 所以放在最后一道 —— 它要起一个 PowerShell（几百毫秒），前面能命中就别用它。
+ */
+export async function findDesktopRootFromProcess(opts = {}) {
+  if ((opts.platform || process.platform) !== 'win32') return null;
+  const run = opts.run || ((f, a, o) => spawnCommand(f, a, o));
+  const script = `$p = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -like '*Harness*' } | Select-Object -First 1; if ($p) { $p.Path }`;
+  const res = await run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], { timeoutMs: opts.timeoutMs || 15000, quiet: true });
+  if (res.code !== 0) return null;
+  const exePath = String(res.stdout || '').trim().split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
+  if (!exePath || !isFile(exePath)) return null;
+  return path.dirname(exePath);
+}
+
+/**
+ * 「桌面版自带命令在哪」的缓存 —— 它跟数据根无关，只跟安装目录有关。
+ * 为什么必须有：向导页的 GET /state 每个请求都会走 buildSuiteState，一开页面就是几百次
+ * 探测；不缓存的话每次都扫 26 个盘符、必要时还起一个 PowerShell（本机实测把测试从 1 分钟拖到 4 分钟以上）。
+ */
+const cliCache = new Map();
+
+/** 夹具用：伪造/撤掉一套桌面版目录之后清缓存 */
+export function resetDesktopCliCache() {
+  cliCache.clear();
+}
+
+function cliCacheKey(opts, env, platform) {
+  return [
+    platform,
+    env.DSH_DESKTOP_DIR || '',
+    env.DSH_DESKTOP_CLI || '',
+    Array.isArray(opts.roots) ? opts.roots.join('|') : '',
+    opts.allowProcessProbe === false ? 'noprobe' : 'probe',
+  ].join('::');
+}
+
+/**
+ * 找出桌面版自带命令。
+ * @param {object} [opts] { home, env, platform, run, allowProcessProbe, roots }
+ * @returns {Promise<{cli:string, root:string, source:string, evidence:string[]}>}
+ */
+export async function findDesktopCli(opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const key = cliCacheKey(opts, env, platform);
+  if (cliCache.has(key)) return cliCache.get(key);
+  const result = await findDesktopCliUncached({ ...opts, env, platform });
+  cliCache.set(key, result);
+  return result;
+}
+
+async function findDesktopCliUncached(opts = {}) {
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const evidence = [];
+
+  const explicit = env.DSH_DESKTOP_CLI;
+  if (explicit) {
+    if (isFile(explicit)) return { cli: explicit, root: path.dirname(path.dirname(path.dirname(path.dirname(explicit)))), source: '$DSH_DESKTOP_CLI', evidence: [`显式指定 ${explicit}`] };
+    evidence.push(`$DSH_DESKTOP_CLI 指向的文件不存在：${explicit}`);
+  }
+
+  for (const root of (Array.isArray(opts.roots) ? opts.roots : desktopRootCandidates(env, platform))) {
+    const hit = looksLikeDesktopRoot(root);
+    if (hit) {
+      evidence.push(`安装目录命中：${root}`);
+      return { cli: hit.cli, root: hit.root, source: 'known-path', evidence };
+    }
+  }
+
+  if (opts.allowProcessProbe !== false && platform === 'win32') {
+    try {
+      const root = await findDesktopRootFromProcess({ run: opts.run, platform, timeoutMs: opts.timeoutMs });
+      if (root) {
+        const hit = looksLikeDesktopRoot(root);
+        if (hit) {
+          evidence.push(`从运行中的进程反查到安装目录：${root}`);
+          return { cli: hit.cli, root: hit.root, source: 'process', evidence };
+        }
+        evidence.push(`进程目录 ${root} 里没有完整的一套桌面版文件`);
+      }
+    } catch (err) {
+      evidence.push(`进程反查失败（${err && err.message ? err.message : err}）`);
+    }
+  }
+  if (!evidence.length) evidence.push('已知安装目录、$DSH_DESKTOP_DIR、运行中的进程三处都没找到');
+  return { cli: '', root: '', source: '', evidence };
+}
+
+/**
+ * 综合探测：桌面版在不在、自带命令在哪、它自建的 profile 在不在。
+ *
+ * @returns {Promise<{detected:boolean, cliCmd:string, root:string, source:string,
+ *   desktopProfileExists:boolean, evidence:string[]}>}
+ */
+export async function detectDesktop(opts = {}) {
+  const home = opts.home;
+  const env = opts.env || process.env;
+  const desktopProfileFile = home ? path.join(home, 'profiles', 'desktop', 'package.json') : '';
+  let desktopProfileExists = false;
+  try {
+    desktopProfileExists = Boolean(desktopProfileFile) && fs.existsSync(desktopProfileFile);
+  } catch { desktopProfileExists = false; }
+
+  const found = await findDesktopCli({ env, platform: opts.platform, run: opts.run, allowProcessProbe: opts.allowProcessProbe, timeoutMs: opts.timeoutMs, roots: opts.roots });
+  const evidence = found.evidence.slice();
+  if (desktopProfileExists) evidence.unshift(`数据根里有桌面版自建的 profile：${desktopProfileFile}`);
+  return {
+    detected: Boolean(desktopProfileExists || found.cli),
+    cliCmd: found.cli,
+    root: found.root,
+    source: found.source,
+    desktopProfileExists,
+    evidence,
+  };
+}
+
+/** 找不到自带命令时给人看的那段话（硬拒绝时原样打印） */
+export function desktopMissingHelp(home) {
+  const homeText = home || '<数据根>';
+  return [
+    '这是桌面版（Electron 版）DSH 的 profile：本机 npm 装的 CLI 改不动它',
+    '（宿主会回 error: profile "desktop" is managed exclusively by the Electron application）。',
+    '要装就得用桌面版**自带**的那条命令：',
+    '  <桌面版安装目录>\\resources\\runtime\\cli\\bin\\dsh.cmd',
+    '本工具在下面三处都找过，没找到它：',
+    '  ① 环境变量 DSH_DESKTOP_DIR / DSH_DESKTOP_CLI',
+    '  ② 常见安装目录（%LOCALAPPDATA%\\Programs\\DSH Desktop、Program Files、各盘根下的 DSH Desktop）',
+    '  ③ 正在运行的桌面版进程',
+    `要么把桌面版装上/打开一次让它出现在上面任一位置，要么用 DSH_DESKTOP_DIR 指一下安装目录；`,
+    `确认这本机压根没有桌面版的话，就别用 --profile desktop（当前数据根：${homeText}）。`,
+  ].join('\n');
+}

package/lib/exec.mjs

@@ -1,15 +1,29 @@
 /**
  * 跑一条外部命令（只跑官方命令：`dsh plugin ...`、`npm ...`）。
  *
- * Windows 上的两个实测坑，这里一次兜住：
- *  1) `spawnSync('npm')` 直接 **ENOENT** —— `npm` 其实是 `npm.cmd` 壳，无 shell 解析不到；
- *  2) `spawnSync('npm.cmd')` 直接 **EINVAL** —— Node 18.20+ 拒绝在没有 shell 的情况下执行 .cmd。
- * 结论：在 Windows 上必须过 shell。为了不让参数被 shell 二次解释，这里对所有参数做
- * 最小必要引号化（只有含空格/特殊字符的参数才加引号），并且命令与参数分开维护 ——
- * 打印出来的命令行与真正执行的命令行是同一个函数生成的，报告里不会出现"说要跑 A、
- * 实际跑了 B"。
+ * 🔴 这里有一条**绝不能退回去**的口径（2026-11-06 实测修的，见
+ * `docs\交付报告-桌面端适配与骨架装机实测-20261106.md` §3.3）：
+ * **不许过 shell**。历史版本用 `spawn(cmdline, { shell: true })`，Windows 上等于走
+ * `cmd.exe /c`，而 `^` 是 cmd 的转义符：
+ *     cmd /c "echo @kira905/dsh-ops-toolkit@^0.1.0"   →   @kira905/dsh-ops-toolkit@0.1.0
+ * 于是 `npm i -g <包>@^x.y.z` 静默退化成"精确钉死下界"，而装后自检只查"落在区间内"，
+ * 下界当然在区间内 ⇒ 全绿但全是旧版。参数一旦过 shell 就不再是我们写下的那串。
+ *
+ * Windows 上又不能直接 spawn `.cmd`（Node 18.20+ 起 `spawnSync('npm.cmd')` 直接 EINVAL，
+ * 见下），所以这里的做法是：**把 .cmd 壳解析成它真正要跑的那个可执行 + 参数**，
+ * 然后用 `shell: false` 直接起进程 —— 参数原样交给进程，一个字都不经过 cmd。
+ *
+ *   npm.cmd          → node.exe  <...>\node_modules\npm\bin\npm-cli.js
+ *   dsh.cmd          → node.exe  <...>\node_modules\@deepseek-ai\dsh\lib\bin.js
+ *   桌面版 dsh.cmd   → "DeepSeek Harness.exe" --expose-internals <...>\dsh-desktop-host\lib\cli.js
+ *                      （外加壳里 set 的环境变量，例如 ELECTRON_RUN_AS_NODE=1）
+ *
+ * 解析不出来才退回 `cmd.exe /d /s /c`，并且**必须**把参数里的 cmd 元字符（`^` `&` `|`）
+ * 转义 —— 兜底可以慢，但不能静默改成另一条命令。
  */
 import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 const SAFE_ARG = /^[A-Za-z0-9@/._:+=,~^()-]+$/;
 
@@ -19,13 +33,266 @@ export function quoteArgForWindows(arg) {
   return `"${s.replace(/"/g, '\\"')}"`;
 }
 
-/** 生成"可打印也可执行"的命令行（Windows 走 shell，其它平台参数数组直传） */
+/** 生成"可打印"的命令行。⚠️ 它只用于**展示给人看**；真正执行走 resolveCommand + 参数数组。 */
 export function formatCommandLine(file, args) {
   const parts = [file, ...args];
   if (process.platform === 'win32') return parts.map(quoteArgForWindows).join(' ');
   return parts.map((p) => (/^[A-Za-z0-9@/._:+=,~^-]+$/.test(String(p)) ? p : `'${String(p).replace(/'/g, `'\\''`)}'`)).join(' ');
 }
 
+/* ------------------------------------------------------------------ 找命令 */
+
+const WIN_EXTS = ['', '.cmd', '.CMD', '.exe', '.EXE', '.bat', '.BAT', '.ps1', '.js'];
+
+/**
+ * 在 PATH 上找一个**能被 spawn 起来**的命令。
+ *
+ * 🔴 后缀顺序是有讲究的（2026-11-06 实测）：Windows 的 npm 全局目录里，同一个命令常常
+ * 同时存在 `dsh`（给 bash 用的无扩展脚本）、`dsh.cmd`、`dsh.ps1`。按"无扩展优先"找，
+ * 拿到的是那个 bash 脚本，spawn 必失败。所以这里显式按 exe → cmd → bat 排。
+ * `.ps1` 不认：要另起 PowerShell 才能跑，不属于本工具的用法。
+ */
+export function findExecutableOnPath(cmd, { platform = process.platform, env = process.env } = {}) {
+  const exts = platform === 'win32' ? ['.exe', '.EXE', '.cmd', '.CMD', '.bat', '.BAT'] : [''];
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const file = path.join(dir, `${cmd}${ext}`);
+      try {
+        if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
+      } catch {
+        /* 权限/竞态一律跳过，PATH 扫描不该抛 */
+      }
+    }
+  }
+  return null;
+}
+
+/** 在 PATH 上找一个命令（只查文件存在，不执行；Windows 按常见后缀补壳） */
+export function findOnPath(cmd, { platform = process.platform, env = process.env } = {}) {
+  const exts = platform === 'win32' ? WIN_EXTS : [''];
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const file = path.join(dir, `${cmd}${ext}`);
+      try {
+        if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
+      } catch {
+        /* 权限/竞态一律跳过，PATH 扫描不该抛 */
+      }
+    }
+  }
+  return null;
+}
+
+/* ------------------------------------------------------- .cmd / .bat 壳解析 */
+
+/** `set "NAME=value"`（含大小写混杂的 SET） */
+const SET_RE = /^\s*set\s+"?([A-Za-z_][A-Za-z0-9_]*)=([^"\r\n]*)"?\s*$/i;
+
+/** `%~dp0` 自带尾部分隔符，拼完会出现 `\\`；绝对路径统一过一遍 path.normalize（展示与 spawn 都干净） */
+function tidyPathToken(token) {
+  const t = String(token);
+  if (!/[\\/]/.test(t)) return t;
+  if (/^[A-Za-z]:[\\/]/.test(t) || t.startsWith('\\\\')) return path.normalize(t);
+  return t;
+}
+
+/** 壳内部的局部变量（`_prog` / `NODE_EXE` / `PATHEXT` …）不该漏进子进程的环境 */
+const SHIM_INTERNAL_VARS = new Set(['_prog', 'node_exe', 'pathext', 'dp0', 'comspec']);
+
+function tokenizeCmdLine(line) {
+  const tokens = [];
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === ' ' || ch === '\t') { i += 1; continue; }
+    if (ch === '"') {
+      let j = i + 1;
+      let buf = '';
+      while (j < line.length && line[j] !== '"') { buf += line[j]; j += 1; }
+      tokens.push(buf);
+      i = j + 1;
+    } else {
+      let j = i;
+      while (j < line.length && line[j] !== ' ' && line[j] !== '\t') j += 1;
+      tokens.push(line.slice(i, j));
+      i = j;
+    }
+  }
+  return tokens;
+}
+
+/**
+ * 读一个 .cmd/.bat 壳，抽出「它到底会起什么进程」。
+ *
+ * 只认结构清晰的三类（npm/pnpm 生成的 shim、桌面版自带 shim 都属于这三类）：
+ *   ① `"<prog>" "<script>.js" %*`（prog 可能是个变量，如 %_prog%）
+ *   ② `node "<script>.js" %*`
+ *   ③ `"<...>.exe" <args...> "<...>.js" %*`（桌面版：先 set 环境变量再起 Electron）
+ *
+ * @returns {{file:string, args:string[], env:Object, via:string, problem?:string}}
+ */
+export function parseWindowsShim(shimFile) {
+  let text;
+  try {
+    text = fs.readFileSync(shimFile, 'utf8');
+  } catch (err) {
+    return { file: '', args: [], env: {}, via: 'shim-error', problem: `读不到壳文件 ${shimFile}（${err.code || err.message}）` };
+  }
+  const dir = path.dirname(shimFile);
+  const vars = new Map();
+  const setVars = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const m = SET_RE.exec(rawLine);
+    if (!m) continue;
+    const name = m[1].toLowerCase();
+    const value = m[2].trim();
+    setVars.push({ name, value });
+    if (!vars.has(name)) vars.set(name, []);
+    vars.get(name).push(value);
+  }
+
+  const expand = (token) => String(token)
+    .replace(/%~?dp0%?/gi, `${dir}${path.sep}`)
+    .replace(/%([A-Za-z_][A-Za-z0-9_]*)%/g, (whole, name) => {
+      const list = vars.get(String(name).toLowerCase());
+      if (!list) return whole;
+      for (const v of list) {
+        const expanded = expandOnce(v, dir, vars);
+        if (expanded && fs.existsSync(expanded)) return expanded;
+      }
+      return expandOnce(list[list.length - 1], dir, vars);
+    });
+
+  // 执行行 = 最后一行带 %* 的（npm.cmd 里前面几行也可能出现 %*，最后那行才是真调用）
+  const execLines = text.split(/\r?\n/).filter((l) => l.includes('%*'));
+  if (!execLines.length) {
+    return { file: '', args: [], env: {}, via: 'shim-no-exec', problem: `${path.basename(shimFile)} 里找不到带 %* 的执行行` };
+  }
+  // npm.cmd 的执行行是 `endLocal & goto ... || title %COMSPEC% & "<prog>" "<script>" %*`
+  const pieces = execLines[execLines.length - 1].split('&');
+  const callPiece = pieces.find((p) => p.includes('%*')) || execLines[execLines.length - 1];
+  const tokens = tokenizeCmdLine(callPiece.replace(/%\*/g, ' '))
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (!tokens.length) {
+    return { file: '', args: [], env: {}, via: 'shim-empty', problem: `${path.basename(shimFile)} 的执行行里没有可执行命令` };
+  }
+
+  // `endLocal` / `title` 这类 cmd 内建可能在同一个 & 段里，先剥掉
+  const BUILTINS = new Set(['endlocal', 'setlocal', 'title', 'echo', 'call', 'goto', 'if', 'exit']);
+  while (tokens.length && BUILTINS.has(tokens[0].toLowerCase())) tokens.shift();
+  if (!tokens.length) {
+    return { file: '', args: [], env: {}, via: 'shim-builtin', problem: `${path.basename(shimFile)} 的执行行只有 cmd 内建命令` };
+  }
+
+  const headRaw = tokens.shift();
+  const head = tidyPathToken(expand(headRaw));
+  let file = head;
+  if (!path.isAbsolute(file)) {
+    // 壳里写的 `node` / `node.exe`：先用壳目录（npm 的 shim 会优先用自带的 node.exe），
+    // 再用 PATH，最后用跑本工具的这个 node。
+    const local = path.join(dir, file);
+    if (fs.existsSync(local)) file = local;
+    else file = findExecutableOnPath(file) || '';
+  }
+  if (!file || !fs.existsSync(file)) {
+    return { file: '', args: [], env: {}, via: 'shim-unresolved', problem: `${path.basename(shimFile)} 里的可执行解析不到（读到 ${JSON.stringify(headRaw)}）` };
+  }
+
+  const args = tokens.map((t) => tidyPathToken(expand(t)));
+  const env = {};
+  for (const { name, value } of setVars) {
+    // 只收"静态赋值"（不含 % 变量的），例如桌面版壳里的 ELECTRON_RUN_AS_NODE=1；
+    // 壳自己的局部变量（_prog / NODE_EXE …）必须滤掉，否则会污染子进程环境。
+    if (/%/.test(value)) continue;
+    if (name.startsWith('_') || SHIM_INTERNAL_VARS.has(name)) continue;
+    env[name.toUpperCase()] = value;
+  }
+  return { file, args, env, via: 'shim-parsed' };
+}
+
+function expandOnce(value, dir, vars) {
+  return String(value)
+    .replace(/%~?dp0%?/gi, `${dir}${path.sep}`)
+    .replace(/%([A-Za-z_][A-Za-z0-9_]*)%/g, (whole, name) => {
+      const list = vars.get(String(name).toLowerCase());
+      return list ? list[0] : whole;
+    });
+}
+
+/* ------------------------------------------------------------- 命令解析入口 */
+
+/**
+ * 把一个"命令名或路径"解析成可以直接 spawn 的 { file, argsPrefix, env, via }。
+ *
+ * - Windows：`.cmd/.bat` 走壳解析；`.exe` 直接用；裸名字先找 PATH。
+ * - 其它平台：原样直传（本来就不需要 shell）。
+ *
+ * @param {string} command
+ * @param {object} [opts] { platform, env, allowCmdFallback }
+ */
+export function resolveCommand(command, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const base = { file: command, argsPrefix: [], env: {}, via: 'direct', command, problem: '' };
+  if (platform !== 'win32') return base;
+
+  let file = String(command);
+  const looksLikePath = /[\\/]/.test(file);
+  if (!looksLikePath) {
+    const found = findExecutableOnPath(file, { platform, env });
+    if (!found) {
+      // 让 spawn 自己去报 ENOENT：这里不改写命令，但把话说清楚
+      return { ...base, via: 'not-found', problem: `PATH 上找不到 ${file}` };
+    }
+    file = found;
+  }
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.cmd' || ext === '.bat') {
+    const shim = parseWindowsShim(file);
+    if (shim.via === 'shim-parsed') {
+      return { file: shim.file, argsPrefix: shim.args, env: shim.env, via: 'shim', command, shim: file, problem: '' };
+    }
+    return {
+      file: opts.comspec || env.ComSpec || 'cmd.exe',
+      argsPrefix: ['/d', '/s', '/c', buildCmdLineWithEscapes(file, [])],
+      env: {},
+      via: 'cmd-fallback',
+      command,
+      shim: file,
+      problem: shim.problem || '',
+      cmdFallback: true,
+    };
+  }
+  return { ...base, file, via: 'direct-file' };
+}
+
+/**
+ * cmd 兜底用：把参数按 cmd 的规则转义后再拼成一行。
+ *
+ * 🔴 层数是实测出来的（2026-11-06，连测两轮）：
+ *   - `cmd /c <bat> x^y`    → bat 里 `%*` 收到 `xy`（第一层就吃了）
+ *   - `cmd /c <bat> x^^y`   → 还是 `xy`（第二层又吃了一次）
+ *   - `cmd /c <bat> x^^^^y` → `x^y` ✅
+ *   因为参数要过**两层**解析（`cmd /c` 那一行 + 批处理自己的 `%*` 展开），`^` 要写四个。
+ *   - **加了引号**时 cmd 不再把 `^` 当转义符 —— 这时一个都不该加（加了多少就原样多出多少）。
+ * 这个兜底只在 `.cmd` 壳解析不出来时才走；含 `&`/`|`/`"` 的参数一律不承诺（那类不该出现在
+ * 我们这条调用链里 —— 我们只传包名、版本区间、`-g`、`--profile`、profile 名）。
+ */
+export function escapeForCmd(arg) {
+  const s = String(arg);
+  if (/[\s()]/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s.replace(/\^/g, '^^^^');
+}
+
+export function buildCmdLineWithEscapes(file, args) {
+  return [file, ...args].map(escapeForCmd).join(' ');
+}
+
+/* ------------------------------------------------------------------ 杀进程 */
+
 function killTree(pid) {
   if (!pid) return;
   try {
@@ -89,7 +356,7 @@ const ABORT_SETTLE_MS = 3000;
  * @param {object} [options]
  * @param {number} [options.timeoutMs] 单步超时（到点按超时处理，走 killTree）
  * @param {AbortSignal} [options.signal] 外部取消。**不传 ⇒ 行为与加这个参数之前一模一样**
- * @returns {Promise<{code:number|null, stdout:string, stderr:string, timedOut:boolean, aborted:boolean, cmdline:string, error?:string}>}
+ * @returns {Promise<{code:number|null, stdout:string, stderr:string, timedOut:boolean, aborted:boolean, cmdline:string, error?:string, resolved?:object}>}
  */
 export function spawnCommand(file, args, options = {}) {
   const { timeoutMs = 120000, env = {}, cwd, onLine, quiet = false, signal } = options;
@@ -100,17 +367,34 @@ export function spawnCommand(file, args, options = {}) {
     return Promise.resolve({ code: null, stdout: '', stderr: '', timedOut: false, aborted: true, cmdline, error: 'aborted-before-start' });
   }
 
+  const mergedEnv = { ...process.env, ...env };
+  const resolved = resolveCommand(file, { env: mergedEnv });
+  // 兜底路径：.cmd 壳解析不出来才走 cmd.exe，此时必须自己把参数转义进那一行
+  const spawnFile = resolved.file;
+  const spawnArgs = resolved.cmdFallback
+    ? [...resolved.argsPrefix.slice(0, 3), buildCmdLineWithEscapes(resolved.shim || file, args)]
+    : [...resolved.argsPrefix, ...args];
+  const spawnEnv = { ...mergedEnv, ...resolved.env };
+  const diagnostics = {
+    command: resolved.command,
+    via: resolved.via,
+    file: spawnFile,
+    argsPrefix: resolved.argsPrefix,
+    shim: resolved.shim || null,
+    problem: resolved.problem || '',
+  };
+
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(cmdline, {
-        shell: true,
+      child = spawn(spawnFile, spawnArgs, {
+        shell: false,
         cwd,
         windowsHide: true,
-        env: { ...process.env, ...env },
+        env: spawnEnv,
       });
     } catch (err) {
-      resolve({ code: null, stdout: '', stderr: '', timedOut: false, aborted: false, cmdline, error: String(err && err.message ? err.message : err) });
+      resolve({ code: null, stdout: '', stderr: '', timedOut: false, aborted: false, cmdline, resolved: diagnostics, error: String(err && err.message ? err.message : err) });
       return;
     }
 
@@ -132,7 +416,7 @@ export function spawnCommand(file, args, options = {}) {
       if (timer) clearTimeout(timer);
       if (abortSettleTimer) clearTimeout(abortSettleTimer);
       if (signal) signal.removeEventListener('abort', onAbort);
-      resolve(payload);
+      resolve({ ...payload, resolved: diagnostics });
     };
 
     timer = setTimeout(() => {

package/lib/plan.mjs

@@ -26,6 +26,8 @@ import {
   readInstalledDshDecl,
 } from './state.mjs';
 import { formatCommandLine } from './exec.mjs';
+import { detectDesktop, desktopMissingHelp } from './desktop.mjs';
+import { createRegistryResolver } from './registry.mjs';
 import { EXIT } from './cli-args.mjs';
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -72,21 +74,23 @@ export function selectItems(manifest, { only = [], skip = [] } = {}) {
   return { items: selected.filter((i) => !dropped.has(i.name)), errors, groups };
 }
 
-export function installStepFor(item, { profile, npmPrefix }) {
+export function installStepFor(item, { profile, npmPrefix, dshCli }) {
   // 装的时候把**清单里的期望区间**一起点名（`<包>@^x.y.z`）。
   // 为什么必须带上：不带区间时拿到的是注册表 `latest` 标签指的那个版本，而它未必在
   // 我们期望的区间里（实测踩过：latest 标签指着的版本与最高版本号不是一回事）。
   // 带区间 = 让解析器只能落进期望区间，落不进去就报错，而不是"装了个别的版本还报成功"。
+  // ⚠️ 这个 `^` 必须原样到 npm/dsh 手里：lib/exec.mjs 已不再过 shell（cmd 会吃掉 `^`）。
   const spec = `${item.name}@${item.versionRange}`;
   if (item.type === 'plugin') {
-    return { file: 'dsh', args: ['plugin', '--profile', profile, 'add', spec], env: {} };
+    // 桌面版（Electron）的 profile 只能用它自带的 dsh.cmd 改；为 null 时才用 PATH 上的 dsh
+    return { file: dshCli || '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 }) {
+export function uninstallStepFor(item, { profile, npmPrefix, dshCli }) {
   if (item.type === 'plugin') {
-    return { file: 'dsh', args: ['plugin', '--profile', profile, 'remove', item.name], env: {} };
+    return { file: dshCli || 'dsh', args: ['plugin', '--profile', profile, 'remove', item.name], env: {} };
   }
   return { file: 'npm', args: ['rm', '-g', item.name], env: npmPrefix ? { npm_config_prefix: npmPrefix } : {} };
 }
@@ -147,7 +151,7 @@ export function criteriaText(item) {
   } else {
     parts.push(`跑 ${item.probe.cmd} ${(item.probe.argv || []).join(' ')}（清单声明只读：${item.probe.readonlyBecause}）`);
   }
-  parts.push(`实体版本落在 ${describeRange(parseRange(item.versionRange))}`);
+  parts.push(`实体版本落在 ${describeRange(parseRange(item.versionRange))} 内，且不落后于注册表上该区间内的最高合规版（取不到注册表时单列"未核"，不冒充通过）`);
   if (item.type === 'plugin' && (item.mount || 'auto') === 'auto') {
     parts.push('dump-config 里组合头恰好 1 行、条目 name 恰好 1 条、该 id 在整棵树里恰好 1 次');
   }
@@ -191,6 +195,70 @@ function buildOrder(groups, items) {
   return out;
 }
 
+/**
+ * 桌面版探测结果缓存（键 = 数据根 + 两个显式环境变量）。
+ * 为什么必须缓存：向导页的 GET /state 每个请求都会走 buildSuiteState，而探测要扫盘、
+ * 必要时还要起一个 PowerShell 反查进程 —— 不缓存的话打开页面就会卡住。
+ */
+const desktopDetectCache = new Map();
+
+/** 夹具用：换一套伪造环境之前把缓存清掉 */
+export function resetDesktopDetectCache() {
+  desktopDetectCache.clear();
+}
+
+async function desktopFor(home, options) {
+  const env = options.env || process.env;
+  const key = `${home}|${env.DSH_DESKTOP_DIR || ''}|${env.DSH_DESKTOP_CLI || ''}`;
+  if (desktopDetectCache.has(key)) return desktopDetectCache.get(key);
+  const detected = await detectDesktop({
+    home,
+    env,
+    run: options.desktopRun,
+    allowProcessProbe: options.allowProcessProbe,
+    // 夹具用：直接把候选安装目录钉死，免得本机真装了桌面版时测试跟着本机走
+    roots: options.desktopRoots,
+    platform: options.platform,
+  });
+  desktopDetectCache.set(key, detected);
+  return detected;
+}
+
+/**
+ * 这次到底对哪个 profile 动手。
+ *
+ * 三条判据（按顺序）：
+ *  ① 显式 `--profile desktop` 但本机找不到桌面版自带命令 ⇒ **硬拒绝**（rc=2）。
+ *     为什么不能"退回去用 CLI 版试试"：宿主会回 `profile "desktop" is managed exclusively
+ *     by the Electron application`，我们只会给用户一个看不懂的报错。
+ *  ② 用户没亲手点名 profile（--ui 的默认 web）、**数据根里有桌面版自建的 desktop profile**
+ *     且这里压根没有 web profile ⇒ 切 desktop。为什么要求"有 desktop profile"：本机同时
+ *     装着 CLI 版和桌面版是常态，光看"能不能找到桌面版安装目录"就切，会把 CLI 用户的活
+ *     搬进桌面版 profile —— 那才是真事故。
+ *  ③ 用户明确要 web 而机器上有桌面版 ⇒ 只提示、不阻断（同机双装是合法状态）。
+ */
+export function decideProfile({ options, home, desktop }) {
+  const requested = options.profile;
+  const notices = [];
+  if (requested === 'desktop') {
+    if (!desktop.cliCmd) {
+      return { profile: requested, changed: false, source: 'explicit', notices, error: desktopMissingHelp(home) };
+    }
+    return { profile: requested, changed: false, source: 'explicit', notices };
+  }
+  if (!options.profileExplicit) {
+    const webExists = readProfile(home, 'web').exists;
+    if (desktop.desktopProfileExists && desktop.cliCmd && !webExists) {
+      notices.push('这台机器的数据根里只有桌面版自建的 desktop profile（没有 web），已改成 --profile desktop —— 装进 web 的那套界面桌面版永远不加载');
+      return { profile: 'desktop', changed: true, source: 'auto-desktop', notices };
+    }
+  }
+  if (requested === 'web' && desktop.detected && desktop.cliCmd) {
+    notices.push('这台机器上有桌面版：如果你其实是在用它，--profile web 装上去不会加载（web 是 `dsh web` 那套的）；桌面版请用 --profile desktop');
+  }
+  return { profile: requested, changed: false, source: options.profileExplicit ? 'explicit' : 'default', notices };
+}
+
 /**
  * 唯一入口：产出「这次会做什么」的全部数据（文本演练与 /state 共用）。
  *
@@ -243,16 +311,50 @@ export async function buildSuiteState(options, pre = {}) {
 
   // ── 3. 上下文 ──────────────────────────────────────────────
   const home = resolveHome(options.home);
-  const profile = readProfile(home, options.profile);
+  // 桌面版（Electron）识别：它自建 profiles/desktop，而且只有它**自带**的命令改得动那个 profile。
+  // 探测结果按 home 缓存（向导页每个请求都会走到这里，不能每次都扫盘/起 PowerShell）。
+  const desktop = await desktopFor(home, options);
+  const decision = decideProfile({ options, home, desktop });
+  if (decision.error) {
+    for (const line of decision.error.split('\n')) say(line);
+    summary.exitCode = EXIT.USAGE;
+    return fail(EXIT.USAGE);
+  }
+  // 写回 options：--ui 的预览与真装是两个调用，profile 必须在同一个值上，
+  // 否则"预览说装 desktop、真装却写到 web"（这条写回是**有意的副作用**）。
+  options.profile = decision.profile;
+  const profileName = decision.profile;
+  const profile = readProfile(home, profileName);
   const npm = pre.npm || await resolveNpmPrefix(options.npmPrefix);
-  const ctx = { home, profile: options.profile, npmPrefix: npm.prefix };
+  const ctx = {
+    home,
+    profile: profileName,
+    npmPrefix: npm.prefix,
+    // 桌面版自带命令**只对 desktop 这个 profile 有效**：桌面版只管它自己那个 profile，
+    // web/profile 还是得用 PATH 上的 CLI 版。拿桌面命令去改别的 profile = 越权，必错。
+    dshCli: profileName === 'desktop' ? (desktop.cliCmd || null) : null,
+    // 注册表核对器（惰性：只有真正跑判据时才联网；演练档一条都不查）
+    registry: createRegistryResolver({
+      enabled: !options.noRegistry,
+      snapshot: options.registrySnapshot || null,
+      run: options.registryRun,
+      npmCommand: options.npmCommand || 'npm',
+    }),
+  };
   summary.home = home;
   summary.npmPrefix = npm.prefix;
+  summary.profileSource = decision.source;
 
   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(`profile：${profileName}（${profile.exists ? '已存在' : '尚不存在，真装时由宿主自动创建'}）${decision.changed ? ' —— 桌面版环境自动选的（原值 web 在桌面版上永远不加载）' : ''}`);
+  if (ctx.dshCli) {
+    // 只有"这次就要用桌面版自带命令"时才多打这一行：本机同时装着桌面版是常态，
+    // 动不动就提一句会污染 --ui 与 CLI 逐字节一致的那条金标（见 test-ui.mjs）。
+    say(`桌面版：认出是 Electron 版，用它的自带命令 ${desktop.cliCmd} 改 profile ${profileName}`);
+  }
+  for (const notice of decision.notices) say(`ℹ ${notice}`);
   say(`全局包落点：${npm.prefix}（来源：${npm.source}）`);
   if (manifest.excluded.length) {
     for (const entry of manifest.excluded) {
@@ -262,7 +364,7 @@ export async function buildSuiteState(options, pre = {}) {
   say('');
 
   // 前置：dsh 与 npm 两条原语都得在（只查文件存在，不执行）
-  const dshPath = findOnPath('dsh') || findExistingBin({ cmd: 'dsh', home, profile: options.profile, npmPrefix: npm.prefix });
+  const dshPath = ctx.dshCli || findOnPath('dsh') || findExistingBin({ cmd: 'dsh', home, profile: profileName, npmPrefix: npm.prefix });
   const npmPath = findOnPath('npm');
   const preflight = [];
   if (!dshPath) preflight.push('找不到 dsh 命令（PATH 与全局前缀两处都查过）⇒ 插件类无从安装，也无法核对挂载');
@@ -272,8 +374,8 @@ export async function buildSuiteState(options, pre = {}) {
   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 });
+    const installStep = installStepFor(entry.item, { profile: profileName, npmPrefix: npm.prefix, dshCli: ctx.dshCli });
+    const uninstallStep = uninstallStepFor(entry.item, { profile: profileName, npmPrefix: npm.prefix, dshCli: ctx.dshCli });
     entry.command = formatCommandLine(installStep.file, installStep.args);
     entry.commandUninstall = formatCommandLine(uninstallStep.file, uninstallStep.args);
     entry.criteria = criteriaText(entry.item);
@@ -332,8 +434,20 @@ export async function buildSuiteState(options, pre = {}) {
     suite: manifest.meta && manifest.meta.suite ? manifest.meta.suite : null,
     manifest: manifest.path,
     home,
-    profile: options.profile,
+    profile: profileName,
+    profileSource: decision.source,
     profileExists: profile.exists,
+    // 桌面版（Electron）：认出来了就用它自带的命令，绝不拿 npm 装的 CLI 去改它的 profile
+    desktop: {
+      detected: Boolean(desktop.detected),
+      cliCmd: desktop.cliCmd || null,
+      root: desktop.root || null,
+      source: desktop.source || '',
+      desktopProfileExists: Boolean(desktop.desktopProfileExists),
+      evidence: Array.isArray(desktop.evidence) ? desktop.evidence.slice() : [],
+    },
+    // 装后判据要对着注册表核"是不是最新合规版"；这一格说清有没有核（关掉时如实标 off）
+    registryCheck: options.noRegistry ? 'off' : 'on',
     npmPrefix: npm.prefix,
     npmPrefixSource: npm.source,
     upgrade: Boolean(options.upgrade),

package/lib/registry.mjs

@@ -0,0 +1,143 @@
+/**
+ * 「注册表上这个区间内现在最高是哪一版」—— 装后自检的第二半判据。
+ *
+ * 为什么非要有它：老判据只查「实体版本落在清单写的区间内」，而照清单装的时候
+ * 命令里带的正是区间下界（`<包>@^x.y.z`）；只要下界还在区间里，这条判据就**永远绿**。
+ * 实测过的后果（2026-11-06）：整批 17 项 rc=0 全绿，11 个包的实装版本正好等于下界，
+ * 其中 10 个落后 npm latest，还有一个装到了已 deprecate 的 0.1.0。
+ * ⇒ 判据必须对着**清单外面的世界**核一次，不能自己核自己。
+ *
+ * 取数只用一条只读命令：`npm view <name>@<range> version --json`。
+ * 它返回的是「这个区间内所有匹配的版本」，取其中最大的稳定版就是"当前可用的最新合规版"。
+ * 取不到（没网 / 私有源需要登录 / 包已下架）时**绝不冒充通过**：状态记 `unknown`，
+ * 由调用方在汇总里明说"这一项没核是否落后"，而不是悄悄给个绿。
+ *
+ * ⚠️ 它只读、幂等，而且**同一个进程里同一个包只查一次**（缓存）：
+ * 每步判据 + 收尾整批核对会重复问同一个包，缓存把 34 次压回 17 次。
+ */
+import { spawnCommand } from './exec.mjs';
+import { parseVersion, compareVersions, satisfies } from './semver.mjs';
+
+export const DEFAULT_REGISTRY_TIMEOUT_MS = 30000;
+
+/**
+ * 解析 `npm view <spec> version --json` 的输出。
+ * 三种形态都见过：单个字符串、字符串数组、空数组。
+ * @returns {{ok:boolean, versions:string[], problem?:string}}
+ */
+export function parseViewVersions(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return { ok: false, versions: [], problem: 'registry 没有返回任何版本' };
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    // `--json` 之外的老 npm 会一行一个版本；按行兜底
+    const lines = text.split(/\r?\n/).map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    const versions = lines.filter((l) => parseVersion(l));
+    if (!versions.length) return { ok: false, versions: [], problem: `输出解析不了：${JSON.stringify(text.slice(0, 120))}` };
+    return { ok: true, versions };
+  }
+  if (typeof data === 'string') return { ok: true, versions: [data.trim()] };
+  if (Array.isArray(data)) {
+    const versions = data.map((v) => String(v).trim()).filter((v) => parseVersion(v));
+    return { ok: true, versions };
+  }
+  return { ok: false, versions: [], problem: `输出不是版本列表：${JSON.stringify(text.slice(0, 120))}` };
+}
+
+/**
+ * 从一批版本里挑出「落在区间内且版本号最大」的那个（预发布不算候选）。
+ * @returns {{ok:boolean, best:string, rejected:number, problem?:string}}
+ */
+export function pickHighestInRange(rangeText, versions) {
+  let best = null;
+  let rejected = 0;
+  for (const raw of versions) {
+    const v = parseVersion(raw);
+    if (!v) { rejected += 1; continue; }
+    const verdict = satisfies(rangeText, raw);
+    if (verdict !== 'yes') { rejected += 1; continue; }
+    if (!best || compareVersions(v, parseVersion(best)) > 0) best = raw;
+  }
+  if (!best) return { ok: false, best: '', rejected, problem: `区间 ${rangeText} 在注册表上没有任何可用版本` };
+  return { ok: true, best, rejected };
+}
+
+/**
+ * 造一个解析器。**构造零成本**（不 spawn、不联网），第一次 lookup 才真查。
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.enabled=true]  false = 整条判据关闭（离线/演示），lookup 一律返回 skipped
+ * @param {number} [opts.timeoutMs]
+ * @param {Function} [opts.run]  注入的命令执行器（夹具用，签名同 spawnCommand）
+ * @param {string} [opts.npmCommand='npm']
+ * @param {Object<string,string>} [opts.snapshot]  {包名: 版本} 离线快照；给了就不再联网
+ * @param {string} [opts.source]  显示用的取数来源说明
+ */
+export function createRegistryResolver(opts = {}) {
+  const enabled = opts.enabled !== false;
+  const timeoutMs = opts.timeoutMs || DEFAULT_REGISTRY_TIMEOUT_MS;
+  const run = opts.run || ((file, args, o) => spawnCommand(file, args, o));
+  const npmCommand = opts.npmCommand || 'npm';
+  const snapshot = opts.snapshot || null;
+  const cache = opts.cache || new Map();
+  let queried = 0;
+
+  async function query(name, rangeText) {
+    if (snapshot) {
+      const got = snapshot[name];
+      if (!got) return { ok: false, versions: [], problem: `离线取数里没有 ${name}` };
+      return { ok: true, versions: [String(got)], offline: true };
+    }
+    queried += 1;
+    const spec = `${name}@${rangeText}`;
+    const res = await run(npmCommand, ['view', spec, 'version', '--json'], { timeoutMs, quiet: true });
+    if (res.timedOut) return { ok: false, versions: [], problem: `npm view ${spec} 超时（${Math.round(timeoutMs / 1000)}s）` };
+    if (res.code !== 0) {
+      const first = String(res.stderr || '').trim().split(/\r?\n/).find((l) => l && !/^npm (warn|notice)/i.test(l)) || '';
+      return { ok: false, versions: [], problem: `npm view ${spec} 退出码 ${res.code}${first ? `：${first.slice(0, 160)}` : ''}` };
+    }
+    const parsed = parseViewVersions(res.stdout);
+    if (!parsed.ok) return { ok: false, versions: [], problem: parsed.problem };
+    return { ok: true, versions: parsed.versions };
+  }
+
+  /**
+   * @param {{name:string, versionRange:string}} item
+   * @returns {Promise<{status:'ok'|'skipped'|'unknown', best:string, source:string, detail:string}>}
+   */
+  async function lookup(item) {
+    if (!enabled) {
+      return { status: 'skipped', best: '', source: 'off', detail: '注册表核对被关闭（--no-registry）：只核"落在区间内"，没核是否落后' };
+    }
+    const key = `${item.name}@${item.versionRange}`;
+    if (cache.has(key)) return cache.get(key);
+    const got = await query(item.name, item.versionRange);
+    let result;
+    if (!got.ok) {
+      result = { status: 'unknown', best: '', source: snapshot ? 'snapshot' : 'npm-view', detail: `取不到注册表版本（${got.problem}）⇒ 没核是否落后` };
+    } else {
+      const picked = pickHighestInRange(item.versionRange, got.versions);
+      result = picked.ok
+        ? { status: 'ok', best: picked.best, source: snapshot ? 'snapshot' : 'npm-view', detail: `区间 ${item.versionRange} 内注册表现有最高 ${picked.best}` }
+        : { status: 'unknown', best: '', source: snapshot ? 'snapshot' : 'npm-view', detail: `${picked.problem} ⇒ 没核是否落后` };
+    }
+    cache.set(key, result);
+    return result;
+  }
+
+  return {
+    lookup,
+    stats: () => ({ queried, cached: cache.size, enabled, source: snapshot ? 'snapshot' : enabled ? 'npm-view' : 'off' }),
+    clear: () => cache.clear(),
+  };
+}
+
+/** 把 resolver 塞进一个可复用的 ctx（已存在就不换，保证一次运行内缓存不丢） */
+export function ensureRegistry(ctx, opts) {
+  if (ctx.registry) return ctx.registry;
+  const resolver = createRegistryResolver(opts);
+  ctx.registry = resolver;
+  return resolver;
+}

package/lib/run.mjs

@@ -10,7 +10,7 @@
  */
 import path from 'node:path';
 import { describeItem } from './manifest.mjs';
-import { satisfies } from './semver.mjs';
+import { satisfies, parseVersion, compareVersions } from './semver.mjs';
 import {
   readProfile,
   profileInstalledVersion,
@@ -95,13 +95,15 @@ function invalidateDump() {
 
 async function getDumpAnalysis(ctx) {
   if (dumpCache) return dumpCache;
-  const res = await spawnCommand('dsh', ['--profile', ctx.profile, '--dump-config'], {
-    timeoutMs: 10000,
+  // 桌面版（Electron）的 profile 只有它自带的命令读得出来；PATH 上那个 CLI 版会直接拒绝
+  const dshCommand = ctx.dshCli || 'dsh';
+  const res = await spawnCommand(dshCommand, ['--profile', ctx.profile, '--dump-config'], {
+    timeoutMs: 15000,
     env: execEnv(ctx),
     quiet: true,
   });
   if (res.timedOut) {
-    dumpCache = { ok: false, reason: '--dump-config 超时（10s）⇒ 挂载判据记"未知"，不当通过、也不报红' };
+    dumpCache = { ok: false, reason: '--dump-config 超时（15s）⇒ 挂载判据记"未知"，不当通过、也不报红' };
     return dumpCache;
   }
   if (res.code !== 0) {
@@ -119,14 +121,38 @@ async function getDumpAnalysis(ctx) {
   return dumpCache;
 }
 
-function rangeStatus(range, version) {
+function rangeStatus(item, version, registry) {
   if (!version) return { status: 'fail', detail: '未安装' };
-  if (range === 'yes') return { status: 'pass', detail: `实体 ${version}，落在期望区间内` };
-  if (range === 'unknown') return { status: 'skip', detail: `实体 ${version}，带预发布后缀 ⇒ 不判合不合规（三态里的"无法比较"）` };
-  return { status: 'fail', detail: `实体 ${version}，不在期望区间内` };
+  const range = satisfies(item.versionRange, version);
+  if (range === 'unknown') return { status: 'skip', detail: `实体 ${version}，带预发布后缀 ⇒ 不判合不合规（三态里的"无法比较"）`, registryStatus: 'n/a' };
+  if (range === 'no') return { status: 'fail', detail: `实体 ${version}，不在期望区间内（期望 ${item.versionRange}）`, registryStatus: 'n/a' };
+  // 落在区间内只是**一半**。另一半是「是不是这个区间里现在能拿到的最新」——
+  // 老判据只查前半，于是"装成了区间下界"也会绿（2026-11-06 实测整批 17 项全绿却全是旧版）。
+  if (!registry) {
+    return { status: 'pass', detail: `实体 ${version}，落在期望区间内（没有注册表核对器：没核是否落后）`, registryStatus: 'unknown' };
+  }
+  if (registry.status !== 'ok') {
+    // 取不到注册表绝不当成"不落后"：状态记 unknown，汇总里会单列一行说清有 N 项没核过
+    return { status: 'pass', detail: `实体 ${version}，落在期望区间内；${registry.detail}`, registryStatus: 'unknown' };
+  }
+  const cmp = compareVersions(parseVersion(version), parseVersion(registry.best));
+  if (cmp >= 0) {
+    return {
+      status: 'pass',
+      detail: `实体 ${version}，落在期望区间内，且是区间 ${item.versionRange} 内注册表现有最高（${registry.best}）`,
+      registryStatus: 'ok',
+      best: registry.best,
+    };
+  }
+  return {
+    status: 'fail',
+    detail: `实体 ${version} 落后：区间 ${item.versionRange} 内注册表现有最高 ${registry.best}（"等于下界"就是这个症状；装上来的不是最新合规版）`,
+    registryStatus: 'ok',
+    best: registry.best,
+  };
 }
 
-/** 一步跑完之后的判据：探针 + 版本区间 + 挂载（插件且声明自动挂载时） */
+/** 一步跑完之后的判据：探针 + 版本区间（含"是不是最新合规版"）+ 挂载（插件且声明自动挂载时） */
 export async function verifyItem(item, ctx) {
   const mount = item.mount || (item.type === 'plugin' ? 'auto' : 'none');
   const checks = [];
@@ -137,13 +163,43 @@ export async function verifyItem(item, ctx) {
   const version = item.type === 'plugin'
     ? profileInstalledVersion(ctx.home, ctx.profile, item.name)
     : globalInstalledVersion(ctx.npmPrefix, item.name);
-  checks.push({ label: '版本区间', ...rangeStatus(version ? satisfies(item.versionRange, version) : 'no', version) });
+  // 只在"装上了且区间能比"的时候才值得问注册表（省掉没装/预发布那些无意义的网络查询）
+  let registry = null;
+  if (version && satisfies(item.versionRange, version) === 'yes' && ctx.registry) {
+    registry = await ctx.registry.lookup(item);
+  }
+  checks.push({ label: '版本区间', ...rangeStatus(item, version, registry) });
 
   if (item.type === 'plugin') {
     if (mount === 'manual') {
       checks.push({ label: '挂载', status: 'skip', detail: '本包按设计不进 profile 的组合列表（清单 mount=manual）：挂载由它自带的部署命令完成，不由本工具判' });
     } else if (mount === 'none') {
       checks.push({ label: '挂载', status: 'skip', detail: '清单 mount=none，不参与组合列表' });
+    } else if (ctx.dshCli) {
+      // 桌面版（Electron）：它**不提供** --dump-config（实测两条命令都回
+      // `error: profile "desktop" is managed exclusively by the Electron application`）。
+      // 老实现到这里就记"未知"，等于桌面版用户永远看不到挂载判据 —— 又是一处看不见。
+      // 改用文件层等价判据：Electron 宿主启动时按 profile 的 dsh.profile.bundles 装配，
+      // 登记即生效；包自己又声明了 dsh.bundle（上面已确认）⇒ 这两个条件就够。
+      const decl = readInstalledDshDecl(ctx.home, ctx.profile, item.name);
+      const bundleRegistered = readProfile(ctx.home, ctx.profile).bundles.includes(item.name);
+      if (!decl.hasBundle) {
+        checks.push({
+          label: '挂载',
+          status: 'skip',
+          detail: bundleRegistered
+            ? '桌面版不提供 --dump-config；改读 profile 的组合列表：登记了它，但这一版包实体没有 dsh.bundle 声明 ⇒ 登记是空的'
+            : '桌面版不提供 --dump-config；改读 profile 的组合列表：这一版包实体不带 dsh.bundle（装成普通依赖是正确状态）',
+        });
+      } else {
+        checks.push({
+          label: '挂载',
+          status: bundleRegistered ? 'pass' : 'fail',
+          detail: bundleRegistered
+            ? '桌面版不提供 --dump-config，改读 profile 的 dsh.profile.bundles：已登记（Electron 宿主按它装配，登记即生效）'
+            : '桌面版不提供 --dump-config，改读 profile 的 dsh.profile.bundles：**没登记** ⇒ 装了也不会被加载',
+        });
+      }
     } else {
       const dump = await getDumpAnalysis(ctx);
       const decl = readInstalledDshDecl(ctx.home, ctx.profile, item.name);
@@ -298,7 +354,7 @@ export async function runSuite(options, hooks = {}) {
   if (options.uninstall) {
     let failed = 0;
     for (const [index, entry] of plan.entries()) {
-      const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
+      const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix, dshCli: ctx.dshCli });
       say(`\n[${entry.item.group}] ${entry.item.name}`);
       say(`  $ ${formatCommandLine(step.file, step.args)}`);
       emit({ kind: 'step-start', index: index + 1, total: plan.length, item: entry.item.name, action: 'uninstall' });
@@ -365,7 +421,7 @@ export async function runSuite(options, hooks = {}) {
       emit({ kind: 'step-done', index: i + 1, total: plan.length, item: entry.item.name, ok: false, detail: '没开始：整批墙钟超时' });
       break;
     }
-    const step = installStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
+    const step = installStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix, dshCli: ctx.dshCli });
     say(`\n[${i + 1}/${plan.length}] ${entry.item.group} · ${entry.item.name}`);
     say(`  $ ${formatCommandLine(step.file, step.args)}`);
     const res = await spawnCommand(step.file, step.args, {
@@ -448,11 +504,24 @@ export async function runSuite(options, hooks = {}) {
       };
     } else {
       say(`  ✅ ${plan.length} 项全部通过`);
+      // "全绿"里必须说清有多少项其实没核过"是不是最新合规版"—— 否则又是另一种假绿
+      const unverified = sweep.filter((s) => {
+        const c = s.checks.find((x) => x.label === '版本区间');
+        return c && c.registryStatus === 'unknown';
+      });
+      if (unverified.length) {
+        say(`  ⚠ ${unverified.length}/${plan.length} 项没核"是不是最新合规版"（注册表取不到，或用了 --no-registry）：${unverified.map((u) => u.name).join('、')}`);
+      } else {
+        say(`  ✅ ${plan.length}/${plan.length} 项都对着注册表核过：装上来的是该区间内现有最高合规版`);
+      }
     }
   }
 
   summary.sweep = sweep;
   summary.installedThisRun = installedThisRun.map((e) => e.item.name);
+  summary.registry = ctx.registry ? ctx.registry.stats() : { enabled: false, source: 'off' };
+  summary.profile = options.profile;
+  summary.profileSource = summary.profileSource || null;
 
   if (!failure) {
     summary.exitCode = EXIT.OK;
@@ -490,7 +559,7 @@ export async function runSuite(options, hooks = {}) {
       actions.push({ name: entry.item.name, command: '(skipped)', rc: 0, timedOut: false, skipped: true });
       continue;
     }
-    const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
+    const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix, dshCli: ctx.dshCli });
     say(`  $ ${formatCommandLine(step.file, step.args)}`);
     // 回滚里的卸载同样要能被取消打断：用户点了【取消】之后不该继续干 2 分钟的活
     const res = await spawnCommand(step.file, step.args, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kira905/dsh-butler-install",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Thin installer for the DSH butler suite: one command installs the plugin + CLI bundle through the host's own commands, then tells you whether it actually took effect, and can roll the whole batch back. Also ships a local wizard page (--ui) that lives outside DSH and can install from the browser: nothing runs until you press confirm; loopback only, per-process token + same-origin check, four POST entry points (preview/start/cancel/rollback), two honest rollbacks. It does not isolate you from other programs running as the same local user.",
   "type": "module",
   "license": "MIT",

package/suite-manifest.json

@@ -35,7 +35,7 @@
     },
     {
       "name": "@kira905/dsh-host-adapter-client",
-      "versionRange": "^0.1.1",
+      "versionRange": "^0.1.2",
       "type": "plugin",
       "group": "界面",
       "mount": "manual",
@@ -65,7 +65,7 @@
     },
     {
       "name": "@kira905/dsh-board-toolkit",
-      "versionRange": "^0.1.2",
+      "versionRange": "^0.1.3",
       "type": "cli",
       "group": "CLI",
       "aliases": ["看板"],
@@ -83,7 +83,7 @@
     },
     {
       "name": "@kira905/dsh-session-toolkit",
-      "versionRange": "^0.1.1",
+      "versionRange": "^0.1.2",
       "type": "cli",
       "group": "CLI",
       "aliases": ["会话"],
@@ -92,7 +92,7 @@
     },
     {
       "name": "@kira905/dsh-net-toolkit",
-      "versionRange": "^0.1.0",
+      "versionRange": "^0.1.1",
       "type": "cli",
       "group": "CLI",
       "aliases": ["网络"],
@@ -101,7 +101,7 @@
     },
     {
       "name": "@kira905/dsh-notekit",
-      "versionRange": "^0.1.0",
+      "versionRange": "^0.1.1",
       "type": "cli",
       "group": "CLI",
       "aliases": ["笔记"],
@@ -110,7 +110,7 @@
     },
     {
       "name": "@kira905/dsh-nurse",
-      "versionRange": "^0.1.0",
+      "versionRange": "^0.1.1",
       "type": "cli",
       "group": "体检",
       "aliases": ["小护士", "体检"],
@@ -119,7 +119,7 @@
     },
     {
       "name": "@kira905/dsh-firstaid",
-      "versionRange": "^0.1.3",
+      "versionRange": "^0.1.4",
       "type": "cli",
       "group": "体检",
       "aliases": ["急救"],
@@ -128,7 +128,7 @@
     },
     {
       "name": "@kira905/dsh-ops-toolkit",
-      "versionRange": "^0.1.0",
+      "versionRange": "^0.1.2",
       "type": "cli",
       "group": "体检",
       "aliases": ["运维"],
@@ -146,7 +146,7 @@
     },
     {
       "name": "@kira905/dsh-closure-tools",
-      "versionRange": "^0.1.1",
+      "versionRange": "^0.1.2",
       "type": "cli",
       "group": "体检",
       "aliases": ["闭包"],
@@ -155,7 +155,7 @@
     },
     {
       "name": "@kira905/dsh-diagnostics-extra",
-      "versionRange": "^0.1.0",
+      "versionRange": "^0.1.2",
       "type": "cli",
       "group": "体检",
       "aliases": ["对账", "诊断"],