DDDFXYqiming/dsh-vision-skill

dsh-plugins / dsh-vision-skill

dsh-vision-skill 将 General_skills/vision-skill 图像工作流打包为原生 DeepSeek Harness 插件。它使用 DSH 扩展点来实现运行时技能、工具、凭据、会话、Web 服务器和客户端注入。

自 v0.4 起，粘贴的图像在消息发送前由客户端上传到工作区路径。模型接收一个路径并调用插件。较旧的 pi-ai 图像转路径补丁仍可用于兼容性。

工具

| 名称 | 用途 |
|---|---|
| vision | 运行时技能，按需公开图像工具 |
| vision_analyze | 以通用、OCR、表格、代码、错误或证据模式分析本地图像 |
| vision_ocr | 提取可见文本并保留其布局 |
| vision_ground | 定位指定目标并返回像素和归一化框 |
| vision_detect | 枚举元素，例如带编号框的 UI 控件 |
| vision_dominant_colors | 在本地计算主色，无需视觉 API |
| vision_long_screenshot_ocr | 以重叠分块对长截图进行 OCR，先使用本地 Tesseract，再回退到 VLM |
| vision_clipboard | 将剪贴板图像保存到工作区以供识别 |
| vision_activate | 在自动技能激活不可用时显式公开工具集 |

vision_analyze 证据模式返回 summary、ocr_full_text、阅读顺序 layout、语义 entities 和 relations、uncertainty 以及 visual 字段。结果可按图像 SHA-256、模式、预算、裁剪和提示进行缓存。缓存具有可配置的 TTL 和条目限制。

请求流程

图像脚本应用 Qwen 的动态分辨率预处理，并将结果发送到 OpenAI 兼容的多模态端点。Grounding 接受 JSON 或  输出，并将模型的 0 到 1000 坐标转换为像素。长截图先运行本地 tesseract，当 Tesseract 不可用时再使用配置的 VLM。

插件接受本地图像路径作为文本。直接路径在所有环境中都可用。Windows 截图可通过 vision_clipboard 从剪贴板保存。在 v0.4 中，粘贴到 DSH 输入框会将图像上传到 .dsh-vision/pasted/，并在消息中插入路径引用。因此消息包含文本而非图像块，所以纯文本 DSH 适配器仍可调用视觉工具。

安装

对于常规配置文件安装：

dsh plugin --profile web add github:DDDFXYqiming/dsh-vision-skill

对于本地开发，向 web 配置文件添加链接并在其中运行 pnpm install：

git clone https://github.com/DDDFXYqiming/dsh-vision-skill.git
cd dsh-vision-skill
add dsh-vision-skill: link: to the profile dependencies
捆绑的 cordis.patch.yml 提供了 id: vision-skill。在 profile 中覆盖它时，请使用一个完整的裸条目，不要插入具有相同 id 的第二个条目。补丁替换是基于行的，因此请包含所有必须保持生效的配置字段。

- id: vision-skill
config:
apiUrl: 'https://api.example.com/v1/chat/completions'
model: 'your-vision-model'
credential: 'VISION_API_KEY'
visionProviders:
- apiUrl: 'https://api.example.com/v1/chat/completions'
model: 'your-vision-model'
credential: 'VISION_API_KEY'
tesseract: tesseract
tesseractLangs: chi_sim+eng
pasteMaxBytes: 10485760
cache: true
cacheTtlSeconds: 3600
cacheMaxEntries: 200

credential 指的是 DSH 凭据，优先于内联的 apiKey。Provider 条目按顺序尝试；429、5xx 或网络错误可以将请求移到下一个条目。将凭据存储在 $DSH_HOME/.credentials.yaml 中。

主要选项包括默认值为 180 秒的 timeoutMs、默认值为 2 的 concurrency、用于路径围栏的 allowedDirs，以及上述缓存控制项。progressive: false 会在全局注册完整的工具集，而不是等待运行时 skill。

适配器支持

| 适配器或场景 | 粘贴的图片 | 备注 |
|---|---|---|
| dsh-llm-deepseek | 无需补丁即可工作 | 较新的 DSH 版本包含图片到路径的转换。 |
| dsh-llm-pi-ai | 通过 v0.4 的粘贴到路径功能工作 | 较旧的供应商补丁被保留，供仍使用原始附件路径的安装使用。 |
| 原生多模态模型 | 图片被直接发送 | 模型无需转换即可处理图片。 |

兼容性补丁是可选的，且因机器而异。在 DSH 升级后，仅在需要旧的附件行为时重新运行它，然后重启宿主。

powershell -File scripts\reapply-pi-ai-vision-patch.ps1

该补丁会编辑供应商的 dsh-llm-pi-ai 包，并包含一个本地 profile 路径。在另一台机器上使用之前，请更改该路径。它被排除在包文件列表之外。

测试与依赖

npm run check
python -m unittest discover -s tests -v
python scripts/vision.py --check --no-api

该插件需要带有 DSH 的 Node.js（@deepseek-ai/dsh-tools、@deepseek-ai/dsh-credentials 和 @deepseek-ai/schemastery）、带有 Pillow 的 Python 3、用于本地 OCR 快速路径的 Tesseract，以及所选 OpenAI 兼容视觉模型的凭据。

示例

识别这张图         → vision_analyze
OCR 这张图         → vision_ocr
找到图中的         → vision_ground
清点图里的按钮          → vision_detect
分析图片主色            → vision_dominant_colors
提取长截图文字          → vision_long_screenshot_ocr
识别剪贴板截图          → vision_clipboard

所有图片工具接收的是路径，而不是图片字节。该路径必须解析到会话工作区、DSH 附件目录或已配置的 allowedDirs 条目内。

相关
- SKILL.md 包含由 DSH 加载的运行时指令。
- templates/.env.example 记录了独立脚本配置。
- General_skills/vision-skill 包含共享的图像工作流。
- 运行时技能名称为 vision。避免在项目或用户作用域中安装另一个 vision 技能，因为 DSH 会按优先级解析项目、运行时和用户技能。

许可证

MIT