⚠️ 在 Web 设置页配置的模型，能力声明可能是空的

插件的判定完全依赖配置里声明的 inputModalities，而不是模型的真实能力。而 Web 设置页不提供这个字段——这是最容易踩空的一处，单独说清楚。

声明写在 ~/.dsh/settings.yaml 的 llm-deepseek.models[] 里：

llm-deepseek:
  models:
    - id: deepseek-v4-pro
      name: DeepSeek-V4-Pro
      contextWindow: 1000000
      inputModalities:        # ← 决定插件介入还是静默的就是这一项
        - text

Web 模型编辑器只暴露 4 个字段：id / name / contextWindow / maxTokens。 inputModalities 不在其中，所以在页面上新增模型时，写回的条目里没有这一项，而配置 schema 会给它兜底成 ['text']。

在 Web 页面上做的事	对该模型能力声明的影响
新增一个模型	条目里没有 `inputModalities` → 按纯文本处理
编辑已有模型的 name / 窗口 / tokens	原有声明原样保留（页面的 patch 是「展开合并」语义，不会删掉它不认识的字段）

兜底成纯文本会怎样：

该模型确实不支持图片 → 正好是插件该介入的场景，不用管。
该模型其实支持图片（自建 vision 端点，或想把某个多模态模型接进来）→ 插件会多此一举地介入，图片被 Harness 投影成 [image omitted …] 占位符，本来能看图却看不到。这时必须手工补声明：

      inputModalities:
        - text
        - image

改完不用重启：settings.yaml 是热加载的（文件监听 + 去抖），保存即生效。

声明要满足的约束（写错会在加载时直接报错，不会静默忽略）：

必须是非空数组，元素只能是 text / image，且不能重复。
声明了 image 才能写 imagePixelBudget（像素预算，可填 low 或正整数）与 imageMaxBytes （单图字节上限）。纯文本模型写了这两个字段会直接报错： text-only catalog model "xxx" cannot declare image request limits。

非 DeepSeek 的 provider 卡片有自己的字段集合，能力声明的字段名以该 adapter 的配置 schema 为准。

顺带说清一个相关语义：settings.yaml 里的 models 是整体覆盖内置目录的，而模型选择器显示的正是这个数组（适配器的 listModels 直接映射它）。所以在 Web 页面上动过模型列表之后，选择器里有哪些模型完全以这个数组为准—— 把 deepseek-v4-flash-vision-exp 删掉了，就一个多模态模型都切不过去了（本机默认是保留的）。

第 3 步：开始使用

方式 A：粘贴截图（最常用）

在 Web 输入框里按 Ctrl+V / Cmd+V。图片走浏览器原生的附件流程进入会话，之后按上面的表自动分流：纯文本模型 → 本插件兜底；多模态模型 → 模型直接看图。

方式 B：告诉 agent 图片路径

把图片文件的绝对路径（或 ~/…）发给 agent，说「识别这张图片」。

方式 C：直接用附件 sha256（模型自己会做的事）

纯文本模型收到的图片会被 harness 换成一句占位符：

[image omitted because this model accepts text only; attachment sha256:2cd17c8d…]

这串 sha256 就是线索——ocr_image 的 ref 参数认它（8 位前缀就够，如 2cd17c8d），插件据此从本地缓存取图。工具描述里已写明这一点，模型通常第一次就调对，不需要去 find 或者翻 ~/.dsh/attachments/。

配置（可选，默认不用动）

配置文件：~/.dsh/profiles/web/cordis.patch.yml

- insert:
    - id: ocr
      name: 'dsh-ocr-local'
      config:
        autoOcr: true                                   # 见下表
        pythonPath: ~/miniconda3/envs/ocr/bin/python   # 可选：指定 Python
        modelDir: ~/.dsh-ocr/models                     # 可选：模型目录
        cacheDir: ~/.dsh/ocr/cache                      # 可选：图片缓存目录
        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`）

dsh-ocr-local

同名包的其他仓库

安装

说明文档

⚠️ 在 Web 设置页配置的模型，能力声明可能是空的

第 3 步：开始使用

配置（可选，默认不用动）