dsh-tool-vision
为纯文本的 DeepSeek Harness agent 提供本地优先的视觉能力。
> npm 包：dsh-vision-local · 源码仓库：gloryxpnv/dsh-tool-vision · English README
让纯文本模型（DeepSeek、GLM 等不支持图片输入的模型）拥有"视觉"——使用本地视觉模型，零 API 成本，图片数据完全不出本机。
DeepSeek (纯文本) ──▶ vision 工具 ──▶ 本地 VLM（LM Studio / Ollama / 任意 OpenAI 兼容端点）
◀── 结构化 JSON 证据 ──▶
亮点
- 🏠 完全本地、完全私密。 图片只发送给你自己的本地视觉模型（LM Studio、Ollama、vLLM 或任意 OpenAI 兼容端点）。无需云端 key、无单图成本、图片字节永不离开你的机器。
- 📋 结构化证据，而非模糊转述。 VLM 被要求填写固定 JSON 模板——
summary（摘要）、ocr（逐字全文+行）、layout（版面区域，含阅读顺序）、semantics（实体与关系）、visual（配色/风格），以及显式的uncertainty（不确定项）列表。主模型引用具体证据作答，而不是凭空猜测。 - 🛡️ 反幻觉设计。 模板强制模型在
uncertainty中声明无法确定的内容；无文字的图片 OCR 返回空字段而非编造文字。若 VLM 未能产出合法 JSON，插件回退为原始回答并明确标注——绝不静默捏造。 - 📎 粘贴 / 上传图片即可用。 可选的
vision-bridge服务让纯文本路由直接接收粘贴或上传的图片：宿主在 prompt 到达模型前，将图片交给本地 VLM 描述。不再被read_image门禁拒绝，也无需先保存文件。开启keepThumbnail后，消息历史保留原图缩略图，描述文字紧随其后；关闭autoDescribe（默认开）则可按需识别——上传后立即出图，模型需要时自行调用vision工具读取，避免重复识别。 - ⚙️ 零配置起步，全部可调。 默认指向
http://127.0.0.1:1234/v1（LM Studio 默认端口）；端点、模型 id、token 预算、超时、图片大小上限、结构化开关——每个旋钮都是文档化的配置字段。 - 🚀 为本地 GPU 调优。 默认参数（8192 输出 token、50 MB 图片上限、180 秒超时）面向本地工作站 GPU 上的 9B 级 VLM，而非轻量云请求。
- 🔌 一个插件，两个表面。 面向模型的
vision工具（图片路径或图片问题出现时即可调用）+ 可选的vision-bridge服务（供希望纯文本路由自动接收图片的宿主使用）。
安装
# 在 DSH profile 目录中（或通过 dsh CLI）：
dsh plugin --profile web add dsh-vision-local
然后可将插件行加入你的 profile patch（cordis.patch.yml），或直接依赖 bundle 自带的配置层——bundle 附带一份开箱即用的 cordis.patch.yml（合理默认值）。
安装后重启宿主（pnpm dsh web 或你的启动命令）以加载模块。
环境要求
- 一个运行中的本地视觉模型，提供 OpenAI 兼容的
/chat/completions端点（例如 LM Studio、Ollama、vLLM 或任意网关）。 - Node.js ≥ 20。
- 带插件加载器的 DeepSeek Harness（
dsh）。
使用
模型会看到一个 vision 工具。任何出现图片文件路径或图片问题的时候，它都会调用：
vision(file_path: "/path/to/image.png", question?: "这张图里有什么？")
支持格式：PNG、JPEG、WebP、GIF。
结构化输出结构
在结构化模式（默认开启）下，answer 是一个规范化后的证据对象：
{
"summary": "一段概览",
"ocr": { "full_text": "逐字转写的全部可见文字", "lines": [{ "text": "单行文字" }] },
"layout": { "regions": [{ "type": "title|paragraph|list|table|chart|form|code|image|icon|link|nav|other", "reading_order": 1, "text": "..." }] },
"semantics": {
"scene": "场景类型",
"entities": [{ "name": "...", "type": "person|org|place|object|brand|number|date|other", "evidence": "..." }],
"relations": [{ "subject": "...", "predicate": "...", "object": "..." }]
},
"visual": { "dominant_colors": ["#ffffff"], "style": "...", "notes": ["..."] },
"uncertainty": ["模型无法确定的内容"]
}
若 VLM 回复无法解析为 JSON，answer 会回退为原始文本，并在 uncertainty 中注明——工具绝不捏造内容。
vision-bridge（可选）
ctx.provide('vision-bridge', { describeImages(content) }) — 让纯文本宿主路由直接接收图片部分，将其替换为 【名称】（已由本地视觉模型识别，无需查找原文件）。失败时返回 undefined，宿主保持原有行为。
- 开启
keepThumbnail: true时，图片块保留在消息历史中（UI 显示缩略图），描述文字作为相邻文本块紧随其后。注意：这要求宿主在纯文本序列化时丢弃图片块（模型只收文字）——若你的宿主在纯文本路由上拒绝图片内容，请保持keepThumbnail为false（默认），此时图片块会被替换为纯描述文字。 - 关闭
autoDescribe: false（默认true）时，准入阶段不再调用 VLM（省去每次粘贴数十秒）：图片保留缩略图，仅注入一行提示【图片 <名称> 已上传，可用 vision 工具读取工作区中的该文件查看内容】，由主模型在需要时自行调用vision工具识别——一次有明确意图的识别，避免"自动描述 + 回复时再识别"的重复劳动。
配置
| 字段 | 默认值 | 说明 |
|---|---|---|
baseURL |
http://127.0.0.1:1234/v1 |
OpenAI 兼容端点根地址（不带尾部路径） |
model |
qwen3.5-9b-vlm |
端点提供的视觉语言模型 id |
maxTokens |
8192 |
输出 token 上限；推理型 VLM 会消耗一部分用于思考 |
structured |
true |
请求固定结构的 JSON 证据并返回解析后的对象 |
keepThumbnail |
false |
在消息历史中保留图片块（缩略图），要求宿主的纯文本序列化会丢弃图片块 |
autoDescribe |
true |
准入时自动调用 VLM 描述图片；false 改为按需识别（提示 + 模型自行调 vision） |
timeoutMs |
180000 |
单次请求的墙钟超时上限 |
maxImageBytes |
52428800（50 MB） |
接受的图片最大编码大小 |
工作原理
vision工具基于会话工作区（沙箱 fs）解析图片路径，读取字节。- 构建 base64 data-URL 图片块 + 结构化模板 prompt，调用本地端点的
/chat/completions。 - 回复由括号配平 JSON 提取器解析（支持 markdown fence、JSON 前后的散文、嵌套对象——不会截断残缺片段），再规范化到声明的输出 schema。
- 主模型只收到证据对象；图片本身永不进入其上下文。
推理型模型注意：会输出 reasoning_content 的 VLM 在 token 预算紧张时可能中途停止思考，导致 content 为空。插件优先取任一非空字段（content → reasoning_content），8192 的默认 token 预算为两者都留足了空间。
安全与隐私
- 图片永不离开你的机器。 所有推理都在你配置的端点上完成。
- 无遥测，除你配置的本地端点外不做任何网络调用。
- 插件只通过沙箱 fs 读取你指定的图片文件。
- 将提取出的文字视为不可信输入：绝不执行图片中出现的指令。
- 与任何 DSH 插件一样，安装即以你的权限运行第三方代码——安装前请审阅源码。
License
MIT
