Self-contained vision for text-only DSH models: registers its own vision_read_image tool (verbatim OCR, reading-order layout, semantics, uncertainty), turns pasted images into local file paths through a capture-phase paste channel with rolling storage, and optionally exposes a loopback OpenAI/Anthropic-compatible endpoint. Talks to your own upstream directly, with no external vision CLI and no runtime dependency. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-vision-direct
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:eurekame2000/dsh-vision-direct
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
This plugin publishes its README in Chinese only.
给 DeepSeek Harness 的纯文本模型一双自己的眼睛:一个读图工具、一条粘贴通道,和一个可选的本机兼容端点。
不依赖任何外部视觉工具——没有 CLI 子进程、没有第三方包、不读写别的程序的配置。视觉上游是你自己填的任意 OpenAI / Anthropic 兼容端点。
English: A self-contained vision backend for DSH. It registers its own
vision_read_imagetool, turns pasted images into local file paths, and optionally exposes a loopback OpenAI/Anthropic-compatible endpoint. No external vision CLI, no third-party runtime dependency.
和同分类其它视觉插件的区别
同类插件大多走「贴图后立刻转成一段文字描述再喂给主模型」的路子。本插件走的是另一条:插件自己不描述图片,只把图片变成主模型能主动调用的能力。四条实质差别:
| 一次性转译派 | 本插件 | |
|---|---|---|
| 贴图之后 | 立刻送视觉模型,结果作为隐藏上下文塞进对话 | 只落盘 + 把路径插进输入框,图片不占上下文预算 |
| 模型怎么用 | 被动收到一段别人写好的描述,摘要即全部 | 主动调 vision_read_image,可按需重读、追问同一张图的其它方面 |
| 输出形态 | 一段自然语言观感 | 结构化证据:逐字 OCR / 按阅读顺序的版面区域 / 语义 / 颜色风格 / 不确定项单列 |
| 上游 | 通常绑定某家免费视觉模型或某个固定 provider | 你填任意 OpenAI 或 Anthropic 兼容端点,两套协议字段各自独立 |
另外两点别人没有的:
- 可选回环兼容端点:把同一份配置暴露成
127.0.0.1上的 OpenAI / Anthropic 兼容端口,让别的程序也能借用这套视觉能力。默认关闭。 - 密钥不进环境变量:不读
*_API_KEY,只写~/.dsh/vision/config.json(0600),页面永远拿不到明文。
取舍要说清楚:一次性转译的好处是主模型完全无感——不需要多一次工具调用就能「看到」图。本插件多花一轮工具调用,换来的是可追问、不丢细节、以及不把你的上游绑死在别人选的模型上。图片占比高、只想要「大概是什么」的场景,转译派更省事;要读准截图里的字、表格、报错,结构化证据更可靠。
为什么需要它
DSH 默认的模型只收文本。往里贴一张图,图片准入会直接拒绝;让它看一个截图路径,它也无从读起。常见做法是外挂一个视觉 CLI——但那意味着再装一个包、再维护一份它的配置、让它决定你的上游。
这个插件把这件事收回自己:
| 外挂方案 | 本插件 | |
|---|---|---|
| 视觉引擎 | 别人的 CLI | 你的端点,插件直连 |
| 配置 | 写进别人的配置文件 | 只写 ~/.dsh/vision/config.json |
| 依赖 | 视觉包 + 子进程 | Node 内置模块 |
| 协议 | 由 CLI 决定 | OpenAI / Anthropic 二选一 |
功能
- 读图工具
vision_read_image:本地路径或http(s)URL 进,结构化证据出——逐字 OCR、按阅读顺序的版面区域、语义、颜色风格、不确定项。工具 schema 每一轮都在模型眼前,不靠提示词触发。 - 粘贴转路径:
⌘V一张图,插件在捕获阶段拦下,存进~/.dsh/vision/pastes/,把路径文本插进输入框。模型看到的就是一个文件路径,然后自己调读图工具。同一张图重复粘贴按内容寻址,不产生第二份文件。 - 预设可管理:内置预设可以逐张移除(只是隐藏,随时一键恢复),也可以把当前填好的配置存成自己的预设。
- 滚动存储:落盘目录只保留最近 10 张(可配置,
0= 不限),超出的按最后使用时间删最旧的。刚粘过的那张会被刷新,不会因为「内容已存在」而被当成旧图先删。目录里不是本插件写的文件不碰。 - 可选的本机兼容端点:把同一份配置暴露成
127.0.0.1上的 OpenAI / Anthropic 兼容端口,带两套协议互转和自定义请求头。默认关闭,只在你确实要让别的程序接进来时打开。 - 两套上游协议:OpenAI Chat Completions 与 Anthropic Messages,字段各自独立。
- 密钥不出后端:页面只拿到
hasKey和打码预览,明文永远不回到浏览器;配置文件0600。
安装
dsh plugin --profile web add dsh-vision-direct
DSH Desktop 请在应用内 设置 → 插件 里安装(桌面端的 profile 归应用的插件管理器所有,命令行改不了它)。装完重启或刷新页面。
配置
打开 设置 → 视觉模型,选一个预设或自己填:
| 字段 | 说明 |
|---|---|
| 协议 | OpenAI(/chat/completions)或 Anthropic(/messages) |
| 上游地址 | 结尾带不带 /v1 都行 |
| 模型名 | 必须是能看图的模型(名字通常含 vl / vision / omni) |
| API Key | 只存在本机,页面不回显 |
| 额外请求头 | 值写 $uuid 表示每次请求换一个新 uuid |
内置预设:OpenCode Zen · Go 车道、OpenCode Zen、OpenAI 官方、Anthropic 官方。预设只负责填字段,所有值都能改。
填完先点 测试连接(一张 1×1 真图,验证鉴权和视觉输入),再点 读图自检 当场读一张图看证据。
想减就减:额外请求头每行右侧是「删除」;重置配置 会把上游、模型、密钥、请求头、粘贴张数一起清回默认值(会二次确认)。
用法
对话里直接给路径或 URL:
看看 ~/Desktop/invoice.png,把金额和日期列出来
或者直接粘贴截图。模型会拿到类似这样的证据:
一张测试图,画着一个红点。
── OCR(逐字)──
HELLO 42
── 版面(阅读顺序)──
1. [paragraph] HELLO
2. [title] 42
── 语义 ──
screenshot · 测试
实体:42(number;中央)
── 不确定 ──
· 边缘被裁切
支持 PNG / JPEG / GIF / WebP / BMP,单张 ≤ 8MB。HEIC 会被明确拒绝并提示先转格式。
工具契约
// 参数
{ "path": "绝对路径 / ~/… / http(s) URL", "prompt": "可选:这次额外关注什么" }
// 返回(节选)
{
"summary": "一句话说这张图是什么",
"ocr": { "full_text": "逐字原文", "lines": [{ "text": "…", "language": "zh-CN" }] },
"layout": { "regions": [{ "type": "table", "reading_order": 1, "text": "…" }] },
"semantics": { "scene": "…", "intent": "…", "entities": [], "relations": [] },
"visual": { "dominant_colors": ["#rrggbb"], "style": "…", "notes": [] },
"uncertainty": ["看不清、有歧义、可能被裁切的部分"],
"meta": { "source": "…", "mime": "image/png", "bytes": 12740, "model": "…", "ms": 12367 }
}
模型没按 JSON 回答时不会报错:原文进 summary,并在 uncertainty 里标明「这次没按格式回」,调用方永远拿到一个形状完整的对象。
数据留在哪
| 路径 | 内容 | 权限 |
|---|---|---|
~/.dsh/vision/config.json |
协议 / 上游 / 模型 / 密钥 | 0600 |
~/.dsh/vision/pastes/ |
粘贴落盘的图片,按内容寻址,默认只留最近 10 张 | 目录 0700,文件 0600 |
网络请求只有一个方向:发往你自己填的上游地址。没有遥测,没有回传。
与其它视觉插件共存
本插件不依赖、不读写、不启动任何其它视觉工具。如果你已经装了别的读图插件,两边都会注册一个能力近似的工具,模型的工具列表里会出现重复——建议只留一个。
兼容性
- DSH
>= 0.2.0 - Node.js
>= 20(用到内置fetch与node:test之外的零依赖实现)
开发
node test/e2e-offline.mjs
175 条离线断言,不联网:两套协议的请求头与端点、协议互转、证据解析兜底、缓存、粘贴落盘与内容寻址、滚动清理(含 0=不限与外来文件保护)、重置、预设增删、错误边界、网关四条转发路径、配置权限。测试会临时改写 ~/.dsh/vision/config.json,跑完恢复。
改路由时必须遵守的约定
前后端是靠约定对接的,没有 schema 校验,形状对不上也不会抛错,只会静默空白。加路由或改返回值时,两条一起检查:
- 路由返回对象,不返回裸数组或裸标量。
route()外壳把run()的返回值原样当响应体,不做包装。要吐列表就包成{ models: [...] },要吐单值就包成{ value: ... }。 - 前端按字段名取,别把 payload 当数组。 写成
Array.isArray(payload?.models) ? payload.models : []。后端若改回裸数组,这一行会恒空而不报错。
踩过的实例:/api/vision/models 曾经直接返回 listModels() 的数组,页面永远显示 0 个模型(上游实际有 32 个),而且 175 条断言全绿——因为该路由当时没有测试覆盖。所以规则 3:
- 新增路由要同时补一条形状断言,至少验证「返回的是对象、列表在预期字段下、不空」。只测状态码 200 挡不住这类 bug。
route() 的超时只是「页面不等了」:到点回 504,不会取消 run() 和它内部的上游请求。别指望它当中断器用。
License
MIT
Links
More in this category
liustack/modlens★ 4996
Vision bridge for text-only models: paste an image, get structured JSON evidence (OCR, layout, semantics).
ysr666/dsh-vision-router★ 1281
Free vision for text-only agents: built-in keyless vision chain plus pixel tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots); paste an image to use it.
Anionex/dsh-vision-toolkit★ 945
Vision for text-only models: paste an image and the model switches to a Vision Toolkit variant for image Q&A, multi-image comparison, long-screenshot OCR, screenshot-to-UI reproduction, element grounding, and pixel diff. No API key by default — images are processed by the author-hosted free service, 100 per machine per day; configurable to your own provider.
SAOS-3624/dsh-see-now★ 672
Lets a text-only agent watch a live screen or camera feed: every frame is scored by how much the picture changed, only the ones that matter are packed into one numbered sheet with an audio envelope, so the model looks at what actually changed instead of a screenshot every few seconds.
SAOS-3624/dsh-video-storyboard★ 560
Turns a video (a local file, or a Bilibili/yt-dlp link) into one addressable storyboard grid — numbered cells with exact timestamps, per-cell transcript and an audio envelope on the same timeline — and video_zoom re-reads any window at higher resolution, so a text-only model can look at the video instead of reading a summary.
kingcharleslzy-ai/dsh-qwen-studio★ 229
Qwen Image 2.1 workspace for DSH: Apple Silicon MLX or your own NVIDIA server, native reference editing, LoRA, ControlNet, inpainting, shared presets, gallery and live agent progress. Includes verified updates and an agent setup guide.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.