简体中文 | English

DSH Vision Toolkit（@junjian.work 维护版）

为 DeepSeek Harness（DSH）提供统一粘贴图片入口：明确支持图片的模型直接接收 DSH durable attachment；纯文本、能力未知或格式不兼容时才保存到工作区，由 Agent 通过 10 个原生 vision_* 工具返回文字、坐标、颜色等结构化结果。

本包是 Anionex/dsh-vision-toolkit 的本地维护分支 （包名 @junjian.work/dsh-vision-toolkit），在官方基础上修补了 UA 兼容与粘贴预览体验， 并进行了全面的开箱即用与交互优化。修补明细见 PATCHES.md。

专属优化特性

1. 消息发送与粘贴捕获优化：
   • 采用 window capture 级别粘贴监听，确保在各种浏览器环境下粘贴图片均能可靠捕获与预览。
   • 增强 conversation.sendSession：发送时读取当前模型能力，原生多模态图片与工作区路径自动分流，同时保留原始 queue/steer 模式和失败重试草稿。
2. 开箱即用免激活（autoActivate: true 默认开启）：
   • 摆脱官方版本“必须由 Agent 主动调用 skill 工具加载 vision-tools 后才临时暴露工具”的限制。
   • Agent 会话初始化时即自动预激活并挂载全量 10 个 vision_* 工具，粘贴图片后 Agent 即可直接调用 vision_glance。
3. 粘贴预览与悬浮缩略图（Paste Dock & Zoom）：
   • 输入框上方显示待发送图片缩略图，支持点击弹出高保真全屏放大预览和单张移除。
4. Upstream User-Agent 规范化：
   • 修复官方请求头缺失导致的各类逆向 API 网关 403 拦截问题。

功能一览

| 工具 | 作用 | 是否调用视觉 API | |---|---|---| | vision_glance | 看图问答 / 描述 / OCR / 多图对比 | 是 | | vision_ground | 按描述定位图中目标，返回像素框 | 是 | | vision_detect | 盘点某类元素（按钮/输入框…），返回编号与像素框 | 是 | | vision_long_screenshot_ocr | 长截图拆分 OCR，合并为 Markdown | 是（splitOnly 模式除外） | | vision_crop | 按像素框裁剪图片 | 否 | | vision_trace | 图形矢量化导出 SVG | 否 | | vision_pixel_diff | 两张图像素级对比（热力图 + JSON） | 否 | | vision_extract_foreground | 提取图标/Logo 透明前景 | 否 | | vision_dominant_colors | 提取主色板 / 候选色评分 | 否 | | vision_html_screenshot | 本地 HTML 渲染为 PNG | 否 |

粘贴即识别：在 DSH Web 输入框直接 Ctrl+V 粘贴截图，输入框上方立即出现可放大、可删除的 Paste Dock 缩略图。发送时仅当当前模型明确支持图片且 MIME 为 PNG/JPEG/WebP/GIF 才走 DSH 原生 attachment（后台并发完成工作区懒保存）；其余情况懒保存到 .dsh-vision-toolkit/tmp/pasted-images/ 并交给 vision_*。纯粘贴未输入文字时自动补充“请分析这张图片。”。Dock 只在发送成功后清理，失败时保留供重试。

如何判定当前模型是否支持多模态

Vision Toolkit 不根据模型名称猜测，也不维护模型白名单。每次发送都执行以下判定：

1. 浏览器调用 connection.api.sessions.models({ sessionId })，取得当前 Session 实际选择的 provider/model；
2. 同源 capability endpoint 在 Host 端调用 ctx.llm.resolveModelInfo(provider, model)；
3. 只有 modelInfo.inputModalities?.includes('image') === true 才允许原生图片直通；
4. 同时检查 attachment service、部署的图片 MIME、单图大小、总大小和数量限制；
5. DSH Host 在 durable 消息写入前按相同规则再次原子核验，防止能力查询后切换模型的竞态。

| Adapter 返回的 inputModalities | 路由 | |---|---| | ['text', 'image'] | DSH 原生 durable attachment | | ['text'] | 工作区路径 + vision_* 回退 | | 未声明/undefined | 按未知能力处理并回退 | | 能力查询失败 | 保守回退 |

因此，自定义 Provider 或第三方 Adapter 即使实际模型能够看图，只要没有明确声明 image 输入能力，也不会被乐观地送入原生图片通道。

安装

前置条件：DSH（Web 或 Headless profile）、pnpm（dsh plugin 需要）、Python 3.11+ （managed 运行时自动准备，无需手动安装上游依赖）。

粘贴截图识别是 Web Profile 的功能（输入框 Ctrl+V）。只用 Web 的话装 web 即可； headless 无粘贴界面，但 10 个视觉工具同样可用。

双缩略图验收还要求 Web Profile 激活 @junjian.work/dsh-chat-width 并设置 chat-width.userImageThumbnail: true：原生消息缩略图由 DSH attachment UI 渲染，工具回退消息缩略图由 dsh-chat-width 的路径标记 renderer 渲染。缺少该插件时回退功能仍可用，但历史消息只显示路径文本。

从 tgz 安装（当前推荐，无需 npm 发布）

把 dist/junjian.work-dsh-vision-toolkit-<版本>.tgz 复制到目标机器后：

dsh plugin --profile web add file:/绝对/路径/junjian.work-dsh-vision-toolkit-<版本>.tgz
dsh plugin --profile headless add file:/绝对/路径/junjian.work-dsh-vision-toolkit-<版本>.tgz

从 npm 安装（包发布到 npm 后可用）

dsh plugin --profile web add @junjian.work/dsh-vision-toolkit
dsh plugin --profile headless add @junjian.work/dsh-vision-toolkit

验证安装

dsh --profile web --dump-config | grep vision-toolkit

输出应包含 @junjian.work/dsh-vision-toolkit 的 bundle 行。然后重启 Web Profile。

快速配置（视觉 API）

远程工具（glance/ground/detect/长截图 OCR）需要一个 OpenAI 兼容的视觉 API。准备三样东西：

| 配置项 | 含义 | 示例 | |---|---|---| | baseUrl | 视觉 API 的 OpenAI 兼容端点（通常以 /v1 结尾） | https://openrouter.ai/api/v1 | | credential | DSH Credential 引用名（不是密钥本身） | VISION_API_KEY | | model | 支持图片输入的多模态模型名 | google/gemini-2.5-flash、qwen-vl-max 等 |

方式 A：Web 设置界面（推荐）

1. 打开 设置 → 视觉工具；
2. 填写 Provider URL、Credential 引用名、Model；
3. 点 测试连接（向 /models 发请求验证）；
4. 点 保存并应用。

方式 B：编辑 profile 配置

在 ~/.dsh/profiles/web/cordis.patch.yml 追加（headless 同理）：

- id: vision-toolkit
  config:
    provider:
      baseUrl: https://openrouter.ai/api/v1   # 换成你的视觉 API 端点
      credential: VISION_API_KEY              # DSH Credential 引用名
      model: google/gemini-2.5-flash          # 换成支持图片的模型
    language: zh                              # 视觉输出语言 zh/en

设置密钥（Credential）

Credential 引用指向 DSH 凭据存储中的密钥。编辑 ~/.dsh/.credentials.yaml，加入一行：

VISION_API_KEY: sk-你的视觉API密钥

密钥只存在凭据文件里，配置文件只保存引用名，不会泄露密钥。

完成后验证

重启 Web → 粘贴一张截图 → 应立即看到 Paste Dock 缩略图。用图片模型发送后，历史 user message 应显示 DSH 图片缩略图；用纯文本模型发送后，Agent 应调用 vision_glance，历史 user message 仍应通过 dsh-chat-width 显示路径缩略图。两条路径成功后 Dock 才消失。 若提示工具未挂载（新会话首次），Agent 会自动先加载 vision-tools skill（或手动发 /vision-tools）。

使用示例

vision_glance images=["截图.png"] query="这是什么界面？"
vision_ground image="截图.png" target="发送按钮" preview=true
vision_detect image="截图.png" category="buttons"
vision_crop image="截图.png" region="100,100,300,300"
vision_pixel_diff original="参考.png" rebuilt="实现.png"

常见问题

| 现象 | 处理 | |---|---| | 粘贴后没有 Paste Dock | 确认插件已安装并重启 Web；粘贴用的是输入框 Ctrl+V（不是附件按钮） | | 纯文本模型发送后没有工作区路径 | 检查 /_dsh/vision-toolkit/model-capability 与 paste route；图片只在回退分支懒落盘 | | Model "..." does not support image input | 严格 Host admission 拒绝了查询后切模型的竞态；插件只会在可确认该 reason 且没有官方 rail 图片时回退一次 | | 视觉 API 返回 401/403/429 | 检查密钥、端点（/v1 后缀）、模型名、限流；403 code 1010 是 UA 拦截（本包已内置修复） | | 提示 vision_glance 等工具不存在 | 新会话首次需先加载 skill：发 /vision-tools 或让 Agent 自动加载 | | 首次使用联网准备运行时 | managed 模式首次启动会下载 Python 依赖，稍候即可 | | 配置不生效 | 修改 patch 或 Settings 后需完全重启 Web 并刷新页面 |

已知限制与责任边界

• Paste Dock 由 Vision Toolkit 负责；原生历史缩略图由 DSH attachment UI 负责；路径回退历史缩略图由 dsh-chat-width.userImageThumbnail 负责。Vision Toolkit 不复制第三套历史 renderer。
• PNG/JPEG/WebP/GIF 同时覆盖原生与回退；BMP 仅走工具回退。AVIF/SVG/TIFF/HEIC/HEIF 当前不承诺完整预览和发送。
• 严格“未知能力不写入 durable 图片消息”要求 DSH Host 在写入前使用保守门禁：只有 inputModalities 明确包含 image 才放行。未应用该 core 修复时，插件路由只能视为最佳努力。
• 已有官方 attachment rail 图片遇到文本模型时会阻止发送，避免为了回退 Paste Dock 而静默丢弃官方附件。

文档索引

• PATCHES.md — 本包相对官方版的修补记录
• DEVELOP.md — 本机开发 / 重新打包 / 发布流程