dsh-llm-vision

English | 中文

   [](package.json)

给纯文本模型可靠视觉 + OCR 的 DeepSeek Harness 插件。

沉淀了让截图 QA 可信的提示词工程、可靠性工程（预处理 / 重试 / 持久缓存）， 并补齐 DSH 原生体验——粘贴桥、免重启设置卡、URL 输入、附件引用。

> 状态：v0.2.2 已上线 GitHub 与 npm。已在真实 Web GUI 中对真实 OpenAI > 兼容视觉端点完成端到端验证（DashScope qwen3-vl-plus / qwen3.5-ocr）； > 217 个离线测试。v0.2.0 新增：免费引擎预设（智谱 GLM-4V-Flash、Gemini）、 > 多图批量读取、llm_vision_check 诊断工具、HEIC/HEIF 支持。v0.2.2 修复 > llm_vision_check 的 testCall 探针图（1×1 → 64×64，规避 qwen3-vl-plus > 最小尺寸限制），诊断现可端到端通过。

为什么需要它

纯文本模型（DeepSeek V4、GLM 文本系列……）看不了图。本插件注册面向模型的工具， 后端是任意 OpenAI 兼容视觉端点：

DSH 原生体验：

• 粘贴 / 拖拽图片到输入框发送即可：浏览器半在提交时把带图消息改写为附件引用（文本模型可解析），

并在会话里把引用原地升级为缩略图。

• 免重启设置卡（设置 → 插件配置 → llm-vision）：端点、模型、提示词、上限、重试、预处理、缓存。
• 三种输入：本地绝对路径、http(s) URL（拒绝重定向）、附件引用。
• 图片永不进入会话记录——只有返回文字进入对话。

安装

dsh plugin --profile web add dsh-llm-vision@0.2.2

版本号是刻意钉扎的：pnpm 11 会暂缓 24 小时内新发布的包，裸 add dsh-llm-vision （latest）在发版当天会静默装到上一版。本行随每次发版同步更新。

从源码 checkout 安装时，同一命令接受 tarball 或本地路径 （pnpm pack 以当前版本命名 tarball——请使用实际产出的文件名）：

pnpm install && pnpm build && pnpm pack   # → dsh-llm-vision-<版本号>.tgz
dsh plugin --profile web add ./dsh-llm-vision-<版本号>.tgz
# 或：dsh plugin --profile web add /路径/dsh-llm-vision   （先 build——lib/ 被 gitignore）

tarball 自带预构建的 lib/（node 半 + lib/client.js），安装方无需执行构建。

配置

官方 Web GUI 的「插件配置」页只暴露白名单内的 settings 命名空间——第三方 命名空间被刻意排除（官方注释将"插件声明暴露"列为延期工作）。因此设置卡会 显示「命名空间未暴露」说明；请改在 profile patch 层配置，密钥走环境变量 引用（patch 文件绝不写明文密钥）：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: llm-vision
  name: 'dsh-llm-vision'
  config:
    baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen3-vl-plus
    ocrModel: qwen3.5-ocr
    apiKey: !!js process.env.VISION_API_KEY

# ~/.dsh/.env（或启动 dsh 前 export）
VISION_API_KEY=sk-...

然后重启 GUI。设置 → 插件配置中卡片可见，并会说明这一限制而不是消失。

#### 免费预设（零成本路线）

不自己写 baseURL / model / ocrModel，一个 provider 开关即可从内置预设 填充——包括两条永久免费视觉路线（事实验证于 2026-08；免费政策会变， 调用失效时请复查各厂商文档）：

# 智谱 BigModel——免费 GLM-4V-Flash（中国大陆最佳默认）
- id: llm-vision
  name: 'dsh-llm-vision'
  config:
    provider: zhipu
    apiKey: !!js process.env.ZHIPU_API_KEY   # 或设 apiKeyEnv: ZHIPU_API_KEY

# ~/.dsh/.env
ZHIPU_API_KEY=你的智谱密钥   # https://open.bigmodel.cn——免费额度，无需绑卡

# Google Gemini——Google AI Studio 免费 key（aistudio.google.com，免绑卡）
- id: llm-vision
  name: 'dsh-llm-vision'
  config:
    provider: gemini
    apiKey: !!js process.env.GEMINI_API_KEY

# 阿里 DashScope（默认模型，作为预设）
- id: llm-vision
  name: 'dsh-llm-vision'
  config:
    provider: dashscope
    apiKey: !!js process.env.DASHSCOPE_API_KEY

显式 baseURL / model / ocrModel / apiKeyEnv 始终覆盖预设。免费预设的 OCR 复用同一视觉模型（extract_text 用 OCR 提示词驱动）——免费层有限速， 更适合交互使用而非批量跑。

可靠性工程

• 自动预处理——超过 1568px 的图片自动等比缩放、大体积重编码（JPEG q85，透明格式保留 PNG），

基于 macOS 自带 sips 零依赖；任何失败静默回退原图。HEIC/HEIF 输入一律重编码为 JPEG （端点对 HEIC 支持参差），仅在缺少 sips 的平台明确报错。解决「大截图必超时」经典故障。

• 重试——瞬时错误按 maxRetries 重试，指数退避（≤4s），预算等比递减（总预算 ≤ 2×超时）；

耗尽重试的错误带「（已重试 N 次）」后缀；调用方取消立即中止、绝不重试。

• 持久缓存——相同图片 + 模型 + 提示词 + 预处理参数命中内容寻址缓存（图片字节 SHA-256），

存于 ~/.cache/dsh-llm-vision/；只存文字回答、绝不存图片字节；TTL 30 天、上限 500 条、 原子写、0600/0700 权限。注意：敏感文档的 OCR 结果会以明文存在该缓存文件里——在意时把 cacheEnabled 关掉。

安全模型

• 视觉请求与图片下载一律拒绝 HTTP 重定向（redirect: 'error'）——bearer 凭证与图片字节不会离开所配端点。
• 请求体携带 base64 图片但不携带密钥；解析出的凭证绝不进日志。
• 只接受 http(s) URL 与本地路径，其余协议一律拒绝。
• 附件上传先校验（严格 base64、magic bytes、字节上限）再交给附件存储；只有引用 JSON（文本）进入会话。
• 响应体先按上限截断（maxOutputTokens × 8 + 64 KiB）再解析；错误摘要有界（200 字符）。
• 调用工具即把图片字节外发到所配端点——只把允许外传的图片交给模型。

测试状态

216 个离线单元/集成测试（vitest、mock HTTP 服务、tmp 目录缓存）+ 严格 typecheck + 每次推送的 CI。并已在真实 DSH Web GUI 中端到端验证：describe_image 真实读图 （DashScope qwen3-vl-plus）、extract_text 真实 OCR 转录（qwen3.5-ocr）、 attach 上传/回读路由经真实 web 服务器工作、设置卡在插件配置页正常渲染。 已知体验缺口：卡片在 GUI 中无法编辑取值（官方 settings 白名单），配置走 patch 层——见[配置](#配置)。

已知限制

• 附件/上传通道仅 PNG / JPEG / GIF / WebP（官方附件存储的类型集合）。**HEIC/HEIF 图片

可直接经工具读取**本地路径与 URL——macOS 上预处理会重编码为 JPEG——但向 GUI 粘贴 HEIC 文件会被拒绝并给出提示；请先转换或改传路径。Windows/Linux（无 sips）上读取 HEIC/HEIF 会得到明确报错。

• 预处理依赖 macOS sips（零依赖）；Windows/Linux 上静默降级、原样直发——

绝不报错，但超大图更易超时。字节边界（maxBytes）在加载阶段把关， 边界过小是干净的拒绝，不会崩溃。

开发

pnpm typecheck   # tsc -b + vitest 程序
pnpm test        # vitest run（216 个测试，全部离线）
pnpm build       # tsc -b && tsdown → lib/ + lib/client.js
pnpm watch       # tsdown --watch

许可与署名

Apache-2.0。基于：deepseek-harness packages/vision/tool-describe-image （whitelonng/dsh-plugin-describe-image，MIT）、dsh-web-ui 插件全家桶（Apache-2.0）、 llm_vision 设计（MIT）。见 [NOTICE](NOTICE) 与 [AGENTS.md](AGENTS.md)。