前言¶

DSH 的扩展方式是插件化。一个具体场景是：主模型保持 text-only，但聊天框里已经出现了图片。dsh-vision-fallback 处理的是这个落差：它不改变主模型，也不要求在 UI 里额外处理图片，而是在请求层把图片自动交给固定视觉模型，转换后以隐藏文本上下文返回给主模型。

这是什么¶

dsh-vision-fallback 是 1HelloMan1 维护的 DSH 插件，许可证为 MIT。

它的核心定位是：主模型照常选择，图片自动交给固定视觉模型后，以隐藏上下文返回主模型。聊天框中的原图仍保留在 UI 中。

已核实兼容的 DSH 版本包括：

• 0.1.2-alpha.3
• 0.1.2-alpha.4
• 0.1.2-alpha.5

运行要求为 Node >=22.13.0。

核心功能¶

• 主模型保持 text-only，聊天框图片自动交给固定视觉模型，并转换为隐藏文本上下文；UI 保留原图。
• 处理 MCP / ACP 持久化附件与 PTC 嵌套图片，并保持原顺序。
• 支持通过 DSH Web 设置页或 settings.yaml 配置视觉增强。
• 视觉模型请求不使用工具、系统提示或执行权限。
• 切换主模型不会改变固定视觉模型。

安装与启用¶

先安装到 web profile：

dsh plugin --profile web add dsh-vision-fallback

安装后查看配置层，确认插件已注入：

dsh --profile web --dump-config

在输出中应能看到：

# == dsh-vision-fallback layer

由于 patch/bundle 层不支持热加载，需要重启 web 进程：

dsh web

如果从源码目录准备插件，pnpm install 可能需要添加绕过 pre-release peers 限制的参数：

pnpm install --config.minimumReleaseAge=0

典型用法¶

在 DSH Web UI 中进入：

Settings → 视觉增强 / Vision Enhancement

可配置项包括：

• Enabled
• Vision model
• Base URL
• Credential ref

也可以用 settings.yaml 配置。已列出的配置项包括：

vision-fallback:
  enabled: true
  model: <vision-model>
  baseURL: <vision-base-url>
  apiKeyRef: <credential-ref>

apiKeyRef 指向 DSH credentials 中的凭据引用。API key 通过 DSH credentials 解析，不写入 shell 环境文件。

如果启用 recordUsage，真实外部视觉调用会追加到：

<dshHome>/vision-fallback/usage.jsonl

该记录只统计真实外部视觉调用；复用缓存 observation 不追加。

适用场景与注意¶

适合以下场景：

• 主模型是 text-only，但你希望聊天框图片进入主模型可见的上下文。
• 希望固定一个视觉模型做图片转文本，而不随主模型切换改变。
• 需要处理普通聊天图片、MCP / ACP 持久化附件、PTC 嵌套图片，并保持原有顺序。

使用前注意：

• 已明确列出的兼容版本是 0.1.2-alpha.3、0.1.2-alpha.4、0.1.2-alpha.5。
• 安装后需要重启 dsh web，因为 patch/bundle 层不支持热加载。
• 视觉模型请求不使用工具、系统提示或执行权限。
• API key 通过 DSH credentials 解析，不写入 shell 环境文件。
• 插件以当前 dsh 进程权限运行；安装前应检查源码与许可证。
• usage.jsonl 只记录真实外部视觉调用，不记录复用缓存 observation。

参考¶

GitHub：https://github.com/1HelloMan1/dsh-vision-fallback