@ljwei-stak/dsh-model-router 0.16.4 → 0.17.1

package/.dsh-plugin/shared/official-tools-runtime.mjs

@@ -1,19 +1,33 @@
 /**
  * Host-side probe and install runtime for the official tool registry.
  *
- * The DeepSeek Harness plugin host runs as a full Node module, so probing and
- * installing official CLIs uses node:child_process directly. Every command is
- * built exclusively from the fixed registry: callers supply a tool id, never
- * a package name, executable or argument. Installs are serialized (npm global
- * state must not interleave), output is kept as a bounded tail, and success is
- * always confirmed by a fresh probe rather than the installer's exit code.
- * When a newer release is known, a probe that is still older fails the job
- * instead of reporting success.
+ * The DeepSeek Harness plugin host runs as a full Node module, so probing,
+ * installing, uninstalling and repairing official CLIs uses node:child_process
+ * directly. Every command is built exclusively from the fixed registry plus the
+ * user's own Host-side settings: callers supply a tool id and one of that tool's
+ * declared method ids — never a package name, executable or argument. Installs
+ * are serialized (npm global state must not interleave), output is kept as a
+ * bounded tail, and success is always confirmed by a fresh probe rather than the
+ * installer's exit code. When a newer release is known, a probe that is still
+ * older fails the job instead of reporting success.
  */
 import { spawn } from 'node:child_process'
-import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
-import { isAbsolute, join, relative, sep } from 'node:path'
-import { getOfficialTool, installCommandLine, OFFICIAL_TOOLS } from './official-tool-registry.mjs'
+import { mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import {
+  defaultInstallMethod,
+  getOfficialTool,
+  installMethodFor,
+  installCommandLine,
+  OFFICIAL_TOOLS,
+} from './official-tool-registry.mjs'
+import {
+  minimaxScriptRegistry,
+  resolveInstallLocation,
+  resolveInstallPlan,
+  resolveUninstallPlan,
+} from './tool-install-preferences.mjs'
 import { discoverZCodeBundle, unverifiedZCodeInstalls } from './zcode-bundle.mjs'
 import { openZCodeInstaller } from './zcode-installer.mjs'
 import { compareReleaseVersions, latestVersions } from './latest-versions.mjs'
@@ -21,11 +35,14 @@ import { versionStillOlder } from './version-order.mjs'
 
 const PROBE_TIMEOUT_MS = 8_000
 const INSTALL_TIMEOUT_MS = 900_000
+const UNINSTALL_TIMEOUT_MS = 300_000
 const OUTPUT_LINE_CAP = 120
 const IS_WINDOWS = process.platform === 'win32'
 const CREATE_NO_WINDOW = 0x0800_0000
 const MINIMAX_INSTALLER_URL = 'https://filecdn.minimax.chat/public/install.ps1'
-const MAX_INSTALLER_BYTES = 200_000
+// Codex's Windows installer is already ~70KB and MiniMax's is ~57KB. 1MiB still
+// rejects an HTML error page or a substituted archive.
+const MAX_INSTALLER_BYTES = 1_048_576
 /** Windows ships where.exe in System32; POSIX which is ubiquitous. */
 const LOCATOR = IS_WINDOWS ? 'where' : 'which'
 /** Cached probe results keep plan generation fast; installs invalidate them. */
@@ -38,6 +55,32 @@ const CLAUDE_UPDATE_TIMEOUT_MS = 180_000
 /** Non-interactive updater for a native Claude Code install. npm does not move that copy. */
 export const CLAUDE_UPDATE_ARGS = Object.freeze(['update'])
 
+/**
+ * Host-side install preferences (install directory, npm source, per-tool method
+ * and script source). Refreshed from plugin config on every apply, so a client
+ * can only ever pick a method id — these addresses never arrive over the wire.
+ */
+let preferences = { installDir: '', registry: '', methods: {}, scriptUrls: {}, allowScriptInstall: true }
+
+export function setInstallPreferences(next) {
+  if (next && typeof next === 'object') {
+    const changedDirectory = preferences.installDir !== next.installDir
+    preferences = { ...preferences, ...next }
+    // A new directory needs its own PATH entry before the next probe runs.
+    if (changedDirectory) prefixPromise = null
+  }
+  return preferences
+}
+
+export function installPreferences() {
+  return { ...preferences }
+}
+
+/** The machine this Host runs on; the plan resolver needs both to be explicit. */
+export function currentInstallOptions() {
+  return { platform: process.platform, home: homedir() }
+}
+
 /**
  * Spawn shape for a fixed registry command.
  *
@@ -88,11 +131,16 @@ export function staleInstallMessage(label, installedVersion, latestVersion) {
  * Which updater to run. `order` is compareReleaseVersions(installed, latest):
  * -1 older, 0 same, 1 newer, null when either version is unknown.
  */
-export function officialUpdatePlan({ toolId, installed, order, platform }) {
+export function officialUpdatePlan({ toolId, installed, order, platform, methodId }) {
   if (installed && order === 1) return 'refuse-downgrade'
   if (installed && order === 0) return 'already-current'
   if (installed && order === -1 && toolId === 'claude-code') return 'claude-update-then-registry'
   if (installed && (order === -1 || order === null) && toolId === 'minimax-code' && platform === 'win32') {
+    // npm/pnpm is the method the user picked, so that command runs first. The
+    // official Windows installer stays the fallback when that copy does not
+    // advance, and it is the direct plan when no package manager was named
+    // (the historical one-click update of an official-layout install).
+    if (methodId === 'npm' || methodId === 'pnpm') return 'registry-install'
     return 'minimax-official-installer'
   }
   return 'registry-install'
@@ -197,20 +245,62 @@ function runCapture(executable, args, { timeoutMs, onOutput, useShell = false, s
   })
 }
 
+/**
+ * Decode installer bytes the way a terminal would. The MiniMax CDN serves the
+ * PowerShell script as `application/octet-stream` UTF-8; a UTF-16 copy (BOM or
+ * null-padded) is the same script and must not be rejected as a mismatch.
+ */
+export function installerScriptText(source) {
+  return decodeProcessOutput(Buffer.isBuffer(source) ? source : Buffer.from(source ?? '')).replace(/^\uFEFF/, '')
+}
+
+/**
+ * An HTML/XML document is not an installer. PowerShell comment-based help
+ * starts with `<#`, which is not a tag: the published MiniMax, Kimi and MiMo
+ * Windows scripts all open that way. Treating every leading `<` as HTML
+ * rejected those official scripts.
+ */
+export function isMarkupDocument(text) {
+  const head = String(text ?? '').replace(/^\uFEFF/, '').trimStart()
+  if (!head.startsWith('<')) return false
+  if (head.startsWith('<#')) return false
+  return /^<(?:!|\?|[A-Za-z])/.test(head)
+}
+
+const MINIMAX_INSTALLER_MARKERS = Object.freeze(['@minimax-ai/code', 'MCODE_INSTALL_DIR', 'MiniMax Code'])
+
 /**
  * MiniMax's official Windows installer script is run as published (it installs
- * `@minimax-ai/code@latest`). Only structural sanity is checked: it must be the
- * MiniMax Code installer, not an HTML error page or another script.
+ * `@minimax-ai/code@latest`). Structural checks only: the vendor's own markers,
+ * and a refusal of HTML/XML. Content-Type is not consulted — the CDN labels
+ * the real script `application/octet-stream`.
  */
 export function officialMiniMaxInstaller(source) {
-  const bytes = Buffer.isBuffer(source) ? source : Buffer.from(source)
-  const text = bytes.toString('utf8').replace(/^\uFEFF/, '')
-  if (!text.includes('@minimax-ai/code') || /^\s*</.test(text)) {
-    throw new Error('下载内容不是 MiniMax Code 官方 Windows 安装脚本，已拒绝执行。')
+  const text = installerScriptText(source)
+  if (!text.trim()) throw new Error('下载内容为空，已拒绝执行。')
+  if (isMarkupDocument(text)) {
+    throw new Error('下载内容不是 MiniMax Code 官方 Windows 安装脚本（收到 HTML 页面），已拒绝执行。')
+  }
+  const missing = MINIMAX_INSTALLER_MARKERS.filter(marker => !text.includes(marker))
+  if (missing.length) {
+    throw new Error(`下载内容不是 MiniMax Code 官方 Windows 安装脚本（缺少 ${missing.join('、')}），已拒绝执行。`)
   }
   return text
 }
 
+/**
+ * Directory the Windows installer must use. A configured path wins. Otherwise
+ * an already-installed official layout is updated in place. With neither, the
+ * vendor default is `%USERPROFILE%\.minimax-code` — not the npm prefix.
+ */
+export function minimaxOfficialInstallDir(preferences = {}, home = homedir(), existingRoot = '') {
+  const configured = String(preferences?.installDir ?? '').trim()
+  if (configured) return configured
+  const existing = String(existingRoot ?? '').trim()
+  if (existing) return existing
+  return join(home, '.minimax-code')
+}
+
 async function fetchOfficialMiniMaxInstaller(signal) {
   const response = await fetch(MINIMAX_INSTALLER_URL, {
     signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
@@ -226,30 +316,50 @@ async function fetchOfficialMiniMaxInstaller(signal) {
   return officialMiniMaxInstaller(Buffer.concat(chunks))
 }
 
+async function existingMiniMaxInstallRoot() {
+  const paths = (process.env.PATH ?? '').split(IS_WINDOWS ? ';' : ':').filter(Boolean)
+  const candidates = []
+  for (const directory of paths) candidates.push(directory, join(directory, '.minimax-code'))
+  candidates.push(join(homedir(), '.minimax-code'))
+  const seen = new Set()
+  for (const directory of candidates) {
+    const key = directory.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    try {
+      if (!(await stat(join(directory, 'mcode.cmd'))).isFile()) continue
+      if (!(await stat(join(directory, 'current'))).isFile()) continue
+      return await realpath(directory)
+    } catch { /* try the next candidate */ }
+  }
+  return ''
+}
+
 async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
   let staging = null
-  let prefixRoot = null
+  let stagingParent = null
   try {
     job.finishedAt = null
     job.error = null
     job.phase = 'downloading-and-verifying'
     pushLine(job, reason || '— npm 原生依赖未就绪；改用 MiniMax 官方 Windows 安装脚本（安装最新版）—')
-    const prefixResult = await runCapture('npm', ['config', 'get', 'prefix'], {
-      timeoutMs: 5_000, useShell: true, signal: job.controller.signal,
-    })
-    const rawPrefix = prefixResult.stdout.trim().replace(/^\\\\\?\\/, '')
-    if (!prefixResult.ok || !isAbsolute(rawPrefix)) throw new Error('无法确定 npm 全局安装目录。')
-    await mkdir(rawPrefix, { recursive: true })
-    prefixRoot = await realpath(rawPrefix)
+    const existingRoot = preferences.installDir ? '' : await existingMiniMaxInstallRoot()
+    const installDir = minimaxOfficialInstallDir(preferences, homedir(), existingRoot)
+    pushLine(job, preferences.installDir
+      ? `— 使用已配置的安装目录：${installDir} —`
+      : existingRoot
+        ? `— 未配置统一安装目录，沿用已安装的官方目录：${installDir} —`
+        : `— 未配置统一安装目录，使用 MiniMax 官方默认位置：${installDir} —`)
+    await mkdir(installDir, { recursive: true })
+    stagingParent = await realpath(installDir)
     const script = await fetchOfficialMiniMaxInstaller(job.controller.signal)
-    staging = await mkdtemp(join(prefixRoot, '.model-router-minimax-installer-'))
+    staging = await mkdtemp(join(stagingParent, '.model-router-minimax-installer-'))
     const scriptPath = join(staging, 'install.ps1')
     const tempPath = join(staging, 'temp')
     await mkdir(tempPath)
     // Windows PowerShell 5 reads a BOM-less .ps1 using the system ANSI page.
     // The upstream installer contains Unicode art, so write a UTF-8 BOM.
     await writeFile(scriptPath, `\uFEFF${script}`, 'utf8')
-    const installDir = join(prefixRoot, '.minimax-code')
     const powershell = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32',
       'WindowsPowerShell', 'v1.0', 'powershell.exe')
     const utilityModule = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32',
@@ -259,13 +369,17 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
       + 'Import-Module -Name $env:MODEL_ROUTER_UTILITY_MODULE -ErrorAction Stop; '
       + '& $env:MODEL_ROUTER_MINIMAX_INSTALL_SCRIPT'
     job.phase = 'installing'
+    const scriptRegistry = minimaxScriptRegistry(preferences.registry || 'https://registry.npmjs.org/')
+    if (!scriptRegistry && preferences.registry) {
+      pushLine(job, '— MiniMax 官方脚本不接受当前 npm 源，本次使用脚本自己的默认源 —')
+    }
     const outcome = await runCapture(powershell,
       ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', command], {
         timeoutMs: INSTALL_TIMEOUT_MS, signal: job.controller.signal,
         env: { ...process.env, MCODE_INSTALL_DIR: installDir,
-          MCODE_NO_MODIFY_PATH: '1', MCODE_DOWNLOAD_MIRROR: 'global',
-          MCODE_NPM_REGISTRY: 'https://registry.npmjs.org/',
-          npm_config_cache: join(prefixRoot, '.model-router-npm-cache'),
+          MCODE_NO_MODIFY_PATH: '1',
+          ...(scriptRegistry ? { MCODE_NPM_REGISTRY: scriptRegistry } : {}),
+          npm_config_cache: join(staging, 'npm-cache'),
           TEMP: tempPath, TMP: tempPath,
           MODEL_ROUTER_UTILITY_MODULE: utilityModule,
           MODEL_ROUTER_MINIMAX_INSTALL_SCRIPT: scriptPath },
@@ -279,8 +393,7 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
     if (!outcome.ok) throw new Error(outcome.timedOut
       ? '官方安装脚本超时并已终止。'
       : `官方安装脚本退出码 ${outcome.code ?? '信号终止'}。${outcome.stderr.split('\n').find(Boolean)?.slice(0, 180) ?? ''}`)
-    const currentPath = process.env.PATH ?? ''
-    if (!currentPath.split(';').includes(installDir)) process.env.PATH = `${currentPath};${installDir}`
+    appendToProcessPath(installDir)
     job.phase = 'verifying'
     probeCache.delete(job.tool.id)
     const probe = await probeToolWith(job.tool, defaultRunner)
@@ -302,17 +415,265 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
     job.error = `MiniMax 官方安装兜底失败：${String(error?.message ?? error).slice(0, 300)}`
     job.finishedAt = new Date().toISOString()
   } finally {
-    if (staging && prefixRoot) {
-      const part = relative(prefixRoot, staging)
-      if (part.startsWith('.model-router-minimax-installer-') && !part.includes(sep)) {
+    if (staging && stagingParent) {
+      const part = relative(stagingParent, staging)
+      if (part.startsWith('.model-router-minimax-installer-') && !part.includes(sep) && !part.startsWith('..')) {
         await rm(staging, { recursive: true, force: true }).catch(() => {})
       }
     }
   }
 }
 
+/**
+ * The downloaded bytes must still be the vendor script this registry entry
+ * names — never an HTML error page, never another vendor's installer that a
+ * mirror substituted. Markers are the same ones the vendor's own docs publish
+ * inside the script, so a mirror may rehost the file but not rewrite it into a
+ * different program.
+ */
+export function verifiedVendorScript(source, verify = {}) {
+  const text = installerScriptText(source)
+  if (!text.trim()) throw new Error('下载内容为空，已拒绝执行。')
+  if (isMarkupDocument(text)) throw new Error('下载内容不是安装脚本（收到 HTML 页面），已拒绝执行。')
+  // Check "wrong vendor" first: a mirror that substituted another installer is
+  // a different diagnosis from a truncated download, and the clearer one.
+  const foreign = (verify.mustNotInclude ?? []).filter(marker => text.includes(marker))
+  if (foreign.length) throw new Error('下载内容属于其他厂商的安装脚本，已拒绝执行。')
+  const missing = (verify.mustInclude ?? []).filter(marker => !text.includes(marker))
+  if (missing.length) {
+    throw new Error(`下载内容不是该厂商的官方安装脚本（缺少 ${missing.join('、')}），已拒绝执行。`)
+  }
+  return text
+}
+
+async function fetchVendorScript(url, signal) {
+  const response = await fetch(url, {
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+  })
+  if (!response.ok || !response.body) throw new Error(`官方脚本下载失败：HTTP ${response.status}`)
+  const chunks = []
+  let length = 0
+  for await (const chunk of response.body) {
+    length += chunk.length
+    if (length > MAX_INSTALLER_BYTES) throw new Error('官方安装脚本超过大小上限。')
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+const POWERSHELL = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32',
+  'WindowsPowerShell', 'v1.0', 'powershell.exe')
+
+/** argv that runs one staged vendor script; no remote content ever reaches the interpreter. */
+export function vendorScriptInvocation(plan, scriptPath) {
+  // `installArg` is the vendor's own single flag (`--install-dir` / `-InstallDir`).
+  const directoryArgs = plan.installArg?.[0] && plan.installDir ? [plan.installArg[0], plan.installDir] : []
+  if (plan.shell === 'powershell') {
+    return {
+      file: POWERSHELL,
+      args: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...directoryArgs],
+    }
+  }
+  return { file: 'bash', args: [scriptPath, ...directoryArgs] }
+}
+
+/**
+ * Install one tool from its vendor script: download, verify, stage, run the
+ * staged copy. The binary lands in a directory the plugin appends to its own
+ * PATH, so the fresh probe below sees the copy this job just installed rather
+ * than an older one that happened to be on PATH first.
+ */
+async function runVendorScriptInstallJob(job, plan) {
+  let staging = null
+  try {
+    job.phase = 'downloading-and-verifying'
+    for (const notice of plan.notices ?? []) pushLine(job, notice)
+    pushLine(job, `— 下载官方安装脚本：${plan.scriptUrl}`)
+    const source = verifiedVendorScript(await fetchVendorScript(plan.scriptUrl, job.controller.signal), plan.verify)
+    staging = await mkdtemp(join(tmpdir(), '.model-router-tool-install-'))
+    const isPowerShell = plan.shell === 'powershell'
+    const scriptPath = join(staging, isPowerShell ? 'install.ps1' : 'install.sh')
+    // Windows PowerShell 5 reads a BOM-less .ps1 using the system ANSI page;
+    // both vendor scripts contain non-ASCII text, so write a UTF-8 BOM.
+    await writeFile(scriptPath, isPowerShell ? `\uFEFF${source}` : source, 'utf8')
+    const invocation = vendorScriptInvocation(plan, scriptPath)
+    job.phase = 'installing'
+    pushLine(job, `$ ${plan.label}${invocation.args.length > 1 ? ` ${invocation.args.slice(1).join(' ')}` : ''}`)
+    const outcome = await runCapture(invocation.file, invocation.args, {
+      timeoutMs: INSTALL_TIMEOUT_MS,
+      signal: job.controller.signal,
+      env: { ...process.env, ...plan.env },
+      onOutput: captureLines(job),
+    })
+    if (outcome.cancelled || job.cancelRequested) { markCancelled(job); return }
+    job.exitCode = outcome.code
+    job.timedOut = outcome.timedOut
+    if (!outcome.ok) {
+      throw new Error(outcome.timedOut ? '官方安装脚本超时并已终止。'
+        : `官方安装脚本退出码 ${outcome.code ?? '信号终止'}。${String(outcome.stderr ?? '').split('\n').find(Boolean)?.slice(0, 200) ?? ''}`)
+    }
+    const location = resolveInstallLocation(job.tool, plan.method, preferences, currentInstallOptions())
+    if (location?.dir) {
+      appendToProcessPath(location.dir)
+      for (const relative of location.relatives ?? []) {
+        const folder = String(relative).split(/[\\/]/).slice(0, -1).filter(Boolean).join(sep)
+        if (folder) appendToProcessPath(join(location.dir, folder))
+      }
+    }
+    job.phase = 'verifying'
+    probeCache.delete(job.tool.id)
+    const probe = await probeToolWith(job.tool, defaultRunner, { cacheMs: 0 })
+    job.postInstallProbe = probe
+    if (!probe.installed) {
+      throw new Error(`官方安装脚本已完成，但 PATH 上仍找不到 ${job.tool.probeExecutables?.[0] ?? job.tool.label}：${probe.detail}`)
+    }
+    const latest = await latestVersions.lookup(job.tool).catch(() => null)
+    if (latest?.version && versionStillOlder(probe.version, latest.version)) {
+      throw new Error(staleInstallMessage(job.tool.label, probe.version, latest.version))
+    }
+    job.status = 'succeeded'
+    job.finishedAt = new Date().toISOString()
+    pushLine(job, `— 已通过 ${plan.label} 安装 ${job.tool.label} ${probe.version ?? ''} —`)
+  } catch (error) {
+    if (job.cancelRequested || job.controller.signal.aborted) { markCancelled(job); return }
+    job.status = 'failed'
+    job.error = `${job.tool.label} 安装失败：${String(error?.message ?? error).slice(0, 300)}`
+    job.finishedAt = new Date().toISOString()
+  } finally {
+    if (staging) await rm(staging, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Guard rail for the one destructive operation: deleting a vendor binary. Every
+ * part of the path came from the fixed registry and the user's own settings,
+ * and this re-checks all of it — the basename must be one the registry names,
+ * the file must sit inside that tool's install directory, and it can never be a
+ * home directory or a filesystem root.
+ */
+/** One relative path under an install directory. `..` never leaves that directory. */
+export function scriptBinaryCandidate(installDir, relative) {
+  const parts = String(relative ?? '').split(/[\\/]/).filter(Boolean)
+  if (parts.length === 0 || parts.some(part => part === '.' || part === '..')) {
+    throw new Error('拒绝删除安装目录之外的文件。')
+  }
+  return join(installDir, ...parts)
+}
+
+export function checkedRemovableFile(candidate, { allowedNames, installDir, home = homedir() }) {
+  const target = resolve(candidate)
+  const base = target.split(sep).pop() ?? ''
+  if (!allowedNames.includes(base)) throw new Error(`拒绝删除 ${base}：不在该工具的固定可执行文件名列表中。`)
+  if (target === resolve(home) || target === resolve(target, '..')) {
+    throw new Error('拒绝删除用户主目录或文件系统根目录。')
+  }
+  if (installDir && !isInsideDirectory(installDir, target)) {
+    throw new Error(`拒绝删除 ${target}：不在该工具的安装目录 ${installDir} 内。`)
+  }
+  return target
+}
+
+function isInsideDirectory(parent, child) {
+  const canonical = resolve(parent)
+  return child === canonical || child.startsWith(canonical.endsWith(sep) ? canonical : `${canonical}${sep}`)
+}
+
+/**
+ * Remove one tool. Package-manager installs go back through the same manager;
+ * script installs delete the executable the vendor script placed, and only that
+ * file — the vendor's config, credentials and session history stay, so a
+ * reinstall keeps the user's login.
+ */
+async function runVendorScriptUninstallJob(job, plan) {
+  try {
+    job.phase = 'removing'
+    const location = resolveInstallLocation(job.tool, plan.method, preferences, currentInstallOptions())
+    const removed = []
+    const relatives = location?.relatives?.length ? location.relatives : (location?.binaries ?? [])
+    for (const relative of relatives) {
+      const candidate = scriptBinaryCandidate(location.dir, relative)
+      // checkedRemovableFile re-checks the basename, the install directory and
+      // the root/home guards even though every part came from the registry.
+      const target = checkedRemovableFile(candidate, {
+        allowedNames: location.binaries, installDir: location.dir, home: homedir(),
+      })
+      if (!(await stat(target).catch(() => null))?.isFile()) continue
+      await rm(target, { force: true })
+      removed.push(target)
+    }
+    const stripped = await stripPathProfileBlocks(job.tool).catch(error => `（未能清理 PATH 配置：${String(error?.message ?? error).slice(0, 120)}）`)
+    if (removed.length === 0) {
+      throw new Error(`在 ${location?.dir || '安装目录'} 下没有找到 ${job.tool.label} 的可执行文件；它可能是用包管理器安装的，请改用该方式卸载。`)
+    }
+    for (const path of removed) pushLine(job, `已删除 ${path}`)
+    if (stripped.length) pushLine(job, `已清理 shell 配置中的 PATH 记录：${stripped.join('、')}`)
+    pushLine(job, `已保留 ${job.tool.label} 的配置与登录信息（${homedir()}/${String(job.tool.defaultScriptInstallDir ?? '').split('/')[0]}）。`)
+    job.phase = 'verifying'
+    probeCache.delete(job.tool.id)
+    const probe = await probeToolWith(job.tool, defaultRunner, { cacheMs: 0 })
+    job.postInstallProbe = probe
+    job.status = 'succeeded'
+    job.finishedAt = new Date().toISOString()
+    job.error = probe.installed
+      ? `已删除本次安装的可执行文件，但 PATH 上仍有另一份 ${job.tool.label}，请检查其他安装来源。`
+      : null
+  } catch (error) {
+    if (job.cancelRequested || job.controller.signal.aborted) { markCancelled(job); return }
+    job.status = 'failed'
+    job.error = `${job.tool.label} 卸载失败：${String(error?.message ?? error).slice(0, 300)}`
+    job.finishedAt = new Date().toISOString()
+  }
+}
+
+/**
+ * Remove the vendor installer's own marked block from the shell profiles it
+ * writes. Only a well-formed `# stepcode … # stepcode end` block is removed; a
+ * bare mention is left alone, exactly as the vendor's installer decides.
+ */
+export function stripPathBlock(content, marker) {
+  const text = String(content ?? '')
+  if (!text.includes(marker)) return null
+  const lines = text.split(/\r?\n/)
+  const kept = []
+  let removed = 0
+  let inside = false
+  for (const line of lines) {
+    if (!inside && line.trim() === marker) { inside = true; removed += 1; continue }
+    if (inside) {
+      removed += 1
+      if (line.trim() === `${marker} end`) inside = false
+      continue
+    }
+    kept.push(line)
+  }
+  return removed > 0 ? kept.join('\n') : null
+}
+
+const SHELL_PROFILES = ['.bashrc', '.bash_profile', '.zshrc', '.profile']
+
+async function stripPathProfileBlocks(tool) {
+  const markers = tool?.pathProfileMarkers ?? []
+  if (markers.length === 0) return []
+  const touched = []
+  for (const profile of SHELL_PROFILES) {
+    const path = join(homedir(), profile)
+    let content
+    try { content = await readFile(path, 'utf8') } catch { continue }
+    let next = content
+    for (const marker of markers) next = stripPathBlock(next, marker) ?? next
+    if (next === content) continue
+    const temporary = `${path}.model-router-${process.pid}.tmp`
+    await writeFile(temporary, next, 'utf8')
+    await rename(temporary, path)
+    touched.push(profile)
+  }
+  return touched
+}
+
 /** Tools whose ready-check failure can be repaired by reinstalling the same version. */
-const CAPABILITY_REPAIRABLE = new Set(['claude-code', 'codex', 'kimi-code', 'minimax-code', 'mimo-code', 'grok-build'])
+const CAPABILITY_REPAIRABLE = new Set([
+  'claude-code', 'codex', 'kimi-code', 'minimax-code', 'mimo-code', 'grok-build', 'opencode', 'stepcode',
+])
 
 /** Extract the first version-looking token from a CLI banner. */
 export function versionFromBanner(banner) {
@@ -351,9 +712,18 @@ async function probeUncached(tool, runner) {
   if (tool.id === 'minimax-code' && IS_WINDOWS) {
     // The official Windows installer keeps mcode under a versioned releases
     // directory. A partial npm install can leave a broken shim earlier on PATH;
-    // prefer the checksum-verified installer release in that case.
+    // prefer the checksum-verified installer release in that case. Also look at
+    // the configured directory and the vendor default, which may not be on PATH
+    // yet when the installer was told not to edit the user PATH.
     const { findManagedMiniMaxEntry } = await import('./official-tool-executor.mjs')
-    const managed = await findManagedMiniMaxEntry(process.cwd())
+    const directed = minimaxOfficialInstallDir(preferences, homedir())
+    // The configured directory is the copy updates write, so it wins over an
+    // older install that happens to sit earlier on PATH.
+    let managed = preferences.installDir
+      ? await findManagedMiniMaxEntry(process.cwd(), [directed, join(directed, '.minimax-code')])
+      : null
+    if (!managed) managed = await findManagedMiniMaxEntry(process.cwd())
+    if (!managed) managed = await findManagedMiniMaxEntry(process.cwd(), [directed, join(directed, '.minimax-code')])
     if (managed) return { id: tool.id, installed: true, version: managed.version,
       status: 'installed', detail: '已按官方 npm registry 摘要核验 MiniMax 官方 Windows 安装器中的 CLI 文件。',
       bannerLine: `MiniMax Code ${managed.version}` }
@@ -412,12 +782,27 @@ export const defaultRunner = (executable, args, options = {}) =>
 
 let prefixPromise = null
 
+/** Add one directory to this process's PATH unless it is already there. */
+function appendToProcessPath(directory, { includeBin = true } = {}) {
+  const target = String(directory ?? '').trim()
+  if (!target || !isAbsolute(target)) return
+  const separator = IS_WINDOWS ? ';' : ':'
+  const current = process.env.PATH ?? ''
+  if (!current.split(separator).some(entry => entry.toLowerCase() === target.toLowerCase())) {
+    process.env.PATH = current ? `${current}${separator}${target}` : target
+  }
+  // POSIX package managers put global binaries in <prefix>/bin. One level only:
+  // recursing would append bin/bin/bin until the process runs out of memory.
+  if (includeBin && !IS_WINDOWS) appendToProcessPath(join(target, 'bin'), { includeBin: false })
+}
+
 /**
  * Users frequently move the npm global prefix off the default location (for
  * example to save C-drive space), so globally installed CLIs are missing from
- * PATH. Resolve the real prefix once and append it to this process's PATH so
- * probes and installs see the user's actual tools. Best effort: any failure
- * leaves the environment untouched.
+ * PATH. Resolve the real prefix once and append it — plus the directory the
+ * user configured for this plugin — to this process's PATH so probes and
+ * installs see the user's actual tools. Best effort: any failure leaves the
+ * environment untouched.
  */
 export function ensureNpmPrefixOnPath() {
   if (prefixPromise === null) {
@@ -437,10 +822,19 @@ export function ensureNpmPrefixOnPath() {
           // the same non-C drive as this user's npm global prefix.
           process.env.GROK_HOME = join(prefix, '.model-router-grok')
         }
-        const current = process.env.PATH ?? ''
-        if (current.split(IS_WINDOWS ? ';' : ':').includes(prefix)) return
-        process.env.PATH = current ? `${current}${IS_WINDOWS ? ';' : ':'}${prefix}` : prefix
+        appendToProcessPath(prefix)
       } catch { /* environment stays untouched */ }
+      // A --prefix install lands outside the npm prefix, so it needs its own
+      // PATH entry or every later probe reports the tool as missing.
+      try { appendToProcessPath(preferences.installDir) } catch { /* environment stays untouched */ }
+      // Vendor script defaults, so a one-click install that did not edit the
+      // user PATH is still visible to the next probe in this process.
+      for (const relative of [
+        '.minimax-code', '.local/bin', '.kimi-code/bin', '.grok/bin', '.mimocode/bin',
+        '.opencode/bin', '.stepcode/bin', 'AppData/Local/Programs/OpenAI/Codex/bin',
+      ]) {
+        try { appendToProcessPath(join(homedir(), ...relative.split('/'))) } catch { /* skip */ }
+      }
     })()
   }
   return prefixPromise
@@ -490,6 +884,9 @@ function jobView(job) {
   if (!job) return null
   return {
     tool: job.tool.id,
+    operation: job.operation,
+    methodId: job.methodId,
+    installDir: job.installDir,
     command: job.command,
     status: job.status,
     phase: job.phase,
@@ -513,23 +910,16 @@ function pushLine(job, line) {
   job.outputTail.push(line)
 }
 
-/**
- * Start the fixed install for one registry tool id. Returns the job snapshot
- * synchronously; poll installStatus until status is succeeded/failed.
- */
-export function startInstall(toolId) {
-  const tool = getOfficialTool(toolId)
-  if (!tool) throw new Error(`未知工具：${toolId}。只允许安装注册表中的官方工具。`)
-  if (tool.unsupported) throw new Error(tool.unsupportedReason)
+/** Reserve the single per-tool job slot and serialise against every other tool. */
+function beginJob(tool, { operation, methodId, command, installDir = '', run }) {
   const existing = installJobs.get(tool.id)
-  if (existing?.status === 'running') throw new Error(`${tool.label} 已有安装任务正在执行。`)
-  const command = installCommandLine(tool)
-  if (!command) throw new Error(tool.unsupportedReason)
-  // With shell mode on Windows the bare name resolves npm.cmd/uv.exe.
-  const manager = tool.manager === 'npm' ? 'npm' : tool.manager === 'signed-windows-installer' ? 'signed-windows-installer' : 'uv'
+  if (existing?.status === 'running') throw new Error(`${tool.label} 已有${operation === 'uninstall' ? '卸载' : '安装'}任务正在执行。`)
   const job = {
     tool,
+    operation,
+    methodId,
     command,
+    installDir,
     status: 'running',
     phase: 'queued',
     cancelRequested: false,
@@ -545,16 +935,145 @@ export function startInstall(toolId) {
   }
   installJobs.set(tool.id, job)
   probeCache.delete(tool.id)
-  installChain = installChain.then(() => manager === 'signed-windows-installer'
-    ? runZCodeInstallJob(job) : runInstallJob(manager, tool.installArgs, job)).catch(error => {
-    if (job.status === 'cancelled') return
+  installChain = installChain.then(() => run(job)).catch(error => {
+    if (job.status !== 'running') return
     job.status = 'failed'
     job.finishedAt = new Date().toISOString()
-    job.error = `安装流程失败：${String(error?.message ?? error).slice(0, 200)}`
+    job.error = `${operation === 'uninstall' ? '卸载' : '安装'}流程失败：${String(error?.message ?? error).slice(0, 200)}`
   })
   return jobView(job)
 }
 
+/** One-line summary of a resolved plan, for the job log and the UI. */
+export function planCommandLine(plan, operation = 'install') {
+  if (plan.kind === 'script') {
+    const piped = plan.shell === 'powershell' ? `irm ${plan.scriptUrl} | iex` : `curl -fsSL ${plan.scriptUrl} | bash`
+    if (operation === 'uninstall') {
+      return `删除 ${plan.dir} 下的 ${(plan.binaries ?? []).join('、') || '可执行文件'}`
+    }
+    if (plan.installDir && plan.installArg?.[0]) return `${piped} ${plan.installArg[0]} ${plan.installDir}`
+    if (plan.installDir && plan.installDirEnv) return `${piped}（${plan.installDirEnv}=${plan.installDir}）`
+    return piped
+  }
+  return `${plan.manager} ${plan.args.join(' ')}`
+}
+
+/**
+ * Start the fixed install for one registry tool id. `method` names one of that
+ * tool's declared install methods; the default comes from the user's settings
+ * and then from the registry. Returns the job snapshot synchronously; poll
+ * installStatus until status is succeeded/failed.
+ */
+export function startInstall(toolId, { method } = {}) {
+  const tool = getOfficialTool(toolId)
+  if (!tool) throw new Error(`未知工具：${toolId}。只允许安装注册表中的官方工具。`)
+  if (tool.unsupported) throw new Error(tool.unsupportedReason)
+  if (tool.manager === 'signed-windows-installer') {
+    const command = installCommandLine(tool)
+    if (!command) throw new Error(tool.unsupportedReason)
+    return beginJob(tool, { operation: 'install', methodId: 'signed-windows-installer', command, run: runZCodeInstallJob })
+  }
+  const plan = resolveInstallPlan(tool, method, preferences, currentInstallOptions())
+  return beginJob(tool, {
+    operation: 'install',
+    methodId: plan.methodId,
+    command: planCommandLine(plan),
+    installDir: plan.installDir ?? '',
+    run: job => (plan.kind === 'script'
+      ? runVendorScriptInstallJob(job, plan)
+      : runInstallJob(plan.manager, plan.args, job)),
+  })
+}
+
+/** Reinstall the tool even when it is already the latest release. */
+export function startRepair(toolId, { method } = {}) {
+  const tool = getOfficialTool(toolId)
+  if (!tool) throw new Error(`未知工具：${toolId}。`)
+  if (tool.manager === 'signed-windows-installer') {
+    return beginJob(tool, {
+      operation: 'repair', methodId: 'signed-windows-installer',
+      command: installCommandLine(tool), run: runZCodeInstallJob,
+    })
+  }
+  const plan = resolveInstallPlan(tool, method, preferences, currentInstallOptions())
+  return beginJob(tool, {
+    operation: 'repair',
+    methodId: plan.methodId,
+    command: `修复：${planCommandLine(plan)}`,
+    installDir: plan.installDir ?? '',
+    run: async job => {
+      job.repair = true
+      if (plan.kind === 'script') return runVendorScriptInstallJob(job, plan)
+      return runInstallJob(plan.manager, plan.args, job)
+    },
+  })
+}
+
+/**
+ * Remove one tool: through its package manager, or by deleting the single file
+ * the vendor installer placed. Configuration and credentials are never touched.
+ */
+export function startUninstall(toolId, { method } = {}) {
+  const tool = getOfficialTool(toolId)
+  if (!tool) throw new Error(`未知工具：${toolId}。只允许卸载注册表中的官方工具。`)
+  const plan = resolveUninstallPlan(tool, method, preferences, currentInstallOptions())
+  return beginJob(tool, {
+    operation: 'uninstall',
+    methodId: plan.methodId,
+    command: planCommandLine(plan, 'uninstall'),
+    installDir: plan.dir ?? plan.installDir ?? '',
+    run: job => (plan.kind === 'script'
+      ? runVendorScriptUninstallJob(job, plan)
+      : runPackageManagerUninstallJob(job, plan)),
+  })
+}
+
+async function runPackageManagerUninstallJob(job, plan) {
+  try {
+    job.phase = 'preflight'
+    await ensureNpmPrefixOnPath()
+    const before = await probeToolWith(job.tool, defaultRunner)
+    if (job.cancelRequested) { markCancelled(job); return }
+    if (!before.installed) {
+      job.status = 'succeeded'
+      job.finishedAt = new Date().toISOString()
+      job.postInstallProbe = before
+      pushLine(job, `— ${job.tool.label} 本就未安装，无需卸载 —`)
+      return
+    }
+    job.phase = 'uninstalling'
+    const outcome = await runCapture(plan.manager, plan.args, {
+      timeoutMs: UNINSTALL_TIMEOUT_MS,
+      useShell: IS_WINDOWS,
+      signal: job.controller.signal,
+      onOutput: captureLines(job),
+    })
+    if (outcome.cancelled || job.cancelRequested) { markCancelled(job); return }
+    job.exitCode = outcome.code
+    job.timedOut = outcome.timedOut
+    if (!outcome.ok) {
+      throw new Error(outcome.timedOut ? '卸载超时并已终止。'
+        : `卸载命令失败（退出码 ${outcome.code ?? '信号终止'}）。${String(outcome.stderr ?? '').split('\n').find(Boolean)?.slice(0, 200) ?? ''}`)
+    }
+    job.phase = 'verifying'
+    probeCache.delete(job.tool.id)
+    const probe = await probeToolWith(job.tool, defaultRunner, { cacheMs: 0 })
+    job.postInstallProbe = probe
+    job.status = 'succeeded'
+    job.finishedAt = new Date().toISOString()
+    if (probe.installed) {
+      job.error = `${plan.manager} 已卸载 ${job.tool.label}，但 PATH 上仍有另一份；请检查其他安装来源。`
+    } else {
+      pushLine(job, `— 已卸载 ${job.tool.label}，PATH 上已找不到 ${job.tool.probeExecutables?.[0] ?? ''} —`)
+    }
+  } catch (error) {
+    if (job.cancelRequested || job.controller.signal.aborted) { markCancelled(job); return }
+    job.status = 'failed'
+    job.error = `${job.tool.label} 卸载失败：${String(error?.message ?? error).slice(0, 300)}`
+    job.finishedAt = new Date().toISOString()
+  }
+}
+
 function captureLines(job) {
   return chunk => {
     for (const line of String(chunk).split(/\r?\n/)) {
@@ -659,14 +1178,20 @@ async function runInstallJob(manager, args, job) {
     if (order === 0) {
       const readiness = await trustedExecutionReadiness(job.tool.id)
       if (job.cancelRequested) { markCancelled(job); return }
-      if (readiness.ready || !CAPABILITY_REPAIRABLE.has(job.tool.id)) {
+      // A repair re-runs the same command even when nothing looks stale: a
+      // broken install reports the right version, so "already current" is
+      // exactly the case the user pressed 修复 for.
+      if (job.repair) {
+        pushLine(job, `— ${job.tool.label} ${before.version} 已是最新版本，按修复流程重新安装 —`)
+      } else if (readiness.ready || !CAPABILITY_REPAIRABLE.has(job.tool.id)) {
         job.status = 'succeeded'
         job.finishedAt = new Date().toISOString()
         job.postInstallProbe = before
         pushLine(job, `— ${job.tool.label} ${before.version} 已是最新版本，无需重复安装 —`)
         return
+      } else {
+        pushLine(job, `— 已是最新版本 ${before.version}，但执行入口未就绪：${readiness.reason}；重新安装修复 —`)
       }
-      pushLine(job, `— 已是最新版本 ${before.version}，但执行入口未就绪：${readiness.reason}；重新安装修复 —`)
     }
   }
   const plan = officialUpdatePlan({
@@ -674,6 +1199,7 @@ async function runInstallJob(manager, args, job) {
     installed: before.installed === true,
     order,
     platform: process.platform,
+    methodId: job.methodId,
   })
   let triedClaudeUpdate = false
   if (plan === 'claude-update-then-registry') {
@@ -792,12 +1318,15 @@ async function runZCodeInstallJob(job) {
 }
 
 function markCancelled(job) {
+  const uninstalling = job.operation === 'uninstall'
   job.status = 'cancelled'
   job.phase = 'done'
   job.finishedAt = new Date().toISOString()
-  job.error = '已取消安装。若 npm 已开始写入，可能需要重新检测或修复该工具。'
+  job.error = uninstalling
+    ? '已取消卸载。若删除已经开始，请重新检测实际状态。'
+    : '已取消安装。若包管理器已开始写入，可能需要重新检测或修复该工具。'
   probeCache.delete(job.tool.id)
-  pushLine(job, '— 安装已取消；请重新检测实际状态 —')
+  pushLine(job, uninstalling ? '— 卸载已取消；请重新检测实际状态 —' : '— 安装已取消；请重新检测实际状态 —')
 }
 
 /** Cancel a queued or running install; cancellation is reflected after its process exits. */
@@ -843,9 +1372,11 @@ export async function executionChannels(providers) {
   return resolved
 }
 
-/** Test-only: drop caches and jobs. */
+/** Test-only: drop caches, jobs and any preferences a previous test left behind. */
 export function resetForTests() {
   probeCache.clear()
   installJobs.clear()
   installChain = Promise.resolve()
+  prefixPromise = null
+  preferences = { installDir: '', registry: '', methods: {}, scriptUrls: {}, allowScriptInstall: true }
 }