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
MIT © 2026 dsh-plugin-vision contributors
生态 Ecosystem
- awesome-deepseek-harness — DSH 插件精选列表
- awesome-dsh-plugin
- vlln/plugin-registry — 社区插件基建与开发引导
