@anionex/dsh-vision-toolkit 0.1.32 → 0.1.33

package/README.zh.md

@@ -19,42 +19,32 @@
 
 🚀 粘贴图片，直接提问 ｜ 一行命令安装即用 ｜ 内置免费视觉 ｜ 场景丰富
 
-<p align="center">
-  <a href="#亮点">亮点</a> ｜ <a href="#快速开始三步完成">快速开始</a> ｜ <a href="#常见任务">常见任务</a> ｜ <a href="#工具一览">工具一览</a> ｜ <a href="#配置与限制">配置与限制</a> ｜ <a href="#常见问题">常见问题</a> ｜ <a href="#开发与社区">交流群</a>
-</p>
+[亮点](#亮点) ｜ [快速开始](#快速开始三步完成) ｜ [工具一览](#工具一览) ｜ [配置与限制](#配置与限制) ｜ [常见问题](#常见问题) ｜ [交流群](#开发与社区)
 
 🌐 [English](README.md) ｜ **中文**
 
 </div>
 
-如果你在 dsh 中使用 DeepSeek 等纯文本模型，遇到了下面问题中的一个或者多个，那么这个插件适合你：
-1. 粘贴图片被拒绝，不能发图片给模型，还要手动切换模型。
-2. 模型看不到图片内容，不能做和图片有关的任务。
-3. 已有方案只能得到图片笼统描述，完成不了高难度视觉相关任务，例如ui还原，长截图分析等。
-4. 不能安装即用，直接体验，还要自己配置api key。
-
-🏆 本项目为deepseek harness生态首个综合性视觉工具插件：内测前已立项，并在内测期间参考本人的[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit)做出
+🏆 本项目为deepseek harness生态首个综合性视觉工具插件：内测前已立项，并在内测期间参考本人的[`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit)做出。
 
 > **原创声明：** 这套视觉工具的体系和划分方式，以及 `vision-skills` Skill，均由作者个人原创并持续打磨，相关工具、方法和工作流来自长期的真实使用与反复迭代。
 
 ## 亮点
 
-- **粘贴即可使用。** 在 DSH Web 里粘贴图片，文本模型会自动切换到看图模式变体，不需要手动复制路径或更换模型。
-- **无缝体验。** 图片保留原生缩略图、会话记录和工作区路径；Web 可以预览产物，Headless 也能继续使用同一份结构化结果。
+- **粘贴图片，直接提问。** 在 DSH Web 里粘贴图片，文本模型会自动切换到看图模式变体，不需要手动复制路径或更换模型。图片保留原生缩略图、会话记录和工作区路径；Web 可以预览产物。
 - **一行命令安装即用。** 安装插件后默认使用内置免费 Gemini 3.7 Flash 视觉服务，不需要申请 API Key。
-- **内置免费视觉。** 安装后即可直接使用共享服务，每台机器每天有 **300 张图** 的免费额度。
-- **带着意图去看图。** Agent 不只生成通用描述，而是围绕“报错在哪里”“按钮在哪”等当前任务提取证据。
-- **从截图到可验证结果。** 参考图、HTML 截图、差异定位和像素对比组成一条完整 UI 还原闭环。
-
+- **内置免费视觉模型额度。** 安装后即可直接使用共享服务，每台机器每天有**100 张图**的免费额度。
+- **不只是看图描述，是获取图中真正需要关注的内容。** 模型不只是生成通用描述，而是围绕“报错在哪里”“按钮在哪”等当前任务提取证据。
+- **一套经过实战验证的视觉任务方法论**：项目提供的skill，会告诉 agent 面对不同视觉任务时应该看什么、选择哪个工具、按什么步骤推进，以及最后如何验证结果。
 
 [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 的视觉能力不只停留在图片描述：Agent 可以读取、定位、裁剪、描摹、还原和验证视觉内容。DSH Vision Toolkit 是这套工具箱面向 DeepSeek Harness 的原生接入，让它进入 Web 和 Headless Profile。
 
 本项目提供两层能力：
 
 1. **视觉工具和 Skill**：让 Agent 知道什么时候该看图、定位、OCR、裁剪、描摹或做像素对比。
-2. **DSH 原生接入**：把这些能力放进 Profile、会话、Settings、Artifacts 和 Web 界面，并提供安装即可使用的免费 Gemini 3.7 Flash 视觉服务。
+2. **DSH 原生接入**：把这些能力放进 Profile、会话、Settings、Artifacts 和 Web 界面。
 
-> **安装即可使用。** 默认接入内置免费 Gemini 3.7 Flash 视觉服务，不需要申请 API Key；
+> **安装即可使用。** 默认接入内置免费 Gemini 3.7 Flash 视觉服务，不需要申请 API Key。
 
 ```sh
 dsh plugin --profile web add @anionex/dsh-vision-toolkit
@@ -62,25 +52,21 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 **上游工具箱：** [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) · **项目网站：** [agent-vision.anionex.me](https://agent-vision.anionex.me)
 
-<details>
-<summary><strong>目录</strong></summary>
+**目录**
 
 - [亮点](#亮点)
 - [最近更新](#最近更新)
 - [适合谁用](#适合谁用)
 - [实际效果](#实际效果)
 - [快速开始：三步完成](#快速开始三步完成)
-- [常见任务](#常见任务)
 - [工具一览](#工具一览)
 - [配置与限制](#配置与限制)
 - [常见问题](#常见问题)
 - [开发与社区](#开发与社区)
 
-</details>
-
 ## 最近更新
 
-- **2026-08-16 · Windows Python：** 支持 Microsoft Store Python，解决部分 Windows 用户首次创建隔离环境失败的问题。
+- **2026-08-16 · Windows Python：** 支持 Microsoft Store Python，解决 Windows 用户首次创建隔离环境失败的问题。
 - **2026-08-17 · 免费视觉升级：** 默认模型切换到 Gemini 3.7 Flash，并修复 Qwen/Gemini 检测框坐标顺序错位的问题。
 - **2026-08-16 · 免费视觉升级：** 默认模型切换到 Groq Qwen3.6，解决免 Key 方案看图效果不足的问题。
 - **2026-08-16 · 图片粘贴：** 文本模型自动切换到 `(Vision Toolkit)` 变体并保留工作区路径，解决粘贴图片被拦截或后续无法复用的问题。
@@ -89,14 +75,19 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 ## 适合谁用
 
-| 你遇到的问题 | Vision Toolkit 给出的结果 |
-|---|---|
-| **纯文本模型看不到截图** | 在 DSH Web 中直接粘贴图片；插件会把图片交给视觉模型，再把与当前问题相关的证据交回文本模型 |
-| **图片描述很多，但没有重点** | 问“报错在哪里”“提交按钮是什么颜色”，得到围绕当前任务的回答，而不是通用看图作文 |
-| **知道有按钮，却不知道在哪** | 返回原图像素坐标，并可生成带框或带编号的预览图 |
-| **长截图 OCR 容易漏行、重复** | 分块读取并保留 Markdown、分块图、清单和审计结果，失败后也能继续 |
-| **UI 还原只能凭感觉调** | 把参考图和实现截图做像素对比，给出差异比例、重点区域、热力图和 JSON 报告 |
-| **截图里的素材无法继续使用** | 直接得到裁剪图、透明 PNG、主色板或可编辑 SVG，而不只是一段文字 |
+1. 想获得类似多模态模型一样的交互体验：直接粘贴图片，提出要求或疑问
+2. 不只是看图问答，想要完成更复杂、更有价值的视觉任务，例如草图变前端页面，图片转html，提取长截图里的聊天信息等等；后续也会不断补充更多的场景。
+
+随附的 `vision-skills` Skill 携带完整的上游 playbook，说明每个工作流何时使用、按什么顺序调用工具，以及如何验证结果：
+
+| 手册 | Agent 学会做什么 |
+| --- | --- |
+| [读取长截图、聊天记录和滚动页面](assets/skill/references/long-screenshot-ocr.md) | 找到低内容切割带、按顺序 OCR 每个分块、保留聊天发言人/时间戳/引用、只合并重复的重叠部分，并标出有风险的边界供验证 |
+| [根据截图或设计重建 UI](assets/skill/references/restore-ui.md) | 优先复用项目组件和素材，再用代码原生 UI、提取的视觉素材、渲染截图和视觉对比来对齐页面或组件 |
+| [还原图标、Logo、插画或其他图形](assets/skill/references/restore-graphic.md) | 从源图像提取透明 PNG，或按需重建可编辑/可缩放 SVG，然后验证形状、颜色和 alpha 边缘 |
+| [把草图、示意图或白板转成结构化代码](assets/skill/references/restore-structure.md) | 把节点、标签、连接和方向恢复为可编辑的 Mermaid、Graphviz 或其他结构化表示 |
+| [通过截图操作 GUI](assets/skill/references/gui.md) | 定位控件、执行一个动作、再次截图，并先验证结果状态再继续 |
+
 
 ## 实际效果
 
@@ -106,7 +97,7 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
   <img src="assets/dsh-view-example.png" width="82%" alt="DSH Web 中，纯文本 DeepSeek 模型通过 Vision Toolkit 回答用户粘贴图片里的内容" />
 </p>
 
-*用户粘贴一张图片，纯文本模型自动切换到对应的 `Vision Toolkit` 变体，并围绕用户的问题读取画面。*
+*用户粘贴一张图片，纯文本模型自动切换到对应的* `Vision Toolkit` *变体，并围绕用户的问题读取画面。*
 
 ### 从截图到可编辑页面
 
@@ -115,6 +106,8 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
   <img src="assets/upstream/infographic-result.webp" width="49%" alt="根据截图还原出的可编辑 HTML 和 CSS 页面" />
 </p>
 
+> 提示词示例：“（使用vision-skills），把这张图片还原成html”
+
 *左：参考截图；右：用 HTML/CSS 还原出的可编辑结果。视觉结果可以继续进入截图和像素对比流程，而不是停在“描述图片”。*
 
 ### 从手绘稿到可用界面
@@ -126,15 +119,19 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 *左：手绘参考；右：根据参考还原的可用界面。*
 
-### 让“差不多”变成“可验证”
+> 提示词示例：“（使用vision-skills），把这张草稿图做成可用的前端页面”
 
-仓库内置了一个可复现的 UI 还原示例：Agent 会先渲染参考图和实现，再用差异区域、热力图和 JSON 报告指导下一轮修正。
+### 快速 UI 还原：先出一版近似稿
 
-<p>
-  <img src="examples/ui-restoration/assets/initial.png" width="49%" alt="像素对比前仍有布局和样式偏差的初版 UI" />
-  <img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="经过视觉定位和像素对比后的 UI 实现" />
+<p align="center">
+  <img src="assets/upstream/ui-fast-restore-reference.webp" width="49%" alt="快速 UI 还原参考图：YouMind 首页原图" />
+  <img src="assets/upstream/ui-fast-restore-result.webp" width="49%" alt="使用快速 UI 还原模式生成的近似首页" />
 </p>
 
+> 提示词示例：“（使用vision-skills），把这张图片 快速 还原成html”
+
+*左：原始页面；右：保留主要布局、内容和视觉层级的快速还原稿，允许颜色和图标库近似。快速模式的目标是约三分钟内产出首版截图。*
+
 ## 快速开始：三步完成
 
 ### 1. 安装
@@ -166,23 +163,12 @@ dsh plugin --profile headless add @anionex/dsh-vision-toolkit
 按照 reference.png 还原页面，每轮截图后做像素对比，直到主要差异消失。
 ```
 
-## 常见任务
-
-| 任务 | 推荐工作流 |
-|---|---|
-| 图片问答 / 截图排障 | 看图 → 围绕当前问题回答 → 必要时继续定位 |
-| 找按钮、图标或文字区域 | 定位目标 → 返回像素框 → 生成标注预览 |
-| 提取截图里的图标 | 定位 → 裁剪 → 描摹为 SVG |
-| 读取长网页截图 | 自动分块 → OCR → 合并 Markdown → 检查边界 |
-| 复刻网页或组件 | 参考图 → 实现 → HTML 截图 → 像素对比 → 继续修正 |
-| 提取品牌视觉 | 裁剪区域 → 主色分析 → 前景提取 → 导出透明 PNG |
-
 ## 工具一览
 
 插件提供 10 个可以单独调用、也可以组合使用的视觉工具：
 
 | 工具 | 最适合解决的问题 | 主要结果 |
-|---|---|---|
+| --- | --- | --- |
 | `vision_glance` | “这张图里发生了什么？” | 针对性回答、描述、OCR、多图比较 |
 | `vision_ground` | “我要找的东西在哪？” | 原图像素坐标、可选带框预览 |
 | `vision_detect` | “图里有哪些按钮/图标/元素？” | 编号元素清单、坐标、可选预览 |
@@ -200,10 +186,18 @@ dsh plugin --profile headless add @anionex/dsh-vision-toolkit
 
 ## 工作原理
 
-插件把远程图片理解和可重复的本地图片处理放进同一套 Agent 工作流。展开下面的流程可以查看具体边界。
+插件把远程图片理解和可重复的本地图片处理放进同一套 Agent 工作流。下面的流程图展示了具体的职责边界。
 
-<details>
-<summary><strong>架构与图片输入行为</strong></summary>
+### 让描述始终围绕当前任务
+
+多数文本模型视觉桥接的做法是让多模态模型生成一段通用描述，再把描述交给文本模型，这等于多了一层必然有损的语义转换。Vision Toolkit 反过来恢复 **Agent 为什么想看这张图**：把用户消息或模型给出的调用原因作为 focus hint（聚焦提示）传给视觉模型，得到的是围绕当前步骤的重点描述——更少 token、更准确、响应更快。
+
+<p align="center">
+  <img src="assets/upstream/focus-hint-comparison-1.webp" width="49%" alt="通用图片描述与带 focus hint 的任务感知描述对比（一）" />
+  <img src="assets/upstream/focus-hint-comparison-2.webp" width="49%" alt="通用图片描述与带 focus hint 的任务感知描述对比（二）" />
+</p>
+
+**架构与图片输入行为**
 
 ```mermaid
 flowchart LR
@@ -227,8 +221,6 @@ flowchart LR
 
 对于明确标记为纯文本的模型，插件会注册 `<模型名> (Vision Toolkit)` 变体。默认情况下，在 DSH Web 粘贴图片时会自动切换到该变体，并把图片路径与带当前任务重点的视觉描述一起交给模型。
 
-</details>
-
 ## 配置与限制
 
 ### 默认免费服务
@@ -246,8 +238,8 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 这是共享的免费入口，不是无限量私有服务。请求保护规则包括：
 
 | 限制 | 当前值 |
-|---|---:|
-| 每日额度 | 每台机器每天 300 张图 |
+| --- | --- |
+| 每日额度 | 每台机器每天 100 张图 |
 | 单次请求图片数 | 最多 5 张 |
 | 单张图片大小 | 4 MiB |
 | 单张图片像素 | 20,000,000 |
@@ -279,119 +271,17 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 
 如果受信任的内部端点使用自签证书或 MITM 代理，可在启动 DSH 进程时设置 `VISION_SSL_VERIFY=0`。插件会把该值传入隔离的 Python 运行环境；未设置或使用其他值时仍默认校验证书。还支持大小写不敏感的假值 `false`、`off`、`no`、`none` 和 `disabled`。
 
-### 运行要求
-
-- DeepSeek Harness Web 或 Headless Profile。
-- Node.js `^22.19.0` 或 `>=24.0.0`。
-- Python 3.11+，通常无需预装：插件优先使用系统 Python；找不到时会自动下载固定版本托管 Python（3.13）并创建隔离环境，仅首次自动下载需要网络。
-- 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge。
-- 图片需为 PNG、JPEG、GIF 或 WebP，并位于会话工作区、平台临时目录或明确允许的目录中。
-
 ### 配置 Python 运行时
 
-默认情况下插件会自动选择系统 Python 3.11+，找不到时下载托管 Python，普通用户无需配置本节。以下内容供自动发现失败、需要固定版本或使用外部运行时的高级场景参考。
-
-打包的 `managed` 运行时会创建自己的隔离虚拟环境。`runtime.python` 指定的是引导或刷新该环境时使用的 Python 解释器，并不会把 managed 运行时替换成系统解释器的全局 site-packages。当自动发现失败或机器上有多个 Python 时，应设置这个选项；`runtime.mode: external` 也使用该覆盖值。
-
-要求 Python 3.11 或更高版本；自动下载的托管 Python 为 3.13.15，与系统 Python 一样只用于引导隔离环境。不设置覆盖值时，插件在 macOS/Linux 上依次尝试 `python3`、`python`，在 Windows 上依次尝试 `python`、`py -3`、`python3`，全部不可用时会自动下载托管 Python。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 Shell 命令，因此 Windows 启动器应填写 `py`（不要填写 `py -3`）；需要固定版本时，请填写绝对路径。
-
-在 Profile patch 中配置：
-
-```yaml
-- id: vision-toolkit
-  config:
-    runtime:
-      # macOS/Linux 系统 Python
-      python: python3
-      # 或使用项目内虚拟环境：
-      # python: /absolute/path/to/project/.venv/bin/python
-      # Windows 虚拟环境（YAML 中也可以使用正斜杠）：
-      # python: C:/Users/you/project/.venv/Scripts/python.exe
-      # Windows 启动器；其默认 Python 必须是 3.11+：
-      # python: py
-```
-
-对于 managed 运行时，创建项目内解释器并将 `runtime.python` 指向它即可。插件会把锁定依赖安装到自己的 managed 缓存中，因此将 lockfile 安装到这个引导环境是可选的：
-
-```sh
-python3 --version                         # 必须是 3.11 或更高
-uv venv .venv --python 3.13
-```
-
-对于 `runtime.mode: external`，请使用 **DSH Vision Toolkit 插件** checkout 中的 `runtime/requirements.lock` 安装锁定依赖，再把 `runtime.agentVisionToolkitPath` 指向另一个准确的 `agent-vision-toolkit` 快照。未被修改的打包目录 `vendor/agent-vision-toolkit` 就是这样的快照：
+大多数用户无需配置 Python 运行时：插件会优先使用系统 Python 3.11+，找不到时自动下载固定版本的托管 Python。
 
-```sh
-uv pip install --python .venv/bin/python \
-  -r /absolute/path/to/dsh-vision-toolkit/runtime/requirements.lock
-```
-
-```yaml
-- id: vision-toolkit
-  config:
-    runtime:
-      mode: external
-      python: /absolute/path/to/dsh-vision-toolkit/.venv/bin/python
-      agentVisionToolkitPath: /absolute/path/to/dsh-vision-toolkit/vendor/agent-vision-toolkit
-```
-
-Windows 请使用 `py -3 --version` 检查版本，并在对应命令中使用 `.venv\Scripts\python.exe` 和 `runtime\requirements.lock`：
-
-```powershell
-py -3 --version                         # 必须是 3.11 或更高
-uv venv .venv --python 3.13
-# 仅 external 模式需要；请使用插件 checkout 中 lockfile 的绝对路径：
-uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-vision-toolkit\runtime\requirements.lock
-```
-
-把 `runtime.python` 指向同一个解释器，保存 Profile patch 后重启 Web Profile。然后打开 **设置 → 视觉工具**：运行时面板应显示实际使用的解释器和 Python 版本；点击 **运行健康检查** 和 **测试视觉模型**，确认不再出现 Python 版本错误。最后可将一张 PNG/JPEG 放入会话工作区并调用 `vision_glance` 做冒烟测试。
-
-路径围栏会自动允许会话工作区和平台临时目录。macOS/Linux 的临时目录根路径是 `/tmp`。Windows 依次读取 `TEMP`、`TMP`，两者都未设置时使用操作系统回退值；模型生成的 `/tmp/...` 路径会先映射到该 Windows 临时目录，再执行常规 realpath 路径围栏检查。这些平台临时路径无需加入 `allowedDirs`。
-
-只有在需要读取会话工作区和平台临时目录之外的可信输入根目录时，才配置 `allowedDirs`：
-
-```yaml
-- id: vision-toolkit
-  config:
-    allowedDirs:
-      # macOS/Linux 示例
-      - /srv/vision-inputs
-      # Windows 示例（Windows 上改用这一项）
-      # - D:/vision-inputs
-```
-
-`allowedDirs` 是输入目录白名单，不是 managed 运行时缓存目录。managed 运行时自己的文件位于 `$DSH_HOME/cache/dsh-vision-toolkit`（未设置 `DSH_HOME` 时是 `~/.dsh/cache/dsh-vision-toolkit`），无需加入白名单。`allowedDirs` 内不会展开 `$env:TEMP` 或 `%TEMP%` 这类环境变量，因此额外输入根目录必须填写真实绝对路径。
-
-<details>
-<summary><strong>安装、升级、禁用和卸载</strong></summary>
-
-```sh
-dsh plugin --profile web update @anionex/dsh-vision-toolkit
-dsh plugin --profile web remove @anionex/dsh-vision-toolkit
-```
-
-如果从已停止发布的 `@dsh-external/dsh-vision-toolkit` 迁移，请先移除旧包，再安装 `@anionex/dsh-vision-toolkit`。
-
-需要临时禁用时，在 Profile patch 中设置：
-
-```yaml
-- id: vision-toolkit
-  disabled: true
-```
-
-重新启用或升级 Web 插件后，请重启 Web Profile 并刷新页面。
-
-</details>
-
-### 插件更新
-
-在 **设置 → 视觉工具** 中，**检查更新**会查询当前 Profile 的 npm registry。若插件是直接 registry 依赖，**自动更新并重启**只会安装用户刚确认的准确版本，完成校验后重启明确允许自重启、且使用固定 `--port` 的 POSIX Web 进程。本地/workspace/file/git/URL 安装、Windows、动态端口、只读 Profile 和由进程管理器托管的实例只允许检查版本。
-
-更新器会在修改前重新验证 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 时不能安装。
+需要覆盖 `runtime.python`、使用 `runtime.mode: external`、验证运行时，或允许读取其他目录时，请参阅 [Python 运行时配置](docs/python-runtime.zh.md)。
 
 ## 常见问题
 
 | 问题 | 处理方式 |
-|---|---|
+| --- | --- |
+| 视觉模型测试失败：`Vision API returned an incompatible response structure` | 通常是 API 地址少了路径前缀。LM Studio、Ollama 等本地 OpenAI 兼容服务需填写 `http://127.0.0.1:1234/v1`（带 `/v1`），插件会在其后拼接 `/chat/completions`；只填端口号会命中服务的未知端点并返回该错误 |
 | 粘贴图片后仍提示模型不支持图片 | 重启 Web Profile 并刷新页面，确认当前模型已切换到带 `(Vision Toolkit)` 的变体；也可以把图片先放进会话工作区，再调用 `/vision-skills` |
 | 免费服务提示 429 | 按错误中的 `Retry-After` 等待后重试；如果需要稳定高额度，切换到自己的视觉端点 |
 | 图片过大或像素超限 | 先裁剪或缩放图片；错误会明确显示是字节还是像素限制 |
@@ -400,9 +290,11 @@ dsh plugin --profile web remove @anionex/dsh-vision-toolkit
 | 找不到 Chrome | 安装 Chrome、Chromium 或 Edge；只有 HTML 截图不可用，其他工具不受影响 |
 | 产物无法预览 | 使用“打开文件”或结果中的工作区路径；预览 URL 只在 Web 路由可用时存在 |
 
-## 项目状态与限制
+## FAQ
+
+**接入视觉模型会显著增加成本吗？**
 
-当前版本专注于截图理解、视觉定位、OCR、素材提取、UI 还原和像素级验证。它不是视频/音频/摄像头输入系统，也不会自动点击 GUI；交互式标注编辑、远程服务集群、模型投票和跨会话视觉缓存也不在当前范围内。
+不会。每次检查只把必要的意图和图片发给多模态模型，调用之间不会累积上下文，因此额外成本很小。想进一步降低成本，可以用本地部署的小型多模态侧模型（例如 Gemma 4 或 Qwen 3.5/3.6 系列）提供视觉能力。
 
 ## 开发与社区
 
@@ -416,7 +308,7 @@ dsh plugin --profile web remove @anionex/dsh-vision-toolkit
   <img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="240" />
 </p>
 
-我是 <a href="https://anionex.me/">anionex</a>，一位 AI 原生开发者，曾位列 GitHub 全球开发者趋势榜第 <strong>3</strong> 名，项目累计超过 16k stars。想了解我后续的工作，欢迎在 <a href="https://github.com/Anionex">GitHub</a> 关注我。
+我是 [anionex](https://anionex.me/)，一位 AI 原生开发者，曾位列 GitHub 全球开发者趋势榜第 **3** 名，项目累计超过 16k stars。想了解我后续的工作，欢迎在 [GitHub](https://github.com/Anionex) 关注我。
 
 [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 由 [Anionex](https://anionex.me/) 创建。本仓库维护它面向 DeepSeek Harness 的原生集成。
 

package/assets/upstream/README.md

@@ -10,7 +10,9 @@ The source files exist at the packaged runtime pin [`c27d1a300962b553c0884993c57
 | `infographic-result.webp` | `assets/infographic-restore-result.png` |
 | `ui-sketch.webp` | `assets/ui-restore-sketch.png` |
 | `ui-result.webp` | `assets/ui-restore-result.png` |
-| `image-qa.webp` | `assets/effect-1.jpg` |
-| `screenshot-debugging.webp` | `assets/effect-2.jpg` |
+| `focus-hint-comparison-1.webp` | `assets/focus-hint-comparison-1.png` |
+| `focus-hint-comparison-2.webp` | `assets/focus-hint-comparison-2.png` |
+| `ui-fast-restore-reference.webp` | `assets/ui-fast-restore-reference.png` |
+| `ui-fast-restore-result.webp` | `assets/ui-fast-restore-result.png` |
 
 Each derivative preserves the complete frame, limits the longest edge to 1200 pixels, removes metadata, and uses WebP quality 90 for repository delivery. The originals and visual algorithms remain covered by the upstream [MIT License](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/LICENSE).

package/docs/python-runtime.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write dsh-vision-toolkit/docs/python-runtime.md
+python-runtime.md: d2071e9ffbffe97d44c5708193e24ee3eabb50b1
+python-runtime.zh.md: 0ef2e984b564b5436424fbca70262e0b9c59aed9

package/docs/python-runtime.md

@@ -0,0 +1,75 @@
+# Configure the Python runtime
+
+By default the plugin picks a system Python 3.11+, or downloads a standalone Python when none is found; most users never need to configure this section. The rest is for advanced setups where automatic discovery fails, a specific interpreter is required, or an external runtime is used.
+
+The packaged `managed` runtime creates its own isolated virtual environment. `runtime.python` selects the Python executable used to bootstrap or refresh that environment; it does not replace the managed environment with the interpreter's global site-packages. Set it when automatic discovery fails or when several Python installations exist. The override is also used by `runtime.mode: external`.
+
+Python 3.11 or newer is required; the automatically downloaded standalone Python is 3.13.15 and, like a system interpreter, is only used to bootstrap the isolated environment. Without an override, the plugin tries `python3` then `python` on macOS/Linux, and `python`, `py -3`, then `python3` on Windows, before falling back to the standalone download. A configured value is passed as one executable name or path, not as a shell command with arguments, so use `py` (not `py -3`) for the Windows launcher; use an absolute path when you need a specific version.
+
+Configure it in the Profile patch:
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      # macOS/Linux system Python
+      python: python3
+      # Or a project-local environment:
+      # python: /absolute/path/to/project/.venv/bin/python
+      # Windows venv (forward slashes also work in YAML):
+      # python: C:/Users/you/project/.venv/Scripts/python.exe
+      # Windows launcher, when its default Python is 3.11+:
+      # python: py
+```
+
+For a managed runtime, create the project-local interpreter and point `runtime.python` at it. The plugin installs the locked dependencies into its own managed cache, so installing the lockfile into this bootstrap environment is optional:
+
+```sh
+python3 --version                         # must report 3.11 or newer
+uv venv .venv --python 3.13
+```
+
+For `runtime.mode: external`, install the locked dependencies using the `runtime/requirements.lock` from the **DSH Vision Toolkit plugin** checkout, then point `runtime.agentVisionToolkitPath` at a separate exact `agent-vision-toolkit` snapshot. The packaged `vendor/agent-vision-toolkit` directory is such a snapshot when it has not been modified:
+
+```sh
+uv pip install --python .venv/bin/python \
+  -r /absolute/path/to/dsh-vision-toolkit/runtime/requirements.lock
+```
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      mode: external
+      python: /absolute/path/to/dsh-vision-toolkit/.venv/bin/python
+      agentVisionToolkitPath: /absolute/path/to/dsh-vision-toolkit/vendor/agent-vision-toolkit
+```
+
+On Windows, use `py -3 --version` for the version check and `.venv\Scripts\python.exe` plus `runtime\requirements.lock` in the corresponding commands:
+
+```powershell
+py -3 --version                         # must report 3.11 or newer
+uv venv .venv --python 3.13
+# External mode only; use the plugin checkout's absolute lockfile path:
+uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-vision-toolkit\runtime\requirements.lock
+```
+
+Point `runtime.python` at the same interpreter, save the Profile patch, and restart the Web Profile. Then open **Settings → Vision Toolkit**: the Runtime panel should show the resolved interpreter and Python version, and **Run health check** plus **Test vision model** should complete without the Python-version error. A final smoke test is to place a PNG/JPEG in the session workspace and call `vision_glance`.
+
+## Allowed input directories
+
+The path fence automatically allows the session workspace and the platform temporary directory. On macOS/Linux the temporary root is `/tmp`. On Windows it is `TEMP`, then `TMP`, with the operating-system fallback if neither is set; model-generated `/tmp/...` paths are translated to that Windows directory before the normal realpath fence runs. No `allowedDirs` entry is needed for these platform temporary paths.
+
+Use `allowedDirs` only for additional trusted input roots outside the workspace and platform temporary directory:
+
+```yaml
+- id: vision-toolkit
+  config:
+    allowedDirs:
+      # macOS/Linux example
+      - /srv/vision-inputs
+      # Windows example (use this instead on Windows)
+      # - D:/vision-inputs
+```
+
+`allowedDirs` is an input allowlist, not the managed runtime cache. The managed runtime keeps its own files under `$DSH_HOME/cache/dsh-vision-toolkit` (or `~/.dsh/cache/dsh-vision-toolkit` when `DSH_HOME` is unset); that directory does not need to be added. Environment-variable forms such as `$env:TEMP` and `%TEMP%` are not expanded inside `allowedDirs`, so configure extra roots with real absolute paths.

package/docs/python-runtime.zh.md

@@ -0,0 +1,75 @@
+# 配置 Python 运行时
+
+默认情况下插件会自动选择系统 Python 3.11+，找不到时下载托管 Python，普通用户无需配置本节。以下内容供自动发现失败、需要固定版本或使用外部运行时的高级场景参考。
+
+打包的 `managed` 运行时会创建自己的隔离虚拟环境。`runtime.python` 指定的是引导或刷新该环境时使用的 Python 解释器，并不会把 managed 运行时替换成系统解释器的全局 site-packages。当自动发现失败或机器上有多个 Python 时，应设置这个选项；`runtime.mode: external` 也使用该覆盖值。
+
+要求 Python 3.11 或更高版本；自动下载的托管 Python 为 3.13.15，与系统 Python 一样只用于引导隔离环境。不设置覆盖值时，插件在 macOS/Linux 上依次尝试 `python3`、`python`，在 Windows 上依次尝试 `python`、`py -3`、`python3`，全部不可用时会自动下载托管 Python。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 Shell 命令，因此 Windows 启动器应填写 `py`（不要填写 `py -3`）；需要固定版本时，请填写绝对路径。
+
+在 Profile patch 中配置：
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      # macOS/Linux 系统 Python
+      python: python3
+      # 或使用项目内虚拟环境：
+      # python: /absolute/path/to/project/.venv/bin/python
+      # Windows 虚拟环境（YAML 中也可以使用正斜杠）：
+      # python: C:/Users/you/project/.venv/Scripts/python.exe
+      # Windows 启动器；其默认 Python 必须是 3.11+：
+      # python: py
+```
+
+对于 managed 运行时，创建项目内解释器并将 `runtime.python` 指向它即可。插件会把锁定依赖安装到自己的 managed 缓存中，因此将 lockfile 安装到这个引导环境是可选的：
+
+```sh
+python3 --version                         # 必须是 3.11 或更高
+uv venv .venv --python 3.13
+```
+
+对于 `runtime.mode: external`，请使用 **DSH Vision Toolkit 插件** checkout 中的 `runtime/requirements.lock` 安装锁定依赖，再把 `runtime.agentVisionToolkitPath` 指向另一个准确的 `agent-vision-toolkit` 快照。未被修改的打包目录 `vendor/agent-vision-toolkit` 就是这样的快照：
+
+```sh
+uv pip install --python .venv/bin/python \
+  -r /absolute/path/to/dsh-vision-toolkit/runtime/requirements.lock
+```
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      mode: external
+      python: /absolute/path/to/dsh-vision-toolkit/.venv/bin/python
+      agentVisionToolkitPath: /absolute/path/to/dsh-vision-toolkit/vendor/agent-vision-toolkit
+```
+
+Windows 请使用 `py -3 --version` 检查版本，并在对应命令中使用 `.venv\Scripts\python.exe` 和 `runtime\requirements.lock`：
+
+```powershell
+py -3 --version                         # 必须是 3.11 或更高
+uv venv .venv --python 3.13
+# 仅 external 模式需要；请使用插件 checkout 中 lockfile 的绝对路径：
+uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-vision-toolkit\runtime\requirements.lock
+```
+
+把 `runtime.python` 指向同一个解释器，保存 Profile patch 后重启 Web Profile。然后打开 **设置 → 视觉工具**：运行时面板应显示实际使用的解释器和 Python 版本；点击 **运行健康检查** 和 **测试视觉模型**，确认不再出现 Python 版本错误。最后可将一张 PNG/JPEG 放入会话工作区并调用 `vision_glance` 做冒烟测试。
+
+## 允许读取的输入目录
+
+路径围栏会自动允许会话工作区和平台临时目录。macOS/Linux 的临时目录根路径是 `/tmp`。Windows 依次读取 `TEMP`、`TMP`，两者都未设置时使用操作系统回退值；模型生成的 `/tmp/...` 路径会先映射到该 Windows 临时目录，再执行常规 realpath 路径围栏检查。这些平台临时路径无需加入 `allowedDirs`。
+
+只有在需要读取会话工作区和平台临时目录之外的可信输入根目录时，才配置 `allowedDirs`：
+
+```yaml
+- id: vision-toolkit
+  config:
+    allowedDirs:
+      # macOS/Linux 示例
+      - /srv/vision-inputs
+      # Windows 示例（Windows 上改用这一项）
+      # - D:/vision-inputs
+```
+
+`allowedDirs` 是输入目录白名单，不是 managed 运行时缓存目录。managed 运行时自己的文件位于 `$DSH_HOME/cache/dsh-vision-toolkit`（未设置 `DSH_HOME` 时是 `~/.dsh/cache/dsh-vision-toolkit`），无需加入白名单。`allowedDirs` 内不会展开 `$env:TEMP` 或 `%TEMP%` 这类环境变量，因此额外输入根目录必须填写真实绝对路径。