dsh-vision-router 图片轮为什么"就是普通工具调用":轮级视觉路由原理深度解析

原创2026-10-14 09:10:421,732 阅读

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 清晰可见,就像调用任何工具一样):

dsh-vision-router 识图问答:图片轮被改写为 vision_describe 工具调用

工具返回后,DeepSeek 基于视觉模型的像素级观察组织出结构化答案——画面主体、按钮、文字逐条列出:

dsh-vision-router 图片轮视觉路由的工具调用结果:结构化的识图回答

三、路由决策: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 供应商降级链)按顺序逐个尝试,全部失败才报错:

  1. 用户视觉模型(设置页从上到下一行一个)
  2. 本地 Ollama(可选,默认关)
  3. 本地 LM Studio(可选,默认关)
  4. 高级自定义 HTTP 视觉端点
  5. 内置 OVH 匿名免费兜底(5 个免 Key 模型,每 IP 每模型 2 次/分钟,理论合计约 10 次/分钟)

遇到 429 限流会立即切下一后端,并按 Retry-After 开启有上限的熔断冷却;超大上传图在调用前自动压缩(默认预算 400 万像素)。对 Agent 来说,它感受到的只是"这次工具调用可能多花了几秒",路由细节完全透明。

五、一个像素级闭环的实测:为什么工具调用要"可验证"

图片轮作为工具调用的最大好处是可验证——vision_pixel_diff 会给出逐像素差异率和最差网格区域,让 Agent 知道"改得对不对",而不是一句模糊的"看起来差不多":

dsh-vision-router 像素级复刻闭环:参考设计到 Agent 复刻,vision_pixel_diff 实测差异 2.54%

图中展示了完整循环: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:

dsh-vision-router 视觉路由设置页:图片轮整轮自动路由、识图工具、图片块改写、隐身模式开关

关键开关速查:

开关 默认 作用
图片轮整轮自动路由 关 开启后图片轮不整轮到视觉模型,而是像普通文本轮一样调用 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。

登录后查看全文
dsh-vision-router