@ljwei-stak/dsh-model-router 0.18.2 → 0.20.0

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'

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.20.0 — 2026-10-15
+
+Fully quit Harness, including its tray or WebUI Host process, and restart after upgrading.
+
+- Add **官方工具协作** to the workbench launcher for **团队分工**. Choose read-only checks or approved editing in an isolated Git worktree. Preview and the session tool share `planOfficialTeam` / `executeOfficialTeamPlan`, filter CLI readiness for the selected mode, execute dependency packages sequentially and record results. This executor has no automatic model-directory API fallback; editable integration retains the existing clean-source and matching-baseline checks.
+- Preserve every vendor CLI's configured model by default. Catalog recommendation IDs are no longer passed as implicit CLI model arguments. Only explicit `cliModel`, saved route mappings or team `cliModelsJson` select a CLI model; package bindings take precedence over tool bindings and saved mappings. ZCode keeps its per-call model limitation.
+- Retain verified CLI model, entry, sandbox, usage and reported-cost evidence through routed, single-tool and team records. Separate recommended, requested and actual reported model identities. Preserve a valid reported zero cost; incomplete usage or unknown/unmatched actual CLI model identity cannot be costed using a recommended catalog price.
+- Bind installation/version and CLI login-status checks to the actual selected npm, pnpm or native copy. Refuse silent PATH substitution when the saved installation cannot be resolved or its concrete entry is unavailable.
+- Keep Windows Codex's original `CODEX_HOME` under the reviewed Harness ACL state-directory contract for read-only tasks. Explicitly selected native editable teams can use Codex's own workspace-write policy. Real Codex network checks failed in this batch; they are not reported as accepted execution.
+- Store Windows isolated Git worktrees in Host-derived per-source private temporary storage. Real use exposed source drives with Modify permission but no WRITE_OWNER, where the SDK could not initialize its ACL boundary. Keep source authorization and patch checks, reject redirected storage, and preserve failed worktrees for retry. A no-model SDK confined-write and cross-drive integration probe passed.
+- Add an explicit **厂商 CLI 正常环境** option for editable official teams. It retains normal vendor state, shell, skills and MCP under current user permissions, outside Harness's process sandbox. Git worktrees collect changes rather than restrict OS access. Startup and retry require separate confirmation even when legacy direct-CLI confirmation is disabled; restricted runs never switch automatically. Native Kimi and ordinary npm MiniMax entries additionally require registry package/manifest/entry attestation.
+- Preserve bounded, scrubbed failure diagnostics and exit codes, including Claude result errors. Keep verified usage and reported costs after failures, cancellation and timeouts, mark partial usage incomplete, and retain earlier team results if a later adapter throws. Reassignment applies the new route's saved CLI model mapping.
+- Clear obsolete failure details after a successful rerun and display the stored execution mode accurately. Update the English/Chinese README and workbench guide, including the existing Windows ZCode bundled TUI terminal support.
+
+Real Windows validation: authenticated workbench RPC executed one Claude package; the installed production runtime then executed Claude analysis → MiniMax delivery with dependency context and source patch integration. Independent JSON readback passed. Successful calls report $0.253848 known API cost in total; earlier unknown amounts and unpriced subscription reference usage remain separate. File/shell tools passed; every MCP service and vendor are not claimed tested. See [validation evidence and limits](docs/releases/0.20.0-validation.md). Automated checks and exact totals are included in the GitHub release notes.
+
+Engineering checks: frozen-lockfile strict-peer install passed; 833 tests, 830 passed, 3 conditional skips, no failures; client build and generated-client consistency passed. Skipped process/PTY checks are not counted as real execution acceptance.
+
+## 0.19.0 — 2026-10-12
+
+Stable minor under the npm latest tag. Fully quit Harness (including its tray or WebUI Host process) and restart after upgrading.
+
+- Synchronize interactive terminal targets with the complete official-tool registry, adding OpenCode, Step Code and the verified Windows ZCode desktop-bundled TUI. Terminal refresh discovers current installations; older requests and health snapshots cannot restore stale target lists.
+- Resolve terminals from the saved package manager, package entry or private script directory. Refuse to launch a different PATH copy when the selected installation is missing. Fix Windows pipe fallback argument handling for command shims.
+- Add independent ZCode desktop-directory configuration in its tool card and plugin settings. Explicit selection is authoritative; missing, unsigned or modified bundles cannot silently fall back to another desktop. The built-in CLI follows desktop updates, while users configure login, models and plugins in TUI.
+- Offer separate desktop update checks and reinstall controls, preserve reviewed queued-job settings and refuse known downgrades or an unverified latest version. Opening an installer remains distinct from completed installation.
+- Fix ZCode discovery/installer signature checks under inherited PowerShell 7 module paths by using the Windows PowerShell system module directory. Prefer signed external Node 24 for TUI; a verified desktop Electron runtime can run the same bundled entry when Node is unavailable.
+- Add directory, refresh-race, desktop lifecycle and terminal launch regressions. Release notes record full validation and version-only probes of all ten installed CLI entries; no model requests were made.
+
 ## 0.18.2 — 2026-10-12
 
 Stable patch under the npm latest tag. Upgrade and fully restart Harness before using Step install, repair or update.

package/README.md

@@ -1,9 +1,13 @@
 # Model Router · DeepSeek Harness Desktop
 
-Version: **0.18.2**. See [routing research](docs/ROUTING_RESEARCH.zh.md), [mathematical derivation and experiments](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md), and the [LiveBench evidence audit and validation protocol](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md). The latest public 2026-06-25 score/cost tables are aggregates; its paired question-quality/cost matrix has not been obtained, and no real routing gain is claimed.
+Current release: **0.20.0**. See [routing research](docs/ROUTING_RESEARCH.zh.md), [mathematical derivation and experiments](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md), and the [LiveBench evidence audit and validation protocol](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md). The latest public 2026-06-25 score/cost tables are aggregates; its paired question-quality/cost matrix has not been obtained, and no real routing gain is claimed.
 
 A cost-aware model-routing workbench for **DeepSeek Harness Desktop**. Describe a task, compare your configured models, inspect the plan, and explicitly choose when to execute it.
 
+**0.20.0:** **官方工具协作** runs dependent team packages with official CLIs and no automatic API fallback. For editable tasks, explicitly choose **Harness 受限环境** or **厂商 CLI 正常环境**. The latter retains normal vendor login, configuration, skills and MCP under current user permissions, requires a separate confirmation, and uses a Git worktree to collect changes rather than restrict OS access. CLIs keep their configured model unless explicitly mapped. Real Windows Claude execution and a Claude → MiniMax dependency handoff with file integration passed; see [validation and limits](docs/releases/0.20.0-validation.md).
+
+**0.19.0:** interactive terminals follow the full registry and saved installation, including OpenCode, Step and the ZCode desktop-bundled TUI. ZCode has independent desktop-directory configuration and desktop update/reinstall controls; its bundled CLI follows desktop updates. Fresh terminal discovery discards stale responses.
+
 **0.18.2:** isolates configurable vendor scripts beneath the shared install root, preventing Step from replacing other tools’ npm packages. Gemini/OpenCode installation success is separate from restricted execution support; Windows Gemini uses its verified package entry through Node. Upgrade and restart Harness before updating Step.
 
 **0.18.1:** fixes install-method selection stuck on saving. Saved volatile settings now update Host install preferences immediately; command previews refresh separately from tool inspection.
@@ -20,7 +24,7 @@ A cost-aware model-routing workbench for **DeepSeek Harness Desktop**. Describe
 
 **0.16.0:** [dynamic data and adaptive feedback](docs/ROUTING_ADAPTIVE_LEARNING.zh.md) adds opt-in public benchmark/curated fixed-USD pricing refresh and task-specific, time-decayed, shrinkage-regularized subjective utility. Objective proxy quality floors remain separate. Public sources default off; preferences are shared within one local DSH_HOME and limited to the latest 200 runs. This is not a universal vendor-price scraper or evidence of real quality–cost gains.
 
-Current version: **0.18.2** (`@ljwei-stak/dsh-model-router`). Its declared host compatibility is **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
+Current version: **0.20.0** (`@ljwei-stak/dsh-model-router`). Its declared host compatibility is **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
 
 **0.15.0 changes:** a four-tab workbench with routing advice directly below task planning, protection against stale execution previews, preserved spending totals across history pruning and retries, and a standalone mock UI preview for source development.
 
@@ -36,9 +40,9 @@ For self-testing, follow the [desktop acceptance and quality–cost experiment s
 | Model configuration | Reads exact `provider/model` routes from Harness; optional user-supplied quality, USD prices, specialties, CLI model names, execution and billing preferences. |
 | Routing presets | Economy, balanced and quality-first presets; quality floors, estimated token costs and bounded assignment search. Missing prices stay unknown. |
 | Read-only execution | Preview and confirm a routed run from the workbench, or invoke it in an official Harness session. Supported headless CLIs and model-directory API calls return recorded results. |
-| Editable CLI execution | One supported official CLI or a sequential CLI team, using approved isolated Git worktrees and conditional patch integration. |
+| Editable CLI execution | A sequential CLI team from the workbench, or one supported CLI from a session, using approved isolated Git worktrees and conditional patch integration. |
 | Official tools | Detect, install/update, check launch readiness and inspect login status for ten registry tools; installation jobs have logs and cancellation. |
-| Interactive terminal | PowerShell/system shell and seven CLI targets, including fixed login commands, live output and multiple sessions. |
+| Interactive terminal | PowerShell/system shell and all ten registry CLI targets (ZCode TUI on verified Windows desktop installs), including fixed login commands, live output and multiple sessions. |
 | Costs and subscriptions | Daily/monthly budget checks, economy downgrade or pause, subscription-first routing, quota cooldown and explicit handling of other subscription failures. |
 | History and quality | Per-package results, dependency views, failure details, rerun/reassignment, ratings and optional stronger-model review. |
 | Execution boundaries | Shows what each route can read/write and whether its process uses the Harness sandbox. |
@@ -52,16 +56,16 @@ Generating a route recommendation is local: it does not start a vendor CLI or ma
 Open **Plugins → Add plugin** and enter:
 
 ```text
-@ljwei-stak/dsh-model-router@0.18.2
+@ljwei-stak/dsh-model-router@0.20.0
 ```
 
-Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.18.2** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
+Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.20.0** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
 
 You can instead install a local `.tgz` archive or its extracted inner `package` directory through the plugin manager. Both must contain `package.json` and `.dsh-plugin`. See [releases](https://github.com/Alice-Marx/dsh-model-router/releases) for archived builds, or build your own checkout below.
 
 ### Upgrade from the old package name
 
-The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.18.2`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
+The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.20.0`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
 
 For the combined 0.11.x package, back up the profile and export the GAL saves you want to preserve before upgrading. Story playback, artwork, music and saves now belong to the independent `@ljwei-stak/dsh-galgame` package. The detailed save limitations are in [MIGRATION.md](docs/archive/MIGRATION.md).
 
@@ -71,7 +75,7 @@ The 0.15.0 workbench groups the workflow into four navigation tabs. Its header s
 
 | Tab | What you do there |
 | --- | --- |
-| **任务与执行** — Task and execution | Describe the task, select a planning mode, generate advice, preview a read-only run and inspect run history. |
+| **任务与执行** — Task and execution | Describe the task, generate advice, choose routed read-only execution or official CLI teamwork, preview and confirm, then inspect history. |
 | **模型配置** — Model configuration | Refresh/search the model directory and edit exact-route profiles. |
 | **官方工具** — Official tools | Complete onboarding checks, inspect/install tools and use the interactive terminal. |
 | **预算与安全** — Budget and security | Set routing/cost/review policies and inspect subscription status and execution boundaries. |
@@ -86,8 +90,8 @@ Switching tabs keeps the panels mounted, preserving in-progress installation and
 2. Optionally enter quality and prices for the routes you want compared. Prices are **USD per million tokens**; quality is a user-supplied **0–100** estimate. Leave unknown prices blank rather than entering zero.
 3. In **任务与执行**, describe concrete deliverables, constraints and acceptance criteria. Select **单任务** (single recommendation), **团队分工** (dependent packages for sufficiently complex requests), or **指定模型** (one exact route, without comparing others). Team mode alone does not start any team.
 4. Set the per-run estimate target; `0` removes that planning constraint. Click **生成路由建议**. The result appears directly below planning. Check the route, complexity, cost, execution channel and each package's dependencies/checklist.
-5. For a real read-only run, use **在工作台执行**. Enter an existing absolute workspace path, or reuse the last run's path. Click **预览执行计划**, review the current route and all required confirmations, then explicitly confirm execution. The Host rechecks the plan before starting; changed conditions can require confirmation again.
-6. Inspect **执行记录与子任务** for the actual channel, response, failures, cost and ratings. Editable CLI tasks start from an official Harness session using the tools below.
+5. In **在工作台执行**, choose **模型路由（只读）** for the existing routed executor, or first select **团队分工** and choose **官方工具协作**. For official teamwork, select **只读检查** or **编辑文件**. Enter an existing absolute workspace path, or reuse the last run's path. Click **预览执行计划**, review each package, its permissions and required confirmations, then explicitly confirm execution. The Host rechecks the plan before starting; changed conditions can require confirmation again.
+6. Inspect **执行记录与子任务** for the actual channel, response, failures, cost and ratings. Official teamwork replans using only installed CLIs ready for the selected permission mode. Edits require approval and a clean Git repository; successful worktree changes are conditionally integrated. An unavailable or failed CLI never silently becomes an API call in this mode.
 
 Changing task text, planning mode, profiles, directory or relevant settings invalidates the prior recommendation. Changing execution inputs also discards the pending or completed preview, so execution requires a new preview of the current request. Previewing execution uses current Host state and can differ from a previous local plan.
 
@@ -134,7 +138,7 @@ A read-only single-tool request:
 {"tool":"codex","task":"Inspect the repository and list UI layout issues; do not edit files","mode":"read-only"}
 ```
 
-Supply `provider` and `model` together when selecting an exact catalog route. A vendor's CLI model name may differ from its Harness id; use `cliModel` or team `cliModelsJson` only for names verified with that CLI. ZCode uses its own default and cannot switch model per call. Most CLIs do not report a verifiable actual model id; check the vendor run record.
+Supply `provider` and `model` together when selecting an exact catalog route. All CLIs retain their own configured model by default; a catalog recommendation is never automatically passed as a CLI model argument. To switch explicitly, save a verified **官方 CLI 模型名** in the route profile, pass `cliModel` for one tool call, or use team `cliModelsJson`. Team bindings prefer a package id, then a tool id, then the saved route mapping. ZCode uses its own default and cannot switch model per call. History records the recommendation, requested CLI name and reported actual model separately; a request is not proof of the model used. Check vendor records when no actual model is reported.
 
 The CLI team runner is the plugin's own sequential dependency executor. It does not control the model selection or lifecycle of Harness's built-in Agent Teams.
 
@@ -144,7 +148,7 @@ The CLI team runner is the plugin's own sequential dependency executor. It does
 | --- | --- | --- |
 | `kimi-code` | Kimi Code | Approved `workspace-write` |
 | `claude-code` | Claude Code | `read-only`, approved `workspace-write` |
-| `codex` | Codex CLI | `read-only`, approved `workspace-write` |
+| `codex` | Codex CLI | Windows managed `read-only`; editable execution is currently unsupported |
 | `minimax-code` | MiniMax Code | Approved `workspace-write` |
 | `mimo-code` | MiMo Code | `read-only`, approved `workspace-write` |
 | `grok-build` | Grok Build | `read-only`, approved `workspace-write` |
@@ -170,15 +174,19 @@ With no shared directory, ordinary checks discover the selected manager's packag
 
 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.
 
+Version and CLI login-status checks use the selected installation's concrete entry. A missing selected copy cannot be replaced by a different command on PATH; its login status remains unknown when that entry cannot be checked.
+
 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.
 
+For Windows Codex tasks in the Harness environment, only read-only is available: the outer ACL sandbox grants the original `CODEX_HOME` state and a private temporary directory, while Codex retains `--sandbox read-only`. Explicitly confirmed native editable teams can use Codex with its own workspace-write policy. Codex network readiness remains account/environment dependent and did not pass the real connection checks in this batch.
+
 ### Interactive terminal
 
-In **官方工具 → 官方工具终端**, select the shell or an installed CLI, choose interactive/login mode where available, enter an existing absolute directory, and review the startup confirmation. ZCode is a desktop app and is not a terminal target.
+In **官方工具 → 官方工具终端**, select the shell or an installed CLI, choose interactive/login mode where available, enter an existing absolute directory, and review the startup confirmation. Verified Windows ZCode desktop installations provide their bundled TUI as a terminal target.
 
 These sessions run **outside the Harness sandbox**, with the Host user's login environment, proxies and API-key variables. Commands typed there can read/write files with that user's permissions. Terminal launches are separate from routed execution and its approval/billing policy.
 
@@ -191,7 +199,7 @@ The plugin does not persist terminal input/output. It stores session metadata on
 - **Budgets:** per-run planning target plus daily/monthly checks. Over-budget routing can try the economy preset or pause for confirmation. Unknown prices remain unknown. These are local accounting/estimation controls, not a hard provider billing cap.
 - **Subscription-first:** the default is to prefer a detected CLI account subscription or a configured coding-plan route. API-key environment variables are removed for CLI subscription attempts. `billing` can be `subscription-first`, `api-only` or `subscription-only`; `subscription` can be `cli-login`, `plan-key` or `none`.
 - **Fallback:** detected quota exhaustion/rate limits mark a subscription in cooldown and can retry the routed step on its configured API route, subject to policy and availability. Other attempted subscription failures pause by default (`onSubscriptionFailure: "ask"`): choose API retry, subscription retry or cancel in history. Managed editable/single-tool/team runs do not automatically retry on the API.
-- **Accounting:** API costs count toward budgets. Subscription runs display an API-price reference cost separately. Actual usage is taken from CLI-reported amounts or token usage and supplied prices when available; provider bills remain authoritative. Version 0.15.0 retains spending from evicted detailed runs and replaced retry results, so trimming history or retrying a step does not erase earlier charges. Costs already discarded by older versions cannot be reconstructed.
+- **Accounting:** API costs count toward budgets. Subscription runs display a reference cost separately. A valid CLI-reported amount, including zero, takes precedence. Token-based CLI cost requires complete usage and an actual reported model matching a configured model or its explicit CLI mapping; unknown or mismatched identity keeps cost unknown. The recommendation's price alone cannot establish actual CLI cost. Provider bills remain authoritative. Version 0.15.0 retains spending from evicted detailed runs and replaced retry results, so trimming history or retrying a step does not erase earlier charges. Costs already discarded by older versions cannot be reconstructed.
 - **Quality and preference:** optional `off`/`sample`/`always` stronger-model review can add paid calls; it is not treated as human feedback. Explicit ratings adjust separate subjective utility for the exact route and task type, using time decay and low-sample shrinkage (default limit ±0.04, configurable up to ±0.1). They do not change objective quality scores or their hard floors; learning can be disabled, ratings withdrawn, or its starting point reset.
 
 Coding-plan keys and endpoints stay in Harness provider settings. A `plan-key` profile may name an exact configured `apiRoute` as its fallback; the profile editor does not accept credentials or arbitrary commands. Vendor plan eligibility and terms must be checked with the vendor.

package/README.zh.md

@@ -1,9 +1,13 @@
 # Model Router · DeepSeek Harness 模型路由插件
 
-版本：**0.18.2**。选模求解器概览见[路由研究说明](docs/ROUTING_RESEARCH.zh.md)；公式、条件证明与实验见[数学推导与实验记录](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md)。[LiveBench 最新证据与验证协议](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md)已核查 2026-06-25 聚合评分/费用；最新逐题质量—费用矩阵尚未取得，不声称真实路由收益。
+当前版本：**0.20.0**。选模求解器概览见[路由研究说明](docs/ROUTING_RESEARCH.zh.md)；公式、条件证明与实验见[数学推导与实验记录](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md)。[LiveBench 最新证据与验证协议](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md)已核查 2026-06-25 聚合评分/费用；最新逐题质量—费用矩阵尚未取得，不声称真实路由收益。
 
 为 **DeepSeek Harness Desktop** 提供任务规划、成本感知的模型分配和官方工具执行工作台。输入任务，比较已配置模型，审阅计划，再明确选择是否执行。
 
+**0.20.0**：工作台新增**官方工具协作**，按依赖执行官方 CLI 工作包，不自动回退 API。编辑任务可明确选择 **Harness 受限环境**或**厂商 CLI 正常环境**；后者以当前用户权限保留原登录、配置、技能和 MCP，单独确认后才启动，Git 工作树用于改动回收，不构成操作系统读写边界。CLI 默认使用自身模型，仅显式映射才切换。Windows Claude 实际执行、Claude → MiniMax 依赖交接与补丁整合已通过，见[验收与限制](docs/releases/0.20.0-validation.md)。
+
+**0.19.0**：官方工具终端同步完整注册表与保存的安装目录，补齐 OpenCode、Step 和 ZCode 内置 TUI。ZCode 可单独保存桌面目录、检查更新和重新安装；内置 CLI 随桌面版更新。终端刷新重新发现工具并丢弃迟到结果。
+
 **0.18.2**：厂商脚本使用统一根目录下的工具专属子目录，修复 Step 安装替换其他 npm 工具包的问题。Gemini/OpenCode 安装成功与受限执行能力分别显示；Windows Gemini 使用核验后的包入口通过 Node 启动。先升级并重启 Harness，再更新 Step。
 
 **0.18.1**：修复安装方式切换卡在“保存方式中…”的问题。已保存设置立即同步到宿主安装配置，命令预览单独刷新；工具体检延迟时仍能继续切换方式。
@@ -20,7 +24,7 @@
 
 **0.16.0 新增**：[动态数据与持续反馈](docs/ROUTING_ADAPTIVE_LEARNING.zh.md)：可选公开价格/LiveBench快照刷新；按任务类型、时间衰减和低样本收缩调整个人偏好，质量门槛独立保留。设置在“预算与安全”，公开源默认关闭；价格源需提供按官方文档核对的固定USD单价JSON，不是通用官网抓价器。本地DSH_HOME共享、最近200运行窗口，暂无真实收益证明。
 
-当前版本为 **0.18.2**，包名为 `@ljwei-stak/dsh-model-router`；声明兼容的宿主为 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**。自 0.12.0 起，路由与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 已拆成两个独立插件。
+当前版本为 **0.20.0**，包名为 `@ljwei-stak/dsh-model-router`；声明兼容的宿主为 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**。自 0.12.0 起，路由与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 已拆成两个独立插件。
 
 **0.15.0 更新**：工作台分为四页，路由建议紧接任务规划展示；执行输入变化时丢弃旧预览；裁剪历史或重试后仍保留费用累计；源码开发新增独立模拟 UI 预览。
 
@@ -36,9 +40,9 @@
 | 模型配置 | 读取 Harness 官方目录中的准确 `provider/model`；可填写自报质量、美元单价、专长、CLI 模型名、执行与计费偏好。 |
 | 路由方案 | 省钱优先、均衡、效果优先；按质量门槛、预估 token 成本与有限组合搜索分配模型。未知价格保持未知。 |
 | 只读执行 | 工作台先预览、再确认执行；也可在官方会话调用工具。支持的无界面 CLI 或模型目录 API 返回结果并留存记录。 |
-| 可编辑执行 | 通过官方会话启动单个 CLI 或顺序 CLI 团队，经审批在独立 Git 工作树修改，满足条件后整合补丁。 |
+| 可编辑执行 | 工作台启动顺序 CLI 团队，或官方会话启动单个支持的 CLI；经审批在独立 Git 工作树修改，满足条件后整合补丁。 |
 | 官方工具 | 十个固定注册表工具的检测、安装/更新、可信入口与登录体检；安装有日志和取消操作。 |
-| 交互终端 | 系统终端/PowerShell 与七个 CLI，含固定登录命令、多会话和实时输出。 |
+| 交互终端 | 系统终端/PowerShell 与十个注册表 CLI（ZCode TUI 使用已核验的 Windows 桌面安装），含固定登录命令、多会话和实时输出。 |
 | 成本与订阅 | 每日/月度预算检查、自动尝试省钱方案或暂停、订阅优先、额度冷却，以及其他订阅失败的确认流程。 |
 | 执行与质量记录 | 逐工作包结果、依赖图、失败详情、重跑/改派、用户评价与可选强模型复核。 |
 | 执行边界 | 显示每条路线可读/可写范围，以及是否经过 Harness 进程沙箱。 |
@@ -52,7 +56,7 @@
 打开 **插件 → 添加插件**，填写：
 
 ```text
-@ljwei-stak/dsh-model-router@0.18.2
+@ljwei-stak/dsh-model-router@0.20.0
 ```
 
 镜像缺少该精确版本时使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。安装并启用后，完全退出 Harness（包括托盘进程）再启动。插件详情应显示 **0.18.2**，侧栏出现**模型路由**。仅运行全局 `npm install -g` 不会把插件注册到桌面版 profile。
@@ -61,7 +65,7 @@
 
 ### 从旧包名升级
 
-`@ljwei-stak/model-router-galgame` 的最后版本为 0.13.0。保留 profile 与应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.18.2`。不要同时安装两个包：它们共用内部插件 id `model-router-galgame` 与工具名；id 保留使已有路由设置和执行历史能够延续。
+`@ljwei-stak/model-router-galgame` 的最后版本为 0.13.0。保留 profile 与应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.20.0`。不要同时安装两个包：它们共用内部插件 id `model-router-galgame` 与工具名；id 保留使已有路由设置和执行历史能够延续。
 
 从 0.11.x 合并版迁移时，先备份 profile 并导出希望保留的 GAL 进度。剧情、立绘、音乐、自由模式和存档属于独立 `@ljwei-stak/dsh-galgame` 插件。导出范围及同 profile 迁移的限制见 [MIGRATION.md](docs/archive/MIGRATION.md)。
 
@@ -71,7 +75,7 @@
 
 | 页面 | 操作内容 |
 | --- | --- |
-| **任务与执行** | 写任务、选规划模式、生成建议、预览只读执行、查看逐步骤历史。 |
+| **任务与执行** | 写任务、生成建议，选择模型路由只读执行或官方工具协作，预览确认后查看逐步骤历史。 |
 | **模型配置** | 刷新/搜索官方模型目录，编辑每条准确路线的能力与价格档案。 |
 | **官方工具** | 完成首次体检，检测/安装工具，使用交互终端。 |
 | **预算与安全** | 设置路由、预算、复核策略，查看订阅状态和执行范围。 |
@@ -86,8 +90,8 @@
 2. 为参与比较的路线填写可选档案。质量分为你提供的 **0–100** 估值；输入/输出单价单位是 **USD / 百万 token**。不知道价格就留空，不要把未知填成零。
 3. 在**任务与执行**写清交付物、约束与验收标准。**单任务**推荐一条路线；**团队分工**为足够复杂的任务拆依赖工作包；**指定模型**直接选一个准确路线，跳过其他模型比较。选团队模式不会自动启动团队。
 4. 设置本次估算目标；`0` 表示不限制本次规划。点**生成路由建议**，结果直接出现在任务规划后方。核对路线、复杂度、费用、执行渠道，以及每包依赖和验收清单。
-5. 需要实际只读执行时，使用**在工作台执行**，填写存在的工作区绝对路径（留空沿用上次运行）。先点**预览执行计划**，审阅当前路线和所有确认项，再明确确认执行。宿主启动前会再次检查；状态变化时可能要求重新确认。
-6. 在**执行记录与子任务**查看实际通道、回答、错误、费用与评价。需要 CLI 修改文件时，在 Harness 官方会话中调用下方可编辑工具。
+5. 在**在工作台执行**选择**模型路由（只读）**，或先在上方选择**团队分工**，再选**官方工具协作**。官方协作可选**只读检查**或**编辑文件**。填写存在的工作区绝对路径（留空沿用上次运行），点**预览执行计划**，核对每包路线、权限和全部确认项，再明确确认执行。宿主启动前会再次检查；状态变化时可能要求重新确认。
+6. 在**执行记录与子任务**查看真实渠道、回答、失败、费用和评价。官方协作按所选权限下已安装、入口就绪的 CLI 重新规划；编辑要求审批和干净 Git 仓库，成功后满足条件才整合补丁。该模式下 CLI 不可用或失败均不自动转为 API 调用。
 
 更改任务、模式、模型档案、目录或相关设置后，需要重新生成建议。更改执行输入会丢弃正在请求或已经返回的旧预览，必须重新预览当前请求才能确认执行。执行预览采用宿主当前状态，因此可能与早先的本地建议不同。
 
@@ -134,7 +138,7 @@
 {"tool":"codex","task":"检查仓库 UI 排版并列出问题；不要修改文件","mode":"read-only"}
 ```
 
-指定目录路线时，`provider` 与 `model` 必须成对填写。厂商 CLI 模型名可能与 Harness ID 不同；只有在对应 CLI 验证后才设置 `cliModel` 或团队 `cliModelsJson`。ZCode 使用自身默认模型，不能逐次切换。多数 CLI 不回报可核验的实际模型 ID，需对照厂商运行记录。
+指定目录路线时，`provider` 与 `model` 必须成对填写。所有 CLI 默认保留自身配置模型，目录推荐 ID 不会自动作为 CLI 模型参数。需要显式切换时，在档案保存已验证的**官方 CLI 模型名**，单工具传 `cliModel`，或团队传 `cliModelsJson`；团队优先采用工作包 ID 映射，其次工具 ID，最后已保存的路线映射。ZCode 使用自身默认模型，不能逐次切换。历史分别记录推荐模型、请求 CLI 名和回报实际模型；请求参数不是实际模型证明，未回报时需对照厂商运行记录。
 
 CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams 的成员模型与生命周期仍由宿主管理。
 
@@ -144,7 +148,7 @@ CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams
 | --- | --- | --- |
 | `kimi-code` | Kimi Code | 经审批的 `workspace-write` |
 | `claude-code` | Claude Code | `read-only`、经审批的 `workspace-write` |
-| `codex` | Codex CLI | `read-only`、经审批的 `workspace-write` |
+| `codex` | Codex CLI | Windows 托管只读 `read-only`；暂不支持可编辑执行 |
 | `minimax-code` | MiniMax Code | 经审批的 `workspace-write` |
 | `mimo-code` | MiMo Code | `read-only`、经审批的 `workspace-write` |
 | `grok-build` | Grok Build | `read-only`、经审批的 `workspace-write` |
@@ -170,15 +174,19 @@ CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams
 
 **已安装、可信入口就绪、账号已登录、模型有权限是不同状态。** 登录未知不代表已退出。在 Windows，托管入口按发布者签名或官方 npm tarball 校验；ZCode 另对签名构建中的脚本记录首次信任摘要。平台细则见[注册表](.dsh-plugin/shared/official-tool-registry.mjs)和[执行器](.dsh-plugin/shared/official-tool-executor.mjs)。
 
+版本和 CLI 登录状态命令使用所选安装副本的实际入口。该副本缺失时不改用 PATH 中另一份命令；无法检查对应入口时，登录状态保持未知。
+
 会话内可用 `/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 的较大可读范围。
 
+Windows Codex 在 Harness 环境仅支持只读：外层 ACL 为原 `CODEX_HOME` 状态与私有临时目录授予写权限，Codex 内层保持 `--sandbox read-only`。明确选择并确认厂商正常环境后，可在可编辑团队中使用 Codex 自身 workspace-write 策略。本批 Codex 真实连接检查仍失败，账号与网络可用性须在本机另行确认。
+
 ### 官方工具终端
 
-在**官方工具 → 官方工具终端**选择系统终端或已安装 CLI、交互/登录方式和存在的工作区绝对路径，核对启动确认后运行。ZCode 是桌面应用，不属于终端目标。
+在**官方工具 → 官方工具终端**选择系统终端或已安装 CLI、交互/登录方式和存在的工作区绝对路径，核对启动确认后运行。核验成功的 Windows ZCode 桌面安装提供内置 TUI 终端目标。
 
 终端**不经过 Harness 沙箱**，继承 Host 用户的登录环境、代理及 API Key 环境变量。输入的命令可以按该用户权限读取/修改文件。终端与路由执行的审批和计费流程分别处理。
 
@@ -191,7 +199,7 @@ CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams
 - **预算**：本次规划目标与每日/月度执行检查分别生效。超预算可尝试省钱方案或暂停确认；缺少价格保持费用未知。它们是本机估算与核算机制，不是厂商账单的硬上限。
 - **订阅优先**：默认先使用检测到的 CLI 订阅账号或配置的编程套餐路线。尝试 CLI 订阅时去掉 API Key 环境变量。`billing` 可设 `subscription-first`、`api-only`、`subscription-only`；`subscription` 可设 `cli-login`、`plan-key`、`none`。
 - **回退**：识别到额度用尽/限流后，将订阅标记为冷却，并可按策略及可用性用已配置 API 路线重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`），在历史中选择 API 重试、重试订阅或取消。单工具/团队托管执行不会自动转 API 重试。
-- **核算**：API 费用计入预算；订阅单独展示按 API 单价折算的参考费用。实际用量可来自 CLI 自报金额，或 token 用量乘你提供的单价；真实消费以厂商账单为准。0.15.0 保留被裁剪历史和被重试结果替换的费用累计，避免重跑或清理详细历史抹掉此前消费；旧版本已经丢弃的费用无法反推恢复。
+- **核算**：API 费用计入预算；订阅单独展示参考费用。优先保留有效的 CLI 自报金额，包括零；按 token 折算 CLI 费用须有完整用量，且回报实际模型与已配置模型或其显式 CLI 映射匹配。实际模型未知或不匹配时，费用保持未知，不套用推荐路线的单价。真实消费以厂商账单为准。0.15.0 保留被裁剪历史和被重试结果替换的费用累计，避免重跑或清理详细历史抹掉此前消费；旧版本已经丢弃的费用无法反推恢复。
 - **质量与偏好**：强模型复核可设 `off`、`sample`、`always`，会增加真实调用，但不作为人工反馈。明确评价按准确路线和任务类型，以时间衰减及低样本收缩调整独立主观效用（默认上限 ±0.04，可配置至 ±0.1）；不修改客观质量分或质量硬门槛。可停用学习、撤回评价或重置学习起点。
 
 编程套餐 Key 与端点留在 Harness 官方供应商设置里。`plan-key` 档案可指定一个准确、已登记的 `apiRoute` 作为回退；模型档案不接收凭据或任意命令。套餐资格及使用条款须向厂商核对。

package/docs/INSTALLATION_GUIDE.zh.md

@@ -2,7 +2,7 @@
 
 模型路由从 **0.12.0** 起独立发布；GAL 是新的 **0.1.0** 插件。两者均声明支持官方 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**，可分别安装和更新。
 
-当前路由正式版为 **0.18.2**。本版修复 Step 安装覆盖共享 npm 包目录的问题：统一目录是安装根，厂商脚本使用工具专属子目录。Gemini 安装状态与受限执行能力分开，Windows 无界面启动使用核验后的包入口。先升级并完全退出 Harness 后重启，再使用 Step 更新/修复。保留 0.18.0 的官方安装方法、MiniMax 脚本校验和统一目录改进。统一安装设置需点击保存，再选择工具的安装方式。公开数据默认关闭；安装时选择下方精确版本。
+当前路由正式版为 **0.19.0**。官方终端同步已保存的安装目录和完整工具列表；ZCode 行可独立配置桌面目录，再从终端进入内置 TUI，自行配置登录、模型和插件。桌面版可单独检查更新或重新安装，内置 CLI 随桌面版更新。本版修复 Step 安装覆盖共享 npm 包目录的问题：统一目录是安装根，厂商脚本使用工具专属子目录。Gemini 安装状态与受限执行能力分开，Windows 无界面启动使用核验后的包入口。先升级并完全退出 Harness 后重启，再使用 Step 更新/修复。保留 0.18.0 的官方安装方法、MiniMax 脚本校验和统一目录改进。统一安装设置需点击保存，再选择工具的安装方式。公开数据默认关闭；安装时选择下方精确版本。
 
 [路由 README](../README.zh.md) · [迁移说明](archive/MIGRATION.md) · [独立 GAL README](https://github.com/Alice-Marx/deepseek-harness-galgame#readme)
 
@@ -10,7 +10,7 @@
 
 | 需求 | 添加插件输入框 | 安装后的入口 |
 | --- | --- | --- |
-| 分析复杂度、按质量和费用选模型、调用官方工具 | `@ljwei-stak/dsh-model-router@0.18.2` | 模型路由 |
+| 分析复杂度、按质量和费用选模型、调用官方工具 | `@ljwei-stak/dsh-model-router@0.19.0` | 模型路由 |
 | 剧情、立绘、音乐、存档、自由对话 | `@ljwei-stak/dsh-galgame@0.1.0` | Gal 模块 |
 | 两者都要 | 分别安装上面两个包 | 模型路由 + Gal 模块 |
 
@@ -24,7 +24,7 @@
 2. 在“包名、GitHub 仓库地址或本地目录路径”输入框填一个完整包名，例如：
 
    ```text
-   @ljwei-stak/dsh-model-router@0.18.2
+   @ljwei-stak/dsh-model-router@0.19.0
    ```
 
    只想安装 GAL 时填写：
@@ -40,7 +40,7 @@
    ```
 
 4. 核对预览的包名、版本和宿主兼容信息，安装并启用。完全退出 Harness（包括托盘进程）再启动，确保 Host 加载新代码。
-5. 检查插件详情与侧边栏：路由应为 **0.18.2 / 模型路由**；GAL 应为 **0.1.0 / Gal 模块**。仅装路由时没有 GAL 入口是预期行为。
+5. 检查插件详情与侧边栏：路由应为 **0.19.0 / 模型路由**；GAL 应为 **0.1.0 / Gal 模块**。仅装路由时没有 GAL 入口是预期行为。
 
 普通用户无需 `npm install -g`，该命令不会把插件注册到当前 Harness profile。
 
@@ -48,7 +48,7 @@
 
 进入对应 Release 下载 `.tgz`：
 
-- [模型路由 Releases](https://github.com/Alice-Marx/dsh-model-router/releases)（也可运行 `npm pack @ljwei-stak/dsh-model-router@0.18.2` 获取同一安装包）
+- [模型路由 Releases](https://github.com/Alice-Marx/dsh-model-router/releases)（也可运行 `npm pack @ljwei-stak/dsh-model-router@0.19.0` 获取同一安装包）
 - [独立 GAL v0.1.0](https://github.com/Alice-Marx/deepseek-harness-galgame/releases/tag/v0.1.0)
 
 在“添加插件”填写下载文件的**绝对路径**，例如：
@@ -74,7 +74,7 @@ Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-galgame-0
 
 1. 在旧合并插件的 GAL 播放器导出需要保留的剧情进度，并备份整个 Harness profile。每份 JSON 仅保存**当前剧情状态**，不含所有手动槽、设置、已读记录或本地音乐；重要槽位可依次读档再导出。
 2. 在**同一个 profile**安装独立 `@ljwei-stak/dsh-galgame@0.1.0`。
-3. 0.13.0 起包名改为 `@ljwei-stak/dsh-model-router`（旧包名最后版本为 0.13.0，内容相同，之后不再更新）：在插件管理器卸载原 `@ljwei-stak/model-router-galgame`（保留 profile 与应用数据），再添加 `@ljwei-stak/dsh-model-router@0.18.2`。不要两个同时安装（条目 id 与工具名相同）；条目 id 未变，路由设置与执行记录会保留。完成两项更新后再玩剧情，避免同时操作旧合并入口和新入口。
+3. 0.13.0 起包名改为 `@ljwei-stak/dsh-model-router`（旧包名最后版本为 0.13.0，内容相同，之后不再更新）：在插件管理器卸载原 `@ljwei-stak/model-router-galgame`（保留 profile 与应用数据），再添加 `@ljwei-stak/dsh-model-router@0.19.0`。不要两个同时安装（条目 id 与工具名相同）；条目 id 未变，路由设置与执行记录会保留。完成两项更新后再玩剧情，避免同时操作旧合并入口和新入口。
 4. 现在路由与 GAL 各有一个入口。独立 GAL 沿用旧存档 localStorage 键，核对当前进度和三槽；更换 profile 或进度未恢复时，先切换到匹配剧目，再导入 JSON 备份。
 5. 后续分别更新需要的插件；只用路由可以不启用或不安装 GAL。保留 profile 与应用数据，卸载插件时不要清理故事数据。
 

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -1,6 +1,8 @@
 # 模型路由工作台：配置、规划与实际执行
 
-适用版本：正式版 `@ljwei-stak/dsh-model-router@0.18.2`；声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2`。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](archive/MIGRATION.md)。
+适用版本：`@ljwei-stak/dsh-model-router@0.20.0`。声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2`。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](archive/MIGRATION.md)。
+
+0.20.0 在工作台增加**官方工具协作**和明确的执行环境选择。默认保留 CLI 自身配置的模型，分别记录推荐、请求和实际回报模型。Windows Claude 单包执行及 Claude → MiniMax 依赖交接、实际文件整合已通过；具体入口、费用和未验证范围见[验收记录](releases/0.20.0-validation.md)。
 
 0.15.0 新增四页布局、规划后直接展示路由建议、执行输入变化时丢弃旧预览，以及历史裁剪和重试后的费用累计保留。源码中的独立 UI 预览使用模拟数据，用于组件检查，不代表真实账号调用或桌面端到端验收。
 
@@ -28,7 +30,7 @@
 | 输入/输出单价 | 两项同时填写，单位 **USD / 百万 token**；未知留空，零表示确实按零价估算。 |
 | 缓存价 | 可选缓存读取/写入单价；应与相应供应商计费口径一致。 |
 | 擅长方向 | 英文小写标签，逗号分隔，例如 `code, reasoning`。 |
-| 官方 CLI 模型名 | 仅填厂商 CLI 已验证接受的名称；不等同于 Harness 模型 ID。ZCode 不支持逐次换模型。 |
+| 官方 CLI 模型名 | 留空保留 CLI 自身配置的模型；仅显式填写厂商 CLI 已验证接受的名称才切换，不自动传 Harness 模型 ID。ZCode 不支持逐次换模型。 |
 | LiveBench 准确模型名称 | 可选的显式基准映射，须确认模型版本与推理档位一致；不自动猜测别名，也不证明实际执行参数。 |
 | 执行方式 | `auto`、`official` 优先适用的官方工具；`api` 只走模型目录 API。 |
 | 计费方式 | 默认 `subscription-first`；也可指定 `api-only` 或 `subscription-only`。 |
@@ -68,15 +70,26 @@
 
 ## 在工作台执行：预览后确认
 
-**在工作台执行**沿用任务文本和规划模式，允许选择路由方案并填写工作区。它仅发起只读执行；需要 CLI 修改文件时使用官方会话。
+**在工作台执行**沿用任务文本和规划模式，允许选择执行方式、路由方案并填写工作区。
+
+| 执行方式 | 适用范围 |
+| --- | --- |
+| **模型路由（只读）** | 支持单任务、团队分工和指定模型；沿用路由 CLI/API 及订阅失败策略，保持只读。 |
+| **官方工具协作** | 先在上方选择**团队分工**；仅用当前模式已就绪的官方 CLI 顺序执行工作包，不自动回退 API。可选**只读检查**或**编辑文件**。 |
 
 1. 输入已经存在的工作区绝对路径，例如 `F:\projects\demo`；留空沿用上次运行的路径。
-2. 点击**预览执行计划**。宿主根据当前目录、登录、额度、预算和方案给出与 `model_router_execute` 相同的决策，包括适用的省钱降级。
-3. 核对预估费用、路线、工作包及全部确认项。超预算和直接启动无沙箱 CLI 的原因会合并展示。
+2. 选择执行方式；官方协作还需选择任务权限。点击**预览执行计划**。模型路由沿用 `model_router_execute` 的决策；官方协作与 `model_router_team_execute` 共用团队规划和执行逻辑，按所选权限筛选已配置路线、已安装且就绪的 CLI，因此可能与本地建议不同。
+3. 核对预估费用、每包路线、读写权限和全部确认项。**编辑文件**要求干净 Git 仓库与审批，先在独立工作树执行；全部步骤成功后，原仓库仍干净且基线匹配时才整合源码补丁。Git 忽略产物另行核查；整合失败会保留工作树供检查。
+
+Windows 独立工作树保存在用户私有临时目录中，按原仓库路径分别存储；避免原工程所在盘只有普通修改权限、无法初始化 Harness ACL 的情况。源工程权限不因该操作改变。失败后可从运行记录查看独立路径；系统清理临时目录后可能无法续跑，重要成果应及时审阅和归档。
+
+编辑权限下还需选择**执行环境**。默认 **Harness 受限环境**保留进程沙箱，但 Windows 后端会限制状态写入及部分子进程管道；登录成功不能消除这些限制。**厂商 CLI 正常环境**保留原登录、配置、技能和 MCP，以当前用户权限运行，启动与续跑均须额外确认；工具可访问工作树外当前用户有权访问的资源，Git 工作树只负责改动回收。失败不会自动切换环境。运行记录会标明实际环境。
+
+**只读检查**使用各 CLI 的受限工具集。Claude 此模式禁用 shell、技能和既有 MCP，并忽略用户设置；需要正常工具协作时选择**编辑文件**，在隔离工作树执行。
 4. 明确确认执行后才调用模型/CLI。期间状态变化可能导致宿主拒绝旧确认，需重新审阅。
 5. 在下方**执行记录与子任务**看结果、状态、实际渠道、原始失败原因和费用。实际运行可能计费。
 
-修改任务、模式、路由方案或工作区等执行输入后，正在请求或已经返回的旧预览会被丢弃。重新预览并核对当前请求后才能确认执行。
+修改任务、规划模式、执行方式、任务权限、路由方案或工作区等输入后，正在请求或已经返回的旧预览会被丢弃。重新预览并核对当前请求后才能确认执行。官方协作不代替缺失的 CLI，不支持当前权限的工具也不会进入该模式的计划。
 
 **预览不会启动模型，确认会启动。** 模型 API 将任务文本发给供应商；CLI 可能读取工作区或其他其权限允许的文件。只读不等于所有 CLI 只能读取工作区，先看**预算与安全 → 安全边界**。
 
@@ -86,6 +99,8 @@
 
 记录展示分配模型、执行渠道、费用、步骤依赖和错误。任务/回答摘录会本地保存，因此分享日志或截图前先脱敏。
 
+CLI 记录分别保留 Harness 推荐模型、显式请求 CLI 模型和 CLI 回报的实际模型，同时保留可用的入口、沙箱、用量及金额证据。无显式 CLI 映射时使用厂商自身配置；参数中的请求名称不等于实际模型证明。单工具 `cliModel` 可覆盖档案映射；团队 `cliModelsJson` 优先按工作包 ID，其次工具 ID，最后采用档案映射。没有实际回报时请核对厂商运行记录。
+
 - **只读路由/团队失败**：重跑失败步骤及依赖它的未完成步骤；已完成结果作为上下文保留。允许时可改派另一条已配置路线。
 - **可编辑团队失败**：符合条件时在新独立工作树中套用此前改动后续跑；要求原仓库干净且仍在原基线。已经整合或等待人工整合的运行不能任意单步重跑。
 - **单工具调用失败**：重新执行原调用，生成关联的新运行；可编辑模式仍需审批。
@@ -95,10 +110,14 @@
 
 保存的任务文本最多 20,000 字符，单个回答最多 4,000 字符；历史不是完整交付文件的替代，重跑可能使用截断后的上下文。
 
+重跑完成后以新的步骤状态、回答和时间为准；已成功的步骤不应继续显示上次失败原因。记录中的只读/可编辑模式对应实际执行权限，不能从“官方 CLI”渠道名称单独推断。
+
 ## 官方工具：体检、安装与登录
 
 当前注册表包括 Kimi、Claude、Codex、MiniMax、MiMo、Grok、Gemini、OpenCode、Step Code 和 ZCode。点**重新体检**查看实际安装、版本、入口及账号状态；最新版查询失败时保持未知，不表示已无更新。
 
+版本检测与 CLI 登录状态命令绑定所选安装副本的实际入口。该副本缺失或入口不可用时，不使用 PATH 中另一份同名工具代替；对应登录状态保持未知。已安装、入口就绪、已登录和模型权限仍是四项独立检查。
+
 1. 未安装时可从卡片固定官方来源安装；npm 工具安装厂商 `@latest`。新厂商版本没有自动通过本项目测试。
 2. 安装中可查看日志或取消；取消后重新体检确认状态。
 3. 有更新时可更新；已安装版本比查询结果更高时不会降级。
@@ -147,7 +166,7 @@ MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.
 
 “—”表示当前厂商未提供相应渠道。每个工具的安装方式下拉框保留所有声明方式，并说明本机不适用的原因。MiniMax 官方脚本只接受官方 npm 源或 npmmirror；其他 npm 镜像请选 npm/pnpm 方式。
 
-安装成功只表示所选目录的命令入口和版本已确认，不代表工具支持受限执行。Gemini 使用核验后的 npm/pnpm 包入口无界面执行；OpenCode、Step 当前可安装和在终端中使用，尚不支持受限任务。缺少这类能力不再报安装失败。Kimi、MiMo、Grok 的独立原生脚本安装目前没有插件需要的 npm 文件摘要证明，自动任务会显示执行入口未就绪并回退到 API；npm/pnpm 安装保留可核验的执行路径。Windows Codex 脚本使用目录联接，插件不提供通用文件删除卸载；请按官方方式移除原生安装。
+安装成功只表示所选目录的命令入口和版本已确认，不代表工具支持受限执行。Gemini 使用核验后的 npm/pnpm 包入口无界面执行；OpenCode、Step 当前可安装和在终端中使用，尚不支持受限任务。缺少这类能力不再报安装失败。Kimi、MiMo、Grok 的独立原生脚本安装目前没有插件需要的 npm 文件摘要证明，会显示执行入口未就绪；模型路由可按策略使用 API，官方工具协作则不选用该入口且不自动回退。npm/pnpm 安装保留可核验的执行路径。Windows Codex 脚本使用目录联接，插件不提供通用文件删除卸载；请按官方方式移除原生安装。
 
 ### 安装方式的会话与 Agent 等价物
 
@@ -164,7 +183,8 @@ MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.
 
 | 工具 ID | 单工具/团队执行支持 |
 | --- | --- |
-| `claude-code`、`codex`、`mimo-code`、`grok-build` | 只读，以及经审批的可编辑执行。 |
+| `claude-code`、`mimo-code`、`grok-build` | 只读，以及经审批的可编辑执行。 |
+| `codex` | Windows 托管只读；暂不支持可编辑执行，也不进入可编辑团队计划。 |
 | `kimi-code`、`minimax-code`、`zcode` | 经审批的可编辑执行。 |
 | `gemini` | 路由无界面适配器，不进入单工具/团队托管执行器。 |
 | `opencode`、`stepcode` | 尚未核验受限执行入口；插件负责安装、检测与登录体检，执行请在终端中直接进行。 |
@@ -173,6 +193,10 @@ MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.
 
 在**官方工具终端**选择系统终端或已安装的 CLI，填写存在的绝对目录；支持时可选登录方式。启动确认显示命令、目录与权限范围。
 
+0.19.0 起，终端清单覆盖全部十个注册表工具，包含 OpenCode、Step Code 和 Windows ZCode 内置 TUI。“刷新”重新检测安装状态；启动沿用已保存的安装方式与目录，选定副本不存在时会提示，不改用 PATH 上的其他副本。
+
+已安装 **ZCode 桌面版**时，在 ZCode 工具行的“ZCode TUI 独立配置”填写其桌面目录，例如 `D:/Program Files/ZCode`，点击“保存并刷新 TUI 入口”；留空恢复自动检测。核验成功后在官方工具终端选择 **ZCode TUI（桌面版内置）**，使用现有登录环境自行配置模型和插件。无需额外独立 CLI 安装包。内置 CLI 随桌面版更新；ZCode 行可单独“检查并更新桌面版”或“重新安装桌面版”，在官方窗口完成后重新体检。桌面版本与内置 CLI 版本不同，工具行显示桌面版本。
+
 终端**不经过 Harness 沙箱**，保留用户登录环境、代理和 API Key 变量；输入的命令可按用户权限修改文件。它与上面的只读路由执行分别处理，不共享“只读”的承诺。
 
 PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺寸同步可能不可用。最多四个并发会话，无人读取约两分钟或达到六小时上限会结束。切换工作台页面保留会话；关闭整个工作台会终止。完成后点**结束会话**。输入/输出不持久化，只记录工具、目录、时间及退出状态。
@@ -185,6 +209,8 @@ PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺
 
 API 花费计入预算；订阅显示按 API 价折算的参考费用，不计入预算。预算和费用是本地估算/核算，不代替厂商账单；无法确定费用时显示未知。
 
+有效的 CLI 自报金额优先，包括 `0`。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+
 0.15.0 会保留裁剪详细历史及重试前的费用累计，避免超过 200 条历史或重跑步骤后预算漏算。此前旧版本已丢弃的消费记录无法恢复。
 
 ### 持续反馈与本地偏好
@@ -205,6 +231,8 @@ API 花费计入预算；订阅显示按 API 价折算的参考费用，不计
 
 **安全边界**显示各路线可读/写范围与沙箱。模型 API 没有本地进程文件访问；可编辑 CLI 要求 Harness 沙箱和独立 Git 工作树。缺少沙箱时可编辑托管执行被拒绝。交互终端始终在沙箱外运行。
 
+Windows Codex 在 Harness 环境仅支持只读：其原 `CODEX_HOME` 状态仍可更新，内层保持 `--sandbox read-only`。在明确确认的厂商 CLI 正常环境中支持可编辑工作包，使用 Codex 自身 workspace-write 策略。本批真实 Codex 连接未通过，不能以安装或登录状态推断网络调用成功。
+
 ## 从官方会话启动任务
 
 在 Harness 选择正确工作区，使用自然语言明确要求调用插件工具。以下 JSON 是核对工具调用详情的示例，不需要粘贴到工作台任务框。