# dsh-vision-router

> 为纯文本 DeepSeek Harness Agent 增加视觉能力：内置免 Key 免费视觉链 + 14 个像素级工具，发图即用，无需 Python。

## 元数据

- 作者: [@ysr666](https://github.com/ysr666)
- 仓库: <https://github.com/ysr666/dsh-vision-router.git>
- GitHub: [ysr666/dsh-vision-router](https://github.com/ysr666/dsh-vision-router)
- Star: 621
- 主语言: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- 主页: <https://github.com/ysr666/dsh-vision-router>
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `multimodal`, `vision`
- Fork: 25
- Open Issues: 3
- 最后推送: 2026-08-17T16:46:36.000Z
- 加入目录: 2026-08-14T00:00:00.000Z

## 安装

```bash
dsh plugin --profile web add github:ysr666/dsh-vision-router
```

## 百科

## 一句话定位
dsh-vision-router 是 DeepSeek Harness 的视觉增强插件：让原本只能聊文字的 Agent 直接"看见"图片——发图后 Agent 像调用普通工具一样调用 14 个视觉工具（定位、裁剪、像素对比、OCR、矢量化、抠图、HTML 截图等），同时内置免注册、免 Key 的匿名视觉链兜底，整套链路不依赖 Python。

## 核心能力
- 让图片轮像普通文本轮一样工作：用户粘贴图片，Agent 通过 vision_describe 看图作答，并可连续多步操作（ground → crop → describe → pixel_diff）
- 自动把已有模型组镜像成「+ 自动识图」入口，原模型组保持不变，新模型/包装范围变更后热更新
- 内置 OVHcloud 匿名免费视觉链兜底（5 个 Qwen/Mistral 模型），不填任何 Key 也能用
- 提供像素级视觉工具：定位、裁剪、逐像素对比（差异率 + 红色热力图）、取色、SVG 矢量化、纯色背景抠图
- 视觉答案按附件内容哈希缓存，后续文字轮用记录描述替换历史图片，DeepSeek "记得"之前发过的图而不重复消耗视觉调用
- 自动故障降级链：地区限制/风控/额度/限流/上下文超长/网络故障，逐供应商尝试，429 触发熔断冷却

## 技术实现
- **语言**: JavaScript (ESM) / CommonJS 客户端产物
- **关键依赖**: sharp（图像处理）、potrace（位图矢量化）、puppeteer-core + 系统 Chrome（HTML 截图）、undici（HTTP 调用）、@deepseek-ai/schemastery（配置 Schema）
- **架构模式**: Cordis 插件 + bundle patch 自挂载，注入 `tools`、`llm`；entry.js 标准化 progressiveTools 默认值后调用核心 apply；客户端走 `dsh.client` 注入到 `dsh-client-ui-settings`/`dsh-client-runtime`/`dsh-client-connection`/`dsh-api-remotes`
- **入口文件**: entry.js → index.js（核心 7222 行），客户端 bundle 入口 lib/client.js；同时暴露 `dsh-vision-router` CLI（lib/doctor-cli.js）用于诊断/修复

## 适用场景
适合在 DSH Web 里发图给 DeepSeek 风格 Agent 的用户：粘截图让它看 UI 错误、贴参考图让它复刻页面、贴产品图让它描述差异、贴长聊天截图让它转写。需要 UI 还原的可验证闭环（设计稿 → HTML → vision_pixel_diff 量化差异 → 修复 → 再比），或希望用本地 Ollama/LM Studio 离线识别敏感图片的用户都能直接受益。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | >= 0.1.0-rc.6 | peer 依赖声明 `@deepseek-ai/dsh-anonymous-user-id` 与 `@deepseek-ai/dsh-llm-deepseek` ^0.1.0-rc.6；安装时需 `--profile web` |
| Node.js | >= 22 | engines.node 声明 |
| sharp | >= 0.35.3 < 1 | peer 依赖；pnpm onlyBuiltDependencies 允许原生编译；profile 内残留 0.34.0 会与宿主 0.35.3 冲突（DLL 报错） |
| 系统工具 | 视工具而定 | `vision_html_screenshot` 需要 Chrome/Chromium/Edge；`vision_screenshot`（macOS/Windows 用系统截屏，Linux 需 ImageMagick `import` 或 `scrot`）；`vision_ocr` 本地 tesseract 缺失时自动回退视觉模型 |
| 平台 | macOS / Windows / Linux | 核心工具跨平台；桌面截屏工具按平台有差异 |

## 安装方式
```bash
dsh plugin --profile web add github:ysr666/dsh-vision-router
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| providers | 数组 | 多供应商视觉后端链，按序尝试；新装用户默认含一条内置免费 `vision-http` | `[{"provider":"vision-http","model":"ovh/Qwen3.5-397B-A17B"}]` |
| httpProviders | 数组 | OpenAI 兼容直连端点（智谱/阿里百炼/Groq/OpenRouter 等），优先于内置免费链 | `[]` |
| autoWrapProviders | 布尔 | 自动把已启用模型镜像成「+ 自动识图」组，模型目录变化热更新 | `true` |
| wrappedProviders | 数组 | 手动包装范围（关闭自动包装或限定部分模型时使用） | `[{provider:"deepseek-official",models:[]}]` |
| routing | 布尔 | 旧版整轮链路由（一次性整轮切视觉模型）；关闭走工具优先流程（推荐） | `false` |
| stealth | 布尔 | 接管官方 `deepseek-official` 路由（仅官方行；自定义路由由自动包装处理） | `false` |
| progressiveTools | 布尔 | 渐进式工具挂载（首次需要时再展开完整 14 个工具）；默认关闭以稳定长会话 prefix/KV 缓存 | `false` |
| structuredVisionBootstrap | 布尔 | 1+x 结构化预识别（先建立任务无关证据底图再进行后续视觉调用） | `false` |
| desktopScreenshot | 布尔 | 暴露 vision_screenshot 桌面截屏工具的隐私开关 | `false` |
| freeFallback | 布尔 | 在显式本地/自定义 HTTP 后端之后追加匿名 OVH 免费链 | `true` |
| localOllama | 对象 | 本地 Ollama 视觉后端（启/关、地址、模型名、OpenAI/Anthropic 协议、可选 temperature/top_p） | `{enabled:false,baseURL:"http://127.0.0.1:11434/v1",model:"qwen2.5vl",format:"openai"}` |
| localLmStudio | 对象 | 本地 LM Studio 视觉后端（同 Ollama；model 必须填 Developer 页或 /v1/models 返回的真实标识） | `{enabled:false,baseURL:"http://localhost:1234/v1",model:"",format:"openai"}` |
| instantDescribe | 布尔 | 图片轮第一模型步之前用本地后端识别无缓存图片（Ollama→LM Studio，失败回退静态工具标记） | `false` |
| downscale / downscaleMaxPixels | 布尔 / 数字 | 调用前自动压缩超大图（延迟保护） | `true` / `4000000` |
| cache / cacheTtlSeconds / cacheMaxEntries | 布尔 / 数字 | 视觉答案缓存 | `true` / `3600` / `200` |
| timeoutMs | 数字 | 单次视觉调用超时 | `120000` |
| proxy / proxyHosts | 字符串 / 数组 | 仅视觉供应商域名走本地代理（DeepSeek 保持直连） | `""` / openrouter 等 9 个默认域名 |
| artifactsDir | 字符串 | 产物目录（相对会话工作区） | `.dsh-vision-router/artifacts` |

## 常见问题

**Q: 安装后需要额外配置吗？**

A: 不需要。插件自带 bundle 补丁并默认开启内置 OVH 匿名免费视觉链；装完只需在聊天页右下角切换到带「+ 自动识图」的模型组即可发图。

**Q: 不开 API Key 能用吗？**

A: 可以。默认链内置 5 个 OVHcloud 匿名视觉模型，免注册免 Key，每 IP 每模型 2 次/分钟。额度不够时可在设置卡里加一条带 Key 的 `httpProviders`（智谱 glm-4v-flash 等）即可。

**Q: 为什么聊天页说"当前模型不支持图片"？**

A: 插件不修改原模型组。需要在聊天页右下角的模型选择器里切换到带「+ 自动识图」的组才能发图；选择原纯文本组发图会被宿主直接拦截。

**Q: 支持哪些平台？**

A: 跨平台运行。vision_screenshot 在 macOS/Windows 使用系统截屏能力，Linux 需要安装 ImageMagick 的 `import` 或 `scrot`；vision_html_screenshot 需要 Chrome/Chromium/Edge；其他工具无浏览器也能用。

**Q: 视觉工具有哪些？**

A: 共 13-14 个默认挂载：vision_describe（看图问答）、vision_ground（像素定位）、vision_detect（元素清单）、vision_crop（裁剪）、vision_pixel_diff（像素对比 + 热力图）、vision_colors（取色）、vision_ocr（文字转写）、vision_trace（SVG 矢量化）、vision_extract_foreground（抠图）、vision_present（持久展示图片）、vision_materialize（附件落盘）、vision_html_screenshot（HTML 截图）、vision_long_screenshot_ocr（长截图转写），加上 vision_bootstrap 结构化预识别；隐私敏感的 vision_screenshot 默认关闭，开启后为第 14 个。

**Q: 能否纯本地离线识别？**

A: 能。开启 `localOllama.enabled` 或 `localLmStudio.enabled` 后，本地后端排在 HTTP 视觉链最前，不通则自动降级；配合 `instantDescribe: true` 可在第一模型步之前完成本地识别。

**Q: 升级后 DSH 启动报"duplicate loader entry id: vision-router"？**

A: profile 目录的 `cordis.patch.yml` 里残留了 v0.x 时代的手动插入块，与插件自带的 bundle 补丁重复。删除整块 `insert:` 段，或改写为按 id 覆盖行后重启即可。

**Q: 如何卸载？**

A: 执行 `dsh plugin --profile web remove github:ysr666/dsh-vision-router`，包装路由、工具、技能与设置卡片会被一并移除，已生成的产物文件保留。

## 上手难度
入门 — 默认配置即可发图工作，零配置起步；进阶用户可通过设置卡或 profile 补丁调整视觉后端链、本地后端、缓存、代理等参数。

## 已知问题与限制
- DSH profile 目录的 `package.json` 若被某些编辑器保存为 UTF-8 with BOM，启动时 `dsh web` 会报 `Unexpected token ... is not valid JSON`；可用插件自带的 `npx dsh-vision-router repair --profile web` 去掉 BOM
- 旧版 profile 内残留 sharp 0.34.0 与宿主 0.35.3 同进程 DLL 冲突（issue #42/#75），像素工具报 `colourspace: parameter space not set`；v1.2.2+ 会在检测到残留时主动告警
- Oh-DSH Desktop ≤ 0.1.5 内置 DSH 0.1.0-rc.5，v1.4.1 及更早版本会让该运行时启动崩溃（报 `configurable provider "deepseek-official" is already declared`）；需安装 v1.4.2+
- 同时安装 `dsh-web-ui` / `dsh-web-ui-all` 时，其 `dsh-tool-describe-image` 发送钩子可能先于本插件改写图片块；需在「图像理解」设置里关闭"发送时改写图片为 describe-image 引用"
- pnpm v11 会静默拦下发布不足 24 小时的新版本，导致 `update` 报 `downloaded 0` / `added 0`；需显式 `add dsh-vision-router@<版本号>` 或跑 `npx dsh-vision-router repair`
- vision_html_screenshot 依赖系统安装的 Chrome/Chromium/Edge，未检测到时该工具直接报错而不自动安装
- vision_ocr 本地引擎（tesseract）缺失时静默回退到视觉模型，OCR 速度与额度按视觉模型计
- vision_screenshot 默认关闭，开启后 macOS/Windows 走系统截屏能力；Linux 需安装 ImageMagick `import` 或 `scrot` 且必须处于可截取桌面会话（Wayland 支持取决于环境）

---

本文档由 [deepseek-plugin.org](https://deepseek-plugin.org) 自动生成，对应 HTML 页面: [dsh-vision-router](https://deepseek-plugin.org/plugins/ysr666/dsh-vision-router)
百度百科由 AI 生成 (模型: `MiniMax-M3`)