dsh-vision-bridge

一个 DeepSeek Harness 插件：让纯文本模型也能接收并理解图片，视觉工作由本机模型完成。

    

English · 简体中文

---

这是什么？

DeepSeek Harness（dsh）是一个开源的 AI 编程环境，所有组件都是插件。它的对话模型——deepseek-v4-flash 和 deepseek-v4-pro——是纯文本模型：API 不接受图片数据。所以在 Harness 里，你没法给它们粘贴截图、在消息里附图片，也不能用自带的 read_image 工具。

这个插件解决这件事，分三层：

1. 一条接受图片的模型路由。 同一个 DeepSeek 模型以"孪生"provider（deepseek-vision）再注册一份，并声明支持图片。于是正常的图片功能都能用：粘贴出现缩略图和图片块，read_image 也放行。在请求真正发给 DeepSeek API 之前，插件会把对话里的每张图片先交给本机视觉模型，转成文字描述。API 永远只收到文本；模型回答起来就像真的看过图。 2. 九个检查工具。 describe_image、extract_text、structured_scan、query_region、detect_elements、locate_object、compare_images、read_clipboard、check_health——模型可以按不同粒度查看图片：从整体描述到每个元素的具体坐标；你也可以在对话里直接使用。 3. 粘贴分流。 粘贴图片时，浏览器端的一个小组件会先问服务器：当前模型能不能处理图片？能（孪生路由）就保留为正常图片；不能（官方纯文本路由）就把图片存成本地私有文件，把路径作为文本插入，供检查工具读取。

视觉模型（Ollama + qwen2.5vl）跑在你自己机器上。图片字节不会发给 DeepSeek API，也不会发给任何云端视觉服务。

如果你只用官方路由，这个插件依然有用：粘贴的图片会变成本地路径，检查工具可以读取。如果你只需要工具，也可以完全忽略孪生路由。

目录

• [这是什么](#这是什么)
• [解决的问题](#解决的问题)
• [解决方案](#解决方案)
• [功能特性](#功能特性)
• [系统架构](#系统架构)
• [交互逻辑](#交互逻辑)
• [安装](#安装)
• [使用](#使用)
• [配置](#配置)
• [视觉工具](#视觉工具)
• [项目结构](#项目结构)
• [安全与隐私](#安全与隐私)
• [环境要求](#环境要求)
• [故障排查](#故障排查)
• [许可证](#许可证)

---

解决的问题

DeepSeek 旗舰对话模型（deepseek-v4-flash、deepseek-v4-pro）是纯文本模型：API 端点无法接收 图片字节，模型元数据也声明 inputModalities: ['text']。DeepSeek Harness 在三个硬关卡上依赖这份元数据：

市面上的变通方案要么fork preset（脆弱）、要么依赖云端视觉 key（Gemini 等）、要么迫使你 为整个会话切换成更弱的视觉模型——丢掉 DeepSeek 的编码能力。没有一种真正满足需求： DeepSeek 主脑 + 原生图片体验 + 看得见。

解决方案

一个自包含插件，三层协同：

1. 视觉孪生路由（deepseek-vision）——同一批 DeepSeek 模型以 inputModalities: ['text','image'] 重新注册。所有原生关卡随之打开：粘贴准入、缩略图、持久图片块、read_image。底层，孪生 在请求层拦截图片块，交给本地视觉桥分析，只把文本转发给 DeepSeek API。 2. 智能体视觉工具——九个原生工具（describe_image、structured_scan、query_region …）， 由本地 Ollama 视觉模型驱动：结构化输出、校验+重试、内容寻址缓存。 3. 粘贴分流器——浏览器半部向宿主请求判定，依据真实模型元数据：视觉能力路由保留原生 照片流；纯文本路由回退到本地路径，由桥工具接管。

功能特性

• 纯文本模型的原生图片体验——粘贴截图 → 缩略图、图片块、真正"看见"的 DeepSeek，全程没有

一个图片字节到达 API。

• 不需要任何云端 key——视觉引擎是本地 Ollama（qwen2.5vl）；孪生复用你已有的 DEEPSEEK_API_KEY

凭据，解析逻辑与官方路由完全同源。

• 请求层透明——无提示词 hack、无 preset fork、无可能竞态的动态注入；拦截发生在适配器内，

每个请求恰好一次。

• 带坐标的结构化输出——元素边界框（[0,1000] 归一化）、区域真裁剪、两级定位、双图对比、

剪贴板读取、schema 校验输出 + 格式错误自动重试。

• 重复图片自动缓存——重复图片命中内容哈希缓存：零额外推理，前缀缓存行为稳定。
• 自包含、可分发——单个 29KB tarball，无任何本机路径依赖；任何机器 dsh plugin --profile web add 即装。
• 与官方路由共存——官方 provider 原样保留作兜底；粘贴判定按会话、按实时元数据决定走哪条流。

系统架构

┌──────────────────────────── 浏览器 · client.js ────────────────────────────┐
│ 粘贴 / 拖拽图片                                                            │
│   → 捕获阶段监听（先于 composer 自身处理器）                                │
│   → GET /vision-bridge/paste?model=<选择器标签>   （宿主判定）              │
│        ├─ takeover:true   （确认纯文本路由）                                │
│        │    → POST 字节 → 宿主存私有临时文件 → 路径文本                      │
│        │      插入输入框；桥工具接管                                        │
│        └─ takeover:false  （图片能力路由）                                  │
│             → 原生粘贴：图片块 + 缩略图，原样保留                           │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      ▼
┌──────────────────────── 宿主插件 · lib/index.js ───────────────────────────┐
│  · POST /vision-bridge/paste → 魔数嗅探 → 0600 临时文件 → {path}           │
│  · 9 个工具注册进 ctx.tools（原生编目，无 mcp__ 前缀）                      │
│  · registerAdapter('deepseek-vision', VisionDeepSeekAdapter)               │
└──────────────┬───────────────────────────────────────────┬─────────────────┘
               ▼                                           ▼
     ┌────────────────────┐                  ┌──────────────────────────────┐
     │ vision-core         │                  │ VisionDeepSeekAdapter（孪生） │
     │ · 预处理/校验        │                  │ · listModels/resolveModel：  │
     │ · 串行队列           │                  │   图片能力元数据              │
     │ · LRU 缓存          │                  │ · stream()：图片块 ──►        │
     │ · 9 个工具处理器     │                  │   桥分析文本 ──►              │
     │                     │                  │   DeepSeek API（纯文本）      │
     └──────────┬──────────┘                  └───────────────┬──────────────┘
                ▼                                              ▼
        Ollama · qwen2.5vl                        DeepSeek API · 与官方同端点、
        本地 · 私有 · 免费                         同凭据

lib/core/ 是与作者 MCP 视觉桥共享的宿主无关视觉核心（scripts/sync-core.mjs 可重新同步—— 单一事实源，两种交付形态）。

交互逻辑

1. 粘贴分流（每次粘贴，按实时模型元数据判定）

客户端按选择器标签缓存判定（60 秒 TTL）并在聚焦时刷新，会话的第一次粘贴就已正确。元数据未知 时绝不劫持粘贴——原生路径是安全默认。

2. 请求层拦截（仅视觉孪生）

用户粘贴图片 ──► 会话历史中的持久图片块
        │
        ▼
下一次模型请求 ──► VisionDeepSeekAdapter.stream()
        │
        ▼
sanitize()：对每个图片块 ──► attachments.readImage(字节)
        │                                 │
        │                                 ▼
        │               内容寻址落盘
        │               (~/.dsh/vision-bridge/images/<sha1>.png)
        │                                 │
        │                                 ▼
        │               vision-core.describe_image(路径)   ← 缓存命中 ⇒ 零推理
        │                                 │
        │                                 ▼
        │               文本：[图片（视觉桥分析）] … + 本地路径
        │
        ▼
纯文本请求 ──► DeepSeek API（与官方路由同端点、同凭据）
        │
        ▼
DeepSeek 基于视觉分析回答；也可对嵌入路径继续调用 query_region / extract_text
做更深、坐标级精确的检查。

3. 工具链（证据工作流）

structured_scan ──► 带 bbox 的元素清单（heading/table/chart/button/…）
        │
        ├──► query_region(bbox) ──► 区域被真正裁剪后单独分析
        ├──► extract_text(with_coordinates) ──► 带归一化坐标的 OCR 块
        └──► locate_object(描述) ──► 粗定位 → ×1.3 裁剪 → 精定位 → 全图 bbox

安装

# 1. 前置：Ollama 运行中且有视觉模型（如 qwen2.5vl:7b）；
#    孪生路由需要 DEEPSEEK_API_KEY。

# 2. 安装插件（任选一种形式）
dsh plugin --profile web add .\dsh-external-dsh-vision-bridge-2.0.0.tgz   # tarball
#   dsh plugin --profile web add <包目录>                                # 本地 checkout
#   dsh plugin --profile web add @yulee-314/dsh-vision-bridge            # npm

# 3. 重启 dsh web（bundle 层在启动时加载）

使用

1. 任意会话中打开模型选择器： - DeepSeek (视觉桥) → DeepSeek-V4-Flash (视觉桥) —— 推荐：编码 + 原生图片体验，视觉由桥供给。 - 官方 DeepSeek 路由 —— 粘贴回退为路径文本；桥工具照常可用。 2. 粘贴或拖拽图片。孪生路由出现缩略图；官方路由插入路径。 3. 正常提问即可。DeepSeek 基于桥的分析回答；需要坐标级细节时用 query_region / extract_text。

让孪生成为每个新会话的默认：

# ~/.dsh/settings.yaml
agent-default-model:
  provider: deepseek-vision
  model: deepseek-v4-flash-vision
  reasoningEffort: max

配置

若某部署不需要粘贴分流，可在 bundle 行配置 pasteToPath: false 关闭。

视觉工具

项目结构

dsh-vision-bridge/
├── package.json              # dsh.bundle + dsh.client 双清单，自包含依赖
├── cordis.patch.yml          # loader 行（bundle 层）
├── client.js                 # 浏览器半部：粘贴拦截 + verdict 协议
├── README.md / README.zh-CN.md
├── scripts/sync-core.mjs     # 从 MCP 视觉桥重新同步 lib/core
└── lib/
    ├── index.js              # 宿主插件：工具、粘贴路由、适配器注册
    ├── deepseek-vision.mjs   # 视觉孪生路由（继承官方 DeepSeek 适配器）
    └── core/                 # 宿主无关视觉核心（内嵌、自包含）
        ├── vision-core.mjs   #   工具 + prompt + 重试/校验编排
        ├── image.js          #   预处理、裁剪、data URL
        ├── validate.js       #   schema 校验 + 重试提示
        ├── cache.js          #   内容哈希 LRU
        ├── queue.js          #   串行推理队列
        ├── errors.js         #   错误分类（ollama_down / model_not_found / …）
        ├── grounding.js      #   两级定位换算
        ├── compare.js        #   并排对比图合成
        └── clipboard.js      #   Windows 剪贴板读取

安全与隐私

• 图片永不出机器。 视觉引擎是本机 Ollama；孪生路由只把桥的文本分析发给 DeepSeek API。
• 粘贴字节经魔数校验（PNG/JPEG/WebP/GIF）、大小上限（25MB）、以 0600 存入全新不可预测的临时目录。
• 孪生复用官方路由的凭据解析——无第二把 key、无明文配置。
• 粘贴劫持严格基于证据：没有纯文本的正面确认，原生路径绝不动。

环境要求

故障排查

许可证

MIT。视觉核心源自作者自研的 MCP 视觉桥项目。