dsh-deepseek-vision

一句话定位

给纯文本 DeepSeek 模型装上"贴图"能力：注册一条新的模型路由 deepseek-vision，对聊天窗口声明支持图片输入，但在内部把图片先送给你配置的视觉模型（默认 qwen3-vl-flash）逐字描述成文字，再交给原汁原味的 DeepSeek 流式接口。

核心能力

• 注册新的 provider 路由 DeepSeek + Vision，在 Models 页面选择后，聊天窗口贴图、工具结果里的内嵌图片、MCP/ACP 客户端传入的图片都能通过官方准入门槛
• 把图片块改写为 VL 模型生成的描述文字后再发往 DeepSeek，原图仍原样写入 session 日志，历史与回放不受影响
• 按 attachmentId 在进程内做 LRU 描述缓存，同一张图片在重试、会话压缩、后续轮次里只识图一次
• 任何兼容 OpenAI /chat/completions 接口的 VL 网关都可接入（DashScope、vLLM 自部署、OpenRouter、LM Studio 等），设置卡片里改端点即可，不改代码
• 失败语义明确：默认 fail-closed 并返回稳定错误码（AUTH / TIMEOUT / TRANSPORT / RATE_LIMIT / IMAGE_TOO_LARGE 等），可选 placeholder 策略降级为文字占位继续
• 部署图片上限预检：图片字节或像素超过宿主限制时，在 base64 编码前就以 IMAGE_TOO_LARGE 失败，不把大图送进 VL 端点再死

技术实现

• 语言: TypeScript（宿主面 + React 客户端面）
• 关键依赖: @deepseek-ai/dsh-llm-deepseek（继承 DeepSeekAdapter 流式/重试/wire 序列化）、@deepseek-ai/dsh-llm（错误码与稳定状态）、@deepseek-ai/dsh-credentials（密钥解析）
• 架构模式: 服务端通过 cordis.patch.yml 在 bundle 层注册 llm-vl-gateway 设置段与一条 provider 路由，继承官方 DeepSeekAdapter 覆写 stream()，先经 ImageBridge 把图片块改写成文本描述再 super.stream()；客户端通过 settings.plugin.item 槽位挂一张设置卡片。注册/目录重注册是原子的，路由 id 与显示名在设置卡片里即时生效
• 入口文件: 服务端 src/index.ts（导出 apply、Config、VisionGatewayAdapter、ImageBridge），客户端 src/client/index.ts（导出 apply 并向 settings.plugin.item 注入卡片）

适用场景

日常使用 DeepSeek 编程、写代码的开发者，经常需要把报错截图、UI 截图、ASCII 之外的草图、终端输出图粘贴到对话里让模型理解。官方 DeepSeek 接口对纯文本模型会拒收图片，本插件在你不动官方配置、不换模型的前提下补齐这条能力。当你想在不同 VL 供应商之间切换、或不想引入额外的本地模型与第三方中转时，这条"最薄的桥"是最直接的方案。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:siegfly/dsh-deepseek-vision

配置项

常见问题

Q: 安装之后需要做什么才能在聊天里贴图？

A: 打开 dsh 设置 → 插件 → 插件配置 里的 "DeepSeek + Vision（视觉语言桥接）" 卡片，填好 VL 模型密钥（或在终端导出 QWEN_VL_API_KEY），然后在 Models 页面把 provider 切换到 DeepSeek + Vision，聊天窗口贴图即可。DeepSeek key 沿用现有凭据，不需要再配。

Q: 卸载本插件后，含图的历史会话会坏掉吗？

A: 数据不会丢，但这类会话会切不回纯文本模型——官方的 selectModel 按 inputModalities 拒绝文本模型接入含图会话，属于预期行为而非数据损坏。新会话不受影响，重新安装本插件即可恢复。

Q: VL 模型描述失败，整次请求就废了吗？

A: 默认是 fail-closed：描述失败会让整次请求以稳定错误码（如 AUTH、TIMEOUT、TRANSPORT、RATE_LIMIT、IMAGE_TOO_LARGE）终止，不会静默丢图。如果你希望即使识别失败也继续对话，可以在卡片里把失败策略改成 placeholder，图片会被替换成一段文字占位说明。

Q: 同一张图反复出现，会被多次扣费吗？

A: 不会。插件按图片的 attachmentId 在进程内做 LRU 缓存，重试、会话压缩、后续轮次都复用同一份描述文字。卸载或重启后缓存清空，下一次需要时会重新识图。

Q: 必须用 qwen3-vl-flash 吗？

A: 不必。设置卡片里的 vl.baseURL 和 vl.model 就是为换 VL 准备的。任何提供 OpenAI 兼容 /chat/completions 接口的网关都能用，例如 vLLM 自部署、OpenRouter、LM Studio。复杂视觉推理可以换 qwen-vl-max。

Q: headless 模式能用吗？

A: 能。网关路由在 web 和 headless 两个 profile 的行为完全一致；可视化设置卡片只在 web profile 里出现，headless 直接编辑 settings.yaml 配置 llm-vl-gateway.vl 段即可。

Q: 会自动锁死官方 DSH 版本吗？

A: 不会。dshCompat.anchorVersion 只是声明 lib/ 的构建出处，不是安装门禁。官方 CLI 安装路径直接装发布产物；无 CLI 复刻路径会在目标机用目标机自己的 dsh 重新构建，构建成功本身就是兼容性证明。

Q: 怎么卸载？

A: 执行 dsh plugin --profile web remove dsh-deepseek-vision（headless 把 web 换成 headless）。该操作仅卸载插件本身，已写进 session 日志的原始图片不受影响。

上手难度

入门 — 安装后填一个 VL 模型密钥、在 Models 页选 DeepSeek + Vision 即可使用，无需编程或额外配置；想换 VL 模型或调缓存大小时再进设置卡片。

已知问题与限制

• 没有图片降采样能力：当图片超过宿主 attachments.imageLimits 时会以 IMAGE_TOO_LARGE 拒绝，部署上限内的图片仍可能超过 VL 供应商自家大小上限，需要控制 vl.timeoutMs 并查阅供应商文档
• 描述文字会占用 DeepSeek 的 context 窗口，每张图片几百 token，仅首次计费
• 默认 fail-closed：VL 密钥失效、超时、429 等错误会让整次请求终止，不静默丢图（可改 placeholder 策略降级）
• 若手动把会话压缩策略 pin 到 deepseek-official 且历史含图，压缩阶段会因官方 UNSUPPORTED_CONTENT 失败；继续使用本路由的 provider（deepseek-vision）不会出现这个问题
• 卸载插件后，含图历史会话切不回文本模型（官方按 inputModalities 准入拒绝，预期行为）；新会话不受影响
• 官方 CLI 安装路径不在目标机重建也不跑兼容门禁，目标机器的 dsh 与构建锚点 API 不一致时问题会在启动或调用时显现；无 CLI 复刻路径（pnpm install-profile）会先重建并分级门禁

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

dsh-deepseek-vision 是给 DeepSeek Harness 的视觉语言网关插件。 纯文本的 DeepSeek 编程模型 通过一个"网关"provider 路由获得贴图能力：图片先由可配置的视觉模型（默认 Qwen-VL） 逐字描述成文字，再交给 DeepSeek 继续写代码。官方仓库零改动、跨机器安装不锁官方版本。 同类方案里它是最薄的桥：不注入 agent 工具、不经过第三方中转、不依赖本地模型。

English | 中文

目录

• 亮点
• 为什么选它
• 快速开始
• 效果
• 工作原理
• 配置
• 使用
• 安装
• 版本对齐
• 开发
• 边界与注意
• 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 机制安装、装前兼容门禁、构建锚点章、 102 个测试 / 97% 覆盖率、双语文档。

上表只列方向性差异，各项目仍在快速迭代；选型时请以各项目最新 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.5）同样可用：把 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 之后：

• 粘贴 / 拖入图片 → 被配置好的视觉模型先描述成文字（逐字提取代码、报错、日志、 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 --> 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 序列化器对 image block 抛 UNSUPPORTED_CONTENT。本插件注册新的 provider 路由，继承官方 导出的 DeepSeekAdapter，stream() 里把图片块经 VL 模型改写为文本后再走原汁原味的 DeepSeek wire；reasoning efforts / context 窗口 / 默认 maxTokens / retry policy 全部从 父类继承。

配置

全部可省略（走默认值）。两个 key 都支持 credential-ref（环境变量名）。已挂载 dsh 的 credentials 服务时，其解析结果（即使未配置）具有权威性；只有服务缺席才直接读取启动环境。 官方 credentials-local 的优先级是：进程环境变量（最高、只读）→ GUI 管理的 .credentials.yaml → .env 回退。因此 Web Models 页写入的凭据可用，而本次进程显式 导出的 key 始终优先且不能在 GUI 内修改：

llm-vl-gateway 也是一个 settings namespace，三个编辑入口：设置 → 插件 → 插件配置 的"DeepSeek + Vision（视觉语言桥接）"卡片（vl.* 全字段 + VL 密钥）、Web Models 页 （deepseek.* 子段由可配置 provider 目录接管）、settings.yaml（两个子段都可写）。

provider / displayName 是注册期事实，修改即时生效（adapter 路由 + 可配置 provider 目录原子重注册，不需重启）；改成已被占用的路由 id 时两个注册表保留旧值并记日志。

patch 行内配置示例（全部可选）：

- insert:
    - id: llm-vl-gateway
      name: dsh-deepseek-vision
      config:
        deepseek:
          reasoningEffort: high
        vl:
          apiKeyEnv: DASHSCOPE_API_KEY
          model: qwen3-vl-flash

使用

1. 设置两个 key：设置 → 插件 → 插件配置 → "DeepSeek + Vision（视觉语言桥接）" 卡片里填 VL 密钥（写入凭据存储，不出现在任何响应/设置里）；DeepSeek key 沿用现有凭据；
2. Models 页选择 provider DeepSeek + Vision（会话内切换即持久化为默认）；
3. 聊天窗贴图，发消息——图片自动被描述，DeepSeek 看到的是文字。

设置卡片是本插件的客户端面（dsh.client）：以官方解耦插件的方式注册进 settings.plugin.item 槽位，编辑 llm-vl-gateway.vl 段，与官方内置卡片（终端 / Agent 循环 / 网页搜索）同机制、同交互（暂存草稿、覆盖状态显示、保存时整体写入）。

安装

安装走官方 bundle 机制：本包在 package.json 声明 dsh.bundle.patch（指向包内 cordis.patch.yml），dsh plugin add 把包链接进 profile 并把包名对账进 profile manifest 的 dsh.profile.bundles 层栈，loader 启动时按层挂载——不需要手工往 cordis.patch.yml 加任何行（旧版本加过的受管块会在下次安装/卸载时自动迁移移除）。

四种 spec 任选（日常推荐 git 形式，锁 commit）：

dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>       # git（推荐），锁 commit
dsh plugin --profile web add dsh-deepseek-vision                          # npm（已发布 0.1.5）
dsh plugin --profile web add file:<本仓库路径>                        # 本地目录（开发）
dsh plugin --profile web add ./dsh-deepseek-vision-<version>.tgz              # tarball

headless 同理：dsh plugin --profile headless add dsh-deepseek-vision（客户端卡片只在 web 生效）。验证 bundle 层已挂载：dsh --profile web --dump-config | grep llm-vl-gateway。 卸载与安装一一对应：dsh plugin --profile <name> remove dsh-deepseek-vision。

无 CLI 的机器用等价复刻（需 Node 22.19+ 或 24+、PATH 里有 pnpm；init 布局 → 目标机 重建 → 兼容门禁 → pnpm add → bundles 对账）：

pnpm install        # 只装 devDeps（typescript/vitest），不会装 @deepseek-ai/*
pnpm install-profile          # 或 node scripts/install-profile.mjs [profile] [dshHome]

这是唯一在目标机重建的安装路径：install-profile 先用目标机自己的 dsh 类型重新构建 插件并通过 check-compat.mjs 门禁，再装入 profile（见版本对齐）。 两条路径都做下面两件事：

• 把 dsh-deepseek-vision 链接进 profile 的 node_modules（运行时 @deepseek-ai/* 依赖经 官方 healed fallback 解析到同一个 dsh 安装，共享同一个 cordis 实例，无双实例问题）；
• 把 dsh-deepseek-vision 对账进 dsh.profile.bundles——loader 按层挂载包内 cordis.patch.yml 的 insert 行（注册路由 + 设置段）；
• 首次安装时如 profile 布局缺失，按官方 initProfile 语义补齐（manifest + 空用户 patch 层 + pnpm-workspace.yaml），已存在的文件从不改动。

装完重启一次 dsh web（bundles 层栈变化 + 客户端模块扫描按包名缓存）。

本仓库是独立 git 仓库，与 deepseek-harness 官方仓库没有任何 git 关系 （无 fork / 子模块 / 远程关联）；官方 checkout 零改动。

版本对齐

两条安装路径的兼容性策略不同：

• 官方 CLI 路径（dsh plugin add，npm / git / tarball）：直接安装发布产物—— npm 包在作者发布时构建，git 形式使用提交的 lib/，tarball 是作者打包的产物， 都不在目标机重建，也没有兼容门禁。运行时 @deepseek-ai/* 依赖从目标机自己的 dsh 安装解析（healed fallback）；若目标机官方 dsh 的 API 与本插件编译产物不匹配， 安装不会提前失败，问题会在启动或调用时显现。装前请自行确认目标 dsh 与 dshCompat.anchorVersion 声明的代际大致一致。
• 无 CLI 复刻路径（pnpm install-profile）：安装前先在目标机用目标机自己的 dsh 类型重新构建插件，再跑 check-compat.mjs 分级门禁。只有这条路径提供 “构建成功即兼容证明”：

无 CLI 复刻路径下，发布版不锁定任何官方版本——目标机器用比锚点更新（或更旧）的 官方 dsh 都可以安装；构建成功本身就是兼容性证明。若新官方版改了本插件用到的 API， 构建会自然失败并给出明确的 tsc 错误，那时才需要发新版适配。作者无需跟随官方每次 升级重新发布。

• dshCompat.anchorVersion 只声明提交的 lib/ 的构建出处（出处声明，不是安装 许可）；pnpm build 写入的 lib/build-anchor.json 让出处无法撒谎。
• node scripts/check-compat.mjs [dshHome] 安装前对目标机分级：完全一致 = exit 0； 任何不一致 = exit 1 提示并放行；残缺发布 / 复刻漂移 = 拒绝（有环境变量强制开关）。 该检查只在 install-profile 里运行，官方 CLI 路径不会调用它。

完整策略、退出码分级与发版触发条件：docs/VERSIONING.md。

开发

pnpm test      # vitest
pnpm build     # tsc（宿主面 + 客户端面）+ tsdown 浏览器 bundle

• scripts/harness-paths.mjs 是仓库唯一的解析缝：$DSH_CHECKOUT → 仓库根 harness-paths.json（gitignored）→ 本机已安装 dsh 的 healed fallback。
• 纯 npm 机器上 2 个客户端测试套件自行跳过（npm 只发布浏览器闭包里的客户端运行时）； 有官方源码 checkout 的机器跑全量。
• 产物里的 @deepseek-ai/* 导入保持裸说明符，运行时走 profile fallback。

细节：docs/DEVELOPMENT.md。贡献指南：CONTRIBUTING.md； 安全漏洞报告：SECURITY.md。

边界与注意

• compaction：默认继承会话 provider（即网关路由），图片被改写且命中缓存；若把压缩 策略显式 pin 到 deepseek-official 且历史含图，会按原逻辑 UNSUPPORTED_CONTENT 失败。
• 卸载后的含图会话：卸载插件后，含图历史会话无法切回文本模型（官方 selectModel 按 inputModalities 准入拒绝，属预期行为，不是数据损坏）；新会话不受影响，重装即恢复。
• VL 失败语义：默认 fail-closed——描述失败（如 key 失效）整个请求以稳定错误码 （AUTH / TIMEOUT / TRANSPORT…）终止，不静默丢图；onFailure: placeholder 可降级。
• 图片上限 fast-fail：描述前按部署图片准入上限（ctx.attachments.imageLimits）预检， 超限图片在 base64 编码前就以 IMAGE_TOO_LARGE 失败（placeholder 策略下降级），不把 几 MB 的 data URL 送进 VL 端点再死。插件不做图片降采样（官方 seam 没有公开的降采样 能力）；部署上限内的图片仍可能超过 VL 供应商自己的大小上限，建议控制 vl.timeoutMs 并留意供应商文档。
• 描述文本会占用 DeepSeek 的 context（每图几百 token，仅首次计费）。

FAQ

新机器上 dsh 命令不存在 / 报 command not found？ 先装官方 CLI： npm install -g @deepseek-ai/dsh（一次性，之后 dsh 永久在 PATH）。如果平时用 npx @deepseek-ai/dsh web 启动（官方一行方式），CLI 只在 npx 缓存里运行、不会进 PATH，装插件时要用 npx 前缀：npx @deepseek-ai/dsh plugin --profile web add dsh-deepseek-vision——插件本身装在 profile 里，与 CLI 从哪来无关，装一次永久有效。

安装需要关心 Node 版本吗？ 官方 CLI 路径（dsh plugin add）不需要；只有无 CLI 的 复刻脚本需要 Node 22.19+ / 24+ 和 PATH 里的 pnpm。

#<sha> 是什么？ git spec 形式的占位符——替换成具体 commit 哈希可锁死精确代码快照； 不加 #<sha> 则安装默认分支最新提交。

支持 CLI（headless）吗？ 支持。网关路由在两个 profile 行为一致；设置卡片是 web 专属，headless 用 settings.yaml 配置。

卸载后，含图历史会话选不了模型？ 属预期行为：官方 selectModel 按 inputModalities 拒绝文本模型接入含图会话。新会话不受影响，重装即恢复。

为什么图片不直接发给 DeepSeek？ 官方 DeepSeek 接口对纯文本模型会拒绝 image_url，所以先由 VL 模型描述成文字再转发——不换模型、不丢信息。

许可

MIT