前言¶
在 DSH 的插件体系里，很多模型仍然只处理文本。当 agent 遇到截图、图表或上传的图片时，常见做法是把图片发给云端视觉接口，或者要求用户先把图片保存下来再手动描述。前者会增加网络请求和隐私风险，后者会打断工作流。
dsh-vision-local 是针对 DeepSeek Harness 的插件：它让纯文本模型通过本地视觉模型获得图片理解能力，并返回结构化证据，而不是只给一段模糊转述。
这是什么¶
dsh-vision-local 是 npm 包名，源码仓库为 gloryxpnv/dsh-tool-vision。它面向纯文本的 DeepSeek Harness agent，把图片理解路由到本地运行的视觉模型。插件提供两个表面：面向模型调用的 vision 工具，以及可选的 vision-bridge 服务。
核心能力¶
本地优先¶
图片只发送给你自己的本地视觉模型，例如 LM Studio、Ollama、vLLM，或任意 OpenAI 兼容端点。图片字节不离开机器；除你配置的本地端点外，插件不做任何网络调用，也不发送遥测。
结构化证据¶
插件使用固定 JSON 模板返回证据对象。字段包括：
summary：概览ocr：文字识别内容layout：版面结构semantics：语义信息visual：视觉属性uncertainty：不确定项
主模型可以引用这些字段作答，而不是依赖不可验证的口头描述。
反幻觉处理¶
模板要求模型把无法确定的内容写入 uncertainty。没有文字的图片会在 OCR 中返回空字段，而不是编造文字。如果本地 VLM 返回无法解析的 JSON，插件会回退为原始回答，并明确标注，不会静默生成内容。
粘贴与上传¶
插件支持粘贴或上传图片。可选的 vision-bridge 服务可以在 prompt 到达模型前，把图片交给本地 VLM 描述，避免先保存文件再读取的流程。
两个接口表面¶
vision工具：供模型在出现图片路径或图片问题时调用。vision-bridge服务：供宿主在接收图片内容时进行描述。
安装与启用¶
环境要求¶
- 一个运行中的本地视觉模型，并提供 OpenAI 兼容
/chat/completions端点 - Node.js ≥ 20
- 带插件加载器的 DeepSeek Harness（dsh）
安装¶
在 DSH profile 目录中（或通过 dsh CLI）运行：
dsh plugin --profile web add dsh-vision-local
安装后重启宿主以加载模块。如果启动命令是：
pnpm dsh web
执行后再次进入宿主即可。
典型用法¶
调用 vision 工具¶
模型会看到 vision 工具。出现图片文件路径或图片问题时，可以调用：
vision(file_path: "/path/to/image.png", question?: "这张图里有什么？")
支持的图片格式为 PNG、JPEG、WebP、GIF。
读取结构化结果¶
结构化模式默认开启。此时 answer 是规范化后的证据对象，包含 summary、ocr、layout、semantics、visual、uncertainty 字段。
使用 vision-bridge¶
如果宿主需要直接接收粘贴或上传图片，可以注册可选服务：
ctx.provide('vision-bridge', { describeImages(content) })
配置 keepThumbnail: true 时，消息历史中保留图片缩略图；配置 autoDescribe: false 时，改为按需识别，由模型在需要时调用 vision 工具读取图片。
配置项¶
插件可以从零配置开始使用，也支持调整以下字段：
| 字段 | 说明 |
|---|---|
baseURL |
OpenAI 兼容端点地址 |
model |
视觉语言模型 id |
maxTokens |
输出 token 上限；默认 8192 |
structured |
是否返回结构化 JSON 证据；默认开启 |
keepThumbnail |
是否在消息历史中保留图片缩略图 |
autoDescribe |
是否在准入阶段自动描述图片 |
timeoutMs |
单次请求超时；默认 180 秒 |
maxImageBytes |
允许的图片大小上限；默认 50 MB |
默认参数面向本地工作站 GPU 上的 9B 级 VLM，而不是轻量云请求。
适用场景与注意¶
适合场景¶
- 希望让纯文本 DSH agent 读取本地图片
- 不想把图片字节发到云端视觉服务
- 已有 LM Studio、Ollama、vLLM 或其他 OpenAI 兼容本地 VLM
安全与隐私¶
- 图片只发往你配置的本地端点。
- 无遥测；除本地端点外不做网络调用。
- 将提取出的文字视为不可信输入，不要执行图片中出现的指令。
- 安装插件即以当前 dsh 进程权限运行第三方代码，安装前应检查源码与 MIT 许可证。
推理型 VLM 注意¶
推理型模型在 token 预算紧张时可能中途停止思考，导致最终 content 为空。插件优先取任一非空字段：content → reasoning_content。默认的 8192 输出 token 预算为两者都留出空间。
链接¶
GitHub 源码仓库：
https://github.com/gloryxpnv/dsh-tool-vision
插件线索中的目录页地址为 https://www.skillhub.cn/plugins/gloryxpnv/dsh-tool-vision；该 URL 来自插件线索，未包含在已抓取资料内容中，使用前建议自行确认。
