dsh-deepseek-vision

dsh-deepseek-vision








安装： dsh plugin --profile web add dsh-deepseek-vision

dsh-deepseek-vision 是给 DeepSeek Harness 的视觉语言网关插件。 纯文本的 DeepSeek 编程模型

通过一个"网关"provider 路由获得贴图能力：目录声明支持 image 的模型（官方

deepseek-v4-flash-vision-exp）图片直通原生视觉端点；其余模型先由可配置的视觉模型

（默认 Qwen-VL）逐字描述成文字，再交给 DeepSeek 继续写代码。官方仓库零改动、跨机器

安装不锁官方版本。同类方案里它是最薄的桥：不注入 agent 工具、不经过第三方中转、

不依赖本地模型。

[English](README.en.md) | [中文](README.md)

目录

• [亮点](#亮点)
• [为什么选它](#为什么选它)
• [快速开始](#快速开始)
• [效果](#效果)
• [工作原理](#工作原理)
• [配置](#配置)
• [使用](#使用)
• [安装](#安装)
• [版本对齐](#版本对齐)
• [开发](#开发)
• [边界与注意](#边界与注意)
• [FAQ](#faq)
• [许可](#许可)

亮点

• 贴图即用，不用换模型： 注册独立路由 deepseek-vision（显示名 DeepSeek + Vision），

真实声明 inputModalities: ['text','image']——聊天窗贴图、tool-fs read_image、浏览器

截图、MCP 工具返回的图片、ACP 客户端内联图片全部放行。

• 每张图只描述一次： 按 attachmentId 进程内 LRU 缓存，重试、上下文压缩、后续轮次

复用同一份描述，不重复计费。

• 会话不变量保持： 原始图片仍持久化进 session log，历史 / 回放 / 重构不受影响。
• 官方机制安装： bundle 声明 + dsh plugin add，四种 spec（npm / git / 目录 / tarball）、

web 与 headless 双 profile，与官方插件完全同一路径。

• 换 VL 模型零改码： 端点 / 模型 / 提示词 / 密钥全在设置卡片，兼容任意

OpenAI 风格 /chat/completions 网关（DashScope、vLLM、OpenRouter、LM Studio…）。

• 失败语义明确： 默认 fail-closed，稳定错误码（AUTH / TIMEOUT / TRANSPORT /

IMAGE_TOO_LARGE…），或 placeholder 降级为文字占位继续。

• 跨版本不锁死： 发布版不锁定官方 dsh 版本。无 CLI 复刻路径（`pnpm

install-profile`）在目标机用自己的 dsh 重建，构建成功即兼容证明，装前分级

提示、绝不静默失败；官方 CLI 路径（dsh plugin add）直接安装发布产物，不在

目标机重建——运行时依赖经 healed fallback 解析，但兼容性未经目标机验证

（见[版本对齐](#版本对齐)）。

为什么选它

dsh 视觉插件生态在官方 harness 发布后的几十小时内密集涌现，机制与取舍各不相同。本插件的

立场是一句话：最薄的桥——只加一条 provider 路由，其余什么都别加。

• 不注入 agent 工具：不新增 vision_describe / analyze_image 之类的工具，agent

的行为面不变，贴图走的就是"贴图"这条原路；

• 不经过第三方中转：没有匿名回退端点、没有代理服务器、没有磁盘答案缓存——图片

只经过你自己配置的 VL 端点（你的 key、你的端点、你的数据）；

• 不依赖本地模型：无 Python / MLX / llama.cpp / Ollama 要求，装上即用；
• 与官方插件同一发布质量：官方 bundle 机制安装、装前兼容门禁、构建锚点章、

111 个测试 / 97% 覆盖率、双语文档。

维度 · 本插件 · 工具型（如 dsh-vision-any、dsh-vision） · 路由型（如 dsh-vision-router） · 代理型（如 dsh-vision-proxy） · 本地管线型（如 DeepSeek-Harness-Vision-Tools）

机制 · provider 网关路由 · 注入 agent 工具 · 工具 + 多供应商路由 · 透明代理路由 · Python 本地 VLM 管线

图片数据流 · 只经你自己的 VL 端点 · 你自己的 API · 含第三方匿名回退 · 自有端点 + 回退链 · 本地模型，不出网

换 VL 模型 · 设置卡片，零改码 · 配置文件 · 配置文件 · 配置 + 自动探测 Ollama · 换本地模型

答案/描述缓存 · 进程内 LRU（仅描述） · — · 内容哈希答案缓存 · SHA-256 缓存 · —

失败语义 · fail-closed + 稳定错误码 · — · — · 超时保护 · —

发布链路 · 官方 bundle 机制 + 兼容门禁 + 锚点章 · — · — · — · 非 bundle

上表只列方向性差异，各项目仍在快速迭代；选型时请以各项目最新 README 为准。

快速开始

前置：dsh CLI 已可用并启动过一次、PATH 里有 pnpm（dsh plugin 命令经 pnpm 安装插件）。

第一步：新机器装 dsh（一次性，二选一）。 dsh 是官方 CLI（npm 包

@deepseek-ai/dsh）：

npm install -g @deepseek-ai/dsh        # 推荐：dsh 永久进入 PATH，之后命令直接敲
# 或（官方一行启动方式）：
npx @deepseek-ai/dsh web               # 不装全局：CLI 只在 npx 缓存里运行，不会进 PATH

⚠️ 用 npx 方式时 dsh 不会进入 PATH——新开终端直接敲 dsh 会报

"command not found"。要么全局安装，要么所有命令都带 npx @deepseek-ai/dsh 前缀。

第二步：安装（git 形式，锁 commit，推荐）：

dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>
# 没装全局、走 npx 时：
npx @deepseek-ai/dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>

已发布的 npm 版（0.1.7）同样可用：把 spec 换成 dsh-deepseek-vision 即可。

部署使用： 重启一次 dsh web → Models 页选 DeepSeek + Vision → 设置 → 插件 →

插件配置里填 VL 密钥 → 聊天窗贴图，发消息。

卸载：

dsh plugin --profile web remove dsh-deepseek-vision

headless profile、其他 spec 形式（git / 目录 / tarball）、无 CLI 的机器——见[安装](#安装)。

效果

聊天窗里选中 DeepSeek + Vision provider 之后：

 · 

• 粘贴 / 拖入图片 → 按所选模型分流：目录声明支持 image 的模型（官方默认目录里的

deepseek-v4-flash-vision-exp）图片直通原生，直接走 DeepSeek 官方视觉端点；

纯文本 / 未列目录的模型则由配置好的视觉模型先描述成文字（逐字提取代码、报错、

日志、UI 文案，并描述布局）；

• 描述文字替代图片发给 DeepSeek → 你继续用 DeepSeek 写代码，同时获得图片理解能力；
• 每张图片只描述一次，重试 / 压缩 / 后续轮次都复用同一份描述，不重复计费；
• session 日志仍然持久化原始图片，历史 / 回放 / 重构不变量不受影响。

工作原理

flowchart LR
    User["聊天窗贴图 / read_image / 截图 / MCP / ACP"] --> Gate["deepseek-vision 路由：inputModalities = text + image"]
    Gate --> Persist["apiproxy prompt RPC → ImageBlock 持久化进 session log"]
    Persist --> Decide{"DeepSeek 目录声明该模型支持 image？"}
    Decide -- "是（官方视觉模型）" --> Native["yield* super.stream()：父类原生序列化图片，直通 DeepSeek 视觉端点"]
    Decide -- "否（纯文本 / 未列目录）" --> Bridge["ImageBridge：改写图片块（含 tool-result 嵌套）"]
    VL["可配置 VL 模型（默认 qwen3-vl-flash，OpenAI 兼容端点）"] --> Bridge
    Cache["attachmentId → 描述 LRU 缓存"] --> Bridge
    Bridge --> Stream["yield* super.stream()：原生 DeepSeek wire 继续流式"]

为什么是"网关适配器"而不是中间件：DSH 有两道硬门槛——prompt / selectModel RPC 按

inputModalities 拒绝不含 image 的模型（纯 llm/stream 中间件拦不到），llm-deepseek

序列化器对 text-only 模型的 image block 抛 UNSUPPORTED_CONTENT。本插件注册新的

provider 路由，继承官方导出的 DeepSeekAdapter：stream() 先按父类目录判断所选

模型——目录声明 image 能力的（官方 rc.2 默认发布 deepseek-v4-flash-vision-exp）原样

直通，由父类原生序列化图片；纯文本与未列目录的模型才把图片

…(truncated)