dsh-vision-router 图片轮为什么"就是普通工具调用":轮级视觉路由原理深度解析
dsh-vision-router 图片轮为什么"就是普通工具调用":轮级视觉路由原理深度解析
dsh-vision-router 是给 DeepSeek Harness 纯文本 Agent 装上"眼睛"的视觉路由插件:当你粘贴图片时,它通过轮级视觉路由把"看图"改写成一次普通工具调用,让 DeepSeek 只负责思考、视觉模型只负责看像素,图片轮因此可定位、可迭代、可验证,且默认免 Key 免费、一键安装、无需 Python。
很多新手装过各种视觉插件后都有同一个疑惑:为什么有的插件"看一眼"就结束,而 dsh-vision-router 里粘贴图片后的那一轮,看起来和 Agent 调用任何工具(读文件、跑命令)一样自然?答案就藏在它的轮级视觉路由设计里。这篇文章从原理角度把它拆清楚。
一、先搞清楚两种"给 Agent 看图"的思路
市面上 DSH 视觉插件大致分三类:
| 思路 | 做法 | 代价 |
|---|---|---|
| 描述桥 | 图片先经外部 VLM 转成一段文字描述,再喂给 DeepSeek | 有损、一次性,看不见像素 |
| 转译桥 | 包装 provider,请求流里把图片转译成文本 | 整条路由被劫持,日常模型受影响 |
| 路由桥(本插件) | 图片轮直接交给视觉模型看图像像素 | 像素级,可连续多步迭代 |
dsh-vision-router 属于第三种:它不重写你的模型,也不把图片"翻译"成文字,而是把图片轮变成一次指向视觉工具的调用。
二、核心机制:图片轮 = 调用工具的文本轮
这是理解整套路由的关键一句话(来自项目 README.zh.md):
可连续多步看图。图片轮 = 调用工具的文本轮:
vision_ground→vision_crop→vision_describe→vision_pixel_diff→ 修复 → 再截图,Agent 可以一直迭代到任务完成。
具体分三层看:
1. 请求层:agent/request 瀑布改写路由
插件不包装 provider,而是通过 agent/request 瀑布在模型输入层改写指向视觉工具的请求(见 README.zh.md 同类插件对比)。改写只发生在模型看到的输入上——rewriteImages 把模型输入层里的图片块换成"缓存描述或工具提示标记",而会话界面里图片照常显示为图片,从不写入会话日志(README.zh.md)。
2. 执行层:视觉工具就是工具
改写之后,DeepSeek 看到的就是一个普通工具提示:"这里有一张图,可用 vision_describe / vision_ground 等工具查看"。于是 Agent 像调用任何其他工具一样发起调用,比如:
vision_ground image="ref.png" target="发送按钮"
vision_pixel_diff original="ref.png" rebuilt="screenshot.png"
每个工具返回文本结果(坐标、差异率、转写内容),文字轮在模型、成本、上下文上完全不动——DeepSeek 始终是大脑,视觉模型只当"眼睛"、按需调用(README.zh.md)。
3. 证据层:答案按图片内容缓存
同一个问题对同一张图重复问,命中缓存直接返回,不重复烧视觉额度。这让"工具调用轮"在多轮对话里足够便宜,也解释了为什么它敢让 Agent"一直迭代到任务完成"。
下面是实际会话中图片轮的完整过程:左边是用户粘贴图片并提问,中间是 Agent 发起 vision_describe 工具调用(Tool call 清晰可见,就像调用任何工具一样):
工具返回后,DeepSeek 基于视觉模型的像素级观察组织出结构化答案——画面主体、按钮、文字逐条列出:
三、路由决策:Authority → Evidence → Planner → Execution
"普通工具调用"听起来简单,背后其实是一套严格的轮级路由契约。官方文档 docs/v2-capability-routing.md 把路由拆成四个有序关注点:
权限(Authority)→ 证据(Evidence)→ 规划(Planner)→ 执行(Execution)
对应到源码就是这几个模块(都在 src/lib/ 下):
| 模块 | 职责 |
|---|---|
| src/lib/vision-routing-authority.ts | 路由授权:ordered/auto 模式、后台测量授权,Auto 绝不自我授权 |
| src/lib/vision-routing-evidence.js | 能力证据:只信"精确部署身份 + 当前测试套件"下测得的数据 |
| src/lib/vision-execution-order-plan.js | 规划器:按配置顺序为基线,Auto 只允许有≥0.08 实测优势的相邻重排 |
| src/lib/agent-request-route-authority.js | agent/request 完成的路由变更视为授权移交:源模型的生成默认值不得混入目标模型配置,证据不全就 fail-closed 不改写 |
几个值得新手记住的设计约束:
- 配置顺序永远兜底。规划失败、授权被撤回、计划过期,都自动回落到当前配置顺序(docs/v2-capability-routing.md)。
- Auto 只影响视觉工具。临时 Auto 顺序被隔离在单次视觉工具调用里,用完自动还原(
AsyncLocalStorage),不污染你的文字轮。 - 不靠名字猜能力。规划器不会从模型名、厂商口碑推断能力——没测过的路由就是"信息屏障",保持配置顺序穿过它。
四、供应商降级链:工具调用失败会自动换"眼睛"
普通工具调用最怕的是"调一次失败就报错"。图片轮的路由链(README.zh.md 供应商降级链)按顺序逐个尝试,全部失败才报错:
- 用户视觉模型(设置页从上到下一行一个)
- 本地 Ollama(可选,默认关)
- 本地 LM Studio(可选,默认关)
- 高级自定义 HTTP 视觉端点
- 内置 OVH 匿名免费兜底(5 个免 Key 模型,每 IP 每模型 2 次/分钟,理论合计约 10 次/分钟)
遇到 429 限流会立即切下一后端,并按 Retry-After 开启有上限的熔断冷却;超大上传图在调用前自动压缩(默认预算 400 万像素)。对 Agent 来说,它感受到的只是"这次工具调用可能多花了几秒",路由细节完全透明。
五、一个像素级闭环的实测:为什么工具调用要"可验证"
图片轮作为工具调用的最大好处是可验证——vision_pixel_diff 会给出逐像素差异率和最差网格区域,让 Agent 知道"改得对不对",而不是一句模糊的"看起来差不多":
图中展示了完整循环:vision_html_screenshot 截图 → vision_pixel_diff 对比 → 修复 → 再截图,直到差异收敛(32,939 / 1,296,000 个差异像素,threshold 16/channel)。这正是"图片轮 = 工具轮"的威力:工具返回结构化数字,Agent 就能基于数字继续迭代。
六、在哪里配置:视觉路由设置页
所有行为都可以按需调整,入口在 设置 → 插件 → 视觉路由(自动识图),相关配置客户端见 src/lib/web/routing-section.js、src/lib/web/settings-controller.js:
关键开关速查:
| 开关 | 默认 | 作用 |
|---|---|---|
| 图片轮整轮自动路由 | 关 | 开启后图片轮不整轮到视觉模型,而是像普通文本轮一样调用 vision_describe 等工具(即本文主角的轮级路由) |
| 识图工具 | 开 | 关闭后 vision_describe / vision_ground 等视觉工具不可用 |
| 图片块改写 | 开 | 模型输入层把图片块换成文字标记;已有视觉记录就给出记录 |
| 隐身模式 | 关 | 接管官方 DeepSeek 路由;官方还在时不启用,避免路由冲突 |
总结:一句话记住轮级视觉路由
图片轮不是"把图片塞给模型",而是"给 Agent 一次指向视觉工具的工具调用"。
像素留在视觉模型侧,推理留在 DeepSeek 侧;改写只发生在模型输入层,会话界面与日志无感;失败有降级链、结果有缓存、迭代可验证。这就是 dsh-vision-router 的图片轮"就是普通工具调用"的完整原理。想动手体验?一条命令即可安装:
npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
更多细节可参阅 README.zh.md 的"工作原理"章节与 docs/v2-capability-routing.md。


