@anionex/dsh-vision-toolkit 0.1.12 → 0.1.14
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.i18n.yaml +3 -3
- package/README.md +207 -346
- package/README.zh.md +212 -360
- package/docs/requirements-traceability/README.i18n.yaml +2 -2
- package/docs/requirements-traceability/README.md +1 -1
- package/docs/requirements-traceability/README.zh.md +1 -1
- package/lib/client.js +173 -7
- package/lib/client.js.map +1 -1
- package/lib/config.js +4 -0
- package/lib/config.js.map +1 -1
- package/lib/defaults.js +1 -1
- package/lib/defaults.js.map +1 -1
- package/lib/plugin-update.js +1011 -0
- package/lib/plugin-update.js.map +1 -0
- package/lib/runtime-install.js +61 -1
- package/lib/runtime-install.js.map +1 -1
- package/lib/runtime.js +20 -3
- package/lib/runtime.js.map +1 -1
- package/lib/skill.js +7 -3
- package/lib/skill.js.map +1 -1
- package/lib/tools.js +3 -2
- package/lib/tools.js.map +1 -1
- package/lib/types/client/index.d.ts +55 -1
- package/lib/types/client/index.d.ts.map +1 -1
- package/lib/types/config.d.ts.map +1 -1
- package/lib/types/defaults.d.ts +1 -1
- package/lib/types/defaults.d.ts.map +1 -1
- package/lib/types/plugin-update.d.ts +111 -0
- package/lib/types/plugin-update.d.ts.map +1 -0
- package/lib/types/runtime-install.d.ts +11 -0
- package/lib/types/runtime-install.d.ts.map +1 -1
- package/lib/types/runtime.d.ts +3 -0
- package/lib/types/runtime.d.ts.map +1 -1
- package/lib/types/skill.d.ts +1 -1
- package/lib/types/skill.d.ts.map +1 -1
- package/lib/types/tools.d.ts.map +1 -1
- package/lib/types/upstream.d.ts +1 -0
- package/lib/types/upstream.d.ts.map +1 -1
- package/lib/types/web.d.ts +13 -1
- package/lib/types/web.d.ts.map +1 -1
- package/lib/upstream.js +20 -8
- package/lib/upstream.js.map +1 -1
- package/lib/web.js +46 -7
- package/lib/web.js.map +1 -1
- package/package.json +12 -14
- package/src/client/index.tsx +229 -6
- package/src/config.ts +4 -0
- package/src/defaults.ts +1 -1
- package/src/plugin-update.ts +1142 -0
- package/src/runtime-install.ts +77 -1
- package/src/runtime.ts +23 -3
- package/src/skill.ts +7 -3
- package/src/tools.ts +4 -2
- package/src/upstream.ts +21 -8
- package/src/web.ts +69 -3
- package/vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json +3 -3
- package/vendor/agent-vision-toolkit/bin/crop +0 -0
- package/vendor/agent-vision-toolkit/bin/detect +0 -0
- package/vendor/agent-vision-toolkit/bin/glance +0 -0
- package/vendor/agent-vision-toolkit/bin/ground +0 -0
- package/vendor/agent-vision-toolkit/bin/trace +0 -0
- package/vendor/agent-vision-toolkit/skills/vision-tools/scripts/html_shot.py +323 -11
- package/vendor/agent-vision-toolkit/skills/vision-tools/scripts/long_screenshot_ocr.py +0 -0
- /package/assets/{hero.png → hero-v2.png} +0 -0
package/README.zh.md
CHANGED
|
@@ -1,484 +1,336 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="assets/hero.png" alt="DSH Vision Toolkit
|
|
2
|
+
<img src="assets/hero-v2.png" alt="DSH Vision Toolkit：让纯文本 DeepSeek Harness Agent 看懂图片并完成视觉任务" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
|
-
<
|
|
5
|
+
<div align="center">
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
<a href="https://github.com/Anionex/dsh-vision-toolkit/blob/main/README.md">English</a> | 中文
|
|
9
|
-
</p>
|
|
7
|
+
# DSH Vision Toolkit
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
<a href="tests"><img src="https://img.shields.io/badge/verified-233%20tests-2EA44F?style=flat-square" alt="已验证：233 项测试" /></a>
|
|
17
|
-
</p>
|
|
9
|
+
[](https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit)
|
|
10
|
+
[](https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit)
|
|
11
|
+
[](https://www.npmjs.com/package/@anionex/dsh-vision-toolkit)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
[](cordis.patch.yml)
|
|
18
14
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
15
|
+
**更强大的视觉工具箱——给 DeepSeek Harness 里的纯文本模型装上眼睛：图片问答、长图 OCR、前端 UI 还原、GUI 视觉任务，一套视觉工具箱和一个 Skill。**
|
|
16
|
+
|
|
17
|
+
🚀 粘贴图片，直接提问 ｜ 一行命令安装即用 ｜ 内置免费额度 ｜ 场景丰富
|
|
18
|
+
|
|
19
|
+
🌐 [English](README.md) ｜ **中文**
|
|
20
|
+
|
|
21
|
+
</div>
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
如果你在 dsh 中使用 DeepSeek 等纯文本模型，遇到了下面问题中的一个或者多个，那么这个插件适合你：
|
|
24
|
+
1. 粘贴图片被拒绝，不能发图片给模型，还要手动切换模型。
|
|
25
|
+
2. 模型看不到图片内容，不能做和图片有关的任务。
|
|
26
|
+
3. 已有方案只能得到图片笼统描述，完成不了高难度视觉相关任务，例如ui还原，长截图分析等。
|
|
27
|
+
4. 不能安装即用，直接体验，还要自己配置api key。
|
|
27
28
|
|
|
28
|
-
|
|
29
|
+
🏆 本项目为deepseek harness生态首个综合性视觉工具插件：内测前已立项，并在内测期间参考本人的[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit)做出
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
> **原创声明：** 这套视觉工具和 `vision-tools` Skill 由作者个人原创并持续打磨，相关工具、方法和工作流来自长期的真实使用与反复迭代。
|
|
32
|
+
|
|
33
|
+
## 亮点
|
|
34
|
+
|
|
35
|
+
- **粘贴即可使用。** 在 DSH Web 里粘贴图片，文本模型会自动切换到看图模式变体，不需要手动复制路径或更换模型。
|
|
36
|
+
- **无缝体验。** 图片保留原生缩略图、会话记录和工作区路径；Web 可以预览产物，Headless 也能继续使用同一份结构化结果。
|
|
37
|
+
- **一行命令安装即用。** 安装插件后默认使用内置免费 Groq Qwen3.6 视觉服务，不需要申请 API Key。
|
|
38
|
+
- **内置免费额度。** 共享服务提供每客户端每天 100 次、全局每天 3,000 次和每 60 秒 60 次突发请求额度，并在触发限制时返回明确原因。
|
|
39
|
+
- **带着意图去看图。** Agent 不只生成通用描述，而是围绕“报错在哪里”“按钮在哪”等当前任务提取证据。
|
|
40
|
+
- **从截图到可验证结果。** 参考图、HTML 截图、差异定位和像素对比组成一条完整 UI 还原闭环。
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 的视觉能力不只停留在图片描述：Agent 可以读取、定位、裁剪、描摹、还原和验证视觉内容。DSH Vision Toolkit 是这套工具箱面向 DeepSeek Harness 的原生接入，让它进入 Web 和 Headless Profile。
|
|
44
|
+
|
|
45
|
+
本项目提供两层能力：
|
|
46
|
+
|
|
47
|
+
1. **视觉工具和 Skill**：让 Agent 知道什么时候该看图、定位、OCR、裁剪、描摹或做像素对比。
|
|
48
|
+
2. **DSH 原生接入**：把这些能力放进 Profile、会话、Settings、Artifacts 和 Web 界面，并提供安装即可使用的免费 Groq Qwen3.6 视觉服务。
|
|
49
|
+
|
|
50
|
+
> **安装即可使用。** 默认接入内置免费 Groq Qwen3.6 视觉服务，不需要申请 API Key；
|
|
31
51
|
|
|
32
52
|
```sh
|
|
33
53
|
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
34
54
|
```
|
|
35
55
|
|
|
36
|
-
npm 包已经包含视觉工具快照，并默认使用托管运行时。**普通安装不需要下载源码，也不需要填写 `agentVisionToolkitPath`。**
|
|
37
|
-
|
|
38
56
|
**上游工具箱：** [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) · **项目网站：** [agent-vision.anionex.me](https://agent-vision.anionex.me)
|
|
39
57
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
58
|
+
<details>
|
|
59
|
+
<summary><strong>目录</strong></summary>
|
|
60
|
+
|
|
61
|
+
- [亮点](#亮点)
|
|
62
|
+
- [最近更新](#最近更新)
|
|
63
|
+
- [适合谁用](#适合谁用)
|
|
64
|
+
- [实际效果](#实际效果)
|
|
65
|
+
- [快速开始：三步完成](#快速开始三步完成)
|
|
66
|
+
- [常见任务](#常见任务)
|
|
67
|
+
- [工具一览](#工具一览)
|
|
68
|
+
- [配置与限制](#配置与限制)
|
|
69
|
+
- [常见问题](#常见问题)
|
|
70
|
+
- [开发与社区](#开发与社区)
|
|
50
71
|
|
|
51
|
-
|
|
72
|
+
</details>
|
|
52
73
|
|
|
53
|
-
##
|
|
74
|
+
## 最近更新
|
|
54
75
|
|
|
55
|
-
|
|
76
|
+
- **2026-08-16 · Windows Python：** 支持 Microsoft Store Python，解决部分 Windows 用户首次创建隔离环境失败的问题。
|
|
77
|
+
- **2026-08-16 · 免费视觉升级：** 默认模型切换到 Groq Qwen3.6，解决免 Key 方案看图效果不足的问题。
|
|
78
|
+
- **2026-08-16 · 图片粘贴：** 文本模型自动切换到 `(Vision Toolkit)` 变体并保留工作区路径，解决粘贴图片被拦截或后续无法复用的问题。
|
|
79
|
+
- **2026-08-16 · 免费额度：** 全局和突发额度提高到 `3,000/日` 和 `60/分钟`，更充分利用三个 Groq 账号，同时保留单客户端 `100/日` 限制。
|
|
80
|
+
- **2026-08-16 · 真实模型测试：** Settings 新增完整图片请求测试，解决 `/models` 可访问却不能证明模型真的会看图的问题。
|
|
56
81
|
|
|
57
|
-
|
|
82
|
+
## 适合谁用
|
|
58
83
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
84
|
+
| 你遇到的问题 | Vision Toolkit 给出的结果 |
|
|
85
|
+
|---|---|
|
|
86
|
+
| **纯文本模型看不到截图** | 在 DSH Web 中直接粘贴图片；插件会把图片交给视觉模型，再把与当前问题相关的证据交回文本模型 |
|
|
87
|
+
| **图片描述很多，但没有重点** | 问“报错在哪里”“提交按钮是什么颜色”，得到围绕当前任务的回答，而不是通用看图作文 |
|
|
88
|
+
| **知道有按钮，却不知道在哪** | 返回原图像素坐标，并可生成带框或带编号的预览图 |
|
|
89
|
+
| **长截图 OCR 容易漏行、重复** | 分块读取并保留 Markdown、分块图、清单和审计结果，失败后也能继续 |
|
|
90
|
+
| **UI 还原只能凭感觉调** | 把参考图和实现截图做像素对比，给出差异比例、重点区域、热力图和 JSON 报告 |
|
|
91
|
+
| **截图里的素材无法继续使用** | 直接得到裁剪图、透明 PNG、主色板或可编辑 SVG，而不只是一段文字 |
|
|
62
92
|
|
|
63
|
-
|
|
93
|
+
## 实际效果
|
|
64
94
|
|
|
65
|
-
###
|
|
95
|
+
### 在 DSH 里直接粘贴图片提问
|
|
66
96
|
|
|
67
97
|
<p align="center">
|
|
68
|
-
<img src="assets/
|
|
69
|
-
<img src="assets/upstream/infographic-result.webp" width="49%" alt="上游使用 HTML 和 CSS 还原出的可编辑模型训练信息图。" />
|
|
98
|
+
<img src="assets/dsh-view-example.png" width="82%" alt="DSH Web 中，纯文本 DeepSeek 模型通过 Vision Toolkit 回答用户粘贴图片里的内容" />
|
|
70
99
|
</p>
|
|
71
100
|
|
|
72
|
-
|
|
101
|
+
*用户粘贴一张图片，纯文本模型自动切换到对应的 `Vision Toolkit` 变体，并围绕用户的问题读取画面。*
|
|
73
102
|
|
|
74
|
-
###
|
|
103
|
+
### 从截图到可编辑页面
|
|
75
104
|
|
|
76
105
|
<p align="center">
|
|
77
|
-
<img src="assets/upstream/
|
|
78
|
-
<img src="assets/upstream/
|
|
106
|
+
<img src="assets/upstream/infographic-reference.webp" width="49%" alt="用于还原的信息图原始截图" />
|
|
107
|
+
<img src="assets/upstream/infographic-result.webp" width="49%" alt="根据截图还原出的可编辑 HTML 和 CSS 页面" />
|
|
79
108
|
</p>
|
|
80
109
|
|
|
81
|
-
|
|
110
|
+
*左：参考截图；右：用 HTML/CSS 还原出的可编辑结果。视觉结果可以继续进入截图和像素对比流程，而不是停在“描述图片”。*
|
|
82
111
|
|
|
83
|
-
###
|
|
112
|
+
### 从手绘稿到可用界面
|
|
84
113
|
|
|
85
114
|
<p align="center">
|
|
86
|
-
<img src="assets/
|
|
87
|
-
<img src="assets/
|
|
115
|
+
<img src="assets/upstream/ui-sketch.webp" width="49%" alt="作为 UI 还原输入的手绘 JupyterLab 界面草图" />
|
|
116
|
+
<img src="assets/upstream/ui-result.webp" width="49%" alt="根据手绘参考还原出的 JupyterLab 工作区界面" />
|
|
88
117
|
</p>
|
|
89
118
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
DSH Vision Toolkit 把这套工作流带进 DSH，让结果可以直接成为文件、坐标、可度量的对比报告，或同一会话中的下一步行动。
|
|
119
|
+
*左：手绘参考；右：根据参考还原的可用界面。*
|
|
93
120
|
|
|
94
|
-
|
|
121
|
+
### 让“差不多”变成“可验证”
|
|
95
122
|
|
|
96
|
-
|
|
123
|
+
仓库内置了一个可复现的 UI 还原示例：Agent 会先渲染参考图和实现，再用差异区域、热力图和 JSON 报告指导下一轮修正。
|
|
97
124
|
|
|
98
125
|
<p>
|
|
99
|
-
<img src="examples/ui-restoration/assets/initial.png" width="49%" alt="
|
|
100
|
-
<img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="
|
|
126
|
+
<img src="examples/ui-restoration/assets/initial.png" width="49%" alt="像素对比前仍有布局和样式偏差的初版 UI" />
|
|
127
|
+
<img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="经过视觉定位和像素对比后的 UI 实现" />
|
|
101
128
|
</p>
|
|
102
129
|
|
|
103
|
-
|
|
104
|
-
|---|---|
|
|
105
|
-
| 参考图 | 可打开、可编辑的 HTML 实现 |
|
|
106
|
-
| 第一次对比 | 主要问题区域的差异为 `6.04%` |
|
|
107
|
-
| 最终对比 | 在 `1200 × 720` 下达到 `0%` 差异 |
|
|
108
|
-
|
|
109
|
-
## 它为什么好用
|
|
110
|
-
|
|
111
|
-
- **直接提出你要解决的问题。** “提交按钮在哪里？”和“这张截图为什么和参考图不一样？”都会进入针对性的视觉分析，而不是得到一段泛泛的描述。
|
|
112
|
-
- **拿到可以继续使用的证据。** Agent 会返回坐标、OCR、测量结果、JSON 和文件，方便打开或交给下一步处理。
|
|
113
|
-
- **工作流留在 DSH 里。** Credential、Settings、产物、Web 卡片和 Headless 结果都与会话的其他内容放在一起。
|
|
114
|
-
- **能本地处理就不调用远程模型。** 裁剪、描摹、像素对比、颜色分析、前景提取和 HTML 截图都不消耗视觉 API 请求。
|
|
115
|
-
- **让迭代有终点。** 参考图 → 实现 → 截图 → 像素对比，把 UI 还原变成有数据支撑的闭环。
|
|
116
|
-
|
|
117
|
-
## 三步开始使用
|
|
130
|
+
## 快速开始：三步完成
|
|
118
131
|
|
|
119
|
-
|
|
132
|
+
### 1. 安装
|
|
120
133
|
|
|
121
134
|
```sh
|
|
122
135
|
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
123
|
-
dsh plugin --profile headless add @anionex/dsh-vision-toolkit
|
|
124
136
|
```
|
|
125
137
|
|
|
126
|
-
|
|
127
|
-
2. 如果要使用远程视觉模型，选择 DSH Credential，然后执行**测试 API 连接**和**测试视觉模型**。
|
|
128
|
-
3. 在会话中粘贴图片或把图片放进工作区，调用 `/vision-tools`，提出一个明确的视觉任务。
|
|
129
|
-
|
|
130
|
-
如果使用较旧的 DSH launcher，安装前可能需要在 Profile 中设置 `nodeLinker: hoisted` 和 `autoInstallPeers: false`。当前 launcher 会自动修复这些设置。
|
|
131
|
-
|
|
132
|
-
安装后重启正在运行的 Web Profile，打开 **设置 → 视觉工具**，先执行**测试 API 连接**，再执行**测试视觉模型**。新安装会自动使用内置免费 Gemma 4 提供方，不需要 API Key 或 DSH Credential。若要使用其他提供方，请修改端点、模型或协议，并配置对应的 DSH Credential。
|
|
133
|
-
|
|
134
|
-
## 加入交流群
|
|
138
|
+
Headless Profile 也可以安装：
|
|
135
139
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
<p align="center">
|
|
139
|
-
<img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="260">
|
|
140
|
-
</p>
|
|
141
|
-
本地裁剪、SVG、像素、颜色、前景和 HTML 操作不需要视觉 API Credential。
|
|
142
|
-
|
|
143
|
-
> **不需要本地路径。** 普通 npm 安装保持默认的 `runtime.mode: managed` 即可。`runtime.agentVisionToolkitPath` 只面向明确需要外部固定 checkout 的开发者或受控部署。
|
|
144
|
-
|
|
145
|
-
<details>
|
|
146
|
-
<summary><strong>技术架构</strong></summary>
|
|
147
|
-
|
|
148
|
-
## 工作原理
|
|
149
|
-
|
|
150
|
-
```mermaid
|
|
151
|
-
flowchart LR
|
|
152
|
-
User["Workspace image or local HTML"] --> Skill["vision-tools Skill"]
|
|
153
|
-
Skill --> Activate["Agent-scoped activation"]
|
|
154
|
-
Activate --> Tools["10 independent vision_* tools"]
|
|
155
|
-
Tools --> Runtime["Shared VisionToolkitRuntime"]
|
|
156
|
-
Credentials["DSH Credentials"] --> Runtime
|
|
157
|
-
Settings["Web Settings and health"] --> Runtime
|
|
158
|
-
Runtime --> Upstream["Pinned agent-vision-toolkit"]
|
|
159
|
-
Runtime --> Remote["Configured vision API"]
|
|
160
|
-
Upstream --> Result["Text, coordinates, JSON"]
|
|
161
|
-
Remote --> Result
|
|
162
|
-
Runtime --> Artifacts["Workspace Artifacts"]
|
|
163
|
-
Result --> Session["Reconstructable Session log"]
|
|
164
|
-
Artifacts --> Web["Preview, download, or open file"]
|
|
140
|
+
```sh
|
|
141
|
+
dsh plugin --profile headless add @anionex/dsh-vision-toolkit
|
|
165
142
|
```
|
|
166
143
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
</details>
|
|
170
|
-
|
|
171
|
-
## 工具
|
|
144
|
+
### 2. 重启并确认
|
|
172
145
|
|
|
173
|
-
|
|
174
|
-
|---|---|---|---|
|
|
175
|
-
| `vision_glance` | 远程视觉 API | 描述、针对性回答、OCR 或多图比较 | 无 |
|
|
176
|
-
| `vision_ground` | 远程视觉 API；可选本地预览 | 目标、原图尺寸和像素框 | 可选标注 PNG |
|
|
177
|
-
| `vision_detect` | 远程视觉 API；可选本地预览 | 带编号的元素清单和原图像素框 | 可选编号 PNG |
|
|
178
|
-
| `vision_trace` | 本地固定 vtracer 流水线 | SVG 几何状态、路径数、缩放和大小 | SVG |
|
|
179
|
-
| `vision_crop` | 本地 Pillow 流水线 | 实际像素框、尺寸、格式和裁剪边界状态 | PNG 或 JPEG |
|
|
180
|
-
| `vision_pixel_diff` | 本地 NumPy/Pillow 流水线 | 差异比例和排序后的网格区域 | PNG 热力图和 JSON 报告 |
|
|
181
|
-
| `vision_long_screenshot_ocr` | 本地切分/审计；除 `splitOnly=true` 外执行远程 OCR | 分块边界、复用状态、完成状态和运行目录 | Markdown、manifest、边界审计、分块 PNG 和 OCR 伴随文件 |
|
|
182
|
-
| `vision_extract_foreground` | 本地固定提取流水线 | 选区、连通分量数、前景覆盖率和尺寸 | 透明 PNG |
|
|
183
|
-
| `vision_dominant_colors` | 本地固定颜色分析 | 提取的调色板或有像素证据的候选色排序 | 无 |
|
|
184
|
-
| `vision_html_screenshot` | 本地 Chrome/Chromium/Edge 适配器 | 已授权源文件信息、视口和渲染尺寸 | PNG |
|
|
146
|
+
重启正在运行的 Web Profile，打开 **设置 → 视觉工具**。默认免费服务已经配置好；你可以直接运行**测试视觉模型**确认连接。
|
|
185
147
|
|
|
186
|
-
|
|
148
|
+
首次启动会自动准备隔离运行环境，因此需要能访问 Python 包缓存或网络。普通安装不需要下载 `agent-vision-toolkit` 源码，也不需要设置本地路径。
|
|
187
149
|
|
|
188
|
-
|
|
189
|
-
<summary><strong>高级模型行为</strong></summary>
|
|
190
|
-
|
|
191
|
-
## 渐进式模型暴露
|
|
192
|
-
|
|
193
|
-
运行时就绪状态属于整个 Profile，但 10 个视觉执行工具的 schema 属于具体 Agent。Agent 加载 `vision-tools` 前，插件只贡献很小的 `vision_toolkit_activate` 引导工具；该 Agent 的请求 schema 中没有视觉执行工具。标准 `skill` 工具以 `name="vision-tools"` 成功加载后，会为下一模型步骤自动挂载全部 10 个工具并隐藏引导工具。直接调用 `/vision-tools` 会注入 skill 指令；如果此时视觉工具仍不可见，这些指令要求调用一次 `vision_toolkit_activate`。激活只影响当前 Agent；Session 中存在与打包 skill 版本匹配的持久证据时可以恢复，并持续到 Agent 或插件被释放。
|
|
194
|
-
|
|
195
|
-
健康检查、连接测试以及插件/上游版本检查属于 Web Settings 管理操作。`vision_toolkit_health` 和 `vision_toolkit_version` 不是模型工具，即使视觉执行工具已经激活，也永远不会进入 Agent schema。
|
|
196
|
-
|
|
197
|
-
## 纯文本模型的图片输入变体
|
|
198
|
-
|
|
199
|
-
纯文本模型路由仍会获得同名的兄弟模型条目：`<模型名> (Vision Toolkit)`，挂在对应的提供方分组下。但 DSH 原生图片块不会把粘贴附件的本地路径传给模型，因此所有桥接路径都会先把图片复制进会话工作区，再把绝对路径暴露给模型。模型随后可以把这个路径传给 `vision_glance` 或其他视觉工具。当服务端图片输入变体启用时，同一个模型可见消息还会包含与 `agent-vision-toolkit` 对齐、带 focus hint 的 `[vision model description]` 证据；路径仍然保留，模型可以再次针对更具体的问题调用视觉工具。会话日志保存可复用的路径引用，UI 保留粘贴记录。
|
|
200
|
-
|
|
201
|
-
插件会自动为宿主明确声明为纯文本的每个模型注册变体（例如 DeepSeek 对话家族）。粘贴处理是全自动的：当当前模型被确认为纯文本、且它的变体已注册时，浏览器端集成会自动把会话切换到变体（会有一条简短提示说明新模型名），随后粘贴走原生流程，无需手动切换模型。宿主依据浏览器从实时模型目录读到的精确模型路由来裁决，模型选择器标签作为兜底；无法确认或支持图片的路由一律保持原生流程，而"纯文本但没有变体"的模型（例如变体被关闭时）继续走"粘贴转路径"：图片被复制进会话工作区，输入框里插入的是它的路径文本。
|
|
202
|
-
|
|
203
|
-
默认启用图片输入变体自动切换。描述转换需要已配置的视觉提供方及其 Credential；当运行时未就绪或读取失败时，请求链路上的图片块仍保留工作区路径，并追加与上游兼容的 `[vision unavailable: ...]` 提示，而不是让整轮失败。桥接不会把注入的上下文文件当作当前用户意图；如果图片来自工具调用，则使用最新的助手段落作为关注提示。用 `imageInputVariants.enabled: false` 关闭变体，用 `imageInputVariants.providers` 限制被包装的路由，或用 `imageInputVariants.autoSwitch: false` 改回只注入路径的接管流程。
|
|
150
|
+
### 3. 粘贴图片，直接说你要做什么
|
|
204
151
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
## 运行要求
|
|
208
|
-
|
|
209
|
-
- 启用 Web 或 Headless Profile 的 DeepSeek Harness，并确保 `dsh plugin` 可以使用 `pnpm`。
|
|
210
|
-
- Python 3.11 或更高版本。Managed 模式会创建隔离环境，用户无需手工安装上游 CLI（命令行界面）或 Python 包。
|
|
211
|
-
- 首次启用 managed 运行时需要联网；如果配置的软件包缓存已有 `runtime/requirements.lock` 中的精确版本，则无需联网。
|
|
212
|
-
- 内置免费 Gemma 4 提供方可直接用于 `vision_glance`、`vision_ground`、`vision_detect` 和非仅切分长截图 OCR。只有改用自定义 OpenAI 兼容或 Anthropic 端点时才需要 DSH Credential；本地工具不依赖任何远程提供方。
|
|
213
|
-
- 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge；未安装受支持浏览器时，其他工具保持可用。
|
|
214
|
-
- 输入必须是会话工作区或显式 `allowedDirs` 根目录内的 PNG、JPEG、GIF 或 WebP。
|
|
215
|
-
|
|
216
|
-
## 安装与生命周期
|
|
152
|
+
在会话中粘贴截图，或把图片放进会话工作区，然后调用 `/vision-tools`。例如：
|
|
217
153
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
224
|
-
dsh plugin --profile headless add @anionex/dsh-vision-toolkit
|
|
225
|
-
dsh --profile web --dump-config | grep vision-toolkit
|
|
226
|
-
dsh --profile headless --dump-config | grep vision-toolkit
|
|
154
|
+
```text
|
|
155
|
+
看看这张截图，告诉我报错原因和最值得先修的地方。
|
|
156
|
+
找到右上角的登录按钮，返回原图像素坐标并生成带框预览图。
|
|
157
|
+
把这个图标裁出来并转成 SVG。
|
|
158
|
+
按照 reference.png 还原页面，每轮截图后做像素对比，直到主要差异消失。
|
|
227
159
|
```
|
|
228
160
|
|
|
229
|
-
|
|
161
|
+
## 常见任务
|
|
230
162
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
163
|
+
| 任务 | 推荐工作流 |
|
|
164
|
+
|---|---|
|
|
165
|
+
| 图片问答 / 截图排障 | 看图 → 围绕当前问题回答 → 必要时继续定位 |
|
|
166
|
+
| 找按钮、图标或文字区域 | 定位目标 → 返回像素框 → 生成标注预览 |
|
|
167
|
+
| 提取截图里的图标 | 定位 → 裁剪 → 描摹为 SVG |
|
|
168
|
+
| 读取长网页截图 | 自动分块 → OCR → 合并 Markdown → 检查边界 |
|
|
169
|
+
| 复刻网页或组件 | 参考图 → 实现 → HTML 截图 → 像素对比 → 继续修正 |
|
|
170
|
+
| 提取品牌视觉 | 裁剪区域 → 主色分析 → 前景提取 → 导出透明 PNG |
|
|
234
171
|
|
|
235
|
-
|
|
172
|
+
## 工具一览
|
|
236
173
|
|
|
237
|
-
|
|
238
|
-
- id: vision-toolkit
|
|
239
|
-
disabled: true
|
|
240
|
-
```
|
|
174
|
+
插件提供 10 个可以单独调用、也可以组合使用的视觉工具：
|
|
241
175
|
|
|
242
|
-
|
|
176
|
+
| 工具 | 最适合解决的问题 | 主要结果 |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| `vision_glance` | “这张图里发生了什么？” | 针对性回答、描述、OCR、多图比较 |
|
|
179
|
+
| `vision_ground` | “我要找的东西在哪？” | 原图像素坐标、可选带框预览 |
|
|
180
|
+
| `vision_detect` | “图里有哪些按钮/图标/元素？” | 编号元素清单、坐标、可选预览 |
|
|
181
|
+
| `vision_crop` | “把这块区域单独取出来” | PNG 或 JPEG 裁剪图 |
|
|
182
|
+
| `vision_trace` | “把这个图形变成可编辑矢量” | SVG |
|
|
183
|
+
| `vision_pixel_diff` | “实现和参考图到底差在哪？” | 差异比例、重点区域、热力图、JSON |
|
|
184
|
+
| `vision_long_screenshot_ocr` | “读完这张很长的截图” | Markdown、分块图、清单和审计结果 |
|
|
185
|
+
| `vision_extract_foreground` | “把主体抠出来” | 透明 PNG |
|
|
186
|
+
| `vision_dominant_colors` | “这块区域用了哪些主要颜色？” | 主色板或候选色排序 |
|
|
187
|
+
| `vision_html_screenshot` | “按精确视口渲染本地页面，或一次捕获整页” | PNG 和可选的 CSS `pageHeight` |
|
|
243
188
|
|
|
244
|
-
|
|
189
|
+
坐标始终使用原图像素格式 `x1,y1,x2,y2`，因此定位结果可以直接交给裁剪、描摹或后续自动化。
|
|
245
190
|
|
|
246
|
-
|
|
191
|
+
对于长 HTML 文档，传入 `fullPage=true`。请求的宽高仍作为布局视口，生成的 PNG 会覆盖完整文档，并以 CSS 像素返回 `pageHeight`。
|
|
247
192
|
|
|
248
|
-
|
|
249
|
-
dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit
|
|
250
|
-
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
251
|
-
```
|
|
193
|
+
## 工作原理
|
|
252
194
|
|
|
253
|
-
|
|
195
|
+
插件把远程图片理解和可重复的本地图片处理放进同一套 Agent 工作流。展开下面的流程可以查看具体边界。
|
|
254
196
|
|
|
255
|
-
|
|
197
|
+
<details>
|
|
198
|
+
<summary><strong>架构与图片输入行为</strong></summary>
|
|
256
199
|
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
|
|
200
|
+
```mermaid
|
|
201
|
+
flowchart LR
|
|
202
|
+
Image["截图或本地 HTML"] --> Skill["vision-tools Skill"]
|
|
203
|
+
Skill --> Agent["文本 Agent 选择任务"]
|
|
204
|
+
Agent --> Vision["需要理解图片时调用视觉模型"]
|
|
205
|
+
Agent --> Local["裁剪、SVG、像素等任务在本地处理"]
|
|
206
|
+
Vision --> Result["回答、OCR、坐标"]
|
|
207
|
+
Local --> Artifact["PNG、SVG、热力图、JSON"]
|
|
208
|
+
Result --> Session["继续推理和行动"]
|
|
209
|
+
Artifact --> Session
|
|
260
210
|
```
|
|
261
211
|
|
|
262
|
-
|
|
212
|
+
视觉能力来自打包的固定版本 `agent-vision-toolkit`。DSH 插件负责安装、会话级工具暴露、Credential、路径校验、取消、超时、结果文件和 Web 展示。运行时不会在后台拉取上游 `main`。
|
|
263
213
|
|
|
264
|
-
|
|
214
|
+
对于明确标记为纯文本的模型，插件会注册 `<模型名> (Vision Toolkit)` 变体。默认情况下，在 DSH Web 粘贴图片时会自动切换到该变体，并把图片路径与带当前任务重点的视觉描述一起交给模型。
|
|
265
215
|
|
|
266
|
-
|
|
267
|
-
dsh plugin --profile web remove @anionex/dsh-vision-toolkit
|
|
268
|
-
dsh plugin --profile headless remove @anionex/dsh-vision-toolkit
|
|
269
|
-
```
|
|
216
|
+
</details>
|
|
270
217
|
|
|
271
|
-
|
|
218
|
+
## 配置与限制
|
|
272
219
|
|
|
273
|
-
|
|
220
|
+
### 默认免费服务
|
|
274
221
|
|
|
275
|
-
|
|
222
|
+
默认配置使用：
|
|
276
223
|
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
baseUrl: https://vision.anionex.me/v1
|
|
282
|
-
credential: ANIONEX_FREE_VISION
|
|
283
|
-
model: gemma-4-26b-a4b-it
|
|
284
|
-
protocol: openai
|
|
285
|
-
anthropicThinking: omit
|
|
286
|
-
userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36
|
|
287
|
-
language: zh
|
|
288
|
-
timeoutMs: 60000
|
|
289
|
-
maxImageBytes: 4194304
|
|
290
|
-
maxImagePixels: 20000000
|
|
291
|
-
concurrency: 4
|
|
292
|
-
runtime:
|
|
293
|
-
mode: managed
|
|
294
|
-
allowedDirs: []
|
|
295
|
-
imageInputVariants:
|
|
296
|
-
enabled: true
|
|
297
|
-
providers: []
|
|
298
|
-
autoSwitch: true
|
|
224
|
+
```text
|
|
225
|
+
Base URL: https://vision.anionex.me/v1
|
|
226
|
+
Model: qwen/qwen3.6-27b
|
|
227
|
+
API Key: 不需要用户配置
|
|
299
228
|
```
|
|
300
229
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
| 字段 | 默认值 | 契约 |
|
|
304
|
-
|---|---|---|
|
|
305
|
-
| `provider.baseUrl` | `https://vision.anionex.me/v1` | 内置免费 OpenAI 兼容端点；自定义提供方可改用其他基础 URL，使用时会去除结尾斜杠 |
|
|
306
|
-
| `provider.credential` | `ANIONEX_FREE_VISION` | 免费服务的只读内置引用；自定义提供方使用 DSH Credential 引用，而不是密钥值 |
|
|
307
|
-
| `provider.model` | `gemma-4-26b-a4b-it` | 远程工具使用的多模态模型名 |
|
|
308
|
-
| `provider.protocol` | `openai` | `openai` 发送 Chat Completions 请求；`anthropic` 发送原生 Messages 请求 |
|
|
309
|
-
| `provider.anthropicThinking` | `omit` | Anthropic thinking 字段。`omit` 不发送 thinking 字段，兼容性最好；仅当所选模型明确支持时使用 `disabled` 或 `adaptive`，提供方返回 HTTP 400 时应先恢复 `omit`。 |
|
|
310
|
-
| `provider.userAgent` | 浏览器兼容默认值 | 视觉请求和显式连接测试发送的 User-Agent；可为提供方或代理兼容性覆盖 |
|
|
311
|
-
| `language` | `zh` | 视觉输出语言：`zh` 或 `en` |
|
|
312
|
-
| `timeoutMs` | `60000` | 完整操作截止时间，1000-600000 毫秒；每个工具可请求更窄的覆盖值 |
|
|
313
|
-
| `maxImageBytes` | `4194304` | 每张输入图片的编码字节上限；内置免费服务最多接受 4 MiB |
|
|
314
|
-
| `maxImagePixels` | `20000000` | 每张输入图片的解码像素上限；内置免费服务最多接受 20,000,000 像素 |
|
|
315
|
-
| `concurrency` | `4` | 每个会话内的并发操作数，1-16 |
|
|
316
|
-
| `runtime.mode` | `managed` | `managed` 使用打包快照；`external` 只接受精确固定版本 |
|
|
317
|
-
| `runtime.agentVisionToolkitPath` | 未设置 | `external` 模式必填；必须是精确导出快照或固定 commit 的干净 Git checkout |
|
|
318
|
-
| `runtime.python` | 未设置 | 可选的 Python 3.11+ 引导程序/解释器覆盖值 |
|
|
319
|
-
| `allowedDirs` | `[]` | 额外的 realpath 解析输入根目录；会话工作区始终允许 |
|
|
320
|
-
| `imageInputVariants.enabled` | `true` | 为纯文本模型路由在模型选择器中注册图片输入变体条目 |
|
|
321
|
-
| `imageInputVariants.providers` | `[]` | 按提供方 id 限制被包装的上游路由；为空时包装所有符合条件的路由 |
|
|
322
|
-
| `imageInputVariants.autoSwitch` | `true` | 粘贴时自动切换到图片输入变体；模型同时收到工作区路径和聚焦描述。设为 `false` 时只走路径接管 |
|
|
323
|
-
|
|
324
|
-
### Credential
|
|
325
|
-
|
|
326
|
-
内置免费提供方使用固定的 `ANIONEX_FREE_VISION` 引用，不接受也不会保存用户 API Key。修改端点、模型或协议切换到自定义提供方后，只写的 **API 密钥** 输入框会自动解锁；填写后保存，会把密钥写入高级设置中的 **凭据名称** 引用。Headless 部署可以在 `$DSH_HOME/.credentials.yaml` 中预置该自定义引用。
|
|
327
|
-
|
|
328
|
-
Settings 只保存引用，不保存值。浏览器不会读取已保存的密钥，保存成功后输入框也会立即清空而不是回显。每次远程操作都会重新解析引用，并只把值注入对应子进程环境。插件排除用户 `.env`、checkout `.env`、`PYTHONPATH`、`PYTHONHOME`、`VIRTUAL_ENV` 和用户 site-packages，避免环境中的 Python 或上游配置覆盖选定的 DSH 提供方。日志、错误、工具结果、产物元数据和 Settings 响应都不包含密钥。
|
|
329
|
-
|
|
330
|
-
### 内置免费服务限制
|
|
331
|
-
|
|
332
|
-
公开服务是共享的零配置默认入口，不是无限量私有端点。限制由代理执行，并以 OpenAI 风格错误返回明确的原因代码和可读提示；限流响应还会携带 `Retry-After` 与请求额度响应头。
|
|
230
|
+
这是共享的免费入口，不是无限量私有服务。当前限制如下：
|
|
333
231
|
|
|
334
232
|
| 限制 | 当前值 |
|
|
335
233
|
|---|---:|
|
|
336
234
|
| 单客户端 | 每个 UTC 日 100 次 |
|
|
337
|
-
| 全局服务 | 每个 UTC 日
|
|
338
|
-
|
|
|
339
|
-
|
|
|
340
|
-
|
|
|
341
|
-
|
|
|
235
|
+
| 全局服务 | 每个 UTC 日 3,000 次 |
|
|
236
|
+
| 突发请求 | 60 秒内 60 次 |
|
|
237
|
+
| 单张图片大小 | 4 MiB |
|
|
238
|
+
| 单张图片像素 | 20,000,000 |
|
|
239
|
+
| 单次输出 | 512 tokens |
|
|
342
240
|
|
|
343
|
-
|
|
241
|
+
这些限制用于保护共享额度、避免异常大图占满内存或请求时间。触发限制时，服务会返回明确的原因代码和可读提示；限流响应还会带上 `Retry-After`，不会只得到一个含糊的“模型失败”。
|
|
344
242
|
|
|
345
|
-
|
|
243
|
+
### 使用自己的视觉模型
|
|
346
244
|
|
|
347
|
-
|
|
245
|
+
如果你需要更高额度、私有端点或其他模型，可以在 **设置 → 视觉工具** 中修改提供方，并把 API Key 保存为 DSH Credential。Settings 只保存 Credential 引用，不会回显密钥。
|
|
348
246
|
|
|
349
|
-
|
|
247
|
+
也可以在 Profile patch 中配置：
|
|
350
248
|
|
|
351
249
|
```yaml
|
|
352
250
|
- id: vision-toolkit
|
|
353
251
|
config:
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
252
|
+
provider:
|
|
253
|
+
baseUrl: https://api.example.com/v1
|
|
254
|
+
credential: MY_VISION_KEY
|
|
255
|
+
model: your-vision-model
|
|
256
|
+
protocol: openai
|
|
358
257
|
```
|
|
359
258
|
|
|
360
|
-
|
|
259
|
+
支持 OpenAI Chat Completions 兼容端点和 Anthropic Messages。Web Settings 页面还可以调整超时、图片限制、并发、运行时和图片输入变体。
|
|
361
260
|
|
|
362
|
-
|
|
261
|
+
### 运行要求
|
|
363
262
|
|
|
364
|
-
|
|
263
|
+
- DeepSeek Harness Web 或 Headless Profile。
|
|
264
|
+
- Node.js `^22.19.0` 或 `>=24.0.0`。
|
|
265
|
+
- Python 3.11+；插件默认自动创建隔离环境。
|
|
266
|
+
- 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge。
|
|
267
|
+
- 图片需为 PNG、JPEG、GIF 或 WebP，并位于会话工作区或明确允许的目录中。
|
|
365
268
|
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
“保存并应用”会验证完整配置，准备候选 Python/上游运行时，提交 Settings revision，最后才原子切换 generation。候选被拒绝时，之前的 generation 继续服务，页面也会把这种状态与运行时确实不可用区分开来。“重新加载”始终恢复后端已保存的权威值，即使 revision 没有变化也会丢弃被拒绝的浏览器草稿。初始启动无法准备运行时时，Settings 路由仍可用于提交有效配置并激活首个 generation。陈旧浏览器 revision 不会覆盖较新的保存结果，而是返回冲突；刷新后再重试。只读 Settings 提供方允许查看和健康检查，但禁用保存。
|
|
369
|
-
|
|
370
|
-
“运行健康检查”只执行本地检查。“测试 API 连接”是显式操作，会把已配置 Credential 发送到 `GET /models`；OpenAI 使用 Bearer 认证，Anthropic 使用 `x-api-key` 与 `anthropic-version`。这个轻量测试不会上传图片，也不会创建 completion。“测试视觉模型”会另行把插件自带的 `assets/vision-model-test.png` 通过与 `vision_glance` 相同的多模态运行路径发送出去；它会创建一次真实 completion，并用于权威确认所选端点、Credential、模型、协议和上游账户确实能够处理图片。视觉模型检查卡会单独显示“已实测”“未测试”或“测试失败”Tag，避免把 `/models` 返回 HTTP 200 误认为图片调用成功。插件加载和普通 Settings 读取不会发送这两类请求。
|
|
371
|
-
|
|
372
|
-
健康检查、连接测试以及插件/上游版本检查属于 Web Settings 管理能力，而不是模型工具，因此其 schema 永远不会占用 agent 请求上下文。
|
|
373
|
-
|
|
374
|
-
## 产物与展示
|
|
375
|
-
|
|
376
|
-
会生成产物的工具只能写入 `<workspace>/.dsh-vision-toolkit/artifacts`，写入形式为单个已验证文件或原子提交的运行目录。每个模型可见产物描述都包含路径、文件名、MIME 类型、种类、说明、来源工具、预览意图和字节数，因此 Headless agent 无需浏览器支持，也能在后续调用中复用该路径。提交 trace SVG 前，运行时会把它作为 XML 解析：允许标准声明与注释，但拒绝 doctype、格式错误或多根文档、非 SVG namespace，以及上游报告与实际路径数/字节数不一致的结果。
|
|
269
|
+
<details>
|
|
270
|
+
<summary><strong>安装、升级、禁用和卸载</strong></summary>
|
|
377
271
|
|
|
378
|
-
|
|
272
|
+
```sh
|
|
273
|
+
dsh plugin --profile web update @anionex/dsh-vision-toolkit
|
|
274
|
+
dsh plugin --profile web remove @anionex/dsh-vision-toolkit
|
|
275
|
+
```
|
|
379
276
|
|
|
380
|
-
|
|
277
|
+
如果从已停止发布的 `@dsh-external/dsh-vision-toolkit` 迁移，请先移除旧包，再安装 `@anionex/dsh-vision-toolkit`。
|
|
381
278
|
|
|
382
|
-
|
|
279
|
+
需要临时禁用时，在 Profile patch 中设置：
|
|
383
280
|
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
vision_detect image="screenshot.png" category="buttons" preview=true
|
|
388
|
-
vision_crop image="screenshot.png" region="1067,841,1108,881"
|
|
389
|
-
vision_trace image="icon.png" color=true output="icon.svg"
|
|
390
|
-
vision_pixel_diff original="reference.png" rebuilt="actual.png" runName="comparison"
|
|
391
|
-
vision_long_screenshot_ocr image="page.png" mode="general" jobs=2
|
|
392
|
-
vision_extract_foreground image="logo.png" mode="color"
|
|
393
|
-
vision_dominant_colors image="screen.png" region="0,0,600,300" top=8
|
|
394
|
-
vision_html_screenshot source="implementation.html" width=1200 height=720
|
|
281
|
+
```yaml
|
|
282
|
+
- id: vision-toolkit
|
|
283
|
+
disabled: true
|
|
395
284
|
```
|
|
396
285
|
|
|
397
|
-
|
|
286
|
+
重新启用或升级 Web 插件后，请重启 Web Profile 并刷新页面。
|
|
398
287
|
|
|
399
|
-
|
|
288
|
+
</details>
|
|
400
289
|
|
|
401
|
-
|
|
290
|
+
### 插件更新
|
|
402
291
|
|
|
403
|
-
|
|
404
|
-
npm run example:ui-restoration
|
|
405
|
-
npm run example:ui-restoration:write
|
|
406
|
-
```
|
|
292
|
+
在 **设置 → 视觉工具** 中，**检查更新**会查询当前 Profile 的 npm registry。若插件是直接 registry 依赖，**自动更新并重启**只会安装用户刚确认的准确版本，完成校验后重启明确允许自重启、且使用固定 `--port` 的 POSIX Web 进程。本地/workspace/file/git/URL 安装、Windows、动态端口、只读 Profile 和由进程管理器托管的实例只允许检查版本。
|
|
407
293
|
|
|
408
|
-
|
|
294
|
+
更新器会在修改前重新验证 Profile，备份原始 manifest 与 lockfile，并持有带所有权 token 的跨进程锁。只有重启辅助进程确认备份可读且锁交接成功后，当前 Web 进程才会退出；如果更新前 Profile 已经可用，替代进程还必须同时报告目标插件版本和 Runtime 已就绪，失败时会恢复原始 manifest/lockfile，并用 frozen lockfile 重建依赖后再尝试恢复之前的准确版本。若自动恢复本身失败，备份与锁会保留，路径写入 `$DSH_HOME/logs/vision-toolkit-restart.log`。脱离原管理器的自重启需要设置 `DSH_VISION_TOOLKIT_ALLOW_DETACHED_RESTART=1`；存在未保存的 Settings 或 API Key 时不能安装。
|
|
409
295
|
|
|
410
|
-
##
|
|
296
|
+
## 常见问题
|
|
411
297
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
298
|
+
| 问题 | 处理方式 |
|
|
299
|
+
|---|---|
|
|
300
|
+
| 粘贴图片后仍提示模型不支持图片 | 重启 Web Profile 并刷新页面，确认当前模型已切换到带 `(Vision Toolkit)` 的变体；也可以把图片先放进会话工作区，再调用 `/vision-tools` |
|
|
301
|
+
| 免费服务提示 429 | 按错误中的 `Retry-After` 等待后重试；如果需要稳定高额度，切换到自己的视觉端点 |
|
|
302
|
+
| 图片过大或像素超限 | 先裁剪或缩放图片；错误会明确显示是字节还是像素限制 |
|
|
303
|
+
| 自定义 Credential 缺失 | 在 **设置 → 视觉工具** 填写 API Key，并确认 Credential 名称与配置一致 |
|
|
304
|
+
| 首次运行时准备失败 | 检查 Python 3.11+、网络或包缓存、磁盘权限，然后在 Settings 中重新测试 |
|
|
305
|
+
| 找不到 Chrome | 安装 Chrome、Chromium 或 Edge；只有 HTML 截图不可用，其他工具不受影响 |
|
|
306
|
+
| 产物无法预览 | 使用“打开文件”或结果中的工作区路径；预览 URL 只在 Web 路由可用时存在 |
|
|
420
307
|
|
|
421
|
-
|
|
308
|
+
## 项目状态与限制
|
|
422
309
|
|
|
423
|
-
|
|
310
|
+
当前版本专注于截图理解、视觉定位、OCR、素材提取、UI 还原和像素级验证。它不是视频/音频/摄像头输入系统，也不会自动点击 GUI；交互式标注编辑、远程服务集群、模型投票和跨会话视觉缓存也不在当前范围内。
|
|
424
311
|
|
|
425
|
-
|
|
426
|
-
|---|---|
|
|
427
|
-
| `Model "..." does not support image input. (attachment-error)` | 图片走了 DSH 的模型原生附件通道，纯文本模型会在 Skill 或 Vision Toolkit 运行前拒绝该轮。启用图片输入变体时这很少发生：粘贴会自动把会话切换到 `<模型名> (Vision Toolkit)` 变体。若变体被关闭或自动切换被禁用，请使用 DSH Paste Input 的附件按钮、粘贴或拖放流程，让文件先复制到会话工作区并以路径形式进入消息，再调用 `/vision-tools`。安装或升级任一浏览器插件后，需要重启 Web Profile 并刷新页面。 |
|
|
428
|
-
| Credential 显示缺失 | 在 Web 设置页的 **API 密钥** 中粘贴密钥，确认高级设置中的 **凭据名称** 与 `provider.credential` 一致，保存后重新运行健康检查。Headless 部署可以在 `$DSH_HOME/.credentials.yaml` 中预置同名引用。本地工具不需要它。 |
|
|
429
|
-
| 运行时准备失败 | 查看 Settings 中的运行时错误，检查 Python 3.11+、软件包缓存/网络、磁盘权限和精确 external 固定版本。修正候选后再保存；当前 generation 不受影响。 |
|
|
430
|
-
| 找不到 Chrome | 安装 Chrome、Chromium 或 Edge，或让其中一个可被运行环境发现。只有 `vision_html_screenshot` 不可用。 |
|
|
431
|
-
| macOS 弹出钥匙串对话框 | 确认安装的是当前构建产物，且没有遗留的外部 `html_shot`/headless Chrome 进程。当前启动使用 mock keychain 和一次性 profile；取消对话框，不要重置登录钥匙串。 |
|
|
432
|
-
| 输入或输出路径被拒绝 | 把文件移入会话工作区，或有意将真实目录加入 `allowedDirs`；移除会逃逸的符号链接。输出参数只接受文件名，不接受绝对路径或嵌套路径。 |
|
|
433
|
-
| 视觉服务返回 401/403 | 替换 Credential 值，或选择正确的引用和端点。错误内容保持脱敏。 |
|
|
434
|
-
| 视觉服务返回 429 | 等待提供方限流窗口结束后重试，或降低 `concurrency`。插件不会静默切换提供方。 |
|
|
435
|
-
| 操作超时或被取消 | 在 1000-600000 毫秒范围内提高 `timeoutMs`、减少图片/分块工作量，或在取消后重新执行。子进程/请求会随操作停止。 |
|
|
436
|
-
| Settings 保存冲突 | 重新加载分区以取得当前 revision，重新应用目标修改，再次保存。 |
|
|
437
|
-
| Settings 只读 | 更换活动 Settings 提供方，或编辑其拥有的 Profile 配置；插件不能绕过提供方可写性。 |
|
|
438
|
-
| 无法预览产物 | 使用“打开文件”或模型可见路径。只有 Web HTTP 路由已挂载时才存在预览/下载 URL。 |
|
|
439
|
-
|
|
440
|
-
## 开发与验证
|
|
312
|
+
## 开发与社区
|
|
441
313
|
|
|
442
314
|
```sh
|
|
443
315
|
pnpm install --frozen-lockfile --trust-lockfile
|
|
444
316
|
pnpm run verify:portable
|
|
445
317
|
pnpm run build
|
|
446
318
|
pnpm test
|
|
447
|
-
pnpm
|
|
448
|
-
pnpm pack --dry-run
|
|
319
|
+
TSX_TSCONFIG_PATH=tsconfig.json pnpm dlx tsx scripts/ui-restoration-example.ts --check
|
|
449
320
|
```
|
|
450
321
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
## 项目状态与范围
|
|
458
|
-
|
|
459
|
-
版本 `0.1.12` 是当前公开 npm 版本。产品重点是截图理解、视觉定位、OCR、素材提取、UI 还原和 DSH Web/Headless Profile 中的像素级验证。Web 上传、拖拽、摄像头/视频/音频/文档输入、交互式标注框编辑、GUI 自动点击、远程服务集群、模型路由、模型投票和跨会话视觉缓存不属于当前产品范围。
|
|
460
|
-
|
|
461
|
-
<details>
|
|
462
|
-
<summary><strong>维护者范围说明</strong></summary>
|
|
463
|
-
|
|
464
|
-
稳定的 `ctx.visionToolkit` 服务和能力发现 API 会等到独立插件成为真实消费方后再发布。这样可以让公开集成面建立在已验证的使用场景上，而不是未经验证的生态契约上。
|
|
465
|
-
|
|
466
|
-
</details>
|
|
322
|
+
- 贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
|
323
|
+
- Bug、功能建议和使用问题请提交到 [GitHub Issues](https://github.com/Anionex/dsh-vision-toolkit/issues)；渠道说明见 [SUPPORT.md](SUPPORT.md)。
|
|
324
|
+
- 安全漏洞请按 [SECURITY.md](SECURITY.md) 私下报告。
|
|
325
|
+
- 版本变化见 [CHANGELOG.md](CHANGELOG.md)，赞助说明见 [FUNDING.md](FUNDING.md)。
|
|
326
|
+
- 通用视觉工具、跨 Agent 接入和视觉任务方法论请访问上游 [agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit)。
|
|
467
327
|
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
- 可复现缺陷、范围明确的功能建议和使用问题请提交到 [GitHub Issues](https://github.com/Anionex/dsh-vision-toolkit/issues)；如何选择渠道见 [SUPPORT.md](SUPPORT.md)。
|
|
472
|
-
- 安全漏洞必须按 [SECURITY.md](SECURITY.md) 私下报告，不要创建公开 Issue。
|
|
473
|
-
- 版本与兼容性变化记录在 [CHANGELOG.md](CHANGELOG.md)。
|
|
474
|
-
- 可选赞助方式与用途见 [FUNDING.md](FUNDING.md)；赞助不购买路线图优先级或私有支持。
|
|
475
|
-
- 通用工具箱、跨 Harness 接入、视觉任务 playbook 和官方实跑案例请访问上游[项目网站](https://agent-vision.anionex.me)与[代码仓库](https://github.com/Anionex/agent-vision-toolkit)。
|
|
476
|
-
- 如果 `agent-vision-toolkit` 的算法或方法节省了时间，欢迎为上游 star、分享、贡献或赞助；DSH 专属缺陷和集成需求请提交到本仓库。
|
|
477
|
-
|
|
478
|
-
[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 由 [Anionex](https://anionex.me/) 创建。本仓库维护它面向 DeepSeek Harness 的原生集成：DSH 侧负责生命周期、安全、结构化 schema、Credentials、产物和 Web 展示；视觉算法与可复用 playbook 继续由上游项目维护。
|
|
328
|
+
<p align="center">
|
|
329
|
+
<img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="240" />
|
|
330
|
+
</p>
|
|
479
331
|
|
|
480
|
-
|
|
332
|
+
[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 由 [Anionex](https://anionex.me/) 创建。本仓库维护它面向 DeepSeek Harness 的原生集成。
|
|
481
333
|
|
|
482
334
|
## 许可证
|
|
483
335
|
|
|
484
|
-
插件采用 MIT
|
|
336
|
+
插件采用 [MIT License](LICENSE)。打包的上游快照保留其原始 MIT 许可证，见 [`vendor/agent-vision-toolkit/LICENSE`](vendor/agent-vision-toolkit/LICENSE)。
|