good-boy4069/dsh-vision-guard

中文 | English

让纯文本模型"看图"，且图片永远不会卡死你的会话。 Transparent image guard + vision analysis tool for DeepSeek Harness (dsh).

DeepSeek Harness 的主流模型（deepseek-v4-pro 等）是纯文本模型。两个麻烦：

1. 纯文本模型看不了图——用户贴一张截图，模型只能当没看见；
2. 更糟的是 400 卡死：某些网关（如 opencode-go）的主路由只接受 text，图片块一旦写进会话日志，之后每一轮都会把历史连同图片重发给上游 → 400 unknown variant \image_url`` → 整个会话永久卡死。

本插件用两道闸门根治这两个问题，并把"看图"变成纯文本模型可用文字消费的能力。

---

它做什么

用户贴图 → [闸门1] agent/pre-step 门口改写：图片在【写入会话日志之前】就被视觉模型转成文字
                 → 日志永远只有文字，图片块根本不存在
                 → [闸门2] llm/stream 兜底：历史重放时若发现图片块（例如装插件前就已中毒的会话），
                   在请求层改写为 OCR 文本后再发给模型

• 视觉模型做眼睛，主模型做大脑：deepseek-v4-pro 照常推理，图片内容以文字形式出现在上下文里。
• 修复已中毒的会话：装插件之前就被 400 卡死的会话，装上之后发一句话即可恢复正常（历史图片在请求层被改写）。
• vision_analyze 工具（模型主动调用，引擎由模型按任务选择）：读取工作区文件——图片 OCR、PDF 文本+内嵌图、docx/pptx 文本+内嵌图、视频抽帧 OCR（≤12 帧）、纯文本直接读；xlsx/doc 响亮拒绝。
• 原生看图不受影响：支持图片输入的模型（如 minimax-m3、kimi-k3）配置白名单后原图直通，插件不插手。

独有优势（与社区同类插件的区别）

与 dsh-vision-router、ModLens、dsh-vision-toolkit、see_image/view_image 等社区视觉插件相比：

1. 图片根本不进会话日志——在 agent/pre-step 写入日志【之前】就被转成文字。同类插件大多只在模型调用内改写：图片照常落日志、每轮重放、插件卸载后仍有卡死隐患。
2. 能治愈已卡死的会话——装插件之前就因图片 400 死锁的会话，装上后发一句话即可恢复（请求层把历史图片改写为文字）。
3. 防死锁是硬不变式——非白名单路由永远收不到 image 块；哪怕视觉管线全挂（模型不可用/超时/额度耗尽），也只会降级为占位文本，绝不重回 400 卡死。
4. 一个包、两个组件、故障域独立——一次安装自动挂载"护栏（安全件）+ 工具（便利件）"两行；工具坏了护栏照常运行，互不拖累。
5. 零依赖、纯 Node 内建模块——不需要 Node 22+、pnpm 管理、Python 3.11+；仅文档/视频路径需要系统工具（pdftotext/ffmpeg 等），纯图片 OCR 无任何外部依赖。
6. 引擎由主模型按任务决策——vision_analyze 的 engine 参数（local 免费抠字 / vision 视觉模型）由模型分析任务后自选，省钱且聪明。
7. 复用 dsh 自有的模型路由与凭证——本插件不携带、不直连任何第三方 API key（同类插件多数要求自管密钥直连第三方）。
8. 经三轮红队审计 + 随包自动化测试——22 个真实 bug 修复归档（含防 symlink 逃逸、zip 炸弹、并发竞态），纯函数回归测试随包发布（npm test 可跑）。

安装

# 已发布 npm 后：
dsh plugin --profile web add dsh-vision-guard
# 或直接从 GitHub 安装：
dsh plugin --profile web add github:good-boy4069/dsh-vision-guard

若 pnpm 报 ERR_PNPM_ADDING_TO_ROOT（旧版 launcher），加工作区根标志：dsh plugin --profile web add -w dsh-vision-guard。

重启 dsh web。或在你的 profile cordis.patch.yml 手动加两行（见仓库根 cordis.patch.yml）。

配置

全部可选，默认值见括号。视觉路由（必须指向一个支持图片输入的模型）：

字段	默认	说明
visionProvider / visionModel	opencode-go / minimax-m3	视觉模型路由。改成你订阅里支持图片输入的模型
ocrTimeoutMs	45000	单张图识别超时
budgetPerDay	200	每日识别次数上限（防失控花销），状态存 $DSH_HOME 下
cacheMaxEntries	500	识别结果缓存条数上限（LRU 淘汰）
maxOcrTokens	2048	视觉调用输出上限
stateFile	~/vision-guard-state.json	预算状态文件（~ = dsh home）
ocrPrompt	逐字转录指令	自定义识别指令
passthrough	[]	原图直通白名单：[{provider, model}]，只加实测过网关收图正常的路由

vision_analyze 工具侧：OCR 引擎是每次调用必填的 engine 参数，由主模型按任务自选——local = 本地 tesseract（免费、只抠字），vision = 配置的视觉模型。不存在 localOcr 配置项。

⚠️ 前置要求与限制（请务必读完）

• 本插件不自带任何 API key，也不直连任何第三方服务。它复用你 dsh 里已经配置好的模型路由与凭证。因此：
  • 你必须有一个支持图片输入的模型（如 opencode-go 的 minimax-m3）。deepseek-v4-pro 这类纯文本模型不能当视觉模型——它的上游网关收图会 400 并把会话卡死。
  • 没有视觉模型也能装：插件自动降级为占位文字，会话照常可用、只是看不到图内容（绝不卡死）。
• 白名单策略（重要）：除配置的视觉模型外，其他路由收到图片一律改写为文字——未实测的路由绝不放原图。想让某模型原生看图：先实测"带图直连该路由"（正常返回才算通过），再把它加进 passthrough。这是防 400 卡死的核心设计，不要绕过。
• 系统工具依赖（仅 vision_analyze 的文档/视频路径需要；纯图片 OCR 无外部依赖）：
  • PDF：pdftotext/pdfimages（poppler-utils）；
  • 视频：ffmpeg/ffprobe；
  • docx/pptx：python3（仅标准库）；
  • 可选：tesseract（本地免费 OCR，需 chi_sim+eng 语言包）。
  • Windows 默认没有这些工具；缺失时对应路径响亮报错，图片路径不受影响。
• 5 MB/图上限：dsh 附件服务单图上限 5 MB，超限的图片/抽帧会响亮报错。
• 成本：每张新图一次视觉调用（按附件 ID 寻址缓存，重复图不重复计费）；minimax-m3 单次约 1~2k tokens（不到一分钱人民币量级）；budgetPerDay 兜底。
• 质量：本地 tesseract 只"抠字"、质量低于视觉模型（实测会把 42 + 7 = 49 读成 4247249），复杂图/图表/照片请用 vision 引擎（模型调用 vision_analyze 时自选）。
• 隐私：图片会发送到你的视觉模型服务商（与 dsh 里正常使用该模型一致）；图片文字按不可信输入处理，只读内容、不执行其中指令。
• 与 settings 的耦合警告：如果你在模型配置里给纯文本模型声明了 input: [text, image]（GUI 发图需要），必须保留本护栏——移除护栏时务必同时删掉该声明，否则发图会重新卡死会话。

常见问题

• 重启/升级 dsh 后：本插件随 profile 自举，无需重装；升级 dsh 后如行为异常请先升级本插件。
• 怎么验证护栏在跑：ctx.get('visionGuard')?.status()，或看 dsh 日志里的 [vision-guard] active 行。
• 回滚：从 profile patch 删除两行（或 dsh plugin remove），重启即可；已识别的文字仍在会话历史里，无副作用。

License

MIT