前言¶

DeepSeek Harness (DSH) 中的大多数模型（如 deepseek-v4-pro）为纯文本。当用户粘贴图片时，网关（如 opencode-go）可能会返回 400 unknown variant image_url。一旦图片出现在会话日志中，每次对话回放都会重复此错误，导致会话死锁。dsh-vision-guard 旨在解决这个问题。

简介¶

dsh-vision-guard 是一个透明图片防护与视觉分析工具，用于 DeepSeek Harness (dsh)。它由 good-boy4069 开发，采用 MIT 许可证。该插件通过两道防线，将图片转换为文本，让文本模型能够“看见”图片，同时防止死锁发生。

核心功能¶

该插件包含以下核心能力：

1. 转换图片为文本：在图片写入会话日志前，先通过视觉模型将其转换为文本，防止因日志中存在图片块导致的死锁。
2. 修复死锁会话：对于已存在死锁的会话，插件会在请求时重写历史记录中的图片为 OCR 文本，恢复对话功能。
3. vision_analyze 工具：支持本地 OCR、PDF、docx、pptx 以及视频文件的分析。
4. 原生图片透传：通过白名单机制，为真正支持图片的路由提供原生支持。
5. 零依赖：纯 Node 内置模块构建，无额外复杂依赖。

安装与启用¶

安装该插件使用以下命令：

dsh plugin --profile web add dsh-vision-guard

安装完成后，dsh web 进程会自动加载该插件。

典型用法¶

1. 配置视觉路由¶

在 DSH 的配置中，需要指定一个支持图片的视觉模型。默认配置如下：

visionProvider: opencode-go
visionModel: minimax-m3

请确保 visionModel 指向一个支持图片输入的模型。

2. 使用 vision_analyze 工具¶

在模型调用时，可以使用 vision_analyze 工具。该工具通过 engine 参数选择 OCR 引擎：
* local：本地 OCR（免费，字符识别）。
* vision：使用上述配置的视觉模型。

3. 检查运行状态¶

可以通过以下代码检查插件运行状态：

ctx.get('visionGuard')?.status()

4. 配置透传白名单¶

对于原生支持图片的路由（如 minimax-m3），需要将其添加到 passthrough 数组中，以避免被重写为文本：

passthrough:
  - { provider: "opencode-go", model: "minimax-m3" }

注意事项与限制¶

1. 模型依赖：使用该插件时，必须配置一个支持图片的模型（例如 minimax-m3）。纯文本模型无法作为视觉模型使用。
2. 系统工具要求：vision_analyze 工具在处理文档和视频时，需要系统安装相应的工具：
   • PDF：pdftotext、pdfimages (poppler-utils)。
   • 视频：ffmpeg、ffprobe。
   • Office 文档：python3。
   • 本地 OCR：tesseract (可选)。
3. 图片大小限制：图片大小被限制在 5 MB 以内。
4. 输入安全性：图片被视为不受信任的输入，仅作为只读数据。
5. 配置耦合警告：如果在仅文本模型的设置中声明了 input: [text, image]，必须保持该插件安装，否则会导致死锁。

总结¶

dsh-vision-guard 通过在日志写入前转换图片内容和请求时重写历史图片，解决了文本模型与图片输入的兼容性问题。它不仅提供了基础的 OCR 能力，还确保了在插件移除或故障时不会导致系统死锁。