@ljwei-stak/dsh-model-router 0.18.1 → 0.19.0

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

@@ -26,6 +26,7 @@ import {
 import {
   expandInstallDir,
   resolveInstallLocation,
+  resolveLegacyScriptLocation,
   resolveInstallPlan,
   resolveUninstallPlan,
 } from './tool-install-preferences.mjs'
@@ -59,7 +60,7 @@ export const CLAUDE_UPDATE_ARGS = Object.freeze(['update'])
  * and script source). Refreshed on apply and live config updates, 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 }
+let preferences = { installDir: '', registry: '', methods: {}, scriptUrls: {}, allowScriptInstall: true, zcodeInstallDir: '' }
 
 export function setInstallPreferences(next) {
   if (next && typeof next === 'object') {
@@ -308,16 +309,22 @@ async function fetchOfficialMiniMaxInstaller(signal) {
 }
 
 export function minimaxOfficialInstallDir(selectedPreferences = {}, home = homedir(), existingRoot = '') {
-  return selectedPreferences.installDir || existingRoot || join(home, '.minimax-code')
+  return selectedPreferences.installDir
+    ? resolveInstallPlan(getOfficialTool('minimax-code'), 'script-powershell', selectedPreferences, { platform: 'win32', home }).installDir
+    : existingRoot || join(home, '.minimax-code')
 }
 
 /** Keep a discovered native installation in place when its legacy updater runs. */
 export function miniMaxFallbackPlan(selectedPreferences, beforeProbe, prefix, options = currentInstallOptions()) {
   const installDir = minimaxOfficialInstallDir(selectedPreferences, options.home,
     beforeProbe?.installed ? beforeProbe.installDir : '')
-  const executionPreferences = { ...selectedPreferences, installDir,
+  const executionPreferences = { ...selectedPreferences,
     methods: { ...selectedPreferences.methods, 'minimax-code': 'script-powershell' } }
-  return { plan: resolveInstallPlan(getOfficialTool('minimax-code'), 'script-powershell', executionPreferences, options), executionPreferences }
+  const plan = resolveInstallPlan(getOfficialTool('minimax-code'), 'script-powershell', selectedPreferences, options)
+  // installDir is already the discovered exclusive native root or the resolved
+  // child of the configured base. Never reinterpret it as another shared base.
+  return { plan: { ...plan, installDir, binDir: installDir,
+    env: { ...plan.env, MCODE_INSTALL_DIR: installDir } }, executionPreferences }
 }
 
 async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
@@ -330,6 +337,7 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
     pushLine(job, reason || '— npm 原生依赖未就绪；改用 MiniMax 官方 Windows 安装脚本（安装最新版）—')
     const { plan, executionPreferences } = miniMaxFallbackPlan(job.preferences, job.beforeProbe, '')
     const installDir = plan.installDir
+    await assertVendorInstallDirectory(job.tool, plan, job.preferences)
     await mkdir(installDir, { recursive: true })
     prefixRoot = await realpath(installDir)
     const script = await fetchOfficialMiniMaxInstaller(job.controller.signal)
@@ -354,6 +362,7 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
       + 'Import-Module -Name $env:MODEL_ROUTER_UTILITY_MODULE -ErrorAction Stop; '
       + '& $env:MODEL_ROUTER_MINIMAX_INSTALL_SCRIPT'
     job.phase = 'installing'
+    await assertVendorInstallDirectory(job.tool, plan, job.preferences)
     const outcome = await runCapture(powershell,
       ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', command], {
         timeoutMs: INSTALL_TIMEOUT_MS, signal: job.controller.signal,
@@ -378,7 +387,7 @@ async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
     probeCache.delete(job.tool.id)
     const probe = await probeToolWith(job.tool, defaultRunner, { preferences: executionPreferences, plan, cacheMs: 0 })
     job.postInstallProbe = probe
-    const readiness = await trustedExecutionReadiness(job.tool.id, { preferences: executionPreferences })
+    const readiness = await trustedExecutionReadiness(job.tool.id, { preferences: executionPreferences, plan })
     if (!probe.installed || !readiness.ready) {
       throw new Error(`官方安装器完成，但执行入口未通过 npm registry 摘要核验：${readiness.reason ?? probe.detail}`)
     }
@@ -516,6 +525,95 @@ export function vendorScriptInvocation(plan, scriptPath) {
   return { file: plan.shell === 'sh' ? 'sh' : 'bash', args: [scriptPath, ...directoryArgs] }
 }
 
+/** Resolve an existing ancestor too, so a missing child under a junction is checked. */
+async function canonicalInstallPath(path) {
+  let current = resolve(path)
+  const suffix = []
+  for (;;) {
+    try { return join(await realpath(current), ...suffix) }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error
+      const parent = dirname(current)
+      if (parent === current) throw error
+      suffix.unshift(current.slice(parent.length).replace(/^[\\/]+/, ''))
+      current = parent
+    }
+  }
+}
+
+/** A vendor owns its target; its cleanup must never touch a shared npm prefix. */
+export async function assertVendorInstallDirectory(tool, plan, selectedPreferences = {}, options = currentInstallOptions()) {
+  const directory = plan.installDir || plan.binDir
+  if (!directory) throw new Error('官方脚本安装目录无法确定，已停止安装。')
+  const canonical = await canonicalInstallPath(directory)
+  if (canonical.split(/[\\/]+/).some(part => ['node_modules', '.pnpm'].includes(part.toLowerCase()))) {
+    throw new Error('官方脚本不能写入 npm/pnpm 的包目录或共享存储目录。')
+  }
+  if (canonical === dirname(canonical) || canonical === await canonicalInstallPath(homedir())) {
+    throw new Error('官方脚本不能在磁盘根目录或用户主目录中执行。')
+  }
+  let codexOwnedRelease = false
+  if (tool.id === 'codex' && plan.shell === 'powershell') {
+    // The official Windows script keeps releases under the user's existing
+    // CODEX_HOME. CODEX_INSTALL_DIR selects only the visible bin junction.
+    // Respect that documented layout without redirecting the user's config.
+    const codexHome = options.env?.CODEX_HOME || join(options.home || homedir(), '.codex')
+    const homeRoot = await canonicalInstallPath(codexHome)
+    const releases = join(homeRoot, 'packages', 'standalone', 'releases')
+    const member = relative(releases, canonical)
+    const expectedVisible = !selectedPreferences.installDir || resolve(directory) === resolve(join(selectedPreferences.installDir, plan.method.installDirSubdir))
+    codexOwnedRelease = Boolean(expectedVisible && member && member !== '..' && !member.startsWith(`..${sep}`) && !isAbsolute(member))
+  }
+  if (selectedPreferences.installDir && plan.method?.supportsInstallDir) {
+    const base = await canonicalInstallPath(selectedPreferences.installDir)
+    const child = relative(base, canonical)
+    if (!codexOwnedRelease && (!child || child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child))) {
+      throw new Error('官方脚本必须使用统一安装根目录下的工具专属子目录；已拒绝覆盖共享目录。')
+    }
+    const owner = plan.method.installDirSubdir?.split(/[\\/]+/)[0]
+    const ownedRoot = owner ? join(base, owner) : null
+    const ownedChild = ownedRoot ? relative(ownedRoot, canonical) : '..'
+    if (!codexOwnedRelease && (ownedChild === '..' || ownedChild.startsWith(`..${sep}`) || isAbsolute(ownedChild))) {
+      throw new Error('官方脚本的目录联接必须留在本工具专属目录中，不能指向其他工具。')
+    }
+  }
+  // These fixed/default bin installers replace only their own launcher, not
+  // another CLI's runtime directory. Sharing ~/.local/bin is intentional.
+  if (plan.method?.sharedDefaultBin && (!selectedPreferences.installDir || !plan.method.supportsInstallDir)) return
+  const targetStat = await stat(directory).catch(error => {
+    if (error.code === 'ENOENT') return null
+    throw error
+  })
+  if (targetStat && !targetStat.isDirectory()) throw new Error('官方脚本安装目标不是目录。')
+  const packageText = await readFile(join(directory, 'package.json'), 'utf8').catch(error => {
+    if (error.code === 'ENOENT') return null
+    throw error
+  })
+  if (packageText) {
+    let name
+    try { name = JSON.parse(packageText).name } catch { throw new Error('安装目录已有无法核验归属的 package.json，已停止运行官方脚本。') }
+    const ownPackage = tool.package || (tool.id === 'stepcode' ? '@step-harness/coding-agent' : '')
+    if (!name || name !== ownPackage) throw new Error('安装目录已有其他工具或项目的 package.json，已停止运行官方脚本。')
+  }
+  for (const other of OFFICIAL_TOOLS) {
+    if (other.id === tool.id) continue
+    const commandDirectories = [...new Set([directory, plan.binDir].filter(Boolean))]
+    const candidates = commandDirectories.flatMap(dir => (other.probeExecutables ?? []).flatMap(name =>
+      [name, `${name}.exe`, `${name}.cmd`, `${name}.ps1`].map(file => join(dir, file))))
+    if (other.package) {
+      candidates.push(join(directory, 'node_modules', ...other.package.split('/'), 'package.json'))
+      candidates.push(join(directory, 'lib', 'node_modules', ...other.package.split('/'), 'package.json'))
+    }
+    for (const path of candidates) {
+      const found = await stat(path).catch(error => {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+        throw error
+      })
+      if (found?.isFile()) throw new Error(`安装目录中已有 ${other.label} 的文件，已拒绝运行可能替换其资源的官方脚本。请使用独立目录。`)
+    }
+  }
+}
+
 /**
  * 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
@@ -527,6 +625,7 @@ async function runVendorScriptInstallJob(job, plan) {
   let staging = null
   try {
     job.phase = 'preflight'
+    await assertVendorInstallDirectory(job.tool, plan, job.preferences)
     const before = await probeToolWith(job.tool, defaultRunner, { plan, preferences: job.preferences, cacheMs: 0 })
     job.beforeProbe = before
     const latestBefore = before.installed ? await latestVersions.lookup(job.tool, { fresh: true }).catch(() => null) : null
@@ -548,6 +647,7 @@ async function runVendorScriptInstallJob(job, plan) {
     await writeFile(scriptPath, isPowerShell ? `\uFEFF${source}` : source, 'utf8')
     const invocation = vendorScriptInvocation(plan, scriptPath)
     job.phase = 'installing'
+    await assertVendorInstallDirectory(job.tool, plan, job.preferences)
     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,
@@ -768,10 +868,13 @@ async function probeUncached(tool, runner, { selectedPreferences, plan, fileExis
   }
   if (tool.manager === 'signed-windows-installer') {
     let rejected = null
-    const bundle = await discoverZCodeBundle({ onRejected: value => { rejected ??= value } })
+    const bundle = await discoverZCodeBundle({ installDir: (selectedPreferences ?? preferences).zcodeInstallDir,
+      onRejected: value => { rejected ??= value } })
     if (bundle) return { id: tool.id, installed: true, version: bundle.version, status: 'installed',
-      detail: `${tool.probeNote} 安装目录：${bundle.root}`, bannerLine: `${tool.label} ${bundle.buildVersion}` }
-    if (rejected) return { id: tool.id, installed: false, version: null, status: 'not-installed', detail: `检测到已安装的 ZCode ${rejected.version}（${rejected.root}）：${rejected.rejected}` }
+      detail: `${tool.probeNote} 安装目录：${bundle.root}`, bannerLine: `${tool.label} 桌面版 ${bundle.buildVersion}`,
+      installDir: bundle.root, cliEntry: bundle.cliEntry, source: bundle.source }
+    if (rejected) return { id: tool.id, installed: false, version: null, status: 'not-installed',
+      detail: rejected.version ? `检测到 ZCode ${rejected.version}（${rejected.root}）：${rejected.rejected}` : rejected.rejected }
     const other = (await unverifiedZCodeInstalls().catch(() => []))[0]
     return { id: tool.id, installed: false, version: null, status: 'not-installed',
       detail: other
@@ -827,6 +930,22 @@ async function probeUncached(tool, runner, { selectedPreferences, plan, fileExis
           bannerLine: banner.split('\n').find(Boolean)?.slice(0, 200) ?? '' }
       }
     }
+    const legacy = resolveLegacyScriptLocation(tool, selectedPlan.method, selectedPreferences, currentInstallOptions())
+    if (legacy) {
+      for (const executable of tool.probeExecutables) {
+        const names = IS_WINDOWS ? [`${executable}.exe`, `${executable}.cmd`, executable] : [executable]
+        for (const name of names) {
+          const target = join(legacy.dir, name)
+          if (!(await fileExists(target))) continue
+          // Discovery is read-only. The old root can never satisfy a new job's
+          // target probe or become a script update/uninstall destination.
+          return { id: tool.id, installed: false, version: null, status: 'legacy-install',
+            installDir: selectedPlan.installDir, binDir: selectedPlan.binDir,
+            legacyExecutablePath: target,
+            detail: `发现旧共享目录中的 ${tool.label}：${target}。请安装到独立目录 ${selectedPlan.installDir}；旧文件会保留，不能用旧目录覆盖其他工具。` }
+        }
+      }
+    }
     return { id: tool.id, installed: false, version: null, status: 'not-installed',
       installDir: selectedPlan.installDir, binDir: selectedPlan.binDir,
       detail: `未在所选安装目录 ${selectedPlan.binDir} 中找到官方命令。` }
@@ -1006,6 +1125,7 @@ function jobView(job) {
     exitCode: job.exitCode,
     timedOut: job.timedOut,
     error: job.error,
+    executionReadiness: job.executionReadiness ?? null,
     outputTail: [...job.outputTail],
     outputTruncated: job.outputTruncated,
     postInstallProbe: job.postInstallProbe,
@@ -1272,8 +1392,10 @@ export function installEnvironment(plan, base = process.env) {
   return env
 }
 
-/** Mark the job succeeded only when the fresh probe is installed, ready, and not still older. */
-async function finishVerifiedInstall(job, probe) {
+/** Installation and version must pass; verify execution only where an adapter supports it. */
+export async function finishVerifiedInstall(job, probe, {
+  lookupLatest = tool => latestVersions.lookup(tool), readinessFor = trustedExecutionReadiness,
+} = {}) {
   job.postInstallProbe = probe
   if (job.cancelRequested) { markCancelled(job); return true }
   if (!probe.installed) {
@@ -1282,14 +1404,15 @@ async function finishVerifiedInstall(job, probe) {
     job.error = `安装命令已完成，但重探测失败：${probe.detail}`
     return true
   }
-  const latest = await latestVersions.lookup(job.tool).catch(() => null)
+  const latest = await lookupLatest(job.tool).catch(() => null)
   if (latest?.version && versionStillOlder(probe.version, latest.version)) {
     failBecauseStillOlder(job, probe, latest.version)
     return true
   }
-  const readiness = await trustedExecutionReadiness(job.tool.id, { preferences: job.preferences, plan: job.plan })
+  const readiness = await readinessFor(job.tool.id, { preferences: job.preferences, plan: job.plan })
+  job.executionReadiness = readiness
   if (job.cancelRequested) { markCancelled(job); return true }
-  if (!readiness.ready) {
+  if (!readiness.ready && readiness.supported !== false) {
     if (IS_WINDOWS && job.tool.id === 'minimax-code' && !job.configured) {
       await runOfficialMiniMaxInstaller(job)
       return true
@@ -1300,8 +1423,11 @@ async function finishVerifiedInstall(job, probe) {
     return true
   }
   job.status = 'succeeded'
+  job.error = null
   job.finishedAt = new Date().toISOString()
-  pushLine(job, `— 已安装 ${job.tool.label} ${probe.version ?? ''}，官方执行入口已核验（新版本未经插件测试）—`)
+  pushLine(job, readiness.supported === false
+    ? `— 已安装 ${job.tool.label} ${probe.version ?? ''}，版本探测已通过；受限执行未启用：${readiness.reason} —`
+    : `— 已安装 ${job.tool.label} ${probe.version ?? ''}，官方执行入口已核验（新版本未经插件测试）—`)
   return true
 }
 
@@ -1378,11 +1504,13 @@ async function runInstallJob(installPlan, job) {
       // 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)) {
+      } else if (readiness.ready || readiness.supported === false || !CAPABILITY_REPAIRABLE.has(job.tool.id)) {
         job.status = 'succeeded'
         job.finishedAt = new Date().toISOString()
         job.postInstallProbe = before
+        job.executionReadiness = readiness
         pushLine(job, `— ${job.tool.label} ${before.version} 已是最新版本，无需重复安装 —`)
+        if (readiness.supported === false) pushLine(job, `— 受限执行未启用：${readiness.reason} —`)
         return
       } else {
         pushLine(job, `— 已是最新版本 ${before.version}，但执行入口未就绪：${readiness.reason}；重新安装修复 —`)
@@ -1464,30 +1592,43 @@ async function runInstallJob(installPlan, job) {
   await finishVerifiedInstall(job, probe)
 }
 
-async function runZCodeInstallJob(job) {
+export async function runZCodeInstallJob(job, {
+  probe = probeToolWith, lookup = (...args) => latestVersions.lookup(...args),
+  openInstaller = openZCodeInstaller, capture = runCapture,
+} = {}) {
   if (job.status !== 'running') return
   job.phase = 'preflight'
   probeCache.delete(job.tool.id)
-  const before = await probeToolWith(job.tool, defaultRunner)
+  const before = await probe(job.tool, defaultRunner, { preferences: job.preferences, cacheMs: 0 })
   if (job.cancelRequested) { markCancelled(job); return }
-  const latest = await latestVersions.lookup(job.tool, { fresh: true }).catch(() => null)
+  const latest = await lookup(job.tool, { fresh: true }).catch(() => null)
   if (job.cancelRequested) { markCancelled(job); return }
-  if (before.installed && latest?.version && (compareReleaseVersions(before.version, latest.version) ?? -1) >= 0) {
+  const desktopOrder = before.installed && latest?.version ? compareReleaseVersions(before.version, latest.version) : null
+  if (before.installed && desktopOrder === null) {
+    job.status = 'failed'
+    job.phase = 'done'
+    job.finishedAt = new Date().toISOString()
+    job.error = '无法核实 ZCode 最新桌面版本；保留当前安装，网络恢复后重试检查更新。'
+    return
+  }
+  if (desktopOrder === 1 || (job.operation !== 'repair' && desktopOrder === 0)) {
     job.status = 'succeeded'
     job.phase = 'done'
     job.finishedAt = new Date().toISOString()
     job.postInstallProbe = before
-    pushLine(job, `— 已找到 ZCode ${before.version}（最新 ${latest.version}），无需重复打开安装器 —`)
+    pushLine(job, desktopOrder === 1
+      ? `— ZCode ${before.version} 高于下载页的 ${latest.version}，不会打开旧版安装器降级；TUI 使用当前桌面内置入口 —`
+      : `— 已找到 ZCode ${before.version}（最新 ${latest.version}），无需重复打开安装器；TUI 使用当前桌面内置入口 —`)
     return
   }
-  const prefix = await runCapture('npm', ['config', 'get', 'prefix'], {
+  const prefix = await capture('npm', ['config', 'get', 'prefix'], {
     timeoutMs: 5_000, useShell: IS_WINDOWS, signal: job.controller.signal,
   })
   if (job.cancelRequested) { markCancelled(job); return }
   job.phase = 'downloading-and-verifying'
   let lastProgress = 0
   try {
-    const opened = await openZCodeInstaller({
+    const opened = await openInstaller({
       latest,
       npmPrefix: prefix.ok ? prefix.stdout.trim() : undefined,
       signal: job.controller.signal,
@@ -1504,7 +1645,11 @@ async function runZCodeInstallJob(job) {
     job.finishedAt = new Date().toISOString()
     probeCache.delete(job.tool.id)
     pushLine(job, `已验证发布者签名并打开 ZCode ${opened.version} 官方安装器：${opened.installerPath}`)
-    pushLine(job, '请在原厂安装界面选择非 C 盘目录；完成后点击“重新检测”。')
+    const desktopDirectory = before.installDir || (/[\\/]ZCode\.exe$/i.test(job.preferences.zcodeInstallDir ?? '')
+      ? dirname(job.preferences.zcodeInstallDir) : job.preferences.zcodeInstallDir)
+    pushLine(job, desktopDirectory
+      ? `请在原厂安装界面选择原桌面安装目录 ${desktopDirectory}；完成后重新体检，内置 TUI 随桌面版更新。`
+      : '请在原厂安装界面选择独立的 ZCode 桌面目录；完成后保存该目录并重新体检，内置 TUI 随桌面版更新。')
   } catch (error) {
     if (job.cancelRequested || job.controller.signal.aborted) { markCancelled(job); return }
     job.status = 'failed'
@@ -1575,5 +1720,5 @@ export function resetForTests() {
   installJobs.clear()
   installChain = Promise.resolve()
   prefixPromise = null
-  preferences = { installDir: '', registry: '', methods: {}, scriptUrls: {}, allowScriptInstall: true }
+  preferences = { installDir: '', registry: '', methods: {}, scriptUrls: {}, allowScriptInstall: true, zcodeInstallDir: '' }
 }

package/.dsh-plugin/shared/task-executors.mjs

@@ -14,8 +14,11 @@
 import { spawn } from 'node:child_process'
 import { StringDecoder } from 'node:string_decoder'
 import { realpath, stat } from 'node:fs/promises'
-import { isAbsolute, win32 } from 'node:path'
+import { dirname, isAbsolute, join, relative, sep, win32 } from 'node:path'
 import { toolForProvider } from './official-tool-registry.mjs'
+import { findGlobalPackageEntries, findNodeExecutable, officialToolEntrySelection } from './official-tool-executor.mjs'
+import { installedModuleRoots } from './vendor-mimo-grok-adapter.mjs'
+import { CODE_FILE, npmAttestor } from './npm-attestation.mjs'
 import { normalizeExecutionPreference } from './model-profiles.mjs'
 import { BILLING_MODE_LABEL, billingPlan, detectQuotaExhaustion, vendorKey } from './subscription-billing.mjs'
 
@@ -666,6 +669,45 @@ function officialSuccess({ route, adapter, preference, answer, exitCode, version
   }
 }
 
+/** Gemini's Windows npm shim cannot be spawned without a shell; use its selected package bin. */
+export async function resolvePortableToolLaunch(adapter, workspace, {
+  selection = adapter?.id === 'gemini' ? officialToolEntrySelection('gemini') : null,
+  findEntries = findGlobalPackageEntries, findNode = findNodeExecutable, attestor = npmAttestor,
+} = {}) {
+  if (adapter?.id !== 'gemini') return { file: adapter.executable, args: [] }
+  const entries = await findEntries('@google/gemini-cli', 'gemini', 'dist/index.js', workspace, { selection })
+  const found = entries[0]
+  if (!found) return { reason: '未在所选安装目录中找到 @google/gemini-cli 的 gemini 入口；已回退模型目录 API。' }
+  const inside = (root, entry) => {
+    const part = relative(root, entry)
+    return part !== '' && part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part)
+  }
+  const roots = Array.isArray(selection?.plan?.packageModuleRoots) ? selection.plan.packageModuleRoots
+    : await installedModuleRoots(selection?.directories ?? [], { manager: selection?.plan?.manager })
+  const prefix = selection?.plan?.installDir ? await realpath(selection.plan.installDir).catch(() => null) : null
+  if (selection?.plan?.installDir && !prefix) return { reason: 'Gemini 所选安装根无法确认，已拒绝启动并回退模型目录 API。' }
+  let contained = false
+  for (const declared of roots) {
+    const boundary = await realpath(declared).catch(() => null)
+    const parent = await realpath(dirname(declared)).catch(() => null)
+    if (!boundary || !parent || !inside(parent, boundary) || (prefix && !inside(prefix, boundary))) continue
+    if (inside(boundary, found.packageRoot) && inside(found.packageRoot, found.entry)
+      && !inside(workspace, found.packageRoot) && found.packageRoot !== workspace) { contained = true; break }
+  }
+  if (!contained) return { reason: 'Gemini 包或入口离开了所选安装目录的包存储树，已拒绝启动并回退模型目录 API。' }
+  // The manifest controls bin/import resolution, so attest it as well as all
+  // package code. Checking name/version or a signed Node alone is insufficient.
+  const include = new RegExp(`${CODE_FILE.source}|(?:^|/)package\\.json$`, 'i')
+  const checked = await attestor.matchesPackage(found.packageRoot, '@google/gemini-cli', found.version, include)
+  if (!checked.ok) return { reason: `Gemini 安装文件未通过官方 npm 摘要核验：${checked.reason}；已回退模型目录 API。` }
+  const member = relative(found.packageRoot, found.entry).split(sep).join('/')
+  const entryChecked = await attestor.matches(found.entry, '@google/gemini-cli', found.version, member)
+  if (!entryChecked.ok) return { reason: `Gemini 入口未通过官方 npm 摘要核验：${entryChecked.reason}；已回退模型目录 API。` }
+  const node = await findNode(workspace, [20, 0, 0])
+  if (!node) return { reason: '未找到工作区外的 Node.js 20+ 可执行文件；已回退模型目录 API。' }
+  return { file: node, args: [found.entry], version: found.version, source: 'official-npm-registry-attested' }
+}
+
 /**
  * Run one assigned model task. `auto` and `official` try the vendor CLI first.
  * `api` skips the CLI. A missing tool or a failed process uses `apiFallback`.
@@ -673,6 +715,7 @@ function officialSuccess({ route, adapter, preference, answer, exitCode, version
 export async function executeAssignedTask({
   route, task, workspace, timeoutMs, signal, credentials = null, spawnImpl = spawn,
   apiFallback, runVerified = null, onChunk = null, skipOfficial = null, stopGraceMs, credentialMode = 'default',
+  resolvePortableLaunch = resolvePortableToolLaunch,
 } = {}) {
   const prompt = checkedTask(task)
   const preference = executionPreference(route)
@@ -734,7 +777,13 @@ export async function executeAssignedTask({
     })
   }
   const { env, secret, credentialSource } = childEnvironment(adapter, credentials, credentialMode)
-  const probe = await captureProcess(spawnImpl, adapter.executable, ['--version'], {
+  let launch
+  try { launch = await resolvePortableLaunch(adapter, cwd) } catch (error) {
+    launch = { reason: `${adapter.label} 的安装入口无法读取：${String(error?.message ?? error).slice(0, 200)}；已回退模型目录 API。` }
+  }
+  if (!launch?.file) return useApi(apiFallback, { route, task: prompt, signal, adapter, preference,
+    reason: launch?.reason ?? `${adapter.label} 未安装或无法启动，已回退模型目录 API。` })
+  const probe = await captureProcess(spawnImpl, launch.file, [...launch.args, '--version'], {
     cwd, env, stdin: '', timeoutMs: Math.min(PROBE_TIMEOUT_MS, timeout), signal, secret,
   })
   if (probe.spawnError || probe.cancelled || probe.timedOut || probe.exitCode !== 0) {
@@ -748,7 +797,7 @@ export async function executeAssignedTask({
     return useApi(apiFallback, { route, task: prompt, signal, adapter, preference, reason })
   }
   const args = adapter.buildArgs(modelId)
-  const run = await captureProcess(spawnImpl, adapter.executable, args, {
+  const run = await captureProcess(spawnImpl, launch.file, [...launch.args, ...args], {
     cwd, env, stdin: prompt, timeoutMs: timeout, signal, onChunk, secret,
     ...(Number.isSafeInteger(stopGraceMs) && stopGraceMs >= 10 && stopGraceMs <= STOP_GRACE_MS ? { stopGraceMs } : {}),
   })

package/.dsh-plugin/shared/tool-install-preferences.mjs

@@ -70,6 +70,26 @@ export function expandInstallDir(value, { home = '', env = {} } = {}) {
   return expanded
 }
 
+/** ZCode's existing desktop bundle is selected independently of npm's prefix. */
+export function normalizeZCodeInstallDir(value, options = {}) {
+  const input = String(value ?? '')
+  if (/[\x00-\x1f]/.test(input)) throw new Error('ZCode 安装位置包含无效字符。')
+  const raw = input.trim().replace(/^"(.*)"$/, '$1')
+  if (!raw) return ''
+  let path
+  try { path = expandInstallDir(raw, options) } catch (error) {
+    throw new Error(`ZCode 安装位置无效：${error.message}`)
+  }
+  // Discovery and Authenticode verification operate on local Windows files.
+  if (!/^[A-Za-z]:[\\/]/.test(path)) {
+    throw new Error('ZCode 安装位置必须是 Windows 本地绝对目录或 ZCode.exe 路径。')
+  }
+  if (/\.exe[\\/]*$/i.test(path) && !/[\\/]ZCode\.exe[\\/]*$/i.test(path)) {
+    throw new Error('ZCode 程序路径必须指向官方 ZCode.exe。')
+  }
+  return path.replace(/[\\/]+$/, '')
+}
+
 /** Only https mirrors are accepted; a plain-http script source can be tampered with in transit. */
 export function normalizeSourceUrl(value, subject) {
   const raw = String(value ?? '').trim()
@@ -116,6 +136,7 @@ function keepKnownToolIds(raw, known, subject) {
 export function parseInstallPreferences(config = {}, { tools = [], home = '', env = {} } = {}) {
   const known = new Set(tools.map(tool => tool.id))
   const installDir = expandInstallDir(valueOf(config, 'toolInstallDir', ''), { home, env })
+  const zcodeInstallDir = normalizeZCodeInstallDir(valueOf(config, 'zcodeInstallDir', ''), { home, env })
   const registry = normalizeSourceUrl(valueOf(config, 'toolNpmRegistry', DEFAULT_NPM_REGISTRY), 'npm 源') || DEFAULT_NPM_REGISTRY
   const methodRaw = keepKnownToolIds(
     parseJsonObject(valueOf(config, 'toolInstallMethodsJson', '{}'), '安装方式覆盖'), known, '安装方式覆盖')
@@ -134,6 +155,7 @@ export function parseInstallPreferences(config = {}, { tools = [], home = '', en
   }
   return {
     installDir,
+    zcodeInstallDir,
     registry,
     methods,
     scriptUrls,
@@ -249,12 +271,17 @@ export function resolveInstallPlan(tool, methodId, preferences = {}, { platform
     const binDir = target
       ? (method.installDirSuffix ? joinPath(target, method.installDirSuffix) : target)
       : vendorScriptDir(tool, { home, env, method })
-    const notices = target ? [] : installDir
+    const notices = target && installDir && method.installDirSubdir
+      ? [`官方脚本在工具专属子目录 ${target} 维护资源，保护统一安装根中的其他工具。`]
+      : target ? [] : installDir
       ? [`${method.label} 无法使用自定义安装目录（官方脚本写死了安装路径），将安装到 ${vendorScriptDir(tool, { home, env, method })}。`]
       : []
     if (method.registryEnv === 'MCODE_NPM_REGISTRY' && preferences.registry && !minimaxScriptRegistry(preferences.registry)) {
       notices.push('MiniMax 官方脚本只接受 https://registry.npmjs.org/ 或 https://registry.npmmirror.com/，本次不改写它的 npm 源。')
     }
+    if (tool.id === 'codex' && method.id === 'script-powershell') {
+      notices.push('Codex Windows 脚本将命令目录联接到用户 Codex 资源目录；统一根控制命令位置，运行资源仍由厂商保存在用户目录。需要所有文件位于统一根时请选 npm/pnpm。')
+    }
     return {
       toolId: tool.id,
       method,
@@ -332,6 +359,20 @@ export function resolveInstallLocation(tool, method, preferences = {}, { home =
   return { kind: 'package-manager', dir: packageManagerBinDir(preferences?.installDir || '', { platform }), installDir: preferences?.installDir || '', binaries: [] }
 }
 
+/**
+ * Read-only compatibility location for scripts installed directly into a
+ * configured shared root before dedicated script directories were introduced.
+ * Never use this result as an install/update target: those installers can
+ * replace a whole runtime tree belonging to another tool.
+ */
+export function resolveLegacyScriptLocation(tool, method, preferences = {}, options = {}) {
+  if (!preferences.installDir || !method?.legacySharedInstallDir || !methodHonoursInstallDir(method)) return null
+  return {
+    ...resolveInstallLocation(tool, { ...method, installDirSubdir: undefined }, preferences, options),
+    legacySharedInstallDir: true,
+  }
+}
+
 function scriptEnv(method, { installDir, scriptUrl, registry }) {
   const env = {}
   if (installDir && method.installDirEnv) env[method.installDirEnv] = installDir

package/.dsh-plugin/shared/zcode-bundle.mjs

@@ -46,6 +46,14 @@ function powershellPath(env) {
   return join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
 }
 
+/** PowerShell 7's module path can prevent Windows PowerShell 5.1 loading Security. */
+export function zcodeWindowsPowerShellEnvironment(env = process.env) {
+  return {
+    ...env,
+    PSModulePath: join(env.SystemRoot || env.windir || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'Modules'),
+  }
+}
+
 async function powershellJson(script, env, extraEnv = {}) {
   if (process.platform !== 'win32') return null
   const command = Buffer.from(
@@ -62,7 +70,7 @@ async function powershellJson(script, env, extraEnv = {}) {
       encoding: 'utf8',
       timeout: 10_000,
       maxBuffer: 256_000,
-      env: { ...env, ...extraEnv },
+      env: { ...zcodeWindowsPowerShellEnvironment(env), ...extraEnv },
     })
     const output = stdout.trim().replace(/^\uFEFF/, '')
     return output ? JSON.parse(output) : null
@@ -94,13 +102,21 @@ function rootFromCommand(value) {
   return executable && win32.isAbsolute(executable) ? dirname(executable) : null
 }
 
-function candidateRoots(env, records) {
+/** Explicit selection is authoritative, even when the selected bundle is missing. */
+export function zcodeDiscoveryCandidates({ installDir = '', env = process.env, records = [] } = {}) {
   const candidates = []
   const add = (path, source, registryVersion = null) => {
     if (typeof path !== 'string' || !path.trim()) return
     candidates.push({ path: path.trim().replace(/^"|"$/g, ''), source, registryVersion })
   }
-  add(env[ZCODE_INSTALL_ENV_VAR], 'operator-env')
+  if (installDir != null && String(installDir).trim()) {
+    add(installDir, 'operator-config')
+    return candidates
+  }
+  if (env[ZCODE_INSTALL_ENV_VAR] != null && String(env[ZCODE_INSTALL_ENV_VAR]).trim()) {
+    add(env[ZCODE_INSTALL_ENV_VAR], 'operator-env')
+    return candidates
+  }
   for (const record of records) {
     const version = String(record.displayVersion || '') || null
     add(record.installLocation, 'uninstall-registry', version)
@@ -204,7 +220,7 @@ async function checkedBundle(candidate, env, trustPath) {
   const input = candidate.path
   if (!localWindowsPath(input)) return null
   try {
-    const initial = input.toLowerCase().endsWith('\\zcode.exe') ? dirname(input) : input
+    const initial = /[\\/]zcode\.exe$/i.test(input) ? dirname(input) : input
     const root = await realpath(initial)
     if (!localWindowsPath(root) || !(await stat(root)).isDirectory()) return null
     const executable = await realpath(join(root, 'ZCode.exe'))
@@ -239,18 +255,23 @@ async function checkedBundle(candidate, env, trustPath) {
   }
 }
 
-/** Return the first verified local bundle (any version), or null when none is usable. */
-export async function discoverZCodeBundle({ env = process.env, trustPath = zcodeTrustPath(env), onRejected } = {}) {
+/** A configured desktop location never falls back to a different installation. */
+export async function discoverZCodeBundle({ installDir = '', env = process.env, trustPath = zcodeTrustPath(env), onRejected } = {}) {
   if (process.platform !== 'win32') return null
-  const records = await uninstallRecords(env)
+  const explicit = Boolean(String(installDir || env[ZCODE_INSTALL_ENV_VAR] || '').trim())
+  const records = explicit ? [] : await uninstallRecords(env)
   const seen = new Set()
-  for (const candidate of candidateRoots(env, records)) {
+  for (const candidate of zcodeDiscoveryCandidates({ installDir, env, records })) {
     const key = win32.normalize(candidate.path).toLowerCase()
     if (seen.has(key)) continue
     seen.add(key)
     const bundle = await checkedBundle(candidate, env, trustPath)
     if (bundle?.rejected) { onRejected?.(bundle); continue }
     if (bundle) return bundle
+    if (explicit) onRejected?.({
+      root: candidate.path,
+      rejected: `指定的 ZCode 安装位置 ${candidate.path} 不存在，或未通过官方签名、桌面内置 CLI 和目录边界核验；请检查独立安装位置。`,
+    })
   }
   return null
 }

package/.dsh-plugin/shared/zcode-installer.mjs

@@ -19,7 +19,7 @@ import { dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { Readable, Transform } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { promisify } from 'node:util'
-import { ZCODE_SIGNER } from './zcode-bundle.mjs'
+import { ZCODE_SIGNER, zcodeWindowsPowerShellEnvironment } from './zcode-bundle.mjs'
 import { getOfficialTool } from './official-tool-registry.mjs'
 import { latestVersions } from './latest-versions.mjs'
 
@@ -118,7 +118,7 @@ async function verifyInstallerSignature(path, env) {
       encoding: 'utf8',
       timeout: 120_000,
       maxBuffer: 16_384,
-      env: { ...env, MODEL_ROUTER_ZCODE_INSTALLER_PATH: path },
+      env: { ...zcodeWindowsPowerShellEnvironment(env), MODEL_ROUTER_ZCODE_INSTALLER_PATH: path },
     })
     const signature = JSON.parse(stdout.trim().replace(/^\uFEFF/, ''))
     return signature.status === 'Valid'