前言¶
在 DSH 智能体场景里，文本模型经常需要处理图片：用户发来截图、网页报错图、表格、长聊天记录，或者希望模型在图中找某个图标、按钮、文字区域。若底层模型本身不支持图片，插件就只能依赖外部补丁、手工转述，或者把图片先转成文字再交给模型。
dsh-vision-skill 是一个 DeepSeek Harness（DSH）标准插件版识图技能。它把识图能力包装成 DSH 原生 runtime skill，让不支持图片的纯文本模型也能看图、OCR、定位目标。
这是什么¶
dsh-vision-skill 由 DDDFXYqiming 维护，采用 MIT 授权。
它提供 DSH 原生 runtime skill vision，由模型按需加载，并渐进式暴露识图工具。加载后，对话中的图片相关请求可以路由到对应的本地工具，而不是要求文本模型直接理解图像。
该插件适用于 DSH 生态中的插件化智能体工作流，尤其适合需要在文本模型中补充图片识别、文字提取和目标定位能力的场景。
核心能力¶
下面介绍已核实的工具能力。
vision_analyze¶
vision_analyze 用于识别本地图片，支持 6 种模式：
generalocrtablecodeerrorevidence
其中 evidence 是结构化证据模式，返回一段 JSON，包含：
summary / ocr_full_text / layout / semantics / uncertainty / visual
这个模式适合需要把图片证据拆成可引用字段的场景，而不只是拿一段自然语言描述。
vision_ocr¶
vision_ocr 是独立 OCR 工具，保留原始排版。适合从图片中提取文字，同时尽量维持原有结构。
vision_ground¶
vision_ground 用于目标定位。模型可以请求在图中找某个目标，工具返回像素坐标和归一化坐标。
vision_detect¶
vision_detect 用于枚举一类元素，例如按钮、图标、表格单元格等，并给出编号和像素坐标框。
vision_dominant_colors¶
vision_dominant_colors 用于主色分析。该能力使用本地像素算法，不消耗视觉 API。
vision_long_screenshot_ocr¶
vision_long_screenshot_ocr 用于超长截图分块 OCR。流程是先跑本地 tesseract，失败时再交给 VLM 兜底，最后合并结果。
vision_clipboard¶
vision_clipboard 用于剪贴板图片兜底识别。适合截屏后直接让模型“看图”的场景。
工程化能力¶
除了工具本身，dsh-vision-skill 还有一些工程化设计。
直接贴图¶
v0.4 起直接贴图走 paste-to-path，不再需要 pi-ai 补丁。
如果旧版宿主没有 reference 能力，直接贴图会自动回退为插入路径文本。
多 provider 容错¶
插件支持多 provider failover。遇到 429 时，会按 Retry-After 退避重试一次。
图像缓存¶
插件提供图像记忆缓存，按图片 SHA-256 加 mode / budget / crop / prompt 做缓存。TTL 内命中时直接返回：
{
"cached": true
}
路径围栏¶
图片路径必须位于会话工作区、DSH 附件目录或 allowedDirs 之一，并经过 realpath 校验。
这可以防止任意路径图片被直接读取。
安装与启用¶
安装命令如下：
dsh plugin --profile web add github:DDDFXYqiming/dsh-vision-skill
该命令将插件安装到 web profile 中。
运行环境要求：
{
"engines": {
"node": ">=22.19"
}
}
密钥推荐用 DSH Credential 引用：
credential: VISION_API_KEY
插件也兼容明文 apiKey，但不推荐。
自定义配置时，用裸条目按 id 覆盖。如果出现重复 id，会触发：
duplicate loader entry id
宿主启动会直接崩溃，因此不建议在已有 vision-skill 条目的配置里再插入同 id 条目。
典型用法¶
在对话里用自然语言描述需求即可，请求会被路由到对应工具。
识别这张图 <路径>
对应工具：
vision_analyze
OCR 这张图 <路径>
对应工具：
vision_ocr
在这张图里找到 <目标>
对应工具：
vision_ground
返回像素坐标框。
清点这张图的所有按钮
对应工具：
vision_detect
这张图的主色是什么
对应工具：
vision_dominant_colors
该工具使用本地算法，不消耗视觉 API。
提取这段长聊天记录的文字
对应工具：
vision_long_screenshot_ocr
看图（剪贴板截图）
对应工具：
vision_clipboard
适用场景与注意事项¶
dsh-vision-skill 适合以下场景：
- 文本模型需要识别图片内容。
- 需要从图片中提取文字。
- 需要在图中定位目标或枚举元素。
- 需要处理超长截图。
- 需要分析图片主色。
- 希望在 DSH 中以原生插件方式管理识图能力。
使用前需要注意：
- 插件以当前 dsh 进程权限运行。安装前建议检查源码、依赖和许可证。
- 本插件以 runtime 层注册技能名
vision。如果同时安装 user 层或 project 层同名技能，可能互相遮蔽，建议二选一安装。 - 直接贴图属于 client/Web 行为。重启 web 宿主后，需要强刷浏览器才能验证。
- pi-ai 旧补丁仅作兼容保留。若 dsh 升级后旧补丁被重新打上，可运行：
scripts/restore_pi_ai_vision_patch.py
- 图片路径受工作区、DSH 附件目录或
allowedDirs限制。 - 自定义配置时避免重复 id，否则宿主启动会失败。
链接¶
GitHub：
https://github.com/DDDFXYqiming/dsh-vision-skill
授权：
MIT
