dsh-plugin-vision: DeepSeek Harness Plugin, Install & GitHub Guide

dsh-plugin-vision

为 DeepSeek Harness 中的纯文本大模型提供视觉能力——通过 Gemini / GLM 免费视觉 API 完成图像描述、OCR 与视觉问答。

Vision for text-only LLMs inside DeepSeek Harness (DSH) — describe images, OCR, and answer visual questions through the free Gemini / GLM vision APIs.

目录 Table of Contents

简介 Introduction
功能特性 Features
安装 Installation
API Key 配置 API Key Configuration
使用方法 Usage
工具参考 Tool Reference
插件配置项 Plugin Configuration
安全说明 Security
成本说明 Cost
浏览器端图片粘贴（可选）Browser Paste & Drop (Optional)
开发构建 Development
兼容性 Compatibility
已知限制 Limitations
常见问题 FAQ
许可证 License

简介 Introduction

DeepSeek 等主流文本模型不支持图片输入。本插件通过 Gemini（gemini-3.6-flash）与 智谱 GLM（glm-4.6v-flash，完全免费、国内直连）等外部视觉 API，把「看图」能力封装为 DSH 会话内可直接调用的工具，无需切换模型即可完成截图解读、文档 OCR、图表分析等任务。

本插件遵循 DSH 官方插件格式发布（dsh.bundle.patch + cordis.patch.yml），可作为 npm 包安装，或以 overlay patch 挂载。任何 API Key 都不会进入代码或仓库。

功能特性 Features

特性	说明
🖼️ `see_image` 工具	分析本地图片（png / jpg / jpeg / webp / gif，≤ 20MB），支持自定义提问
🔀 双提供商	Gemini 与 GLM 双通道，`auto` 模式自动选择可用 Key 的提供商
⚡ 粘性路由	自动记住上次成功的提供商，减少无效请求等待
🔄 故障转移	网络失败或限流时自动切换至另一提供商
⏱️ 限流重试	429 / 访问量过大自动退避重试（默认 3 次）
🗜️ 大图压缩	超过 4MB 的图片自动压缩至 1920px（JPEG 质量 85）后上传
🔑 `vision_set_key`	会话内保存 API Key（写入 DSH 凭据库，立即生效）
📊 `vision_status`	查看各提供商 Key 配置状态（不泄露 Key 本身）
📋 粘贴/拖入图片（内置）	浏览器端 Ctrl+V / 拖入 / 🖼️ 按钮 → 原生风格附件卡片，随包集成、重启不丢

安装 Installation

前置要求 Prerequisites

Node.js ≥ 20
DeepSeek Harness (DSH) 已部署
至少一个视觉 API Key（Gemini 或智谱 GLM，均可免费申请）

方式一：overlay patch（临时试用）

npm i -D dsh-plugin-vision
dsh web --patch node_modules/dsh-plugin-vision/cordis.patch.yml

方式二：合并进 profile（持久安装）

将以下内容合并进你的 profile cordis.patch.yml：

- insert:
    - id: dsh-plugin-vision
      name: 'dsh-plugin-vision'

如需自定义配置，可附加 config（字段见插件配置项）：

- insert:
    - id: dsh-plugin-vision
      name: 'dsh-plugin-vision'
      config:
        provider: auto        # auto | gemini | glm
        glmModel: glm-4.6v-flash

验证安装 Verify

重启 DSH 会话后，输入「查看我的视觉工具配置」或直接询问模型图片路径，模型应能调用 see_image。

API Key 配置 API Key Configuration

插件不内置、不提交任何 Key。按以下任意一种方式提供即可（优先级从高到低）：

方式 1：环境变量

export GEMINI_API_KEY=your_key        # Gemini（国内访问需代理）
export ZHIPU_API_KEY=your_key         # 智谱 GLM（直连，国内推荐）

方式 2：DSH 凭据库（持久）

编辑 ~/.dsh/.credentials.yaml：

GEMINI_API_KEY: your_key
ZHIPU_API_KEY: your_key

方式 3：会话内工具（立即生效，无需重启）

在对话中直接说：

帮我保存 Gemini 的 Key：AIza...

模型将调用 vision_set_key 完成写入。

Key 申请

Gemini：Google AI Studio（免费额度）
智谱 GLM：open.bigmodel.cn（glm-4.6v-flash 完全免费）

使用方法 Usage

在对话中自然描述需求即可，模型会自动调用视觉工具：

帮我看看这张图 D:\work\screenshot.png
这张订单截图里商品是什么？多少钱？
用 GLM 分析 code/my/logo.png，描述一下配色

显式指定提供商 / 模型：

用 gemini-3.6-flash 看 baojia/data/purchased_items/xxx.jpg，做 OCR

工具参考 Tool Reference

`see_image`

分析本地图片并返回视觉模型的理解结果。

参数	类型	必填	说明
`image_path`	string	✅	图片路径（绝对路径或相对当前工作区）
`question`	string	—	针对图片的问题；省略时默认要求详细描述
`provider`	string	—	`auto` / `gemini` / `glm`，默认 `auto`
`model`	string	—	覆盖默认模型名

`vision_set_key`

保存提供商 API Key 至 DSH 凭据库（~/.dsh/.credentials.yaml）。

参数	类型	必填	说明
`provider`	string	✅	`gemini` 或 `glm`
`api_key`	string	✅	API Key 值（非空）

`vision_status`

查询各提供商 Key 配置状态（仅报告是否已配置、来源与可写性，不回显 Key 内容）。

插件配置项 Plugin Configuration

字段	默认值	说明
`provider`	`auto`	默认提供商：`auto` / `gemini` / `glm`
`geminiModel`	`gemini-3.6-flash`	Gemini 默认模型
`glmModel`	`glm-4.6v-flash`	GLM 默认模型（免费）
`geminiKeyEnv`	`GEMINI_API_KEY`	Gemini Key 的凭据引用名
`glmKeyEnv`	`ZHIPU_API_KEY`	GLM Key 的凭据引用名
`maxAttempts`	`3`	限流重试次数（1-6）
`maxImageBytes`	`20971520`	图片读取上限（字节）
`downscaleThreshold`	`4194304`	超过该字节数触发压缩；`0` 关闭
`maxDimension`	`1920`	压缩后最长边（像素）
`jpegQuality`	`85`	压缩质量（0-100）

安全说明 Security

仓库中不含任何 API Key；Key 仅存在于你的环境变量或 ~/.dsh/.credentials.yaml。
.gitignore 已排除 .env、*.credentials.yaml、.dsh-vision/ 等敏感与临时路径。
vision_status 只报告配置状态，永不回显 Key。
调用凭证经 DSH 凭据服务按次解析，支持热更新，无需重启。
请求临时文件（含认证头的 curl 配置、请求/响应体）在每次调用后自动清理，不残留磁盘。

成本说明 Cost

视觉调用使用 Gemini / GLM 免费额度，通常为 0 元。
本插件自身的 DeepSeek token 开销：单次图像分析往返约数千 tokens，日常使用成本可忽略；具体计费见 DeepSeek 官方定价。

浏览器端图片粘贴与拖入（内置）Browser Paste & Drop (Built-in)

从 v0.2.0 起，粘贴能力随包集成（Host 半区注册 /vision/save-image HTTP 路由，Client 半区以标准 client bundle 加载），与视觉工具同装同删、重启不丢，不再需要单独的动态插件。

在聊天页 Ctrl+V 粘贴 / 拖入 / 点击 🖼️ 按钮 添加图片（可多张）；
图片经 POST /vision/save-image 保存至工作区 .dsh-vision/uploads/，输入框上方展示原生风格附件卡片（缩略图、可移除、可继续添加）；
不自动发送：输入问题后按 Enter 发送，模型自动调用 see_image 看图；
发送成功后附件卡片自动清除。

说明：浏览器→宿主通道由插件自有的 HTTP 路由实现（ctx.webServer.register），不依赖平台级 api-proxy 白名单，因此可以随 npm 包分发。

开发构建 Development

git clone https://github.com/tdf1995/dsh-plugin-vision
cd dsh-plugin-vision
npm install            # 安装 peer dependencies
npm run check          # 语法检查 lib/index.js
npm test               # 加载期回归测试
npm pack               # 本地打包验证

本插件为纯 JavaScript（ESM），无构建步骤，fork 即可修改。

兼容性 Compatibility

环境	支持	备注
Node.js	≥ 20	—
平台	Windows / POSIX	大图压缩依赖 pwsh + System.Drawing，仅 Windows 生效；其他平台自动回退原图
HTTP 客户端	`curl`	Windows 自带 `curl.exe`

已知限制 Limitations

粘贴/拖入仅对 Web UI（dsh web）生效；Host 侧工具在无 Web 界面（TUI 等）时也可用（此时无保存路由，浏览器功能自动缺席）。
/vision/save-image 路由仅监听回环地址，文件名经过消毒、大小受限；仍建议仅在本机使用。
GLM 免费层高峰时段偶发 429，插件自动重试，但极端繁忙时可能失败。
Gemini 在国内网络需代理访问；GLM 直连即可。

常见问题 FAQ

Q：为什么不把图片直接作为附件发送？

A：DeepSeek 等文本模型不支持图片输入，DSH 的输入框会拦截图片附件。本插件采用「保存图片 → 路径入消息 → 工具读图」的桥接方案，是文本模型下最接近原生视觉模型体验的实现。

Q：两个提供商都配了，会重复扣费吗？

A：不会。auto 模式按顺序尝试（记住上次成功者），仅在失败时切换；不会并行请求两个提供商。

Q：Key 存在哪里？安全吗？

A：存于 ~/.dsh/.credentials.yaml（权限 0600）或环境变量。仓库、会话日志均不落盘 Key。

许可证 License

生态 Ecosystem

awesome-deepseek-harness — DSH 插件精选列表
awesome-dsh-plugin
vlln/plugin-registry — 社区插件基建与开发引导

tdf1995 / dsh-plugin-vision

Installation

README