dsh-vision-router 3.0.4 → 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.
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.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
+ [详细上手](#快速开始) · [功能亮点](#亮点) · [数据流向与纯本地配置](#数据流向与严格纯本地配置)
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
+ - [免费视觉 Key 渠道](#免费视觉-key-渠道)
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,6 +217,21 @@ 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
 
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
+
218
235
  ## 免费视觉 Key 渠道
219
236
 
220
237
  内置 OVH 兜底是匿名设计,OVH 对匿名访问的限制是**每 IP、每模型 2 次/分钟**。觉得不够用时,下面这些渠道都有**免费且额度大得多的视觉模型**——全部免费注册,无需为免费档付费。免费政策轮换频繁,下表是 2026 年 8 月快照,依赖前请以各家控制台为准。
@@ -236,80 +253,45 @@ pnpm dsh plugin --profile web add dsh-vision-router
236
253
  > [!NOTE]
237
254
  > 免费政策随时可能调整——Cerebras 已在 2026 年 7 月取消免费档(改为一次性 $5 赠金),SambaNova 免费档收紧到 20 次/天,Hugging Face 只剩 $0.10/月。第三方“`:free` 中转”聚合站刻意不列入:轮换频繁、无 SLA,部分还存在违反上游条款的转售行为。
238
255
 
239
- ## 亮点
240
-
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 保持直连。
249
-
250
- ### 像素闭环实测
251
-
252
- [![参考设计与 Agent 最终复刻,通过 vision_pixel_diff 实测最终差异为 2.54%。](assets/pixel-loop-zh.png)](assets/pixel-loop-zh.png)
253
-
254
- <p align="center"><sub>点击图片可查看完整原图。</sub></p>
255
-
256
- Agent 仅根据参考图复刻 UI,再用 `vision_pixel_diff` 验证最终结果:**最终差异 2.54%**(32,939 / 1,296,000 个差异像素,threshold 16/channel)。
256
+ ## 为什么做这个
257
257
 
258
- ## 工作原理
258
+ 大多数 DSH 视觉插件把图片“翻译”成一段文字描述再喂给 DeepSeek——有损、一次性、看不见像素。本插件把**Host 规范化后的图像像素留在视觉模型侧**、把推理留在 DeepSeek 侧,并把“看图”变成一次**普通的工具调用**:
259
259
 
260
- <p align="center">
261
- <img src="assets/how-it-works-zh.svg" width="100%" alt="DSH Vision Router 的工作原理:DeepSeek 作为大脑,视觉工具作为眼睛。" />
262
- </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
+ - **界面无感。** 上传的图片在会话界面里照常显示为图片;指向视觉工具的改写只发生在模型输入层,从不写入会话日志。
263
266
 
264
- 视觉模型**只当眼睛**,DeepSeek **始终是大脑**。图片轮永远不会被一次性视觉答案“劫持”——Agent 自己驱动工具,可以跨多个步骤持续对同一张图操作。
267
+ ## 对比同类插件
265
268
 
266
- ## 工具
269
+ **一句话讲清区别**:其他 dsh 视觉插件大多"把图片转成文字描述再喂给 DeepSeek"(描述桥,有信息损耗);
270
+ 本插件主打"**图片轮直接交给视觉模型看图像像素**"(路由桥,像素级),同时内置免 Key 免费模型兜底。
267
271
 
268
- 默认 `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,而不是上传源文件编码字节逐字节不变。
269
274
 
270
- <p align="center">
271
- <img src="assets/vision-tools-zh.svg" width="100%" alt="DSH Vision Router 的 11 个图像处理工具。" />
272
- </p>
275
+ | | 手动切换模型 | MCP 视觉桥 | 本插件 |
276
+ |---|---|---|---|
277
+ | 图像像素 | ✅ 可用(切换后) | ❌ 只有文字描述 | ✅ Host 规范化栅格,图片轮内 |
278
+ | 自动化 | ❌ | ✅ | ✅ |
279
+ | 日常模型不受影响 | ❌(整会话被换) | ✅ | ✅ |
280
+ | 供应商失败恢复 | ❌ | ❌ | ✅ 降级链 |
281
+ | 可复用的结构化查询 | — | 部分 | ✅ JSON 模式 + 缓存 |
282
+ | 免费开箱即用 | ❌ | ❌ | ✅ 内置免 Key 免费端点 |
283
+ | 贴合 dsh 组合体系 | — | 外部服务器 | ✅ 一行插件行 |
273
284
 
274
- 图中展示 11 个图像处理工具;另有 `vision_materialize`、负责持久展示图片的 `vision_present` 与可选 1+x 结构化首遍识别的 `vision_bootstrap`,默认深看工具集共 14 个。若启动时显式开启隐私敏感的 `vision_screenshot`,则额外增加为第 15 个工具。
285
+ **与现有 dsh 社区方案的差异**(均为优秀项目,各有侧重;描述以各家 README 2026-08 状态为准):
275
286
 
276
- | 工具 | 作用 | 产物 |
287
+ | 项目 | 思路 | 本插件的差异 |
277
288
  |---|---|---|
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
- ```
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` 瀑布图片桥(粘贴图入日志前转成工具提示) | 瀑布桥思路相近;本插件多出轮次路由、降级链、缓存与免费端点 |
313
295
 
314
296
  ## 供应商降级链
315
297
 
@@ -319,7 +301,7 @@ vision_long_screenshot_ocr image="chat-log.png" chunkHeight=1200 overlap=120
319
301
  2. **本地 Ollama(可选,默认关)**:`localOllama.enabled` 开启后,通过本机 Ollama 做免 Key、离线识别(例如 qwen2.5vl);
320
302
  3. **本地 LM Studio(可选,默认关)**:`localLmStudio.enabled` 排在 Ollama 之后,模型名必须填写 LM Studio Developer 页或 `/v1/models` 返回的真实标识;
321
303
  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 次/分钟。
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 次/分钟。
323
305
 
324
306
  > [!IMPORTANT]
325
307
  > 这里的“视觉链”是 Vision Router 调用的**眼睛**:设置页里每一行只选一个用户视觉模型;聊天页右下角选择的是**脑子/会话模型**,两者完全分开。纯文本 DeepSeek / opencode 不会出现在视觉后端下拉里;内部 `Vision HTTP` 也不会再暴露给用户。
@@ -614,6 +596,42 @@ npx dsh-vision-router doctor --profile web
614
596
  - 密钥不上线:`apiKeyEnv` 只指向 DSH 凭据引用,值按调用解析、永不写入日志。
615
597
  - 设置写入走设置服务(schema 校验 + 修订号检查)——过期或非法的保存会被拒绝,不会半截生效。
616
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
+
617
635
  ## License
618
636
 
619
637
  [MIT](LICENSE)
@@ -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,34 @@
1
+ # v3.0.5 release-candidate acceptance record
2
+
3
+ Release candidate must be tested on the final PR head, then on the exact main SHA before publishing. Evidence below refers to the merged change PRs; it is not a claim that the future v3.0.5 package has already been installed by a user.
4
+
5
+ | Scenario | Evidence | Scope and verdict |
6
+ | --- | --- | --- |
7
+ | `vision_describe` succeeds and assistant visibly answers (#727) | #731 23/23, #733 22/22, trusted combined #732 23/23 | Actual Desktop automated PNG upload → vision tool execution → final visible assistant reply; canonical tool-result and Session V3/V4 notice attribution preserved. **NOT** a separately installed/published 3.0.5 artifact |
8
+ | Contributor attribution of #728 | Main merge `0fc51c3` / #733; original commit `14c67c7` | Git ancestor/merge-base verified; original GitHub #728 recognized as merged, no squashed/copied authorship |
9
+ | Latest DSH Alpha JSONL CI loader | #730 (Node 22/24 real published-alpha lifecycle) | Canary runner/export compatibility only; no production transport, minimum Host or settings change |
10
+ | Optional peers missing at activation | #722, CI run 39019198833 | Passed isolated actual Node ESM entry-load probe and negative control; not a manual end-user Desktop install |
11
+ | DSH 0.2.1-rc.1 real Host/Web+Chromium | #721, run 39017893115; #723, run 39020741495 | Pinned source, Vision cold toggle, image+text, Settings save/reload/readback, bundle recomposes |
12
+ | DSH 0.2.0-rc.2 compatibility | #723, run 39020741454 | Pinned original Host and Desktop/Chromium cross-platform gates |
13
+ | DSH alpha.5 and legacy 0.1.7 | #723, alpha Settings Host and 0.1.7 real Host smoke | Tested against published pinned source; older support window remains unchanged |
14
+ | Node 22 and 24, packed API | #723, CI run 39020741423 | Passed both Node versions, packed public API and Ubuntu/macOS/Windows Host-Sharp |
15
+ | Official OVH 10 MB JSON request boundary | #723, tests/http-compat.test.js | Passed mocked negative and positive wires; **not** an online request to OVH |
16
+ | billion-context coexistence | Issue #704 | **NOT VERIFIED** in a pinned dual-real-plugin runtime; reporter must identify which package/version |
17
+ | Windows native-disabled click suppression | #735 / Issue #684 closed | **MITIGATED:** bounded cached-pair actionability during catalog loading, with Host authority intact; not a blanket guarantee against all intermittent failures |
18
+ | Windows delivered-click Host RPC failure | Issue #738 / diagnostics #737 | **UNRESOLVED:** a real 0.1.7 Windows Node24 run recorded `gateway/internal` after both clicks arrived. #737 adds only safe error-origin telemetry, with independent exact real-Host CI 6/6 alpha, 5/5 legacy, 7/7 rc.2 |
19
+ | Multi-provider HTTP 400 | Issue #716 | **NOT REPRODUCED**, needs redacted response body; do not claim success |
20
+
21
+ ## Acceptance matrix for a final install / upgrade
22
+
23
+ For the final v3.0.5 candidate, record exact OS, Node, DSH, DVR package and git SHA for every row. Protect API keys, image contents and personal profile paths in shared logs.
24
+
25
+ 1. **Clean install (isolated profile):** install the actual packed v3.0.5 tarball through the supported DSH plugin mechanism. Ensure the two optional DSH peer modules can be absent; restart the Desktop, confirm Host Connection and Vision settings mount and that no ERR_MODULE_NOT_FOUND occurs.
26
+ 2. **Upgrade from v3.0.4:** preserve profile Settings and Session data, change only the plugin package, restart and verify the displayed version and unchanged stored values. Do not delete a live package.json.lock.
27
+ 3. **Cold Web + Desktop:** check Vision OFF by default, toggle OFF to ON to OFF once, paste a small PNG alongside text, run a vision tool, open Settings, save/reload/read back and test a second window. Capture button pointer traces if OFF fails; do not simulate retries.
28
+ 4. **Payload boundary:** for the exact official OVH HTTPS model, a small PNG should reach the selected mocked or test endpoint unchanged. Oversized aggregate JSON should stop locally with INVALID_REQUEST, no outbound call, and no image content in diagnostics. A non-OVH provider must not inherit OVH's size limit.
29
+ 5. **Privacy and ecosystem:** local-only mode must not call an external vision provider; verify remote text model caveat. Co-install with either billion-context package only when its exact package/version and user-reported failure are known; check both plugin load orders and first failure.
30
+ 6. **Release supply chain:** pnpm frozen install, reproducible build, source-artifact map, Node 22/24 tests, packed public API, Host support contract and npm version uniqueness must all pass on exact final main commit. Release workflow verifies one tarball, provenance, registry hash and immutable GitHub assets.
31
+
32
+ ## Release decision
33
+
34
+ Do not label any unexecuted row green. GitHub Actions real Host + Chromium gates are automated integration tests, **not** a manually observed installation on the user's computer. Release notes must explicitly state that #738 and #716 remain open, and must not turn #684's bounded mitigation or #704's closed disposition into a claim of fully reproduced root-cause repair. The manual trusted release workflow remains an independent action after this candidate PR is accepted.
@@ -0,0 +1,31 @@
1
+ # v3.0.5 release candidate
2
+
3
+ This is a corrective patch for the existing 3.0.x line, not an announcement that npm has already published it.
4
+
5
+ ## Included
6
+ - #727: successful `vision_describe` guidance now uses a source-attributed `notice`, so a synthetic injected context does not terminate the assistant's visible answer. Original contribution from @kevindawn11-hash in #728 (authored commit `14c67c7`, preserved in history by merge #733), paired with Session V3/V4 source-boundary fix #731. The final merged source is `main@0fc51c3` and no npm publication is implied.
7
+ - #730: updated latest-alpha CI to accept DSH JSONL namespace plugin exports in addition to older defaults; the exact published alpha lifecycle passed on Node 22/24. This is CI-only.
8
+ - #721 qualifies DSH 0.2.1-rc.1 at upstream 1600d8a1e140dcde43a1a0941940a0480712c011 with exact source and real Host/Chromium/Settings/attachment CI.
9
+ - #722 fixes #719 by removing two unused imports of optional DSH dependencies, originally contributed by @m4ku1337 in #720. Missing optional peers must not prevent Desktop activation.
10
+ - #723 checks the actual OVHcloud VLM JSON body against its documented 10 MB limit before egress. Only the official OVH endpoint is affected; image content is not silently changed.
11
+
12
+ - #735: keep the Vision toggle clickable across a transient Host model-catalog refresh only when a valid complete source/wrapper pair remains; Host selection authority and all cold/unavailable/selecting gates remain unchanged. This mitigates the independently evidenced native-disabled click-loss case, but does not resolve the separate Host RPC fault tracked in #738.
13
+ - #737: add a privacy-bounded, test-only `gateway/internal` origin classifier for real Desktop evidence. It does not change runtime behavior or repair the intermittent Host failure.
14
+ - #736: improve English/Chinese onboarding and preserve visible cloud-data disclosure; no runtime or dependency changes.
15
+
16
+ ## Compatibility
17
+ Node ^22.19.0 or 24+. DSH >=0.1.5-rc.1 <0.2.0-0 or >=0.2.0-rc.2 <0.3.0-0. No settings or session migration, new Host privileges, or API breaking changes.
18
+
19
+ ## Qualification
20
+ Each fixing PR passed its final-head CI. #735 passed 98 checks (one conditional skip); #737 passed 33 checks (one conditional skip) plus manually dispatched DSH Alpha / 0.1.7 / 0.2.0-rc.2 exact Host gates (6/6, 5/5, 7/7). These were source and Host qualification tests, **not a clean install or an npm release of the final v3.0.5 tarball**. The candidate version still requires its own Node, packed artifact, real Host and browser verification. For detailed acceptance evidence see docs/development/v305-real-scenario-acceptance.md.
21
+
22
+ ## Still open
23
+ - #738 (open): intermittent Windows Node24 Host `gateway/internal` on an **already delivered** Vision OFF selection; #737 adds only diagnostic classification, not a fix.
24
+ - #716 (open): user-reported backend HTTP 400; four small synthetic OVH requests have since returned 200 from the maintainer's machine, but this does not explain the reporter's failures.
25
+ - #726 (open, low priority): TUI-only overlay not-found diagnostic noise; no speculative profile-composition change is included.
26
+ - #684 (closed): catalog-refreshed native click suppression received the bounded #735 mitigation. Its separate Host error class is tracked as #738.
27
+ - #704 (closed / awaiting reproducible evidence): historical billion-context coexistence report; no verified co-installation failure is claimed repaired here.
28
+ - #729 (still a PR): Atlas Cloud preset remains outside this release until the specific models' image-content behavior is verified.
29
+ - #703 (closed): upstream installer writer-lock contention was out of scope, not repaired by DVR.
30
+
31
+ Publication is a separate release gate and is not performed by this preparation PR.