dsh-ocr-local 0.4.0

package/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 dsh-ocr-local contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party components:
+
+- PP-OCRv5 models (PP-OCRv5_mobile_det.onnx / PP-OCRv5_mobile_rec.onnx)
+  and ppocrv5_dict.txt are from PaddleOCR (https://github.com/PaddlePaddle/PaddleOCR),
+  Apache License 2.0. Downloaded at install time by ocr/download_models.py,
+  not bundled in this repository.
+- ONNX Runtime is MIT licensed (https://github.com/microsoft/onnxruntime).

package/README.en.md

@@ -0,0 +1,218 @@
+# dsh-ocr-local
+
+[English](README.en.md) · [中文](README.md)
+
+[![license](https://img.shields.io/npm/l/dsh-ocr-local?style=flat-square)](LICENSE) [![GitHub](https://img.shields.io/badge/GitHub-grelvan%2Fdsh--ocr--local-2f81f7?style=flat-square)](https://github.com/grelvan/dsh-ocr-local)
+
+A **local OCR fallback** for DeepSeek Harness (Web): when the model a session is
+routed to **cannot accept image input**, this plugin reads the text out of a
+pasted image for it. When the model *can* see images, the plugin stays completely
+silent.
+
+The engine is PP-OCRv5 + ONNX Runtime — **CPU-only, fully offline**, and your
+images never leave your machine.
+
+## When the plugin acts, and when it stays silent
+
+This is the most important table here. The decision is based on the input
+capabilities the session's **actually routed model** declares
+(`inputModalities`) — it is not a guess:
+
+| Model routed by the session | Plugin behaviour | What the model actually receives |
+| --- | --- | --- |
+| **Explicitly cannot accept images** (e.g. a text-only model) | ✅ **Acts**: the image is saved to a local cache and its path is injected, so the model calls `ocr_image` | Text. For these models the harness substitutes only `[image omitted because this model accepts text only; …]` — **no path at all**, so without this plugin the model cannot read the image |
+| **Explicitly accepts images** (multimodal model) | 🔇 **Silent**: no cache write, no hint injected | The image itself. The harness also prefixes a **read-only copy path**, so the model can call `ocr_image` on that path when it needs verbatim characters |
+| **Cannot be determined** (provider not registered / lookup failed / no modalities declared) | 🔇 **Silent** | Handled by the harness as usual. Better not to intrude than to add an OCR hint to a model that may well see images |
+
+"Silent when undetermined" is deliberate. If you genuinely want unconditional
+intervention, set `autoOcr: 'always'` (see Configuration below).
+
+> On **unlisted model ids**: the DeepSeek adapter explicitly returns
+> `inputModalities: ["text"]` for ids that are not in the model catalog, so those
+> text-only routes are covered by row 1. Other providers that report no modality
+> information for undeclared models fall through to row 3 (silent).
+
+## Relationship to vision models
+
+The two paths do not interfere, because they operate at different layers:
+
+- **This plugin only does local OCR**: it caches the image and asks the model to
+  call `ocr_image`.
+- **Whether the image is sent to the model** is decided by model capability and
+  client configuration; the plugin does not interfere.
+
+So with a multimodal model you do not need to do anything: the plugin withdraws
+on its own. If you want the text read anyway, just tell the agent "read this
+image with ocr_image".
+
+## Quick start
+
+### Step 1: Install the plugin
+
+DSH profiles are isolated, so install the plugin into **the profile you use**
+(the Web profile is usually called `web`):
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web add dsh-ocr-local
+```
+
+**Or straight from GitHub** (to track the latest commits, or when npm is
+unreachable):
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web add github:grelvan/dsh-ocr-local
+```
+
+**Or from a local clone:**
+
+```sh
+git clone https://github.com/grelvan/dsh-ocr-local.git
+npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-ocr-local
+```
+
+**Restart dsh** after installing, or the plugin will not take effect.
+
+### Step 2: Prepare the recognition engine (once)
+
+Send the agent any image and say:
+
+> read the text in this image
+
+If the engine is not ready yet, the tool tells you what is missing. Then say:
+
+> install the OCR environment with the ocr_setup tool
+
+The plugin will **create a virtualenv → install Python dependencies → download
+the models** (about 20MB). After that every recognition runs locally in seconds.
+
+> Manual install works too (replace `<profile>` with your profile name, e.g. `web`):
+>
+> ```sh
+> python ~/.dsh/profiles/<profile>/node_modules/dsh-ocr-local/ocr/setup.py
+> ```
+
+### Step 3: Use it
+
+**Option A: paste a screenshot (most common)**
+
+Press Ctrl+V / Cmd+V in the Web composer. The image enters the session through
+the browser's native attachment flow, and then splits according to the table
+above: text-only model → this plugin covers it; multimodal model → the model
+looks at the image directly.
+
+**Option B: give the agent a path**
+
+Send the agent the absolute path of an image file and say "read this image".
+
+## What it handles / limits
+
+| ✅ Good at | ⚠️ Mediocre |
+| --- | --- |
+| Screenshots, error dialogs, chat logs | Very small text (e.g. 4px) may have a few wrong characters |
+| Mixed Chinese + English, long paragraphs | Complex backgrounds, stylized fonts, handwriting |
+| Dark-theme screenshots (auto-inverted) | Blurry or heavily compressed images |
+
+In the output, **lines that are too small or low-confidence are flagged ⚠**, so
+you can tell which characters are not fully trustworthy.
+
+### Why local OCR is still worth it for verbatim fidelity
+
+A multimodal model looking at an image and local OCR reading it do **not** get
+the same amount of information:
+
+| | Multimodal model looking directly | Local OCR |
+| --- | --- | --- |
+| Resolution reaching the model | Bounded by the harness per-image pixel budget (640,000 px by default). A 1920×1080 screenshot is downscaled to about 1066×600 | Detection runs at a 736px longest side, but **recognition crops from the original image**, enlarging small text first (glyph height floor 20px, up to 6×) |
+| Output | A paraphrase by the model, with **no signal about what it is unsure of** | Per-line text plus confidence / glyph height / box coordinates, with low-confidence lines flagged ⚠ |
+| Best for | Understanding what is happening in the screenshot | Copying code, checking error messages, verifying hashes, reading table numbers |
+
+An honest boundary note: the detection stage's 736px longest side is **more
+conservative than the multimodal path's ~1066px**, so very small text in a
+full-screen 4K screenshot can be missed here too. The accurate claim is
+**"lines it does detect are transcribed more precisely"**, not "unlimited
+resolution".
+
+## Configuration (optional; defaults are fine)
+
+Config file: `~/.dsh/profiles/web/cordis.patch.yml`
+
+```yaml
+- insert:
+    - id: ocr
+      name: 'dsh-ocr-local'
+      config:
+        autoOcr: true                                   # see the table below
+        pythonPath: ~/miniconda3/envs/ocr/bin/python   # optional: pick a Python
+        modelDir: ~/.dsh-ocr/models                     # optional: model directory
+        maxCacheFiles: 300                              # optional: cache file cap
+        maxCacheAgeDays: 30                             # optional: cache retention
+```
+
+`autoOcr` has three states:
+
+| Value | Behaviour |
+| --- | --- |
+| `true` (default) | Automatic: acts **only when the model explicitly cannot accept images** |
+| `false` | No automatic intervention at all. The model can still call `ocr_image` on request |
+| `'always'` | Unconditional intervention (a hint is injected even for vision-capable models). The old 0.3.x behaviour; useful for troubleshooting |
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `DSH_OCR_MODELS_MIRROR` | Mirror prefix for model downloads (e.g. `https://ghproxy.com/`) |
+| `DSH_OCR_PYTHON` | Which Python the OCR engine uses (auto-detected by default) |
+| `DSH_OCR_MODELS` | Model directory (defaults to `~/.dsh-ocr/models`) |
+
+## FAQ
+
+**Q: I pasted an image but the model says it cannot see it.**
+First check whether the current model is text-only (the only case this plugin is
+meant to cover). If it is, verify the engine is ready ("check the OCR
+environment with ocr_setup"). With a multimodal model the model simply looks at
+the image, and this plugin is silent by design.
+
+**Q: "Environment not ready" / "missing dependencies"?**
+Tell the agent "install the OCR environment with ocr_setup", or run
+`python ~/.dsh/profiles/web/node_modules/dsh-ocr-local/ocr/setup.py` manually.
+
+**Q: Model download is slow or fails?**
+Set the mirror and retry (idempotent):
+`DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python .../ocr/setup.py`
+
+**Q: pip reports externally-managed-environment (PEP 668)?**
+Do not add `--break-system-packages`. Use `ocr/setup.py` — it creates a
+virtualenv automatically and sidesteps the system Python restriction.
+
+**Q: The recognition has wrong characters.**
+Check the ⚠ flags in the output. For very small text the engine does misread:
+scale the original image up and retry, or ask the agent to double-check that line.
+
+**Q: Why does the plugin no longer intercept my paste?**
+As of 0.4.0 it does not. The Web composer already intakes pasted images through
+its native attachment flow; intercepting only prevented vision-capable models
+from seeing the image. The old `pasteToPath` config key is gone — you can delete it.
+
+## How it works (one sentence)
+
+A pasted image enters the session as an attachment through the native flow →
+the plugin listens for `user/message` events → it queries the routed model's
+`inputModalities` → **only when the model explicitly cannot accept images** does
+it save the image to `~/.dsh/ocr/cache` and inject its path → the model calls
+`ocr_image` → local PP-OCRv5 models (ONNX Runtime, CPU-only) → text. Models are
+downloaded to `~/.dsh-ocr/models` on first use and everything is offline
+afterwards. More detail in [docs/usage.md](docs/usage.md).
+
+## Upgrading
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web update dsh-ocr-local
+```
+
+If you installed from a local directory, `git pull` and re-run `add` in the
+plugin directory.
+
+## License
+
+MIT (code). The recognition models are Apache-2.0 (PaddleOCR) and are downloaded
+during setup. See [LICENSE](LICENSE).

package/README.md

@@ -0,0 +1,195 @@
+# dsh-ocr-local
+
+[English](README.en.md) · [中文](README.md)
+
+[![license](https://img.shields.io/npm/l/dsh-ocr-local?style=flat-square)](LICENSE) [![GitHub](https://img.shields.io/badge/GitHub-grelvan%2Fdsh--ocr-local-2f81f7?style=flat-square)](https://github.com/grelvan/dsh-ocr-local)
+
+给 DeepSeek Harness（Web 端）装一个**本地 OCR 兜底**：当会话路由到的模型**不支持图片输入**时，
+把图片里的文字读出来给模型；模型能看图时，插件完全静默、不插手。
+
+识别引擎是 PP-OCRv5 + ONNX Runtime，**纯 CPU、完全离线**，图片不会离开你的电脑。
+
+## 插件什么时候生效，什么时候静默
+
+这是理解本插件最重要的一张表。判定基于当前会话实际路由到的模型**声明的输入能力**
+（`inputModalities`），而不是猜：
+
+| 会话路由到的模型 | 插件行为 | 模型实际拿到什么 |
+| --- | --- | --- |
+| **明确声明不支持图片**（如纯文本模型） | ✅ **生效**：图片存到本地缓存，并注入路径提示 → 模型调 `ocr_image` 识别 | 文字。Harness 对这类模型只给一句 `[image omitted because this model accepts text only; …]`，**没有任何路径**，所以没有本插件模型就完全读不到图 |
+| **明确声明支持图片**（多模态模型） | 🔇 **静默**：不存缓存、不注入提示 | 图片本身。Harness 还会在图片前附一条**只读副本路径**，模型想逐字核对时可以直接对那个路径调 `ocr_image` |
+| **无法确定**（provider 未注册 / 查询失败 / 没声明模态） | 🔇 **静默** | 按 Harness 原样处理。宁可不打扰，也不在一个可能能看图的模型上多塞提示 |
+
+"无法确定就静默"是刻意的。如果你确实需要无条件介入，把 `autoOcr` 设成 `'always'`（见下方配置）。
+
+> 关于「未登记的 model id」：DeepSeek 适配器对没写进模型目录的 id 会**显式**返回
+> `inputModalities: ["text"]`，所以这类纯文本路由会被上表第一行正确覆盖。
+> 其它 provider 若对未声明模型返回「无模态信息」，则落到第三行（静默）。
+
+## 与视觉模型的关系
+
+两条链路互不干扰，因为它们在**不同的层**做事：
+
+- **插件只管本地 OCR**：把图存到本地、提示模型去调 `ocr_image`。
+- **图要不要发给模型**由模型能力 / 客户端配置决定，插件不干预。
+
+所以多模态模型下你不需要为本插件做任何事：它会自己退场。想手动让它读图里的字，
+随时可以直接对 agent 说「用 ocr_image 读这张图」。
+
+## 快速开始
+
+### 第 1 步：安装插件
+
+DSH 的 profile 互相隔离，插件要装到**你要用的那个 profile**（Web 端通常叫 `web`）：
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web add dsh-ocr-local
+```
+
+**也可以直接从 GitHub 安装**（想跟最新提交、或 npm 不可达时）：
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web add github:grelvan/dsh-ocr-local
+```
+
+**或本地克隆后安装：**
+
+```sh
+git clone https://github.com/grelvan/dsh-ocr-local.git
+npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-ocr-local
+```
+
+装完**重启 dsh**，插件才会生效。
+
+### 第 2 步：准备识别引擎（只需一次）
+
+把任意一张图片发给 agent，说：
+
+> 识别这张图片
+
+如果引擎还没装好，工具会告诉你缺什么。这时再对 agent 说：
+
+> 用 ocr_setup 工具安装 OCR 环境
+
+插件会自动完成三件事：**建虚拟环境 → 装 Python 依赖 → 下载识别模型**（约 20MB），
+之后每次识别都在本地秒级完成。
+
+> 想手动装也可以（把 `<profile>` 换成你的 profile 名，如 `web`）：
+>
+> ```sh
+> python ~/.dsh/profiles/<profile>/node_modules/dsh-ocr-local/ocr/setup.py
+> ```
+
+### 第 3 步：开始使用
+
+**方式 A：粘贴截图（最常用）**
+
+在 Web 输入框里按 Ctrl+V / Cmd+V。图片走浏览器原生的附件流程进入会话，
+之后按上面的表自动分流：纯文本模型 → 本插件兜底；多模态模型 → 模型直接看图。
+
+**方式 B：告诉 agent 图片路径**
+
+把图片文件的绝对路径发给 agent，说「识别这张图片」。
+
+## 能识别什么 / 有什么限制
+
+| ✅ 擅长 | ⚠️ 效果一般 |
+| --- | --- |
+| 截图、报错弹窗、聊天记录 | 极小的字（如 4px）可能有个别错字 |
+| 中文 + 英文混排、长段落 | 复杂背景、艺术字、手写体 |
+| 暗色主题截图（自动反色处理） | 模糊或严重压缩的图片 |
+
+识别结果里，**字太小或置信度低的行会标注 ⚠**，方便你判断哪些字不能全信。
+
+### 为什么"逐字保真"这件事仍然值得用本地 OCR
+
+多模态模型看图和本地 OCR 读图，拿到的**信息量不一样**：
+
+| | 多模态模型直接看图 | 本地 OCR |
+| --- | --- | --- |
+| 送进模型的分辨率 | 受限于 Harness 的每图像素预算（默认 640,000 px）。1920×1080 的截图会被压到约 1066×600 | 检测阶段最长边 736px，但**识别阶段是从原图裁块**，小字还会先放大（字高下限 20px，最多 6×） |
+| 输出 | 模型的一段转述，**不告诉你它哪里不确定** | 逐行文本 + 每行置信度 / 字高 / 坐标框，低置信行标 ⚠ |
+| 适合 | 看懂截图里发生了什么 | 抄代码、对报错信息、核 hash、读表格数字 |
+
+诚实的边界说明：检测阶段的最长边限制是 736px，**比多模态链路的约 1066px 更保守**，
+所以 4K 全屏截图里极小的字，本插件也可能漏检。准确的说法是
+**"检得到的行，认得更准"**，而不是"分辨率无上限"。
+
+## 配置（可选，默认不用动）
+
+配置文件：`~/.dsh/profiles/web/cordis.patch.yml`
+
+```yaml
+- insert:
+    - id: ocr
+      name: 'dsh-ocr-local'
+      config:
+        autoOcr: true                                   # 见下表
+        pythonPath: ~/miniconda3/envs/ocr/bin/python   # 可选：指定 Python
+        modelDir: ~/.dsh-ocr/models                     # 可选：模型目录
+        maxCacheFiles: 300                              # 可选：图片缓存最多文件数
+        maxCacheAgeDays: 30                             # 可选：图片缓存保留天数
+```
+
+`autoOcr` 三态：
+
+| 值 | 行为 |
+| --- | --- |
+| `true`（默认） | 自动判定：**只有模型明确不支持图片输入时**才介入 |
+| `false` | 完全关闭自动介入。仍可手动让模型调 `ocr_image` |
+| `'always'` | 无条件介入（即使模型能看图也注入提示）。旧版 0.3.x 的行为，排查问题时可用 |
+
+常用环境变量：
+
+| 变量 | 作用 |
+| --- | --- |
+| `DSH_OCR_MODELS_MIRROR` | 模型下载镜像前缀（国内下载慢时设，如 `https://ghproxy.com/`） |
+| `DSH_OCR_PYTHON` | 指定 OCR 用哪个 Python（默认自动找） |
+| `DSH_OCR_MODELS` | 模型存放目录（默认 `~/.dsh-ocr/models`） |
+
+## 常见问题
+
+**Q：粘贴了图片，但模型说看不到图？**
+先确认当前模型是不是纯文本模型（这是本插件唯一该生效的场景）。如果是，检查引擎是否就绪
+（对 agent 说「用 ocr_setup 检查 OCR 环境」）。如果用的是多模态模型，模型直接看图即可，
+本插件按设计就是静默的。
+
+**Q：提示「环境未就绪」/「缺少依赖」？**
+对 agent 说「用 ocr_setup 安装 OCR 环境」即可自动修复；或手动运行
+`python ~/.dsh/profiles/web/node_modules/dsh-ocr-local/ocr/setup.py`。
+
+**Q：模型下载很慢或失败？**
+设镜像后重试（幂等，可反复跑）：
+`DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python .../ocr/setup.py`
+
+**Q：系统提示 pip externally-managed-environment（PEP 668）？**
+不要加 `--break-system-packages`。直接用 `ocr/setup.py`——它会自动创建虚拟环境，
+绕开系统 Python 的限制。
+
+**Q：识别结果有错字？**
+看输出里的 ⚠ 标注。字太小时模型确实会看走眼：把原图放大一点再试，
+或让 agent 把对应行再确认一遍。
+
+**Q：为什么插件不拦截我的粘贴了？**
+0.4.0 起不再拦截。Web 输入框原生就把粘贴的图片收进附件流程，拦截只会让
+本来能看图的模型反而看不到图。旧配置里的 `pasteToPath` 已失效，可以删掉。
+
+## 工作原理（一句话）
+
+Web 端粘贴的图片按原生流程进入会话成为附件 → 插件监听 `user/message` 事件 →
+查询当前路由模型的 `inputModalities` → **只有明确不支持图片时**，把图片存到
+`~/.dsh/ocr/cache` 并向模型注入路径提示 → 模型调 `ocr_image` → 本地 PP-OCRv5 模型
+（ONNX Runtime，纯 CPU）→ 文字。模型第一次使用时下载到 `~/.dsh-ocr/models`，
+之后完全离线。更多细节见 [docs/usage.md](docs/usage.md)。
+
+## 升级
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web update dsh-ocr-local
+```
+
+从本地目录安装的话，`git pull` 后在插件目录重跑一次 `add` 即可。
+
+## 许可
+
+MIT（代码）。识别模型 Apache-2.0（PaddleOCR），安装时自动下载。见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
+- insert:
+    - id: ocr
+      name: 'dsh-ocr-local'

package/dsh/capability.js

@@ -0,0 +1,82 @@
+/**
+ * dsh-ocr-local — 能力判定（纯函数，零依赖，可单测）。
+ *
+ * 插件只在**明确接入不支持多模态的模型**时才介入：把进入会话的图片存到本地
+ * 缓存并向模型注入路径提示，让它调用 `ocr_image` 本地识别。
+ *
+ * 判定三态：
+ *   - 模型明确声明支持 image（`inputModalities` 含 `image`）→ 静默，交给视觉链路
+ *   - 模型明确声明只支持 text（含未登记的 model id，适配器按其显式返回处理）→ 介入
+ *   - 无法确定（没有 llm 服务 / provider 未注册 / 查询失败 / 没返回模态）→ 静默
+ *
+ * 「无法确定时静默」是有意为之：宁可不打扰，也不要在一个其实能看图的模型上
+ * 多塞一条 OCR 提示。需要无条件介入时用 `autoOcr: 'always'`。
+ */
+
+/** autoOcr 生效模式。 */
+export const AUTO_OCR_MODES = ['off', 'auto', 'always']
+
+/**
+ * 把插件配置解析成生效模式。
+ * @param config - 插件配置对象。
+ * @returns `off`（关闭）| `auto`（仅明确不支持多模态时介入，默认）| `always`（总是介入）。
+ */
+export function autoOcrMode(config = {}) {
+  if (config.autoOcr === false) return 'off'
+  if (config.autoOcr === 'always') return 'always'
+  return 'auto'
+}
+
+/**
+ * 给定模型声明的输入模态，判断是否**明确**不支持图片输入。
+ * @param modalities - `inputModalities` 数组；undefined / 空数组表示无法确定。
+ * @returns 明确只支持文本时为 true。
+ */
+export function isExplicitlyTextOnly(modalities) {
+  if (!Array.isArray(modalities) || modalities.length === 0) return false
+  return !modalities.includes('image')
+}
+
+/**
+ * 是否为一张刚进入会话的图片注入本地 OCR 路径提示。
+ * @param mode - {@link autoOcrMode} 的返回值。
+ * @param modalities - 解析到的 `inputModalities`；undefined 表示无法确定。
+ * @returns 应当注入时为 true。
+ */
+export function shouldInjectOcrPath(mode, modalities) {
+  if (mode === 'off') return false
+  if (mode === 'always') return true
+  return isExplicitlyTextOnly(modalities)
+}
+
+/**
+ * 从候选来源里选出「下一条请求会用哪个 provider/model」。
+ * 按可信度排序：用户刚切换的待生效选择 → 上一次真实请求的请求头 → 会话创建时的路由。
+ * @param candidates - `{ pending, header, options }`，每项可为 undefined 或
+ *   `{ provider, model }` 形状的对象。
+ * @returns `{ provider, model, source }`，都取不到时返回 undefined。
+ */
+export function pickRoute(candidates = {}) {
+  const order = [
+    ['pending', candidates.pending],
+    ['header', candidates.header],
+    ['options', candidates.options],
+  ]
+  for (const [source, value] of order) {
+    if (!value) continue
+    const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
+    const model = typeof value.model === 'string' ? value.model.trim() : ''
+    if (provider && model) return { provider, model, source }
+  }
+  return undefined
+}
+
+/**
+ * 跨会话共用的模态缓存键。
+ * @param provider - provider 路由 id。
+ * @param model - 模型 id。
+ * @returns 稳定的缓存键。
+ */
+export function modalityCacheKey(provider, model) {
+  return `${provider}\u0000${model}`
+}