dsh-vision-router 2.2.8 → 2.3.0

package/README.md

@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.1"><img src="https://img.shields.io/badge/release-v2.2.1-5B4CF0?style=flat-square" alt="Release v2.2.1" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.3.0"><img src="https://img.shields.io/badge/release-v2.3.0-5B4CF0?style=flat-square" alt="Release v2.3.0" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-Node%2022%20%2B%2024-2EA44F?style=flat-square" alt="Verified: Node 22 + 24" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="License: MIT" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -42,9 +42,9 @@
 > **Data leaves your machine by default.** When a cloud vision model is used, Vision Router sends the image (or a derived crop), the vision prompt and related request metadata to that provider. A fresh install has an anonymous OVHcloud vision fallback enabled, so "free" and "no key" do **not** mean offline. Do not use the cloud chain for confidential, regulated or classified material. See [Data flow and strict local-only use](#data-flow-and-strict-local-only-use).
 
 > [!WARNING]
-> 📌 **Announcement (v2.2.5)**
+> 📌 **Announcement (v2.3.0)**
 >
-> **v2.2.5:** Adds fail-closed **Local-only vision** and fixes the remaining DSH `0.1.7-rc.2` Windows Desktop multi-plugin `Loading plugins…` hang by isolating Vision Router’s WebServer registrar from other plugins. The public Host floor remains `0.1.0-rc.8`. [What’s new →](docs/releases/v2.2.5.md)
+> **v2.3.0:** Architecture hardening and compatibility convergence. The supported DSH 0.1.x window now starts at `0.1.5-rc.1`, while the 0.2.x train starts at verified `0.2.0-rc.2`; composition, Session repair, Settings/browser ownership and Desktop lifecycle contracts are hardened, and only proven-unreachable pre-floor shims are retired. [What’s new →](docs/releases/v2.3.0.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="Demo: paste an image, the agent locates the send button with vision_ground / vision_crop / vision_pixel_diff and answers with coordinates" />
@@ -320,11 +320,11 @@ Failures are classified (region / tos / quota / rate-limit / context / network)
 
 Stealth mode is **off by default** (explicit opt-in since issue #34): the official `deepseek-official` route stays untouched. When you need images, the composer’s “👁 Vision” control switches to the internal DeepSeek wrapper, which is hidden from the stock picker and `/model` presentation by default.
 
-On newer DSH Host generations, the official DeepSeek provider owns request-local attachment, file and image-access behavior. Vision Router therefore **never reconstructs or resurrects `deepseek-official` on those Hosts**. Keep `llm-deepseek` enabled and use the internal “DeepSeek + Auto Vision” wrapper / “👁 Vision” control for image tasks. If the official row is disabled or unavailable, the settings card reports that configuration problem instead of silently recreating a partial provider.
+On every DSH Host supported by DVR 2.3, the official DeepSeek provider owns request-local attachment, file and image-access behavior. Vision Router therefore **never reconstructs or resurrects `deepseek-official`**. Keep `llm-deepseek` enabled and use the internal “DeepSeek + Auto Vision” wrapper / “👁 Vision” control for image tasks. If the official row is disabled or unavailable, the settings card reports that configuration problem instead of silently recreating a partial provider.
 
-Legacy Host contracts that do not expose this provider-ownership capability retain the historical takeover/keep-alive behavior for compatibility: when their stock DeepSeek row is absent, Vision Router can still rebuild the legacy provider path so existing profiles and sessions keep working. This fallback is not a setup requirement for current Hosts and should not be enabled by disabling `llm-deepseek` on a modern installation.
+The historical `stealth` field is retained only so existing profiles continue to parse cleanly; it no longer grants provider-takeover authority on the DVR 2.3 support window.
 
-> Stealth mode **only affects the official DeepSeek route**. Custom/third-party routes such as opencode also receive internal vision wrappers by default, used through the composer toggle rather than a second user-facing model group.
+> Custom/third-party routes such as opencode also receive internal vision wrappers by default, used through the composer toggle rather than a second user-facing model group.
 
 ## Auto-vision wrappers and manual scope
 
@@ -436,7 +436,7 @@ ollama pull qwen2.5vl
 ## Requirements
 
 - DeepSeek Harness Web profile. Normal installs can use `npx @deepseek-ai/dsh ...`; source checkouts use `pnpm dsh ...`. A bare `dsh ...` command only works when the CLI is already on your shell `PATH`.
-- **DSH Host support policy:** DVR 2.2.x keeps DSH `0.1.0-rc.8` as the public minimum and currently supports the released stable channel through `0.1.5-rc.3`. The DSH `0.2.x` train is peer-admitted from the verified `0.2.0-rc.1` boundary (`>=0.2.0-rc.1 <0.3.0-0`); exact `0.2.0-rc.2` (`next/rc`) source, real Host, Windows Desktop, multi-plugin, Settings, mixed-attachment, bundle-recompose, and Host-Sharp gates are preview verification evidence, not a support-floor increase. The final stable `0.2.0` tag and signed Desktop artifact will still be revalidated when published. DVR 2.0.x was the final train with public support for rc.6/rc.7. See [DSH Host support window](docs/architecture/dsh-support-window.md).
+- **DSH Host support policy:** DVR 2.3.x supports DSH 0.1.x continuously from `0.1.5-rc.1` (current stable evidence: `0.1.5-rc.3`) and supports the 0.2.x train from verified `0.2.0-rc.2`. Exact `0.2.0-rc.2` is also the ordinary 2.3 development Host. Pre-0.1.5 Hosts are unsupported, and DVR no longer publishes the older jagged 0.1.x exception list. Runtime behavior remains capability-based. See [DSH Host support window](docs/architecture/dsh-support-window.md).
 - Node ≥ 22 (host side).
 - No API key for the default free chain; a credential reference (`apiKeyEnv`) only for paid `httpProviders`.
 - Chrome / Chromium / Edge is needed only for `vision_html_screenshot`; every other tool works without a browser.

package/README.zh.md

@@ -17,7 +17,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.2.1"><img src="https://img.shields.io/badge/release-v2.2.1-5B4CF0?style=flat-square" alt="Release v2.2.1" /></a>
+  <a href="https://github.com/ysr666/dsh-vision-router/releases/tag/v2.3.0"><img src="https://img.shields.io/badge/release-v2.3.0-5B4CF0?style=flat-square" alt="Release v2.3.0" /></a>
   <a href="tests"><img src="https://img.shields.io/badge/verified-Node%2022%20%2B%2024-2EA44F?style=flat-square" alt="已验证 Node 22 + 24" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="MIT 许可证" /></a>
   <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
@@ -42,9 +42,9 @@
 > **默认配置会让数据出网。** 使用云端视觉模型时，Vision Router 会将图片（或由它裁剪出的局部）、识图提示词及相关请求元数据发送给对应供应商。新安装默认开启 OVHcloud 匿名视觉兜底，因此“免费”和“免 Key”不等于离线。涉密、涉案、内部或其他受限材料请勿使用云端链路。详见[数据流向与严格纯本地配置](#数据流向与严格纯本地配置)。
 
 > [!WARNING]
-> 📌 **公告（v2.2.5）**
+> 📌 **公告（v2.3.0）**
 >
-> **v2.2.5：新增 fail-closed 的「仅本地视觉」，并根修 DSH `0.1.7-rc.2` Windows Desktop 多插件环境下残留的 `Loading plugins…` 卡死——Vision Router 的 WebServer registrar 不再污染其他插件。公开最低 Host 仍保持 `0.1.0-rc.8`。** [查看完整更新 →](docs/releases/v2.2.5.md)
+> **v2.3.0：架构加固与兼容收敛。DSH 0.1.x 正式支持线提高到 `0.1.5-rc.1` 起，0.2.x 从已验证的 `0.2.0-rc.2` 起；composition、Session repair、Settings/浏览器 ownership 与 Desktop lifecycle 均完成加固，只退休已证明在新支持窗口不可达的旧 shim。** [查看完整更新 →](docs/releases/v2.3.0.md)
 
 <p align="center">
   <img src="assets/vision-demo.gif" width="640" alt="演示：粘贴图片，Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
@@ -318,11 +318,11 @@ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
 
 隐身模式默认**关闭**（issue #34 起显式 opt-in）：官方 `deepseek-official` 路由原样保留；需要看图时通过输入框旁的「👁 识图」切换到内部 DeepSeek wrapper。该 wrapper 默认从原生模型选择器和 `/model` 展示层隐藏。
 
-在新版 DSH Host 中，官方 DeepSeek provider 自己负责请求期的附件、Files API 与图片访问能力。因此 Vision Router **不会再重建或复活 `deepseek-official`**。请保持 `llm-deepseek` 启用，通过内部「DeepSeek + 自动识图」wrapper /「👁 识图」处理图片；如果官方行被禁用或不可用，设置页会明确提示重新启用，而不是偷偷注册一个能力不完整的替代 provider。
+在 DVR 2.3 支持的所有 DSH Host 中，官方 DeepSeek provider 都由 Host 自己负责请求期的附件、Files API 与图片访问能力。因此 Vision Router **不会重建或复活 `deepseek-official`**。请保持 `llm-deepseek` 启用，通过内部「DeepSeek + 自动识图」wrapper /「👁 识图」处理图片；如果官方行被禁用或不可用，设置页会明确提示重新启用，而不是偷偷注册一个能力不完整的替代 provider。
 
-缺少这项 provider ownership 能力的 legacy Host contract 仍保留历史接管 / keep-alive 行为，以兼容旧 profile 和旧会话：只有这条兼容路径在官方行缺失时才可能由 Vision Router 重建旧 provider。这不是新版 Host 的配置方式；当前安装不要为了隐身模式去禁用 `llm-deepseek`。
+历史 `stealth` 字段仅为兼容已有 profile 而继续读取；在 DVR 2.3 支持窗口内，它不再具有接管 provider 的权限。
 
-> 隐身模式**只作用于官方 DeepSeek 路由**。opencode 等自定义/第三方文本路由与隐身模式无关——默认也会生成内部识图 wrapper，由「👁 识图」按需使用。
+> opencode 等自定义/第三方文本路由默认也会生成内部识图 wrapper，由「👁 识图」按需使用。
 
 ## 自动识图包装与手动范围
 
@@ -434,7 +434,7 @@ ollama pull qwen2.5vl
 ## 环境要求
 
 - DeepSeek Harness 的 Web profile。普通安装可用 `npx @deepseek-ai/dsh ...`；从源码仓库运行时用 `pnpm dsh ...`。只有 CLI 已经进入系统 `PATH` 时才能直接写 `dsh ...`。
-- **DSH Host 支持策略：** DVR 2.2.x 的公开最低 Host 仍为 DSH `0.1.0-rc.8`，当前稳定通道已验证并支持到 `0.1.5-rc.3`。DSH `0.2.x` 从已验证的 `0.2.0-rc.1` 边界开始准入（`>=0.2.0-rc.1 <0.3.0-0`）；精确 `0.2.0-rc.2`（`next/rc`）源码、真实 Host、Windows Desktop、多插件、Settings、混合附件、bundle 重组及 Host-Sharp 门禁仅作为预览验证证据，不抬高公开支持下限。上游正式发布稳定版 `0.2.0` tag 和签名 Desktop 安装包后仍会立即复验。DVR 2.0.x 是最后公开支持 rc.6/rc.7 的版本线。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
+- **DSH Host 支持策略：** DVR 2.3.x 从 `0.1.5-rc.1` 起连续支持 DSH 0.1.x（当前稳定证据为 `0.1.5-rc.3`），并从已验证的 `0.2.0-rc.2` 起支持 0.2.x；精确 `0.2.0-rc.2` 同时作为 2.3 默认开发 Host。低于 0.1.5 的 Host 不再支持，也不再维护旧的 0.1.x 锯齿式例外列表。运行时仍按能力判断，而不是按版本字符串分支。详见 [DSH Host 支持窗口](docs/architecture/dsh-support-window.md)。
 - Node ≥ 22（宿主侧）。
 - 默认免费链路无需 API Key；付费 `httpProviders` 只需一个凭据引用（`apiKeyEnv`）。
 - 只有 `vision_html_screenshot` 需要 Chrome / Chromium / Edge；其余工具无浏览器也能用。

package/docs/architecture/2.3.0-compat-retirement.md

@@ -0,0 +1,147 @@
+# DVR 2.3.0 compatibility retirement review
+
+> **R2.3 re-audit complete.** The original review predates the v2.2.8 / DSH 0.2.0-rc.2 / shared Desktop client-carrier line. The reopened audit retired every seam proven to exist only for a pre-`0.1.5` Host and reclassified the remaining seams against current-Host, durable-data, product, or platform evidence.
+
+Review baseline: `2.3.0@d808014` after explicit `VisionProviderTransport` plumbing.
+
+This review records Workstream B of the 2.3.0 architecture plan. A compatibility seam is not removed merely because it is old or awkward; deletion requires its existing removal condition to be satisfied by current Host/product evidence.
+
+## Result
+
+The process/profile `VisionProviderTransport` registry, the pre-floor Android/no-batch attachment fallback, and the pre-floor DeepSeek provider reconstruction path are retired. No remaining retained compatibility seam is presently classified `retire-ready` or `historical-only`.
+
+| State | Count | Meaning in 2.3.0 |
+| --- | ---: | --- |
+| `retain-host-gap` | 6 | A supported/admitted Host still lacks the native seam needed to remove it. |
+| `product-compat` | 4 | DVR intentionally retains provider, persisted-history, platform, or voluntary legacy compatibility independent of a current Host defect. |
+| `retire-ready` | 0 | No remaining seam has met its removal condition. |
+| `historical-only` | 0 | No retained seam is dead production code awaiting deletion. |
+
+The canonical per-file classifications live in `compat-inventory.md` and are checked by `compat-inventory-completeness.test.js`.
+
+## B1 — retired provider transport registry
+
+The former module-level `installed[]`, `installVisionProviderTransport()` and `currentVisionProviderTransport()` carrier has been deleted. The production dependency path is now explicit:
+
+```text
+public-entry creates VisionProviderTransport
+  -> entry internal runtime argument
+  -> runtime-composition Core runtime dependency
+  -> mature Core call sites
+  -> http-compat / catalog-corrections options
+```
+
+Direct/unit helper callers retain their historical fallback behavior when no explicit transport is supplied. Two concurrent explicit transports are regression-tested to remain isolated, so one runtime can no longer steal another runtime's provider transport by being installed last.
+
+Architecture Closure now forbids every module-global `installed[]` runtime registry rather than allowing a provider-transport exception.
+
+## R2.3-C — retired rc.7-era public compatibility aliases
+
+The transitional public aliases `isRc7ContractRuntime`, `protectRc7ProviderOwnership`, and `installRc7SettingsCompatibility` are removed from both `entry.js` and `lib/dsh-contract-compat.js`.
+
+Repository-wide reachability review found no production consumer: the names existed only as public re-exports plus tests asserting that each alias equaled its capability-named replacement. DVR 2.3's support floor is now the continuous DSH 0.1.5+ line, so retaining rc.7-labelled API aliases would preserve only implementation archaeology rather than supported behavior.
+
+The capability-named APIs remain authoritative:
+
+- `hasBatchAttachmentContract`;
+- `protectHostProviderOwnership`;
+- `installHostSettingsCompatibility`.
+
+This retirement changes no runtime behavior and intentionally shrinks the 2.3 public compatibility surface.
+
+## R2.3-D — supported-window retained-seam verdict
+
+After the three concrete retirements above, the remaining seams were re-audited against minimum `0.1.5-rc.1`, current `0.1.5-rc.3`, mid-train `0.1.7-rc.2`, and exact `0.2.0-rc.2` evidence.
+
+The review stops deleting code at this point because every remaining seam has a reachable non-pre-floor reason:
+
+- `dsh-contract-compat.js`: supported Settings generations still differ, SessionQuery readers remain capability-scoped, and historical attachment-policy overlays are durable profile data that can survive a Host upgrade;
+- `adapter-update-coalescer.js`: DVR-owned adapters remain plain/duck-typed objects and still require current Host base-contract normalization plus bounded synchronous reconciliation;
+- `settings-client-loader-lifecycle.js` (historically `settings-client-rc8-lifecycle.js`): immutable 0.1.5-rc.1 through 0.2.0-rc.2 sources still replace the live module loader during `create()`; R4 renamed the source/API by capability and moved permission/risk semantics into their own owners while retaining the lifecycle reattachment;
+- `pi-ai-bridge-wire-compat.js`: current pi-ai carries generic `sessionId` but does not yet emit OpenCode Go's required `x-opencode-session`;
+- replay, proxy, legacy Core visual-policy, HTTP, Tesseract and AbortSignal seams remain durable-data, explicit product, or runtime/platform compatibility rather than pre-floor Host support.
+
+The normative exact-source matrix now excludes pre-floor `0.1.5-alpha.2`. That immutable Host may remain in a separately labelled browser surveillance workflow, but it is not peer-admitted or counted as DVR 2.3 support evidence.
+
+This is the final R2.3 exit state. The renamed compatibility suite, minimum/current contracts, exact supported-source matrix and aggregate 2.3 gate are green. Final evidence:
+
+- exact supported 0.1.x source matrix: run `36659179011`;
+- minimum/current Host contract: run `36660877445`;
+- aggregate 2.3 gate: run `36660877636`, including Node 22/24, current `0.1.5-rc.3`, exact rc.2 source on three OSes, Chromium, Windows Desktop 22/24, macOS Desktop lifecycle and final `critical-gate`.
+
+
+## B2 — retained seam classification
+
+### `retain-host-gap`
+
+- `dsh-contract-compat.js` — attachment/settings/provider contracts still vary across admitted Host generations.
+- `adapter-update-coalescer.js` — adapter contract/event ordering compatibility remains required by supported Host behavior.
+- `pi-ai-bridge-wire-compat.js` — direct image bridge wire facts and OpenCode session affinity are not yet fully native on every supported path.
+- `settings-client-loader-lifecycle.js` — browser settings loader lifecycle still differs across the support window; only the historical in-page marker/sentinel retains the rc8 token for mixed-generation/HMR idempotency.
+- `legacy-global-proxy-boundary.js` — Host-owned visual adapters still expose no DVR-scoped request/dispatcher parameter for the supported explicit proxy override.
+- `legacy-core-vision-policy-bridge.js` — the Host still lacks both native session-memory rewrite and durable current-turn attachment-reference seams needed by the two retained behaviors.
+
+### `product-compat`
+
+- `replay-envelope-v2-compat.js` — persisted historical sessions are product data compatibility, not merely a currently running Host-version branch.
+- `http-compat.js` — provider/model wire quirks are an intentional provider compatibility layer.
+- `tesseract-exec-compat.js` — Node/platform child-process and Windows DPI behavior is a platform compatibility concern.
+- `abort-signal-compat.js` — partial Host/bridge JS realms remain a runtime compatibility concern; native helpers are never replaced when present.
+
+## R2.3-A — retired Android/no-batch attachment fallback
+
+The reopened support-window audit retires `lib/android-attachment-compat.js` and `attachmentContextForContract()`.
+
+This is a reachability deletion, not an Android product-policy withdrawal. The retired wrapper could run only when the Host attachment service lacked `saveImages()`. Every immutable Host line spanning the DVR 2.3 support/evidence window already exposes the batch contract:
+
+- `dsh-v0.1.5-rc.1` — `183f08e9c6dde7e36cd2318eaee70b0da08fb35e`;
+- `dsh-v0.1.5-rc.3` — `a4c74a91e06b00fe0b0937bde982170c526cc842`;
+- `dsh-v0.1.6-alpha.1` — `0a15e36e7f82b6ed45af6fa9759f29b40dcd965d`;
+- `dsh-v0.1.7-rc.2` — `477b4f420553e8a52c2fbccc464d7561b239c443`;
+- `dsh-v0.2.0-rc.2` — `639ed015397290b3745d163aafe02ffee4aa3f84`.
+
+The former helper also installed the read-only Host capability diagnostics route. That side effect is preserved explicitly in `runtime-composition.js` through `installDshHostCapabilityDiagnostics(settingsCtx)`, and the P3 composition contract locks its position before the tool/runtime boundaries.
+
+The fallback stored only bounded process-local transient image bytes, so no durable Session/profile/config input depends on it. Removing it therefore changes no supported Host behavior and removes no durable-data reader.
+
+## R2.3-B — retired legacy DeepSeek provider reconstruction
+
+DVR 2.3 no longer rebuilds a missing `deepseek-official` provider, registers the hidden `deepseek-official-native` surrogate, waits on the historical 2-second keep-alive settle window, or reconstructs `@deepseek-ai/dsh-llm-deepseek` from plugin-owned settings/credentials.
+
+The deletion follows the same immutable Host evidence used by R2.3-A: every supported Host generation from `0.1.5-rc.1` forward owns the batch attachment contract and therefore the official DeepSeek request-local attachment/file/image-access lifecycle. Reconstructing that adapter inside DVR would create a partial second owner and is no longer an allowed supported-Host fallback.
+
+The persisted `stealth` setting remains readable so existing profiles continue to load; under DVR 2.3 it does not grant provider-takeover authority. A missing official row is reported as `host-owned-official-unavailable` and users are directed to re-enable `llm-deepseek`.
+
+Durable-data compatibility is intentionally separate from production creation. `replay-delegation.js`, the scoped proxy boundary and Host-ownership guard may continue to recognize the historical `deepseek-official-native` identifier so old Session/replay/config inputs remain interpretable. R2.3-B removes the code that **creates** the route, not the code that safely understands historical evidence.
+
+## B3 — DSH Web activation overlays remain required
+
+The exact DSH `0.2.0-rc.1` evidence recorded in `dsh-support-window.md` still has:
+
+- the official `modules` row without a `webServer` activation dependency;
+- the official `connection` row owning `webRuntime` but not `webServer`.
+
+Therefore the DVR `modules -> webServer` and `connection -> webServer` overlays remain `shim-required`. Existing source-contract classifiers intentionally fail with `retire-ready` when upstream begins owning these dependencies; 2.3.0 does not pre-empt that signal.
+
+## B4 — legacy proxy compatibility remains narrow
+
+`proxy` / `proxyHosts` remain supported, non-deprecated Advanced overrides. The compatibility boundary is retained because Host-owned visual adapter requests still cannot receive the DVR override explicitly.
+
+The only unscoped fallback is the documented persisted/manual legacy state:
+
+```text
+routing === true
+chainRoute === ''
+```
+
+Whitespace, a configured chain route, routing disabled, Router-owned direct HTTP, and ordinary Host traffic do not obtain this unscoped authority. `legacy-global-proxy-boundary.test.js` locks this reachability and the scoped/concurrent isolation behavior.
+
+No proxy product-policy change is part of 2.3.0.
+
+## Remote Settings is not a compatibility-retirement target
+
+Remote Settings keeps the frozen 2.3.0 product decision: the risk confirmation is a reminder/acknowledgement, not a server-side authentication or validation gate. Workstream B does not reclassify or strengthen that behavior.
+
+## B exit decision
+
+Workstream B plus reopened R2.3 currently records three real retirements (the provider transport registry, the Android/no-batch attachment fallback, and legacy DeepSeek provider reconstruction) and no speculative shim deletion. Mature-Core extraction may proceed while the remaining compatibility inventory stays capability-detected and independently removable when its recorded conditions become true.