dsh-tool-vision 0.9.2 → 0.9.4
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/LICENSE +23 -23
- package/README.md +36 -8
- package/README.zh.md +346 -326
- package/cordis.patch.yml +8 -8
- package/index.js +1507 -1453
- package/lib/model-probe.js +274 -274
- package/lib/session-header.js +57 -57
- package/lib/vision-tools.js +2485 -2485
- package/package.json +4 -3
package/README.zh.md
CHANGED
|
@@ -1,326 +1,346 @@
|
|
|
1
|
-
# dsh-tool-vision
|
|
2
|
-
|
|
3
|
-
**GitHub**: [Scorp1o117/dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) · **npm**: [dsh-tool-vision](https://www.npmjs.com/package/dsh-tool-vision) · [English](README.md)
|
|
4
|
-
|
|
5
|
-
[](https://github.com/Scorp1o117/dsh-enhancement-suite) [](https://www.npmjs.com/package/dsh-enhancement-suite)
|
|
6
|
-
|
|
7
|
-
属于 [DeepSeek Harness Enhancement Suite](https://github.com/Scorp1o117/dsh-enhancement-suite) —— Vision · Soul/Persona · 长期记忆 · 插件市场。
|
|
8
|
-
|
|
9
|
-
给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 外接**视觉模型**的插件。
|
|
10
|
-
|
|
11
|
-
DSH 0.1.1 已为 DeepSeek 视觉模型目录加入原生图片输入。本插件继续提供独立的 OpenAI 兼容视觉端点、像素级图片工具、截图，以及文本模型图片桥。Harness 的每次模型请求都**严格从会话日志推导**（`llm/stream` 请求必须与持久化推导一致，否则 agent-loop invariant 会报 `log-reconstruction desync`），因此图片桥仍在可持久重建的路径内完成转换：
|
|
12
|
-
|
|
13
|
-
1. **`inspect_image` 工具** —— 把图片（本地文件或 http(s) URL）发给任意支持 `image_url` 内容块的 OpenAI 兼容 `/chat/completions` 端点，把视觉模型的文字回答带回对话。
|
|
14
|
-
2. **图片桥（v0.2.1）** —— 粘贴的图片在**进入持久化日志之前**就被转换成 `inspect_image` 指引文本，拦截点是 `agent/pre-step` waterfall（这是 harness 唯一允许插件替换"进入某一步的消息"的缝；替换后的消息会**成为**持久化的 `user/message` 日志，所以请求重建 invariant 天然满足）。旧版本已经写进日志的图片消息，会在该会话下一次 pre-step 时用 surface `replace` 惰性修复。只有 `multimodalModels` 白名单内的模型直收图片块；**不参考模型的 `inputModalities` 声明**——因为很多配置为了通过 prompt 准入检查，会给纯文本模型声明 `input: [text, image]`（那只是声明，不代表上游真的能吃 `image_url`）。
|
|
15
|
-
|
|
16
|
-
- 除 dsh SDK 外零依赖 —— 兼容任意端点：OpenAI GPT-4o、Qwen-VL（DashScope）、GLM-4V（智谱）、Moonshot、Gemini 兼容端点、本地 Ollama 等。
|
|
17
|
-
- 注册在**全局工具层**：进程内所有 Agent 都能调用 `inspect_image`。
|
|
18
|
-
- **Web UI 设置栏（v0.3.0）**：设置 → 视觉模型 编辑 `tool-vision` 命名空间（API 地址、只写密钥、模型、桥接选项），写入 `settings.yaml`，**改动即时生效无需重启**。API 密钥存放在 `settings.yaml` 而非 profile patch；插件按包名挂载（`name: 'dsh-tool-vision'`）以便 web 端发现客户端 bundle。
|
|
19
|
-
|
|
20
|
-
## 兼容性（v0.9.
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
|
54
|
-
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
-
|
|
111
|
-
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
- **
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
(
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
|
140
|
-
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
`
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
`LlmService.generate`
|
|
253
|
-
|
|
254
|
-
```js
|
|
255
|
-
const
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
`
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
1
|
+
# dsh-tool-vision
|
|
2
|
+
|
|
3
|
+
**GitHub**: [Scorp1o117/dsh-tool-vision](https://github.com/Scorp1o117/dsh-tool-vision) · **npm**: [dsh-tool-vision](https://www.npmjs.com/package/dsh-tool-vision) · [English](README.md)
|
|
4
|
+
|
|
5
|
+
[](https://github.com/Scorp1o117/dsh-enhancement-suite) [](https://www.npmjs.com/package/dsh-enhancement-suite)
|
|
6
|
+
|
|
7
|
+
属于 [DeepSeek Harness Enhancement Suite](https://github.com/Scorp1o117/dsh-enhancement-suite) —— Vision · Soul/Persona · 长期记忆 · 插件市场。
|
|
8
|
+
|
|
9
|
+
给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 外接**视觉模型**的插件。
|
|
10
|
+
|
|
11
|
+
DSH 0.1.1 已为 DeepSeek 视觉模型目录加入原生图片输入。本插件继续提供独立的 OpenAI 兼容视觉端点、像素级图片工具、截图，以及文本模型图片桥。Harness 的每次模型请求都**严格从会话日志推导**（`llm/stream` 请求必须与持久化推导一致，否则 agent-loop invariant 会报 `log-reconstruction desync`），因此图片桥仍在可持久重建的路径内完成转换：
|
|
12
|
+
|
|
13
|
+
1. **`inspect_image` 工具** —— 把图片（本地文件或 http(s) URL）发给任意支持 `image_url` 内容块的 OpenAI 兼容 `/chat/completions` 端点，把视觉模型的文字回答带回对话。
|
|
14
|
+
2. **图片桥（v0.2.1）** —— 粘贴的图片在**进入持久化日志之前**就被转换成 `inspect_image` 指引文本，拦截点是 `agent/pre-step` waterfall（这是 harness 唯一允许插件替换"进入某一步的消息"的缝；替换后的消息会**成为**持久化的 `user/message` 日志，所以请求重建 invariant 天然满足）。旧版本已经写进日志的图片消息，会在该会话下一次 pre-step 时用 surface `replace` 惰性修复。只有 `multimodalModels` 白名单内的模型直收图片块；**不参考模型的 `inputModalities` 声明**——因为很多配置为了通过 prompt 准入检查，会给纯文本模型声明 `input: [text, image]`（那只是声明，不代表上游真的能吃 `image_url`）。
|
|
15
|
+
|
|
16
|
+
- 除 dsh SDK 外零依赖 —— 兼容任意端点：OpenAI GPT-4o、Qwen-VL（DashScope）、GLM-4V（智谱）、Moonshot、Gemini 兼容端点、本地 Ollama 等。
|
|
17
|
+
- 注册在**全局工具层**：进程内所有 Agent 都能调用 `inspect_image`。
|
|
18
|
+
- **Web UI 设置栏（v0.3.0）**：设置 → 视觉模型 编辑 `tool-vision` 命名空间（API 地址、只写密钥、模型、桥接选项），写入 `settings.yaml`，**改动即时生效无需重启**。API 密钥存放在 `settings.yaml` 而非 profile patch；插件按包名挂载（`name: 'dsh-tool-vision'`）以便 web 端发现客户端 bundle。
|
|
19
|
+
|
|
20
|
+
## 兼容性（v0.9.4）
|
|
21
|
+
|
|
22
|
+
DSH `0.1.5-rc.3` 现为 npm 的 `latest` 和 `next`。alpha 版本未经验证前继续标记 `unknown`。
|
|
23
|
+
|
|
24
|
+
## v0.9.4：修复 Windows 图片桥导出文件名
|
|
25
|
+
|
|
26
|
+
- 导出文件名改为从完整附件 ID 生成稳定哈希；`sha256:...` 等 ID 不再写入 NTFS 备用数据流，避免出现可见主文件为 0 字节的情况。
|
|
27
|
+
- 写入前确保导出目录存在；进程内缓存按 `bridgeExportDir` 区分。
|
|
28
|
+
- 已通过 DSH `0.1.5-rc.3` 一次性 Profile 的安装、Web 启动、首页与客户端 Bundle HTTP 检查，以及卸载验证。
|
|
29
|
+
|
|
30
|
+
## 安装
|
|
31
|
+
|
|
32
|
+
在 profile patch（`$DSH_HOME/profiles/<name>/cordis.patch.yml`）里挂载：
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
- insert:
|
|
36
|
+
- id: tool-vision
|
|
37
|
+
name: 'dsh-tool-vision' # 前置：在 profile 里 pnpm add dsh-tool-vision
|
|
38
|
+
config:
|
|
39
|
+
baseURL: 'https://api.openai.com/v1'
|
|
40
|
+
apiKeyEnv: 'VISION_API_KEY'
|
|
41
|
+
model: 'gpt-4o-mini'
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
不装 npm 包、直接加载本地路径：
|
|
45
|
+
|
|
46
|
+
```yaml
|
|
47
|
+
- id: tool-vision
|
|
48
|
+
name: './plugins/dsh-tool-vision/index.js'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## 配置
|
|
52
|
+
|
|
53
|
+
| 字段 | 默认值 | 含义 |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| `enabled` | `true` | **总开关（v0.8.0）**。关闭后插件不注册任何东西：`inspect_image`、14 个 `vision_*` 工具、图片桥、预览路由、图片能力声明统统下线；设置栏本身保留，所以随时能再打开。热生效，无需重启 dsh |
|
|
56
|
+
| `baseURL` | `https://api.openai.com/v1` | OpenAI 兼容 API 基地址 |
|
|
57
|
+
| `apiKey` | `''` | API 密钥（优先于环境变量） |
|
|
58
|
+
| `apiKeyEnv` | `VISION_API_KEY` | 存放密钥的环境变量名 |
|
|
59
|
+
| `model` | `gpt-4o-mini` | 视觉模型 id |
|
|
60
|
+
| `maxTokens` | `1024` | 视觉调用最大输出 token |
|
|
61
|
+
| `timeoutMs` | `60000` | 单次请求超时 |
|
|
62
|
+
| `maxImageBytes` | `10MB` | 本地图片大小上限 |
|
|
63
|
+
| `description` | 默认描述 | 工具描述（模型可见） |
|
|
64
|
+
| `bridgeTextOnly` | `true` | 把粘贴图片转成文本指引（发给看不懂图片的模型时） |
|
|
65
|
+
| `bridgeExportDir` | 临时目录 | 桥接图片导出目录（`os.tmpdir()/dsh-vision-bridge`）；文件名使用附件 ID 的安全哈希 |
|
|
66
|
+
| `multimodalModels` | `[]` | 模型名单（逗号分隔）。每项按「完整 id / 末段裸 id / `provider/id`」三种写法匹配，大小写不敏感，支持 `*` `?` 通配（如 `*vl*`、`deepseek/*`）。含义由下面的模式决定 |
|
|
67
|
+
| `multimodalListMode` | `whitelist` | **名单模式（v0.9.0）**：`whitelist` 名单内模型直收图片块（旧行为）；`blacklist` 名单内模型强制走桥接（用来纠正"声明支持图片但实际不支持"的模型）；`off` 忽略名单。未知值一律回退 `whitelist` |
|
|
68
|
+
| `autoDetectMultimodal` | `true` | **自动识别（v0.9.0）**：按当前路由自己声明的 `inputModalities` 判定，再与名单合成（白名单取并集、黑名单取差集）。默认开启＝识别到纯文本就交给桥接、识别到多模态就等同白名单成员直发图片；声明永远读"包装前"的真值，不会被 `bridgeAutoImage` 的假声明污染。设为 `false` 可退回"只认名单"的纯手工行为 |
|
|
69
|
+
| `probeResults` | `{}` | **实测结果（v0.9.0）**：`"provider/model" → "yes"`/`"no"`，由 `vision_probe_model` 工具写入，不要手改。实测优先级**高于声明**（真实请求 > 自称），但**低于** `multimodalModels`（人的明确意图有最终话语权） |
|
|
70
|
+
| `bridgePreview` | `true` | 桥接图片内联预览：用户气泡内显示缩略图，点击放大 |
|
|
71
|
+
| `bridgePreviewScanIntervalMs` | `2000` | 预览兜底扫描间隔（毫秒）；`0` 关闭兜底 |
|
|
72
|
+
| `bridgePreviewHideHint` | `true` | 图片加载成功后隐藏桥接提示文本（失败时保留，安全降级） |
|
|
73
|
+
| `bridgeAutoImage` | `true` | 桥接开启时向宿主准入检查报告**所有**模型都支持图片输入，纯文本模型也能直接粘贴图片，无需手动改 provider 配置 |
|
|
74
|
+
| `sendSessionHeader` | `true` | 给视觉请求发送稳定的会话标识头。OpenCode Go 等网关要求每请求带 `x-opencode-session`（一个对话一个稳定 ID），缺失的请求在 2026-09-06 起可能报错 |
|
|
75
|
+
| `sessionHeaderName` | `x-opencode-session` | 承载会话 ID 的头名 |
|
|
76
|
+
| `sessionId` | `''` | 固定会话 ID（后台/无 dsh 会话调用时用）；留空则自动：优先取当前 dsh 会话 ID，否则用进程级稳定随机 ID |
|
|
77
|
+
|
|
78
|
+
## 图片桥配置
|
|
79
|
+
|
|
80
|
+
1. （一般不需要）只有关闭 `bridgeAutoImage` 时才需要手动给模型声明图片输入（pi-ai 风格），让 harness 放行图片消息：
|
|
81
|
+
```yaml
|
|
82
|
+
llm-pi-ai:
|
|
83
|
+
providers:
|
|
84
|
+
your-provider:
|
|
85
|
+
models:
|
|
86
|
+
- id: deepseek-v4-flash
|
|
87
|
+
input: [text, image]
|
|
88
|
+
```
|
|
89
|
+
2. 在插件配置里列出真正多模态的模型，让它们直收图片块（名单模式见下一节）：
|
|
90
|
+
```yaml
|
|
91
|
+
- id: tool-vision
|
|
92
|
+
name: 'dsh-tool-vision'
|
|
93
|
+
config:
|
|
94
|
+
multimodalListMode: whitelist # 默认，名单内直发图片
|
|
95
|
+
multimodalModels: ['mimo-v2.5', 'grok-4.5']
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
之后在文本模型下贴图，转录里会留下一条指引：
|
|
99
|
+
`[User sent an image, exported to: <path>. Inspect it with the inspect_image tool...]`
|
|
100
|
+
（该消息不再以像素图形式渲染），Agent 会调用视觉端点查看并把结果带回对话。
|
|
101
|
+
|
|
102
|
+
> 为什么不用 `llm/stream`？harness 会冻结每个请求，且 agent-loop invariant 会拒绝任何与会话日志推导不一致的请求；这个 cordis 版本的 waterfall `next()` 也无法替换请求参数。`agent/pre-step` 才是受支持的缝：它的决策消息**会成为**持久化日志，invariant 天然成立。
|
|
103
|
+
|
|
104
|
+
密钥解析顺序：`config.apiKey` → `process.env[apiKeyEnv]` → `process.env.OPENAI_API_KEY`。
|
|
105
|
+
|
|
106
|
+
## 桥接图片预览（v0.4.0）
|
|
107
|
+
|
|
108
|
+
纯文本模型下，被桥接的图片在对话里只显示一段 `[User sent an image...]` 文本指引。开启 `bridgePreview`（默认开）后，浏览器端会在**展示层**把指引渲染成气泡内缩略图：
|
|
109
|
+
|
|
110
|
+
- **缩略图 + 灯箱**：点击缩略图全屏放大，点击任意处或按 `Esc` 关闭；
|
|
111
|
+
- **即时 + 兜底**：新消息由 MutationObserver 即时处理，历史消息由周期兜底扫描补齐（间隔见 `bridgePreviewScanIntervalMs`）；
|
|
112
|
+
- **隐藏提示文本（P2）**：`bridgePreviewHideHint` 开启时，图片加载成功后桥接文本自动隐藏，气泡只留图片；加载失败则保留文本（安全降级，绝不出现"既无图又无字"）；
|
|
113
|
+
- **识别机制**：桥接文本带不可见前缀标记（`\u200b[bridge]`），客户端据此精确识别桥接块——用户正常发言中出现"exported to:"字样不会被误伤；
|
|
114
|
+
- **纯展示层红线**：不修改持久化消息、不修改转录、不修改模型侧文本、不碰 `inspect_image` 调用链。
|
|
115
|
+
|
|
116
|
+
预览图片由同源回环路由 `/plugins/dsh-tool-vision/image` 提供，只读桥接导出目录、仅本机 Host、仅图片扩展名、单文件 ≤ 20MB、防目录穿越。
|
|
117
|
+
|
|
118
|
+
## 工具：`inspect_image`
|
|
119
|
+
|
|
120
|
+
| 参数 | 必填 | 含义 |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `path` | ✅ | 图片路径（绝对路径，或相对当前工作区）或 http(s) URL |
|
|
123
|
+
| `question` | – | 可选的具体问题 |
|
|
124
|
+
| `detail` | – | `auto` / `low` / `high` 分辨率提示 |
|
|
125
|
+
|
|
126
|
+
示例端点（`baseURL`）：
|
|
127
|
+
|
|
128
|
+
- **OpenAI**：`https://api.openai.com/v1` —— `gpt-4o`、`gpt-4o-mini`
|
|
129
|
+
- **阿里云 DashScope（Qwen-VL）**：`https://dashscope.aliyuncs.com/compatible-mode/v1` —— `qwen-vl-plus`、`qwen-vl-max`
|
|
130
|
+
- **智谱（GLM-4V）**：`https://open.bigmodel.cn/api/paas/v4` —— `glm-4v-flash`（免费档）、`glm-4v-plus`
|
|
131
|
+
- **Moonshot（Kimi）**：`https://api.moonshot.cn/v1` —— `moonshot-v1-8k-vision-preview`
|
|
132
|
+
- **Ollama 本地**：`http://localhost:11434/v1` —— `llama3.2-vision`（无需密钥）
|
|
133
|
+
|
|
134
|
+
## 像素级视觉工具(v0.6.0,移植自 dsh-vision-router)
|
|
135
|
+
|
|
136
|
+
14 个 `vision_*` 工具由**同一个** `inspect_image` 配置的端点驱动
|
|
137
|
+
(baseURL/apiKey/model)——无 provider 链、无本地模型、零新增配置:
|
|
138
|
+
|
|
139
|
+
| 工具 | 用途 |
|
|
140
|
+
|---|---|
|
|
141
|
+
| `vision_describe` | 看图问答 / 多图对比(可选结构化 JSON) |
|
|
142
|
+
| `vision_ground` | 定位目标,返回原图像素坐标框 |
|
|
143
|
+
| `vision_detect` | 枚举元素(按钮/输入框/图标…),带编号框 |
|
|
144
|
+
| `vision_crop` | 按像素区域裁剪出 PNG 产物 |
|
|
145
|
+
| `vision_pixel_diff` | 逐像素对比:差异比例、最差区域、热图、报告 |
|
|
146
|
+
| `vision_colors` | 主色量化,还原 UI 调色板 |
|
|
147
|
+
| `vision_ocr` | 逐字转写文字(只读字,不做场景识别) |
|
|
148
|
+
| `vision_long_screenshot_ocr` | 长截图分块转写为 Markdown |
|
|
149
|
+
| `vision_trace` | potrace 矢量化输出彩色 SVG(worker 线程,安全) |
|
|
150
|
+
| `vision_extract_foreground` | 纯色背景抠图 → 透明 PNG |
|
|
151
|
+
| `vision_html_screenshot` | 本地 HTML 无头渲染截图(禁网) |
|
|
152
|
+
| `vision_screenshot` | 桌面截屏(隐私门控:需在设置中开启 `desktopScreenshot`;Win: PowerShell / macOS: screencapture / Linux: import/scrot) |
|
|
153
|
+
| `vision_present` | 通过宿主附件库把生成的图片正式展示给用户 |
|
|
154
|
+
| `vision_materialize` | 把附件/本地图片落盘为工作区真实路径 |
|
|
155
|
+
|
|
156
|
+
质量与安全细节:
|
|
157
|
+
|
|
158
|
+
- **内容哈希缓存**按 端点+模型+图片+问题 取键(切模型不吃旧答案,失败结果
|
|
159
|
+
不入缓存);
|
|
160
|
+
- **统一 4MP 降采样**后再调用模型;超大输入 stat 预检直接拒绝(文件与
|
|
161
|
+
附件路径统一 20MB 上限);
|
|
162
|
+
- **限流/5xx 自动重试**(感知 Retry-After 退避);端点**内容安全拒绝**明确
|
|
163
|
+
返回 `VISION_CONTENT_FILTERED`,不再误报后端不可用;
|
|
164
|
+
- **长截图 OCR 边界**:120s 总预算、40 块上限、取消检查、首块失败即停;
|
|
165
|
+
- **路径 containment**(相对输入禁止逃逸工作区);产物写入
|
|
166
|
+
`<工作区>/.dsh-tool-vision/`。
|
|
167
|
+
|
|
168
|
+
依赖 `sharp` / `potrace` / `puppeteer-core`(声明为**可选依赖**:平台安装失败
|
|
169
|
+
不会阻断插件安装;缺失时懒加载降级并给出安装提示,不影响其他工具)。
|
|
170
|
+
|
|
171
|
+
`vision_screenshot` 属于隐私敏感能力,**默认不注册**——在 tool-vision 设置中
|
|
172
|
+
开启 `desktopScreenshot: true` 后才会注册桌面截屏工具。
|
|
173
|
+
|
|
174
|
+
## v0.9.0：模型名单模式与自动识别
|
|
175
|
+
|
|
176
|
+
桥接要回答一个问题：**当前这个模型能不能直接看图片？** v0.9.0 把它拆成两个相互独立的输入。
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
base = autoDetectMultimodal ? (路由声明含 image) : 空集
|
|
180
|
+
off → direct = base 名单不参与
|
|
181
|
+
whitelist → direct = base ∪ 名单 名单只做"加"
|
|
182
|
+
blacklist → direct = base \ 名单 名单只做"减"
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**命中名单时以名单为准**：名单是用户明确的意图，优先级高于模型自己的声明，所以永远能纠正误判。
|
|
186
|
+
|
|
187
|
+
**黑名单绝不会退化成"未列出的一律直发"**：黑名单的基准是自动识别集；没开自动识别时基准是空集，未列出的模型照样走桥接。这是刻意设计的——否则一次误配就能把图片硬塞给纯文本端点。
|
|
188
|
+
|
|
189
|
+
**匹配规则**：`mimo-v2.5`、`xiaomi/mimo-v2.5`、`commandcode/xiaomi/mimo-v2.5` 指向同一个路由；`*` / `?` 为通配符；大小写不敏感。v0.8.1 只做字符串全等，README 自己举的 `mimo-v2.5` 例子在 `xiaomi/mimo-v2.5` 这类路由上其实**静默无效**，v0.9.0 修好了（只会多放行，不会收回任何旧配置已经放行的模型）。
|
|
190
|
+
|
|
191
|
+
**面板**（设置 → 视觉模型）：
|
|
192
|
+
|
|
193
|
+
- 名单字段下面是一份**可直接勾选的模型清单**：候选来自 dsh 已配置的模型（`llm.listProviders()` + `llm.listModels()`），按 provider 分组，标注哪些**声明**支持图片；勾选加入、取消勾选移出，上方输入框仍可手打通配符（两者共用同一份草稿，改完按「保存」生效，未保存时清单头部会标"未保存"）；
|
|
194
|
+
- 顶部常驻**当前路由判定**：`provider / model`、直发还是桥接、依据是什么（名单命中 / 自动识别 / 默认）。
|
|
195
|
+
|
|
196
|
+
> 为什么不只用 `<datalist>`：原生 datalist **必须聚焦输入框并敲字才会弹出**，v0.9.0 第一版因此看起来像"面板没反应"。现在清单常驻可见，datalist 只作打字辅助。
|
|
197
|
+
>
|
|
198
|
+
> 取消勾选移除的是**命中的那条记录本身**（名单里写 `mimo-v2.5` 命中了 `xiaomi/mimo-v2.5`，取消勾选就移除 `mimo-v2.5`，不会凭空虚增一个完整 id）。"哪条命中了"由服务端用与桥接**同一套匹配器**算出（payload 的 `matchedEntries`），客户端不复制规则，所以面板显示的状态永远不会和实际判定打架。
|
|
199
|
+
|
|
200
|
+
**判定依据的读取路径**（这是本版最容易做错的地方）：`autoDetectMultimodal` **必须**读 `resolveModelInfo` 被包装之前的真值，否则 `bridgeAutoImage` 给所有模型贴上的"支持图片"就成了自证。代码里由 `unwrappedResolveModelInfo()` 保证，并有专门的回归测试。
|
|
201
|
+
|
|
202
|
+
候选项由插件自己的回环路由提供：`GET /plugins/dsh-tool-vision/models`（仅本机 Host、只读、`no-store`），只返回 provider/model id 与声明能力，**不含任何密钥或端点地址**。它挂在插件主 fiber 而非总开关的子 fiber 上，所以插件关闭时面板依然可用。
|
|
203
|
+
|
|
204
|
+
> ⚠️ `inputModalities` 是**声明**，不是保证——profile 里常见"为了过准入检查而写 `input: [text, image]`"的纯文本模型。上游 `dsh-llm-pi-ai` 自己也把"未声明"一律当作纯文本，理由写在源码注释里：**两种误判的代价不对等**——少声明会在贴图前就拒绝并点名模型，多声明则会放行一张"上游中途拒收、而消息已经落盘"的图片。
|
|
205
|
+
>
|
|
206
|
+
> 所以自动识别是默认开启的，同时带三层兜底：① 某个路由**首次**因"仅凭自己的声明"被放行时，日志会打一条明确提示并点名怎么改；② 面板顶部常驻当前判定与依据；③ 把该模型写进 `multimodalModels` 并切到 `blacklist` 模式即可强制回到桥接。
|
|
207
|
+
|
|
208
|
+
## 测试
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
npm test # 服务端单测（不需要额外依赖）
|
|
212
|
+
npm run test:render # 面板渲染测试（需要 devDependencies）
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`npm run test:render` 在 jsdom 里加载**真实客户端 bundle**、走**真实注册路径**（`apply` → `slots.register` → 组件），数据由**真实的服务端路由处理器**产出，最后断言真实 DOM 与真实的设置写入。
|
|
216
|
+
|
|
217
|
+
它单独成命令、**不并入 `npm test`**：它需要 `react` / `react-dom` / `jsdom`，而一个"依赖缺失就静默跳过"的 DOM 测试只会带来虚假的安全感。需要时先 `npm i -D react@18 react-dom@18 jsdom`。
|
|
218
|
+
|
|
219
|
+
它存在的理由很具体：v0.9.0 第一版把模型清单只渲染进原生 `<datalist>` —— 服务端单测**全绿**，面板却看起来完全没反应。这类 bug 在 DOM 之下根本抓不到。
|
|
220
|
+
|
|
221
|
+
## 实测探测：`vision_probe_model`（v0.9.0）
|
|
222
|
+
|
|
223
|
+
前面所有判定都建立在"模型**说自己**能不能看图"之上。这个工具改为**真的发一张图过去试**，是插件里唯一的地面真相。
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
base = autoDetect ? 路由声明含 image : ∅
|
|
227
|
+
探测结果（若有）覆盖 base 实测 > 自称
|
|
228
|
+
名单命中（若有）覆盖一切 人的意图 > 实测
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
**为什么一次请求不够**（都是实测踩出来的）：
|
|
232
|
+
|
|
233
|
+
- **会瞎猜**：模型可能对橙色方块回答"blue"。所以探测跑**两个不同颜色**，两个都答对才算通过；
|
|
234
|
+
- **推理模型会返回空 `content`**：思考预算不够时 `max_tokens` 全被烧光。默认给 2048，并回退读 `reasoning_content`；
|
|
235
|
+
- **必须要有对照组**：先发一条纯文本请求确认"这条路本身是通的"，否则一个 401/超时会被误读成"它不能看图"——那会把一条好端端的多模态路由**永久**推回桥接；
|
|
236
|
+
- **端点不报错 ≠ 能看图**。真实网关实测：`meituan/LongCat-2.0:free` 收到图片请求返回 200，但回答是 `"I can't see any image."`。只有"端点主动拒绝图片部分"才是确定性的负面信号。
|
|
237
|
+
|
|
238
|
+
结论分三档：`yes`（对照组通过 + 两色全对）、`no`（端点拒绝图片，或答了但没读图）、`unknown`（网络/鉴权/协议问题——**绝不**当作能力结论）。
|
|
239
|
+
|
|
240
|
+
**它怎么拿到主模型的端点与凭据**（不新增任何配置）：`llm.listConfigurableProviders()` 给出 provider 的 settings 命名空间与路径 → `settings.get(ns)` 读出 `baseURL`/`apiKeyEnv`/`api` → `credentials.resolve(apiKeyEnv)` 取出密钥（`.value`），与 `dsh-llm-pi-ai` 真实调用同一条路。只读，且**端点与密钥绝不出现在探测结果里**。
|
|
241
|
+
|
|
242
|
+
**联动**：探测结果写入 `probeResults` 并**立即参与桥接判定**——`yes` 直接放行图片、`no` 强制回到桥接，且**与名单模式无关**。（这比"自动往名单里写一笔"更正确：名单在 `blacklist` 模式下含义是反的，自动写入会得到完全相反的效果。）面板清单里每个模型带徽章：
|
|
243
|
+
|
|
244
|
+
- `已实测可看图` / `已实测不可看图`（蓝 / 红）——实测优先展示；
|
|
245
|
+
- 没探测过的才回退显示声明的 `声明支持图片`；
|
|
246
|
+
- 顶部"依据"栏显示 `实测（真实发图验证通过/未通过）`。
|
|
247
|
+
|
|
248
|
+
> 未知协议的路由（如 `openai-responses`）会直接返回 `unknown` 并说明原因，而不是用 `chat/completions` 去猜一个自信的错误答案。
|
|
249
|
+
|
|
250
|
+
## v0.9.3：适配器快照模型准入（pi-ai 门禁放行）
|
|
251
|
+
|
|
252
|
+
**问题**。`v0.9.2` 的 `installDispatchImageAdmission` 成功满足了 DSH 核心层 `LlmService.generate` 的模态检查，将图片放行给底层适配器。但在以 `dsh-llm-pi-ai` 作为适配器时，其内部在 `streamWithSnapshot` 中执行了第二道门禁校验：
|
|
253
|
+
|
|
254
|
+
```js
|
|
255
|
+
const model = this.modelOf(snapshot, options.provider, options.model);
|
|
256
|
+
if (containsImage && !model.input.includes("image"))
|
|
257
|
+
throw new LlmError(`pi-ai model "${model.id}" does not support image input`, "UNSUPPORTED_CONTENT");
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
`this.modelOf` 直接读取适配器自身维护的 `snapshot.models` 目录，若用户未在 `settings.yaml` 中显式声明 `input: [text, image]`，此处默认只有 `["text"]`。导致未声明的模型在放行图片后，在流式发起前被 `pi-ai` 适配器抛出 `UNSUPPORTED_CONTENT`，且由于该图片已被写进会话历史，后续所有轮次（哪怕发纯文本）都会彻底报错锁死。
|
|
261
|
+
|
|
262
|
+
**修复**。在判定为直通路由（`direct: true`）时，`installDispatchImageAdmission` 增加了双重深度注入：
|
|
263
|
+
1. 包装 `adapter.modelOf`（若存在），使其对直通路由返回携带 `"image"` 模态的模型对象；
|
|
264
|
+
2. 动态向当前快照模型（`snapshot.models.getModel(route, model).input`）追加 `"image"` 模态；
|
|
265
|
+
3. `dispose` 时完整还原 `adapter.modelOf` 并清理被追加的模态数组。
|
|
266
|
+
|
|
267
|
+
## v0.9.2：准入不等于派发
|
|
268
|
+
|
|
269
|
+
**问题**。插件收集的每一个能力信号 —— `probeResults`、`multimodalModels`、
|
|
270
|
+
`autoDetectMultimodal` —— 都只决定**桥接**要不要拦截图片，没有一个决定模型**收不收得到**它。
|
|
271
|
+
|
|
272
|
+
`LlmService.generate` 的能力来源是适配器，不是插件：
|
|
273
|
+
|
|
274
|
+
```js
|
|
275
|
+
const adapterCall = await adapter.prepareCall(provider, model, signal);
|
|
276
|
+
modelInfo = this.normalizeModelInfo(registration, model, adapterCall.model);
|
|
277
|
+
if (modelInfo.inputModalities !== undefined
|
|
278
|
+
&& !modelInfo.inputModalities.includes("image")
|
|
279
|
+
&& projectedMessages.some((message) => contentHasImage(message.content)))
|
|
280
|
+
projectedMessages = projectImagesForTextModel(projectedMessages);
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`projectImagesForTextModel` 会在**调用适配器之前**把每个图像块改写成
|
|
284
|
+
`[image omitted because this model accepts text only; attachment sha256:…]`。
|
|
285
|
+
于是在一条插件已实测为「能读图」的路由上 —— 桥接因此让开放行 —— 图片依然被销毁，
|
|
286
|
+
而销毁它的那个判断只读适配器的声明，不读任何别的东西。`resolveModelInfo` 那层 wrap
|
|
287
|
+
（`bridgeAutoImage`）是**准入**：它决定谁可以「提交」图片，从不改变适配器实际流出的内容。
|
|
288
|
+
插件里没有任何东西够到真正做决定的那一层。
|
|
289
|
+
|
|
290
|
+
症状就是：一条探测结果为 `yes`、也列在 `multimodalModels` 里的路由，依然回
|
|
291
|
+
`[image omitted …]`。
|
|
292
|
+
|
|
293
|
+
**修复**。`installDispatchImageAdmission` 包装 `llm.registration` —— 也就是核心自己
|
|
294
|
+
调用的那个访问器 —— 于是每个适配器（包括安装之后才注册的）都会经由桥接所用的**同一个**
|
|
295
|
+
`routeDirectDecision` 来回答 `prepareCall`。一份优先级规则、两条缝，两者永不可能对同一
|
|
296
|
+
条路由给出不同答案。判定为「走桥接」时行为不变：桥接早已把图片变成 `inspect_image`
|
|
297
|
+
提示，核心的投影仍然是任何漏到派发层的图片的正确兜底。
|
|
298
|
+
|
|
299
|
+
三条性质值得写下来，因为每一条都有测试：
|
|
300
|
+
|
|
301
|
+
- **失败即保守**。判定无法作出时（配置抛错）保持调用原样，而不是把像素发给一条可能拒绝它的路由。
|
|
302
|
+
- **可逆**。dispose 会还原它改过的每个适配器**以及**访问器本身；dispose 后再安装会重新包装。
|
|
303
|
+
- **后注册的 provider 也算**。包装挂在访问器上而不是适配器快照上，所以安装之后注册的 provider 同样覆盖。
|
|
304
|
+
|
|
305
|
+
`routeDirectDecision` 现在是这条优先级规则的唯一实现，桥接与派发共用 —— 两份实现必然
|
|
306
|
+
漂移，而这份有三个输入。
|
|
307
|
+
|
|
308
|
+
## v0.8.0：总开关，以及保存修复
|
|
309
|
+
|
|
310
|
+
**总开关。** `enabled` 字段加设置栏顶部的一键按钮（`一键关闭` / `重新启用`）。
|
|
311
|
+
注册本身就是绑定在「发起注册的 cordis fiber」上的副作用，所以插件把所有工具、
|
|
312
|
+
图片桥、预览路由和图片能力声明都放进一个**子 fiber**：关掉开关就是销毁这个子
|
|
313
|
+
fiber，15 个工具一并从模型侧消失。设置栏留在父 fiber 上，因此关掉之后还能再打开。
|
|
314
|
+
无需重启 dsh。
|
|
315
|
+
|
|
316
|
+
**保存修复。** 此前表单把 18 个字段作为**并行** `scope.set()/unset()` 提交。每个
|
|
317
|
+
写入各自携带一个 revision 栅栏，而栅栏落后于宿主文档的写入会被 `settings/conflict`
|
|
318
|
+
拒绝——**且被拒绝的写入仍然 resolve**（scope 的契约是「完成写入与恢复读取后结算」，
|
|
319
|
+
不是「被拒就抛错」）。于是设置栏显示「已保存」，而编辑内容静默回退，看起来就是
|
|
320
|
+
「完全存不了」。
|
|
321
|
+
|
|
322
|
+
现在改为**一次原子 `mutate()`**，整批修改共用一个栅栏和一次持久化决策；写入结算后
|
|
323
|
+
再回读命名空间section做校验，只有确认生效才报「已保存」，否则弹出「写入未生效」并
|
|
324
|
+
重新载入表单。没有 `mutate()` 的旧宿主回退为**串行**写入（每个等前一个完成，revision
|
|
325
|
+
链条依然正确），绝不并行。
|
|
326
|
+
|
|
327
|
+
另外删掉了 3 处 `if (typeof scope.load === "function") scope.load()`：`SettingsScope` 接口
|
|
328
|
+
从来没有 `load()`（完整 seam 只有 getSnapshot / subscribe / mutate / set / unset，读走的是
|
|
329
|
+
共享 describe 镜像，由宿主 `settings/document-updated` 驱动刷新）。这些守卫是照臆测 API 写的
|
|
330
|
+
死代码，读起来像"已经刷新过了"，反而掩盖了缺失的写入校验。
|
|
331
|
+
|
|
332
|
+
## 限制
|
|
333
|
+
|
|
334
|
+
- 从 `0.6.3` 起最低支持 DSH `0.1.0-rc.7`，已针对 `0.1.0-rc.7`、
|
|
335
|
+
`0.1.0-rc.8` 和 `0.1.1-rc.1` 测试。仍使用 DSH `0.1.0-rc.6` 的用户请锁定
|
|
336
|
+
`dsh-tool-vision@0.6.1`；这是最后一个包含旧 settings 白名单兼容补丁的版本。
|
|
337
|
+
- 被桥接的图片以文本指引进入对话（转录而非像素）——文本模型无法做像素级上下文推理；视觉模型的描述通过 `inspect_image` 回传。
|
|
338
|
+
- 桥接是**单向门**：文本模型下贴的图会在 `agent/pre-step` 被写进持久化日志，之后切到多模态模型也不会还原成图片块（反方向——多模态切到文本模型——会由 `repairLoggedImages` 自动补上桥接）。
|
|
339
|
+
- 图片以 base64 传输；注意隐私与大小限制。
|
|
340
|
+
- 独立于 dsh-llm 的路由/重试体系；失败会向 Agent 返回明确错误。
|
|
341
|
+
|
|
342
|
+
## License
|
|
343
|
+
|
|
344
|
+
MIT —— 桥接预览与整合:xing666173。像素级视觉工具移植自
|
|
345
|
+
[dsh-vision-router](https://github.com/ysr666/dsh-vision-router)(© ysr666,MIT),
|
|
346
|
+
在此致谢。
|