@dshp/vision-bridge

配置项（Host 状态）

字段	类型	默认	说明
enabled	boolean	true	总开关，关闭后 vision_describe 直接抛错提示去设置页启用。
primary	{provider, model} | null	null（首次发现后自动选列表首项）	主视觉模型。
fallback	{provider, model} | null	null（自动选第二项）	备用模型，主失败时重试一次。设为 null 表示不重试。
detail	'auto' | 'low' | 'high'	'auto'	默认详细度；high 会追加“逐字转录”后缀，low 追加“简要概括”。
maxImages	1–8	4	单次 vision_describe 最多喂给视觉模型的图片张数，超出取末尾若干张（最新）。
promptTemplate	string	''	可选追加提示词，每次识别都会拼在问题末尾（截断 500 字符，存储上限 2000）。例如“重点看报错弹窗里的红字”。

与动态版的区别：动态（cordis_define）版本的配置只在内存中，重启进程后恢复默认；标准包版本通过官方 settings API 持久化到 settings.yaml（dshp-vision-bridge），重启后不丢，且外部手工编辑 settings.yaml 可热重载。

配置视觉模型（setting.yml）

本插件的候选来自两个来源的并集去重（按 provider/model 字典序）：

1. 配置层：settings 服务中 llm-pi-ai / llm-deepseek 命名空间下，providers[].models[] 里 input 含 image 的模型。
2. 运行时：llm.listProviders() + llm.listModels(provider) 中 inputModalities 含 image 的模型。

因此你只需在 setting.yml 里给多模态模型加上 input: [text, image]，保存后在设置页点“重新读取”即可出现。请参考现有 setting.yml 中 llm-pi-ai 的写法：

llm-pi-ai:
  providers:
    openrouter:
      models:
        - id: qwen/qwen2.5-vl-32b-instruct
          name: Qwen2.5 VL 32B
          input: [text, image] # ← 关键：声明支持图片输入
        - id: openai/gpt-4o-mini
          name: GPT-4o mini
          input: [text, image]

未配置 input: [text, image] 时，设置页会提示“没有在 setting.yml 里找到 input 含 image 的模型”，且 vision_describe 在无 primary/fallback 时会尝试自动选列表首项；若列表为空会抛“没有可用的视觉模型”并指引去设置页。

推荐：至少配两个视觉模型，一个作 primary，一个作 fallback，主失败时自动重试一次。

使用

1. 发图：在对话里直接粘贴或上传图片（支持一次多张，最多 8 张，受 maxImages 限制）。
2. 提问：纯文本模型看到占位符 [image omitted because this model accepts text only…] 后，会自动调用 vision_describe，把你的问题（如“这里报错是什么意思？”、“把图里的文字都转录出来”）连同图片一起发给视觉模型。
3. 查看结果：vision_describe 返回的 description 会以 tool-result 形式回到模型上下文，模型据此继续回答。你也可以在设置页手动点“检查连通性”验证主/备路由是否可达。

进阶：

• 多图时可用 image_hint 指定某一张：填占位符里显示的 sha 前缀（如 a1b2c3）或序号（1 表示本轮第一张）。
• 需要更详细或更简要时，传 detail: high（逐字转录）或 detail: low（2–3 句概括），或在设置页改默认 detail。
• 有固定偏好（如“总是关注右上角的水印”“转录时保留换行”）可写进设置页的“追加提示词”，每次识别自动拼在问题末尾。

配置（cordis.patch.yml 覆盖）

patch 层可覆盖默认值（可选，设置页保存后持久化会覆盖此处）：

- id: dshp-vision-bridge
  name: '@dshp/vision-bridge'
  config:
    enabled: true
    primary: { provider: 'openrouter', model: 'qwen/qwen2.5-vl-32b-instruct' }
    fallback: { provider: 'openrouter', model: 'openai/gpt-4o-mini' }
    detail: auto # auto | low | high
    maxImages: 4 # 1–8
    promptTemplate: '重点看报错弹窗' # 可选，≤2000 字符

设置页的保存会覆盖同名字段并落盘到 settings.yaml 的 dshp-vision-bridge 分节；旧 storages/*.json 与历史旧 key 不会被读取，也不会有任何自动备份/改名（需旧值请手工搬运）。