dsh-vision-router 3.0.4 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.zh.md CHANGED
@@ -9,140 +9,142 @@
9
9
  <p align="center">DeepSeek 只负责思考,内置免费视觉链 + 14 个深看工具负责“看”;需要看图时开启输入框旁的「👁 识图」,图片轮次就像普通工具调用一样自然、可定位、可验证。</p>
10
10
 
11
11
  <p align="center">
12
- <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
13
12
  <a href="https://github.com/zp-home/dsh-recommend"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzp-home%2Fdsh-recommend%2Fmain%2Fdata%2Fbadges%2Fysr666__dsh-vision-router.certified.json&amp;style=flat-square" alt="dsh-recommend 🏅 精选认证" /></a>
14
13
  <a href="https://www.dshbase.com/plugins/dsh-vision-router/"><img src="https://img.shields.io/badge/dshbase-install--tested-2EA44F?style=flat-square" alt="dshbase 实机安装验证" /></a>
15
14
  <a href="https://github.com/SoberReport-AI/DeepGuard/blob/main/reports/dsh-vision-router/2.0.1/39c8f2b2d69aa398418fd6c8ab40b691a92a1a3d.json"><img src="https://img.shields.io/badge/DeepGuard-audit%20clean-2EA44F?style=flat-square" alt="DeepGuard 审计 clean" /></a>
16
- <a href="https://whyihaveyou.github.io/dsh-suite/"><img src="https://img.shields.io/badge/featured%20on-dsh--suite-4d6bfe?style=flat-square" alt="dsh-suite 精选收录" /></a>
17
15
  </p>
18
16
 
19
- <p align="center">
20
- <a href="https://github.com/ysr666/dsh-vision-router/releases/latest"><img src="https://img.shields.io/github/v/release/ysr666/dsh-vision-router?label=release&color=5B4CF0&style=flat-square" alt="Latest stable release" /></a>
21
- <a href="tests"><img src="https://img.shields.io/badge/verified-Node%2022%20%2B%2024-2EA44F?style=flat-square" alt="已验证 Node 22 + 24" /></a>
22
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square" alt="MIT 许可证" /></a>
23
- <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js >=22" /></a>
24
- <img src="https://img.shields.io/badge/runtime-no%20Python-8A2BE2?style=flat-square" alt="无需 Python" />
25
- </p>
26
-
27
- <p align="center">
28
- <sub>生态收录:</sub>
29
- <a href="https://dshplugin.app/plugins/dsh-vision-router">DSHPlugin.app</a> ·
30
- <a href="https://github.com/diegosouzapw/awesome-omni-dsh-plugins">Awesome Omni DSH Plugins</a> ·
31
- <a href="https://dshpluginhub.ai/plugins/dsh-vision-router">dshpluginhub.ai</a> ·
32
- <a href="https://www.dsh.plus/zh/plugins/dsh-vision-router/">dsh.plus</a> ·
33
- <a href="https://dshplugins.ai/">dshplugins.ai</a> ·
34
- <a href="https://dshmarket.com/p/ysr666/dsh-vision-router/">dsh-market</a>
35
- </p>
36
-
37
- <p align="center">代码仓库:<a href="https://github.com/ysr666/dsh-vision-router">GitHub(开发主仓库、Issue、PR及版本发布)</a> · 国内 AtomGit 托管:<a href="https://atomgit.com/ysr666/dsh-vision-router">AtomGit 镜像</a></p>
17
+ <p align="center"><sub>DeepGuard 徽章对应历史 v2.0.1 审计,不代表当前版本已通过同一审计。</sub></p>
38
18
 
39
19
  <p align="center"><a href="README.md">English</a> · 中文</p>
40
20
 
41
- <p align="center">💬 <strong>QQ 用户交流群:1105463028</strong></p>
42
-
43
21
  > [!CAUTION]
44
22
  > **默认配置会让数据出网。** 使用云端视觉模型时,Vision Router 会将图片(或由它裁剪出的局部)、识图提示词及相关请求元数据发送给对应供应商。新安装默认开启 OVHcloud 匿名视觉兜底,因此“免费”和“免 Key”不等于离线。涉密、涉案、内部或其他受限材料请勿使用云端链路。详见[数据流向与严格纯本地配置](#数据流向与严格纯本地配置)。
45
23
 
46
24
  > [!WARNING]
47
- > 📌 **公告(v3.0.4)**
48
- >
49
- > **v3.0.4:DSH alpha.5 兼容验证与发布门禁加固。** 已通过 `0.2.1-alpha.5` 的
50
- > 精确源码、三平台 Host 与真实 Chromium 验收,并更新 CI Action 固定 SHA。
51
- > 原有 DSH Host 最低支持范围保持不变;`0.2.1-rc.1` 待正式发布后另行验收。
52
- > [查看完整更新 →](docs/releases/v3.0.4.md)
25
+ > **v3.1.0 更新说明:** 简化识图模型设置,增加云端出网关闭指引与「不再提醒」,并修正 DSH 兼容、HTTP 和依赖安全问题。参见[v3.1.0 更新说明](docs/releases/v3.1.0.md)。实际可安装版本请以 [GitHub Releases](https://github.com/ysr666/dsh-vision-router/releases/latest)或 npm 为准。
26
+
27
+ ## 先用起来
28
+
29
+ **1. 装进已有的 DSH Web profile:**
30
+
31
+ ```sh
32
+ npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router
33
+ ```
34
+
35
+ **2. 聊天模型照常选,**需要看图时点击输入框旁的 **「👁 识图」**,确认按钮变为 **「👁 识图 ✓」**。
36
+
37
+ **3. 粘贴或上传图片,**直接告诉 Agent 要看什么。内置免 Key 视觉兜底开箱可用,但默认走云端,不是离线识图。
38
+
39
+ 官方 Desktop 应用把 `--profile web` 换成 `--profile desktop`,装完重新加载插件;Oh-DSH 和手动配置请看[完整安装说明](#快速开始)。
40
+
41
+ [详细上手](#快速开始) · [功能亮点](#亮点) · [数据流向与纯本地配置](#数据流向与严格纯本地配置)
53
42
 
54
43
  <p align="center">
55
44
  <img src="assets/vision-demo.gif" width="640" alt="演示:粘贴图片,Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
56
45
  </p>
57
46
 
47
+ ## 试试这些图片任务
48
+
49
+ - **看懂截图:**“这个报错弹窗是什么意思?把具体报错内容读出来。”
50
+ - **定位界面元素:**“截图里的保存按钮在哪里?告诉我它的位置。”
51
+ - **对照设计稿修改页面:**“我的页面和参考图还有哪些区别?下一步该改哪?”修改后还能用 `vision_pixel_diff` 量化差异。
52
+ - **阅读长截图:**“提取这张长截图里的关键信息,不清楚的局部再裁剪确认。”
53
+
54
+ 直接在平常的对话里提问即可:日常模型负责推理,按需调用视觉工具。[查看工具列表](#工具)或[配置自定义/本地视觉后端](#配置项)。
55
+
58
56
  ## 目录
59
57
 
60
- - [数据流向与严格纯本地配置](#数据流向与严格纯本地配置)
61
- - [为什么做这个](#为什么做这个)
62
- - [对比同类插件](#对比同类插件)
63
- - [设计来源](#设计来源)
64
- - [致谢](#致谢)
65
- - [快速开始](#快速开始)
66
- - [免费视觉 Key 渠道](#免费视觉-key-渠道)
58
+ - [试试这些图片任务](#试试这些图片任务)
67
59
  - [亮点](#亮点)
68
60
  - [工作原理](#工作原理)
69
61
  - [工具](#工具)
62
+ - [快速开始](#快速开始)
63
+ - [数据流向与严格纯本地配置](#数据流向与严格纯本地配置)
64
+ - [配置自己的视觉模型](#配置自己的视觉模型)
65
+ - [为什么做这个](#为什么做这个)
66
+ - [对比同类插件](#对比同类插件)
70
67
  - [配置项](#配置项)
71
68
  - [安装与生命周期](#安装与生命周期)
72
69
  - [故障排查](#故障排查)
70
+ - [设计来源](#设计来源)
71
+ - [致谢](#致谢)
72
+ - [版本公告与社区链接](#版本公告与社区链接)
73
73
 
74
- ## 数据流向与严格纯本地配置
75
-
76
- Vision Router 在默认配置下不是完全离线工具。具体边界取决于操作和当前选择的模型:
77
-
78
- | 操作 | 数据去向 |
79
- |---|---|
80
- | 裁剪、像素对比、取色、SVG 矢量化、抠图、文件实体化、HTML 截图等本地像素工具 | 在 DSH 所在机器处理,这些操作不调用视觉模型。 |
81
- | 使用 Tesseract 的 `vision_ocr` | 在 DSH 所在机器处理。默认 `auto` 引擎在本地 OCR 不可用或结果为空时,可能回退到视觉模型。 |
82
- | 图片轮路由及 describe、detect、ground、视觉 OCR 等模型工具 | 图片或局部裁剪、提示词和相关上下文会发送给当前视觉供应商。 |
83
- | 内置免费兜底 | 以匿名方式(无 API Key)发往 OVHcloud AI Endpoints `oai.endpoints.kepler.ai.cloud.ovh.net`;服务仍会收到请求内容和源 IP 等网络元数据。 |
84
- | 用户配置的云模型 / HTTP 供应商 | 发送到对应配置端点,并受该供应商的保留与隐私条款约束。 |
85
- | 本地 Ollama / LM Studio | 图像像素发送到配置的本地端点;识图结果文本仍会回到当前聊天模型,而聊天模型自身可能仍在云端。 |
74
+ ## 亮点
86
75
 
87
- 若要阻止 **Vision Router 本身**把图片发送给远程视觉端点,请开启 **设置 → Vision Router → 常规 → 仅本地视觉**。这是运行时策略,不会破坏性修改配置:已保存的云端识图行和 `freeFallback` 会保留,但开关开启期间无法执行;只有回环地址(`localhost`、`127.0.0.0/8`、`::1`)上的视觉端点可以运行,包括 Ollama、LM Studio 和自定义本机 HTTP 后端。若要求**整个工作流严格纯本地**,还必须同时使用本地聊天模型,因为识图结果文本仍会交给当前聊天模型。请在自己的环境中验证最终网络边界;Vision Router 无法把远程聊天模型、代理或 Host 集成变成本地服务。
76
+ - **能力感知 Auto 路由。** 想要确定性就继续按配置顺序;想自动选择时再显式开启 Auto,只在已配置模型和已有实测证据上调整优先级。不会通过模型名猜能力,单纯开启 Auto 也不会自动发起测评。
77
+ - **可验证的模型测评。** 「测试识图」只向当前精确模型发一次请求;Quick / Full 分别测 OCR、通用理解,以及结构化、文档、定位等能力。后台能力数据是独立授权,并会给真实前台识图让路。
78
+ - **原图像素,真实答案。** 视觉链按原始分辨率读图(仅为保护延迟/额度自动缩放);你的问题随图一起发送,答案围绕*你的问题*,而不是一段泛泛的描述。
79
+ - **自动降级 + 分类报错。** 地区限制、ToS 风控、402 额度、429 限流、上下文超长、网络故障——链路逐供应商尝试,全部失败才报错并给出可操作的建议。遇到 429 会立即尝试下一后端,并按 Retry-After 开启冷却,不会在单次请求内睡眠等待。
80
+ - **图片记忆。** 视觉答案按附件内容哈希缓存;后续文字轮用记录的描述替换历史图片(标注为不可信证据),DeepSeek 真正“记得”之前发过的图,且不重复消耗视觉调用。
81
+ - **可验证的像素闭环。** 参照图 → `vision_html_screenshot` → `vision_pixel_diff`(差异率 + 红色热力图 + 最差区域排行)→ 修复 → 再对比,直到差异收敛。UI 还原从“目测”变成“实测”。
82
+ - **稳定工具 schema。** 默认从会话开始就注册完整 14 个深看工具,避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in;开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
83
+ - **选择性代理。** 只有配置的视觉供应商域名走本地代理;DeepSeek 保持直连。
88
84
 
89
- ## 为什么做这个
85
+ ### 像素闭环实测
90
86
 
91
- 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**Host 规范化后的图像像素留在视觉模型侧**、把推理留在 DeepSeek 侧,并把“看图”变成一次**普通的工具调用**:
87
+ [![参考设计与 Agent 最终复刻,通过 vision_pixel_diff 实测最终差异为 2.54%。](assets/pixel-loop-zh.png)](assets/pixel-loop-zh.png)
92
88
 
93
- - **一条命令安装。** 包自带组合补丁(`dsh.bundle.patch`):`dsh plugin add` 自动完成插件行挂载、准入包装与附件限制放宽——不用手改任何文件。是否接管官方 DeepSeek 路由由「隐身模式」开关决定(默认关)。
94
- - **默认免费。** 视觉工具最终兜底为 5 个 OVHcloud 匿名视觉模型:免注册、免 Key,每 IP、每模型 2 次/分钟,独立限额理论合计约 10 次/分钟;用户自备视觉模型会优先调用。
95
- - **无 Python。** 整条管线——缩放、定位、裁剪、像素对比、取色、OCR、SVG 矢量化、抠图、HTML 截图——全部基于 sharp / potrace / tesseract / 系统 Chrome。
96
- - **可连续多步看图。** 图片轮 = 调用工具的文本轮:`vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → 修复 → 再截图,Agent 可以一直迭代到任务完成。
97
- - **DeepSeek 始终是大脑。** 文字轮在模型、成本、上下文上完全不动;视觉模型只当“眼睛”、按需调用,答案按图片内容缓存。
98
- - **界面无感。** 上传的图片在会话界面里照常显示为图片;指向视觉工具的改写只发生在模型输入层,从不写入会话日志。
89
+ <p align="center"><sub>点击图片可查看完整原图。</sub></p>
99
90
 
100
- ## 对比同类插件
91
+ Agent 仅根据参考图复刻 UI,再用 `vision_pixel_diff` 验证最终结果:**最终差异 2.54%**(32,939 / 1,296,000 个差异像素,threshold 16/channel)。
101
92
 
102
- **一句话讲清区别**:其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"(描述桥,有信息损耗);
103
- 本插件主打"**图片轮直接交给视觉模型看图像像素**"(路由桥,像素级),同时内置免 Key 免费模型兜底。
93
+ ## 工作原理
104
94
 
105
- > [!NOTE]
106
- > 在 DSH 0.1.2-alpha.1+ 上,附件仍由 Host 单一持有。Vision Router 消费的是 Host 持久化后的 canonical image:落在规范化限制内的单帧 8-bit sRGB/sRGBA 图片可以逐字节直通;需要旋转、色彩空间、元数据、动画或尺寸规范化的图片可能会被重新编码。因此像素工具承诺的是 Host canonical raster,而不是上传源文件编码字节逐字节不变。
95
+ <p align="center">
96
+ <img src="assets/how-it-works-zh.svg" width="100%" alt="DSH Vision Router 的工作原理:DeepSeek 作为大脑,视觉工具作为眼睛。" />
97
+ </p>
107
98
 
108
- | | 手动切换模型 | MCP 视觉桥 | 本插件 |
109
- |---|---|---|---|
110
- | 图像像素 | ✅ 可用(切换后) | ❌ 只有文字描述 | ✅ Host 规范化栅格,图片轮内 |
111
- | 自动化 | ❌ | ✅ | ✅ |
112
- | 日常模型不受影响 | ❌(整会话被换) | ✅ | ✅ |
113
- | 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
114
- | 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
115
- | 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
116
- | 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
99
+ 视觉模型**只当眼睛**,DeepSeek **始终是大脑**。图片轮永远不会被一次性视觉答案“劫持”——Agent 自己驱动工具,可以跨多个步骤持续对同一张图操作。
117
100
 
118
- **与现有 dsh 社区方案的差异**(均为优秀项目,各有侧重;描述以各家 README 2026-08 状态为准):
101
+ ## 工具
119
102
 
120
- | 项目 | 思路 | 本插件的差异 |
121
- |---|---|---|
122
- | [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述,描述作为会话消息交给 DeepSeek;默认 LLM7.io 匿名端点(OVHcloud 为无 Key 备选) | 描述桥方案;本插件提供"图像直看"路由,描述能力由 `vision_describe` 按需替代 |
123
- | [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由,请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案;本插件不包装 provider,通过 `agent/request` 瀑布改写路由 |
124
- | [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由:图片先经所选视觉模型转成描述,再交给 DeepSeek | 双模型桥思路;本插件在此基础上增加自动路由、降级链与工具 |
125
- | [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件;复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路;本插件自带供应商链,不依赖本机其他 CLI |
126
- | [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具(Q&A/OCR/像素校验/UI 还原),按需显式调用 | 工具集更全;本插件多出整轮自动路由与免 Key 免费兜底 |
127
- | [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | `inspect_image` 工具 + `agent/pre-step` 瀑布图片桥(粘贴图入日志前转成工具提示) | 瀑布桥思路相近;本插件多出轮次路由、降级链、缓存与免费端点 |
103
+ 默认 `progressiveTools: false`:14 个深看工具从插件启动时就保持常驻,文本轮和图片轮都可直接调用。若你在 profile / composition 的 `cordis.patch.yml` 中显式开启 `progressiveTools: true`,才会恢复渐进模式:初始只暴露 `vision_activate`,首次需要时再挂载完整工具,并注册 `vision-tools` 技能。该开关是启动期配置,修改后需重启 DSH。全部工具基于 sharp / potrace / tesseract / 系统 Chrome——无 Python:
128
104
 
129
- ## 设计来源
105
+ <p align="center">
106
+ <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个图像处理工具。" />
107
+ </p>
130
108
 
131
- 本项目的深度视觉工具层与 UI restoration 工作流参考并受到 [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) 及其 DSH 原生实现 [Anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) 的设计影响。具体包括意图驱动的工具选择、渐进式工具暴露、pixel-diff 验证闭环,以及部分视觉工具的职责划分与命名,包括长截图 OCR、前景提取和 HTML screenshot 等设计。
109
+ 图中展示 11 个图像处理工具;另有 `vision_materialize`、负责持久展示图片的 `vision_present` 与可选 1+x 结构化首遍识别的 `vision_bootstrap`,默认深看工具集共 14 个。若启动时显式开启隐私敏感的 `vision_screenshot`,则额外增加为第 15 个工具。
132
110
 
133
- `dsh-vision-router` 中相关代码均为独立实现。在这些设计参考基础上,本项目独立发展了 turn-level/tools-first vision routing、DSH 准入/包装集成、多视觉后端与故障 fallback chain、内置免费视觉模型链、附件/图片记忆、缓存与相关运行时容错机制。
111
+ | 工具 | 作用 | 产物 |
112
+ |---|---|---|
113
+ | `vision_bootstrap` | 可选 1+x 结构化首遍视觉识别;先建立任务无关证据底图,再至少进行 1 次后续视觉调用 | — |
114
+ | `vision_describe` | 看图问答 / 多图对比 / 结构化证据 JSON 模式(摘要 + 布局区域 + 实体清单 + 原文转写) | — |
115
+ | `vision_materialize` | 把已授权附件复制到稳定的内容寻址工作区交接文件,并返回绝对路径和较短的工作区相对路径,供本地 OCR/解析器降级使用;不调用视觉模型或网络 | image copy |
116
+ | `vision_ground` | 定位目标 → **原图像素框 x1/y1/x2/y2** | 标注 PNG(可选) |
117
+ | `vision_detect` | 盘点某类元素(按钮/输入框/链接…)→ 编号清单 + 原图像素框 | 编号标注 PNG |
118
+ | `vision_crop` | 按像素框裁剪放大 | PNG |
119
+ | `vision_present` | 把生成或编辑后的本地图片发布为持久聊天附件,供用户查看 | 图片附件 |
120
+ | `vision_pixel_diff` | 逐像素对比:差异率 + 最差 8×8 网格区域 | 红色热力图 PNG + JSON 报告 |
121
+ | `vision_colors` | 主色提取(十六进制 + 占比) | — |
122
+ | `vision_ocr` | 文字转写:默认引擎可配置为 `auto` / 本地 Tesseract / 视觉模型;单次显式 engine 仍优先 | — |
123
+ | `vision_trace` | SVG 矢量化(potrace 分色;图标/logo) | SVG |
124
+ | `vision_extract_foreground` | 边界洪泛抠图(纯色背景) | 透明 PNG |
125
+ | `vision_html_screenshot` | 给本地 HTML 文件截图(无头系统 Chrome);`fullPage: true` 截整页并返回 `pageHeight` | PNG |
126
+ | `vision_screenshot` | **默认关闭,必须显式开启隐私开关。** 截取 Windows 虚拟屏幕、macOS 主显示器或 Linux 根窗口;Windows 使用 PowerShell CopyFromScreen,macOS 使用 `screencapture`,Linux 需安装 ImageMagick `import` 或 `scrot`;`identify=true` 可按顺序尝试已启用的本地识别后端并返回路径+识别文本 | PNG / +描述文本 |
127
+ | `vision_long_screenshot_ocr` | 长截图转写:重叠分片,tesseract 优先 / 视觉模型回退,按序拼接 Markdown | 分片 PNG + Markdown + manifest |
134
128
 
135
- 感谢 Anionex 的先行工作以及整个 DSH 社区的探索。清晰的设计归因与独立迭代并不冲突;二者都有助于维护开放、协作、健康的 DSH 生态。
129
+ 图片格式按**魔数识别**,无扩展名的内容寻址附件文件也能直接用(不用再复制成 `.png`)。
136
130
 
137
- ## 致谢
131
+ **常用流程**
138
132
 
139
- 本插件借鉴了以上全部社区项目的思路,特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
140
- 对免注册免 Key 视觉端点的探索(LLM7.io 与 OVHcloud 匿名层)。感谢
141
- [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
142
- [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
143
- [modlens](https://github.com/liustack/modlens)、
144
- [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
145
- [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) 作者们的探索。
133
+ ```text
134
+ vision_ground image="ref.png" target="发送按钮"
135
+ vision_detect image="page.png" target="输入框"
136
+ vision_crop image="ref.png" region="1067,841,1108,881"
137
+ vision_present path="rebuilt.png"
138
+ vision_describe paths=["ref.png","impl.png"] question="列出两图的差异" json=true
139
+ vision_pixel_diff original="ref.png" rebuilt="screenshot.png"
140
+ vision_ocr image="screenshot.png"
141
+ vision_colors image="ref.png" top=8
142
+ vision_trace image="icon.png" steps=4
143
+ vision_extract_foreground image="logo.png"
144
+ vision_html_screenshot source="page.html" width=1200 height=720
145
+ vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
146
+ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
147
+ ```
146
148
 
147
149
  ## 快速开始
148
150
 
@@ -215,101 +217,68 @@ pnpm dsh plugin --profile web add dsh-vision-router
215
217
  <img src="assets/dsh-conversation-image-qa-result.png" width="49%" alt="Agent 对图片内容的结构化解读。" />
216
218
  </p>
217
219
 
218
- ## 免费视觉 Key 渠道
219
-
220
- 内置 OVH 兜底是匿名设计,OVH 对匿名访问的限制是**每 IP、每模型 2 次/分钟**。觉得不够用时,下面这些渠道都有**免费且额度大得多的视觉模型**——全部免费注册,无需为免费档付费。免费政策轮换频繁,下表是 2026 年 8 月快照,依赖前请以各家控制台为准。
221
-
222
- | 渠道 | 免费视觉模型 | 免费额度 | 大陆直连 | Key 领取 |
223
- |---|---|---|---|---|
224
- | OVHcloud AI Endpoints(access key) | `Qwen2.5-VL-72B-Instruct`——与内置兜底同一个端点 | **400 次/分钟**/项目/模型(对比匿名 2 次/分钟) | ✅ | 注册 OVH 账号 → Public Cloud 项目(需挂支付方式;免费模型不扣费)→ AI Endpoints access key |
225
- | 智谱(bigmodel.cn) | `glm-4.6v-flash` · `glm-4.1v-thinking-flash` · `glm-4v-flash`——三个永久免费模型,串起来容量 ×3 | token 不限量 | ✅ | open.bigmodel.cn → API keys |
226
- | 阿里云百炼 | `qwen3-vl-flash`(限免)与 Qwen-VL 系列 | 新用户每模型系列 100 万 token / 90 天 | ✅ | bailian.console.aliyun.com |
227
- | Intern AI(上海AI实验室) | `internvl-latest` · `internvl3.5-latest` | 30 RPM,**9000 万 token/月** | ✅ | chat.intern-ai.org.cn |
228
- | Groq | `meta-llama/llama-4-scout-17b-16e-instruct`(原生多模态,最多 5 张图) | 30 RPM / 14,400 次/天,免卡 | ❌ 需代理 | console.groq.com |
229
- | Google AI Studio | `gemini-2.5-flash` · `gemini-2.5-flash-lite` | 10–30 RPM / 500–1,500 次/天 | ❌ 需代理 | aistudio.google.com |
230
- | NVIDIA NIM | `meta/llama-3.2-11b-vision-instruct` · `nvidia/nemotron-nano-12b-v2-vl` | 40 RPM,免卡 | ⚠️ | build.nvidia.com |
231
- | OpenCode Zen | `mimo-v2.5-free`(视觉 + 代码) | 30 RPM / 500 次/天 | ⚠️ | opencode.ai/zen |
232
- | OpenRouter | `google/gemma-4-26b-a4b-it:free` · `google/gemma-4-31b-it:free` | 未充值账户 50 次/天 | ❌ 需代理 | openrouter.ai |
220
+ ## 数据流向与严格纯本地配置
233
221
 
234
- 以上渠道都能以 `httpProviders` 条目加入视觉链(Key 放对应环境变量或 `~/.dsh/.credentials.yaml`),链路会先尝试你的条目、再落到匿名兜底。
222
+ Vision Router 在默认配置下不是完全离线工具。具体边界取决于操作和当前选择的模型:
235
223
 
236
- > [!NOTE]
237
- > 免费政策随时可能调整——Cerebras 已在 2026 年 7 月取消免费档(改为一次性 $5 赠金),SambaNova 免费档收紧到 20 次/天,Hugging Face 只剩 $0.10/月。第三方“`:free` 中转”聚合站刻意不列入:轮换频繁、无 SLA,部分还存在违反上游条款的转售行为。
224
+ | 操作 | 数据去向 |
225
+ |---|---|
226
+ | 裁剪、像素对比、取色、SVG 矢量化、抠图、文件实体化、HTML 截图等本地像素工具 | 在 DSH 所在机器处理,这些操作不调用视觉模型。 |
227
+ | 使用 Tesseract 的 `vision_ocr` | 在 DSH 所在机器处理。默认 `auto` 引擎在本地 OCR 不可用或结果为空时,可能回退到视觉模型。 |
228
+ | 图片轮路由及 describe、detect、ground、视觉 OCR 等模型工具 | 图片或局部裁剪、提示词和相关上下文会发送给当前视觉供应商。 |
229
+ | 内置免费兜底 | 以匿名方式(无 API Key)发往 OVHcloud AI Endpoints `oai.endpoints.kepler.ai.cloud.ovh.net`;服务仍会收到请求内容和源 IP 等网络元数据。 |
230
+ | 用户配置的云模型 / HTTP 供应商 | 发送到对应配置端点,并受该供应商的保留与隐私条款约束。 |
231
+ | 本地 Ollama / LM Studio | 图像像素发送到配置的本地端点;识图结果文本仍会回到当前聊天模型,而聊天模型自身可能仍在云端。 |
238
232
 
239
- ## 亮点
233
+ 若要阻止 **Vision Router 本身**把图片发送给远程视觉端点,请开启 **设置 → Vision Router → 常规 → 仅本地视觉**。这是运行时策略,不会破坏性修改配置:已保存的云端识图行和 `freeFallback` 会保留,但开关开启期间无法执行;只有回环地址(`localhost`、`127.0.0.0/8`、`::1`)上的视觉端点可以运行,包括 Ollama、LM Studio 和自定义本机 HTTP 后端。若要求**整个工作流严格纯本地**,还必须同时使用本地聊天模型,因为识图结果文本仍会交给当前聊天模型。请在自己的环境中验证最终网络边界;Vision Router 无法把远程聊天模型、代理或 Host 集成变成本地服务。
240
234
 
241
- - **能力感知 Auto 路由。** 想要确定性就继续按配置顺序;想自动选择时再显式开启 Auto,只在已配置模型和已有实测证据上调整优先级。不会通过模型名猜能力,单纯开启 Auto 也不会自动发起测评。
242
- - **可验证的模型测评。** 「测试识图」只向当前精确模型发一次请求;Quick / Full 分别测 OCR、通用理解,以及结构化、文档、定位等能力。后台能力数据是独立授权,并会给真实前台识图让路。
243
- - **原图像素,真实答案。** 视觉链按原始分辨率读图(仅为保护延迟/额度自动缩放);你的问题随图一起发送,答案围绕*你的问题*,而不是一段泛泛的描述。
244
- - **自动降级 + 分类报错。** 地区限制、ToS 风控、402 额度、429 限流、上下文超长、网络故障——链路逐供应商尝试,全部失败才报错并给出可操作的建议。遇到 429 会立即尝试下一后端,并按 Retry-After 开启冷却,不会在单次请求内睡眠等待。
245
- - **图片记忆。** 视觉答案按附件内容哈希缓存;后续文字轮用记录的描述替换历史图片(标注为不可信证据),DeepSeek 真正“记得”之前发过的图,且不重复消耗视觉调用。
246
- - **可验证的像素闭环。** 参照图 → `vision_html_screenshot` → `vision_pixel_diff`(差异率 + 红色热力图 + 最差区域排行)→ 修复 → 再对比,直到差异收敛。UI 还原从“目测”变成“实测”。
247
- - **稳定工具 schema。** 默认从会话开始就注册完整 14 个深看工具,避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in;开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
248
- - **选择性代理。** 只有配置的视觉供应商域名走本地代理;DeepSeek 保持直连。
235
+ ## 配置自己的视觉模型
249
236
 
250
- ### 像素闭环实测
237
+ **供应商、凭据和全局模型目录由DSH负责;Vision Router使用DSH已配置模型,负责视觉编排、执行、测试与诊断。** 无需安装插件专属的厂商YAML。对**已在DSH配置**的供应商,插件可在自己的视觉后端选择器内补充实时`/models`发现结果及严格限定端点的视觉能力提示;这些内容不会新增供应商或修改DSH全局目录,过期缓存或仅保存的模型ID也不能单独授权直连。参见[历史架构依据](docs/architecture/model-catalog-ownership.md)。
251
238
 
252
- [![参考设计与 Agent 最终复刻,通过 vision_pixel_diff 实测最终差异为 2.54%。](assets/pixel-loop-zh.png)](assets/pixel-loop-zh.png)
239
+ 在DSH「设置 → 模型」维护供应商、模型与密钥,在Vision Router视觉后端列表中选择同一Host目录里的模型,并用「测试识图」核实精确模型确实读取图片。若Host把真正的视觉模型误报为仅文本,优先使用DSH模型设置的「输入类型 → 图片」;旧Host可在**确认模型确实接受图片**后配置`llm-pi-ai`的`input: [text, image]`,再重载配置,不得对纯文本模型伪造能力。
253
240
 
254
- <p align="center"><sub>点击图片可查看完整原图。</sub></p>
241
+ 内置OVH匿名兜底属于Vision Router工具的`httpProviders`运行时,不是DSH厂商目录条目。严格纯本地使用需要同时使用本地聊天模型并开启「仅本地视觉」。商用API的价格、免费额度及模型ID动态变化,本项目不再维护推荐表。[2026年8月历史调研](docs/free-models.zh-CN.md)仅供追溯。
255
242
 
256
- Agent 仅根据参考图复刻 UI,再用 `vision_pixel_diff` 验证最终结果:**最终差异 2.54%**(32,939 / 1,296,000 个差异像素,threshold 16/channel)。
243
+ ## 为什么做这个
257
244
 
258
- ## 工作原理
245
+ 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**Host 规范化后的图像像素留在视觉模型侧**、把推理留在 DeepSeek 侧,并把“看图”变成一次**普通的工具调用**:
259
246
 
260
- <p align="center">
261
- <img src="assets/how-it-works-zh.svg" width="100%" alt="DSH Vision Router 的工作原理:DeepSeek 作为大脑,视觉工具作为眼睛。" />
262
- </p>
247
+ - **一条命令安装。** 包自带组合补丁(`dsh.bundle.patch`):`dsh plugin add` 自动完成插件行挂载、准入包装与附件限制放宽——不用手改任何文件。是否接管官方 DeepSeek 路由由「隐身模式」开关决定(默认关)。
248
+ - **默认免费。** 视觉工具最终兜底为 4 个 OVHcloud 匿名视觉模型:免注册、免 Key,每 IP、每模型 2 次/分钟,独立限额理论合计约 8 次/分钟;用户自备视觉模型会优先调用。
249
+ - **无 Python。** 整条管线——缩放、定位、裁剪、像素对比、取色、OCR、SVG 矢量化、抠图、HTML 截图——全部基于 sharp / potrace / tesseract / 系统 Chrome。
250
+ - **可连续多步看图。** 图片轮 = 调用工具的文本轮:`vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → 修复 → 再截图,Agent 可以一直迭代到任务完成。
251
+ - **DeepSeek 始终是大脑。** 文字轮在模型、成本、上下文上完全不动;视觉模型只当“眼睛”、按需调用,答案按图片内容缓存。
252
+ - **界面无感。** 上传的图片在会话界面里照常显示为图片;指向视觉工具的改写只发生在模型输入层,从不写入会话日志。
263
253
 
264
- 视觉模型**只当眼睛**,DeepSeek **始终是大脑**。图片轮永远不会被一次性视觉答案“劫持”——Agent 自己驱动工具,可以跨多个步骤持续对同一张图操作。
254
+ ## 对比同类插件
265
255
 
266
- ## 工具
256
+ **一句话讲清区别**:其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"(描述桥,有信息损耗);
257
+ 本插件主打"**图片轮直接交给视觉模型看图像像素**"(路由桥,像素级),同时内置免 Key 免费模型兜底。
267
258
 
268
- 默认 `progressiveTools: false`:14 个深看工具从插件启动时就保持常驻,文本轮和图片轮都可直接调用。若你在 profile / composition 的 `cordis.patch.yml` 中显式开启 `progressiveTools: true`,才会恢复渐进模式:初始只暴露 `vision_activate`,首次需要时再挂载完整工具,并注册 `vision-tools` 技能。该开关是启动期配置,修改后需重启 DSH。全部工具基于 sharp / potrace / tesseract / 系统 Chrome——无 Python:
259
+ > [!NOTE]
260
+ > 在 DSH 0.1.2-alpha.1+ 上,附件仍由 Host 单一持有。Vision Router 消费的是 Host 持久化后的 canonical image:落在规范化限制内的单帧 8-bit sRGB/sRGBA 图片可以逐字节直通;需要旋转、色彩空间、元数据、动画或尺寸规范化的图片可能会被重新编码。因此像素工具承诺的是 Host canonical raster,而不是上传源文件编码字节逐字节不变。
269
261
 
270
- <p align="center">
271
- <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个图像处理工具。" />
272
- </p>
262
+ | | 手动切换模型 | MCP 视觉桥 | 本插件 |
263
+ |---|---|---|---|
264
+ | 图像像素 | ✅ 可用(切换后) | ❌ 只有文字描述 | ✅ Host 规范化栅格,图片轮内 |
265
+ | 自动化 | ❌ | ✅ | ✅ |
266
+ | 日常模型不受影响 | ❌(整会话被换) | ✅ | ✅ |
267
+ | 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
268
+ | 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
269
+ | 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
270
+ | 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
273
271
 
274
- 图中展示 11 个图像处理工具;另有 `vision_materialize`、负责持久展示图片的 `vision_present` 与可选 1+x 结构化首遍识别的 `vision_bootstrap`,默认深看工具集共 14 个。若启动时显式开启隐私敏感的 `vision_screenshot`,则额外增加为第 15 个工具。
272
+ **与现有 dsh 社区方案的差异**(均为优秀项目,各有侧重;描述以各家 README 2026-08 状态为准):
275
273
 
276
- | 工具 | 作用 | 产物 |
274
+ | 项目 | 思路 | 本插件的差异 |
277
275
  |---|---|---|
278
- | `vision_bootstrap` | 可选 1+x 结构化首遍视觉识别;先建立任务无关证据底图,再至少进行 1 次后续视觉调用 | — |
279
- | `vision_describe` | 看图问答 / 多图对比 / 结构化证据 JSON 模式(摘要 + 布局区域 + 实体清单 + 原文转写) | — |
280
- | `vision_materialize` | 把已授权附件复制到稳定的内容寻址工作区交接文件,并返回绝对路径和较短的工作区相对路径,供本地 OCR/解析器降级使用;不调用视觉模型或网络 | image copy |
281
- | `vision_ground` | 定位目标 → **原图像素框 x1/y1/x2/y2** | 标注 PNG(可选) |
282
- | `vision_detect` | 盘点某类元素(按钮/输入框/链接…)→ 编号清单 + 原图像素框 | 编号标注 PNG |
283
- | `vision_crop` | 按像素框裁剪放大 | PNG |
284
- | `vision_present` | 把生成或编辑后的本地图片发布为持久聊天附件,供用户查看 | 图片附件 |
285
- | `vision_pixel_diff` | 逐像素对比:差异率 + 最差 8×8 网格区域 | 红色热力图 PNG + JSON 报告 |
286
- | `vision_colors` | 主色提取(十六进制 + 占比) | — |
287
- | `vision_ocr` | 文字转写:默认引擎可配置为 `auto` / 本地 Tesseract / 视觉模型;单次显式 engine 仍优先 | — |
288
- | `vision_trace` | SVG 矢量化(potrace 分色;图标/logo) | SVG |
289
- | `vision_extract_foreground` | 边界洪泛抠图(纯色背景) | 透明 PNG |
290
- | `vision_html_screenshot` | 给本地 HTML 文件截图(无头系统 Chrome);`fullPage: true` 截整页并返回 `pageHeight` | PNG |
291
- | `vision_screenshot` | **默认关闭,必须显式开启隐私开关。** 截取 Windows 虚拟屏幕、macOS 主显示器或 Linux 根窗口;Windows 使用 PowerShell CopyFromScreen,macOS 使用 `screencapture`,Linux 需安装 ImageMagick `import` 或 `scrot`;`identify=true` 可按顺序尝试已启用的本地识别后端并返回路径+识别文本 | PNG / +描述文本 |
292
- | `vision_long_screenshot_ocr` | 长截图转写:重叠分片,tesseract 优先 / 视觉模型回退,按序拼接 Markdown | 分片 PNG + Markdown + manifest |
293
-
294
- 图片格式按**魔数识别**,无扩展名的内容寻址附件文件也能直接用(不用再复制成 `.png`)。
295
-
296
- **常用流程**
297
-
298
- ```text
299
- vision_ground image="ref.png" target="发送按钮"
300
- vision_detect image="page.png" target="输入框"
301
- vision_crop image="ref.png" region="1067,841,1108,881"
302
- vision_present path="rebuilt.png"
303
- vision_describe paths=["ref.png","impl.png"] question="列出两图的差异" json=true
304
- vision_pixel_diff original="ref.png" rebuilt="screenshot.png"
305
- vision_ocr image="screenshot.png"
306
- vision_colors image="ref.png" top=8
307
- vision_trace image="icon.png" steps=4
308
- vision_extract_foreground image="logo.png"
309
- vision_html_screenshot source="page.html" width=1200 height=720
310
- vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
311
- vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
312
- ```
276
+ | [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述,描述作为会话消息交给 DeepSeek;默认 LLM7.io 匿名端点(OVHcloud 为无 Key 备选) | 描述桥方案;本插件提供"图像直看"路由,描述能力由 `vision_describe` 按需替代 |
277
+ | [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由,请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案;本插件不包装 provider,通过 `agent/request` 瀑布改写路由 |
278
+ | [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由:图片先经所选视觉模型转成描述,再交给 DeepSeek | 双模型桥思路;本插件在此基础上增加自动路由、降级链与工具 |
279
+ | [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件;复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路;本插件自带供应商链,不依赖本机其他 CLI |
280
+ | [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具(Q&A/OCR/像素校验/UI 还原),按需显式调用 | 工具集更全;本插件多出整轮自动路由与免 Key 免费兜底 |
281
+ | [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | `inspect_image` 工具 + `agent/pre-step` 瀑布图片桥(粘贴图入日志前转成工具提示) | 瀑布桥思路相近;本插件多出轮次路由、降级链、缓存与免费端点 |
313
282
 
314
283
  ## 供应商降级链
315
284
 
@@ -319,7 +288,7 @@ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
319
288
  2. **本地 Ollama(可选,默认关)**:`localOllama.enabled` 开启后,通过本机 Ollama 做免 Key、离线识别(例如 qwen2.5vl);
320
289
  3. **本地 LM Studio(可选,默认关)**:`localLmStudio.enabled` 排在 Ollama 之后,模型名必须填写 LM Studio Developer 页或 `/v1/models` 返回的真实标识;
321
290
  4. **高级自定义 HTTP 视觉端点**:旧配置/高级配置中的 `httpProviders` 排在本地后端之后;
322
- 5. **内置 OVH 匿名免费兜底**:固定最后尝试,不需要出现在任何模型选择器里。当前内置链按质量优先为 `Qwen3.5-397B-A17B` → `Qwen2.5-VL-72B-Instruct` → `Qwen3.6-27B` → `Mistral-Small-3.2-24B-Instruct-2506` → `Qwen3.5-9B`。OVH 匿名限额为 **每 IP、每模型 2 次/分钟**;5 个模型是独立限额,因此理论上分散请求可到约 **10 次/分钟**,实际仍以 OVH 当时的限流为准。免注册、免 Key。想提额度?详见[免费视觉 Key 渠道](#免费视觉-key-渠道)——同一个端点挂免费 access key 后是 400 次/分钟。
291
+ 5. **内置 OVH 匿名免费兜底**:固定最后尝试,不需要出现在任何模型选择器里。当前内置链按质量优先为 `Qwen3.5-397B-A17B` → `Qwen2.5-VL-72B-Instruct` → `Qwen3.6-27B` → `Qwen3.5-9B`。OVH 匿名限额为 **每 IP、每模型 2 次/分钟**;4 个模型是独立限额,因此理论上分散请求可到约 **8 次/分钟**,实际仍以 OVH 当时的限流为准。OVH 已公告原有 Mistral Small 3.2 模型将在 2026 年 11 月 4 日下线,因此已从自动兜底移除,但不会修改用户手动保存的配置。免注册、免 Key。如需额外容量,请通过DSH配置自备模型;参见[配置自己的视觉模型](#配置自己的视觉模型)。
323
292
 
324
293
  > [!IMPORTANT]
325
294
  > 这里的“视觉链”是 Vision Router 调用的**眼睛**:设置页里每一行只选一个用户视觉模型;聊天页右下角选择的是**脑子/会话模型**,两者完全分开。纯文本 DeepSeek / opencode 不会出现在视觉后端下拉里;内部 `Vision HTTP` 也不会再暴露给用户。
@@ -614,6 +583,42 @@ npx dsh-vision-router doctor --profile web
614
583
  - 密钥不上线:`apiKeyEnv` 只指向 DSH 凭据引用,值按调用解析、永不写入日志。
615
584
  - 设置写入走设置服务(schema 校验 + 修订号检查)——过期或非法的保存会被拒绝,不会半截生效。
616
585
 
586
+ ## 设计来源
587
+
588
+ 本项目的深度视觉工具层与 UI restoration 工作流参考并受到 [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) 及其 DSH 原生实现 [Anionex/dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) 的设计影响。具体包括意图驱动的工具选择、渐进式工具暴露、pixel-diff 验证闭环,以及部分视觉工具的职责划分与命名,包括长截图 OCR、前景提取和 HTML screenshot 等设计。
589
+
590
+ `dsh-vision-router` 中相关代码均为独立实现。在这些设计参考基础上,本项目独立发展了 turn-level/tools-first vision routing、DSH 准入/包装集成、多视觉后端与故障 fallback chain、内置免费视觉模型链、附件/图片记忆、缓存与相关运行时容错机制。
591
+
592
+ 感谢 Anionex 的先行工作以及整个 DSH 社区的探索。清晰的设计归因与独立迭代并不冲突;二者都有助于维护开放、协作、健康的 DSH 生态。
593
+
594
+ ## 致谢
595
+
596
+ 本插件借鉴了以上全部社区项目的思路,特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
597
+ 对免注册免 Key 视觉端点的探索(LLM7.io 与 OVHcloud 匿名层)。感谢
598
+ [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
599
+ [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
600
+ [modlens](https://github.com/liustack/modlens)、
601
+ [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
602
+ [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) 作者们的探索。
603
+
604
+ ## 版本公告与社区链接
605
+
606
+ 版本更新详情:[v3.1.0 更新说明](docs/releases/v3.1.0.md)。正式可安装版本请以 GitHub Releases 或 npm 为准。
607
+
608
+ <p align="center">
609
+ <sub>生态收录:</sub>
610
+ <a href="https://dshplugin.app/plugins/dsh-vision-router">DSHPlugin.app</a> ·
611
+ <a href="https://github.com/diegosouzapw/awesome-omni-dsh-plugins">Awesome Omni DSH Plugins</a> ·
612
+ <a href="https://dshpluginhub.ai/plugins/dsh-vision-router">dshpluginhub.ai</a> ·
613
+ <a href="https://www.dsh.plus/zh/plugins/dsh-vision-router/">dsh.plus</a> ·
614
+ <a href="https://dshplugins.ai/">dshplugins.ai</a> ·
615
+ <a href="https://dshmarket.com/p/ysr666/dsh-vision-router/">dsh-market</a>
616
+ </p>
617
+
618
+ <p align="center">代码仓库:<a href="https://github.com/ysr666/dsh-vision-router">GitHub(开发主仓库、Issue、PR及版本发布)</a> · 国内 AtomGit 托管:<a href="https://atomgit.com/ysr666/dsh-vision-router">AtomGit 镜像</a></p>
619
+
620
+ <p align="center">💬 <strong>QQ 用户交流群:1105463028</strong></p>
621
+
617
622
  ## License
618
623
 
619
624
  [MIT](LICENSE)
@@ -0,0 +1,41 @@
1
+ # 模型目录所有权与预设退役|架构决策
2
+
3
+ > **DSH负责模型供应商及目录;Vision Router负责视觉能力编排、执行与诊断。只有解决真实兼容问题所需的代码或配置,才应由Vision Router长期维护。**
4
+
5
+ DSH管理用户供应商、模型、凭据、Host目录及输入模态权限;Vision Router的设置页经`connection.api.llm.models({})`读取相同目录,视觉模式用`modelDirectories.directoryFor(sessionId)`读取Host权威选择状态。Router继续管理视觉工具、像素处理、能力评估、执行、回退和诊断;不另造商用供应商注册表。Host声明的输入模态不能取代真实图片投递验证。
6
+
7
+ ## 私有视觉模型发现不是第二套供应商目录(#223、#225、#227、#230)
8
+
9
+ 原则中的“DSH负责目录”,指**DSH拥有供应商注册、已配置路由、全局模型目录及其最终权限**;不等于Vision Router只能展示静态DSH目录里当下已有的ID。历史需求已有真实证据:
10
+
11
+ - [PR #223](https://github.com/ysr666/dsh-vision-router/pull/223)把被误标仅文本的模型直连桥限制到DSH/pi-ai的**精确本地预线拒绝**,不会用网络、认证或其他失败当作绕过Host的理由。
12
+ - [PR #225](https://github.com/ysr666/dsh-vision-router/pull/225)针对DSH/pi-ai静态目录遗漏动态新型号,为**DSH已配置**的供应商端点增加独立的`/models`查询。结果只进入Vision Router自己的选择器,不写入DSH全局目录;单凭模型ID在`/models`出现不代表支持图片。
13
+ - [PR #227](https://github.com/ysr666/dsh-vision-router/pull/227)让用户已经保存的模型ID继续可见、可编辑;**仅保存历史不授权UNKNOWN_MODEL直连**。
14
+ - [PR #230](https://github.com/ysr666/dsh-vision-router/pull/230)来自官方BigModel端点`/models`漏列能真实调用的视觉型号。只对端点与协议完全匹配的官方路由添加少数视觉能力提示;缓存重启后仅可展示,必须重新验证当前路由才可授权执行。
15
+
16
+ 现有实现位于`src/lib/live-model-discovery.js`、`src/lib/vision-model-registry.js`、`src/lib/trusted-vision-hints.js`及相关Browser私有预加载层。它们承担的是**对用户已配置模型进行补充发现、显示来源并核验能力**,不是在DVR注册新供应商或替代DSH的全局模型目录。属于用户可用性与兼容层的有条件例外,**不能与静态商业厂商YAML一起删除**。
17
+
18
+ 未来如DSH原生提供同等的活模型发现,应逐条核对:当前支持的每个Host是否覆盖静态目录缺项、模型身份和图片输入真实性、缓存失效、已保存项显示、凭据权限、未知型号失败闭合及浏览器只在插件私域展示。所有这些条件满足后,再独立讨论退役此例外。
19
+
20
+ ## 逐项来源核查(清理前)
21
+
22
+ | 来源 | 当初的目的 | 本轮结论 |
23
+ | --- | --- | --- |
24
+ | [提交16e29d07](https://github.com/ysr666/dsh-vision-router/commit/16e29d07b943d2b2e1dfb615683ab07f24cc96af),2026-08-13(无关联PR) | 降低用户手动写`llm-pi-ai`配置的门槛,添加五份供应商YAML和免费模型调研。 | 退役五份静态示例;原始报告可通过Git历史追溯。 |
25
+ | [提交cf4eb6b3](https://github.com/ysr666/dsh-vision-router/commit/cf4eb6b35fe1005dcf9fd46f840a6688ef60372e) | `zai.yaml`改名为`zhipu.yaml`,避免自定义bigmodel.cn provider key与内置`zai`冲突。 | 不删除已有用户的手动配置,只退役仓库示例。 |
26
+ | [PR #89](https://github.com/ysr666/dsh-vision-router/pull/89),2026-08-16 | DSH Web自定义视觉模型未保存`image`能力声明,曾触发下拉过滤及难以理解的空列表。 | **保留通用图片能力修复指引**和实测提示,不延续过时的“全部隐藏”描述。 |
27
+ | [PR #676](https://github.com/ysr666/dsh-vision-router/pull/676),2026-10-09 | DSH 0.2.1-alpha.2变更Web信任初始化所有权,新增`presets/web-connection-ready/`私有运行时桥接。 | **不能删**,仍由`cordis.patch.yml`加载、`package.json.files`打包,必须保留Host跨代回归门。 |
28
+ | [PR #729](https://github.com/ysr666/dsh-vision-router/pull/729),2026-10-19 | 提交收费Atlas Cloud网关示例及文档;贡献者披露商业关联。 | 按同一职责原则关闭而未合并,不针对特定厂商区别对待。 |
29
+
30
+ ## 清理边界
31
+
32
+ 只删除仓库发布包中需人工复制的`dashscope.yaml`、`zhipu.yaml`、`siliconflow.yaml`、`openrouter.yaml`、`ovh.yaml`。已有用户的`settings.yaml`、凭据、模型注册一概不动。中英文README改为DSH原生模型配置路径;原动态价格清单仅由不可变历史快照承载。
33
+
34
+ **必须保留:** `presets/web-connection-ready/`、`cordis.patch.yml`引用、`package.json`中的`presets`打包项、`src/lib/core-primitives.js`运行时匿名OVH兜底;`src/lib/http-compat.js`的协议兼容预设及catalog corrections不能与手工厂商YAML混淆。后续清理每条真正运行时兼容规则前,也必须查Issue/PR、复现原因、受支持Host替代能力及负向测试。
35
+
36
+ ## 验收门
37
+
38
+ - `pnpm test`、`pnpm typecheck`、`pnpm build`及`pnpm pack`。tarball须含`presets/web-connection-ready/index.mjs`和`package.json`,不含五份厂商YAML。
39
+ - 原有Windows/macOS/Linux、Node22/24与支持窗口内的DSH稳定版/preview Host门不得回归。
40
+ - DSH模型目录选择、#89图片能力提示、真实识图校验、运行时OVH兜底与连接信任权限必须保持原状。
41
+ - 真正移除`web-connection-ready`或供应商协议兼容逻辑,另开PR证明上游问题已不再存在,并提供回滚策略。
@@ -0,0 +1,29 @@
1
+ # DeepSeek Harness 0.2.1-rc.1 next-channel compatibility qualification
2
+
3
+ - **Channel:** `next` / RC; not stable or alpha. The alpha.5 and historical 0.2.0-rc.2 lanes remain independent.
4
+ - **Upstream immutable tag / commit:** `dsh-v0.2.1-rc.1` / `1600d8a1e140dcde43a1a0941940a0480712c011`.
5
+ - **GitHub Release:** 2026-10-17 05:22:10 UTC (13:22:10 China time).
6
+ - **Baseline:** `dsh-v0.2.1-alpha.5` / `1517a4dbca0a2789ff1d41ba439600f8547d23fa`.
7
+ - **Source toolchain:** `pnpm@11.28.5` and Node 22.19.0 or 24.x per published upstream manifest.
8
+ - **Upstream delta:** four commits, including the 0.2.1-rc.1 release and vendor-release merges. Observed changed manifests advance the internal DSH release train and vendor libraries (Cordis 4.0.5, Schemastery 3.18.5, Cosmokit 1.8.6, etc.). Do not confuse a manifest-only change with proof that runtime composition cannot change; use real Host gates below.
9
+
10
+ ## Compatibility review and contracts
11
+
12
+ | Area | RC1 risk/contract | Verification |
13
+ | --- | --- | --- |
14
+ | Host and admission | Preserve published `engines.dsh` and legacy peer support range `>=0.1.5-rc.1 <0.2.0-0 \|\| >=0.2.0-rc.2 <0.3.0-0`. New RC1 must be admissible without changing the lower bound. | Exact DSH plugin compatibility evaluator, old Host matrix |
15
+ | Session | Existing producer-owned Session v4 and event ordering; no package-version substitution for durable Session checks. | Exact source contracts, Desktop Host, adversarial regressions |
16
+ | Settings | Preserve Host-owned Settings mount, save, reload, and readback. | Real DSH Web + Chromium lifecycle |
17
+ | Bundle | Cordis/vendor version upgrades could affect injection and recompose even when DVR code is unchanged. | Three consecutive bundle recomposes, original historical validation lane unchanged |
18
+ | Web/client | Model label slot, skill-cache invalidation and terminal inventory from alpha.5 must remain present. | Exact source assertions plus live cold Vision toggle and renderer |
19
+ | Model and attachments | Preserve Host-owned Sharp canonical dimensions, native-image noninterference, clipboard/mixed image-file handling and model selection. | Windows/macOS/Linux exact-source, real Chromium mixed attachments and Vision |
20
+ | Service injection | Preserve bounded webStartup compatibility overlay, module/connection webServer seams, and Desktop injection boundaries. | Real Desktop injection, web overlay contracts, multi-plugin ordering |
21
+
22
+ ## CI and evidence policy
23
+
24
+ - Dedicated `.github/workflows/dsh-021-rc1-validation.yml` runs on ordinary PR changes against the immutable upstream SHA, with the RC1 pnpm toolchain.
25
+ - Exact-source and Host-Sharp on Linux/macOS/Windows, native Windows Desktop Node 22/24, macOS Desktop, and Linux real DSH Web+Chromium are blocking evidence points.
26
+ - The existing stable 0.2.0-rc.2 and alpha.5 workflows remain intact and must not be replaced or mislabeled as RC1 coverage.
27
+ - Node 22/24 unit, package, security, adversarial, and contract regressions remain required on the PR's actual head. No workflow_dispatch substitute for PR CI.
28
+ - **Status:** creating the gate and the extra RC1 exact-source assertions is *not* a passing validation. Inspect the PR jobs and repair their actual root causes before marking the adapter qualified.
29
+ - No DVR npm package publication, GitHub release, support floor change, Host-global monkeypatch, or Copilot review requirement.
@@ -0,0 +1,24 @@
1
+ # DeepSeek Harness 0.2.1-rc.2 next-channel compatibility qualification
2
+
3
+ - **Channel:** `next` / RC; independent of stable and alpha. Do not conflate with historical DSH `0.2.0-rc.2`.
4
+ - **Upstream immutable release commit:** `687f282e8625c6b8d11ff58211a90524be2e4317` (`dsh-v0.2.1-rc.2`).
5
+ - **Released:** 2026-10-17 08:16:33 UTC (16:16:33 China Standard Time).
6
+ - **Previous qualified next baseline:** `dsh-v0.2.1-rc.1`, `1600d8a1e140dcde43a1a0941940a0480712c011`.
7
+ - **Known upstream changes to review:** new DeepSeek-V4.1-Flash-1017 model identifier; optional DeepSeek Search/Fetch API; Web service wiring, Settings namespaces and bundle composition. New functionality does not imply DVR runtime compatibility without independent Host and browser evidence.
8
+
9
+ ## Compatibility review
10
+
11
+ | Area | Primary RC2 concern | Evidence required |
12
+ | --- | --- | --- |
13
+ | Host and peer admission | Do not raise public minimum Host range (including legacy `>=0.1.5-rc.1 <0.2.0-0 \|\| >=0.2.0-rc.2 <0.3.0-0`) | Official Host peer evaluator and historical lanes |
14
+ | Session | Existing Session lifecycle, ownership, event ordering and cross-version persistence | Exact source contract, real Host and adversarial/contract regression |
15
+ | Settings | New Search/Fetch namespaces must not displace DVR Settings mount/save/reload/readback | Real DSH Web + Chromium lifecycle |
16
+ | Bundle and web/client | Search/Fetch module additions must coexist with DVR overlays and Vision slots | Three bundle recomposes, cold Vision toggle and client checks |
17
+ | Model and attachments | New Flash model label and attachment pathways must retain image handling | Host-Sharp, mixed attachments and native-image regression |
18
+ | Service injection | Search/Fetch injection must not interfere with DVR bounded overlay, webServer and Desktop injection | Host injection / multi-plugin ordering on actual RC2 |
19
+
20
+ ## Acceptance conditions
21
+
22
+ Create a dedicated `dsh-021-rc2-validation.yml` workflow pinned to the exact upstream SHA. Run it on ordinary `pull_request` CI, with Node 22/24, Linux/macOS/Windows exact-source and Host-Sharp, Windows/macOS Desktop injection/renderer, real DSH Web+Chromium cold Vision, mixed attachments, Settings lifecycle, and three bundle recomposes. Reuse existing exact-source validators, extending assertions only for genuinely new RC2 seams. Preserve all stable/RC1/alpha lanes.
23
+
24
+ **Qualification state:** Pending dedicated RC2 PR CI and real Host evidence. Earlier local upstream build/tests do not qualify DVR against RC2. If the workflow or integration tests reveal failures, repair the underlying cause, commit through the normal PR workflow, and rerun CI before merging. No automatic DVR npm publication or support floor change.
@@ -0,0 +1,29 @@
1
+ # DSH 0.2.1-rc.3 next-channel compatibility qualification
2
+
3
+ - **Channel:** next / RC only; not stable, and not alpha.
4
+ - **Exact upstream tag:** `dsh-v0.2.1-rc.3`.
5
+ - **Immutable upstream commit:** `1f81c047fc48fa190a683e469daa699857e9afe8`.
6
+ - **GitHub release:** 2026-10-23 15:26:39 UTC (2026-10-23 23:26:39 Asia/Shanghai).
7
+ - **Previous qualified next:** RC2 `687f282e8625c6b8d11ff58211a90524be2e4317`, covered by merged PR #724.
8
+ - **Baseline DVR:** latest `main` at branch creation (`6bce1d87bacb472b84e30b281ee573d9862d679e`).
9
+ - **Upstream compare:** https://github.com/deepseek-ai/deepseek-harness/compare/dsh-v0.2.1-rc.2...dsh-v0.2.1-rc.3
10
+
11
+ ## Upstream changes and potential compatibility impact
12
+
13
+ Six upstream commits: navigation-entry customization (including More menus and pinned launcher state), navigation/preset analytics, menu and tooltip fixes, official DeepSeek API-key model listing refresh, release metadata, and release merge. The published RC3 notes explicitly call out More menus, restoration of an unsent New Session draft, and API-key adapter model list parity with account login.
14
+
15
+ | Surface | RC3 review / regression focus |
16
+ | --- | --- |
17
+ | Host / peer admission | Pin exact source and run official Host evaluator. Do not change DVR `engines.dsh`, optional peer ranges, or the historical minimum supported Host. |
18
+ | Session | New Session now reuses an eligible blank session; verify Session identity, draft/attachment ownership, cold resume and lifecycle boundaries. |
19
+ | Settings | New entry pin persistence and provider model listing must not alter DVR Settings mount, save, reload or readback. |
20
+ | Bundle | `web-app/cordis.patch.yml` adds `ui-entry-customization`; verify DVR overlay ordering and three actual recompositions. |
21
+ | Web/client | New `sidebar.panellist.actions`, `conversation.view.actions`, and guide actions plus pinned state/menus; exercise real Chromium, Vision toggle and settings UI. |
22
+ | Model/attachments | API-key official `/models` discovery changes model catalog freshness; preserve explicit image-capability checks and mixed attachment routing, not model-name assumptions. |
23
+ | Service injection | New UI plugin and model-listing services must not interfere with existing DVR client inject, Web/connection overlay, Desktop, or Host-Sharp lifecycle. |
24
+
25
+ ## Qualification gates (not yet claimed passed)
26
+
27
+ The dedicated `.github/workflows/dsh-021-rc3-validation.yml` duplicates the proven RC2 matrix but pins RC3's **exact SHA** and retains RC2, alpha and stable lanes separately. It must execute on an ordinary PR, including Node 22/24, Linux/macOS/Windows exact-source and Host-Sharp, Windows Node 22/24 + macOS Desktop, real Web + Chromium cold Vision, mixed attachments, Settings mount/save/reload/readback, three bundle recomposes, source/peer/proxy contracts and existing adversarial/security regression suites.
28
+
29
+ **State:** Await final-head CI and actual Host/Chromium evidence. Any failure must be investigated and fixed at the root before merge. No Copilot review gate; no workflow_dispatch substitute; no automatic DVR release.