dsh-vision-router 3.0.3 → 3.0.5

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.
Files changed (35) hide show
  1. package/README.md +183 -162
  2. package/README.zh.md +179 -158
  3. package/cordis.patch.yml +14 -10
  4. package/docs/architecture/dsh-0.2.1-alpha.2-compat.md +41 -0
  5. package/docs/development/dsh-alpha3-compatibility.md +36 -0
  6. package/docs/development/dsh-alpha4-adaptation.md +12 -0
  7. package/docs/development/dsh-alpha4-validation-evidence.md +29 -0
  8. package/docs/development/dsh-alpha5-adaptation.md +31 -0
  9. package/docs/development/dsh-rc1-adaptation.md +29 -0
  10. package/docs/development/dsh-rc2-adaptation.md +24 -0
  11. package/docs/development/v305-real-scenario-acceptance.md +34 -0
  12. package/docs/development/web-live-reload.md +157 -0
  13. package/docs/releases/v3.0.4.md +18 -0
  14. package/docs/releases/v3.0.5.md +31 -0
  15. package/docs/remote-settings.md +4 -0
  16. package/docs/v2-capability-routing.md +25 -9
  17. package/lib/adapter-update-coalescer.js +41 -8
  18. package/lib/client-presentation-boundary-main.js +41 -7
  19. package/lib/client.js +27 -23
  20. package/lib/core-primitives.js +6 -2
  21. package/lib/http-compat.js +33 -2
  22. package/lib/maintenance-routes.js +7 -1
  23. package/lib/session-message-source-compat.js +13 -4
  24. package/lib/sharp-runtime.js +0 -2
  25. package/lib/vision-backend-runtime-policy.js +3 -3
  26. package/lib/vision-background-benchmark.js +33 -5
  27. package/lib/vision-capability-benchmark-service.js +61 -23
  28. package/lib/vision-evidence-guidance.js +7 -1
  29. package/lib/vision-exact-check-client.js +24 -6
  30. package/lib/vision-image-input-verdict.js +5 -3
  31. package/lib/vision-toggle-root-hardening.js +20 -3
  32. package/lib/web-capability-boundary.js +164 -31
  33. package/package.json +6 -4
  34. package/presets/web-connection-ready/index.mjs +48 -0
  35. package/presets/web-connection-ready/package.json +6 -0
package/README.zh.md CHANGED
@@ -9,139 +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/tag/v2.3.0"><img src="https://img.shields.io/badge/release-v2.3.0-5B4CF0?style=flat-square" alt="Release v2.3.0" /></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>
17
+ <p align="center"><sub>DeepGuard 徽章对应历史 v2.0.1 审计,不代表当前版本已通过同一审计。</sub></p>
36
18
 
37
19
  <p align="center"><a href="README.md">English</a> · 中文</p>
38
20
 
39
- <p align="center">💬 <strong>QQ 用户交流群:1105463028</strong></p>
40
-
41
21
  > [!CAUTION]
42
22
  > **默认配置会让数据出网。** 使用云端视觉模型时,Vision Router 会将图片(或由它裁剪出的局部)、识图提示词及相关请求元数据发送给对应供应商。新安装默认开启 OVHcloud 匿名视觉兜底,因此“免费”和“免 Key”不等于离线。涉密、涉案、内部或其他受限材料请勿使用云端链路。详见[数据流向与严格纯本地配置](#数据流向与严格纯本地配置)。
43
23
 
44
24
  > [!WARNING]
45
- > 📌 **公告(v3.0.3)**
46
- >
47
- > **v3.0.3:修正图片呈现与代理边界。** 恢复历史会话和空的 `vision_present` 结果不再抢走滚动位置,
48
- > 新生成的图片仍会在新版 phase 生命周期与受支持的 DSH 0.1.5 旧生命周期上正确聚焦;
49
- > cookie-domain 风格的 `.example.com` 现在与 `*.example.com` 遵守同一套代理主机规则;
50
- > DSH 0.1.7 精确浏览器 smoke 也重新跟随两个 presentation-boundary owner。CI Action 固定版本同步更新,
51
- > 运行时依赖和 Host 支持范围均不变。[查看完整更新 →](docs/releases/v3.0.3.md)
25
+ > **v3.0.5 修正版更新说明:** 修复识图后回复中断、可选依赖加载以及 OVH 请求体限制,并缓解模型目录刷新期间识图开关短暂失效的问题。参见[v3.0.5 更新说明](docs/releases/v3.0.5.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
+ [详细上手](#快速开始) · [功能亮点](#亮点) · [数据流向与纯本地配置](#数据流向与严格纯本地配置)
52
42
 
53
43
  <p align="center">
54
44
  <img src="assets/vision-demo.gif" width="640" alt="演示:粘贴图片,Agent 用 vision_ground / vision_crop / vision_pixel_diff 定位发送按钮并给出坐标" />
55
45
  </p>
56
46
 
47
+ ## 试试这些图片任务
48
+
49
+ - **看懂截图:**“这个报错弹窗是什么意思?把具体报错内容读出来。”
50
+ - **定位界面元素:**“截图里的保存按钮在哪里?告诉我它的位置。”
51
+ - **对照设计稿修改页面:**“我的页面和参考图还有哪些区别?下一步该改哪?”修改后还能用 `vision_pixel_diff` 量化差异。
52
+ - **阅读长截图:**“提取这张长截图里的关键信息,不清楚的局部再裁剪确认。”
53
+
54
+ 直接在平常的对话里提问即可:日常模型负责推理,按需调用视觉工具。[查看工具列表](#工具)或[配置自定义/本地视觉后端](#配置项)。
55
+
57
56
  ## 目录
58
57
 
59
- - [数据流向与严格纯本地配置](#数据流向与严格纯本地配置)
60
- - [为什么做这个](#为什么做这个)
61
- - [对比同类插件](#对比同类插件)
62
- - [设计来源](#设计来源)
63
- - [致谢](#致谢)
64
- - [快速开始](#快速开始)
65
- - [免费视觉 Key 渠道](#免费视觉-key-渠道)
58
+ - [试试这些图片任务](#试试这些图片任务)
66
59
  - [亮点](#亮点)
67
60
  - [工作原理](#工作原理)
68
61
  - [工具](#工具)
62
+ - [快速开始](#快速开始)
63
+ - [数据流向与严格纯本地配置](#数据流向与严格纯本地配置)
64
+ - [免费视觉 Key 渠道](#免费视觉-key-渠道)
65
+ - [为什么做这个](#为什么做这个)
66
+ - [对比同类插件](#对比同类插件)
69
67
  - [配置项](#配置项)
70
68
  - [安装与生命周期](#安装与生命周期)
71
69
  - [故障排查](#故障排查)
70
+ - [设计来源](#设计来源)
71
+ - [致谢](#致谢)
72
+ - [版本公告与社区链接](#版本公告与社区链接)
72
73
 
73
- ## 数据流向与严格纯本地配置
74
-
75
- Vision Router 在默认配置下不是完全离线工具。具体边界取决于操作和当前选择的模型:
76
-
77
- | 操作 | 数据去向 |
78
- |---|---|
79
- | 裁剪、像素对比、取色、SVG 矢量化、抠图、文件实体化、HTML 截图等本地像素工具 | 在 DSH 所在机器处理,这些操作不调用视觉模型。 |
80
- | 使用 Tesseract 的 `vision_ocr` | 在 DSH 所在机器处理。默认 `auto` 引擎在本地 OCR 不可用或结果为空时,可能回退到视觉模型。 |
81
- | 图片轮路由及 describe、detect、ground、视觉 OCR 等模型工具 | 图片或局部裁剪、提示词和相关上下文会发送给当前视觉供应商。 |
82
- | 内置免费兜底 | 以匿名方式(无 API Key)发往 OVHcloud AI Endpoints `oai.endpoints.kepler.ai.cloud.ovh.net`;服务仍会收到请求内容和源 IP 等网络元数据。 |
83
- | 用户配置的云模型 / HTTP 供应商 | 发送到对应配置端点,并受该供应商的保留与隐私条款约束。 |
84
- | 本地 Ollama / LM Studio | 图像像素发送到配置的本地端点;识图结果文本仍会回到当前聊天模型,而聊天模型自身可能仍在云端。 |
74
+ ## 亮点
85
75
 
86
- 若要阻止 **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 保持直连。
87
84
 
88
- ## 为什么做这个
85
+ ### 像素闭环实测
89
86
 
90
- 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**Host 规范化后的图像像素留在视觉模型侧**、把推理留在 DeepSeek 侧,并把“看图”变成一次**普通的工具调用**:
87
+ [![参考设计与 Agent 最终复刻,通过 vision_pixel_diff 实测最终差异为 2.54%。](assets/pixel-loop-zh.png)](assets/pixel-loop-zh.png)
91
88
 
92
- - **一条命令安装。** 包自带组合补丁(`dsh.bundle.patch`):`dsh plugin add` 自动完成插件行挂载、准入包装与附件限制放宽——不用手改任何文件。是否接管官方 DeepSeek 路由由「隐身模式」开关决定(默认关)。
93
- - **默认免费。** 视觉工具最终兜底为 5 个 OVHcloud 匿名视觉模型:免注册、免 Key,每 IP、每模型 2 次/分钟,独立限额理论合计约 10 次/分钟;用户自备视觉模型会优先调用。
94
- - **无 Python。** 整条管线——缩放、定位、裁剪、像素对比、取色、OCR、SVG 矢量化、抠图、HTML 截图——全部基于 sharp / potrace / tesseract / 系统 Chrome。
95
- - **可连续多步看图。** 图片轮 = 调用工具的文本轮:`vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → 修复 → 再截图,Agent 可以一直迭代到任务完成。
96
- - **DeepSeek 始终是大脑。** 文字轮在模型、成本、上下文上完全不动;视觉模型只当“眼睛”、按需调用,答案按图片内容缓存。
97
- - **界面无感。** 上传的图片在会话界面里照常显示为图片;指向视觉工具的改写只发生在模型输入层,从不写入会话日志。
89
+ <p align="center"><sub>点击图片可查看完整原图。</sub></p>
98
90
 
99
- ## 对比同类插件
91
+ Agent 仅根据参考图复刻 UI,再用 `vision_pixel_diff` 验证最终结果:**最终差异 2.54%**(32,939 / 1,296,000 个差异像素,threshold 16/channel)。
100
92
 
101
- **一句话讲清区别**:其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"(描述桥,有信息损耗);
102
- 本插件主打"**图片轮直接交给视觉模型看图像像素**"(路由桥,像素级),同时内置免 Key 免费模型兜底。
93
+ ## 工作原理
103
94
 
104
- > [!NOTE]
105
- > 在 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>
106
98
 
107
- | | 手动切换模型 | MCP 视觉桥 | 本插件 |
108
- |---|---|---|---|
109
- | 图像像素 | ✅ 可用(切换后) | ❌ 只有文字描述 | ✅ Host 规范化栅格,图片轮内 |
110
- | 自动化 | ❌ | ✅ | ✅ |
111
- | 日常模型不受影响 | ❌(整会话被换) | ✅ | ✅ |
112
- | 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
113
- | 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
114
- | 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
115
- | 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
99
+ 视觉模型**只当眼睛**,DeepSeek **始终是大脑**。图片轮永远不会被一次性视觉答案“劫持”——Agent 自己驱动工具,可以跨多个步骤持续对同一张图操作。
116
100
 
117
- **与现有 dsh 社区方案的差异**(均为优秀项目,各有侧重;描述以各家 README 2026-08 状态为准):
101
+ ## 工具
118
102
 
119
- | 项目 | 思路 | 本插件的差异 |
120
- |---|---|---|
121
- | [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述,描述作为会话消息交给 DeepSeek;默认 LLM7.io 匿名端点(OVHcloud 为无 Key 备选) | 描述桥方案;本插件提供"图像直看"路由,描述能力由 `vision_describe` 按需替代 |
122
- | [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由,请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案;本插件不包装 provider,通过 `agent/request` 瀑布改写路由 |
123
- | [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由:图片先经所选视觉模型转成描述,再交给 DeepSeek | 双模型桥思路;本插件在此基础上增加自动路由、降级链与工具 |
124
- | [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件;复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路;本插件自带供应商链,不依赖本机其他 CLI |
125
- | [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具(Q&A/OCR/像素校验/UI 还原),按需显式调用 | 工具集更全;本插件多出整轮自动路由与免 Key 免费兜底 |
126
- | [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:
127
104
 
128
- ## 设计来源
105
+ <p align="center">
106
+ <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个图像处理工具。" />
107
+ </p>
129
108
 
130
- 本项目的深度视觉工具层与 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 个工具。
131
110
 
132
- `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 |
133
128
 
134
- 感谢 Anionex 的先行工作以及整个 DSH 社区的探索。清晰的设计归因与独立迭代并不冲突;二者都有助于维护开放、协作、健康的 DSH 生态。
129
+ 图片格式按**魔数识别**,无扩展名的内容寻址附件文件也能直接用(不用再复制成 `.png`)。
135
130
 
136
- ## 致谢
131
+ **常用流程**
137
132
 
138
- 本插件借鉴了以上全部社区项目的思路,特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
139
- 对免注册免 Key 视觉端点的探索(LLM7.io 与 OVHcloud 匿名层)。感谢
140
- [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
141
- [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
142
- [modlens](https://github.com/liustack/modlens)、
143
- [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
144
- [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
+ ```
145
148
 
146
149
  ## 快速开始
147
150
 
@@ -203,7 +206,7 @@ pnpm dsh plugin --profile web add dsh-vision-router
203
206
 
204
207
  如果当前 session 已经包含图片,DSH 可能拒绝从识图 route 切回不接受图片的纯文本 route。此时 Vision Router 不绕过 Host 约束:会显示与原生模型选择器一致的临时错误提示,真实模型保持不变,`👁 识图 ✓` 也继续反映真实状态,可继续使用或稍后重试。
205
208
 
206
- 默认已经有内置 OVH 匿名视觉兜底,无需注册、无需 Key。**聊天页右下角只选择“脑子/会话模型”**;视觉模型不要在那里选。高级配置在 **设置 → Vision Router**:视觉后端链每一行都可以选择 **设置 → 模型** 中任意可调用的生成式用户模型。DSH 的图片能力声明现在只作提示:未声明图片能力、甚至被标成仅文本的模型也会列出并给出警告。运行时永远先通过该供应商已注册的 DSH adapter 实际调用,因此 WebSocket、RPC 和私有协议都保留原生传输;只有明确识别为 http(s) OpenAI Chat Completions 的渠道才可能进入 HTTP 直连兼容兜底。实际调用失败后自动尝试下一后端;一行都不填也可以,OVH 免费链会固定在最后兜底。插件内部的 `Vision HTTP` 只是传输实现,不是用户需要选择的模型组。
209
+ 默认已经有内置 OVH 匿名视觉兜底,无需注册、无需 Key。**聊天页右下角只选择“脑子/会话模型”**;视觉模型不要在那里选。高级配置在 **设置 → Vision Router**:视觉后端链每一行都可以选择 **设置 → 模型** 中任意可调用的生成式用户模型。DSH 的图片能力声明对**后端选择**只作提示:未声明图片能力或被标为仅文本的模型仍可选择,并会显示警告。但实际分发时,DSH 会把明确声明为仅文本模型的图片转换为文本占位符。此时 Vision Router 只有在确认渠道为 http(s) OpenAI Chat Completions 时才会通过直连兼容桥传送图片;否则会安全地判定该后端失败并尝试下一后端,避免把只收到 SHA 文本的回复误判为识图成功。WebSocket、RPC、Responses API、Anthropic 等协议在 Host 声明支持图片(或未声明输入模态)时仍走注册的原生 adapter。如果自定义模型确实支持图片但被 Host 标为仅文本,请优先在 DSH **设置 → 模型 → 对应供应商 → 自定义设置 → 模型选项 → 输入类型** 中勾选**图片**(Host 提供该选项时)。旧版 Host 没有此选项时,请在相应模型配置中声明正确字段:`llm-pi-ai` 使用 `input: [text, image]`,`llm-deepseek` 使用 `inputModalities: [text, image]`,然后重新加载配置;不支持图片的模型不要添加该声明。一行都不填也可以,OVH 免费链会固定在最后兜底。插件内部的 `Vision HTTP` 只是传输实现,不是用户需要选择的模型组。
207
210
 
208
211
  ### 实际效果
209
212
 
@@ -214,6 +217,21 @@ pnpm dsh plugin --profile web add dsh-vision-router
214
217
  <img src="assets/dsh-conversation-image-qa-result.png" width="49%" alt="Agent 对图片内容的结构化解读。" />
215
218
  </p>
216
219
 
220
+ ## 数据流向与严格纯本地配置
221
+
222
+ Vision Router 在默认配置下不是完全离线工具。具体边界取决于操作和当前选择的模型:
223
+
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 | 图像像素发送到配置的本地端点;识图结果文本仍会回到当前聊天模型,而聊天模型自身可能仍在云端。 |
232
+
233
+ 若要阻止 **Vision Router 本身**把图片发送给远程视觉端点,请开启 **设置 → Vision Router → 常规 → 仅本地视觉**。这是运行时策略,不会破坏性修改配置:已保存的云端识图行和 `freeFallback` 会保留,但开关开启期间无法执行;只有回环地址(`localhost`、`127.0.0.0/8`、`::1`)上的视觉端点可以运行,包括 Ollama、LM Studio 和自定义本机 HTTP 后端。若要求**整个工作流严格纯本地**,还必须同时使用本地聊天模型,因为识图结果文本仍会交给当前聊天模型。请在自己的环境中验证最终网络边界;Vision Router 无法把远程聊天模型、代理或 Host 集成变成本地服务。
234
+
217
235
  ## 免费视觉 Key 渠道
218
236
 
219
237
  内置 OVH 兜底是匿名设计,OVH 对匿名访问的限制是**每 IP、每模型 2 次/分钟**。觉得不够用时,下面这些渠道都有**免费且额度大得多的视觉模型**——全部免费注册,无需为免费档付费。免费政策轮换频繁,下表是 2026 年 8 月快照,依赖前请以各家控制台为准。
@@ -235,80 +253,45 @@ pnpm dsh plugin --profile web add dsh-vision-router
235
253
  > [!NOTE]
236
254
  > 免费政策随时可能调整——Cerebras 已在 2026 年 7 月取消免费档(改为一次性 $5 赠金),SambaNova 免费档收紧到 20 次/天,Hugging Face 只剩 $0.10/月。第三方“`:free` 中转”聚合站刻意不列入:轮换频繁、无 SLA,部分还存在违反上游条款的转售行为。
237
255
 
238
- ## 亮点
239
-
240
- - **能力感知 Auto 路由。** 想要确定性就继续按配置顺序;想自动选择时再显式开启 Auto,只在已配置模型和已有实测证据上调整优先级。不会通过模型名猜能力,单纯开启 Auto 也不会自动发起测评。
241
- - **可验证的模型测评。** 「测试识图」只向当前精确模型发一次请求;Quick / Full 分别测 OCR、通用理解,以及结构化、文档、定位等能力。后台能力数据是独立授权,并会给真实前台识图让路。
242
- - **原图像素,真实答案。** 视觉链按原始分辨率读图(仅为保护延迟/额度自动缩放);你的问题随图一起发送,答案围绕*你的问题*,而不是一段泛泛的描述。
243
- - **自动降级 + 分类报错。** 地区限制、ToS 风控、402 额度、429 限流、上下文超长、网络故障——链路逐供应商尝试,全部失败才报错并给出可操作的建议。遇到 429 会立即尝试下一后端,并按 Retry-After 开启冷却,不会在单次请求内睡眠等待。
244
- - **图片记忆。** 视觉答案按附件内容哈希缓存;后续文字轮用记录的描述替换历史图片(标注为不可信证据),DeepSeek 真正“记得”之前发过的图,且不重复消耗视觉调用。
245
- - **可验证的像素闭环。** 参照图 → `vision_html_screenshot` → `vision_pixel_diff`(差异率 + 红色热力图 + 最差区域排行)→ 修复 → 再对比,直到差异收敛。UI 还原从“目测”变成“实测”。
246
- - **稳定工具 schema。** 默认从会话开始就注册完整 14 个深看工具,避免图片轮中途扩展工具列表导致长上下文的 KV / prefix cache 失效。仍保留 `progressiveTools: true` 作为高级启动期 opt-in;开启后才使用 `vision_activate` 按需挂载。详见 [`docs/progressive-tools-cache.md`](docs/progressive-tools-cache.md)。
247
- - **选择性代理。** 只有配置的视觉供应商域名走本地代理;DeepSeek 保持直连。
248
-
249
- ### 像素闭环实测
250
-
251
- [![参考设计与 Agent 最终复刻,通过 vision_pixel_diff 实测最终差异为 2.54%。](assets/pixel-loop-zh.png)](assets/pixel-loop-zh.png)
252
-
253
- <p align="center"><sub>点击图片可查看完整原图。</sub></p>
254
-
255
- Agent 仅根据参考图复刻 UI,再用 `vision_pixel_diff` 验证最终结果:**最终差异 2.54%**(32,939 / 1,296,000 个差异像素,threshold 16/channel)。
256
+ ## 为什么做这个
256
257
 
257
- ## 工作原理
258
+ 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**Host 规范化后的图像像素留在视觉模型侧**、把推理留在 DeepSeek 侧,并把“看图”变成一次**普通的工具调用**:
258
259
 
259
- <p align="center">
260
- <img src="assets/how-it-works-zh.svg" width="100%" alt="DSH Vision Router 的工作原理:DeepSeek 作为大脑,视觉工具作为眼睛。" />
261
- </p>
260
+ - **一条命令安装。** 包自带组合补丁(`dsh.bundle.patch`):`dsh plugin add` 自动完成插件行挂载、准入包装与附件限制放宽——不用手改任何文件。是否接管官方 DeepSeek 路由由「隐身模式」开关决定(默认关)。
261
+ - **默认免费。** 视觉工具最终兜底为 4 个 OVHcloud 匿名视觉模型:免注册、免 Key,每 IP、每模型 2 次/分钟,独立限额理论合计约 8 次/分钟;用户自备视觉模型会优先调用。
262
+ - **无 Python。** 整条管线——缩放、定位、裁剪、像素对比、取色、OCR、SVG 矢量化、抠图、HTML 截图——全部基于 sharp / potrace / tesseract / 系统 Chrome。
263
+ - **可连续多步看图。** 图片轮 = 调用工具的文本轮:`vision_ground` → `vision_crop` → `vision_describe` → `vision_pixel_diff` → 修复 → 再截图,Agent 可以一直迭代到任务完成。
264
+ - **DeepSeek 始终是大脑。** 文字轮在模型、成本、上下文上完全不动;视觉模型只当“眼睛”、按需调用,答案按图片内容缓存。
265
+ - **界面无感。** 上传的图片在会话界面里照常显示为图片;指向视觉工具的改写只发生在模型输入层,从不写入会话日志。
262
266
 
263
- 视觉模型**只当眼睛**,DeepSeek **始终是大脑**。图片轮永远不会被一次性视觉答案“劫持”——Agent 自己驱动工具,可以跨多个步骤持续对同一张图操作。
267
+ ## 对比同类插件
264
268
 
265
- ## 工具
269
+ **一句话讲清区别**:其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"(描述桥,有信息损耗);
270
+ 本插件主打"**图片轮直接交给视觉模型看图像像素**"(路由桥,像素级),同时内置免 Key 免费模型兜底。
266
271
 
267
- 默认 `progressiveTools: false`:14 个深看工具从插件启动时就保持常驻,文本轮和图片轮都可直接调用。若你在 profile / composition 的 `cordis.patch.yml` 中显式开启 `progressiveTools: true`,才会恢复渐进模式:初始只暴露 `vision_activate`,首次需要时再挂载完整工具,并注册 `vision-tools` 技能。该开关是启动期配置,修改后需重启 DSH。全部工具基于 sharp / potrace / tesseract / 系统 Chrome——无 Python:
272
+ > [!NOTE]
273
+ > 在 DSH 0.1.2-alpha.1+ 上,附件仍由 Host 单一持有。Vision Router 消费的是 Host 持久化后的 canonical image:落在规范化限制内的单帧 8-bit sRGB/sRGBA 图片可以逐字节直通;需要旋转、色彩空间、元数据、动画或尺寸规范化的图片可能会被重新编码。因此像素工具承诺的是 Host canonical raster,而不是上传源文件编码字节逐字节不变。
268
274
 
269
- <p align="center">
270
- <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个图像处理工具。" />
271
- </p>
275
+ | | 手动切换模型 | MCP 视觉桥 | 本插件 |
276
+ |---|---|---|---|
277
+ | 图像像素 | ✅ 可用(切换后) | ❌ 只有文字描述 | ✅ Host 规范化栅格,图片轮内 |
278
+ | 自动化 | ❌ | ✅ | ✅ |
279
+ | 日常模型不受影响 | ❌(整会话被换) | ✅ | ✅ |
280
+ | 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
281
+ | 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
282
+ | 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
283
+ | 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
272
284
 
273
- 图中展示 11 个图像处理工具;另有 `vision_materialize`、负责持久展示图片的 `vision_present` 与可选 1+x 结构化首遍识别的 `vision_bootstrap`,默认深看工具集共 14 个。若启动时显式开启隐私敏感的 `vision_screenshot`,则额外增加为第 15 个工具。
285
+ **与现有 dsh 社区方案的差异**(均为优秀项目,各有侧重;描述以各家 README 2026-08 状态为准):
274
286
 
275
- | 工具 | 作用 | 产物 |
287
+ | 项目 | 思路 | 本插件的差异 |
276
288
  |---|---|---|
277
- | `vision_bootstrap` | 可选 1+x 结构化首遍视觉识别;先建立任务无关证据底图,再至少进行 1 次后续视觉调用 | — |
278
- | `vision_describe` | 看图问答 / 多图对比 / 结构化证据 JSON 模式(摘要 + 布局区域 + 实体清单 + 原文转写) | — |
279
- | `vision_materialize` | 把已授权附件复制到稳定的内容寻址工作区交接文件,并返回绝对路径和较短的工作区相对路径,供本地 OCR/解析器降级使用;不调用视觉模型或网络 | image copy |
280
- | `vision_ground` | 定位目标 → **原图像素框 x1/y1/x2/y2** | 标注 PNG(可选) |
281
- | `vision_detect` | 盘点某类元素(按钮/输入框/链接…)→ 编号清单 + 原图像素框 | 编号标注 PNG |
282
- | `vision_crop` | 按像素框裁剪放大 | PNG |
283
- | `vision_present` | 把生成或编辑后的本地图片发布为持久聊天附件,供用户查看 | 图片附件 |
284
- | `vision_pixel_diff` | 逐像素对比:差异率 + 最差 8×8 网格区域 | 红色热力图 PNG + JSON 报告 |
285
- | `vision_colors` | 主色提取(十六进制 + 占比) | — |
286
- | `vision_ocr` | 文字转写:默认引擎可配置为 `auto` / 本地 Tesseract / 视觉模型;单次显式 engine 仍优先 | — |
287
- | `vision_trace` | SVG 矢量化(potrace 分色;图标/logo) | SVG |
288
- | `vision_extract_foreground` | 边界洪泛抠图(纯色背景) | 透明 PNG |
289
- | `vision_html_screenshot` | 给本地 HTML 文件截图(无头系统 Chrome);`fullPage: true` 截整页并返回 `pageHeight` | PNG |
290
- | `vision_screenshot` | **默认关闭,必须显式开启隐私开关。** 截取 Windows 虚拟屏幕、macOS 主显示器或 Linux 根窗口;Windows 使用 PowerShell CopyFromScreen,macOS 使用 `screencapture`,Linux 需安装 ImageMagick `import` 或 `scrot`;`identify=true` 可按顺序尝试已启用的本地识别后端并返回路径+识别文本 | PNG / +描述文本 |
291
- | `vision_long_screenshot_ocr` | 长截图转写:重叠分片,tesseract 优先 / 视觉模型回退,按序拼接 Markdown | 分片 PNG + Markdown + manifest |
292
-
293
- 图片格式按**魔数识别**,无扩展名的内容寻址附件文件也能直接用(不用再复制成 `.png`)。
294
-
295
- **常用流程**
296
-
297
- ```text
298
- vision_ground image="ref.png" target="发送按钮"
299
- vision_detect image="page.png" target="输入框"
300
- vision_crop image="ref.png" region="1067,841,1108,881"
301
- vision_present path="rebuilt.png"
302
- vision_describe paths=["ref.png","impl.png"] question="列出两图的差异" json=true
303
- vision_pixel_diff original="ref.png" rebuilt="screenshot.png"
304
- vision_ocr image="screenshot.png"
305
- vision_colors image="ref.png" top=8
306
- vision_trace image="icon.png" steps=4
307
- vision_extract_foreground image="logo.png"
308
- vision_html_screenshot source="page.html" width=1200 height=720
309
- vision_html_screenshot source="page.html" width=1200 height=720 fullPage=true
310
- vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
311
- ```
289
+ | [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar) | 图片先经外部 VLM 做 OCR/描述,描述作为会话消息交给 DeepSeek;默认 LLM7.io 匿名端点(OVHcloud 为无 Key 备选) | 描述桥方案;本插件提供"图像直看"路由,描述能力由 `vision_describe` 按需替代 |
290
+ | [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy) | 包装 provider 路由,请求流里把图片转译成文本再交给 DeepSeek | 转译桥方案;本插件不包装 provider,通过 `agent/request` 瀑布改写路由 |
291
+ | [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider) | 注册 `DeepSeek + Vision` 组合路由:图片先经所选视觉模型转成描述,再交给 DeepSeek | 双模型桥思路;本插件在此基础上增加自动路由、降级链与工具 |
292
+ | [modlens](https://github.com/liustack/modlens) | 最早的 dsh 视觉插件;复用本机 Claude Code/Codex/OpenCode/Pi 等登录态作为视觉引擎 | 引擎复用思路;本插件自带供应商链,不依赖本机其他 CLI |
293
+ | [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit) | 10 个意图化视觉工具(Q&A/OCR/像素校验/UI 还原),按需显式调用 | 工具集更全;本插件多出整轮自动路由与免 Key 免费兜底 |
294
+ | [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) | `inspect_image` 工具 + `agent/pre-step` 瀑布图片桥(粘贴图入日志前转成工具提示) | 瀑布桥思路相近;本插件多出轮次路由、降级链、缓存与免费端点 |
312
295
 
313
296
  ## 供应商降级链
314
297
 
@@ -318,7 +301,7 @@ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
318
301
  2. **本地 Ollama(可选,默认关)**:`localOllama.enabled` 开启后,通过本机 Ollama 做免 Key、离线识别(例如 qwen2.5vl);
319
302
  3. **本地 LM Studio(可选,默认关)**:`localLmStudio.enabled` 排在 Ollama 之后,模型名必须填写 LM Studio Developer 页或 `/v1/models` 返回的真实标识;
320
303
  4. **高级自定义 HTTP 视觉端点**:旧配置/高级配置中的 `httpProviders` 排在本地后端之后;
321
- 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 次/分钟。
304
+ 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。想提额度?详见[免费视觉 Key 渠道](#免费视觉-key-渠道)——同一个端点挂免费 access key 后是 400 次/分钟。
322
305
 
323
306
  > [!IMPORTANT]
324
307
  > 这里的“视觉链”是 Vision Router 调用的**眼睛**:设置页里每一行只选一个用户视觉模型;聊天页右下角选择的是**脑子/会话模型**,两者完全分开。纯文本 DeepSeek / opencode 不会出现在视觉后端下拉里;内部 `Vision HTTP` 也不会再暴露给用户。
@@ -352,6 +335,8 @@ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
352
335
 
353
336
  Web profile 现在提供一级 **设置 → Vision Router** 页面。常规页把识图模型与 v2 路由授权放在一起;「识图策略 / 本地与设备 / 高级 / 诊断」分别承载工具行为、本地后端、敏感/性能设置和排障。
354
337
 
338
+ **反向代理部署须知:**遵循[DSH上游部署要求](https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/user/guide/public-deployments.md),代理转发时必须保留浏览器原始 `Host`,不能把远程访问改写成 `localhost` 后冒充“本机专属操作”。带常见代理转发标记的回环请求将失去Vision Router本机操作权限;但代理如果同时改写 `Host` 且抹掉全部来源信息,现有Host接口仍无法可靠辨别。参见[远程设置安全说明](docs/remote-settings.md)及[Issue #680](https://github.com/ysr666/dsh-vision-router/issues/680)。
339
+
355
340
  - **识图模型链**:`vision_describe` 等视觉工具真正调用的图片模型,内置免费链固定作为最终兜底;
356
341
  - **模型选择方式**:继续按配置顺序,或显式开启能力感知 Auto,并选择「综合 / 质量 / 速度 / 本地」偏好;
357
342
  - **后台补充能力数据**:`关闭 / 仅本地与免费 / 所有模型`,独立授权,不会因开启 Auto 自动开启;
@@ -611,6 +596,42 @@ npx dsh-vision-router doctor --profile web
611
596
  - 密钥不上线:`apiKeyEnv` 只指向 DSH 凭据引用,值按调用解析、永不写入日志。
612
597
  - 设置写入走设置服务(schema 校验 + 修订号检查)——过期或非法的保存会被拒绝,不会半截生效。
613
598
 
599
+ ## 设计来源
600
+
601
+ 本项目的深度视觉工具层与 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 等设计。
602
+
603
+ `dsh-vision-router` 中相关代码均为独立实现。在这些设计参考基础上,本项目独立发展了 turn-level/tools-first vision routing、DSH 准入/包装集成、多视觉后端与故障 fallback chain、内置免费视觉模型链、附件/图片记忆、缓存与相关运行时容错机制。
604
+
605
+ 感谢 Anionex 的先行工作以及整个 DSH 社区的探索。清晰的设计归因与独立迭代并不冲突;二者都有助于维护开放、协作、健康的 DSH 生态。
606
+
607
+ ## 致谢
608
+
609
+ 本插件借鉴了以上全部社区项目的思路,特别是 [dsh-vision-sidecar](https://github.com/121103qwq/dsh-vision-sidecar)
610
+ 对免注册免 Key 视觉端点的探索(LLM7.io 与 OVHcloud 匿名层)。感谢
611
+ [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)、
612
+ [dsh-vision-provider](https://github.com/libinyam/dsh-vision-provider)、
613
+ [modlens](https://github.com/liustack/modlens)、
614
+ [dsh-vision-toolkit](https://github.com/Anionex/dsh-vision-toolkit)、
615
+ [dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) 作者们的探索。
616
+
617
+ ## 版本公告与社区链接
618
+
619
+ 版本更新详情:[v3.0.5 更新说明](docs/releases/v3.0.5.md)。正式可安装版本请以 GitHub Releases 或 npm 为准。
620
+
621
+ <p align="center">
622
+ <sub>生态收录:</sub>
623
+ <a href="https://dshplugin.app/plugins/dsh-vision-router">DSHPlugin.app</a> ·
624
+ <a href="https://github.com/diegosouzapw/awesome-omni-dsh-plugins">Awesome Omni DSH Plugins</a> ·
625
+ <a href="https://dshpluginhub.ai/plugins/dsh-vision-router">dshpluginhub.ai</a> ·
626
+ <a href="https://www.dsh.plus/zh/plugins/dsh-vision-router/">dsh.plus</a> ·
627
+ <a href="https://dshplugins.ai/">dshplugins.ai</a> ·
628
+ <a href="https://dshmarket.com/p/ysr666/dsh-vision-router/">dsh-market</a>
629
+ </p>
630
+
631
+ <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>
632
+
633
+ <p align="center">💬 <strong>QQ 用户交流群:1105463028</strong></p>
634
+
614
635
  ## License
615
636
 
616
637
  [MIT](LICENSE)
package/cordis.patch.yml CHANGED
@@ -19,25 +19,29 @@
19
19
  name: '@deepseek-ai/dsh-client-modules'
20
20
  inject: [webServer]
21
21
 
22
- # DSH rc.6 至 0.1.5-rc.2 的 Web bundle 里,Connection provider row 只声明
23
- # webRuntime,但 HostConnectionService.rpc/fetch 的 accessor 会把调用 owner
24
- # 追踪回这个 provider fiber;rpc.handle() 最终又通过 owner.webServer.register()
25
- # 挂载路由。因此仅在 DVR 的调用 child fiber 注入 webServer 仍不足以覆盖
26
- # Cordis Service shadow 语义(issue #478 / Desktop 2.0.9 可稳定复现)。
22
+ # DSH 0.1.x / 0.2.0-rc.2 Connection 的 Host owner 必须注入 webServer
23
+ # (issue #478),但 0.2.1-alpha.2 已移除 webRuntime、改为 webStartup。
24
+ # 不要静态引用任一代独有的 webRuntime:它会使新 Host 必需服务永远待定。
27
25
  #
28
- # 保留官方既有 webRuntime 依赖,并让 Connection provider 本身同时等待
29
- # webServer。这样不改 connection config / trustedHosts,不复制 RPC 协议或鉴权,
30
- # 也不改变非 Web surface。exact-source contract 会监控上游 row;官方一旦
31
- # 自己拥有 webServer,此 shim 必须随支持窗口审计退休,避免覆盖未来新增依赖。
26
+ # 本层统一让 Connection 在 webServer、webStartup 及 DVR 私有 ready gate
27
+ # 均就绪后启动;ready gate 在旧 Host 等官方 webRuntime(含 bind-derived
28
+ # LAN authorities),在新 Host 直接读取官方 webStartup.trustedHosts。
29
+ # trustedHosts 只转交 Host 授权列表,不自行扩大、合并或猜测网络信任;
30
+ # Cookie、/api 和 RPC 仍归官方 Connection 所有。Host 新增配置项时,
31
+ # exact-source contract 必须拒绝未经审查的整段 config 覆盖。
32
32
  - id: connection
33
33
  name: '@deepseek-ai/dsh-client-connection'
34
- inject: [webRuntime, webServer]
34
+ inject: [webStartup, webServer, visionRouterWebConnectionReady]
35
+ config:
36
+ trustedHosts: !!js ctx.visionRouterWebConnectionReady.trustedHosts
35
37
 
36
38
  # 挂载插件行。默认保持完整视觉工具表常驻(issue #81):虽然渐进挂载可以
37
39
  # 少发一小段工具 schema,但图片轮首次扩展工具列表会改变请求前缀,可能让
38
40
  # 长会话的 provider KV/prefix cache 整体失效。高级用户仍可在 profile /
39
41
  # composition 补丁中显式把 progressiveTools 改回 true(启动期配置)。
40
42
  - insert:
43
+ - id: vision-router-web-connection-ready
44
+ name: './presets/web-connection-ready/index.mjs'
41
45
  - id: vision-router
42
46
  name: dsh-vision-router
43
47
  config:
@@ -0,0 +1,41 @@
1
+ # DSH 0.2.1-alpha.2 compatibility audit (2026-10-09)
2
+
3
+ ## Identity and scope
4
+
5
+ - Upstream **tag**: `dsh-v0.2.1-alpha.2`.
6
+ - Annotated tag object: `6851e496285b2c9670066fdd142e7e46da586649`; peeled **commit**: `d743267388641bc76f17c45ce8b4c231aed1d32c`.
7
+ - Previous reviewed alpha: `dsh-v0.2.1-alpha.1@5badb15009ae1756c3afe0ae0cef1faafc290ccc` (PR #645).
8
+ - The upstream tag exists, but its GitHub Release and npm alpha dist-tag were **not confirmed published** when this work began. Treat exact source as the test target, not floating npm resolution.
9
+ - Keep DVR's existing 0.1.x minimum, current 0.2.0-rc.2 support evidence, 0.2.x peer bounds, and package version unchanged.
10
+
11
+ ## Changes requiring a real Host gate
12
+
13
+ 1. **Build tooling**: DSH root `packageManager` changed from `pnpm@11.7.0` to `pnpm@11.28.5`. DVR remains pinned to its own package manager. Explicitly validate the upstream manifest and execute Host builds with the new manager; do not rewrite DVR's published package requirements.
14
+ 2. **Settings/client**: the Host reorganized plugin settings and its experimental catalog. Verify plugin settings mount, save, refresh, and readback in a real Chromium browser; do not infer support from source-level slot presence.
15
+ 3. **Web transport**: WebServer gained native TLS and concrete bind-address handling; Desktop Host now constructs URLs using `webServer.protocol` and may request OS-assigned ports. Verify authenticated Host/plugin routes, proxy authority, and injected Desktop client. Existing plaintext smoke does not establish support for every custom TLS topology.
16
+ 4. **LLM/model routing**: Host `prepareCall` supports a third `configure` callback and revised call-control binding; model visibility is also changing. Verify the registered adapter, image input and fallback paths. Existing DVR use of `prepareCall(config, signal)` remains positional compatibility pending executable checks.
17
+ 5. **Session/attachments**: Session schema/version compatibility and plugin record behavior changed. Keep source admission, durable image ownership, cold-restart, and mixed-attachment tests.
18
+ 6. **Bundle lifecycle**: Host package and dependency mappings continue changing. Verify cold startup, browser injection, multi-plugin ordering, and recompose through real DSH rather than mocks.
19
+
20
+ ## Acceptance gate
21
+
22
+ The existing `.github/workflows/dsh-alpha-settings-host-gate.yml` performs:
23
+ - immutable alpha source contract and Host-owned Sharp on Linux/macOS/Windows;
24
+ - official Host peer admission and proxy egress;
25
+ - macOS Desktop renderer;
26
+ - Windows Desktop auth on Node 22 and Node 24, plus renderer/multi-plugin adversaries;
27
+ - real Web + Chromium cold Vision, Settings mount/save/reload/readback, mixed attachments, and bundle recomposition.
28
+
29
+ The pin is intentionally **not** a blanket support declaration: a PR with pending/failed gates does not authorize saying alpha.2 is validated. No release, tag, dependency bump, production workaround, or merge is part of this audit PR. Only add a runtime workaround after reproducing a genuine interface regression.
30
+
31
+ ## Observed blockers (2026-10-09, exact-source gate)
32
+
33
+ - **P1 / real compatibility break**: the `connection` row fails to activate under alpha.2 (`missing webRuntime`). Alpha.2 replaces its upstream `inject: [webRuntime]` with `inject: [webStartup]`, while DVR still overlays `inject: [webRuntime, webServer]`. Older supported Hosts still use `webRuntime` and materialize extra LAN trust information there. A global rename does not preserve this old-Host contract. The PR **must remain Draft and unmerged** until a version-aware solution passes both old and new real Host gates.
34
+ - **Desktop CI fixture / independent**: Windows Node 22/24 originally failed required `desktop-product-telemetry` validation because the isolated test runner omitted Host-owned `DSH_CLIENT_VERSION`. Set that environment value to the exact Desktop release version in the fixture, retaining normal required-plugin validation and restoring the previous environment afterward. This change does not repair the Connection incompatibility.
35
+ - The ordinary CI, security, architecture, native cold-resume, and exact old-Host checks passed on the earlier head; they are **not** evidence that alpha.2 real browser/desktop support has passed. The alpha2 end-to-end test must be rerun and fully green before merging.
36
+
37
+ ## Proposed corrective architecture (still requires green real-Host CI)
38
+
39
+ The compatibility patch no longer installs an obsolete `webRuntime` dependency into the alpha.2 Connection row. It instead injects `webStartup`, `webServer` and a private readiness service. A legacy Host's native `webRuntime` is awaited before capturing its complete bind-derived LAN plus declared trust list; alpha.2 captures only native `webStartup.trustedHosts`. Both are detached, frozen and validated; Host Connection still owns every authentication and RPC action. Unexpected protocol, trust-list and upstream Connection-config drift fail closed.
40
+
41
+ The sidecar must live under an independent private nested package root, `presets/web-connection-ready/package.json`, with a different package name and **no** `dsh.client` declaration. DSH 0.1.7 client-modules rejects two active Loader specifiers that resolve into the **same** client package, even when the second specifier only supplies a host service. A separate package identity prevents this duplicate-source startup failure without creating another browser client or adding an external runtime dependency. Both the older and the alpha.2 real-Host gates remain mandatory before merge.
@@ -0,0 +1,36 @@
1
+ # DSH 0.2.1-alpha.3 compatibility audit
2
+
3
+ **Channel:** alpha/pre-release, not stable or next/rc. npm `latest` and `next` are still `0.2.0-rc.2`; npm `alpha` is `0.2.1-alpha.3`.
4
+
5
+ **Immutable source:** `dsh-v0.2.1-alpha.3` → `2fbf4359b82fb94c03dcce0b831660d87f12ea5c`. Compared against alpha.2 `d743267388641bc76f17c45ce8b4c231aed1d32c`. npm publication: 2026-10-14 12:35:33 UTC; GitHub release: 2026-10-14 13:32:15 UTC. Upstream uses `pnpm@11.28.5`.
6
+
7
+ ## Compatibility review
8
+
9
+ - **Host:** WebServer now exposes `getOrigin()` and makes `port` explicitly optional before listening. DVR does not directly depend on an early `webServer.port` read. The existing named-route registration/cleanup contract remains in place.
10
+ - **LLM / model / image:** `LlmRuntime.imageRequestTarget()` newly calls the registered adapter's method without optional chaining. DVR's plain adapter objects do not inherit the new `LlmAdapter` default. The compatibility boundary therefore supplies the upstream normalized-image identity target (`width`, `height`, `maxBytes`) only for DVR-owned adapters on Hosts exposing that method. Explicit adapter implementations take precedence; frozen adapters use a scoped proxy. This is a real root-level runtime contract repair.
11
+ - **Attachment:** The canonical image admission and normalization policy is still exercised against the exact Host's Sharp pipeline. No change to DVR's 20 MiB / 100 MP / 10,000 px policy.
12
+ - **Session:** Upstream adds resource identity to session remote metadata and changes session-controller and chat projection code. The session event and persistence boundaries remain subject to exact-source and real-browser gates.
13
+ - **Settings:** Credential precedence and Settings navigation changed. Newer Web shells expose Settings through the Account menu rather than a top-level Settings button; browser acceptance must follow the actual shell. Settings mount/save/reload/readback remains a mandatory gate.
14
+ - **Bundle/HMR:** Source changes in `app-boot`, `hmr` and `web-app` require bundle recompose verification. The exact macOS run completed three recomposes with stable DVR routes.
15
+ - **Web/client/Connection:** New connect/peer handshake and browser-auth paths require authenticated Desktop and Chromium tests. No unscoped Host-wide patch is introduced.
16
+ - **Service injection:** Exact alpha.3 still uses `webStartup` for Connection readiness. The existing DVR overlay remains required; do not remove it or raise the minimum public Host support.
17
+
18
+ ## Verified locally (not a substitute for CI)
19
+
20
+ - macOS Node 24 exact-source/Host-Sharp, Web Connection, peer admission and proxy egress: PASS.
21
+ - DVR local tests: 1,770 + 28 + 41 passing; two platform-limited skips; zero failures.
22
+ - macOS upstream full build: nine of nine gates PASS.
23
+ - macOS Desktop renderer: functional Vision turn and Settings save/reload PASS.
24
+ - macOS Desktop authenticated Host: token-to-cookie 303, authenticated index 200, missing API 404, DVR RPC 200.
25
+ - macOS bundle recompose: three passes, route stable.
26
+ - Windows Node 24 exact-source/Host-Sharp and upstream build: PASS.
27
+ - macOS Web Settings browser lifecycle: PASS after locally adapting the acceptance selector to the Account menu. The browser acceptance helper now supports both the legacy Settings button and the newer Account-menu Settings entry, without changing shipped product behavior.
28
+ - macOS cold Vision and mixed-attachment Web smoke could not automate the native directory picker; Linux Chromium remains the authoritative headless gate.
29
+
30
+ ## Release/merge hold
31
+
32
+ The exact alpha.3 CI pin and repairs are reviewed through [PR #710](https://github.com/ysr666/dsh-vision-router/pull/710). Merge only after the PR cross-platform Linux/macOS/Windows exact-source/Host-Sharp, Windows Node 22/24, real Web+Chromium lifecycle, and related contract/adversarial gates pass on the final head. This compatibility PR does not authorize publishing. Keep the public minimum Host range and stable/next verification baselines unchanged.
33
+
34
+ ## Windows CRLF regression (local follow-up)
35
+
36
+ On a real Windows Node 24 checkout with `core.autocrlf=true`, the pre-existing root-hardening test failed because exact client-source seam replacements assumed LF template literals. A focused source change now matches the same owned seam under CRLF without normalizing unrelated HTML or changing the Host; the original 9-test Windows root-hardening suite passes after rebuilding package artifacts. A new CRLF-specific regression also passes on macOS. Full Windows and Linux CI acceptance is still required before merging.
@@ -0,0 +1,12 @@
1
+ # DSH 0.2.1-alpha.4 adaptation
2
+
3
+ Channel: alpha/pre-release (not stable or next).
4
+ Upstream tag: `dsh-v0.2.1-alpha.4`.
5
+ Exact upstream commit: `86a402200d95fecef4529d969836f1fe13c6cb0d`.
6
+ Published to npm: 2026-10-15 13:08:08 UTC.
7
+ GitHub release: 2026-10-15 13:40:02 UTC.
8
+ Baseline: alpha.3 `2fbf4359b82fb94c03dcce0b831660d87f12ea5c`.
9
+
10
+ Upstream changes include model reasoning levels, custom plugin index sources, `engines.dsh`-first plugin admission, Web/client release-change and HMR handling, command editor fixes, and developer tools UI. Keep the 0.1.5-rc.1 minimum and 0.2.0-rc.2 stable/next evidence unchanged. No automatic release.
11
+
12
+ Technical gates pending.