@anionex/dsh-vision-toolkit 0.1.11 → 0.1.13
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 +192 -343
- package/README.zh.md +192 -357
- package/assets/hero-v2.png +0 -0
- 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 +172 -6
- package/lib/client.js.map +1 -1
- package/lib/config.js +10 -3
- package/lib/config.js.map +1 -1
- package/lib/image-input-variants.js +65 -23
- package/lib/image-input-variants.js.map +1 -1
- package/lib/paste-images.js +6 -1
- package/lib/paste-images.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 +2 -2
- package/lib/types/config.d.ts.map +1 -1
- package/lib/types/image-input-variants.d.ts +6 -4
- package/lib/types/image-input-variants.d.ts.map +1 -1
- package/lib/types/paste-images.d.ts +10 -0
- package/lib/types/paste-images.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 +1 -1
- package/src/client/index.tsx +228 -5
- package/src/config.ts +13 -5
- package/src/image-input-variants.ts +81 -23
- package/src/paste-images.ts +7 -2
- 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/skills/vision-tools/scripts/html_shot.py +323 -11
- package/assets/hero.png +0 -0
package/README.zh.md
CHANGED
|
@@ -1,484 +1,319 @@
|
|
|
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
|
-
<a href="https://github.com/Anionex/dsh-vision-toolkit/releases/tag/v0.1.11"><img src="https://img.shields.io/badge/release-v0.1.11-5B4CF0?style=flat-square" alt="Release v0.1.11" /></a>
|
|
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://www.npmjs.com/package/@anionex/dsh-vision-toolkit)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](cordis.patch.yml)
|
|
18
13
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
</p>
|
|
14
|
+
**给 DSH 里的纯文本 Agent 装上眼睛：粘贴图片就能问，找到元素就能继续操作，还能把 UI 还原做到有数据可验。**
|
|
15
|
+
|
|
16
|
+
🌐 [English](README.md) ｜ **中文**
|
|
17
|
+
|
|
18
|
+
</div>
|
|
25
19
|
|
|
26
|
-
|
|
20
|
+
如果你在 DeepSeek Harness（DSH）里使用 DeepSeek 等纯文本模型，可能已经遇到过这些问题：模型看不到截图、只能得到一段泛泛的图片描述、找不到按钮的准确位置，或者还原出来的页面“看起来差不多”，却不知道到底差了多少。
|
|
27
21
|
|
|
28
|
-
|
|
22
|
+
DSH Vision Toolkit 把 [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 变成一个原生 DSH 插件。安装后，Agent 不只会“看图”，还会围绕当前任务读取、定位、裁剪、描摹、还原和验证图片。
|
|
29
23
|
|
|
30
|
-
|
|
24
|
+
> **安装即可使用。** 默认接入内置免费 Gemma 4 视觉服务，不需要申请 API Key；裁图、像素对比、颜色分析、前景提取、SVG 描摹和网页截图等本地工具也不消耗视觉 API 请求。
|
|
31
25
|
|
|
32
26
|
```sh
|
|
33
27
|
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
34
28
|
```
|
|
35
29
|
|
|
36
|
-
npm 包已经包含视觉工具快照，并默认使用托管运行时。**普通安装不需要下载源码，也不需要填写 `agentVisionToolkitPath`。**
|
|
37
|
-
|
|
38
30
|
**上游工具箱：** [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) · **项目网站：** [agent-vision.anionex.me](https://agent-vision.anionex.me)
|
|
39
31
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
32
|
+
<details>
|
|
33
|
+
<summary><strong>目录</strong></summary>
|
|
34
|
+
|
|
35
|
+
- [最近更新](#最近更新)
|
|
36
|
+
- [它解决什么问题](#它解决什么问题)
|
|
37
|
+
- [实际效果](#实际效果)
|
|
38
|
+
- [亮点](#亮点)
|
|
39
|
+
- [快速开始：三步完成](#快速开始三步完成)
|
|
40
|
+
- [常见任务](#常见任务)
|
|
41
|
+
- [工具一览](#工具一览)
|
|
42
|
+
- [配置与限制](#配置与限制)
|
|
43
|
+
- [常见问题](#常见问题)
|
|
44
|
+
- [开发与社区](#开发与社区)
|
|
50
45
|
|
|
51
|
-
|
|
46
|
+
</details>
|
|
52
47
|
|
|
53
|
-
##
|
|
48
|
+
## 最近更新
|
|
54
49
|
|
|
55
|
-
|
|
50
|
+
- **2026-08-16 · Windows Python：** 支持 Microsoft Store Python，解决部分 Windows 用户首次创建隔离环境失败的问题。
|
|
51
|
+
- **2026-08-16 · 免费视觉升级：** 默认模型切换到 Gemma 4，解决免 Key 方案看图效果不足的问题。
|
|
52
|
+
- **2026-08-16 · 图片粘贴：** 文本模型自动切换到 `(Vision Toolkit)` 变体并保留工作区路径，解决粘贴图片被拦截或后续无法复用的问题。
|
|
53
|
+
- **2026-08-16 · 免费额度：** 单客户端、全局和突发额度分别提高到 `100/日`、`400/日` 和 `20/分钟`，解决早期用户容易撞限而共享额度闲置的问题。
|
|
54
|
+
- **2026-08-16 · 真实模型测试：** Settings 新增完整图片请求测试，解决 `/models` 可访问却不能证明模型真的会看图的问题。
|
|
56
55
|
|
|
57
|
-
|
|
56
|
+
## 它解决什么问题
|
|
58
57
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
| 你遇到的问题 | Vision Toolkit 给出的结果 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| **纯文本模型看不到截图** | 在 DSH Web 中直接粘贴图片；插件会把图片交给视觉模型，再把与当前问题相关的证据交回文本模型 |
|
|
61
|
+
| **图片描述很多，但没有重点** | 问“报错在哪里”“提交按钮是什么颜色”，得到围绕当前任务的回答，而不是通用看图作文 |
|
|
62
|
+
| **知道有按钮，却不知道在哪** | 返回原图像素坐标，并可生成带框或带编号的预览图 |
|
|
63
|
+
| **长截图 OCR 容易漏行、重复** | 分块读取并保留 Markdown、分块图、清单和审计结果，失败后也能继续 |
|
|
64
|
+
| **UI 还原只能凭感觉调** | 把参考图和实现截图做像素对比，给出差异比例、重点区域、热力图和 JSON 报告 |
|
|
65
|
+
| **截图里的素材无法继续使用** | 直接得到裁剪图、透明 PNG、主色板或可编辑 SVG，而不只是一段文字 |
|
|
62
66
|
|
|
63
|
-
|
|
67
|
+
## 实际效果
|
|
64
68
|
|
|
65
|
-
###
|
|
69
|
+
### 在 DSH 里直接粘贴图片提问
|
|
66
70
|
|
|
67
71
|
<p align="center">
|
|
68
|
-
<img src="assets/
|
|
69
|
-
<img src="assets/upstream/infographic-result.webp" width="49%" alt="上游使用 HTML 和 CSS 还原出的可编辑模型训练信息图。" />
|
|
72
|
+
<img src="assets/dsh-view-example.png" width="82%" alt="DSH Web 中，纯文本 DeepSeek 模型通过 Vision Toolkit 回答用户粘贴图片里的内容" />
|
|
70
73
|
</p>
|
|
71
74
|
|
|
72
|
-
|
|
75
|
+
*用户粘贴一张图片，纯文本模型自动切换到对应的 `Vision Toolkit` 变体，并围绕用户的问题读取画面。*
|
|
73
76
|
|
|
74
|
-
###
|
|
77
|
+
### 从截图到可编辑页面
|
|
75
78
|
|
|
76
79
|
<p align="center">
|
|
77
|
-
<img src="assets/upstream/
|
|
78
|
-
<img src="assets/upstream/
|
|
80
|
+
<img src="assets/upstream/infographic-reference.webp" width="49%" alt="用于还原的信息图原始截图" />
|
|
81
|
+
<img src="assets/upstream/infographic-result.webp" width="49%" alt="根据截图还原出的可编辑 HTML 和 CSS 页面" />
|
|
79
82
|
</p>
|
|
80
83
|
|
|
81
|
-
|
|
84
|
+
*左：参考截图；右：用 HTML/CSS 还原出的可编辑结果。视觉结果可以继续进入截图和像素对比流程，而不是停在“描述图片”。*
|
|
82
85
|
|
|
83
|
-
###
|
|
86
|
+
### 从手绘稿到可用界面
|
|
84
87
|
|
|
85
88
|
<p align="center">
|
|
86
|
-
<img src="assets/
|
|
87
|
-
<img src="assets/
|
|
89
|
+
<img src="assets/upstream/ui-sketch.webp" width="49%" alt="作为 UI 还原输入的手绘 JupyterLab 界面草图" />
|
|
90
|
+
<img src="assets/upstream/ui-result.webp" width="49%" alt="根据手绘参考还原出的 JupyterLab 工作区界面" />
|
|
88
91
|
</p>
|
|
89
92
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
DSH Vision Toolkit 把这套工作流带进 DSH，让结果可以直接成为文件、坐标、可度量的对比报告，或同一会话中的下一步行动。
|
|
93
|
+
*左：手绘参考；右：根据参考还原的可用界面。*
|
|
93
94
|
|
|
94
|
-
|
|
95
|
+
### 让“差不多”变成“可验证”
|
|
95
96
|
|
|
96
|
-
|
|
97
|
+
仓库内置了一个可复现的 UI 还原示例：初版与参考图的差异为 **6.04%**，经过定位和修正后，在 `1200 × 720` 下达到 **0% 像素差异**。
|
|
97
98
|
|
|
98
99
|
<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="
|
|
100
|
+
<img src="examples/ui-restoration/assets/initial.png" width="49%" alt="像素对比前仍有布局和样式偏差的初版 UI" />
|
|
101
|
+
<img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="经过视觉定位和像素对比后达到零差异的最终 UI" />
|
|
101
102
|
</p>
|
|
102
103
|
|
|
103
|
-
|
|
104
|
-
|---|---|
|
|
105
|
-
| 参考图 | 可打开、可编辑的 HTML 实现 |
|
|
106
|
-
| 第一次对比 | 主要问题区域的差异为 `6.04%` |
|
|
107
|
-
| 最终对比 | 在 `1200 × 720` 下达到 `0%` 差异 |
|
|
108
|
-
|
|
109
|
-
## 它为什么好用
|
|
104
|
+
## 亮点
|
|
110
105
|
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
106
|
+
- **安装后就能免费用。** 新用户默认使用内置 Gemma 4 服务，不需要注册新的模型平台，也不需要先填写 Key。
|
|
107
|
+
- **不只描述图片，而是解决当前问题。** Agent 会把当前任务作为视觉关注点，优先返回这一轮真正要用到的内容。
|
|
108
|
+
- **返回可以继续工作的结果。** 坐标、OCR、透明 PNG、SVG、截图、热力图和 JSON 都能直接交给下一步。
|
|
109
|
+
- **特别适合 UI 和截图工程。** 从参考图、元素定位、素材提取到 HTML 截图和像素对比，形成完整闭环。
|
|
110
|
+
- **能本地做的就本地做。** 裁剪、描摹、像素对比、颜色、前景和 HTML 截图不需要上传到视觉模型。
|
|
111
|
+
- **Web 与 Headless 使用同一套能力。** Web 中可以预览和下载产物，Headless 中仍会得到可重放的结构化结果和文件路径。
|
|
116
112
|
|
|
117
|
-
##
|
|
113
|
+
## 快速开始：三步完成
|
|
118
114
|
|
|
119
|
-
|
|
115
|
+
### 1. 安装
|
|
120
116
|
|
|
121
117
|
```sh
|
|
122
118
|
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
123
|
-
dsh plugin --profile headless add @anionex/dsh-vision-toolkit
|
|
124
119
|
```
|
|
125
120
|
|
|
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
|
-
## 加入交流群
|
|
135
|
-
|
|
136
|
-
欢迎加入 `agent-vision-toolkit` 项目交流群，交流使用经验、反馈问题并提出建议。
|
|
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
|
-
## 工作原理
|
|
121
|
+
Headless Profile 也可以安装：
|
|
149
122
|
|
|
150
|
-
```
|
|
151
|
-
|
|
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"]
|
|
123
|
+
```sh
|
|
124
|
+
dsh plugin --profile headless add @anionex/dsh-vision-toolkit
|
|
165
125
|
```
|
|
166
126
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
</details>
|
|
170
|
-
|
|
171
|
-
## 工具
|
|
172
|
-
|
|
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 |
|
|
185
|
-
|
|
186
|
-
插件不重新实现视觉算法。DSH 侧只负责验证路径与限制、解析 Credential、用 argv 向量调用固定上游脚本、解析精确输出契约、分类失败、描述文件，并把结果投影给模型和 Web 客户端。
|
|
187
|
-
|
|
188
|
-
<details>
|
|
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 或插件被释放。
|
|
127
|
+
### 2. 重启并确认
|
|
194
128
|
|
|
195
|
-
|
|
129
|
+
重启正在运行的 Web Profile，打开 **设置 → 视觉工具**。默认免费服务已经配置好；你可以直接运行**测试视觉模型**确认连接。
|
|
196
130
|
|
|
197
|
-
|
|
131
|
+
首次启动会自动准备隔离运行环境，因此需要能访问 Python 包缓存或网络。普通安装不需要下载 `agent-vision-toolkit` 源码，也不需要设置本地路径。
|
|
198
132
|
|
|
199
|
-
|
|
133
|
+
### 3. 粘贴图片，直接说你要做什么
|
|
200
134
|
|
|
201
|
-
|
|
135
|
+
在会话中粘贴截图，或把图片放进会话工作区，然后调用 `/vision-tools`。例如：
|
|
202
136
|
|
|
203
|
-
|
|
204
|
-
|
|
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
|
-
## 安装与生命周期
|
|
217
|
-
|
|
218
|
-
### 安装
|
|
219
|
-
|
|
220
|
-
将 Bundle 安装到需要暴露能力的每个 Profile：
|
|
221
|
-
|
|
222
|
-
```sh
|
|
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
|
|
137
|
+
```text
|
|
138
|
+
看看这张截图，告诉我报错原因和最值得先修的地方。
|
|
139
|
+
找到右上角的登录按钮，返回原图像素坐标并生成带框预览图。
|
|
140
|
+
把这个图标裁出来并转成 SVG。
|
|
141
|
+
按照 reference.png 还原页面，每轮截图后做像素对比，直到主要差异消失。
|
|
227
142
|
```
|
|
228
143
|
|
|
229
|
-
|
|
144
|
+
## 常见任务
|
|
230
145
|
|
|
231
|
-
|
|
146
|
+
| 任务 | 推荐工作流 |
|
|
147
|
+
|---|---|
|
|
148
|
+
| 图片问答 / 截图排障 | 看图 → 围绕当前问题回答 → 必要时继续定位 |
|
|
149
|
+
| 找按钮、图标或文字区域 | 定位目标 → 返回像素框 → 生成标注预览 |
|
|
150
|
+
| 提取截图里的图标 | 定位 → 裁剪 → 描摹为 SVG |
|
|
151
|
+
| 读取长网页截图 | 自动分块 → OCR → 合并 Markdown → 检查边界 |
|
|
152
|
+
| 复刻网页或组件 | 参考图 → 实现 → HTML 截图 → 像素对比 → 继续修正 |
|
|
153
|
+
| 提取品牌视觉 | 裁剪区域 → 主色分析 → 前景提取 → 导出透明 PNG |
|
|
232
154
|
|
|
233
|
-
|
|
155
|
+
## 工具一览
|
|
234
156
|
|
|
235
|
-
|
|
157
|
+
插件提供 10 个可以单独调用、也可以组合使用的视觉工具：
|
|
236
158
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
159
|
+
| 工具 | 最适合解决的问题 | 主要结果 |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| `vision_glance` | “这张图里发生了什么？” | 针对性回答、描述、OCR、多图比较 |
|
|
162
|
+
| `vision_ground` | “我要找的东西在哪？” | 原图像素坐标、可选带框预览 |
|
|
163
|
+
| `vision_detect` | “图里有哪些按钮/图标/元素？” | 编号元素清单、坐标、可选预览 |
|
|
164
|
+
| `vision_crop` | “把这块区域单独取出来” | PNG 或 JPEG 裁剪图 |
|
|
165
|
+
| `vision_trace` | “把这个图形变成可编辑矢量” | SVG |
|
|
166
|
+
| `vision_pixel_diff` | “实现和参考图到底差在哪？” | 差异比例、重点区域、热力图、JSON |
|
|
167
|
+
| `vision_long_screenshot_ocr` | “读完这张很长的截图” | Markdown、分块图、清单和审计结果 |
|
|
168
|
+
| `vision_extract_foreground` | “把主体抠出来” | 透明 PNG |
|
|
169
|
+
| `vision_dominant_colors` | “这块区域用了哪些主要颜色？” | 主色板或候选色排序 |
|
|
170
|
+
| `vision_html_screenshot` | “按精确视口渲染本地页面，或一次捕获整页” | PNG 和可选的 CSS `pageHeight` |
|
|
243
171
|
|
|
244
|
-
|
|
172
|
+
坐标始终使用原图像素格式 `x1,y1,x2,y2`，因此定位结果可以直接交给裁剪、描摹或后续自动化。
|
|
245
173
|
|
|
246
|
-
|
|
174
|
+
对于长 HTML 文档，传入 `fullPage=true`。请求的宽高仍作为布局视口，生成的 PNG 会覆盖完整文档，并以 CSS 像素返回 `pageHeight`。
|
|
247
175
|
|
|
248
|
-
|
|
249
|
-
dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit
|
|
250
|
-
dsh plugin --profile web add @anionex/dsh-vision-toolkit
|
|
251
|
-
```
|
|
176
|
+
## 工作原理
|
|
252
177
|
|
|
253
|
-
|
|
178
|
+
插件把远程图片理解和可重复的本地图片处理放进同一套 Agent 工作流。展开下面的流程可以查看具体边界。
|
|
254
179
|
|
|
255
|
-
|
|
180
|
+
<details>
|
|
181
|
+
<summary><strong>架构与图片输入行为</strong></summary>
|
|
256
182
|
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
|
|
183
|
+
```mermaid
|
|
184
|
+
flowchart LR
|
|
185
|
+
Image["截图或本地 HTML"] --> Skill["vision-tools Skill"]
|
|
186
|
+
Skill --> Agent["文本 Agent 选择任务"]
|
|
187
|
+
Agent --> Vision["需要理解图片时调用视觉模型"]
|
|
188
|
+
Agent --> Local["裁剪、SVG、像素等任务在本地处理"]
|
|
189
|
+
Vision --> Result["回答、OCR、坐标"]
|
|
190
|
+
Local --> Artifact["PNG、SVG、热力图、JSON"]
|
|
191
|
+
Result --> Session["继续推理和行动"]
|
|
192
|
+
Artifact --> Session
|
|
260
193
|
```
|
|
261
194
|
|
|
262
|
-
|
|
195
|
+
视觉能力来自打包的固定版本 `agent-vision-toolkit`。DSH 插件负责安装、会话级工具暴露、Credential、路径校验、取消、超时、结果文件和 Web 展示。运行时不会在后台拉取上游 `main`。
|
|
263
196
|
|
|
264
|
-
|
|
197
|
+
对于明确标记为纯文本的模型，插件会注册 `<模型名> (Vision Toolkit)` 变体。默认情况下，在 DSH Web 粘贴图片时会自动切换到该变体，并把图片路径与带当前任务重点的视觉描述一起交给模型。
|
|
265
198
|
|
|
266
|
-
|
|
267
|
-
dsh plugin --profile web remove @anionex/dsh-vision-toolkit
|
|
268
|
-
dsh plugin --profile headless remove @anionex/dsh-vision-toolkit
|
|
269
|
-
```
|
|
199
|
+
</details>
|
|
270
200
|
|
|
271
|
-
|
|
201
|
+
## 配置与限制
|
|
272
202
|
|
|
273
|
-
|
|
203
|
+
### 默认免费服务
|
|
274
204
|
|
|
275
|
-
|
|
205
|
+
默认配置使用：
|
|
276
206
|
|
|
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: false
|
|
207
|
+
```text
|
|
208
|
+
Base URL: https://vision.anionex.me/v1
|
|
209
|
+
Model: gemma-4-26b-a4b-it
|
|
210
|
+
API Key: 不需要用户配置
|
|
299
211
|
```
|
|
300
212
|
|
|
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` | `false` | 是否在粘贴时自动把纯文本会话切换到图片输入变体；默认关闭，纯文本模型继续走 DSH 兼容的"粘贴转路径"流程 |
|
|
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` 与请求额度响应头。
|
|
213
|
+
这是共享的免费入口，不是无限量私有服务。当前限制如下：
|
|
333
214
|
|
|
334
215
|
| 限制 | 当前值 |
|
|
335
216
|
|---|---:|
|
|
336
217
|
| 单客户端 | 每个 UTC 日 100 次 |
|
|
337
218
|
| 全局服务 | 每个 UTC 日 400 次 |
|
|
338
|
-
|
|
|
339
|
-
|
|
|
340
|
-
|
|
|
341
|
-
|
|
|
219
|
+
| 突发请求 | 60 秒内 20 次 |
|
|
220
|
+
| 单张图片大小 | 4 MiB |
|
|
221
|
+
| 单张图片像素 | 20,000,000 |
|
|
222
|
+
| 单次输出 | 512 tokens |
|
|
342
223
|
|
|
343
|
-
|
|
224
|
+
这些限制用于保护共享额度、避免异常大图占满内存或请求时间。触发限制时，服务会返回明确的原因代码和可读提示；限流响应还会带上 `Retry-After`，不会只得到一个含糊的“模型失败”。
|
|
344
225
|
|
|
345
|
-
|
|
226
|
+
### 使用自己的视觉模型
|
|
346
227
|
|
|
347
|
-
|
|
228
|
+
如果你需要更高额度、私有端点或其他模型，可以在 **设置 → 视觉工具** 中修改提供方，并把 API Key 保存为 DSH Credential。Settings 只保存 Credential 引用，不会回显密钥。
|
|
348
229
|
|
|
349
|
-
|
|
230
|
+
也可以在 Profile patch 中配置：
|
|
350
231
|
|
|
351
232
|
```yaml
|
|
352
233
|
- id: vision-toolkit
|
|
353
234
|
config:
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
235
|
+
provider:
|
|
236
|
+
baseUrl: https://api.example.com/v1
|
|
237
|
+
credential: MY_VISION_KEY
|
|
238
|
+
model: your-vision-model
|
|
239
|
+
protocol: openai
|
|
358
240
|
```
|
|
359
241
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
## Web Settings
|
|
363
|
-
|
|
364
|
-
Web Profile 会注册 Vision Toolkit Settings 分区，可配置提供方 URL、Credential 引用、模型、OpenAI/Anthropic 协议、Anthropic thinking 模式、User-Agent、语言、超时、字节/像素限制、并发数、运行时模式、Python 覆盖值、external 源码路径和允许目录。该页面还会显示插件/上游版本、当前运行时 generation、不含密钥的 Credential configured/source/writable 状态、运行时路径、健康检查结果和产物路由可用性。
|
|
365
|
-
|
|
366
|
-
**插件更新**卡片会通过当前 Profile 配置的 npm registry 检查 `@anionex/dsh-vision-toolkit` 新版本。点击**自动更新并重启**后，插件只安装用户刚刚确认的准确版本，校验安装结果，启动独立重启辅助进程，再优雅重启 DSH Web；当前页面会等待新进程恢复，并在新插件版本开始服务后自动刷新。该操作要求同源请求，只能更新这个固定包，并且会串行执行；`link:`、`file:`、workspace、git、URL、传递依赖、无法唯一识别、只读或缺少 `pnpm` 的安装方式不会开放自动更新，避免覆盖本地开发源码。重启可能中断正在运行的任务，因此界面会要求再次确认。
|
|
242
|
+
支持 OpenAI Chat Completions 兼容端点和 Anthropic Messages。Web Settings 页面还可以调整超时、图片限制、并发、运行时和图片输入变体。
|
|
367
243
|
|
|
368
|
-
|
|
244
|
+
### 运行要求
|
|
369
245
|
|
|
370
|
-
|
|
246
|
+
- DeepSeek Harness Web 或 Headless Profile。
|
|
247
|
+
- Node.js `^22.19.0` 或 `>=24.0.0`。
|
|
248
|
+
- Python 3.11+；插件默认自动创建隔离环境。
|
|
249
|
+
- 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge。
|
|
250
|
+
- 图片需为 PNG、JPEG、GIF 或 WebP，并位于会话工作区或明确允许的目录中。
|
|
371
251
|
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
## 产物与展示
|
|
375
|
-
|
|
376
|
-
会生成产物的工具只能写入 `<workspace>/.dsh-vision-toolkit/artifacts`，写入形式为单个已验证文件或原子提交的运行目录。每个模型可见产物描述都包含路径、文件名、MIME 类型、种类、说明、来源工具、预览意图和字节数，因此 Headless agent 无需浏览器支持，也能在后续调用中复用该路径。提交 trace SVG 前，运行时会把它作为 XML 解析：允许标准声明与注释，但拒绝 doctype、格式错误或多根文档、非 SVG namespace，以及上游报告与实际路径数/字节数不一致的结果。
|
|
252
|
+
<details>
|
|
253
|
+
<summary><strong>安装、升级、禁用和卸载</strong></summary>
|
|
377
254
|
|
|
378
|
-
|
|
255
|
+
```sh
|
|
256
|
+
dsh plugin --profile web update @anionex/dsh-vision-toolkit
|
|
257
|
+
dsh plugin --profile web remove @anionex/dsh-vision-toolkit
|
|
258
|
+
```
|
|
379
259
|
|
|
380
|
-
|
|
260
|
+
如果从已停止发布的 `@dsh-external/dsh-vision-toolkit` 迁移，请先移除旧包，再安装 `@anionex/dsh-vision-toolkit`。
|
|
381
261
|
|
|
382
|
-
|
|
262
|
+
需要临时禁用时，在 Profile patch 中设置：
|
|
383
263
|
|
|
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
|
|
264
|
+
```yaml
|
|
265
|
+
- id: vision-toolkit
|
|
266
|
+
disabled: true
|
|
395
267
|
```
|
|
396
268
|
|
|
397
|
-
|
|
269
|
+
重新启用或升级 Web 插件后，请重启 Web Profile 并刷新页面。
|
|
398
270
|
|
|
399
|
-
|
|
271
|
+
</details>
|
|
400
272
|
|
|
401
|
-
|
|
273
|
+
### 插件更新
|
|
402
274
|
|
|
403
|
-
|
|
404
|
-
npm run example:ui-restoration
|
|
405
|
-
npm run example:ui-restoration:write
|
|
406
|
-
```
|
|
275
|
+
在 **设置 → 视觉工具** 中，**检查更新**会查询当前 Profile 的 npm registry。若插件是直接 registry 依赖，**自动更新并重启**只会安装用户刚确认的准确版本，完成校验后重启明确允许自重启、且使用固定 `--port` 的 POSIX Web 进程。本地/workspace/file/git/URL 安装、Windows、动态端口、只读 Profile 和由进程管理器托管的实例只允许检查版本。
|
|
407
276
|
|
|
408
|
-
|
|
277
|
+
更新器会在修改前重新验证 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
278
|
|
|
410
|
-
##
|
|
279
|
+
## 常见问题
|
|
411
280
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
281
|
+
| 问题 | 处理方式 |
|
|
282
|
+
|---|---|
|
|
283
|
+
| 粘贴图片后仍提示模型不支持图片 | 重启 Web Profile 并刷新页面，确认当前模型已切换到带 `(Vision Toolkit)` 的变体；也可以把图片先放进会话工作区，再调用 `/vision-tools` |
|
|
284
|
+
| 免费服务提示 429 | 按错误中的 `Retry-After` 等待后重试；如果需要稳定高额度，切换到自己的视觉端点 |
|
|
285
|
+
| 图片过大或像素超限 | 先裁剪或缩放图片；错误会明确显示是字节还是像素限制 |
|
|
286
|
+
| 自定义 Credential 缺失 | 在 **设置 → 视觉工具** 填写 API Key，并确认 Credential 名称与配置一致 |
|
|
287
|
+
| 首次运行时准备失败 | 检查 Python 3.11+、网络或包缓存、磁盘权限，然后在 Settings 中重新测试 |
|
|
288
|
+
| 找不到 Chrome | 安装 Chrome、Chromium 或 Edge；只有 HTML 截图不可用，其他工具不受影响 |
|
|
289
|
+
| 产物无法预览 | 使用“打开文件”或结果中的工作区路径；预览 URL 只在 Web 路由可用时存在 |
|
|
420
290
|
|
|
421
|
-
|
|
291
|
+
## 项目状态与限制
|
|
422
292
|
|
|
423
|
-
|
|
293
|
+
当前版本专注于截图理解、视觉定位、OCR、素材提取、UI 还原和像素级验证。它不是视频/音频/摄像头输入系统，也不会自动点击 GUI；交互式标注编辑、远程服务集群、模型投票和跨会话视觉缓存也不在当前范围内。
|
|
424
294
|
|
|
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
|
-
## 开发与验证
|
|
295
|
+
## 开发与社区
|
|
441
296
|
|
|
442
297
|
```sh
|
|
443
298
|
pnpm install --frozen-lockfile --trust-lockfile
|
|
444
299
|
pnpm run verify:portable
|
|
445
300
|
pnpm run build
|
|
446
301
|
pnpm test
|
|
447
|
-
pnpm
|
|
448
|
-
pnpm pack --dry-run
|
|
302
|
+
TSX_TSCONFIG_PATH=tsconfig.json pnpm dlx tsx scripts/ui-restoration-example.ts --check
|
|
449
303
|
```
|
|
450
304
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
## 项目状态与范围
|
|
458
|
-
|
|
459
|
-
版本 `0.1.11` 是当前公开 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>
|
|
467
|
-
|
|
468
|
-
## 社区与关于
|
|
305
|
+
- 贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
|
306
|
+
- Bug、功能建议和使用问题请提交到 [GitHub Issues](https://github.com/Anionex/dsh-vision-toolkit/issues)；渠道说明见 [SUPPORT.md](SUPPORT.md)。
|
|
307
|
+
- 安全漏洞请按 [SECURITY.md](SECURITY.md) 私下报告。
|
|
308
|
+
- 版本变化见 [CHANGELOG.md](CHANGELOG.md)，赞助说明见 [FUNDING.md](FUNDING.md)。
|
|
309
|
+
- 通用视觉工具、跨 Agent 接入和视觉任务方法论请访问上游 [agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit)。
|
|
469
310
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
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 继续由上游项目维护。
|
|
311
|
+
<p align="center">
|
|
312
|
+
<img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="240" />
|
|
313
|
+
</p>
|
|
479
314
|
|
|
480
|
-
|
|
315
|
+
[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 由 [Anionex](https://anionex.me/) 创建。本仓库维护它面向 DeepSeek Harness 的原生集成。
|
|
481
316
|
|
|
482
317
|
## 许可证
|
|
483
318
|
|
|
484
|
-
插件采用 MIT
|
|
319
|
+
插件采用 [MIT License](LICENSE)。打包的上游快照保留其原始 MIT 许可证，见 [`vendor/agent-vision-toolkit/LICENSE`](vendor/agent-vision-toolkit/LICENSE)。
|