dsh-maoying 0.1.17 → 0.1.19

package/lib/self-update.mjs

@@ -1,42 +1,108 @@
 /**
- * 面板内一键升级 —— 直接跑 pnpm 把本包装到当前 DSH profile（创作台面板用）。
+ * 面板内一键升级 —— 版本预检 + pnpm 候选链（机制对齐 dsh-paoding
+ * tools/lib/upgrade.mjs，0.1.18 起）。
  *
  * 背景：desktop 档的真实安装形态是 <dshHome>/profiles/<profile>/node_modules/
  * dsh-maoying（真实目录，非 symlink），宿主 dsh CLI 拒绝管理 desktop 档，唯一
- * 可行的升级命令是直接 pnpm：`pnpm --dir <profileDir> add dsh-maoying@latest`。
+ * 可行的升级命令是在 profile 目录里直跑 `pnpm add dsh-maoying@<精确版本>`：
+ *   - cwd 就是 profile 目录（pnpm 的操作对象是它），不带 --dir；
+ *   - 装精确版本而非 @latest——避开 pnpm 新鲜度防护 / 镜像 packument 滞后
+ *     造成的「跑了但啥也没装」静默空转。
+ *
+ * pnpm 解析（0.1.18 重写，修复「未找到 pnpm」误报）：不再 existsSync+
+ * accessSync(X_OK) 文件预筛（corepack 管理且未 `corepack enable` 的机器 PATH
+ * 里没有裸 pnpm，桌面 GUI 进程 PATH 还可能是 launchd 最小集，预筛必落空），
+ * 改为 spawn ENOENT 探测链：逐候选真 spawn，仅 err.code==='ENOENT' 才换下一
+ * 路；EACCES / 超时 / 非零退出都是真实运行结果，如实返回不换通道。候选链：
+ *   1) 裸 pnpm（npm i -g / homebrew 等常规安装）；
+ *   2) 裸 corepack（corepack 随 node 发行，未 enable 也能 `corepack pnpm ...`
+ *      即装即用）；
+ *   3) /opt/homebrew/bin/corepack（existsSync 预筛，不在盘上不浪费 spawn）；
+ *   4) /opt/homebrew/opt/node@XX/bin/corepack（readdirSync 过滤 node 前缀目录
+ *      拼路径，
+ *      兜住 keg-only 的 node@XX 版代安装——desktop Electron 最小 PATH 实测
+ *      全靠它命中）；
+ *   5) path.dirname(process.execPath)/corepack（桌面 Electron 下无用但无害，
+ *      headless / web profile 的 node 同目录形态有用）；
+ *   6) ~/Library/pnpm、~/.local/share/pnpm（pnpm 独立安装脚本落位）。
+ * win32 的 pnpm / corepack 都是 .cmd shim，spawn 必须 shell:true（Node 直接
+ * spawn .cmd 会 EINVAL，见 CVE-2024-27980 加固），命令补 .cmd 后缀、参数保持
+ * 数组形式；darwin/linux 恒 shell:false，无注入面。
+ *
+ * 升级前版本预检：fetchLatestFromRegistry（10s）失败再 fetchLatestFromMirror
+ * （10s），拿不到 latest 绝不做半截升级；compareVersions(target, current) <= 0
+ * 直接短路「已是最新」，不 spawn。装完失效版本检测缓存。
  *
  * 安全边界（缺一不可，全不满足绝不执行安装）：
  *   1) 安装形态判定——插件包自身目录先 realpathSync 取真路径，真路径 ≠ 常规
  *      路径即 link/symlink 安装（如 web 档指向 dev repo）→ 拒绝（dev-link，
- *      请在开发目录 git pull）；真路径不匹配 <dshHome>/profiles/<profile>/
- *      node_modules/dsh-maoying 结构 → 拒绝（unsupported-layout）。dshHome /
- *      profile 取 env.DSH_HOME / DSH_PROFILE（~ 前缀手动展开），缺失时回退从
- *      真路径的 profiles 祖先推导，推导不出同样拒绝。
- *   2) pnpm 解析——按候选路径逐个 existsSync + accessSync(X_OK)（PATH 各目录
- *      在前，homebrew / pnpm 官方安装位在后），一个都不可执行 → 拒绝
- *      （pnpm-missing）。绝不用 shell:true，无注入面。
- *   3) 超时 180 秒——超时 kill 子进程收敛为 timeout，不挂死面板请求。
+ *      指路 git pull）；真路径不匹配 <dshHome>/profiles/<profile>/node_modules/
+ *      dsh-maoying 结构 → 拒绝（unsupported-layout）。dshHome / profile 取
+ *      env.DSH_HOME / DSH_PROFILE（~ 前缀手动展开），缺失时回退从真路径的
+ *      profiles 祖先推导，推导不出同样拒绝。
+ *   2) profile 就绪判定——profile 目录没有 package.json（未初始化）→ 拒绝
+ *      （profile-missing），不硬跑 pnpm（会在空目录另起一份 package.json）。
+ *   3) 超时 180 秒——超时 SIGTERM（5s 后升级 SIGKILL）收敛为 timeout，不挂死
+ *      面板请求。
+ *
+ * 全局 CLI 顺带更新（方案 B：desktop profile 与全局 npm 安装是两份独立拷贝，
+ * 只更 profile 会版本偏斜）：profile 阶段落定（installed 装完 / up-to-date
+ * 短路）后跑独立的全局阶段，目标是两份安装收敛到同一精确版本：
+ *   - detectGlobalCli 零 spawn 纯文件系统检测：PATH 各目录 + /opt/homebrew/bin
+ *     + /usr/local/bin 找 `maoying`（win32 `maoying.cmd`），existsSync 预筛；
+ *     命中后 realpathSync 该 bin 两级上溯得包根（bin/maoying.mjs → 包根），
+ *     包根 package.json 的 name 必须是 dsh-maoying 才认（防怪链接）；包根
+ *     realpath 落在本 profile 目录内（如 profile 自带 .bin/maoying）→ 不是
+ *     全局安装，跳过该候选继续找。找不到任何候选 → { found: false }。
+ *   - 找不到全局安装 → globalCli: { ok: true, skipped: 'missing' }，不 spawn；
+ *   - 全局 version 与精确目标同版 → skipped: 'same'，不 spawn；否则 spawn
+ *     `npm i -g dsh-maoying@<target>`（cwd=os.tmpdir()、独立 120s 超时，npm
+ *     候选链与 pnpm 同款 spawn ENOENT 探测：裸 npm → execPath 同目录 →
+ *     /opt/homebrew/bin → /usr/local/bin → /opt/homebrew/opt/node@XX/bin）。
+ *   - 全局阶段失败（npm 缺失 / 非零 / 超时）**不拖累整体结果**：profile 已装
+ *     好，重启照常生效；globalCli.ok:false + 中文 error（含手动出路
+ *     `npm i -g dsh-maoying@<target>`）如实透出。dev-link / unsupported-layout /
+ *     no-target / profile-missing 等失败路径维持整单拒绝，不碰全局。
  *
  * 所有失败路径都不抛错，一律收敛为 { ok: false, kind, message } 结果对象；
- * 成功返回 { ok: true, kind: 'installed', from, to, restartRequired: true }。
- * 硬约束：装完后运行中的进程仍是旧代码，必须重启 DeepSeek 才生效——restart-
- * Required 恒 true，UI 文案必须明说，不得暗示装完即生效。依赖全部可注入
- * （spawnImpl / realpathImpl / existsImpl / readImpl …），对齐 lib/version.mjs
- * 的 fetchImpl 模式，方便测试。
+ * 成功返回 { ok: true, kind: 'installed', from, to, restartRequired: true,
+ * globalCli }，已是最新短路返回 { ok: true, kind: 'up-to-date', from,
+ * globalCli }（globalCli 形状见上节）。硬约束：装完后运行
+ * 中的进程仍是旧代码，必须重启 DeepSeek 才生效——restartRequired 恒 true，UI
+ * 文案必须明说，不得暗示装完即生效。依赖全部可注入（spawnImpl / realpathImpl /
+ * existsImpl / readdirImpl / fetchImpl / platform …），对齐 lib/version.mjs 的
+ * fetchImpl 模式，方便测试。
  */
 import { spawn as nodeSpawn } from 'node:child_process'
-import { accessSync, constants as fsConstants, existsSync, realpathSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { invalidateVersionCache } from './version.mjs'
+import {
+  compareVersions,
+  currentVersion,
+  fetchLatestFromMirror,
+  fetchLatestFromRegistry,
+  invalidateVersionCache,
+} from './version.mjs'
 
 /** 安装超时：pnpm 冷缓存 + 国内网络最坏留足 3 分钟。 */
 export const SELF_UPDATE_TIMEOUT_MS = 180 * 1000
-/** 失败信息里保留的子进程输出尾部字节数（stdout / stderr 各一份）。 */
-const OUTPUT_TAIL_BYTES = 2048
+/** 全局 CLI 更新超时：npm i -g 单包安装，独立于 profile 的 180s，2 分钟收敛。 */
+export const GLOBAL_CLI_TIMEOUT_MS = 120 * 1000
+/** 版本预检单路（registry / mirror）超时：用户显式点了「升级」，等得起。 */
+const VERSION_TIMEOUT_MS = 10 * 1000
+/**
+ * 失败信息里保留的子进程输出尾部长度（stdout+stderr 合并后取尾）：8KB——
+ * pnpm 的报错结论都在尾部，但镜像 404 / 对账冲突这类关键行可能被进度刷屏
+ * 顶得很深，2KB 不够排障。
+ */
+const OUTPUT_TAIL_BYTES = 8 * 1024
+/** 输出累积硬上限：超过先截一版，防异常刷爆内存。 */
+const OUTPUT_HARD_CAP_BYTES = 1024 * 1024
+/** SIGTERM 后留给进程自行退出的宽限，超时升级 SIGKILL。 */
+const TERM_GRACE_MS = 5 * 1000
 
 /**
  * 插件包自身目录（package.json 所在目录）。抽成函数便于测试注入假安装位。
@@ -46,34 +112,57 @@ function defaultPkgDir() {
 }
 
 /**
- * PATH 里 pnpm 之后的候选兜底（macOS 常见安装位；GUI 进程 PATH 常缺 pnpm，
- * 宿主进程又不经过 shell，PATH 找不到时按固定路径逐个试）。
+ * 缺省子进程执行器（可被 spawnImpl 注入替换，测试用）：spawn 任意命令，合并
+ * 收集 stdout+stderr，永不 reject，统一收敛为
+ *   { code, output, error?, errorCode? }
+ * error 仅子进程异常（spawn 失败 / 超时）时存在；errorCode 为结构化失败码：
+ * spawn 失败透传 err.code（如 'ENOENT'，候选链据此换下一路），超时收敛为
+ * 'ETIMEDOUT'。timeoutLabel 只用于超时文案标明哪条通道超时。超时先 SIGTERM，
+ * TERM_GRACE_MS 后仍不退则 SIGKILL 兜底（pnpm 尊重 SIGTERM；SIGKILL 保证
+ * close 事件必然到达，调用方绝不悬挂）。
  */
-function extraPnpmCandidates(env) {
-  const home = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : os.homedir()
-  return [
-    '/opt/homebrew/bin/pnpm',
-    '/usr/local/bin/pnpm',
-    path.join(home, '.local', 'share', 'pnpm', 'pnpm'),
-    path.join(home, 'Library', 'pnpm', 'pnpm'),
-  ]
-}
-
-/** 解析 pnpm 可执行文件：PATH 各目录在前、常见安装位兜底，去重后逐个可执行性检查。 */
-function resolvePnpm(env, { existsImpl, accessImpl }) {
-  const pathEnv = typeof env.PATH === 'string' ? env.PATH : ''
-  const fromPath = pathEnv.split(path.delimiter).filter((d) => d !== '').map((d) => path.join(d, 'pnpm'))
-  const candidates = [...new Set([...fromPath, ...extraPnpmCandidates(env)])]
-  for (const candidate of candidates) {
+export function defaultSpawn(command, args, options, timeoutMs, timeoutLabel) {
+  return new Promise((resolve) => {
+    let child
     try {
-      if (!existsImpl(candidate)) continue
-      accessImpl(candidate, fsConstants.X_OK)
-      return candidate
-    } catch {
-      /* 存在但不可执行（或探测异常）：换下一个候选 */
+      child = nodeSpawn(command, args, options)
+    } catch (err) {
+      // 参数非法等同步异常：与 error 事件同一收敛形状。
+      resolve({ code: null, output: '', error: String(err?.message ?? err), errorCode: err?.code ?? null })
+      return
     }
-  }
-  return null
+    let output = ''
+    const onChunk = (chunk) => {
+      output += chunk.toString()
+      if (output.length > OUTPUT_HARD_CAP_BYTES) output = output.slice(-OUTPUT_TAIL_BYTES)
+    }
+    child.stdout?.on('data', onChunk)
+    child.stderr?.on('data', onChunk)
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      try { child.kill('SIGTERM') } catch { /* 已退出：忽略 */ }
+    }, timeoutMs)
+    const killTimer = setTimeout(() => {
+      if (!timedOut) return
+      try { child.kill('SIGKILL') } catch { /* 已退出：忽略 */ }
+    }, timeoutMs + TERM_GRACE_MS)
+    const settle = (r) => { clearTimeout(timer); clearTimeout(killTimer); resolve(r) }
+    child.on('error', (err) => {
+      settle({ code: null, output: tailOutput(output), error: String(err?.message ?? err), errorCode: err?.code ?? null })
+    })
+    child.on('close', (code) => {
+      settle(timedOut
+        ? { code, output: tailOutput(output), error: `${timeoutLabel} 超时（${Math.round(timeoutMs / 1000)} 秒）已中止`, errorCode: 'ETIMEDOUT' }
+        : { code, output: tailOutput(output) })
+    })
+  })
+}
+
+/** 取尾部：超长只留最后 OUTPUT_TAIL_BYTES。 */
+function tailOutput(text) {
+  const s = String(text ?? '')
+  return s.length > OUTPUT_TAIL_BYTES ? s.slice(-OUTPUT_TAIL_BYTES) : s
 }
 
 /**
@@ -98,48 +187,213 @@ function dshHomeFromEnv(env) {
   return raw
 }
 
+/** env 里的用户 home（PATH 候选拼接用；缺失回退 os.homedir()）。 */
+function homeFromEnv(env) {
+  const raw = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : ''
+  return raw !== '' ? raw : os.homedir()
+}
+
 /**
- * 读安装目录 package.json 的 version；读不到（缺失 / 解析失败 / 字段异常）
- * 返回 null——from 缺失不拦安装（pnpm 退出码才是成败信号），to 缺失照常
- * ok:true（version 显示为 null，前端兜底显示）。
+ * 组装 pnpm 候选链（详见文件头注）：裸 pnpm → 裸 corepack（+['pnpm'] 前缀）
+ * → 各绝对路径落位（existsSync 预筛，不存在不浪费 spawn；去重保序）。
+ * win32 的 pnpm / corepack 是 .cmd shim，命令补 .cmd 后缀（配合 shell:true）；
+ * darwin/linux 补空串。/opt/homebrew 系仅 darwin+homebrew 存在，existsSync
+ * 自然过滤，无需按平台分支。
  */
-async function readPkgVersion(pkgJsonPath, readImpl) {
+function buildCandidates({ platform, env, execPath, existsImpl, readdirImpl }) {
+  const suffix = platform === 'win32' ? '.cmd' : ''
+  const candidates = [
+    { command: `pnpm${suffix}`, argsPrefix: [], label: 'pnpm' },
+    { command: `corepack${suffix}`, argsPrefix: ['pnpm'], label: 'corepack pnpm' },
+  ]
+  const absolute = ['/opt/homebrew/bin/corepack']
   try {
-    const raw = await readImpl(pkgJsonPath)
-    const pkg = JSON.parse(raw)
-    return typeof pkg?.version === 'string' && pkg.version !== '' ? pkg.version : null
-  } catch {
-    return null
+    // /opt/homebrew/opt/<node 版本目录>/bin/corepack：目录不存在（非 ARM
+    // homebrew mac）readdir 抛错即跳过；命中多个 node 版本时按名排序全收。
+    const nodeDirs = readdirImpl('/opt/homebrew/opt')
+      .filter((name) => name.startsWith('node'))
+      .sort()
+    for (const dir of nodeDirs) absolute.push(path.join('/opt/homebrew/opt', dir, 'bin', `corepack${suffix}`))
+  } catch { /* 无 /opt/homebrew/opt：跳过这组候选 */ }
+  absolute.push(path.join(path.dirname(execPath), `corepack${suffix}`))
+  const home = homeFromEnv(env)
+  absolute.push(path.join(home, 'Library', 'pnpm', `pnpm${suffix}`))
+  absolute.push(path.join(home, '.local', 'share', 'pnpm', `pnpm${suffix}`))
+  for (const p of [...new Set(absolute)]) {
+    if (existsImpl(p)) candidates.push({ command: p, argsPrefix: [], label: p })
+  }
+  return candidates
+}
+
+/**
+ * 全局 maoying CLI 检测（零 spawn，纯文件系统；机制见文件头注「全局 CLI 顺带
+ * 更新」节）。bin 候选位 = env.PATH 各目录 + /opt/homebrew/bin + /usr/local/bin
+ * （去重保序），找 `maoying`（win32 `maoying.cmd`），existsSync 预筛；命中后
+ * realpathSync 两级上溯得包根，包根 package.json 的 name 必须是 dsh-maoying
+ * 才认；包根 realpath 落在 profileDir 内（或就是它）→ 是 profile 自己的
+ * .bin/maoying，跳过该候选继续找。全落空 → { found: false }。
+ * 任何一步异常（断链 symlink / 包根不可读 / JSON 坏）都只跳过该候选，不抛错。
+ */
+function detectGlobalCli({ env, platform, profileDir, existsImpl, realpathImpl, readImpl }) {
+  const binName = `maoying${platform === 'win32' ? '.cmd' : ''}`
+  const dirs = String(typeof env.PATH === 'string' ? env.PATH : '')
+    .split(path.delimiter)
+    .map((d) => d.trim())
+    .filter((d) => d !== '')
+  dirs.push('/opt/homebrew/bin', '/usr/local/bin')
+  // profile 目录 realpath 只算一次（目录此刻必然存在——package.json 就绪闸已过；
+  // 读不到真路径就退回原路径，比对退化为保守不误杀全局候选）。
+  let realProfileDir = null
+  try { realProfileDir = path.resolve(realpathImpl(profileDir)) } catch { realProfileDir = path.resolve(profileDir) }
+  for (const dir of [...new Set(dirs)]) {
+    const bin = path.join(dir, binName)
+    if (!existsImpl(bin)) continue
+    let cli
+    try { cli = path.resolve(realpathImpl(bin)) } catch { continue }
+    const root = path.dirname(path.dirname(cli))
+    let manifest
+    try { manifest = JSON.parse(readImpl(path.join(root, 'package.json'))) } catch { continue }
+    if (manifest?.name !== 'dsh-maoying') continue
+    let realRoot
+    try { realRoot = path.resolve(realpathImpl(root)) } catch { realRoot = path.resolve(root) }
+    if (realRoot === realProfileDir || realRoot.startsWith(realProfileDir + path.sep)) continue
+    return {
+      found: true,
+      bin,
+      root,
+      version: typeof manifest.version === 'string' ? manifest.version : '',
+    }
+  }
+  return { found: false }
+}
+
+/**
+ * 组装 npm 候选链（全局 CLI 更新用，与 pnpm 链同款 spawn ENOENT 探测语义）：
+ * 裸 npm → execPath 同目录（node 与 npm 同落位的常规发行形态）→
+ * /opt/homebrew/bin → /usr/local/bin → /opt/homebrew/opt/node@XX/bin（readdirSync
+ * 过滤 node 前缀目录，兜 keg-only node@XX）。绝对路径候选 existsSync 预筛；
+ * 去重保序。win32 的 npm 是 .cmd shim，命令补后缀（配合 shell:true）。
+ */
+function buildNpmCandidates({ platform, execPath, existsImpl, readdirImpl }) {
+  const suffix = platform === 'win32' ? '.cmd' : ''
+  const candidates = [{ command: `npm${suffix}`, label: 'npm' }]
+  const absolute = [
+    path.join(path.dirname(execPath), `npm${suffix}`),
+    '/opt/homebrew/bin/npm',
+    '/usr/local/bin/npm',
+  ]
+  try {
+    const nodeDirs = readdirImpl('/opt/homebrew/opt')
+      .filter((name) => name.startsWith('node'))
+      .sort()
+    for (const dir of nodeDirs) absolute.push(path.join('/opt/homebrew/opt', dir, 'bin', `npm${suffix}`))
+  } catch { /* 无 /opt/homebrew/opt：跳过这组候选 */ }
+  for (const p of [...new Set(absolute)]) {
+    if (existsImpl(p)) candidates.push({ command: p, label: p })
+  }
+  return candidates
+}
+
+/**
+ * 全局 CLI 阶段（profile 阶段落定后跑；失败绝不拖累整体结果，形状见文件头注）。
+ * 返回 { ok: true, skipped: 'missing' } / { ok: true, skipped: 'same', version } /
+ * { ok: true, from, to: targetVersion } / { ok: false, error, output? }。
+ * spawn 走 npm 候选链（仅 ENOENT 换下一路），cwd=os.tmpdir()（npm 全局装与
+ * cwd 无关，不该在 profile / 仓库里跑），独立 globalTimeoutMs 超时。
+ */
+async function updateGlobalCliStage({ targetVersion, profileDir }, deps) {
+  const { env, platform, execPath, spawnImpl, existsImpl, readdirImpl, realpathImpl, readImpl, logger, globalTimeoutMs } = deps
+  const g = detectGlobalCli({ env, platform, profileDir, existsImpl, realpathImpl, readImpl })
+  if (!g.found) return { ok: true, skipped: 'missing' }
+  // 版本比对（'' = 包根 package.json 缺 version，当旧版处理装到精确目标）。
+  if (g.version !== '' && compareVersions(g.version, targetVersion) === 0) {
+    logger?.info?.(`maoying 创作台: 全局 maoying CLI 已是 ${g.version}，跳过更新`)
+    return { ok: true, skipped: 'same', version: g.version }
+  }
+
+  const spawnOptions = {
+    cwd: os.tmpdir(),
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: platform === 'win32',
+  }
+  const candidates = buildNpmCandidates({ platform, execPath, existsImpl, readdirImpl })
+  const installArgs = ['i', '-g', `dsh-maoying@${targetVersion}`]
+  const manual = `npm i -g dsh-maoying@${targetVersion}`
+
+  let proc = null
+  for (const cand of candidates) {
+    proc = await spawnImpl(cand.command, installArgs, spawnOptions, globalTimeoutMs, 'npm i -g')
+    if (proc?.errorCode !== 'ENOENT') break
+  }
+  const output = tailOutput(proc?.output)
+
+  // 以下失败路径一律 globalCli.ok:false + 中文 error 含手动出路；整体结果由
+  // 调用方维持 ok:true（profile 已装好，全局失败不追责整单）。
+  if (proc?.errorCode === 'ENOENT') {
+    const tried = candidates.map((c) => c.label).join(' / ')
+    const error = `未找到可用的 npm（已试 ${tried}），全局 CLI 未更新；可手动执行：${manual}`
+    logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(npm-missing): ${error}`)
+    return { ok: false, error }
+  }
+  if (proc?.errorCode === 'ETIMEDOUT') {
+    logger?.warn?.('maoying 创作台: 全局 CLI 更新失败(timeout): ' + String(proc?.error ?? ''))
+    return {
+      ok: false,
+      error: `npm i -g 超时（${Math.round(globalTimeoutMs / 1000)} 秒）已中止，全局 CLI 未更新；可手动执行：${manual}`,
+      output,
+    }
+  }
+  if (proc?.error) {
+    const error = `npm 启动失败: ${proc.error}，全局 CLI 未更新；可手动执行：${manual}`
+    logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(spawn): ${proc.error}`)
+    return { ok: false, error, output }
   }
+  if (proc?.code !== 0) {
+    const error = `npm i -g 失败（exit ${proc?.code}），全局 CLI 未更新；可手动执行：${manual}`
+    logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(exit ${proc?.code}): ${output}`)
+    return { ok: false, error, output }
+  }
+  logger?.info?.(`maoying 创作台: 全局 maoying CLI ${g.version} → ${targetVersion}`)
+  return { ok: true, from: g.version, to: targetVersion }
 }
 
 /** 组装最小注入面：缺省走真实 Node 实现，测试逐项替换。 */
-function normalizeDeps(opts) {
-  const env = opts.env ?? process.env
+function normalizeDeps(opts = {}) {
   return {
-    env,
-    spawnImpl: opts.spawnImpl ?? nodeSpawn,
+    env: opts.env ?? process.env,
+    platform: opts.platform ?? process.platform,
+    execPath: opts.execPath ?? process.execPath,
+    spawnImpl: opts.spawnImpl ?? defaultSpawn,
     pkgDirImpl: opts.pkgDirImpl ?? defaultPkgDir,
     realpathImpl: opts.realpathImpl ?? ((p) => realpathSync(p)),
     existsImpl: opts.existsImpl ?? ((p) => existsSync(p)),
-    accessImpl: opts.accessImpl ?? ((p, mode) => accessSync(p, mode)),
-    readImpl:
-      opts.readImpl ??
-      ((p) => readFile(p, 'utf8')),
+    readdirImpl: opts.readdirImpl ?? ((p) => readdirSync(p)),
+    readImpl: opts.readImpl ?? ((p) => readFileSync(p, 'utf8')),
+    fetchImpl: opts.fetchImpl ?? null,
     logger: opts.logger ?? console,
     timeoutMs:
       typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0 ? opts.timeoutMs : SELF_UPDATE_TIMEOUT_MS,
+    globalTimeoutMs:
+      typeof opts.globalTimeoutMs === 'number' && opts.globalTimeoutMs > 0
+        ? opts.globalTimeoutMs
+        : GLOBAL_CLI_TIMEOUT_MS,
   }
 }
 
 /**
  * selfUpdate 主体（永不 reject；concurrency 去重与兜底 try/catch 在外层）。
  * @returns {Promise<{ok: boolean, kind: string, from?: string|null, to?: string|null,
- *           restartRequired?: boolean, message?: string}>}
+ *           restartRequired?: boolean, message?: string,
+ *           globalCli?: {ok: true, skipped: 'missing'} | {ok: true, skipped: 'same', version: string} |
+ *                       {ok: true, from: string, to: string} | {ok: false, error: string, output?: string}}>}
+ *           globalCli 仅两个成功路径携带，形状见文件头注「全局 CLI 顺带更新」节。
  */
 async function runSelfUpdate(opts = {}) {
-  const { spawnImpl, pkgDirImpl, realpathImpl, existsImpl, accessImpl, readImpl, env, logger, timeoutMs } =
-    normalizeDeps(opts)
+  const {
+    env, platform, execPath, spawnImpl, pkgDirImpl, realpathImpl, existsImpl, readdirImpl, readImpl,
+    fetchImpl, logger, timeoutMs, globalTimeoutMs,
+  } = normalizeDeps(opts)
 
   // ── a) 安装形态判定 ──────────────────────────────────────────────────────
   const pkgDir = pkgDirImpl()
@@ -169,75 +423,106 @@ async function runSelfUpdate(opts = {}) {
     }
   }
 
-  // ── b) 解析 pnpm ────────────────────────────────────────────────────────
-  const pnpmPath = resolvePnpm(env, { existsImpl, accessImpl })
-  if (!pnpmPath) {
+  // ── b) 版本预检：拿不到 latest 绝不做半截升级（宁可不动现有安装）─────────
+  //    官方源失败再试 npmmirror 镜像（点「升级」的用户网络本来就在出状况，
+  //    多一路快路实打实救回一次升级）；仍拿不到如实报 no-target。
+  const { version: current } = await currentVersion()
+  const reg = await fetchLatestFromRegistry({ fetchImpl, timeoutMs: VERSION_TIMEOUT_MS })
+  const mirror = reg.ok ? null : await fetchLatestFromMirror({ fetchImpl, timeoutMs: VERSION_TIMEOUT_MS })
+  const manifest = reg.ok ? reg : mirror
+  if (!manifest.ok) {
     return {
       ok: false,
-      kind: 'pnpm-missing',
-      message: '未找到 pnpm 可执行文件（PATH 与常见安装路径都没有），请先安装 pnpm 后重试',
+      kind: 'no-target',
+      message: `无法确定最新版本：官方源 ${reg.error}；镜像 ${manifest.error}`,
     }
   }
+  const target = manifest.latest // 形如 v0.2.3
+  const targetVersion = target.replace(/^v/, '')
+  // 全局 CLI 阶段的依赖包（两个成功路径各跑一次；失败路径整单拒绝、碰都不碰）。
+  const globalDeps = { env, platform, execPath, spawnImpl, existsImpl, readdirImpl, realpathImpl, readImpl, logger, globalTimeoutMs }
+  if (compareVersions(target, current) <= 0) {
+    logger?.info?.(`maoying 创作台: self-update 短路：本地 ${current} 已不落后线上 ${target}`)
+    // 方案 B 语义 = 两份同版：profile 已是 target 时全局 CLI 若仍落后，照样更到
+    // 同一精确版本（全局没装 / 已同版时阶段内自行跳过，不 spawn）。
+    const globalCli = await updateGlobalCliStage({ targetVersion, profileDir }, globalDeps)
+    return { ok: true, kind: 'up-to-date', from: current, globalCli }
+  }
 
-  const pkgJsonPath = path.join(realDir, 'package.json')
-  const from = await readPkgVersion(pkgJsonPath, readImpl)
+  // ── c) profile 就绪判定：目录没有 package.json 说明未初始化，诚实失败，
+  //      不硬跑（pnpm 会在空目录另起一份 package.json，装到错误的位置）。
+  if (!existsImpl(path.join(profileDir, 'package.json'))) {
+    return {
+      ok: false,
+      kind: 'profile-missing',
+      message: `profile 未初始化（${profileDir} 缺 package.json），无法就地升级，请先重启 DeepSeek 或重新安装插件`,
+    }
+  }
 
-  // ── c) 执行安装（绝不用 shell:true，无注入面）────────────────────────────
-  const exitInfo = await new Promise((resolve) => {
-    let child
-    try {
-      child = spawnImpl(pnpmPath, ['--dir', profileDir, 'add', 'dsh-maoying@latest'], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-    } catch (err) {
-      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
-      return
+  // ── d) pnpm 候选链：spawn ENOENT（命令不存在）才换下一路，EACCES / 超时 /
+  //       非零退出都是真实运行结果，如实返回不换通道。cwd 就是 profile 目录
+  //       （pnpm 的操作对象是它），不带 --dir；装精确版本而非 @latest（避开
+  //       pnpm 新鲜度防护 / 镜像 packument 滞后的静默空转）。
+  //       win32 的 pnpm/corepack 是 .cmd shim，必须借 shell 拉起（Node 直接
+  //       spawn .cmd 会 EINVAL，见 CVE-2024-27980 加固），参数保持数组形式。
+  const useShell = platform === 'win32'
+  const spawnOptions = {
+    cwd: profileDir,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: useShell,
+  }
+  const candidates = buildCandidates({ platform, env, execPath, existsImpl, readdirImpl })
+  const installArgs = ['add', `dsh-maoying@${targetVersion}`]
+
+  let proc = null
+  for (const cand of candidates) {
+    proc = await spawnImpl(cand.command, [...cand.argsPrefix, ...installArgs], spawnOptions, timeoutMs, 'pnpm add')
+    if (proc?.errorCode !== 'ENOENT') break
+  }
+  const output = tailOutput(proc?.output)
+
+  // 全候选 ENOENT：给可操作的出路，不裸抛 spawn pnpm ENOENT（本修复的病灶）。
+  if (proc?.errorCode === 'ENOENT') {
+    const tried = candidates.map((c) => c.label).join(' / ')
+    return {
+      ok: false,
+      kind: 'pnpm-missing',
+      message: `未找到可用的 pnpm（已试 ${tried}）。可先在终端执行 corepack enable 并重启 DSH 后重试；或手动升级：cd ${profileDir} && corepack pnpm add dsh-maoying@${targetVersion}`,
     }
-    let out = Buffer.alloc(0)
-    let errBuf = Buffer.alloc(0)
-    const keepTail = (buf, chunk) => Buffer.concat([buf, Buffer.from(chunk)]).subarray(-OUTPUT_TAIL_BYTES)
-    child.stdout?.on?.('data', (chunk) => { out = keepTail(out, chunk) })
-    child.stderr?.on?.('data', (chunk) => { errBuf = keepTail(errBuf, chunk) })
-    // 定时器只在进程仍存活时触发；exit 先到则清掉，不留挂起句柄。
-    const timer = setTimeout(() => {
-      try { child.kill() } catch { /* 已退出：忽略 */ }
-      resolve({
-        failed: true,
-        kind: 'timeout',
-        message: `pnpm 安装超时（${Math.round(timeoutMs / 1000)} 秒）已中止，请检查网络后重试`,
-      })
-    }, timeoutMs)
-    const onExit = (code, signal) => {
-      clearTimeout(timer)
-      if (code === 0) {
-        resolve({ failed: false })
-        return
-      }
-      const tailText = `${out.toString('utf8')}\n${errBuf.toString('utf8')}`.trim()
-      resolve({
-        failed: true,
-        kind: 'pnpm-failed',
-        message: `pnpm add 失败（${signal != null ? `signal ${signal}` : `exit ${code}`}）：${tailText !== '' ? tailText : '无输出'}`,
-      })
+  }
+  if (proc?.errorCode === 'ETIMEDOUT') {
+    // 超时：SIGTERM 已发（宽限后 SIGKILL），如实收敛不换通道。
+    logger?.warn?.('maoying 创作台: self-update 失败(timeout): ' + String(proc?.error ?? ''))
+    return {
+      ok: false,
+      kind: 'timeout',
+      message: `pnpm 安装超时（${Math.round(timeoutMs / 1000)} 秒）已中止，请检查网络后重试`,
+    }
+  }
+  if (proc?.error) {
+    // 其他子进程异常（EACCES 等真实结果，不换通道、不猜原因）。
+    logger?.warn?.(`maoying 创作台: self-update 失败(spawn): ${proc.error}`)
+    return { ok: false, kind: 'nonzero', message: `pnpm 启动失败: ${proc.error}` }
+  }
+  if (proc?.code !== 0) {
+    return {
+      ok: false,
+      kind: 'nonzero',
+      message: `pnpm add 失败（exit ${proc?.code}）：${output !== '' ? output : '无输出'}`,
     }
-    child.on?.('exit', onExit)
-    child.on?.('error', (err) => {
-      clearTimeout(timer)
-      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
-    })
-  })
-  if (exitInfo.failed) {
-    logger?.warn?.(`maoying 创作台: self-update 失败(${exitInfo.kind}): ${exitInfo.message}`)
-    return { ok: false, kind: exitInfo.kind, message: exitInfo.message }
   }
 
-  // ── d) 成功后重读新版本 + 版本缓存失效 ───────────────────────────────────
-  const to = await readPkgVersion(pkgJsonPath, readImpl)
-  // 装的是磁盘上的新包，进程内 update-check 的 1h 缓存已是旧结论，立刻失效，
-  // 下次打开面板（重启后）按磁盘新版本重算 updateAvailable。
+  // ── e) 成功：版本缓存立刻失效（装的是磁盘新包，进程内 1h 缓存已是旧结论）。
+  //       to 取预检到的精确目标版本（退出码即成败信号，不做磁盘后验——本进程
+  //       代码不随升级变化，无从对账）。随后跑全局 CLI 阶段（方案 B：desktop
+  //       profile 与全局 npm 安装是两份独立拷贝，顺带更到同一精确版本）；全局
+  //       阶段失败不拖累整体——profile 已装好，重启照常生效，globalCli.ok:false
+  //       如实透出。
   invalidateVersionCache()
-  logger?.info?.(`maoying 创作台: self-update 完成 ${from ?? '?'} → ${to ?? '?'}（重启 DeepSeek 后生效）`)
-  return { ok: true, kind: 'installed', from, to, restartRequired: true }
+  logger?.info?.(`maoying 创作台: self-update 完成 ${current} → ${targetVersion}（重启 DeepSeek 后生效）`)
+  const globalCli = await updateGlobalCliStage({ targetVersion, profileDir }, globalDeps)
+  return { ok: true, kind: 'installed', from: current, to: targetVersion, restartRequired: true, globalCli }
 }
 
 // in-flight 去重：并发的 selfUpdate（连点按钮 / 双面板）复用同一次安装

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-maoying",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "毛颖 — DSH 网文创作辅助插件：主编 + 五帮手编排（大纲/写手/审校/设定/考据），novel/ 结构化文件为数据库",
   "type": "module",
   "license": "MIT",