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

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

@@ -0,0 +1,294 @@
+/**
+ * Turns the user's plugin settings into one concrete, reviewable install plan.
+ *
+ * Two separate "addresses" are configurable, and both stay on the Host: a
+ * unified install directory and a set of download sources (an npm registry plus
+ * per-tool installer-script URLs). The client never sends either — the RPC
+ * carries only a registry id and a method id, so a hostile client cannot point
+ * this plugin at an arbitrary package or URL. Everything here is Host config
+ * the user typed into their own settings form.
+ *
+ * Script installs are never piped into an interpreter. A plan carries the
+ * vendor URL plus the markers that still identify that vendor's script; the
+ * runtime downloads it with a size cap, checks the markers, stages a copy and
+ * runs that. So a mirror may serve different bytes, but it may not serve a
+ * different program.
+ *
+ * This module is imported by the browser bundle too, so it must stay free of
+ * Node built-ins: paths are handled with plain string rules, and the Host passes
+ * the home directory in when it needs one.
+ */
+import {
+  DEFAULT_NPM_REGISTRY,
+  defaultInstallMethod,
+  installMethodBlockReason,
+  installMethodFor,
+  installMethodsFor,
+  methodHonoursInstallDir,
+} from './official-tool-registry.mjs'
+
+export const MAX_INSTALL_DIR_CHARS = 4_096
+export const MAX_SOURCE_URL_CHARS = 2_048
+export const MAX_OVERRIDES = 64
+
+/** Windows drive paths, UNC paths, or anything rooted at `/`. */
+export function isAbsolutePath(value) {
+  const raw = String(value ?? '')
+  if (!raw) return false
+  if (raw.startsWith('/')) return true
+  if (/^[A-Za-z]:[\\/]/.test(raw)) return true
+  return /^\\\\[^\\]+\\[^\\]+/.test(raw)
+}
+
+/** Join path segments with the separator the first absolute segment already uses. */
+export function joinPath(base, ...segments) {
+  const separator = String(base ?? '').includes('\\') && !String(base ?? '').includes('/') ? '\\' : '/'
+  const parts = [String(base ?? '').replace(/[\\/]+$/, ''), ...segments.map(item => String(item ?? '').replace(/^[\\/]+|[\\/]+$/g, ''))]
+  return parts.filter(Boolean).join(separator) || separator
+}
+
+/** Expand `~` and environment references the way a shell would on this host. */
+export function expandInstallDir(value, { home = '', env = {} } = {}) {
+  const raw = String(value ?? '').trim()
+  if (!raw) return ''
+  if (raw.includes('\0')) throw new Error('安装目录包含无效字符。')
+  let expanded = raw
+  const userHome = String(home ?? '')
+  if (expanded === '~') expanded = userHome
+  else if (expanded.startsWith('~/') || expanded.startsWith('~\\')) expanded = joinPath(userHome, expanded.slice(2))
+  // `%VAR%` on Windows, `$VAR` elsewhere — both forms the vendor scripts accept.
+  expanded = expanded
+    .replace(/%([A-Za-z_][A-Za-z0-9_]*)%/g, (match, name) => env[name] ?? match)
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, name) => env[name] ?? match)
+  if (expanded.length > MAX_INSTALL_DIR_CHARS) throw new Error('安装目录过长。')
+  if (!isAbsolutePath(expanded)) throw new Error('安装目录必须是绝对路径。')
+  // A bare root ("/", "D:\\", "\\\\server\\share") would take the machine with it.
+  const withoutTrailing = expanded.replace(/[\\/]+$/, '')
+  if (!withoutTrailing) throw new Error('安装目录不能是文件系统根目录。')
+  if (/^[A-Za-z]:$/.test(withoutTrailing)) throw new Error('安装目录不能是文件系统根目录。')
+  if (/^\\\\[^\\]+\\[^\\]+$/.test(withoutTrailing)) throw new Error('安装目录不能是网络共享根目录。')
+  return expanded
+}
+
+/** 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()
+  if (!raw) return ''
+  if (raw.length > MAX_SOURCE_URL_CHARS) throw new Error(`${subject}地址过长。`)
+  let url
+  try { url = new URL(raw) } catch { throw new Error(`${subject}不是有效网址。`) }
+  if (url.protocol !== 'https:') throw new Error(`${subject}必须使用 https。`)
+  if (url.username || url.password) throw new Error(`${subject}不能包含账号密码。`)
+  return url.toString()
+}
+
+function parseJsonObject(value, subject) {
+  const raw = String(value ?? '').trim()
+  if (!raw) return {}
+  let parsed
+  try { parsed = JSON.parse(raw) } catch { throw new Error(`${subject}不是有效 JSON。`) }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${subject}必须是 JSON 对象。`)
+  }
+  const entries = Object.entries(parsed)
+  if (entries.length > MAX_OVERRIDES) throw new Error(`${subject}条目过多。`)
+  return Object.fromEntries(entries.filter(([, item]) => typeof item === 'string' && item.trim()))
+}
+
+function valueOf(config, key, fallback) {
+  const value = config?.[key]
+  return value !== undefined && typeof value?.get === 'function' ? value.get() : value ?? fallback
+}
+
+/** Registry entries used by the installer are the only keys an override may name. */
+function keepKnownToolIds(raw, known, subject) {
+  for (const key of Object.keys(raw)) {
+    if (!known.has(key)) throw new Error(`${subject}中的 ${key} 不是官方工具 ID。`)
+  }
+  return raw
+}
+
+/**
+ * Read the plugin settings into a normalized, already-validated shape.
+ * Throws with a user-facing message on the first bad value, so the settings
+ * form and the installer fail the same way.
+ */
+export function parseInstallPreferences(config = {}, { tools = [] } = {}) {
+  const known = new Set(tools.map(tool => tool.id))
+  const installDir = expandInstallDir(valueOf(config, 'toolInstallDir', ''))
+  const registry = normalizeSourceUrl(valueOf(config, 'toolNpmRegistry', DEFAULT_NPM_REGISTRY), 'npm 源') || DEFAULT_NPM_REGISTRY
+  const methodRaw = keepKnownToolIds(
+    parseJsonObject(valueOf(config, 'toolInstallMethodsJson', '{}'), '安装方式覆盖'), known, '安装方式覆盖')
+  const scriptRaw = keepKnownToolIds(
+    parseJsonObject(valueOf(config, 'toolScriptUrlsJson', '{}'), '安装脚本源覆盖'), known, '安装脚本源覆盖')
+  const methods = {}
+  const scriptUrls = {}
+  for (const [id, methodId] of Object.entries(methodRaw)) methods[id] = methodId.trim()
+  for (const [id, url] of Object.entries(scriptRaw)) scriptUrls[id] = normalizeSourceUrl(url, `${id} 安装脚本源`)
+  for (const [id, methodId] of Object.entries(methods)) {
+    if (!installMethodFor({ id, installMethods: tools.find(tool => tool.id === id)?.installMethods }, methodId)) {
+      throw new Error(`${id} 不支持安装方式 ${methodId}。`)
+    }
+  }
+  return {
+    installDir,
+    registry,
+    methods,
+    scriptUrls,
+    /** Script execution stays a deliberate act; a config file alone must not run one. */
+    allowScriptInstall: valueOf(config, 'toolAllowScriptInstall', true) !== false,
+  }
+}
+
+/** Where a script install puts the binary: the user's directory, else the vendor default. */
+export function scriptInstallDir(tool, preferences, { home = '' } = {}) {
+  if (!tool?.defaultScriptInstallDir) return ''
+  return preferences?.installDir || vendorScriptDir(tool, { home })
+}
+
+/** The location the vendor script uses on its own, ignoring any configured directory. */
+export function vendorScriptDir(tool, { home = '' } = {}) {
+  return joinPath(home, ...String(tool?.defaultScriptInstallDir ?? '').split('/').filter(Boolean))
+}
+
+/** argv for a package-manager method, honouring the configured registry and prefix. */
+export function packageManagerArgs(method, preferences, { installDir = '' } = {}) {
+  const registry = preferences?.registry || DEFAULT_NPM_REGISTRY
+  const args = method.installArgs.filter(arg => !arg.startsWith('--registry='))
+  args.push(`--registry=${registry}`)
+  if (installDir) args.push('--prefix', installDir)
+  return [...args]
+}
+
+function baseUrlOf(scriptUrl) {
+  try {
+    const url = new URL(scriptUrl)
+    return `${url.origin}${url.pathname.replace(/\/[^/]*$/, '')}`
+  } catch { return '' }
+}
+
+/**
+ * The method to use: the requested one, else the user's saved choice, else the
+ * registry default — and if none of those run on this platform, the first
+ * declared method that does, so a Windows user is not asked to pick between
+ * two Unix shells.
+ */
+function pickMethod(tool, methodId, preferences, platform) {
+  const requested = methodId ?? preferences?.methods?.[tool.id]
+  if (!requested) {
+    return installMethodsFor(tool).find(method => !installMethodBlockReason(method, platform)) ?? defaultInstallMethod(tool)
+  }
+  // A named method is never silently swapped. If the tool does not declare it,
+  // or it does not run here, the caller gets the reason instead of a surprise.
+  const chosen = installMethodFor(tool, requested)
+  if (!chosen) throw new Error(`${tool.label} 没有名为 ${requested} 的安装方式。`)
+  return chosen
+}
+
+function unsupportedMethodError(tool) {
+  return tool?.manager === 'signed-windows-installer'
+    ? 'ZCode 使用官方签名桌面安装器，由用户在安装窗口选择目录。'
+    : `${tool?.label ?? '此工具'} 没有可用的安装方式。`
+}
+
+/**
+ * One concrete plan for one tool and one method. A thrown Error means the user
+ * asked for something this tool cannot do, with a reason they can act on.
+ */
+export function resolveInstallPlan(tool, methodId, preferences = {}, { platform = 'linux', home = '' } = {}) {
+  if (!tool || tool.unsupported) throw new Error(tool?.unsupportedReason ?? '此工具不支持一键安装。')
+  const method = pickMethod(tool, methodId, preferences, platform)
+  if (!method) throw new Error(unsupportedMethodError(tool))
+  const blocked = installMethodBlockReason(method, platform)
+  if (blocked) throw new Error(`${tool.label}：${blocked}`)
+  if (method.kind === 'script' && preferences?.allowScriptInstall === false) {
+    throw new Error('安装脚本方式已在插件设置中关闭；请改用包管理器方式，或在设置里重新允许。')
+  }
+  const installDir = preferences?.installDir || ''
+  if (method.kind === 'script') {
+    const scriptUrl = preferences?.scriptUrls?.[tool.id] || method.scriptUrl
+    const target = methodHonoursInstallDir(method) ? scriptInstallDir(tool, preferences, { home }) : ''
+    return {
+      toolId: tool.id,
+      method,
+      methodId: method.id,
+      kind: 'script',
+      label: method.label,
+      shell: method.shell,
+      scriptUrl,
+      verify: method.verify,
+      installArg: method.installArgs,
+      installDir: target,
+      env: scriptEnv(method, { installDir: target, scriptUrl }),
+      notices: target ? [] : installDir
+        ? [`${method.label} 无法使用自定义安装目录（官方脚本写死了安装路径），将安装到 ${vendorScriptDir(tool, { home })}。`]
+        : [],
+    }
+  }
+  return {
+    toolId: tool.id,
+    method,
+    methodId: method.id,
+    kind: 'package-manager',
+    label: method.label,
+    manager: method.manager,
+    args: packageManagerArgs(method, preferences, { installDir }),
+    installDir,
+    env: {},
+    notices: [],
+  }
+}
+
+/** Same plan shape for removal, so a UI can show exactly what will be deleted. */
+export function resolveUninstallPlan(tool, methodId, preferences = {}, options = {}) {
+  const platform = options.platform ?? 'linux'
+  const method = pickMethod(tool, methodId, preferences, platform)
+  if (!method) throw new Error(tool?.manager === 'signed-windows-installer'
+    ? 'ZCode 是桌面安装版，请在系统“应用”中卸载它。'
+    : `${tool?.label ?? '此工具'} 没有可用的卸载方式。`)
+  const blocked = installMethodBlockReason(method, platform)
+  if (blocked) throw new Error(`${tool.label}：${blocked}`)
+  if (method.kind === 'script') {
+    return { toolId: tool.id, method, methodId: method.id, kind: 'script', label: method.label, ...resolveInstallLocation(tool, method, preferences, options) }
+  }
+  return {
+    toolId: tool.id,
+    method,
+    methodId: method.id,
+    kind: 'package-manager',
+    label: method.label,
+    manager: method.manager,
+    args: [
+      ...method.uninstallArgs,
+      ...(preferences?.registry ? [`--registry=${preferences.registry}`] : []),
+      ...(preferences?.installDir ? ['--prefix', preferences.installDir] : []),
+    ],
+    installDir: preferences?.installDir || '',
+  }
+}
+
+/** Where the tool's binary lives, so a later uninstall can find it. */
+export function resolveInstallLocation(tool, method, preferences = {}, { home = '' } = {}) {
+  if (!method) return null
+  if (method.kind === 'script') {
+    // A method that cannot honour the configured directory always lands in the
+    // vendor's own location, whatever the user typed.
+    const dir = methodHonoursInstallDir(method)
+      ? scriptInstallDir(tool, preferences, { home })
+      : vendorScriptDir(tool, { home })
+    return { kind: 'script', dir, binaries: [...(tool.scriptBinaryNames ?? [])] }
+  }
+  return { kind: 'package-manager', dir: preferences?.installDir || '', binaries: [] }
+}
+
+function scriptEnv(method, { installDir, scriptUrl }) {
+  const env = {}
+  if (installDir && method.env?.includes('STEP_INSTALL_DIR')) env.STEP_INSTALL_DIR = installDir
+  // The step installers read their release base from this variable, so a mirror
+  // URL also moves the binaries and the checksum manifest, not just the script.
+  if (method.env?.includes('STEP_RELEASE_BASE_URL') && scriptUrl) {
+    const base = baseUrlOf(scriptUrl)
+    if (base) env.STEP_RELEASE_BASE_URL = base
+  }
+  return env
+}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.17.0 — 2026-10-11
+
+Stable minor under the npm `latest` tag. Fully quit Harness, including the tray or WebUI host process, and restart after upgrading so the Host reloads. Existing 0.16.4 artifacts remain unchanged.
+
+- **Two new official tools.** `opencode` (OpenCode, `opencode-ai` on npm or the official `curl -fsSL … | bash` installer) and `stepcode` (Step Code from StepFun, installed only by the vendor's `curl | bash` / `irm | iex` script — it publishes no npm package). Both are covered by the registry's probe, version lookup, health check and login guidance. Step Code's latest version is read from the same `latest.json` release manifest its own installer uses. Neither has a verified restricted execution entry yet, and both say so rather than claiming one.
+- **Every tool can now declare several install methods.** `installMethods` is the closed list the Host may use: `npm` and `pnpm` everywhere a package exists, plus the vendor installer script where the vendor ships one. The existing `manager` / `installArgs` stay the default method, so nothing about the old one-click path changed.
+- **Unified install settings.** New volatile config: `toolInstallDir`, `toolNpmRegistry`, `toolInstallMethodsJson`, `toolScriptUrlsJson`, `toolAllowScriptInstall`. They are editable from the **官方工具** page and from the plugin settings form, and apply to one-click install, repair and uninstall as well as `/tools` and the agent tools. An install directory becomes `--prefix` for npm/pnpm and `-InstallDir` / `--install-dir` for Step Code. OpenCode's official script hardcodes `~/.opencode/bin` and takes no directory, so for that tool the row says where it will actually land.
+- **Vendor scripts are verified before they run, never piped.** The plugin downloads the script with a size cap, requires the vendor's own markers, refuses an HTML error page or another vendor's installer, writes a staged copy and runs that. A configured mirror may rehost the same script; it may not substitute another program. A Step Code script mirror also redirects that vendor's binary and checksum downloads. Script installs can be switched off entirely.
+- **One-click repair and uninstall.** Repair re-runs the same fixed official command even when the tool already reports the latest version, which is the case a broken install actually presents. Uninstall removes only the program: package-manager installs go back through the same manager, script installs delete the single executable the vendor installer placed plus that install's own `# stepcode` PATH block in the shell profile. Configuration, credentials and session history are always kept. `checkedRemovableFile` re-checks the basename, the install directory and the root/home guards on every delete.
+- **The RPC stays closed.** `installTool`, `uninstallTool` and `repairTool` take one strict `{ tool, method? }` request; an unknown field, an unknown tool id or a method the tool does not declare is refused. Install addresses still come only from Host config, so a compromised client cannot redirect an install. `list()` now also reports the effective install directory, source and per-tool commands so the panel can show what will run.
+- `/tools` accepts `install`, `uninstall`, `repair`, `cancel` and `method`, each with an optional method id. New agent tools `model_router_tool_repair` and `model_router_tool_uninstall`, plus a `method` parameter on `model_router_tool_install`. Install, repair and uninstall each ask for approval, and uninstall's prompt states that settings and login are kept.
+- The workbench panel shows the settings block, a per-row method selector with the platform reason for anything unavailable, the resolved command, and repair/uninstall buttons. Install settings also appear in the plugin settings card with the same client-side validation as the Host.
+- Release validation on Windows 11: 649 tests passed, 3 conditional skips, `npm run build:client` and `npm run check:client` passed. No real vendor CLI was installed, no vendor script was executed, and no paid model call was made as part of this verification.
+
 ## 0.16.4 — 2026-10-09
 
 Stable patch under the npm `latest` tag. Fully quit Harness, including the tray or WebUI host process, and restart after upgrading so the Host reloads. Existing 0.16.3 artifacts remain unchanged.

package/README.md

@@ -143,12 +143,22 @@ The CLI team runner is the plugin's own sequential dependency executor. It does
 | `mimo-code` | MiMo Code | `read-only`, approved `workspace-write` |
 | `grok-build` | Grok Build | `read-only`, approved `workspace-write` |
 | `gemini` | Gemini CLI | Routed headless adapter; not the managed single-tool/team runner |
+| `opencode` | OpenCode | Install, probe and login check; no verified restricted execution entry yet |
+| `stepcode` | Step Code | Install, probe and login check; no verified restricted execution entry yet |
 | `zcode` | ZCode | Windows; approved `workspace-write` |
 
-Installers use fixed official npm packages at each vendor's `@latest`, or the official publisher-signed Windows ZCode installer. An installation newer than the reported latest is not downgraded. Latest-version lookups are cached for about 12 hours; unavailable lookups leave the version unknown. New vendor releases are not automatically validated by this project. ZCode's installation window still requires you to choose a directory and finish installation.
+Installers use fixed official npm packages at each vendor's `@latest`, the vendor's own installer script, or the official publisher-signed Windows ZCode installer. An installation newer than the reported latest is not downgraded. Latest-version lookups are cached for about 12 hours; unavailable lookups leave the version unknown. New vendor releases are not automatically validated by this project. ZCode's installation window still requires you to choose a directory and finish installation.
+
+**Unified install settings.** The top of the **官方工具** page (also in the plugin settings form) sets the install address for every tool at once: one install directory (empty means each vendor's default location), an npm source, and per-tool overrides for vendor installer-script mirrors. Directories must be absolute; sources must be https. Each row picks its own install method from `npm`, `pnpm` or the vendor script (`curl | bash` or `irm | iex`); a method that cannot run on this platform says so on the row instead of being silently swapped. The exact command is shown above the buttons before anything runs.
+
+**Script installs never pipe remote content into an interpreter.** The plugin downloads the vendor script, checks it is still that vendor's official installer (vendor markers required, HTML pages and other vendors' scripts refused), and runs the local copy. A mirror may rehost the same script; it may not substitute a different program. Step Code's script accepts an install directory; the OpenCode script hardcodes `~/.opencode/bin`, so a custom directory only applies to it through npm/pnpm's `--prefix`. Script installs can be switched off entirely, leaving only the package managers.
+
+**One-click repair and uninstall.** Repair re-runs the same fixed official command, which is what a broken install needs even when it already reports the latest version. Uninstall removes only the program: a package-manager install goes back through the same manager, and a script install deletes just the executable the vendor installer placed plus that install's own PATH entry in the shell profile. **Configuration, credentials and session history are always kept.**
 
 Installation, trusted launch readiness, account login and model entitlement are separate checks. An unknown login status is not proof of logout. On Windows, supported managed launch entries are checked against publisher signatures or official npm-tarball attestations; ZCode also records trust for its bundled script per signed build. See [the registry](.dsh-plugin/shared/official-tool-registry.mjs) and [executor](.dsh-plugin/shared/official-tool-executor.mjs) for the exact platform rules.
 
+In a session, `/tools install|uninstall|repair|method <tool-id> [method]` does the same; agents can call `model_router_tool_install`, `model_router_tool_repair` and `model_router_tool_uninstall`. The install directory and download sources always come from the user's own plugin settings and never travel over the RPC, so no call can redirect an install at an arbitrary package or URL.
+
 `model_router_execute` has fixed headless adapters for Claude, Codex and Gemini. Other suppliers use the model-directory API unless a supported subscription route applies. Missing/unusable CLIs can fall back to that API; subscription failures follow the policy below.
 
 Editable execution needs a clean Git repository, Host approval and the Harness process sandbox. Changes are made in an isolated worktree and applied back only after successful execution and a matching clean source workspace. Failed or conflicting integration is reported. Git-ignored outputs need separate review. Read-only CLI flags do not necessarily limit file reads to the workspace; check **安全边界**, especially Codex's broader readable scope.

package/README.zh.md

@@ -143,12 +143,22 @@ CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams
 | `mimo-code` | MiMo Code | `read-only`、经审批的 `workspace-write` |
 | `grok-build` | Grok Build | `read-only`、经审批的 `workspace-write` |
 | `gemini` | Gemini CLI | 路由执行的无界面适配器；不属于单工具/团队托管执行器 |
+| `opencode` | OpenCode | 安装、检测与登录体检；尚未完成受限执行入口核验 |
+| `stepcode` | Step Code | 安装、检测与登录体检；尚未完成受限执行入口核验 |
 | `zcode` | ZCode | Windows；经审批的 `workspace-write` |
 
-安装使用固定官方 npm 包的 `@latest`，或 ZCode 官方、经过发布者签名验证的 Windows 安装器。已安装版本比查询到的最新版更高时不会降级。最新版查询缓存约 12 小时；离线/查询失败时保持未知。厂商新版本没有自动获得本项目验证。ZCode 打开安装窗口后，仍需手动选目录并完成安装。
+安装使用固定官方 npm 包的 `@latest`、厂商官方安装脚本，或 ZCode 官方、经过发布者签名验证的 Windows 安装器。已安装版本比查询到的最新版更高时不会降级。最新版查询缓存约 12 小时；离线/查询失败时保持未知。厂商新版本没有自动获得本项目验证。ZCode 打开安装窗口后，仍需手动选目录并完成安装。
+
+**统一安装设置。** 在**官方工具**页顶部（或插件设置页）可以一次设定所有工具的安装目录与下载源：统一安装目录（留空=各厂商默认位置）、npm 源地址，以及按工具 ID 覆盖厂商安装脚本的镜像地址。目录必须是绝对路径，下载地址必须是 https。每个工具都可以在**安装方式**下拉框里单独选择 `npm`、`pnpm`、厂商安装脚本（`curl | bash` 或 `irm | iex`）；选了某个平台不支持的方式时，行内会写明原因而不是悄悄换成别的。每行上方实时显示将要执行的完整命令。
+
+**脚本方式不会把远程内容直接管道给解释器。** 插件先下载厂商安装脚本、核对它仍然是该厂商的官方脚本（校验厂商标记、拒绝 HTML 页面和其他厂商的脚本），再执行本地副本。镜像可以重新托管同一个脚本，但不能替换成别的程序。阶跃的脚本还支持安装目录参数，OpenCode 的官方脚本写死了 `~/.opencode/bin`，因此自定义安装目录对它只能通过 npm/pnpm 的 `--prefix` 生效。脚本方式可以整体关闭，只保留包管理器方式。
+
+**一键修复与一键卸载。** 修复会用同一条固定官方命令重新安装一遍，适合修复损坏或不完整的安装；卸载只删除程序本身——包管理器安装走同一个管理器卸载，脚本安装只删除厂商安装器放下的那一个可执行文件，并顺带清掉它在 shell 配置里写的 PATH 记录。**配置、登录信息和历史记录一律保留**，重新安装后仍在。
 
 **已安装、可信入口就绪、账号已登录、模型有权限是不同状态。** 登录未知不代表已退出。在 Windows，托管入口按发布者签名或官方 npm tarball 校验；ZCode 另对签名构建中的脚本记录首次信任摘要。平台细则见[注册表](.dsh-plugin/shared/official-tool-registry.mjs)和[执行器](.dsh-plugin/shared/official-tool-executor.mjs)。
 
+会话内可用 `/tools install|uninstall|repair|method <工具id> [安装方式]`；Agent 可调用 `model_router_tool_install`、`model_router_tool_repair` 和 `model_router_tool_uninstall`。安装目录与下载源始终来自用户自己的插件设置，不会由客户端或 Agent 传入，因此任何一条调用都无法把安装指向自定义包名或任意地址。
+
 `model_router_execute` 的固定无界面适配器为 Claude、Codex 和 Gemini；其他供应商经模型目录 API 或适用的订阅路线执行。CLI 缺失/不可用时可回退 API；真正尝试后的订阅失败按下方策略处理。
 
 可编辑执行要求干净 Git 仓库、Harness 审批与进程沙箱。修改先在独立工作树进行，执行成功且原仓库仍干净并匹配时才整合源码补丁；执行或整合失败会明确报告。Git 忽略的输出另行检查。只读参数不一定把可读文件限制在工作区，尤其需在**安全边界**核对 Codex 的较大可读范围。

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -97,14 +97,44 @@
 
 ## 官方工具：体检、安装与登录
 
-当前注册表包括 Kimi、Claude、Codex、MiniMax、MiMo、Grok、Gemini 和 ZCode。点**重新体检**查看实际安装、版本、入口及账号状态；最新版查询失败时保持未知，不表示已无更新。
+当前注册表包括 Kimi、Claude、Codex、MiniMax、MiMo、Grok、Gemini、OpenCode、Step Code 和 ZCode。点**重新体检**查看实际安装、版本、入口及账号状态；最新版查询失败时保持未知，不表示已无更新。
 
 1. 未安装时可从卡片固定官方来源安装；npm 工具安装厂商 `@latest`。新厂商版本没有自动通过本项目测试。
 2. 安装中可查看日志或取消；取消后重新体检确认状态。
 3. 有更新时可更新；已安装版本比查询结果更高时不会降级。
-4. 已安装但未就绪时查看入口/平台原因，使用适用的修复动作；仅检测到文件不能证明可信执行。
-5. ZCode 打开官方安装窗口后，还需要手动选目录完成安装，再体检。它属于 Windows 桌面应用。
-6. 按**去登录**提示，在对应 CLI/终端完成厂商授权，然后用小任务验证权限。
+4. 已安装但未就绪时点**一键修复**，用同一条固定命令重新安装一遍。
+5. 不再需要时点**一键卸载**，只删除程序本身；配置、登录信息和历史记录保留，重新安装后仍在。
+6. ZCode 打开官方安装窗口后，还需要手动选目录完成安装，再体检。它属于 Windows 桌面应用，由系统“应用”卸载。
+7. 按**去登录**提示，在对应 CLI/终端完成厂商授权，然后用小任务验证权限。
+
+### 统一安装设置
+
+卡片顶部**统一安装设置**一次设定所有工具的安装地址，改动后下一次安装、修复、卸载立即使用。插件设置页里有同样的字段。
+
+| 设置 | 作用 | 限制 |
+| --- | --- | --- |
+| 统一安装目录 | 所有一键安装的目标目录 | 必须是绝对路径，不能是磁盘或共享根目录；留空=各厂商默认位置 |
+| npm 源地址 | npm / pnpm 方式的下载源 | 必须 https，可填国内镜像 |
+| 安装脚本源覆盖 | 按工具 ID 指定厂商安装脚本的镜像 | JSON，键是官方工具 ID，值是 https 链接 |
+| 允许 curl / irm 安装脚本 | 是否允许执行厂商安装脚本 | 关闭后只剩 npm / pnpm |
+
+几个容易踩的点：
+
+- **不同工具对"自定义目录"的支持不一样。** npm 与 pnpm 都接受 `--prefix`，所以一定生效。阶跃的安装脚本接受 `--install-dir`（Windows 上是 `-InstallDir`），也生效。OpenCode 的官方脚本把路径写死成 `~/.opencode/bin`，**无法**接受自定义目录——如果设置里填了目录，它的行内会明确写出将装到哪里。
+- **脚本方式不是把远程内容直接交给解释器。** 插件会先下载脚本、核对它仍然是该厂商的官方安装脚本，再执行本地副本；HTML 报错页和其他厂商的脚本都会被拒绝执行。镜像可以重新托管同一个脚本，不能替换成别的程序。阶跃的脚本源覆盖还会同时改写它下载二进制与校验和的地址，所以镜像需要提供完整的发布文件。
+- **每行可以单独选安装方式。** 下拉框里列出该工具声明的全部方式；当前系统不支持的方式会写明原因，而不是悄悄换成别的。选中某个工具的方式会保存成该工具的默认，`/tools` 和 Agent 工具也会照此执行。
+- **命令是可见的。** 每行上方实时显示这条设置下真正会执行的完整命令，点击前就能核对。
+
+### 安装方式的会话与 Agent 等价物
+
+| 工作台操作 | 会话命令 | Agent 工具 |
+| --- | --- | --- |
+| 一键安装 / 更新 | `/tools install <工具id> [安装方式]` | `model_router_tool_install` |
+| 一键修复 | `/tools repair <工具id> [安装方式]` | `model_router_tool_repair` |
+| 一键卸载 | `/tools uninstall <工具id> [安装方式]` | `model_router_tool_uninstall` |
+| 查看可用方式 | `/tools method <工具id>` | `model_router_tools` 的 `installMethods` |
+
+安装目录与下载源只来自你自己的插件设置，不会由客户端或 Agent 传入；任何一条调用都无法把安装指向自定义包名或任意地址。安装和卸载都需要 Harness 审批。
 
 注册表 ID 和托管模式如下：
 
@@ -113,6 +143,7 @@
 | `claude-code`、`codex`、`mimo-code`、`grok-build` | 只读，以及经审批的可编辑执行。 |
 | `kimi-code`、`minimax-code`、`zcode` | 经审批的可编辑执行。 |
 | `gemini` | 路由无界面适配器，不进入单工具/团队托管执行器。 |
+| `opencode`、`stepcode` | 尚未核验受限执行入口；插件负责安装、检测与登录体检，执行请在终端中直接进行。 |
 
 ### 交互终端
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljwei-stak/dsh-model-router",
-  "version": "0.16.4",
+  "version": "0.17.0",
   "type": "module",
   "description": "Model Router for official DeepSeek Harness Desktop: cost-aware task routing, dependent work packages and official vendor CLI discovery, installation and execution. GAL is available separately as @ljwei-stak/dsh-galgame.",
   "repository": {
@@ -54,6 +54,7 @@
     ".dsh-plugin/shared/official-tools-remote.mjs",
     ".dsh-plugin/shared/official-tool-executor.mjs",
     ".dsh-plugin/shared/task-executors.mjs",
+    ".dsh-plugin/shared/tool-install-preferences.mjs",
     ".dsh-plugin/shared/vendor-minimax-adapter.mjs",
     ".dsh-plugin/shared/vendor-mimo-grok-adapter.mjs",
     ".dsh-plugin/shared/latest-versions.mjs",
@@ -102,7 +103,7 @@
     "experiment:routing-summary": "node scripts/summarize-routing-search.mjs",
     "experiment:routing-adaptive": "node scripts/adaptive-routing-study.mjs",
     "audit:livebench": "node scripts/livebench-aggregate-audit.mjs",
-    "test": "node --test tests/adaptive-*.test.mjs tests/dynamic-data.test.mjs tests/router.test.mjs tests/routing-optimizer.test.mjs tests/routing-evaluation.test.mjs tests/routing-paired-statistics.test.mjs tests/routing-selftest-tools.test.mjs tests/livebench-aggregate-audit.test.mjs tests/livebench-prior-study.test.mjs tests/routing-search-experiment.test.mjs tests/routing-regression-study.test.mjs tests/routing-search-summary.test.mjs tests/harness-*.test.mjs tests/official-tools.test.mjs tests/official-team-runtime.test.mjs tests/model-profiles.test.mjs tests/model-profile-editor.test.mjs tests/tool-install-state.test.mjs tests/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/task-executors.test.mjs tests/roadmap.test.mjs tests/insights-state.test.mjs tests/billing-team-ledger.test.mjs tests/subscription-billing.test.mjs tests/subscription-host.test.mjs tests/test-pass-regressions.test.mjs tests/roadmap-gaps.test.mjs tests/cordis-inject.test.mjs tests/cli-terminal.test.mjs tests/cli-terminal-gateway.test.mjs tests/latest-versions.test.mjs",
+    "test": "node --test tests/adaptive-*.test.mjs tests/dynamic-data.test.mjs tests/router.test.mjs tests/routing-optimizer.test.mjs tests/routing-evaluation.test.mjs tests/routing-paired-statistics.test.mjs tests/routing-selftest-tools.test.mjs tests/livebench-aggregate-audit.test.mjs tests/livebench-prior-study.test.mjs tests/routing-search-experiment.test.mjs tests/routing-regression-study.test.mjs tests/routing-search-summary.test.mjs tests/harness-*.test.mjs tests/official-tools.test.mjs tests/official-team-runtime.test.mjs tests/model-profiles.test.mjs tests/model-profile-editor.test.mjs tests/tool-install-state.test.mjs tests/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/task-executors.test.mjs tests/tool-install-preferences.test.mjs tests/roadmap.test.mjs tests/insights-state.test.mjs tests/billing-team-ledger.test.mjs tests/subscription-billing.test.mjs tests/subscription-host.test.mjs tests/test-pass-regressions.test.mjs tests/roadmap-gaps.test.mjs tests/cordis-inject.test.mjs tests/cli-terminal.test.mjs tests/cli-terminal-gateway.test.mjs tests/latest-versions.test.mjs",
     "prepack": "node scripts/prepack.mjs",
     "pack:local": "npm pack --pack-destination dist"
   },