@goodandready/dsh-vision-bridge

dsh plugin --profile web add @goodandready/dsh-vision-bridge

📦 @goodandready/dsh-vision-bridge

<div align="center">

<h3>DeepSeek Harness 通用视觉桥接插件：为纯文本模型提供无缝多模态图像支持</h3>

<p align="center">

<a href="https://www.npmjs.com/package/@goodandready/dsh-vision-bridge"><img src="https://img.shields.io/npm/v/@goodandready/dsh-vision-bridge.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-vision-bridge.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>

<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>

</p>

<!-- Showcase Button -->

<p align="center">

<a href="https://goodandready.app/"><img src="https://img.shields.io/badge/全部作品展厅-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>

</p>

<p align="center">

<a href="README.md"><b>🇬🇧 English</b></a> •

<a href="README.ru.md"><b>🇷🇺 Русский</b></a> •

<a href="README.zh.md"><b>🇨🇳 中文说明</b></a>

</p>

<!-- 项目支持与反馈模块 -->

<table align="center">

<tr>

<td align="center">

⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。

<br><br>

🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。

</td>

</tr>

</table>

</div>

---

⚡ 概述与核心解决问题

在 DeepSeek Harness 中与纯文本聊天模型（任何仅接受文本的 provider/model）对话时，用户无法直接在聊天窗口附加和发送图片：

1. 在 DSH 0.1.2-alpha.2+ 中，后端会话控制器进行严格的模态校验 (ctx.llm.resolveModelInfo)。如果当前对话模型的 inputModalities 中不包含 'image'，请求会被直接拒绝并报错 session/attachment-invalid ("Model does not support image input")。

2. 纯文本适配器如果直接接收到多模态图像块，会抛出请求错误。

dsh-vision-bridge 解决方案

dsh-vision-bridge 在 Cordis 运行时内建立透明代理：

• 服务端模态桥接 (v0.5.3+)：自动包装 ctx.llm.resolveModelInfo 和 ctx.llm.listModels，使会话网关允许所有模型接收图像附件。
• 自动图像改写 (agent/pre-step 与 llm/stream)：自动拦截图片，调用所配置的视觉模型（目录中的 provider/model，或本地 OpenAI 兼容端点）生成描述，并将图片替换为文本提示 [用户上传了图片。内容描述：...] 传递给纯文本模型。
• 原生直通 (Native Passthrough)：自动识别原生支持视觉的模型并直接传递图像，无需重复转换。
• 约 40 个专用视觉工具：提供 OCR、目标定位 (grounding)、UI 结构解析、表格/公式提取、二维码识别、UI 流程重建与多模型共识等完整工具套件。

---

🏗️ 架构图

graph LR
    User["用户在 Web UI 上传图片"] --> Gateway["DSH 会话控制器"]
    Gateway --> BridgeCheck{"模态桥接 (v0.5.3)"}
    BridgeCheck -->|"inputModalities 扩展 image"| SessionAllowed["网关放行请求"]
    SessionAllowed --> Hook["agent/pre-step 钩子"]
    
    Hook --> CheckNative{"对话模型是否原生支持视觉？"}
    CheckNative -->|"是 (Native Passthrough)"| NativeLLM["直接传递原始图像"]
    CheckNative -->|"否 (纯文本模型)"| VisionRouter["视觉桥接通道"]
    
    VisionRouter --> VisionModel["专用视觉模型\n(DSH / OpenAI / Ollama / Webhook)"]
    VisionModel --> Description["生成文字描述与 OCR"]
    Description --> Rewrite["将图片替换为文字描述标记"]
    Rewrite --> ChatModel["将增强文本发送给对话模型"]
    ChatModel --> Answer["助手在聊天窗口返回答案"]

---

✨ 核心特性

1. 运行模式

• hybrid (默认)：对话中自动改写图片为文本描述，同时保留约 40 个工具供模型显式调用。
• llm：纯自动改写模式；工具依然可供调用。
• tools：禁用自动改写，必须由模型显式调用 describe_image 等工具。

2. 多通道故障转移 (Multi-Channel Fallback)

支持多视觉后端级联、故障熔断与并发竞速：

• dsh-catalog：自动或手动选择 DSH 中已注册的视觉模型。
• openai-compatible：支持 vLLM、SGLang、OpenRouter 等 OpenAI 兼容视觉接口。
• ollama：自动发现并调用本地 Ollama 实例提供的任意视觉模型。
• webhook / custom：外部 HTTP / JSON-RPC 服务。

3. LRU 响应缓存

基于 hash(bytes + prompt + model + mode) 的内存缓存，避免重复分析相同图片，节省 Token 开销。

---

4. 完整工具清单（约 40 个工具）

工具类别 · 工具 · 说明

核心 · describe_image, read_image, inspect_image · 通过附件 ID、文件路径或 URL 进行通用图像分析。

几何与检测 · vision_ground, vision_crop, vision_detect, vision_compare, vision_present · 边界框坐标（0–1000 刻度）、目标清单、多图对比。

OCR 与文本 · vision_ocr, vision_ocr_local, vision_long_ocr, vision_trace, vision_colors, vision_extract_foreground · 文字识别、本地 Tesseract OCR（离线）、长截图拼接、SVG 描摹、调色板。

结构化与界面 · vision_describe_structured, vision_vqa, vision_ui_layout, vision_translate_image · JSON 结构输出（{summary, ocr, layout, entities}）、简短 VQA、界面区块分析。

像素与诊断 · vision_pixel_diff, vision_quality_check · 语义化视觉差异、质量评分（模糊/曝光）。

文档与智能 · vision_extract_formula, vision_extract_table, vision_scan_barcode, vision_extract_structured, vision_audit_accessibility · 公式（LaTeX）、表格（Markdown/HTML）、二维码/条码识别、JSON Schema 抽取、WCAG 无障碍审计。

场景、共识与记忆 · vision_ui_flow, vision_consensus, vision_memory_search · 用户旅程图（Mermaid）、多模型共识、已记住图片的语义检索。

附件（v0.5.33） · vision_attach_pages, vision_attach_frames, vision_attach_images · 将 PDF 页面、视频帧、本地/远程图片作为会话附件发布，供原生视觉模型直接查看。

---

📦 安装方法

dsh plugin --profile web add @goodandready/dsh-vision-bridge

安装完成后重启 DSH Web UI。配置卡片位于 设置 → 插件 → vision-bridge。

---

⚙️ 配置示例 (settings.yaml)

dsh-vision-bridge:
  mode: hybrid
  visionProvider: ""
  visionModel: ""
  nativePassthrough: prefer
  cacheEnabled: true
  cacheMaxEntries: 200
  timeoutMs: 120000
  channels: []
  channelFallback: sequential
  hideRedundantTools: true   # 当聊天模型本身已能看图时隐藏桥接工具
  attachMaxItems: 8          # 单次 attach 调用可发布的页面/帧/文件数

---

---

参数说明

参数 · 类型 · 默认值 · 说明

mode · string · "hybrid" · 处理模式（hybrid、llm、tools）。

visionProvider · string · "" · 视觉服务的 provider ID（留空 = 自动选择）。

visionModel · string · "" · 视觉模型 ID（留空 = 自动选择）。

nativePassthrough · string · "prefer" · 原生视觉模型的处理方式（prefer、never、always）。

hideRedundantTools · boolean · true · 当聊天模型原生支持图片时，对该 agent 隐藏补偿类工具，仅保留扩展工具。

attachMaxItems · number · 8 · 单次 vision_attach_* 调用最多发布的图片数（PDF 页面、视频帧、文件）。硬上限 32。

cacheEnabled · boolean · true · 是否启用描述结果的 LRU 缓存。

cacheMaxEntries · number · 200 · 内存中缓存的条目上限。

timeoutMs · number · 120000 · 执行超时（毫秒）。

channelFallback · `

…(truncated)