@anionex/dsh-vision-toolkit 0.1.12 → 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.
Files changed (49) hide show
  1. package/README.i18n.yaml +3 -3
  2. package/README.md +192 -343
  3. package/README.zh.md +192 -357
  4. package/docs/requirements-traceability/README.i18n.yaml +2 -2
  5. package/docs/requirements-traceability/README.md +1 -1
  6. package/docs/requirements-traceability/README.zh.md +1 -1
  7. package/lib/client.js +172 -6
  8. package/lib/client.js.map +1 -1
  9. package/lib/plugin-update.js +1011 -0
  10. package/lib/plugin-update.js.map +1 -0
  11. package/lib/runtime-install.js +61 -1
  12. package/lib/runtime-install.js.map +1 -1
  13. package/lib/runtime.js +20 -3
  14. package/lib/runtime.js.map +1 -1
  15. package/lib/skill.js +7 -3
  16. package/lib/skill.js.map +1 -1
  17. package/lib/tools.js +3 -2
  18. package/lib/tools.js.map +1 -1
  19. package/lib/types/client/index.d.ts +55 -1
  20. package/lib/types/client/index.d.ts.map +1 -1
  21. package/lib/types/plugin-update.d.ts +111 -0
  22. package/lib/types/plugin-update.d.ts.map +1 -0
  23. package/lib/types/runtime-install.d.ts +11 -0
  24. package/lib/types/runtime-install.d.ts.map +1 -1
  25. package/lib/types/runtime.d.ts +3 -0
  26. package/lib/types/runtime.d.ts.map +1 -1
  27. package/lib/types/skill.d.ts +1 -1
  28. package/lib/types/skill.d.ts.map +1 -1
  29. package/lib/types/tools.d.ts.map +1 -1
  30. package/lib/types/upstream.d.ts +1 -0
  31. package/lib/types/upstream.d.ts.map +1 -1
  32. package/lib/types/web.d.ts +13 -1
  33. package/lib/types/web.d.ts.map +1 -1
  34. package/lib/upstream.js +20 -8
  35. package/lib/upstream.js.map +1 -1
  36. package/lib/web.js +46 -7
  37. package/lib/web.js.map +1 -1
  38. package/package.json +1 -1
  39. package/src/client/index.tsx +228 -5
  40. package/src/plugin-update.ts +1142 -0
  41. package/src/runtime-install.ts +77 -1
  42. package/src/runtime.ts +23 -3
  43. package/src/skill.ts +7 -3
  44. package/src/tools.ts +4 -2
  45. package/src/upstream.ts +21 -8
  46. package/src/web.ts +69 -3
  47. package/vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json +3 -3
  48. package/vendor/agent-vision-toolkit/skills/vision-tools/scripts/html_shot.py +323 -11
  49. /package/assets/{hero.png → hero-v2.png} +0 -0
package/README.md CHANGED
@@ -1,470 +1,319 @@
1
1
  <p align="center">
2
- <img src="assets/hero.png" alt="DSH Vision Toolkit — native visual engineering for text-only DeepSeek Harness agents" />
2
+ <img src="assets/hero-v2.png" alt="DSH Vision Toolkit helps text-only DeepSeek Harness agents understand images and complete visual tasks" />
3
3
  </p>
4
4
 
5
- <h1 align="center">DSH Vision Toolkit</h1>
5
+ <div align="center">
6
6
 
7
- <p align="center">
8
- English | <a href="https://github.com/Anionex/dsh-vision-toolkit/blob/main/README.zh.md">中文</a>
9
- </p>
7
+ # DSH Vision Toolkit
10
8
 
11
- <p align="center">
12
- <a href="https://dshfind.com/en/plugins/Anionex/dsh-vision-toolkit"><img src="https://img.shields.io/badge/recommended%20by-dshfind-FFD700?style=flat-square" alt="Recommended by dshfind" /></a>
13
- <a href="https://dshfind.com/en/plugins/Anionex/dsh-vision-toolkit"><img src="https://img.shields.io/badge/dshfind%20score-94%20%7C%20highest--rated%20plugin-5B4CF0?style=flat-square" alt="dshfind score: 94 — highest-rated plugin" /></a>
14
- <a href="https://x.com/anion_ex"><img src="https://img.shields.io/badge/-@anion__ex-000000?style=flat-square&amp;logo=x&amp;logoColor=white" alt="X: @anion_ex" /></a>
15
- <a href="https://github.com/Anionex/dsh-vision-toolkit/releases/tag/v0.1.12"><img src="https://img.shields.io/badge/release-v0.1.12-5B4CF0?style=flat-square" alt="Release v0.1.12" /></a>
16
- <a href="tests"><img src="https://img.shields.io/badge/verified-233%20tests-2EA44F?style=flat-square" alt="Verified: 233 tests" /></a>
17
- </p>
9
+ [![Recommended by dshfind](https://img.shields.io/badge/recommended%20by-dshfind-FFD700?style=flat-square)](https://dshfind.com/en/plugins/Anionex/dsh-vision-toolkit)
10
+ [![npm](https://img.shields.io/npm/v/@anionex/dsh-vision-toolkit?style=flat-square&color=5B4CF0)](https://www.npmjs.com/package/@anionex/dsh-vision-toolkit)
11
+ [![MIT](https://img.shields.io/badge/license-MIT-0B7285?style=flat-square)](LICENSE)
12
+ [![DSH](https://img.shields.io/badge/DSH-Web%20%2B%20Headless-5B4CF0?style=flat-square)](cordis.patch.yml)
18
13
 
19
- <p align="center">
20
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B7285?style=flat-square" alt="License: MIT" /></a>
21
- <a href="package.json"><img src="https://img.shields.io/badge/Node.js-%5E22.19%20%7C%20%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js ^22.19 or >=24" /></a>
22
- <a href="runtime/requirements.lock"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" alt="Python 3.11+" /></a>
23
- <a href="cordis.patch.yml"><img src="https://img.shields.io/badge/DSH-Web%20%2B%20Headless-5B4CF0?style=flat-square" alt="DSH Web and Headless profiles" /></a>
24
- </p>
14
+ **Give text-only DSH agents eyes: paste an image, ask a question, locate exact elements, extract assets, and verify UI restoration with measurable results.**
15
+
16
+ 🌐 **English** | [中文](README.zh.md)
17
+
18
+ </div>
25
19
 
26
- ## Give your DSH agent eyes
20
+ When you run DeepSeek or another text-only model in DeepSeek Harness (DSH), familiar problems appear quickly: the model cannot see a screenshot, generic image descriptions miss the point, buttons have no usable coordinates, and a rebuilt page may look “close enough” without any way to measure the remaining difference.
27
21
 
28
- Drop in a screenshot and let a text-only DeepSeek Harness agent inspect it, read it, locate elements, extract assets, rebuild interfaces, and measure whether the result matches.
22
+ DSH Vision Toolkit packages [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) as a native DSH plugin. It helps an agent do more than describe an image: the agent can read, locate, crop, trace, rebuild, and verify visual work around the task at hand.
29
23
 
30
- DSH Vision Toolkit packages [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) as a native DSH plugin. You get focused image Q&A, OCR, original-pixel coordinates, UI restoration, pixel comparison, downloadable results, and a Web Settings panel without assembling scripts by hand.
24
+ > **Install and use it immediately.** The default setup includes a free Gemma 4 vision service and requires no API key. Cropping, pixel diffing, color analysis, foreground extraction, SVG tracing, and HTML screenshots run locally without spending vision API requests.
31
25
 
32
26
  ```sh
33
27
  dsh plugin --profile web add @anionex/dsh-vision-toolkit
34
28
  ```
35
29
 
36
- The npm package includes the visual toolkit snapshot and uses a managed runtime by default. **Normal installation does not require a source checkout or an `agentVisionToolkitPath`.**
37
-
38
30
  **Upstream toolkit:** [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) · **Project website:** [agent-vision.anionex.me](https://agent-vision.anionex.me)
39
31
 
40
- ## What you can do
41
-
42
- | Goal | What the agent can deliver |
43
- |---|---|
44
- | Understand a screenshot | Focused answers, visual descriptions, multi-image comparison, and OCR |
45
- | Find an interface element | Original-image pixel coordinates with an optional labeled preview |
46
- | Rebuild a page from a reference | Screenshot rendering, region-by-region diagnosis, and measurable iteration |
47
- | Extract a usable asset | Cropped images, transparent foregrounds, dominant colors, or editable SVG |
48
- | Read a long screenshot | Auditable chunks, Markdown output, manifests, and resumable OCR runs |
49
- | Verify a visual result | A difference percentage, ranked mismatch regions, heatmap, and JSON report |
32
+ <details>
33
+ <summary><strong>Table of contents</strong></summary>
34
+
35
+ - [Recent updates](#recent-updates)
36
+ - [Problems it solves](#problems-it-solves)
37
+ - [See it in action](#see-it-in-action)
38
+ - [Highlights](#highlights)
39
+ - [Quick start: three steps](#quick-start-three-steps)
40
+ - [Common workflows](#common-workflows)
41
+ - [Toolbox](#toolbox)
42
+ - [Configuration and limits](#configuration-and-limits)
43
+ - [Troubleshooting](#troubleshooting)
44
+ - [Development and community](#development-and-community)
50
45
 
51
- You can use remote vision only where it adds value. Cropping, tracing, pixel comparison, color analysis, foreground extraction, and HTML screenshots run locally.
46
+ </details>
52
47
 
53
- ## See it in action
48
+ ## Recent updates
54
49
 
55
- The first example is a live DSH Web view. The next two examples come from the same `agent-vision-toolkit` lineage packaged with this plugin, and the last shows the workflow inside a live DeepSeek Harness Web session. See the [asset provenance record](assets/upstream/README.md) for source details.
50
+ - **2026-08-16 · Windows Python:** Added Microsoft Store Python support, fixing first-time isolated-runtime setup failures for affected Windows users.
51
+ - **2026-08-16 · Better free vision:** Switched the default model to Gemma 4, improving the no-key image-understanding path.
52
+ - **2026-08-16 · Image paste:** Text-only routes now switch to a `(Vision Toolkit)` variant and keep a workspace path, fixing blocked pastes and images that could not be reused later.
53
+ - **2026-08-16 · Higher free quotas:** Raised per-client, global, and burst limits to `100/day`, `400/day`, and `20/minute`, reducing avoidable rate-limit failures while the shared capacity is lightly used.
54
+ - **2026-08-16 · Real model test:** Added a full image-request test in Settings, fixing the false confidence caused by a successful `/models` request to a model that still cannot process images.
56
55
 
57
- ### DSH view example
56
+ ## Problems it solves
58
57
 
59
- <p align="center">
60
- <img src="assets/dsh-view-example.png" width="80%" alt="DSH Web session view in which a text-only DeepSeek-V4-Flash (Vision Toolkit) model answers a question about a pasted banner image." />
61
- </p>
58
+ | The problem | What Vision Toolkit delivers |
59
+ |---|---|
60
+ | **A text-only model cannot see a screenshot** | Paste an image in DSH Web; the plugin obtains visual evidence and returns the task-relevant parts to the text model |
61
+ | **The description is long but misses the point** | Ask “Where is the error?” or “What color is the submit button?” and receive an answer focused on that question |
62
+ | **The model knows an element exists but cannot act on it** | Get original-image pixel coordinates and an optional labeled or numbered preview |
63
+ | **Long-screenshot OCR skips or duplicates lines** | Split and audit the image while preserving Markdown, chunks, manifests, and resumable run state |
64
+ | **UI restoration is judged by feel** | Compare the reference and implementation screenshots to get a difference percentage, ranked regions, a heatmap, and JSON |
65
+ | **Screenshot assets cannot be reused** | Produce a crop, transparent PNG, color palette, or editable SVG instead of stopping at prose |
62
66
 
63
- *A live DSH Web view: the user pastes a brand-banner screenshot, and the text-only model answers what the image contains through the `DeepSeek-V4-Flash (Vision Toolkit)` image-input variant.*
67
+ ## See it in action
64
68
 
65
- ### Infographic restoration: screenshot to editable HTML/CSS
69
+ ### Paste an image directly into DSH
66
70
 
67
71
  <p align="center">
68
- <img src="assets/upstream/infographic-reference.webp" width="49%" alt="Upstream reference screenshot of a three-stage model-training infographic." />
69
- <img src="assets/upstream/infographic-result.webp" width="49%" alt="Upstream editable HTML and CSS reconstruction of the model-training infographic." />
72
+ <img src="assets/dsh-view-example.png" width="82%" alt="A text-only DeepSeek model answering a question about a pasted image through Vision Toolkit in DSH Web" />
70
73
  </p>
71
74
 
72
- *Left: source screenshot. Right: the editable HTML/CSS result from the upstream [infographic-restoration reference](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/examples/infographic-restoration/how-is-the-model-trained.html).*
75
+ *Paste an image into the conversation. A text-only model can switch to its `Vision Toolkit` variant and inspect the image in the context of the user's question.*
73
76
 
74
- ### UI restoration: sketch to working interface
77
+ ### Screenshot to editable page
75
78
 
76
79
  <p align="center">
77
- <img src="assets/upstream/ui-sketch.webp" width="49%" alt="Upstream hand-drawn JupyterLab workspace used as a UI restoration reference." />
78
- <img src="assets/upstream/ui-result.webp" width="49%" alt="Upstream JupyterLab-style working interface reconstructed from the hand-drawn reference." />
80
+ <img src="assets/upstream/infographic-reference.webp" width="49%" alt="Reference infographic screenshot used for restoration" />
81
+ <img src="assets/upstream/infographic-result.webp" width="49%" alt="Editable HTML and CSS reconstruction created from the reference screenshot" />
79
82
  </p>
80
83
 
81
- *Left: hand-drawn input. Right: the upstream reconstructed interface; the complete method lives in the [UI restoration playbook](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/skills/vision-tools/references/restore-ui.md).*
84
+ *Left: the reference screenshot. Right: an editable HTML/CSS result. The result can continue into screenshot rendering and pixel comparison instead of ending as an image description.*
82
85
 
83
- ### Image Q&A and screenshot-guided debugging
86
+ ### Sketch to working interface
84
87
 
85
88
  <p align="center">
86
- <img src="assets/dsh-conversation-image-qa.png" width="49%" alt="DSH Web session in which a text-only agent answers a focused question about a UI reference image." />
87
- <img src="assets/dsh-conversation-screenshot-debugging.png" width="49%" alt="DSH Web session in which the agent uses a screenshot comparison to diagnose mismatched UI fields and recommend vision_pixel_diff." />
89
+ <img src="assets/upstream/ui-sketch.webp" width="49%" alt="Hand-drawn JupyterLab interface used as the restoration reference" />
90
+ <img src="assets/upstream/ui-result.webp" width="49%" alt="Working JupyterLab-style interface reconstructed from the sketch" />
88
91
  </p>
89
92
 
90
- *Left: intent-aware image Q&A in DSH Web. Right: a DSH Web screenshot-debugging turn that lists the concrete UI differences and continues toward `vision_pixel_diff`. The upstream workflow source is the same [`agent-vision-toolkit` reference](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/README.md#real-world-effects).*
93
+ *Left: a hand-drawn reference. Right: the working interface reconstructed from it.*
91
94
 
92
- DSH Vision Toolkit brings this workflow into DSH, where the result can become a file, a coordinate, a measured comparison, or the next step in the same session.
95
+ ### Turn “looks close” into a verifiable result
93
96
 
94
- ## From a rough match to pixel-perfect
95
-
96
- The included UI-restoration workflow starts with an intentionally inaccurate HTML implementation. Vision Toolkit measures a `6.04%` difference, points to the worst regions, and helps drive the next iteration. The final render reaches an exact `0%` difference at `1200 × 720`.
97
+ The repository includes a reproducible UI-restoration example. The first implementation differs from the reference by **6.04%**. After the highlighted regions are corrected, the final `1200 × 720` render reaches **0% pixel difference**.
97
98
 
98
99
  <p>
99
- <img src="examples/ui-restoration/assets/initial.png" width="49%" alt="Initial UI restoration candidate before Vision Toolkit iteration, with measurable layout and styling differences from the reference." />
100
- <img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="Final UI restoration output reproduced by the checked-in workflow with zero pixel difference from the reference." />
100
+ <img src="examples/ui-restoration/assets/initial.png" width="49%" alt="Initial UI implementation with measurable layout and styling differences" />
101
+ <img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="Final UI implementation after visual diagnosis, reaching zero pixel difference" />
101
102
  </p>
102
103
 
103
- | Start | Result |
104
- |---|---|
105
- | Reference image | A working HTML implementation you can open and edit |
106
- | First comparison | `6.04%` difference across the visible problem regions |
107
- | Final comparison | `0%` difference at `1200 × 720` |
108
-
109
- ## Why it feels different
104
+ ## Highlights
110
105
 
111
- - **Ask for the thing you need.** “Where is the submit button?” and “Why does this screenshot differ from the reference?” lead to focused visual work instead of a generic caption.
112
- - **Get evidence you can use.** The agent returns coordinates, OCR, measurements, JSON, and files you can open or pass to the next step.
113
- - **Keep the workflow in DSH.** Credentials, Settings, Artifacts, Web cards, and Headless results live alongside the rest of your session.
114
- - **Use local tools when you can.** Crop, trace, pixel comparison, color analysis, foreground extraction, and HTML screenshots do not consume a vision API request.
115
- - **Repeat the loop.** Reference image → implementation → screenshot → pixel diff gives UI work a measurable finish line.
106
+ - **Free by default.** New installations use the built-in Gemma 4 service without requiring another account or API key.
107
+ - **Focused on the current task.** The agent sends the reason it needs to inspect the image, so the result emphasizes useful evidence instead of producing a generic caption.
108
+ - **Outputs you can keep working with.** Coordinates, OCR, transparent PNGs, SVGs, screenshots, heatmaps, and JSON can feed directly into the next step.
109
+ - **Built for UI and screenshot work.** Reference analysis, element location, asset extraction, HTML rendering, and pixel comparison form one continuous workflow.
110
+ - **Local where possible.** Crop, trace, pixel diff, color, foreground, and HTML screenshot operations do not need a remote vision model.
111
+ - **The same capabilities in Web and Headless.** Web users can preview and download artifacts; Headless runs still receive replayable structured results and workspace paths.
116
112
 
117
- ## Start in three steps
113
+ ## Quick start: three steps
118
114
 
119
- Use DeepSeek Harness `0.1.0-rc.6` or a compatible later `0.1.x` release. The plugin prepares its managed runtime on first use.
115
+ ### 1. Install
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
- 1. Restart your Web profile and open **Settings → Vision Toolkit**.
127
- 2. New installations use the built-in free Gemma 4 provider, so you can run **Test API connection** and **Test vision model** without an API key. To use another provider, edit the endpoint/model/protocol and provide its DSH Credential.
128
- 3. In a conversation, paste an image or put it in the workspace, invoke `/vision-tools`, and ask for a concrete visual task.
129
-
130
- If you use an older DSH launcher, the profile may need `nodeLinker: hoisted` and `autoInstallPeers: false` before installation. Current launchers repair these settings for you.
131
-
132
- Local crop, trace, pixel, color, foreground, and HTML operations do not require a visual API credential.
121
+ You can install it into a Headless Profile too:
133
122
 
134
- ## Community Group
135
-
136
- Join the `agent-vision-toolkit` community group to exchange usage tips, share feedback, and suggest improvements.
137
-
138
- <p align="center">
139
- <img src="assets/community-group-qr.png" alt="QR code for the agent-vision-toolkit community group" width="260">
140
- </p>
141
-
142
- > **No local path is required.** Keep the default `runtime.mode: managed` for the normal npm installation. The optional `runtime.agentVisionToolkitPath` setting is only for developers or controlled deployments that deliberately use an external pinned checkout.
143
-
144
- <details>
145
- <summary><strong>Technical architecture</strong></summary>
146
-
147
- ## How it works
148
-
149
- ```mermaid
150
- flowchart LR
151
- User["Workspace image or local HTML"] --> Skill["vision-tools Skill"]
152
- Skill --> Activate["Agent-scoped activation"]
153
- Activate --> Tools["10 independent vision_* tools"]
154
- Tools --> Runtime["Shared VisionToolkitRuntime"]
155
- Credentials["DSH Credentials"] --> Runtime
156
- Settings["Web Settings and health"] --> Runtime
157
- Runtime --> Upstream["Pinned agent-vision-toolkit"]
158
- Runtime --> Remote["Configured vision API"]
159
- Upstream --> Result["Text, coordinates, JSON"]
160
- Remote --> Result
161
- Runtime --> Artifacts["Workspace Artifacts"]
162
- Result --> Session["Reconstructable Session log"]
163
- Artifacts --> Web["Preview, download, or open file"]
123
+ ```sh
124
+ dsh plugin --profile headless add @anionex/dsh-vision-toolkit
164
125
  ```
165
126
 
166
- Tool definitions call one runtime; the runtime validates paths, limits, credentials, cancellation, and deadlines before dispatching to the pinned upstream snapshot or configured vision provider endpoint. Web presentation consumes the same structured results and Artifact descriptors, so it does not change Headless behavior. Health, connection testing, and version inspection stay in Settings rather than model tool schemas.
167
-
168
- </details>
169
-
170
- ## Tools
171
-
172
- | Tool | Execution | Structured result | Artifact delivery |
173
- |---|---|---|---|
174
- | `vision_glance` | Remote vision API | Description, targeted answer, OCR, or multi-image comparison | None |
175
- | `vision_ground` | Remote vision API; optional local preview | Target, original-image dimensions, and pixel boxes | Optional labeled PNG |
176
- | `vision_detect` | Remote vision API; optional local preview | Numbered element inventory and original-image pixel boxes | Optional numbered PNG |
177
- | `vision_trace` | Local pinned vtracer pipeline | SVG geometry status, path count, scale, and size | SVG |
178
- | `vision_crop` | Local Pillow pipeline | Applied pixel box, dimensions, format, and clamp status | PNG or JPEG |
179
- | `vision_pixel_diff` | Local NumPy/Pillow pipeline | Difference percentage and ranked grid regions | PNG heatmap and JSON report |
180
- | `vision_long_screenshot_ocr` | Local split/audit; remote OCR unless `splitOnly=true` | Chunk boundaries, reuse state, completion state, and run directory | Markdown, manifest, boundary audit, chunk PNGs, and OCR sidecars |
181
- | `vision_extract_foreground` | Local pinned extraction pipeline | Selected box, component counts, foreground coverage, and dimensions | Transparent PNG |
182
- | `vision_dominant_colors` | Local pinned color analysis | Extracted palette or pixel-backed candidate ranking | None |
183
- | `vision_html_screenshot` | Local Chrome/Chromium/Edge adapter | Authorized source facts, viewport, and rendered dimensions | PNG |
184
-
185
- The plugin does not reimplement visual algorithms. Its DSH-owned layer validates paths and limits, resolves credentials, calls the pinned upstream scripts with argv vectors, parses their exact output contracts, classifies failures, describes files, and projects results to the model and Web client.
186
-
187
- <details>
188
- <summary><strong>Advanced model behavior</strong></summary>
189
-
190
- ## Progressive model exposure
127
+ ### 2. Restart and check it
191
128
 
192
- Runtime readiness is profile-wide, but the ten visual execution schemas are Agent-scoped. Before an Agent loads `vision-tools`, the plugin contributes only the small `vision_toolkit_activate` bootstrap; the visual tools are absent from that Agent's request schema. A successful call to the standard `skill` tool with `name="vision-tools"` mounts all ten tools automatically for the next model step and hides the bootstrap. A direct `/vision-tools` invocation injects the Skill instructions; if the visual tools are still absent, those instructions require one `vision_toolkit_activate` call. Activation affects only that Agent, restores when the Session contains durable evidence matching the bundled Skill version, and lasts until the Agent or plugin is disposed.
129
+ Restart a running Web Profile, then open **Settings → Vision Toolkit**. The free provider is already configured; run **Test vision model** to confirm it is reachable.
193
130
 
194
- Health checks, connection testing, and plugin/upstream version inspection are administrative Web Settings operations. `vision_toolkit_health` and `vision_toolkit_version` are not model tools and never enter an Agent's schema, including after visual-tool activation.
131
+ The first start prepares an isolated runtime, so it needs access to the Python package cache or the network. A normal installation does not require an `agent-vision-toolkit` source checkout or a local path setting.
195
132
 
196
- ## Image-input variants for text-only models
133
+ ### 3. Paste an image and describe the outcome you want
197
134
 
198
- Text-only model routes get sibling model-selector entries named `<model> (Vision Toolkit)` under a matching provider group. DSH cannot pass a pasted attachment's local path through its native image block, so every bridge path materializes the image inside the session workspace and exposes its absolute path to the model. The model can then call `vision_glance` (or another visual tool) with that path. When the server-side image-input variant is active, the same model-visible block also contains the focus-hinted `[vision model description]` evidence aligned with `agent-vision-toolkit`; the path remains available for a second, more targeted visual call. The session log contains the durable path reference and the UI keeps the paste record.
135
+ Paste a screenshot into the conversation or place an image in the session workspace, then invoke `/vision-tools`. For example:
199
136
 
200
- A variant is registered automatically for every model the host positively declares text-only (for example the DeepSeek chat family). With the default `autoSwitch: true`, the browser switches to `<model> (Vision Toolkit)` and the server-side bridge rewrites each native image block into **both** the workspace path and the focus-hinted description; the path is not hidden from the model. Setting `autoSwitch: false` keeps the older path-only takeover instead. The host's verdict uses the exact model route the browser read from the live model catalog, with the selector label as fallback; unconfirmed or image-capable routes keep their native flow.
201
-
202
- Description conversion needs the configured vision provider and its credential when the opt-in image-input variant is used; when the runtime is not ready or a read fails, the wire block keeps the workspace path and adds the upstream-compatible `[vision unavailable: ...]` note instead of failing the turn. The bridge does not treat injected context files as the current user intent, and it uses the latest assistant paragraph when a tool-fetched image is being described. Disable variants with `imageInputVariants.enabled: false`, restrict the wrapped routes with `imageInputVariants.providers`, or opt into native attachment switching with `imageInputVariants.autoSwitch: true`.
203
-
204
- </details>
205
-
206
- ## Requirements
207
-
208
- - DeepSeek Harness with a Web or Headless profile and `pnpm` available to `dsh plugin`.
209
- - Python 3.11 or newer. Managed mode creates an isolated environment, so users do not install the upstream CLI or Python packages manually.
210
- - Network access on the first managed-runtime activation unless the exact packages in `runtime/requirements.lock` are already available in the configured package cache.
211
- - The built-in free Gemma 4 provider is ready for `vision_glance`, `vision_ground`, `vision_detect`, and non-split-only long-screenshot OCR. A DSH Credential is required only when a custom OpenAI-compatible or Anthropic endpoint is configured. Local tools remain usable without either provider.
212
- - Chrome, Chromium, or Edge only for `vision_html_screenshot`; all other tools remain available when no supported browser is installed.
213
- - PNG, JPEG, GIF, or WebP inputs inside the session workspace or an explicitly configured `allowedDirs` root.
214
-
215
- ## Install and lifecycle
216
-
217
- ### Install
218
-
219
- Install the bundle into each profile that should expose it:
220
-
221
- ```sh
222
- dsh plugin --profile web add @anionex/dsh-vision-toolkit
223
- dsh plugin --profile headless add @anionex/dsh-vision-toolkit
224
- dsh --profile web --dump-config | grep vision-toolkit
225
- dsh --profile headless --dump-config | grep vision-toolkit
137
+ ```text
138
+ Inspect this screenshot. Explain the error and tell me what to fix first.
139
+ Find the login button in the top-right corner, return original pixel coordinates, and make a boxed preview.
140
+ Crop this icon and convert it to SVG.
141
+ Rebuild the page from reference.png. After each pass, render it and run a pixel diff until the major differences are gone.
226
142
  ```
227
143
 
228
- Restart a long-lived Web profile after installation. The host discovers the built browser bundle from `package.json`'s `dsh.client` declaration at process startup; the legacy top-level `dshClient` field is not scanned.
229
-
230
- The first managed start verifies the packaged upstream manifest and atomically prepares an isolated environment under `DSH_HOME/cache/dsh-vision-toolkit`. Only after preparation succeeds does the plugin publish the same-version `vision-tools` Skill and activation bootstrap; each Agent receives the execution tools only after loading that Skill. An initial preparation failure leaves the Web Settings repair surface available but exposes neither model capability nor a misleading Skill.
144
+ ## Common workflows
231
145
 
232
- ### Disable and re-enable
146
+ | Task | Recommended workflow |
147
+ |---|---|
148
+ | Image Q&A or screenshot debugging | Inspect → answer around the current question → locate details when needed |
149
+ | Find a button, icon, or text region | Ground the target → return pixel box → create a labeled preview |
150
+ | Extract an icon from a screenshot | Ground → crop → trace to SVG |
151
+ | Read a long webpage screenshot | Split → OCR → merge Markdown → audit boundaries |
152
+ | Recreate a page or component | Reference → implementation → HTML screenshot → pixel diff → iterate |
153
+ | Extract brand visuals | Crop region → analyze dominant colors → extract foreground → export transparent PNG |
233
154
 
234
- Set the bundle row to `disabled: true` in a profile patch or overlay:
155
+ ## Toolbox
235
156
 
236
- ```yaml
237
- - id: vision-toolkit
238
- disabled: true
239
- ```
157
+ The plugin provides 10 tools that can be called independently or composed into a workflow:
240
158
 
241
- Remove the flag or set it to `false` to re-enable the plugin. Disposal first cancels plugin-owned visual operations, then removes every Agent-scoped tool, the bootstrap, and the Skill; reactivation prepares the configured runtime before any model capability becomes visible. User configuration and completed Artifacts remain intact.
159
+ | Tool | Best question to ask | Main result |
160
+ |---|---|---|
161
+ | `vision_glance` | “What is happening in this image?” | Focused answer, description, OCR, or multi-image comparison |
162
+ | `vision_ground` | “Where is the thing I need?” | Original pixel coordinates and optional boxed preview |
163
+ | `vision_detect` | “Which buttons, icons, or elements are present?” | Numbered element inventory, coordinates, and optional preview |
164
+ | `vision_crop` | “Extract this region as its own image” | PNG or JPEG crop |
165
+ | `vision_trace` | “Turn this shape into an editable vector” | SVG |
166
+ | `vision_pixel_diff` | “Where does the implementation differ from the reference?” | Difference percentage, ranked regions, heatmap, and JSON |
167
+ | `vision_long_screenshot_ocr` | “Read this entire long screenshot” | Markdown, chunks, manifest, and audit output |
168
+ | `vision_extract_foreground` | “Remove the background from this subject” | Transparent PNG |
169
+ | `vision_dominant_colors` | “Which colors dominate this area?” | Palette or ranked candidate colors |
170
+ | `vision_html_screenshot` | “Render this local page at an exact viewport or capture the full page” | PNG and optional CSS `pageHeight` |
242
171
 
243
- ### Upgrade
172
+ Coordinates always use original-image pixels in `x1,y1,x2,y2` form, so grounding output can feed directly into cropping, tracing, or later automation.
244
173
 
245
- **Migrating from the retired `@dsh-external/dsh-vision-toolkit`:** the npm package now lives under the `@anionex` scope. If you installed the retired package, do **not** run `update` on it — that account cannot publish this release. Migrate to the new package name and restart the Web profile:
174
+ For a long HTML document, pass `fullPage=true`. The requested width and height remain the layout viewport, while the resulting PNG covers the complete document and reports `pageHeight` in CSS pixels.
246
175
 
247
- ```sh
248
- dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit
249
- dsh plugin --profile web add @anionex/dsh-vision-toolkit
250
- ```
176
+ ## How it works
251
177
 
252
- After restarting, Settings → Vision should report plugin version **0.1.12**. The built-in free provider is selected automatically; custom providers still use the configured DSH Credential.
178
+ The plugin keeps image understanding and deterministic local image processing in one Agent workflow. Expand the flow below for the implementation boundary.
253
179
 
254
- For a registry installation, update the dependency through the profile package manager:
180
+ <details>
181
+ <summary><strong>Architecture and image-input behavior</strong></summary>
255
182
 
256
- ```sh
257
- dsh plugin --profile web update @anionex/dsh-vision-toolkit
258
- dsh plugin --profile headless update @anionex/dsh-vision-toolkit
183
+ ```mermaid
184
+ flowchart LR
185
+ Image["Screenshot or local HTML"] --> Skill["vision-tools Skill"]
186
+ Skill --> Agent["Text agent selects a task"]
187
+ Agent --> Vision["Use a vision model when image understanding is needed"]
188
+ Agent --> Local["Run crop, SVG, and pixel work locally"]
189
+ Vision --> Result["Answer, OCR, coordinates"]
190
+ Local --> Artifact["PNG, SVG, heatmap, JSON"]
191
+ Result --> Session["Continue reasoning and acting"]
192
+ Artifact --> Session
259
193
  ```
260
194
 
261
- For a local path installation, run `add` again against the replacement checkout or tarball. Settings remain in the profile's Settings provider. A candidate runtime is fully validated and prepared before it is persisted and made active; a failed or obsolete concurrent candidate cannot replace the current serving generation.
195
+ The visual capabilities come from a packaged, pinned `agent-vision-toolkit` snapshot. The DSH plugin handles installation, session-scoped tool exposure, Credentials, path checks, cancellation, timeouts, result files, and Web presentation. The runtime never fetches upstream `main` in the background.
262
196
 
263
- ### Uninstall
197
+ For routes that DSH positively identifies as text-only, the plugin registers a sibling `<model> (Vision Toolkit)` variant. By default, pasting an image in DSH Web switches to that variant and gives the model both a reusable workspace path and a visual description focused on the current task.
264
198
 
265
- ```sh
266
- dsh plugin --profile web remove @anionex/dsh-vision-toolkit
267
- dsh plugin --profile headless remove @anionex/dsh-vision-toolkit
268
- ```
199
+ </details>
269
200
 
270
- `dsh plugin remove` removes both the dependency and its bundle layer. The profile no longer exposes the activation bootstrap, Agent-scoped Vision Toolkit tools, or Skill entries. Managed cache data may be deleted separately when no profile uses the package; it is not active configuration and cannot register anything by itself.
201
+ ## Configuration and limits
271
202
 
272
- ## Configure
203
+ ### Built-in free service
273
204
 
274
- The bundle defaults to the managed runtime. A profile patch can override the provider and limits:
205
+ The default setup uses:
275
206
 
276
- ```yaml
277
- - id: vision-toolkit
278
- config:
279
- provider:
280
- baseUrl: https://vision.anionex.me/v1
281
- credential: ANIONEX_FREE_VISION
282
- model: gemma-4-26b-a4b-it
283
- protocol: openai
284
- anthropicThinking: omit
285
- userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36
286
- language: zh
287
- timeoutMs: 60000
288
- maxImageBytes: 4194304
289
- maxImagePixels: 20000000
290
- concurrency: 4
291
- runtime:
292
- mode: managed
293
- allowedDirs: []
294
- imageInputVariants:
295
- enabled: true
296
- providers: []
297
- autoSwitch: true
207
+ ```text
208
+ Base URL: https://vision.anionex.me/v1
209
+ Model: gemma-4-26b-a4b-it
210
+ API Key: no user configuration required
298
211
  ```
299
212
 
300
- ### Configuration fields
301
-
302
- | Field | Default | Contract |
303
- |---|---|---|
304
- | `provider.baseUrl` | `https://vision.anionex.me/v1` | Built-in free OpenAI-compatible endpoint; custom providers may use another base URL, normalized without trailing slashes |
305
- | `provider.credential` | `ANIONEX_FREE_VISION` | Read-only built-in reference for the free service; custom providers use a DSH Credential reference, never a secret value |
306
- | `provider.model` | `gemma-4-26b-a4b-it` | Multimodal model name sent to remote tools |
307
- | `provider.protocol` | `openai` | `openai` sends Chat Completions requests; `anthropic` sends native Messages requests |
308
- | `provider.anthropicThinking` | `omit` | Anthropic thinking field. `omit` sends no thinking field and has the broadest compatibility. Use `disabled` or `adaptive` only when the selected model documents that mode; restore `omit` first if the provider returns HTTP 400. |
309
- | `provider.userAgent` | browser-compatible default | User-Agent sent by vision requests and explicit connection tests; override it for provider or proxy compatibility |
310
- | `language` | `zh` | Vision output language: `zh` or `en` |
311
- | `timeoutMs` | `60000` | Whole-operation deadline, 1000-600000 ms; each tool may request a narrower override |
312
- | `maxImageBytes` | `4194304` | Encoded-byte limit per input image; the built-in free service accepts up to 4 MiB |
313
- | `maxImagePixels` | `20000000` | Decoded-pixel limit per input image; the built-in free service accepts up to 20,000,000 pixels |
314
- | `concurrency` | `4` | In-flight operations per session, 1-16 |
315
- | `runtime.mode` | `managed` | `managed` uses the packaged snapshot; `external` accepts only the exact pin |
316
- | `runtime.agentVisionToolkitPath` | unset | Required in `external` mode; exported exact snapshot or clean pinned Git checkout |
317
- | `runtime.python` | unset | Optional Python 3.11+ bootstrap/interpreter override |
318
- | `allowedDirs` | `[]` | Additional realpath-resolved input roots; the session workspace is always allowed |
319
- | `imageInputVariants.enabled` | `true` | Register image-input variant entries for text-only model routes in the model selector |
320
- | `imageInputVariants.providers` | `[]` | Restrict wrapped upstream routes by provider id; empty wraps every eligible route |
321
- | `imageInputVariants.autoSwitch` | `true` | Automatically switch a text-only session to its image-input variant; the model receives both the workspace path and focused description. `false` keeps the path-only takeover |
322
-
323
- ### Credentials
324
-
325
- The built-in free provider uses the fixed `ANIONEX_FREE_VISION` reference and does not accept or store a user API key. If you change the endpoint, model, or protocol to a custom provider, the write-only **API key** field unlocks; saving a non-empty value writes it under the advanced **Credential name** reference. Headless deployments can pre-provision that custom reference in `$DSH_HOME/.credentials.yaml`.
326
-
327
- Settings store only the reference, never the value. The browser does not receive a stored value, and a successful save clears the field instead of echoing it. Remote operations resolve the reference once per call and inject the value only into that subprocess environment. The plugin excludes user `.env` files, checkout `.env` files, `PYTHONPATH`, `PYTHONHOME`, `VIRTUAL_ENV`, and user site-packages so ambient Python or upstream configuration cannot override the selected DSH provider. Logs, errors, tool results, Artifact metadata, and Settings responses never contain the secret.
328
-
329
- ### Built-in free service limits
330
-
331
- The public service is shared and intended as a zero-configuration default, not an unlimited private endpoint. Limits are enforced by the proxy and returned as OpenAI-style errors with a reason code and readable message; rate-limit responses also include `Retry-After` and request-quota headers.
213
+ This is a shared zero-configuration entry point, not an unlimited private endpoint. Current limits are:
332
214
 
333
215
  | Limit | Current value |
334
216
  |---|---:|
335
217
  | Per client | 100 requests per UTC day |
336
- | Global service | 400 requests per UTC day |
218
+ | Whole service | 400 requests per UTC day |
337
219
  | Burst | 20 requests per 60 seconds |
338
- | Image bytes | 4 MiB per image |
220
+ | Image size | 4 MiB per image |
339
221
  | Decoded pixels | 20,000,000 per image |
340
- | Output | 512 tokens maximum |
222
+ | Output | 512 tokens per request |
341
223
 
342
- ### Managed runtime and optional external runtime
224
+ The limits protect shared capacity and prevent unusually large images from monopolizing memory or request time. When a limit is reached, the service returns a readable reason and error code. Rate-limit responses also include `Retry-After` instead of collapsing into an unexplained model failure.
343
225
 
344
- Managed mode verifies `vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json`, prefers `uv`, falls back to `venv` plus pip, installs exact versions from `runtime/requirements.lock`, coordinates concurrent preparation with a heartbeat lock, and publishes a staged environment only after all probes pass.
226
+ ### Bring your own vision model
345
227
 
346
- Most users should stop at managed mode. It is included in the npm package and prepares the pinned Python environment for you.
228
+ For higher quotas, private endpoints, or another model, change the provider in **Settings → Vision Toolkit** and store the API key as a DSH Credential. Settings stores the Credential reference and never reads the saved secret back into the browser.
347
229
 
348
- The optional external mode is for plugin development or controlled deployments that already maintain the exact upstream checkout:
230
+ You can also configure a Profile patch:
349
231
 
350
232
  ```yaml
351
233
  - id: vision-toolkit
352
234
  config:
353
- runtime:
354
- mode: external
355
- agentVisionToolkitPath: /opt/agent-vision-toolkit
356
- python: python3.12
235
+ provider:
236
+ baseUrl: https://api.example.com/v1
237
+ credential: MY_VISION_KEY
238
+ model: your-vision-model
239
+ protocol: openai
357
240
  ```
358
241
 
359
- The path must be an exported copy matching the packaged manifest or the root of a clean Git checkout at `bc9803d7d6300c864d17460ecbb33540b26638e0`. Modified tracked files and untracked files are rejected because they can change or shadow the pinned Python behavior.
360
-
361
- ## Web Settings
362
-
363
- The Web profile registers a Vision Toolkit Settings section for the provider URL, Credential reference, model, OpenAI/Anthropic protocol, Anthropic thinking mode, User-Agent, language, timeout, byte/pixel limits, concurrency, runtime mode, Python override, external source path, and allowed directories. It also shows plugin/upstream versions, the active runtime generation, non-secret Credential configured/source/writable facts, runtime paths, health results, and Artifact-route availability.
364
-
365
- The **Plugin updates** card checks the profile's configured npm registry for a newer `@anionex/dsh-vision-toolkit` release. **Update and restart** installs that exact confirmed version into the current DSH profile, verifies the installed package, starts an independent restart helper, and gracefully restarts DSH Web; the open page waits for the replacement process and reloads after the new plugin version is serving. The action is same-origin, fixed to this package, serialized, and unavailable for `link:`, `file:`, workspace, git, URL, transitive, ambiguous, read-only, or missing-`pnpm` installations so local development sources are never overwritten. A restart can interrupt work that is currently running, so the UI requires an explicit confirmation.
242
+ OpenAI Chat Completions-compatible endpoints and Anthropic Messages are supported. The Web Settings panel exposes the full provider, runtime, timeout, image-limit, and image-input-variant configuration.
366
243
 
367
- `Save and apply` validates the complete value, prepares the candidate Python/upstream runtime, commits the Settings revision, and only then atomically switches generations. A rejected candidate leaves the previous generation serving and is reported separately from a genuinely unavailable runtime. `Reload` always restores the authoritative saved value, even when its revision did not change, so a rejected browser draft is discarded. If initial startup cannot prepare a runtime, the Settings route remains available so a valid configuration can make the first generation operational. A stale browser revision receives a conflict instead of overwriting a newer save; reload before retrying. A read-only Settings provider allows inspection and health checks but disables saves.
244
+ ### Requirements
368
245
 
369
- `Run health check` performs local checks only. `Test API connection` is an explicit action that sends the configured Credential to `GET /models`; OpenAI uses Bearer authentication, while Anthropic uses `x-api-key` and `anthropic-version`. That lightweight probe uploads no image and creates no completion. `Test vision model` separately sends the bundled `assets/vision-model-test.png` through the same multimodal runtime path as `vision_glance`; it creates one real completion and is the authoritative check that the selected endpoint, credential, model, protocol, and upstream account can process images. The Vision model health card displays a dedicated `Verified`, `Not tested`, or `Test failed` tag, so an HTTP 200 response from `/models` is not presented as a successful image test. Plugin load and ordinary Settings reads never make either request.
246
+ - A DeepSeek Harness Web or Headless Profile.
247
+ - Node.js `^22.19.0` or `>=24.0.0`.
248
+ - Python 3.11+; the plugin prepares an isolated environment by default.
249
+ - Only `vision_html_screenshot` requires Chrome, Chromium, or Edge.
250
+ - Inputs must be PNG, JPEG, GIF, or WebP files in the session workspace or an explicitly allowed directory.
370
251
 
371
- Health, connection testing, and plugin/upstream version inspection are administrative Web Settings capabilities rather than model-facing tools, so their schemas never occupy an agent request.
372
-
373
- ## Artifacts and presentation
374
-
375
- Artifact-producing tools write only under `<workspace>/.dsh-vision-toolkit/artifacts`, either as one validated file or an atomically committed run directory. Each model-visible descriptor contains the path, filename, MIME type, kind, description, source tool, preview intent, and byte size, so Headless agents can reuse the path in later calls without browser support. Before a traced SVG is committed, the runtime parses it as XML: standard declarations and comments are accepted, while doctypes, malformed or multi-root documents, a non-SVG namespace, and reported path/byte mismatches are rejected.
252
+ <details>
253
+ <summary><strong>Install, upgrade, disable, and uninstall</strong></summary>
376
254
 
377
- When the Web HTTP host is present, presentation-only metadata adds signed capability URLs for preview and download without altering the canonical tool result. Every read revalidates the signature, managed-root fence, path components, regular-file status, size, device/inode identity where available, extension, and MIME. SVG responses use a sandboxed no-resource CSP and the client renders them in a sandboxed iframe. Without an HTTP host, the same cards retain `Open file` through `openFile` and show the descriptor instead of inventing an inaccessible URL.
255
+ ```sh
256
+ dsh plugin --profile web update @anionex/dsh-vision-toolkit
257
+ dsh plugin --profile web remove @anionex/dsh-vision-toolkit
258
+ ```
378
259
 
379
- ## Usage patterns
260
+ If you are migrating from the retired `@dsh-external/dsh-vision-toolkit`, remove the old package first and install `@anionex/dsh-vision-toolkit`.
380
261
 
381
- ### Basic calls
262
+ To disable the bundle temporarily, set this in the Profile patch:
382
263
 
383
- ```text
384
- vision_glance images=["screenshot.png"] query="What error is shown?"
385
- vision_ground image="screenshot.png" target="the send button" preview=true
386
- vision_detect image="screenshot.png" category="buttons" preview=true
387
- vision_crop image="screenshot.png" region="1067,841,1108,881"
388
- vision_trace image="icon.png" color=true output="icon.svg"
389
- vision_pixel_diff original="reference.png" rebuilt="actual.png" runName="comparison"
390
- vision_long_screenshot_ocr image="page.png" mode="general" jobs=2
391
- vision_extract_foreground image="logo.png" mode="color"
392
- vision_dominant_colors image="screen.png" region="0,0,600,300" top=8
393
- vision_html_screenshot source="implementation.html" width=1200 height=720
264
+ ```yaml
265
+ - id: vision-toolkit
266
+ disabled: true
394
267
  ```
395
268
 
396
- Common workflows are `vision_ground` → `vision_crop` → `vision_glance`, `vision_ground` → `vision_crop` → `vision_trace`, and reference image → `vision_html_screenshot` → `vision_pixel_diff`. Grounding and detection boxes always use original-image pixels (`x1/y1/x2/y2`).
269
+ Restart the Web Profile and refresh the page after enabling or upgrading the Web plugin.
397
270
 
398
- ### UI restoration example
271
+ </details>
399
272
 
400
- The checked-in [UI restoration example](examples/ui-restoration/README.md) renders a reference, an intentionally inaccurate first implementation, and the final implementation through `vision_html_screenshot`, then compares both candidates through `vision_pixel_diff`:
273
+ ### Plugin updates
401
274
 
402
- ```sh
403
- npm run example:ui-restoration
404
- npm run example:ui-restoration:write
405
- ```
275
+ In **Settings → Vision Toolkit**, **Check for updates** queries the Profile's npm registry. For a direct registry installation, **Update and restart** installs only the exact version you confirmed, verifies it, and restarts an explicitly opted-in POSIX Web process on a fixed `--port`. Local/workspace/file/git/URL installs, Windows, dynamic ports, read-only Profiles, and manager-owned processes remain check-only.
406
276
 
407
- The committed evidence records an initial `6.04%` difference across six non-zero worst regions and a final `0%` difference with no non-zero worst region. Check mode reproduces the tool path and verifies the committed assets; write mode intentionally refreshes the evidence.
277
+ The updater revalidates the Profile before mutation, snapshots the original manifest and lockfile, and holds a token-owned cross-process lock. The current Web process exits only after the restart helper confirms that the backup is readable and the lock handoff succeeded. When the Profile was already operational, the replacement must report both the target plugin version and a ready runtime; failed replacements restore the original manifest/lockfile and rebuild dependencies with a frozen lockfile before retrying the previous exact version. If automatic recovery itself fails, the backup and lock are preserved and their paths are written to `$DSH_HOME/logs/vision-toolkit-restart.log`. Detached restart requires `DSH_VISION_TOOLKIT_ALLOW_DETACHED_RESTART=1`; unsaved Settings or API-key input blocks installation.
408
278
 
409
279
  ## Troubleshooting
410
280
 
411
- | Symptom | Resolution |
281
+ | Problem | What to do |
412
282
  |---|---|
413
- | `Model "..." does not support image input. (attachment-error)` | The image used DSH's native model-attachment channel, so a text-only model rejected the turn before the Skill or Vision Toolkit could run. With image-input variants enabled this is rare: pasting normally auto-switches the session to the `<model> (Vision Toolkit)` variant. If variants are disabled or auto-switch is off, use DSH Paste Input's attachment button, paste, or drop flow so the file is copied into the session workspace and represented by a path, then invoke `/vision-tools`. Restart the Web profile and reload the page after installing or upgrading either browser plugin. |
414
- | Credential reported missing | Paste the key into Web Settings **API key**, keep the advanced **Credential name** aligned with `provider.credential`, save, then rerun health. Headless deployments can provision the same reference in `$DSH_HOME/.credentials.yaml`. Local-only tools do not need it. |
415
- | Runtime preparation fails | Read the Settings runtime error, verify Python 3.11+, package-cache/network access, disk permissions, and the exact external pin. Save only after correcting the candidate; the active generation remains intact. |
416
- | Chrome is not found | Install Chrome, Chromium, or Edge or configure an environment where one is discoverable. Only `vision_html_screenshot` is unavailable. |
417
- | macOS displays a keychain dialog | Confirm the current built adapter is installed and no stale external `html_shot`/headless Chrome process is running. Current launches use a mock keychain and disposable profile; cancel the dialog rather than resetting the login keychain. |
418
- | Input or output path is rejected | Move the file into the session workspace or add an intentional real directory to `allowedDirs`; remove escaping symlinks. Outputs accept a filename, not an absolute or nested path. |
419
- | Vision service returns 401/403 | Replace the Credential value or select the correct reference and endpoint. Errors remain redacted. |
420
- | Vision service returns 429 | Retry after the provider's rate-limit window or lower `concurrency`. The plugin does not silently switch providers. |
421
- | Operation times out or is cancelled | Raise `timeoutMs` within 1000-600000 ms, reduce image/chunk work, or rerun after cancellation. The subprocess/request is stopped with the operation. |
422
- | Settings save reports a conflict | Reload the section to obtain the current revision, reapply the intended edit, and save again. |
423
- | Settings is read-only | Change the active Settings provider or edit the owning profile configuration; the plugin cannot bypass provider writability. |
424
- | Artifact preview is unavailable | Use `Open file` or the model-visible path. Preview/download URLs exist only while a Web HTTP route is attached. |
425
-
426
- ## Development and verification
283
+ | Pasting an image still says the model does not support image input | Restart the Web Profile, refresh the page, and confirm the selected route has the `(Vision Toolkit)` suffix. You can also place the image in the session workspace and invoke `/vision-tools` |
284
+ | The free service returns 429 | Wait for the `Retry-After` interval, or switch to your own endpoint when you need stable higher volume |
285
+ | The image exceeds a size or pixel limit | Crop or resize it first; the error identifies whether bytes or decoded pixels caused the rejection |
286
+ | A custom Credential is missing | Enter the API key in **Settings → Vision Toolkit** and confirm the Credential name matches the provider configuration |
287
+ | First-time runtime setup fails | Check Python 3.11+, network or package-cache access, and disk permissions, then retry the model test in Settings |
288
+ | Chrome is not found | Install Chrome, Chromium, or Edge. Only HTML screenshot rendering is unavailable; the other tools still work |
289
+ | An artifact cannot be previewed | Use **Open file** or the workspace path in the result. Preview URLs exist only while the Web route is available |
290
+
291
+ ## Project status and limitations
292
+
293
+ The current release focuses on screenshot understanding, visual grounding, OCR, asset extraction, UI restoration, and pixel-level verification. It is not a video, audio, or camera-input system and does not automatically click GUI controls. Interactive box editing, remote service clusters, model voting, and cross-session visual caches are also outside the current scope.
294
+
295
+ ## Development and community
427
296
 
428
297
  ```sh
429
298
  pnpm install --frozen-lockfile --trust-lockfile
430
299
  pnpm run verify:portable
431
300
  pnpm run build
432
301
  pnpm test
433
- pnpm run example:ui-restoration
434
- pnpm pack --dry-run
302
+ TSX_TSCONFIG_PATH=tsconfig.json pnpm dlx tsx scripts/ui-restoration-example.ts --check
435
303
  ```
436
304
 
437
- `pnpm run verify:portable` is the dependency-free portable verification gate: it validates the vendored snapshot, package metadata and exports, committed JavaScript syntax, README links and images, required facade files, social-preview dimensions, and the dry-run tarball. The full TypeScript build and test suite run from this standalone checkout against the locked DSH `0.1.0-rc.6` registry packages; the client build also has a separate compiler face that resolves the packages' public exports without internal path aliases. The real Profile acceptance runs when compatible `dsh` and `pnpm` commands are on PATH, and CI requires that path instead of silently skipping it.
438
-
439
- `pnpm run build` verifies the vendored manifest before emitting JavaScript, declarations, and the loader-compatible Web client. The package commits `lib/`, so installation from a checkout does not require a consumer-side build. The keyless real-profile test installs into a clean `DSH_HOME`, boots Headless, executes all five P0 tools plus representative P1 local/remote tools through real tool calls, verifies disable and re-enable behavior, and uninstalls the bundle. See the [requirements traceability reference](docs/requirements-traceability/README.md) for the implementation and verification home of every P0/P1 requirement.
440
-
441
- Update the upstream snapshot only through `pnpm run upstream:sync -- <checkout>`, inspect the source and license, regenerate the manifest, and update the adapter compatibility tests and committed `lib/` in the same change. The runtime never fetches upstream `main`.
442
-
443
- ## Project status and scope
444
-
445
- Version `0.1.12` is the current public npm release. The product focuses on screenshot understanding, visual grounding, OCR, asset extraction, UI restoration, and pixel-level verification in DSH Web and Headless profiles. Web upload, drag-and-drop, camera/video/audio/document ingestion, interactive box editing, automatic GUI clicking, service clusters, model routing, model voting, and cross-session vision caches remain outside the current product.
446
-
447
- <details>
448
- <summary><strong>Maintainer scope note</strong></summary>
305
+ - Read [CONTRIBUTING.md](CONTRIBUTING.md) before contributing.
306
+ - Use [GitHub Issues](https://github.com/Anionex/dsh-vision-toolkit/issues) for bugs, focused feature requests, and usage questions; see [SUPPORT.md](SUPPORT.md) for channel guidance.
307
+ - Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
308
+ - See [CHANGELOG.md](CHANGELOG.md) for releases and [FUNDING.md](FUNDING.md) for sponsorship details.
309
+ - Visit upstream [agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) for the general toolkit, cross-agent integrations, and visual-task playbooks.
449
310
 
450
- The stable `ctx.visionToolkit` service and capability-discovery API remain unpublished until an independent plugin becomes a real consumer. This keeps the public integration surface tied to a tested use case rather than an unvalidated ecosystem contract.
451
-
452
- </details>
453
-
454
- ## Community and About
455
-
456
- - Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing code, protocol, or upstream-snapshot changes.
457
- - Use [GitHub Issues](https://github.com/Anionex/dsh-vision-toolkit/issues) for reproducible bugs, focused feature requests, and usage questions; use [SUPPORT.md](SUPPORT.md) to choose the right channel.
458
- - Report vulnerabilities privately through the process in [SECURITY.md](SECURITY.md), never in a public issue.
459
- - Follow releases and compatibility notes in [CHANGELOG.md](CHANGELOG.md).
460
- - Optional sponsorship is described transparently in [FUNDING.md](FUNDING.md); support does not purchase roadmap priority or private support.
461
- - Use the upstream [project website](https://agent-vision.anionex.me) and [repository](https://github.com/Anionex/agent-vision-toolkit) for the general toolkit, cross-harness integrations, visual-task playbooks, and reference runs.
462
- - Star, share, contribute to, or sponsor `agent-vision-toolkit` if its algorithms or methods save time; DSH-specific bugs and integration requests belong in this repository.
463
-
464
- [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) was created by [Anionex](https://anionex.me/). This repository maintains its native DeepSeek Harness integration: DSH owns lifecycle, security, structured schemas, Credentials, Artifacts, and Web presentation, while the upstream project remains the home of the visual algorithms and reusable playbooks.
311
+ <p align="center">
312
+ <img src="assets/community-group-qr.png" alt="QR code for the agent-vision-toolkit community group" width="240" />
313
+ </p>
465
314
 
466
- If you would like to follow my future work, [follow me on X](https://x.com/anion_ex) or [GitHub](https://github.com/Anionex).
315
+ [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) was created by [Anionex](https://anionex.me/). This repository maintains its native DeepSeek Harness integration.
467
316
 
468
317
  ## License
469
318
 
470
- The plugin is MIT-licensed. The packaged `agent-vision-toolkit` snapshot retains its upstream MIT license in `vendor/agent-vision-toolkit/LICENSE` and remains the sole implementation of its visual algorithms.
319
+ The plugin is available under the [MIT License](LICENSE). The packaged upstream snapshot retains its original MIT license in [`vendor/agent-vision-toolkit/LICENSE`](vendor/agent-vision-toolkit/LICENSE).