# v2.0.0

> **v1.7.7 → v2.0.0**：这是 Vision Router 迄今最大的一次产品级升级。两版之间累计超过 400 个提交；重点不是“多了几个开关”，而是把视觉模型选择从静态顺序推进到一套**用户授权、实测证据驱动、可解释且可撤销**的能力路由系统，同时重做聊天页识图交互、Settings 信息架构、原生多模态共存和发布前可靠性边界。
>
> **v1.7.7 → v2.0.0**: this is Vision Router’s largest product-level upgrade so far, spanning more than 400 commits. The main change is not a handful of new toggles: model selection is now an **explicitly delegated, measured-evidence-driven, explainable and revocable** capability-routing system, accompanied by a new composer Vision interaction, reorganized Settings, stronger native-multimodal coexistence, and substantial release-hardening work.

## 一眼看懂 2.0 / v2 at a glance

- **Auto 能力路由正式落地（#142）**：不再靠模型名猜“谁更会看图”，而是只在用户已经配置并授权的候选中，根据真实能力证据选择；没有足够证据时继续尊重配置基线顺序。
- **Capability-aware Auto routing ships (#142)**: Vision Router no longer guesses visual capability from model names. Auto may only choose among user-configured, authorized candidates with real capability evidence, and falls back to the configured baseline order when evidence is insufficient.

- **设置页新增精确「测试识图」与 Quick / Full 测评**：单模型真实验证、能力轴评分、后台补测、持久化失败状态和可见进度统一进入正式产品界面；旧的模糊 backend smoke-test 路径退役。
- **Exact Test Vision plus Quick / Full benchmarking**: per-model real verification, capability-axis scoring, optional background profiling, persistent failure states and visible progress are now first-class product surfaces. The older ambiguous backend smoke-test path is retired.

- **聊天输入框旁新增显式「👁 识图」模式（#284 / #286）**：普通模型继续由 DSH 原生选择器管理；需要发图时主动开启识图即可，内部 wrapper 不再要求普通用户理解和手动选择。
- **Explicit composer “👁 Vision” mode (#284 / #286)**: the stock DSH picker still owns the ordinary model. Users explicitly turn Vision on when needed, without having to understand or manually select internal wrapper routes.

- **Settings 2.0（#285 / #299 / #301 / #303）**：设置按用户任务重新分组，Auto/模型链/偏好/后台能力数据合并到同一上下文，并解决即时路由控件与未保存表单之间的半事务陷阱。
- **Settings 2.0 (#285 / #299 / #301 / #303)**: settings are reorganized around user tasks, Auto/model chain/preferences/background capability data are presented together, and the mixed-save trap between immediate routing controls and unsaved form drafts is closed.

- **原生多模态优先保留模型控制权（#289 / #292 / #298）**：模型已经能直接看图时，原图先给模型；Vision Router 的 grounding / crop / OCR / pixel-diff 等能力退回“按需精查工具”，不再用全局 guard 强行接管。
- **Native multimodal models retain control (#289 / #292 / #298)**: if the selected model already accepts images, raw pixels reach it first. Vision Router’s grounding, crop, OCR, pixel-diff and related capabilities become optional precision tools instead of a global takeover path.

- **旧会话中的一次性停止提示不会再污染后续图片轮（#302）**：历史版本持久化下来的 guard-stop 会在模型输入面被安全影子替换，不再把“本轮预算/深度已耗尽”错误重放成永久禁用视觉工具的指令。
- **Persisted one-turn stop instructions no longer poison later image turns (#302)**: legacy guard-stop messages are safely shadowed off the model-facing session surface, so a past “this turn’s budget/depth is exhausted” instruction cannot become a permanent ban on vision tools.

## 能力感知 Auto 路由 / Capability-aware Auto routing

- **Auto 是委托，不是默认接管（#142）**：路由遵循 `Authority → Evidence → Planner → Execution`。用户先决定是否授权 Auto；只有显式配置、当前可执行、且具有可用证据的视觉模型才可能进入选择。live `/models` 发现到但用户没有配置的模型，不会因为“看起来更强”被偷偷放进执行池。
- **Auto is delegated authority, not implicit takeover (#142)**: routing follows `Authority → Evidence → Planner → Execution`. Only explicitly configured, executable candidates with usable evidence can participate. Models merely discovered from live `/models` data never enter execution simply because they appear stronger.

- **四种偏好**：Auto 支持「综合 / 质量 / 速度 / 本地」。偏好只会重新排序已经有权参与的候选，不会扩大调用权限，也不会越过用户配置的 provider/model 边界。
- **Four preferences**: Balanced / Quality / Speed / Local only reorder candidates that already have execution authority. A preference never grants access to another provider/model or broadens the configured execution scope.

- **无证据时不装聪明**：如果能力数据缺失、过期或与当前 deployment fingerprint 不匹配，Auto 不用模型名称、供应商品牌或静态印象推断能力，而是回到用户配置的基线顺序。
- **No fake confidence when evidence is missing**: absent, stale or fingerprint-mismatched capability data never triggers name- or brand-based inference. Auto falls back to the configured baseline order instead.

- **默认行为保持保守**：升级后仍默认 `routingMode=ordered`、`routingPreference=balanced`、`backgroundBenchmarking=off`。仅仅打开 Auto 不会自动启动测评，也不会产生额外 Benchmark 请求。
- **Conservative defaults remain**: upgrades still default to `routingMode=ordered`, `routingPreference=balanced`, and `backgroundBenchmarking=off`. Enabling Auto alone does not start benchmarking or create extra Benchmark traffic.

## 测试识图、Benchmark 与能力证据 / Test Vision, benchmarks & capability evidence

- **精确「测试识图」取代模糊 Smoke Test**：每次点击只向当前精确 provider/model 发 **1 次真实图片请求**，无 fallback、无 Auto 分数污染。测试结果回答的是“这个 deployment 现在是否真的接收图片”，而不是“整条 fallback 链最终有没有成功”。
- **Exact Test Vision replaces ambiguous smoke testing**: one click sends **exactly one real image request** to the selected provider/model, with no fallback and no Auto-score side effects. It answers whether that deployment itself currently accepts images, not whether some later fallback eventually succeeds.

- **真实拒图会成为 endpoint-scoped 事实**：明确图片拒绝会记录为当前 endpoint fingerprint 的“实测仅文本”，并停止后台继续花请求；显式成功重测可解除同 fingerprint 的停止状态。DeepSeek 的 `UNSUPPORTED_CONTENT` / `does not accept image input` 等真实拒图形式已覆盖，同时不会把普通 400、内容策略错误或 visual-proof 失败误判成仅文本。
- **Real image rejection becomes endpoint-scoped evidence**: an explicit rejection records the current endpoint fingerprint as measured text-only and stops further background spending. A later explicit successful retest can clear the same-fingerprint stop. Real DeepSeek forms such as `UNSUPPORTED_CONTENT` / `does not accept image input` are recognized without misclassifying generic 400s, content-policy failures or visual-proof failures as text-only.

- **Quick / Full 能力测评**：Quick 约 **3 次请求**，重点测 OCR + General；Full 约 **6 次请求**，覆盖 Structured + OCR + Document + Grounding + General。界面会先显示请求量与预计耗时（Quick 约 1–3 分钟，Full 约 3–8 分钟），避免用户在不知成本的情况下直接开始。
- **Quick / Full capability benchmarks**: Quick uses about **3 requests** focused on OCR + General; Full uses about **6 requests** across Structured + OCR + Document + Grounding + General. The UI shows request-count and time estimates first (roughly 1–3 min Quick, 3–8 min Full) so users are not surprised by cost or duration.

- **Benchmark 在 DSH 后台继续运行**：手动开始后可以关闭 Settings 页面；任务状态、进度和最终 profile 由 Host 侧维护，不依赖浏览器标签页存活。
- **Benchmarks continue in the DSH process**: after a manual start, the Settings page may be closed. Task state, progress and final profile persistence are maintained on the Host side rather than depending on the browser tab.

- **慢模型不再被错误的总墙钟预算吞掉**：Quick / Full 的聚合 deadline 会按 fixture 数量和单请求预算计算，仍保留单请求硬超时，但不会因为三个正常偏慢的顺序请求一起超过旧的固定总时限而把整轮成绩全部丢掉。
- **Slow but valid models no longer lose an entire benchmark to an undersized aggregate wall-clock budget**: the job deadline scales with fixture count and per-request budget while keeping hard per-request safety limits.

- **能力数据按 deployment identity 管理**：评分、新鲜度、图片输入 verdict 与 non-retryable stop 都绑定到可验证的 provider/model/endpoint fingerprint；普通设置刷新不会把同一 deployment 的失败“洗白”，endpoint 变化或显式成功重测才会建立新的事实。
- **Capability evidence follows deployment identity**: scores, freshness, image-input verdicts and non-retryable stops bind to a verifiable provider/model/endpoint fingerprint. Ordinary settings refreshes do not erase a failure for the same deployment; endpoint changes or explicit successful retests establish new evidence.

## 后台能力数据 / Background capability profiling

- **后台补测单独授权**：`off / local-free / all` 与 Auto 开关互相独立；Auto 不会替用户打开后台测评。`all` 可能调用云端模型并产生 API 费用，因此首次开启会明确提示。
- **Background profiling has separate consent**: `off / local-free / all` is independent from the Auto switch. Auto never silently enables background benchmarking, and `all` explicitly warns that cloud API usage may incur cost.

- **低优先级、按能力轴推进**：后台调度不会一次性把整套 Full 测评砸向所有模型，而是逐能力轴补证据，并跳过已经完成、已经明确不支持或当前被 non-retryable stop 阻止的候选。
- **Low-priority, axis-by-axis scheduling**: background work does not blast a full suite at every model. It fills capability evidence incrementally and skips completed, explicitly unsupported or non-retryably blocked candidates.

- **前台真实识图永远优先**：用户发起视觉任务时后台测评会让路，并在约 30 秒空闲后恢复；手动 Benchmark 同样抢占后台，结束后约 15 秒恢复。关闭后台测评会撤销后续请求和写入，而不是“关了开关但队列继续跑”。
- **Foreground work always wins**: real user vision preempts background profiling and allows it to resume after roughly 30 seconds idle. Manual benchmarks also preempt background work, with resume after roughly 15 seconds. Revoking background profiling cancels future requests and writes rather than merely hiding the toggle.

- **失败按正确粒度停止**：`auth / unavailable / protocol` 对同一 deployment fingerprint 是模型级 non-retryable stop，并在 DSH 重启后继续生效；`visual-proof` 只作用于对应能力轴，不会把支持图片的模型整机判死。
- **Failures stop at the correct scope**: `auth / unavailable / protocol` are model-wide non-retryable stops for the same deployment fingerprint and survive DSH restart. `visual-proof` remains axis-scoped and never condemns an image-capable model as a whole.

## 输入框「👁 识图」模式 / Composer “👁 Vision” mode

- **聊天页新增显式识图开关（#284 / #286）**：普通聊天模型仍由 DSH 原生模型选择器负责；需要发图时用户主动开启「👁 识图」，底层切换到同一 provider/model 的 Vision Router wrapper。默认关闭，不因上传图片偷偷开启；发送后保持状态，关闭时返回同一普通模型。
- **Explicit composer Vision toggle (#284 / #286)**: DSH’s stock picker continues to own the ordinary conversation model. Users explicitly enable Vision when needed, switching underneath to Vision Router’s matching wrapper for the same provider/model. It starts off, is never silently enabled by attaching an image, persists across sends, and returns to the same ordinary model when disabled.

- **识图模式没有第二份“假状态”**：按钮状态从 DSH 当前真实 route 派生。只修改 reasoning effort 不会退出识图；用户手动选择另一个普通模型才会离开 wrapper。切换被 Host 拒绝时沿用原生 Toast，不绕过 DSH 安全约束，按钮继续反映真实 current。
- **Vision mode has no second shadow state**: the button derives its state from DSH’s real current route. Effort-only changes stay on the Vision wrapper; choosing another ordinary model exits it. Rejected switches use the stock Toast path and never bypass Host safety, while the button continues to reflect the actual current route.

- **内部「+ 自动识图」wrapper 默认隐藏**：只改变 DSH model-selection 的 presentation，不删除真实 Host route。隐藏必须同时满足配置意图、route/name 和 exact-model 镜像；设置缺失、归属歧义、镜像不完整、第三方 `*-vision` lookalike 都 fail-open，宁可显示也不误藏（#288 / #291 / #294 / #300）。
- **Internal “+ Auto Vision” wrappers are hidden by default**: only stock model-selection presentation changes; real Host routes remain intact. Hiding requires matching configuration intent, route/name identity and exact-model mirroring. Missing/ambiguous settings, incomplete mirrors and third-party `*-vision` lookalikes fail open and remain visible (#288 / #291 / #294 / #300).

- **新手路径同步简化**：Quick Start / onboarding 统一为“选普通模型 → 开启识图 → 发图”，不再要求用户从成对的普通模型与 wrapper 模型中理解该选哪一个。
- **Onboarding is simplified**: Quick Start now consistently teaches “choose the ordinary model → enable Vision → send the image,” rather than requiring users to reason about paired ordinary/wrapper model entries.

- **原生多模态 wrapper 获得当前轮真实 attachment ID**：模型已经看得到原图时，仍可按需调用 `vision_describe` / `vision_ground` 等精查工具，而不需要猜造附件 ID；跨 session 授权和 `unknown attachment id` 安全边界不放宽。
- **Owned multimodal wrappers receive real current-turn attachment IDs** so a model that already sees raw pixels can still invoke precision tools without inventing attachment identifiers. Session-scoped authorization and the `unknown attachment id` boundary remain strict.

## 原生多模态共存 / Native multimodal coexistence

- **原生多模态模型保持控制权（#289 / #292 / #298）**：如果当前模型本来就能直接看图，Vision Router 不再用全局 structured guard / synthetic budget message 强行接管这轮；原始图片先直接交给模型，grounding / crop / OCR / pixel-diff 等只在模型真正需要时作为精查工具参与。
- **Native multimodal models stay in control (#289 / #292 / #298)**: when the selected model already accepts images, Vision Router no longer lets a global structured guard or synthetic budget message hijack the turn. Raw pixels reach the model first; grounding, crop, OCR, pixel diff and other tools remain optional precision aids.

- **原生能力与工具增强可以共存**：能直接看图不等于失去 Vision Router 工具。模型可先看整图，再根据任务决定是否调用定位、裁剪、OCR、颜色、pixel-diff、截图等工具做更精确的二次检查。
- **Native vision and precision tools coexist**: direct image input does not remove Vision Router’s tool layer. A multimodal model can inspect the full image first, then selectively invoke grounding, crop, OCR, color, pixel-diff, screenshot and related tools for precision work.

- **整轮视觉预算默认不再误伤长推理**：`visionTurnBudgetMs` 默认改为 `0`（不设整轮总墙钟上限），预算只在真正开始视觉工作时生效；具体网络请求、工具和 Benchmark 仍各自保留硬超时与资源边界。
- **Whole-turn vision budget no longer penalizes long reasoning by default**: `visionTurnBudgetMs` now defaults to `0` (no global wall-clock cap), while concrete network requests, tools and benchmarks retain their own hard deadlines and resource limits.

## 会话续接与历史兼容 / Session continuity & historical compatibility

- **修复持久化 guard-stop 污染后续轮次（#302）**：历史版本曾把“本轮视觉总时间预算/深度配额已耗尽”的一次性 stop 指令持久化成 `user/message`。DSH 在后续 `deriveMessages()` 时会再次把这条历史消息交给模型，结果可能出现“第一张图正常，之后每张图都认为视觉工具永久禁止”的故障。2.0 会按 Vision Router 私有 message id 精确识别这些旧记录，并通过 DSH 的 session surface shadow 机制只替换**模型看到的投影**；人类可见的原始转写、原事件和其他普通用户消息不被删除或改写。
- **Persisted guard-stop instructions no longer poison later turns (#302)**: older builds could persist a one-turn “vision budget/depth exhausted” stop as a `user/message`. Later `deriveMessages()` projections would feed that stale instruction back to the model, potentially making the first image work while every later image behaved as if vision tools were permanently forbidden. v2 matches only Vision Router-owned message IDs and uses DSH session-surface shadow replacement on the **model-facing projection**; the human-visible transcript, original event and ordinary user messages remain intact.

- **旧的 `-undefined` 形态也可恢复**：历史上 turn id 缺失留下的 `vision-router-structured-guard-stop-undefined` 同样被精确覆盖；匹配只看插件私有 id，不按提示文本搜索，因此用户引用同一句“预算已耗尽”不会被误删。surface compaction / 重启后也会重新建立正确投影。
- **Legacy `-undefined` IDs are covered as well**: historical `vision-router-structured-guard-stop-undefined` records are handled explicitly. Matching is based only on plugin-owned IDs, never the wording of the stop message, so a user quoting the same text is untouched; the correction also survives session-surface compaction and resume.

## 设置 2.0 / Settings 2.0

- **Settings 按用户任务重组（#285 / #299）**：一级 Vision Router 设置页重构为「常规 / 识图策略 / 本地与设备 / 高级 / 诊断」，模型选择、工具策略、本地后端、性能/网络与排障各归其位。迁移层保留有效旧配置，并明确退役历史 UI 状态字段，避免“看似还在、实际已不生效”的幽灵设置。
- **Settings are reorganized around user tasks (#285 / #299)**: General / Vision Strategy / Local & Device / Advanced / Diagnostics separate model choice, tool strategy, local backends, performance/network controls and troubleshooting. Migration preserves meaningful existing configuration while retiring obsolete UI-state fields instead of leaving ghost settings behind.

- **v2 Auto 控件进入识图模型区域（#301）**：模型链、选择方式、偏好与后台能力数据在同一上下文呈现；第一次开启 Auto 会明确说明“Auto ≠ 自动测评”，以及后台“所有模型”可能产生云端 API 费用。
- **v2 Auto controls now live with the vision-model chain (#301)**: configured models, selection mode, preference and background capability profiling are presented together. First enable explains that “Auto ≠ automatic benchmarking” and that “All models” background profiling may incur cloud API cost.

- **发布前收口混合保存陷阱（#303）**：如果 React Settings IA 还有未保存修改，v2 的即时路由控件会要求先保存或放弃，避免出现“Auto 已落盘但刚改的模型链没保存”的半事务状态。Auto 模式下页面明确标注“配置基线顺序”，不再把显示顺序误写成下一次保证执行顺序；Ordered 下不可用的偏好/后台项也恢复明确 disabled 视觉与 ARIA 状态。
- **Mixed-save trap closed before release (#303)**: v2 immediate routing controls are blocked while the React Settings IA still has unrelated unsaved drafts, preventing partial state such as “Auto saved, model-chain edit lost.” Auto labels the displayed chain as the configured baseline rather than a guaranteed next execution order; Ordered-only disabled controls regain clear visual and ARIA state.

- **远程设置继续遵守能力边界**：远程编辑仍默认关闭、需要明确风险确认；API Key、HTTP provider 凭据、本地 Ollama / LM Studio、桌面截图等敏感配置保持本机专属。v2 的安全字段继续通过 Host 权威写入/readback 路径，不引入浏览器侧私有配置副本。
- **Remote settings keep the existing capability boundary**: remote editing remains opt-in behind explicit risk confirmation, while API keys, HTTP-provider credentials, local Ollama / LM Studio and desktop capture stay local-only. Safe v2 fields continue through the authoritative Host write/readback path rather than a browser-side shadow configuration.

## 模型目录、边界与兼容 / Catalog, boundaries & compatibility

- **设置可见模型成为产品权威目录（#288 / #291 / #294）**：显式配置的 Models 行存在时，以它们定义可见/可包装范围；live `/models` 发现只做受限补充，不会把用户已经删除的模型重新塞回 Auto Vision wrapper。wrapper scope、公开 model presentation 与执行权限继续分层。
- **Settings-visible models are authoritative product catalog entries (#288 / #291 / #294)**: explicit configured model rows define visible/wrappable scope; live `/models` discovery is a bounded supplement and cannot resurrect a model the user removed back into Auto Vision wrappers. Wrapper scope, presentation and execution authority remain separate layers.

- **Host 声明与真实调用证据分层**：Host 元数据可以提示某模型是 text-only，但不会单独阻止用户显式 Test Vision；真实图片请求成功/拒绝才建立当前 deployment 的更强证据。这避免静态目录过期时把实际可用模型永久挡掉。
- **Host metadata and real call evidence are layered**: Host metadata may advise that a model is text-only, but does not alone prevent an explicit Test Vision. A real image success or rejection creates stronger evidence for the current deployment, avoiding permanent false negatives from stale catalogs.

- **Vision toggle DOM 根边界收紧（#300）**：增强逻辑只作用于确认属于 Vision Router / DSH 模型选择器的根节点，不会因为相似 ARIA/menu 结构去改写、隐藏或影响第三方界面。
- **Vision-toggle DOM root boundaries are hardened (#300)** so enhancement only touches confirmed Vision Router / DSH model-picker roots instead of rewriting or hiding unrelated third-party ARIA/menu structures.

- **安全与 wire 兼容修复（#295 / #296）**：风险 regex 改为有界/线性判断以通过 CodeQL 并避免病态输入放大；可选图片 metadata（如 `originalDimensions`）可以被兼容接受，但实际图片字节仍是格式、尺寸和资源准入的权威来源。
- **Security and wire compatibility fixes (#295 / #296)** replace risky regex paths with bounded/linear checks and accept optional image metadata such as `originalDimensions` without allowing metadata to override the actual image bytes as the source of truth for format, dimensions or resource admission.

- **DSH 多版本兼容继续作为硬门禁**：CI 持续验证 Node 22 / 24、DSH rc.6 / rc.7 / rc.8 contract、Ubuntu / macOS / Windows host-sharp、native multimodal cold resume 与大图资源压力；真实发布验收使用 DSH 0.1.1-rc.1。
- **DSH compatibility remains a release gate**: CI continues to exercise Node 22/24, DSH rc.6/rc.7/rc.8 contracts, Ubuntu/macOS/Windows host-sharp, native-multimodal cold resume and large-image stress, while real-machine release acceptance was performed on DSH 0.1.1-rc.1.

## 真实验收与发布门禁 / Real-machine acceptance & release gates

- **v2 在真实 DSH 0.1.1-rc.1 环境完成发布验收**：覆盖真实 DeepSeek 拒图、OpenRouter 不可用 deployment、Kimi visual-proof、GLM 慢 Quick Benchmark、前台/手动抢占、撤销后台授权、重启持久化与普通视觉执行。最终复验结果为 **GO**。
- **v2 completed real-machine release acceptance on DSH 0.1.1-rc.1**, covering real DeepSeek image rejection, unavailable OpenRouter deployment behavior, Kimi visual-proof scoping, a real GLM Quick benchmark, foreground/manual preemption, background revocation, restart persistence and normal visual execution. Final recheck result: **GO**.

- **关键复验硬指标**：DeepSeek 判定“实测仅文本”后后台新增请求 **0**；Sol 同 fingerprint 重启后后台请求 **0**；Kimi visual-proof 失败轴重启后重复请求 **0** 且其他能力不被整模型封锁；GLM Quick 为 **3 个请求 / completed / profile 成功写入**。
- **Key recheck evidence**: **0** new background requests after DeepSeek was measured text-only; **0** Sol background requests after restart on the same fingerprint; **0** repeat requests for Kimi’s failed visual-proof axes without model-wide lockout; GLM Quick completed with **3 requests / completed state / persisted profile update**.

- **#302 发布阻塞修复也跑过完整同 SHA 门禁**：原作者提交在 Node 22 / 24、DSH rc.6 / rc.7 / rc.8、Ubuntu / macOS / Windows host-sharp、native multimodal cold resume 和大图资源压力上全部通过后才合入 `main`，再同步进 2.0.0 release branch。
- **The #302 release-blocking fix was validated on the exact contributor SHA** across Node 22/24, DSH rc.6/rc.7/rc.8, Ubuntu/macOS/Windows host-sharp, native-multimodal cold resume and large-image stress before being merged to `main` and synchronized into the v2.0.0 release branch.

- **发布不是“CI 绿了就算完”**：正式 tag 还会由 Release workflow 在不可变源码上重新运行完整 `pnpm test`，校验 tag 与 `package.json` 版本一致、tag 可从 `main` 到达，并通过 npm Trusted Publishing (OIDC) 发布和核对 tarball 身份。
- **Release is not merely “CI is green”**: the final immutable tag is re-verified by the Release workflow, which reruns full `pnpm test`, checks tag/package-version identity and reachability from `main`, then publishes through npm Trusted Publishing (OIDC) and verifies the exact registry tarball.

## 升级时需要知道的变化 / Upgrade notes

- **不会自动打开 Auto**：现有安装升级后仍按原来的用户授权边界运行。想继续旧的行为，保持“按设置顺序”即可；想用 v2 Auto，再主动开启并单独选择后台能力数据权限。
- **Auto is never silently enabled on upgrade**: existing installs keep the same authority boundary. Leave “Configured order” selected for the previous behavior; opt into v2 Auto explicitly and choose background capability profiling separately.

- **旧 Smoke Test 心智模型已经变化**：2.0 更推荐用每行「测试识图」确认“这个模型本身能不能看图”，再用 Quick / Full 回答“它在哪些视觉任务上表现更好”。两者不会混为一个“整条链通不通”的结果。
- **The old smoke-test mental model has changed**: use per-row Test Vision to answer “can this exact model accept images?”, then Quick / Full to answer “which visual tasks is it good at?”. Those are intentionally separate from whole-chain fallback success.

- **内部 wrapper 仍然存在，只是普通模型 UI 默认不展示**：不要把“模型列表里看不到 `+ 自动识图`”理解成 route 被删除。Host route 仍用于图片准入和 Vision Router 切换，只是 presentation 层降噪。
- **Internal wrappers still exist even though the ordinary model UI hides them by default**: absence of a `+ Auto Vision` entry does not mean the Host route was removed. It remains available for image admission and Vision Router switching; only presentation is simplified.

- **后台测评可能产生真实费用**：默认 `off`。如果选择 `all`，Vision Router 会在 Auto 激活、系统空闲时对授权的云端模型补充能力证据；随时切回 `off` 可以撤销后续后台请求。
- **Background profiling can create real API cost**: it defaults to `off`. Choosing `all` allows authorized cloud models to be profiled while Auto is active and the system is idle; switching back to `off` revokes future background requests.

- **推荐仍使用官方 DSH CLI 安装/更新**。2.0.0 仍不要求 Python；既有识图模型、本地后端和安全远程设置配置继续经过迁移/规范化层读取。
- **The official DSH CLI remains the recommended install/update path**. v2.0.0 still requires no Python, and existing vision-model, local-backend and safe remote-settings configuration continues through the migration/normalization layer.

## 设计来源与致谢 / Design attribution & acknowledgements

特别感谢 **@shaoqiuyuavailable** 及其项目 **`shaoqiuyuavailable/text-llm-vision`（dsh-vision）**。v2 在 scene-aware routing、classify-first，以及 precision/depth 分层方向上的一部分思路，受到其更早的探索、讨论与持续 PR 贡献启发；相关贡献也通过 #98、#177、#178 等工作进入了项目演进过程。

Special thanks to **@shaoqiuyuavailable** and **`shaoqiuyuavailable/text-llm-vision` (dsh-vision)**. Part of v2’s direction around scene-aware routing, classify-first reasoning, and precision/depth tiers was informed by that project’s earlier exploration, discussions, and continued pull-request contributions, including work represented in #98, #177 and #178.

这里的归因限定在上述**概念与设计方向**。v2 的 exact-endpoint Benchmark/profile、`Authority → Evidence → Planner → Execution` 权限模型、保守证据策略、deployment fingerprint、后台测评调度与持久化、runtime execution gate，以及 Settings 中的 Auto 控制，是为 `dsh-vision-router` 独立设计和工程化实现的。

This attribution is intentionally scoped to those **conceptual and design directions**. v2’s exact-endpoint Benchmark/profile system, `Authority → Evidence → Planner → Execution` authority model, conservative evidence policy, deployment fingerprints, background profiling/persistence, runtime execution gate, and Settings Auto controls were independently designed and engineered for `dsh-vision-router`.

感谢所有提交 issue、PR、真机复现、兼容性反馈和对抗式测试的社区贡献者；2.0 的不少发布前边界就是由这些真实反馈推动收紧的。

Thanks as well to everyone who filed issues and PRs, reproduced failures on real machines, reported compatibility problems, or stress-tested edge cases. Many of v2’s release-hardening boundaries exist because of that community feedback.

## 安装 / Install

```sh
npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
```

升级后按平时方式重新加载 / 重启 DSH Web，使 Host 重新加载插件即可。
After upgrading, reload or restart DSH Web normally so the Host reloads the plugin.