dsh-mobile-plugin 0.1.60 → 0.1.61

package/lib/routes/control-plane.js

@@ -27,6 +27,10 @@ const readReceipt = require('../read-receipt.cjs');
 // 客户端半边的活体台账：两条绿点同步通道都是「单向轮询 + 无回执」，不记账就永远分不开
 // 「那半边根本没在跑」和「跑了但没清掉」（详见 lib/desktop-half-stats.cjs 的文件头）。
 const desktopHalf = require('../desktop-half-stats.cjs');
+// 「查有没有新版」与「装新版」这两格都归插件自己：查直接问 npm 注册表，装在 profile 里跑
+// 它自己的包管理器（见 `../update-registry.cjs` / `../update-install.cjs`）。不再借道市场。
+const { checkForUpdate } = require('../update-registry.cjs');
+const { installLatest, declaredSource } = require('../update-install.cjs');
 const { clearCompletionForAllDevices, invalidateSessionList } = require('../mobile/session-cache.js');
 
 /** 一次 desktop-read 上报最多带多少个会话 id（防灌爆；客户端半边一次最多也就几个）。 */
@@ -47,6 +51,22 @@ const PANEL_FILE = path.join(__dirname, '..', 'panel', 'index.html');
 /** 插件包根（`<pkg>/lib/routes` 往上两级）：诊断时读它的 `package.json` 与 `React/`。 */
 const PACKAGE_DIR = path.join(__dirname, '..', '..');
 
+/**
+ * 这一代（`lib/` 所在的那份包）自己的版本号。
+ *
+ * 「检查更新」在**没有外壳**的宿主上（无头部署、或那一版没装外壳）也要能答，而盘上版本
+ * 是外壳的 `manager.js` 才知道的事；拿不到就退回这一代的版本号 —— 它至少是「这台机器上
+ * 正在跑的实现」的真实版本，比空着或回一句「问不了」有用。
+ */
+function generationVersion() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, 'package.json'), 'utf8'));
+    return typeof raw.version === 'string' && raw.version ? raw.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /** 按 mtime 缓存：文件被换掉之后内容变了，缓存自然失效，不必手工清。 */
 let panelCache = { file: '', mtime: -1, html: '' };
 
@@ -362,12 +382,12 @@ function registerControlPlaneRoutes(deps) {
   }) })
   // ── 插件更新（2026-10 搬回自更新之后重新有这四条）──
   //
-  // 分工：**下载交给市场**（它在 profile 里跑 pnpm，还负责版本核验、release-age 策略、
-  // 回滚点、重启守卫），**换代码留给外壳**（`lib/index.js` 的 runtime）。所以这里只是把
-  // 外壳那几个动作原样开成本机 HTTP —— 面板与脚本都打这几条，不再各自去拼市场的接口，
-  // 免得「宿主能装、面板说看不见」这种两边写法不一致的偏差。
+  // 分工（2026-10-11 起）：**查归插件自己**（问 npm 注册表，`../update-registry.cjs`）、
+  // **装也归插件自己**（在 profile 里跑它自己的包管理器，`../update-install.cjs`），
+  // **换代码留给外壳**（`lib/index.js` 的 runtime）。市场不再是这条路上的任何一环。
   //
-  // 四条都走 localOnly：它们能触发一次安装并把运行中的实现换掉，是本机运维动作。
+  // 四条都走 localOnly：`check` 读的是版本情况，另外三条会改盘上的插件（`apply` 直接动
+  // profile 的依赖树），全是本机运维动作，不该有局域网 / 中转来的调用者。
   const pluginRuntime = () => {
     try {
       return getPluginRuntime() || null
@@ -375,23 +395,44 @@ function registerControlPlaneRoutes(deps) {
       return null
     }
   }
-  const runtimeUnavailable = { ok: false, error: { code: 'update_unavailable', message: '这一版没有可换代的外壳（插件是被直接挂载的），更新请走 DSH 的插件市场' } }
+  const runtimeUnavailable = { ok: false, error: { code: 'update_unavailable', message: '这一版没有可换代的外壳（插件是被直接挂载的），装完没法就地生效，所以这里不装：无头部署请 rsync 源码后重启' } }
   registerRoute({ kind: 'exact', path: '/api/relay/update/status', handler: localOnly('GET', async (_req, res) => {
     const runtime = pluginRuntime()
     if (!runtime) return sendJson(res, 200, { ok: true, data: { available: false, runningVersion: null, installedVersion: null } })
     return sendJson(res, 200, { ok: true, data: { available: true, ...runtime.status() } })
   }) })
+  // 「检查更新」：插件自己问 npm 注册表，**不经过市场、也没有经过外壳**。
+  //
+  // 刻意不要求外壳在场（所以这一条**不是** `runtimeUnavailable`）：查不需要换代能力，
+  // 装才需要。从前这条转调 `runtime.check()` → 外壳 → 市场，于是市场没装、太老或者坏了，
+  // 「有没有新版」就整个答不出来 —— 一个插件得另一个插件在场才能告诉你自己的版本情况。
+  // 盘上版本仍然优先取外壳那份（市场装完立刻变，和运行中版本对照才看得出「要不要换」），
+  // 拿不到（无头部署 / 没有外壳的那一版）就退回这一代自己的版本号。
   registerRoute({ kind: 'exact', path: '/api/relay/update/check', handler: localOnly('POST', async (_req, res) => {
     const runtime = pluginRuntime()
-    if (!runtime) return sendJson(res, 409, runtimeUnavailable)
+    const snapshot = runtime ? runtime.status() : null
     try {
-      const result = await runtime.check({ force: true })
-      return sendJson(res, 200, { ok: true, data: { update: result, status: runtime.status() } })
+      const update = await checkForUpdate({
+        installedVersion: snapshot?.installedVersion ?? snapshot?.version ?? generationVersion(),
+        // 「安装来源」也自己看：profile 的依赖声明里写的是什么（npm / file: / link:）。读不到
+        // 才退回外壳上次问市场的记忆 —— 这条路上不为它去敲市场。
+        source: declaredSource(snapshot?.profileNodeModules ? path.dirname(snapshot.profileNodeModules) : null) ?? snapshot?.marketResult?.source ?? null,
+      })
+      return sendJson(res, 200, { ok: true, data: { update, status: snapshot } })
     } catch (error) {
-      return sendJson(res, 500, { ok: false, error: { code: 'update_check_failed', message: String(error?.message || error) } })
+      return sendJson(res, 500, {
+        ok: false,
+        error: { code: 'update_check_failed', message: String(error?.message || error) },
+        data: { update: null, status: snapshot },
+      })
     }
   }) })
-  // 「更新并立即生效」：请市场装，装完就地换代。手动与自动走的是同一条路。
+  // 「更新并立即生效」：插件**自己**去 profile 里装新版（`../update-install.cjs`），装完请外壳
+  // 就地换代。不再问市场 —— 装这一半也是插件自己的事了（查在同一条路上的 `check`）。
+  //
+  // 只在有外壳时才装：盘上换了版本、运行中的实现换不掉，等于「装了个用不上的东西」，不如
+  // 直说办不了。装失败一律回 200 + 如实的结果（面板照着 `failure` 说人话），只有我们这边
+  // 出了意料之外的错才回 500。
   registerRoute({ kind: 'exact', path: '/api/relay/update/apply', handler: localOnly('POST', async (req, res) => {
     const runtime = pluginRuntime()
     if (!runtime) return sendJson(res, 409, runtimeUnavailable)
@@ -401,14 +442,70 @@ function registerControlPlaneRoutes(deps) {
     } catch {
       body = {}
     }
+    const force = body.force === true
+    const snapshot = runtime.status()
+    const beforeVersion = snapshot.installedVersion ?? snapshot.version ?? generationVersion()
+    const outcome = {
+      installed: false,
+      skipped: false,
+      state: 'failed',
+      beforeVersion,
+      installedVersion: beforeVersion,
+      swapped: false,
+      // 更新后绝不重启 DSH（外壳就地换代），这两格只为如实上报。
+      restartRequired: false,
+      refreshRequired: false,
+      failure: null,
+    }
+    const answer = (extra = {}) => Object.assign(outcome, extra)
+
+    const profileNodeModules = snapshot.profileNodeModules ?? null
+    if (!profileNodeModules) {
+      answer({ failure: { code: 'profile-unknown', message: '宿主没给出 profile 的 node_modules 路径，装不了' } })
+      return sendJson(res, 500, { ok: false, error: { code: 'update_apply_failed', message: outcome.failure.message }, data: { ...outcome, status: snapshot } })
+    }
+
+    let target = null
+    try {
+      const check = await checkForUpdate({
+        installedVersion: beforeVersion,
+        source: snapshot.marketResult?.source ?? null,
+      })
+      target = check.latestVersion
+      if (!check.updateAvailable && !force) {
+        answer({ skipped: true, state: 'succeeded', installedVersion: check.installedVersion ?? beforeVersion })
+        return sendJson(res, 200, { ok: true, data: { ...outcome, status: runtime.status() } })
+      }
+    } catch (error) {
+      answer({ failure: { code: 'update_check_failed', message: String(error?.message || error) } })
+      return sendJson(res, 500, { ok: false, error: { code: 'update_apply_failed', message: outcome.failure.message }, data: { ...outcome, status: snapshot } })
+    }
+
+    let result
+    try {
+      result = await installLatest({ profileNodeModules, version: target, force })
+    } catch (error) {
+      result = { installed: false, installedVersion: beforeVersion, command: null, output: '', failure: { code: 'install_failed', message: String(error?.message || error) } }
+    }
+    outcome.installedVersion = result.installedVersion ?? beforeVersion
+    outcome.failure = result.failure ?? null
+    outcome.command = result.command ?? null
+    outcome.output = result.output ?? ''
+    if (!result.installed) {
+      return sendJson(res, 200, { ok: false, data: { ...outcome, status: runtime.status() } })
+    }
+
+    // 装上了才换代：换代码是外壳的事，失败要如实报（回滚由外壳负责，见 shell/runtime.js）。
     try {
-      const outcome = await runtime.apply({ force: body.force === true })
-      return sendJson(res, 200, { ok: outcome.installed !== false || outcome.skipped === true, data: outcome })
+      const status = await runtime.reload()
+      answer({ installed: true, state: 'succeeded', swapped: true, installedVersion: status?.version ?? outcome.installedVersion, refreshRequired: status?.shellChanged === true })
     } catch (error) {
-      return sendJson(res, 500, { ok: false, error: { code: 'update_apply_failed', message: String(error?.message || error) }, data: { status: runtime.status() } })
+      answer({ installed: true, state: 'installed-not-swapped', failure: { code: 'swap_failed', message: `新版已经装到盘上，但换代码没成：${String(error?.message || error)}` } })
     }
+    return sendJson(res, 200, { ok: true, data: { ...outcome, status: runtime.status() } })
   }) })
-  // 自动更新开关（默认关）。开=每 10 分钟问一次市场，有新版就装并就地切换。
+  // 自动更新开关（默认关）。开=外壳每 10 分钟问一次有没有新版，有就自己装并就地切换
+  // （轮询住在外壳里，因为「没人看着也要发生」；装与换代用的就是上面这两条同一套实现）。
   registerRoute({ kind: 'exact', path: '/api/relay/update/auto', handler: localOnly('POST', async (req, res) => {
     const runtime = pluginRuntime()
     if (!runtime) return sendJson(res, 409, runtimeUnavailable)

package/lib/shell/updater.js

@@ -1,21 +1,26 @@
 /**
- * 更新编排：替用户去问 DSH 插件市场要新版，装完**就地换代**（不重启 DSH）。
+ * 更新编排：**查与装都归实现自己**，装完**就地换代**（不重启 DSH）。
  *
  * ## 为什么这件事归外壳做，而不是归面板（浏览器）
  *
  * 面板里那颗「更新」按钮只能覆盖「用户正开着页面点一下」这一种情形；自动更新的定义是
  * **没人看着也要发生**。所以轮询和「装完切换」都必须在宿主进程里做，面板只是给它一个开关。
  *
- * ## 为什么下载交给市场、切换留给自己
+ * ## 装法住哪儿（2026-10-11 改）
  *
- * 市场在 profile 里跑 pnpm，还会做版本核验、release-age 策略、回滚点、重启守卫 —— 抄一遍
- * 只会抄漏。它装完会报 `restartRequired: true`（因为绝大多数插件换版本确实得重启 DSH），
- * 而本插件有外壳，可以自己把运行中的实现换掉，所以这里**故意不调它的重启**。
+ * 从前「查」和「装」都是请 DSH 插件市场代劳的（打它的 HTTP 接口）。现在两件都归实现自己：
+ * 查问 npm 注册表、装在 profile 里跑它自己的包管理器（`lib/update-registry.cjs` /
+ * `lib/update-install.cjs`）。外壳**只从盘上那一代**把自装模块取进来跑（`installedInstaller`），
+ * 所以换装法、换判定都不用等重启 —— 盘上换了，下一次自动更新就走新的。
  *
- * 装完新一代是**新目录**（pnpm 换链接），外壳照着新 realpath 重新 import 一代即可，见
+ * 下面那套市场实现是**兜底**，只在「盘上那一代还没有自装模块」时才走到（老一代、刚回滚到
+ * 旧代）。自动更新宁可暂时还走老路，也不能直接坏掉；市场装完会报 `restartRequired: true`，
+ * 而本插件有外壳可以自己换代，所以那条路里**故意不调它的重启**。
+ *
+ * 装完新一代是**新目录**（包管理器换链接），外壳照着新 realpath 重新 import 一代即可，见
  * `lib/shell/manager.js` 与 `lib/shell/runtime.js`。
  *
- * ## 这个模块不做的事
+ * ## 兜底那条路不做的事
  *
  * 不下载、不解包、不校验、不写 profile —— 全是市场的职责。它只回答四个问题：有没有新版、
  * 请它装、装完了没、盘上现在是什么版本。
@@ -25,12 +30,46 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { createRequire } from 'node:module'
-import { installedVersion } from './manager.js'
+import { pathToFileURL } from 'node:url'
+import { installedPackageDir, installedVersion, profileNodeModules } from './manager.js'
 
 const require_ = createRequire(import.meta.url)
 const { dshHome } = require_('../shared/paths.js')
 
 
+/**
+ * 盘上那一代的「自己装」模块（`lib/update-install.cjs`）。
+ *
+ * 「装」这件事 2026-10-11 起归**实现**自己：在 profile 里跑它自己的包管理器，不再借道 DSH
+ * 插件市场。外壳只负责把盘上那一代的模块取进来跑 —— 从**盘上**（不是外壳自己的目录）取，
+ * 是为了「装法改了不用等重启」：市场以外的方式换掉那一代之后，下一次自动更新就走新装法。
+ *
+ * 取不到（老一代没这个文件、安装目录被判了不存在、模块加载失败）就返回 null，调用方退回
+ * 下面那套市场实现 —— 自动更新宁可暂时还走老路，也不能直接坏掉。
+ */
+async function installedInstaller() {
+  const dir = installedPackageDirSafe()
+  if (!dir) return null
+  const file = path.join(dir, 'lib', 'update-install.cjs')
+  if (!fs.existsSync(file)) return null
+  try {
+    const mod = await import(`${pathToFileURL(file).href}?v=${Date.now()}`)
+    const fn = mod.installLatestIfNeeded ?? mod.default?.installLatestIfNeeded
+    return typeof fn === 'function' ? fn : null
+  } catch {
+    return null
+  }
+}
+
+/** `installedPackageDir()` 只是读个路径，读不到不该把自动更新整个抛掉。 */
+function installedPackageDirSafe() {
+  try {
+    return installedPackageDir()
+  } catch {
+    return null
+  }
+}
+
 /**
  * 外壳自己的指纹（`lib/index.js` + `lib/shell/*.js` 的内容哈希）。
  *
@@ -190,6 +229,27 @@ const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'rolled-back'])
  */
 export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false, onEvent = () => {}, now = Date.now } = {}) {
   const before = installedVersion()
+  // 装归实现自己（2026-10-11 起）：盘上那一代里有 `update-install.cjs` 就走它。判定（查一次
+  // 有没有新版、`link:` 来源不碰）也一并交给它，别在这里抄第二份 —— 外壳与面板的按钮必须
+  // 是同一套判定，否则会出现「手动说有新版、自动说没有」。
+  const selfInstall = await installedInstaller()
+  if (selfInstall) {
+    const outcome = await selfInstall({ profileNodeModules: profileNodeModules(), force, onEvent })
+    return {
+      installed: outcome.installed === true,
+      skipped: outcome.skipped === true,
+      state: outcome.installed || outcome.skipped ? 'succeeded' : 'failed',
+      beforeVersion: outcome.beforeVersion ?? before,
+      installedVersion: outcome.installedVersion ?? before,
+      // 外壳就地换代，市场那套「装完要重启」在本项目一律不照做。只为如实上报。
+      restartRequired: false,
+      refreshRequired: false,
+      failure: outcome.failure ?? null,
+      retryable: false,
+      command: outcome.command ?? null,
+      check: outcome.check ?? null,
+    }
+  }
   const check = await checkUpdate(base, name, { force })
   if (check.source !== null && !updatableSource(check.source)) {
     // 本地 link / file: 装的：市场不会碰它（见 updatableSource）。如实返回，别去试。

package/lib/update-install.cjs

@@ -0,0 +1,311 @@
+'use strict';
+
+/**
+ * 自己装新版：在 profile 里跑一次它**自己的**包管理器，把本插件换到指定版本。
+ *
+ * ## 为什么不借道 DSH 插件市场
+ *
+ * 插件的更新分两步：**查**（线上最新是几，见 `update-registry.cjs`）和**装**（把新版本真的
+ * 落到这台机器的 profile 里）。2026-10-11 之前「装」是请市场代劳的（打它的
+ * `/dsh-market/api/v1/updates`，等它跑完 pnpm 再问结果）。用户的判断是：这件事插件应该
+ * 自己完成，不该因为「另一个插件没装 / 太老 / 坏了」就整个失效。这里就是那一步。
+ *
+ * ## 关键：不自己实现包管理，只**驱动**它
+ *
+ * profile 里装插件用的是 pnpm，而且 profile 自己的 `pnpm-workspace.yaml` 已经写好了所有
+ * 关键设置（`node-linker=hoisted`、`auto-install-peers=false`、`minimum-release-age-exclude`
+ * 那些按包放行的条目）。所以这里是「cd 到 profile，跑一句 `pnpm add <包名>@<版本>`」——
+ * **不传布局类开关**，让它按 profile 的既有配置来，免得把别人的布局改写掉。市场那套
+ * （`pnpm-compat.js` + `install.js`）几千行都在处理 pnpm 各版本的旗标拼写、hoist 恢复、
+ * 镜像/超时/Windows shim 这些边角；这里刻意**只做我们自己这条路上必须的那两三个开关**，
+ * 剩下的交给 profile 自己的配置。
+ *
+ * ## 三个开关，每个都有理由
+ *
+ * · `--config.auto-install-peers=false`：本插件的 peer 里有一串 `@deepseek-ai/*`
+ *   （`cordis`、`dsh-tools`、`dsh-client-runtime`…），它们是 **DSH 运行时注入的、npm 上
+ *   根本没有**。pnpm 8 起 `auto-install-peers` 默认开，会去 npm 上拉这些 peer 然后 404。
+ *   profile 里通常已经关掉了，但那是市场帮它写的 —— 换台机器不一定有，所以这里显式带上。
+ * · `--config.minimum-release-age=0`：**只在强制更新时**带。pnpm 的「新发布先晾一会儿」
+ *   门槛会把刚发的版本挡在外面，`force` 就是「我知道，装它」。
+ * · `CI=1`：没有终端可交互。包管理器在无人值守的子进程里问问题是没法回答的。
+ *
+ * ## 边界（照实说）
+ *
+ * · **只动 profile 的依赖树**（`pnpm add` 会顺手把 profile 的 `package.json` 里的依赖声明
+ *   也更新掉——那正是「装上了」的凭据）。不碰仓库、不碰 `~/.dsh` 里别的东西。
+ * · **找不到包管理器就如实失败**，不猜、不回退到「假装装好了」。桌面端由 GUI 拉起时 PATH
+ *   往往很干净（LaunchServices 只给 `/usr/bin:/bin` 之类），所以这里照市场的做法补一组
+ *   常见 bin 目录再找，见 `toolSearchDirs`。
+ * · 装完**以盘上的版本号为准**：`installedVersion` 没变就是没装上，哪怕命令退出码是 0。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const { checkForUpdate } = require('./update-registry.cjs');
+
+/** 本插件的 npm 包名（`package.json` 的 name）。 */
+const DEFAULT_NAME = 'dsh-mobile-plugin';
+
+/** 一次安装的上限：pnpm 装一个包 + 拉依赖，给足但别无限等。 */
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** 命令输出留多少字符（日志与错误信息里给个人看得懂的尾巴）。 */
+const OUTPUT_TAIL = 4000;
+
+/**
+ * 去哪儿找包管理器。
+ *
+ * 与市场那份（dshmarket 的 `dsh-cli.js` `toolSearchDirs`）**故意保持一致**：桌面端由 GUI
+ * 或 Dock 拉起时继承不到 shell 的 PATH，pnpm 常常不在其中，而这一组目录覆盖了官方安装器
+ * 与 Homebrew / npm -g 的落点。`PNPM_HOME` 放最前面：安装器设了它，那是最准的答案。
+ */
+function toolSearchDirs({ platform = process.platform, env = process.env, home = os.homedir(), execDir = path.dirname(process.execPath) } = {}) {
+  const dirs = [];
+  const pnpmHome = typeof env.PNPM_HOME === 'string' ? env.PNPM_HOME.trim() : '';
+  if (pnpmHome) dirs.push(pnpmHome);
+  if (platform === 'win32') {
+    const local = typeof env.LOCALAPPDATA === 'string' ? env.LOCALAPPDATA.trim() : '';
+    const roaming = typeof env.APPDATA === 'string' ? env.APPDATA.trim() : '';
+    if (local) dirs.push(path.join(local, 'pnpm'));
+    if (roaming) dirs.push(path.join(roaming, 'npm'));
+  } else {
+    dirs.push('/opt/homebrew/bin', '/usr/local/bin', path.join(home, '.local', 'bin'));
+    dirs.push(path.join(home, 'Library', 'pnpm'), path.join(home, '.local', 'share', 'pnpm'));
+    dirs.push(path.join(home, '.npm-global', 'bin'));
+  }
+  dirs.push(execDir);
+  return [...new Set(dirs.filter(dir => typeof dir === 'string' && dir.trim() !== ''))];
+}
+
+/** 找一个能跑的可执行文件：先给的那几组目录，再 PATH。Windows 上认 `.cmd` 后缀。 */
+function resolveExecutable(command, dirs, { platform = process.platform, env = process.env } = {}) {
+  const names = platform === 'win32' ? [`${command}.cmd`, `${command}.exe`, command] : [command];
+  const fromPath = String(env.PATH || '')
+    .split(path.delimiter)
+    .filter(Boolean);
+  for (const dir of [...dirs, ...fromPath]) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        const stat = fs.statSync(candidate);
+        if (stat.isFile()) return candidate;
+      } catch {
+        // 不存在就下一个。
+      }
+    }
+  }
+  return null;
+}
+
+/** 把补出来的目录接在 PATH 前面（子进程里的 pnpm 还要再 spawn 它自己的东西）。 */
+function spawnEnv(dirs, env = process.env) {
+  const existing = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  return { ...env, PATH: [...dirs, ...existing].join(path.delimiter), CI: env.CI || '1' };
+}
+
+/** profile 里装着的那份插件包的版本号（读不到返回 null）。 */
+function installedVersion(profileNodeModules, name = DEFAULT_NAME) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(profileNodeModules, name, 'package.json'), 'utf8'));
+    return typeof raw.version === 'string' && raw.version ? raw.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * profile 的依赖声明里这个包是怎么装的（`profileDir` 是 profile 根，不是它的 node_modules）。
+ *
+ * 只有 `link:` 要拦：那是**故意**把插件指向某个本地目录（开发时），装一次 npm 版会把这个
+ * 指向悄悄改掉。`file:` 的 tgz 与普通版号都照装（前者会一并换成注册表来源，这是想要的）。
+ * 读不到就说不知道（null），不要瞎猜。
+ */
+function declaredSource(profileDir, name = DEFAULT_NAME) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8'));
+    const spec = raw?.dependencies?.[name] ?? raw?.devDependencies?.[name];
+    if (typeof spec !== 'string') return null;
+    if (spec.startsWith('link:')) return 'linked';
+    if (spec.startsWith('file:')) return 'file';
+    if (spec.startsWith('workspace:')) return 'workspace';
+    return 'npm';
+  } catch {
+    return null;
+  }
+}
+
+/** 跑一条命令，收 stdout+stderr 的尾巴。超时或非零退出码都如实带出来。 */function run(command, args, { cwd, env, timeoutMs, spawnImpl = spawn }) {
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = spawnImpl(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      resolve({ ok: false, code: null, output: '', error: String(error?.message || error) });
+      return;
+    }
+    let output = '';
+    const collect = chunk => {
+      output += String(chunk);
+      if (output.length > OUTPUT_TAIL * 2) output = output.slice(-OUTPUT_TAIL);
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // 已经退出了。
+      }
+    }, timeoutMs);
+    child.on('error', error => {
+      clearTimeout(timer);
+      resolve({ ok: false, code: null, output, error: String(error?.message || error) });
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code, output: output.slice(-OUTPUT_TAIL), error: null });
+    });
+  });
+}
+
+/**
+ * 装一次：把 <name> 换到 <version>。
+ *
+ * @param {object} options
+ * @param {string} options.profileNodeModules profile 的 `node_modules` 目录
+ * @param {string} options.version           要装的版本（注册表给的）
+ * @param {boolean} [options.force]          true = 跳过「新发布先晾一会儿」的门槛
+ * @returns {Promise<{installed, skipped, beforeVersion, installedVersion, source, command, output, failure}>}
+ */
+async function installLatest({
+  profileNodeModules,
+  version,
+  name = DEFAULT_NAME,
+  force = false,
+  timeoutMs = INSTALL_TIMEOUT_MS,
+  env = process.env,
+  platform = process.platform,
+  // 去哪儿找包管理器。默认那组见 `toolSearchDirs`；注入只为测试。
+  dirs = null,
+  onEvent = () => {},
+} = {}) {
+  const beforeVersion = installedVersion(profileNodeModules, name);
+  const profileDir = path.dirname(profileNodeModules);
+  const searchDirs = dirs ?? toolSearchDirs({ platform, env });
+  const pnpm = resolveExecutable('pnpm', searchDirs, { platform, env });
+  const npm = pnpm ? null : resolveExecutable('npm', searchDirs, { platform, env });
+  const manager = pnpm ? 'pnpm' : npm ? 'npm' : null;
+  const binary = pnpm || npm;
+
+  const fail = (code, message) => ({
+    installed: false,
+    skipped: false,
+    beforeVersion,
+    installedVersion: installedVersion(profileNodeModules, name),
+    source: declaredSource(profileDir, name),
+    command: null,
+    output: '',
+    failure: { code, message },
+  });
+
+  if (!binary) {
+    return fail(
+      'PACKAGE_MANAGER_MISSING',
+      '这台机器上找不到 pnpm / npm，装不了新版。装一个 pnpm（或 npm）之后重试；' +
+        '插件不会自己去下载解包 —— 那等于把包管理器的活抄一遍，抄漏一处就是装出半个包。',
+    );
+  }
+
+  const source = declaredSource(profileDir, name);
+  if (source === 'linked') {
+    return fail(
+      'LINKED_SOURCE',
+      '这个插件在 profile 里指向一个本地目录（link:），是有意为之。自己装会把那个指向改掉，' +
+        '所以这里不动它：要去掉这个指向，先在插件市场里按包名重装一次。',
+    );
+  }
+
+  const spec = `${name}@${version}`;
+  const args = manager === 'pnpm'
+    ? ['add', spec, '--config.auto-install-peers=false', ...(force ? ['--config.minimum-release-age=0'] : [])]
+    : ['install', spec, '--no-audit', '--no-fund'];
+  const command = [manager, ...args].join(' ');
+  onEvent({ phase: 'install-started', command });
+
+  const result = await run(binary, args, { cwd: profileDir, env: spawnEnv(searchDirs, env), timeoutMs });
+  const after = installedVersion(profileNodeModules, name);
+  if (!result.ok) {
+    return {
+      installed: false,
+      skipped: false,
+      beforeVersion,
+      installedVersion: after,
+      source: declaredSource(profileDir, name),
+      command,
+      output: result.output,
+      // 超时与「真的失败了」分开说：前者可以再试，后者多半要看输出。
+      failure: {
+        code: result.code === null ? 'INSTALL_ABORTED' : 'INSTALL_FAILED',
+        message: `${command} ${result.code === null ? '没能跑完' : `退出码 ${result.code}`}${result.error ? `：${result.error}` : ''}`,
+      },
+    };
+  }
+  // 退出码 0 不算数：**盘上版本真的变了**才算装上（市场那份代码吃过这个亏）。
+  const changed = after !== null && after !== beforeVersion;
+  return {
+    installed: changed,
+    skipped: false,
+    beforeVersion,
+    installedVersion: after,
+    source: declaredSource(profileDir, name),
+    command,
+    output: result.output,
+    failure: changed
+      ? null
+      : { code: 'VERSION_UNCHANGED', message: `${command} 跑完了，但盘上还是 ${after ?? '读不到版本'}，这一次不算数` },
+  };
+}
+
+/**
+ * 「让我变成最新」：先查一次，再决定装不装。
+ *
+ * 面板那颗按钮**与外壳的自动更新**都打这个入口 —— 两处走同一套判定，免得出现「手动说有
+ * 新版、自动说没有」这种最难查的偏差。已经是最新（`force` 为假）就什么都不做、如实报
+ * `skipped`。
+ */
+async function installLatestIfNeeded(options = {}) {
+  const { profileNodeModules, force = false, name = DEFAULT_NAME } = options;
+  const beforeVersion = installedVersion(profileNodeModules, name);
+  const check = await checkForUpdate({ installedVersion: beforeVersion, source: declaredSource(path.dirname(profileNodeModules), name) });
+  if (!force && !check.updateAvailable) {
+    return {
+      installed: false,
+      skipped: true,
+      beforeVersion,
+      installedVersion: beforeVersion,
+      source: check.source,
+      command: null,
+      output: '',
+      failure: null,
+      check,
+    };
+  }
+  const result = await installLatest({ ...options, version: check.latestVersion });
+  return { ...result, check };
+}
+
+module.exports = {
+  installLatest,
+  installLatestIfNeeded,
+  installedVersion,
+  declaredSource,
+  toolSearchDirs,
+  resolveExecutable,
+  DEFAULT_NAME,
+  INSTALL_TIMEOUT_MS,
+  OUTPUT_TAIL,
+};