@anionex/dsh-vision-toolkit 0.1.9 → 0.1.11

package/README.zh.md

@@ -1,38 +1,66 @@
-![DSH Vision Toolkit——面向纯文本 DeepSeek Harness Agent 的原生视觉工程能力](assets/hero.png)
+<p align="center">
+  <img src="assets/hero.png" alt="DSH Vision Toolkit——面向纯文本 DeepSeek Harness Agent 的原生视觉工程能力" />
+</p>
+
+<h1 align="center">DSH Vision Toolkit</h1>
+
+<p align="center">
+  <a href="https://github.com/Anionex/dsh-vision-toolkit/blob/main/README.md">English</a> | 中文
+</p>
+
+<p align="center">
+  <a href="https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit"><img src="https://img.shields.io/badge/%E7%94%B1%20dshfind-%E6%8E%A8%E8%8D%90-FFD700?style=flat-square" alt="由 dshfind 推荐" /></a>
+  <a href="https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit"><img src="https://img.shields.io/badge/dshfind%20%E8%AF%84%E5%88%86-94%20%7C%20%E6%9C%80%E9%AB%98%E5%88%86%E6%8F%92%E4%BB%B6-5B4CF0?style=flat-square" alt="dshfind 评分：94——最高分插件" /></a>
+  <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>
+  <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>
+  <a href="tests"><img src="https://img.shields.io/badge/verified-233%20tests-2EA44F?style=flat-square" alt="已验证：233 项测试" /></a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B7285?style=flat-square" alt="许可证：MIT" /></a>
+  <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 或 >=24" /></a>
+  <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>
+  <a href="cordis.patch.yml"><img src="https://img.shields.io/badge/DSH-Web%20%2B%20Headless-5B4CF0?style=flat-square" alt="DSH Web 与 Headless Profile" /></a>
+</p>
 
-# DSH Vision Toolkit
+## 让 DSH Agent 真正看见
 
-[![由 dshfind 推荐](https://img.shields.io/badge/%E7%94%B1%20dshfind-%E6%8E%A8%E8%8D%90-FFD700?style=flat-square)](https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit)
-[![dshfind 评分：94——最高分插件](https://img.shields.io/badge/dshfind%20%E8%AF%84%E5%88%86-94%20%7C%20%E6%9C%80%E9%AB%98%E5%88%86%E6%8F%92%E4%BB%B6-5B4CF0?style=flat-square)](https://dshfind.com/zh/plugins/Anionex/dsh-vision-toolkit)
-[![X (Twitter)](https://img.shields.io/badge/-@anion__ex-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/anion_ex)
-[![Release v0.1.9](https://img.shields.io/badge/release-v0.1.9-5B4CF0?style=flat-square)](https://github.com/Anionex/dsh-vision-toolkit/releases/tag/v0.1.9)
-[![Verified: 230 tests](https://img.shields.io/badge/verified-230%20tests-2EA44F?style=flat-square)](tests)
-[![License: MIT](https://img.shields.io/badge/license-MIT-0B7285?style=flat-square)](LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%5E22.19%20%7C%20%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
-[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](runtime/requirements.lock)
-[![DSH profiles](https://img.shields.io/badge/DSH-Web%20%2B%20Headless-5B4CF0?style=flat-square)](cordis.patch.yml)
+把截图交给纯文本 DeepSeek Harness Agent，它就能看懂画面、读取文字、定位元素、提取素材、还原界面，并用像素差异检查结果是否准确。
 
-**安装：** `dsh plugin --profile web add @anionex/dsh-vision-toolkit`
+DSH Vision Toolkit 将 [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 打包成原生 DSH 插件。安装后即可使用图片问答、OCR、原图像素坐标、UI 还原、像素对比、可下载产物和 Web 设置，无需自己拼接脚本。
 
-**DSH Vision Toolkit 将 [`agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) 作为原生 Profile Bundle 带入 DeepSeek Harness。**
+```sh
+dsh plugin --profile web add @anionex/dsh-vision-toolkit
+```
 
-让纯文本 DSH Agent 真正看见，并知道当前任务应该看哪里：通过带意图的图片问答、OCR、原图像素定位、UI 还原、像素验证、托管产物和 Web Settings 完成视觉闭环。10 个独立工具以结构化 schema 和 Agent 级渐进暴露取代 Shell 拼接。
+npm 包已经包含视觉工具快照，并默认使用托管运行时。**普通安装不需要下载源码，也不需要填写 `agentVisionToolkitPath`。**
 
 **上游工具箱：** [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) · **项目网站：** [agent-vision.anionex.me](https://agent-vision.anionex.me)
 
-[English](README.md) | 中文
+## 你可以用它做什么
 
-## 为什么需要它
+| 目标 | Agent 可以交付什么 |
+|---|---|
+| 看懂截图 | 针对问题作答、描述画面、比较多张图片或执行 OCR |
+| 找到界面元素 | 返回原图像素坐标，并可生成带框预览图 |
+| 按参考图还原页面 | 渲染网页截图、逐区域诊断差异并持续迭代 |
+| 提取可复用素材 | 裁剪图片、透明前景、主色板或可编辑 SVG |
+| 读取长截图 | 可审计分块、Markdown、manifest 和可恢复 OCR 运行目录 |
+| 验证视觉结果 | 差异百分比、主要偏差区域、热力图和 JSON 报告 |
+
+只有需要理解图片内容时才调用远程视觉模型。裁剪、描摹、像素对比、颜色分析、前景提取和 HTML 截图都在本地运行。
 
-`agent-vision-toolkit` 把视觉视为 Agent 可调用的能力，而不是基础模型自带的天赋。它会把“为什么要看这张图”带入视觉请求，从全局逐步收敛到目标区域，并用专用工具验证坐标、颜色、轮廓和差异，不把泛化描述直接当成证据。
+## 看看实际效果
 
-DSH Vision Toolkit 保留这套方法，并用原生 schema、DSH Credentials、受生命周期管理的运行时准备、可从 Session 日志重建的结构化结果、可预览产物、专用 Web 卡片和 Settings 取代 CLI 安装与 Bash 参数拼接。Agent 加载一个带版本的 Skill，只有当前任务需要视觉时才会获得 10 个工具 schema。
+第一个示例是 DSH Web 的真实界面视图；接下来两组示例来自本插件所打包的同一条 `agent-vision-toolkit` 代码线；最后一组展示 DeepSeek Harness Web 中的真实使用流程。素材来源见[素材溯源记录](assets/upstream/README.md)。
 
-本包完整交付已承诺的 P0 与 P1 产品范围。P2 的稳定 `ctx.visionToolkit` 服务会等到独立插件成为真实消费方后再发布；内部运行时不会把未经验证的生态接口伪装为稳定契约。
+### DSH 视图示例
 
-## agent-vision-toolkit 已验证的真实用例
+<p align="center">
+  <img src="assets/dsh-view-example.png" width="80%" alt="DSH Web 会话视图：纯文本的 DeepSeek-V4-Flash (Vision Toolkit) 模型回答用户粘贴的品牌横幅图内容。" />
+</p>
 
-前两张图是本 Bundle 所打包 `agent-vision-toolkit` 固定版本同一代码线上的官方实跑结果；图片问答与截图辅助排障这一张则是在 DeepSeek Harness Web 中实际运行的会话，展示 DSH 中的同一套工作流。上游图片来源见[素材溯源记录](assets/upstream/README.md)。
+*真实的 DSH Web 视图：用户粘贴一张品牌横幅截图，纯文本模型通过 `DeepSeek-V4-Flash (Vision Toolkit)` 图片输入变体回答图片内容。*
 
 ### 信息图还原：从截图到可编辑 HTML/CSS
 
@@ -61,47 +89,61 @@ DSH Vision Toolkit 保留这套方法，并用原生 schema、DSH Credentials、
 
 *左：DSH Web 中带意图的图片问答；右：DSH Web 中通过截图对比定位 UI 字段差异，并继续向 `vision_pixel_diff` 推进。上游工作流来源仍为 [`agent-vision-toolkit` 官方实跑](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/README.md#real-world-effects)。*
 
-DSH Vision Toolkit 在这些上游能力之外增加原生工具 schema、版本化生命周期、Credentials、结构化 Session 结果、产物、Web 展示、Settings 和渐进暴露。下一节展示由本 DSH 仓库实际执行并提交的可复现实证。
+DSH Vision Toolkit 把这套工作流带进 DSH，让结果可以直接成为文件、坐标、可度量的对比报告，或同一会话中的下一步行动。
 
-## DSH 原生实证：从参考图到像素级一致
+## 从大致相似到像素级一致
 
-仓库中的 UI 还原流程会渲染一个故意不准确的 HTML 实现，测得 `6.04%` 像素差异和 6 个非零差异区域；经过迭代后，在 `1200 × 720` 下达到相对参考图精确 `0%` 的差异。
+仓库内的 UI 还原流程从一个故意不准确的 HTML 实现开始。Vision Toolkit 测得 `6.04%` 差异，指出最需要修正的区域，并推动下一轮迭代。最终渲染结果在 `1200 × 720` 下达到精确 `0%` 差异。
 
 <p>
   <img src="examples/ui-restoration/assets/initial.png" width="49%" alt="Vision Toolkit 迭代前的 UI 还原候选，与参考图仍有可测量的布局和样式差异。" />
   <img src="examples/ui-restoration/assets/implementation.png" width="49%" alt="仓库内可复现流程生成的最终 UI 还原结果，与参考图达到零像素差异。" />
 </p>
 
-| 已验证范围 | 证据 |
+| 起点 | 结果 |
 |---|---|
-| 产品范围 | 10 个独立视觉工具、匹配的 `vision-tools` Skill、产物、专用 Web 卡片和实时 Settings |
-| 自动化覆盖 | 17 个 Vitest 文件 / 136 项通过测试，以及不依赖 DSH 开发树的可移植包检查 |
-| 真实 Profile | 干净临时 Web 与 Headless 安装、激活、禁用、重新启用和卸载 |
-| 视觉验收 | 可复现的 HTML 截图 → 像素对比示例，最终差异为 `0%` |
+| 参考图 | 可打开、可编辑的 HTML 实现 |
+| 第一次对比 | 主要问题区域的差异为 `6.04%` |
+| 最终对比 | 在 `1200 × 720` 下达到 `0%` 差异 |
 
-## 亮点
+## 它为什么好用
 
-- **看图但不让每轮提示词膨胀：** 初始只暴露 `vision_toolkit_activate`；加载 `vision-tools` 后，10 个独立 schema 才挂到当前 Agent，版本和健康管理始终不进入模型上下文。
-- **直接使用坐标，而不是解析自然语言：** 定位和元素盘点返回原图像素框，所有模型可见结果保持为结构化文字或 JSON。
-- **交付正式文件，而不是临时输出：** 裁剪、SVG 恢复、OCR、像素对比、前景提取和 HTML 渲染会生成带描述的产物，Web 客户端可预览、下载或在本地打开。
-- **受控管理运行时与凭据：** API Key 由 DSH Credentials 保管；managed 模式准备精确隔离的 Python 环境；失败的 Settings 候选不会替换当前服务 generation。
-- **闭合视觉验证循环：** 本地 HTML 渲染和像素差异排序支持参考图 → 实现 → 截图 → 度量迭代，不依赖模型原生图片通道。
-- **同一 Bundle 同时服务 Web 与 Headless：** Web 增加卡片、预览、Settings 和健康操作；Headless 保持相同工具语义和完整结构化结果。
+- **直接提出你要解决的问题。** “提交按钮在哪里？”和“这张截图为什么和参考图不一样？”都会进入针对性的视觉分析，而不是得到一段泛泛的描述。
+- **拿到可以继续使用的证据。** Agent 会返回坐标、OCR、测量结果、JSON 和文件，方便打开或交给下一步处理。
+- **工作流留在 DSH 里。** Credential、Settings、产物、Web 卡片和 Headless 结果都与会话的其他内容放在一起。
+- **能本地处理就不调用远程模型。** 裁剪、描摹、像素对比、颜色分析、前景提取和 HTML 截图都不消耗视觉 API 请求。
+- **让迭代有终点。** 参考图 → 实现 → 截图 → 像素对比，把 UI 还原变成有数据支撑的闭环。
 
-## 快速开始
+## 三步开始使用
 
-前置条件：DeepSeek Harness `0.1.0-rc.6` 或兼容的后续 `0.1.x` 版本、Python 3.11+，并确保 `dsh plugin` 可以使用 `pnpm`。从 npm 安装已发布的 Bundle，将其加入所需 Profile，并确认 Bundle 行已经挂载：
+使用 DeepSeek Harness `0.1.0-rc.6` 或兼容的后续 `0.1.x` 版本即可。插件会在第一次使用时准备托管运行时。
 
 ```sh
 dsh plugin --profile web add @anionex/dsh-vision-toolkit
 dsh plugin --profile headless add @anionex/dsh-vision-toolkit
-dsh --profile web --dump-config | grep vision-toolkit
-dsh --profile headless --dump-config | grep vision-toolkit
 ```
 
-旧 Profile 的 `pnpm-workspace.yaml` 必须使用 `nodeLinker: hoisted` 和 `autoInstallPeers: false`。更新后的 DSH launcher 会在 `dsh plugin` 运行前修复这两个自有设置；使用旧 launcher 时，应在安装前手动设置，避免 pnpm 在 Profile 内组装第二套 Harness 依赖图。
+1. 重启 Web Profile，打开 **设置 → 视觉工具**。
+2. 如果要使用远程视觉模型，选择 DSH Credential，然后执行**测试 API 连接**和**测试视觉模型**。
+3. 在会话中粘贴图片或把图片放进工作区，调用 `/vision-tools`，提出一个明确的视觉任务。
 
-安装后重启正在运行的 Web Profile，打开 **设置 → 视觉工具**，为远程工具选择 DSH Credential，先执行**测试 API 连接**，再执行**测试视觉模型**以验证一次真实图片请求。在会话中把图片放进工作区路径，调用 `/vision-tools`，再让 Agent 使用明确的 `vision_*` 工具。本地裁剪、SVG、像素、颜色、前景和 HTML 操作不需要视觉 API Credential。
+如果使用较旧的 DSH launcher，安装前可能需要在 Profile 中设置 `nodeLinker: hoisted` 和 `autoInstallPeers: false`。当前 launcher 会自动修复这些设置。
+
+安装后重启正在运行的 Web Profile，打开 **设置 → 视觉工具**，先执行**测试 API 连接**，再执行**测试视觉模型**。新安装会自动使用内置免费 Gemma 4 提供方，不需要 API Key 或 DSH Credential。若要使用其他提供方，请修改端点、模型或协议，并配置对应的 DSH Credential。
+
+## 加入交流群
+
+欢迎加入 `agent-vision-toolkit` 项目交流群，交流使用经验、反馈问题并提出建议。
+
+<p align="center">
+  <img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="260">
+</p>
+本地裁剪、SVG、像素、颜色、前景和 HTML 操作不需要视觉 API Credential。
+
+> **不需要本地路径。** 普通 npm 安装保持默认的 `runtime.mode: managed` 即可。`runtime.agentVisionToolkitPath` 只面向明确需要外部固定 checkout 的开发者或受控部署。
+
+<details>
+<summary><strong>技术架构</strong></summary>
 
 ## 工作原理
 
@@ -124,6 +166,8 @@ flowchart LR
 
 所有工具定义都调用同一个 Runtime；Runtime 在分发到固定上游快照或已配置的视觉提供方端点前，统一验证路径、限制、Credential、取消和超时。Web 展示读取相同的结构化结果与产物描述，因此不会改变 Headless 语义。健康、连接测试和版本检查只留在 Settings，不进入模型工具 schema。
 
+</details>
+
 ## 工具
 
 | 工具 | 执行方式 | 结构化结果 | 产物交付 |
@@ -141,6 +185,9 @@ flowchart LR
 
 插件不重新实现视觉算法。DSH 侧只负责验证路径与限制、解析 Credential、用 argv 向量调用固定上游脚本、解析精确输出契约、分类失败、描述文件，并把结果投影给模型和 Web 客户端。
 
+<details>
+<summary><strong>高级模型行为</strong></summary>
+
 ## 渐进式模型暴露
 
 运行时就绪状态属于整个 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 或插件被释放。
@@ -149,18 +196,20 @@ flowchart LR
 
 ## 纯文本模型的图片输入变体
 
-纯文本模型路由会获得同名的兄弟模型条目：`<模型名> (Vision Toolkit)`，挂在对应的提供方分组下。变体声明支持图片输入，因此粘贴的图片走原生附件流程——输入框缩略图、会话持久化图片与历史渲染全部保留——插件只在发往模型的请求链路上把每个图片块改写成 Vision Toolkit 描述文本，再转交上游路由。会话日志不被改动；回放与 UI 看到的始终是真实图片。
+纯文本模型路由仍会获得同名的兄弟模型条目：`<模型名> (Vision Toolkit)`，挂在对应的提供方分组下。但 DSH 原生图片块不会把粘贴附件的本地路径传给模型，因此默认粘贴流程会先把每张图片复制进会话工作区，再把绝对路径插入模型可见的消息。DSH 模型随后可以把这个路径传给 `vision_glance` 或其他视觉工具，并使用与 `agent-vision-toolkit` 对齐的 focus hint 和 `[vision model description]` 通道标记。会话日志保存可复用的路径引用，UI 保留粘贴记录。
 
 插件会自动为宿主明确声明为纯文本的每个模型注册变体（例如 DeepSeek 对话家族）。粘贴处理是全自动的：当当前模型被确认为纯文本、且它的变体已注册时，浏览器端集成会自动把会话切换到变体（会有一条简短提示说明新模型名），随后粘贴走原生流程，无需手动切换模型。宿主依据浏览器从实时模型目录读到的精确模型路由来裁决，模型选择器标签作为兜底；无法确认或支持图片的路由一律保持原生流程，而"纯文本但没有变体"的模型（例如变体被关闭时）继续走"粘贴转路径"：图片被复制进会话工作区，输入框里插入的是它的路径文本。
 
-描述转换需要已配置的视觉提供方及其 Credential；当运行时未就绪或读取失败时，请求链路上的图片块降级为说明文本，而不是让整轮失败。用 `imageInputVariants.enabled: false` 关闭变体，用 `imageInputVariants.providers` 限制被包装的路由，或用 `imageInputVariants.autoSwitch: false` 让纯文本模型继续走"粘贴转路径"。
+启用图片输入变体并将 `imageInputVariants.autoSwitch` 设为 `true` 时，描述转换需要已配置的视觉提供方及其 Credential；当运行时未就绪或读取失败时，请求链路上的图片块降级为与上游兼容的 `[vision unavailable: ...]` 提示，而不是让整轮失败。默认路径流程不需要先调用这层自动描述桥接，模型可直接使用收到的图片路径调用视觉工具。桥接不会把注入的上下文文件当作当前用户意图；如果图片来自工具调用，则使用最新的助手段落作为关注提示。用 `imageInputVariants.enabled: false` 关闭变体，用 `imageInputVariants.providers` 限制被包装的路由，或用 `imageInputVariants.autoSwitch: true` 显式启用原生附件自动切换。
+
+</details>
 
 ## 运行要求
 
 - 启用 Web 或 Headless Profile 的 DeepSeek Harness，并确保 `dsh plugin` 可以使用 `pnpm`。
 - Python 3.11 或更高版本。Managed 模式会创建隔离环境，用户无需手工安装上游 CLI（命令行界面）或 Python 包。
 - 首次启用 managed 运行时需要联网；如果配置的软件包缓存已有 `runtime/requirements.lock` 中的精确版本，则无需联网。
-- `vision_glance`、`vision_ground`、`vision_detect` 和非仅切分长截图 OCR 需要 OpenAI 兼容或 Anthropic 视觉端点及 DSH Credential。本地工具无需该 Credential 也可使用。
+- 内置免费 Gemma 4 提供方可直接用于 `vision_glance`、`vision_ground`、`vision_detect` 和非仅切分长截图 OCR。只有改用自定义 OpenAI 兼容或 Anthropic 端点时才需要 DSH Credential；本地工具不依赖任何远程提供方。
 - 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge；未安装受支持浏览器时，其他工具保持可用。
 - 输入必须是会话工作区或显式 `allowedDirs` 根目录内的 PNG、JPEG、GIF 或 WebP。
 
@@ -201,7 +250,7 @@ dsh plugin --profile web remove @dsh-external/dsh-vision-toolkit
 dsh plugin --profile web add @anionex/dsh-vision-toolkit
 ```
 
-重启后，Settings → 视觉工具 应显示插件版本 **0.1.9**。
+重启后，Settings → 视觉工具 应显示插件版本 **0.1.11**。内置免费提供方会自动选中；自定义提供方仍使用配置的 DSH Credential。
 
 通过注册表安装时，使用 Profile 的包管理命令更新依赖：
 
@@ -229,16 +278,16 @@ Bundle 默认使用 managed 运行时。Profile patch 可以覆盖提供方与
 - id: vision-toolkit
   config:
     provider:
-      baseUrl: https://api.inferera.com/v1
-      credential: VISION_API_KEY
-      model: gemini-3.6-flash
+      baseUrl: https://vision.anionex.me/v1
+      credential: ANIONEX_FREE_VISION
+      model: gemma-4-26b-a4b-it
       protocol: openai
       anthropicThinking: omit
       userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36
     language: zh
     timeoutMs: 60000
-    maxImageBytes: 10485760
-    maxImagePixels: 40000000
+    maxImageBytes: 4194304
+    maxImagePixels: 20000000
     concurrency: 4
     runtime:
       mode: managed
@@ -246,23 +295,23 @@ Bundle 默认使用 managed 运行时。Profile patch 可以覆盖提供方与
     imageInputVariants:
       enabled: true
       providers: []
-      autoSwitch: true
+      autoSwitch: false
 ```
 
 ### 配置字段
 
 | 字段 | 默认值 | 契约 |
 |---|---|---|
-| `provider.baseUrl` | `https://api.inferera.com/v1` | 提供方 API 基础 URL；去除结尾斜杠后使用。Anthropic 应填写以 `/v1` 结尾的基础 URL，不要填写完整 `/messages` URL |
-| `provider.credential` | `VISION_API_KEY` | DSH Credential 引用，不是密钥值 |
-| `provider.model` | `gemini-3.6-flash` | 远程工具使用的多模态模型名 |
+| `provider.baseUrl` | `https://vision.anionex.me/v1` | 内置免费 OpenAI 兼容端点；自定义提供方可改用其他基础 URL，使用时会去除结尾斜杠 |
+| `provider.credential` | `ANIONEX_FREE_VISION` | 免费服务的只读内置引用；自定义提供方使用 DSH Credential 引用，而不是密钥值 |
+| `provider.model` | `gemma-4-26b-a4b-it` | 远程工具使用的多模态模型名 |
 | `provider.protocol` | `openai` | `openai` 发送 Chat Completions 请求；`anthropic` 发送原生 Messages 请求 |
 | `provider.anthropicThinking` | `omit` | Anthropic thinking 字段。`omit` 不发送 thinking 字段，兼容性最好；仅当所选模型明确支持时使用 `disabled` 或 `adaptive`，提供方返回 HTTP 400 时应先恢复 `omit`。 |
 | `provider.userAgent` | 浏览器兼容默认值 | 视觉请求和显式连接测试发送的 User-Agent；可为提供方或代理兼容性覆盖 |
 | `language` | `zh` | 视觉输出语言：`zh` 或 `en` |
 | `timeoutMs` | `60000` | 完整操作截止时间，1000-600000 毫秒；每个工具可请求更窄的覆盖值 |
-| `maxImageBytes` | `10485760` | 每张输入图片的编码字节上限 |
-| `maxImagePixels` | `40000000` | 每张输入图片的解码像素上限 |
+| `maxImageBytes` | `4194304` | 每张输入图片的编码字节上限；内置免费服务最多接受 4 MiB |
+| `maxImagePixels` | `20000000` | 每张输入图片的解码像素上限；内置免费服务最多接受 20,000,000 像素 |
 | `concurrency` | `4` | 每个会话内的并发操作数，1-16 |
 | `runtime.mode` | `managed` | `managed` 使用打包快照；`external` 只接受精确固定版本 |
 | `runtime.agentVisionToolkitPath` | 未设置 | `external` 模式必填；必须是精确导出快照或固定 commit 的干净 Git checkout |
@@ -270,19 +319,34 @@ Bundle 默认使用 managed 运行时。Profile patch 可以覆盖提供方与
 | `allowedDirs` | `[]` | 额外的 realpath 解析输入根目录；会话工作区始终允许 |
 | `imageInputVariants.enabled` | `true` | 为纯文本模型路由在模型选择器中注册图片输入变体条目 |
 | `imageInputVariants.providers` | `[]` | 按提供方 id 限制被包装的上游路由；为空时包装所有符合条件的路由 |
-| `imageInputVariants.autoSwitch` | `true` | 粘贴时自动把纯文本会话切换到其图片输入变体，让图片保持原生流程；`false` 时纯文本模型继续走"粘贴转路径" |
+| `imageInputVariants.autoSwitch` | `false` | 是否在粘贴时自动把纯文本会话切换到图片输入变体；默认关闭，纯文本模型继续走 DSH 兼容的"粘贴转路径"流程 |
 
 ### Credential
 
-Web 设置页的只写 **API 密钥** 输入框直接接收真实密钥。留空表示保留现有密钥；填写后保存，会把密钥写入高级设置中的 **凭据名称**，默认名称是 `VISION_API_KEY`。Headless 部署可以在 `$DSH_HOME/.credentials.yaml` 中预置同名引用。
+内置免费提供方使用固定的 `ANIONEX_FREE_VISION` 引用，不接受也不会保存用户 API Key。修改端点、模型或协议切换到自定义提供方后，只写的 **API 密钥** 输入框会自动解锁；填写后保存，会把密钥写入高级设置中的 **凭据名称** 引用。Headless 部署可以在 `$DSH_HOME/.credentials.yaml` 中预置该自定义引用。
 
 Settings 只保存引用，不保存值。浏览器不会读取已保存的密钥，保存成功后输入框也会立即清空而不是回显。每次远程操作都会重新解析引用，并只把值注入对应子进程环境。插件排除用户 `.env`、checkout `.env`、`PYTHONPATH`、`PYTHONHOME`、`VIRTUAL_ENV` 和用户 site-packages，避免环境中的 Python 或上游配置覆盖选定的 DSH 提供方。日志、错误、工具结果、产物元数据和 Settings 响应都不包含密钥。
 
-### Managed 与 external 运行时
+### 内置免费服务限制
+
+公开服务是共享的零配置默认入口，不是无限量私有端点。限制由代理执行，并以 OpenAI 风格错误返回明确的原因代码和可读提示；限流响应还会携带 `Retry-After` 与请求额度响应头。
+
+| 限制 | 当前值 |
+|---|---:|
+| 单客户端 | 每个 UTC 日 100 次 |
+| 全局服务 | 每个 UTC 日 400 次 |
+| 突发 | 60 秒内 20 次 |
+| 图片字节 | 每张最多 4 MiB |
+| 解码像素 | 每张最多 20,000,000 像素 |
+| 输出 | 最多 512 tokens |
+
+### Managed 运行时与可选 external 运行时
 
 Managed 模式会验证 `vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json`，优先使用 `uv`，回退到 `venv` 加 pip，按 `runtime/requirements.lock` 安装精确版本，通过 heartbeat 锁协调并发准备，并只在全部探针通过后发布 staging 环境。
 
-External 模式用于开发或受控部署：
+大多数用户只需要 managed 模式。它已经包含在 npm 包中，会自动为你准备固定版本的 Python 环境。
+
+可选的 external 模式面向插件开发或受控部署，适用于已经维护好精确上游 checkout 的场景：
 
 ```yaml
 - id: vision-toolkit
@@ -299,6 +363,8 @@ External 模式用于开发或受控部署：
 
 Web Profile 会注册 Vision Toolkit Settings 分区，可配置提供方 URL、Credential 引用、模型、OpenAI/Anthropic 协议、Anthropic thinking 模式、User-Agent、语言、超时、字节/像素限制、并发数、运行时模式、Python 覆盖值、external 源码路径和允许目录。该页面还会显示插件/上游版本、当前运行时 generation、不含密钥的 Credential configured/source/writable 状态、运行时路径、健康检查结果和产物路由可用性。
 
+**插件更新**卡片会通过当前 Profile 配置的 npm registry 检查 `@anionex/dsh-vision-toolkit` 新版本。点击**自动更新并重启**后，插件只安装用户刚刚确认的准确版本，校验安装结果，启动独立重启辅助进程，再优雅重启 DSH Web；当前页面会等待新进程恢复，并在新插件版本开始服务后自动刷新。该操作要求同源请求，只能更新这个固定包，并且会串行执行；`link:`、`file:`、workspace、git、URL、传递依赖、无法唯一识别、只读或缺少 `pnpm` 的安装方式不会开放自动更新，避免覆盖本地开发源码。重启可能中断正在运行的任务，因此界面会要求再次确认。
+
 “保存并应用”会验证完整配置，准备候选 Python/上游运行时，提交 Settings revision，最后才原子切换 generation。候选被拒绝时，之前的 generation 继续服务，页面也会把这种状态与运行时确实不可用区分开来。“重新加载”始终恢复后端已保存的权威值，即使 revision 没有变化也会丢弃被拒绝的浏览器草稿。初始启动无法准备运行时时，Settings 路由仍可用于提交有效配置并激活首个 generation。陈旧浏览器 revision 不会覆盖较新的保存结果，而是返回冲突；刷新后再重试。只读 Settings 提供方允许查看和健康检查，但禁用保存。
 
 “运行健康检查”只执行本地检查。“测试 API 连接”是显式操作，会把已配置 Credential 发送到 `GET /models`；OpenAI 使用 Bearer 认证，Anthropic 使用 `x-api-key` 与 `anthropic-version`。这个轻量测试不会上传图片，也不会创建 completion。“测试视觉模型”会另行把插件自带的 `assets/vision-model-test.png` 通过与 `vision_glance` 相同的多模态运行路径发送出去；它会创建一次真实 completion，并用于权威确认所选端点、Credential、模型、协议和上游账户确实能够处理图片。视觉模型检查卡会单独显示“已实测”“未测试”或“测试失败”Tag，避免把 `/models` 返回 HTTP 200 误认为图片调用成功。插件加载和普通 Settings 读取不会发送这两类请求。
@@ -390,7 +456,14 @@ pnpm pack --dry-run
 
 ## 项目状态与范围
 
-版本 `0.1.9` 是当前公开 npm 发布。P0 和 P1 是本包的产品承诺。P2 是设计门槛：至少一个独立插件消费内部能力形态前，不发布稳定 `ctx.visionToolkit` 服务、能力发现 API 或提供方生态。Web 上传、拖拽、摄像头/视频/音频/文档输入、交互式标注框编辑、GUI 自动点击、远程服务集群、模型路由、模型投票和跨会话视觉缓存不属于当前产品范围。
+版本 `0.1.11` 是当前公开 npm 版本。产品重点是截图理解、视觉定位、OCR、素材提取、UI 还原和 DSH Web/Headless Profile 中的像素级验证。Web 上传、拖拽、摄像头/视频/音频/文档输入、交互式标注框编辑、GUI 自动点击、远程服务集群、模型路由、模型投票和跨会话视觉缓存不属于当前产品范围。
+
+<details>
+<summary><strong>维护者范围说明</strong></summary>
+
+稳定的 `ctx.visionToolkit` 服务和能力发现 API 会等到独立插件成为真实消费方后再发布。这样可以让公开集成面建立在已验证的使用场景上，而不是未经验证的生态契约上。
+
+</details>
 
 ## 社区与关于
 
@@ -409,11 +482,3 @@ pnpm pack --dry-run
 ## 许可证
 
 插件采用 MIT 许可。打包的 `agent-vision-toolkit` 快照在 `vendor/agent-vision-toolkit/LICENSE` 保留上游 MIT 许可证，并继续作为视觉算法的唯一实现。
-
-## 加入交流群
-
-欢迎加入 `agent-vision-toolkit` 项目交流群，交流使用经验、反馈问题并提出建议。请扫描下方二维码入群。
-
-<p align="center">
-  <img src="assets/community-group-qr.png" alt="agent-vision-toolkit 项目交流群二维码" width="320">
-</p>

package/lib/client.js

@@ -18,6 +18,10 @@ const NS = 'vision-toolkit';
 const SETTINGS_ROUTE = '/_dsh/vision-toolkit/settings';
 const PRESENTATION_META_KEY = '$dshVisionToolkit';
 const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+// Keep these browser defaults aligned with src/defaults.ts without importing server-side config.
+const BUILT_IN_FREE_VISION_BASE_URL = 'https://vision.anionex.me/v1';
+const BUILT_IN_FREE_VISION_CREDENTIAL = 'ANIONEX_FREE_VISION';
+const BUILT_IN_FREE_VISION_MODEL = 'gemma-4-26b-a4b-it';
 const en = {
     nav: 'Vision',
     settingsTitle: 'Vision Toolkit',
@@ -34,7 +38,7 @@ const en = {
     apiKeyBlank: 'The API key cannot contain only spaces.',
     apiKeyInvalid: 'Paste only the key, without a variable name, quotes, spaces, or line breaks.',
     credential: 'Credential name',
-    credentialHint: 'Advanced: the API key is stored under this name. Keep VISION_API_KEY unless another plugin configuration requires a different reference.',
+    credentialHint: 'The built-in free provider needs no user key. For a custom provider, this is the DSH credential reference used to store its key.',
     model: 'Model',
     protocol: 'API protocol',
     anthropicThinking: 'Anthropic thinking',
@@ -181,7 +185,7 @@ const zh = {
     apiKeyBlank: 'API 密钥不能只包含空格。',
     apiKeyInvalid: '请只粘贴密钥本身，不要包含变量名、引号、空格或换行。',
     credential: '凭据名称',
-    credentialHint: '高级用法：API 密钥会按此名称保存。除非其他插件配置要求不同名称，否则保持 VISION_API_KEY。',
+    credentialHint: '内置免费视觉服务无需用户密钥；切换到自定义服务时，此处是保存其密钥的 DSH 凭据名称。',
     model: '模型名称',
     protocol: 'API 协议',
     anthropicThinking: 'Anthropic thinking',
@@ -641,16 +645,16 @@ class VisionSettingsController {
 exports.VisionSettingsController = VisionSettingsController;
 function draftOf(value) {
     return {
-        baseUrl: value.provider?.baseUrl ?? 'https://api.inferera.com/v1',
-        credential: value.provider?.credential ?? 'VISION_API_KEY',
-        model: value.provider?.model ?? 'gemini-3.6-flash',
+        baseUrl: value.provider?.baseUrl ?? BUILT_IN_FREE_VISION_BASE_URL,
+        credential: value.provider?.credential ?? BUILT_IN_FREE_VISION_CREDENTIAL,
+        model: value.provider?.model ?? BUILT_IN_FREE_VISION_MODEL,
         protocol: value.provider?.protocol ?? 'openai',
         anthropicThinking: value.provider?.anthropicThinking ?? 'omit',
         userAgent: value.provider?.userAgent ?? DEFAULT_USER_AGENT,
         language: value.language ?? 'zh',
         timeoutMs: String(value.timeoutMs ?? 60000),
-        maxImageBytes: String(value.maxImageBytes ?? 10485760),
-        maxImagePixels: String(value.maxImagePixels ?? 40000000),
+        maxImageBytes: String(value.maxImageBytes ?? 4194304),
+        maxImagePixels: String(value.maxImagePixels ?? 20000000),
         concurrency: String(value.concurrency ?? 4),
         runtimeMode: value.runtime?.mode ?? 'managed',
         toolkitPath: value.runtime?.agentVisionToolkitPath ?? '',
@@ -699,6 +703,12 @@ function valueOf(draft, t) {
         allowedDirs: draft.allowedDirs.split(/\r?\n/).map(entry => entry.trim()).filter(Boolean),
     };
 }
+function isBuiltInFreeVisionDraft(draft) {
+    return draft.baseUrl.trim().replace(/\/+$/, '') === BUILT_IN_FREE_VISION_BASE_URL
+        && draft.credential.trim() === BUILT_IN_FREE_VISION_CREDENTIAL
+        && draft.model.trim() === BUILT_IN_FREE_VISION_MODEL
+        && draft.protocol === 'openai';
+}
 function Field({ label, children, hint }) {
     return (0, jsx_runtime_1.jsxs)("label", { className: "dvt-field", children: [(0, jsx_runtime_1.jsx)("span", { children: label }), children, hint === undefined ? null : (0, jsx_runtime_1.jsx)("small", { children: hint })] });
 }
@@ -840,7 +850,11 @@ function LoadedSettings({ controller, t }) {
     };
     const busy = state.action !== undefined;
     const credentialMatchesSnapshot = draft.credential.trim() === snapshot.credential.ref;
-    const keyLocked = credentialMatchesSnapshot && !snapshot.credential.writable;
+    const builtInCredentialChangedProvider = snapshot.credential.source === 'built-in-free'
+        && !isBuiltInFreeVisionDraft(draft);
+    const keyLocked = credentialMatchesSnapshot
+        && !snapshot.credential.writable
+        && !builtInCredentialChangedProvider;
     const canSave = snapshot.writable || (apiKey.length > 0 && !keyLocked);
     const runtimeErrorTitle = snapshot.runtime.ready ? t('runtimeCandidateRejected') : t('runtimeUnavailable');
     return ((0, jsx_runtime_1.jsxs)("div", { className: "dvt-settings", children: [(0, jsx_runtime_1.jsx)("div", { className: "dvt-alert notice", children: t('externalNotice') }), !snapshot.writable ? (0, jsx_runtime_1.jsx)("div", { className: "dvt-alert warning", children: t('readOnly') }) : null, draftError === undefined ? null : (0, jsx_runtime_1.jsx)("div", { className: "dvt-alert error", children: draftError }), state.error === undefined ? null : (0, jsx_runtime_1.jsx)("div", { className: "dvt-alert error", children: state.error }), state.message === 'saved' ? (0, jsx_runtime_1.jsx)("div", { className: "dvt-alert success", children: t('saved') }) : null, snapshot.runtime.lastError === undefined ? null : (0, jsx_runtime_1.jsxs)("div", { className: "dvt-alert error", children: [(0, jsx_runtime_1.jsx)("strong", { children: runtimeErrorTitle }), (0, jsx_runtime_1.jsx)("span", { children: snapshot.runtime.lastError })] }), (0, jsx_runtime_1.jsxs)("section", { className: "dvt-panel dvt-essential", children: [(0, jsx_runtime_1.jsxs)("div", { className: "dvt-panel-title", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h3", { children: t('provider') }), (0, jsx_runtime_1.jsx)("p", { children: t('providerHint') })] }), (0, jsx_runtime_1.jsx)("span", { className: `dvt-badge ${snapshot.credential.configured ? 'ok' : 'error'}`, children: snapshot.credential.configured ? t('configured') : t('missing') })] }), (0, jsx_runtime_1.jsxs)("div", { className: "dvt-form-grid", children: [(0, jsx_runtime_1.jsx)(Field, { label: t('protocol'), children: (0, jsx_runtime_1.jsxs)("select", { disabled: !snapshot.writable || busy, value: draft.protocol, onChange: (event) => { update('protocol', event.target.value); }, children: [(0, jsx_runtime_1.jsx)("option", { value: "openai", children: "OpenAI Chat Completions" }), (0, jsx_runtime_1.jsx)("option", { value: "anthropic", children: "Anthropic Messages" })] }) }), (0, jsx_runtime_1.jsx)(Field, { label: t('baseUrl'), children: (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Input, { disabled: !snapshot.writable || busy, value: draft.baseUrl, onChange: (event) => { update('baseUrl', event.target.value); } }) }), (0, jsx_runtime_1.jsx)(Field, { label: t('model'), children: (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Input, { disabled: !snapshot.writable || busy, value: draft.model, onChange: (event) => { update('model', event.target.value); } }) }), (0, jsx_runtime_1.jsx)(Field, { label: t('apiKey'), hint: keyLocked ? t('apiKeyLocked') : snapshot.credential.source === undefined ? t('apiKeyHint') : `${t('apiKeyHint')} ${t('sourceHint', { source: t('source'), value: credentialSource(snapshot.credential.source, t) })}`, children: (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Input, { "aria-label": t('apiKey'), type: "password", autoComplete: "new-password", disabled: busy || keyLocked, placeholder: snapshot.credential.configured ? t('apiKeyPlaceholderConfigured') : t('apiKeyPlaceholderMissing'), value: apiKey, onChange: (event) => { setApiKey(event.target.value); setDraftError(undefined); } }) })] })] }), (0, jsx_runtime_1.jsxs)("div", { className: "dvt-save-row", children: [(0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Button, { variant: "primary", disabled: !canSave || busy, onClick: save, children: state.action === 'save' ? t('saving') : t('save') }), (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Button, { variant: "outline", disabled: busy, onClick: () => { void controller.load(); }, children: t('reload') })] }), (0, jsx_runtime_1.jsxs)("section", { className: "dvt-panel", children: [(0, jsx_runtime_1.jsxs)("div", { className: "dvt-panel-title", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h3", { children: t('health') }), (0, jsx_runtime_1.jsx)("p", { children: t('connectionHint') })] }), (0, jsx_runtime_1.jsxs)("div", { className: "dvt-actions", children: [(0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Button, { size: "sm", variant: "outline", disabled: busy || !snapshot.runtime.ready, onClick: () => { void controller.runHealth('health'); }, children: state.action === 'health' ? t('testing') : t('runHealth') }), (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Button, { size: "sm", variant: "outline", disabled: busy || !snapshot.runtime.ready, onClick: () => { void controller.runHealth('connection'); }, children: state.action === 'connection' ? t('testing') : t('testConnection') }), (0, jsx_runtime_1.jsx)(dsh_client_ui_primitives_1.Button, { size: "sm", variant: "primary", disabled: busy || !snapshot.runtime.ready, onClick: () => { void controller.runHealth('model'); }, children: state.action === 'model' ? t('testingModel') : t('testModel') })] })] }), (0, jsx_runtime_1.jsx)("p", { className: "dvt-muted", children: t('saveBeforeTesting') }), state.health === undefined ? (0, jsx_runtime_1.jsx)("p", { className: "dvt-muted", children: t('notTested') }) : (0, jsx_runtime_1.jsx)("div", { className: "dvt-health-grid", children: Object.entries(state.health.checks).map(([name, check]) => {