dsh-Sight

中文 · English

让 DeepSeek Harness（dsh）拥有视觉能力：无论你选用的模型是纯文本还是多模态， 都可以直接粘贴图片，由 harness 自动把图交给视觉工具理解。

解决的问题

dsh 本身不限制图片进入会话，但当你选用的模型是纯文本模型（例如 deepseek-v4-flash）， 粘贴图片会整轮失败，报错：

pi-ai model "deepseek-v4-flash" does not support image input

图片根本进不了会话，agent 也没有机会用任何工具去看它——dsh 就此失去视觉能力。 本项目从根上给 dsh 补上这条"视觉通路"：图片能进会话，agent 能读到图， 理解交给视觉工具完成。结果就是：dsh 在纯文本模型下也能看图了。

原理

dsh 的 pi-ai 模型通道（@deepseek-ai/dsh-llm-pi-ai）在把请求发给模型之前，有一个硬校验： 只要本轮含图片、而模型声明不支持图片，就直接抛错终止整轮。本项目（dsh-Sight）做两件事：

1. 请求时改写（request-time rewrite）+ 描述缓存：当"真实模型无图能力 + 消息含图"时，不再抛错。 补丁读取 ~/.qwen-mm-plugins/config 里的 DashScope 配置，直接调用视觉 API 把图片转成 文字描述（如"一个女孩站在楼梯上…"），用这段文字替换图片占位后继续发给模型；转换结果写入 <DSH_HOME>/tmp/paste/descriptions.json 持久化缓存，同一张图只转换一次，之后任何轮次、 任何会话、重启后都直接复用描述，不再重复调用视觉 API（消除"每轮 10~30 秒"的固定延迟）。 视觉 API 不可用时回退为"把图落盘到 <DSH_HOME>/tmp/paste/ 并给模型指路"。
2. 假装支持图片：resolveModel / listModels 声明模型支持图片输入，让 harness 的 selectModel 检查通过——即使会话里已经出现过图片，也能自由切换回纯文本模型， 不会被"此模型不支持图片"挡住。

效果：粘贴图片不再整轮失败；图片在请求前就转成文字（比另调一轮视觉 MCP 更快），且同一张图只转一次、之后所有轮次秒回； 纯文本模型（如 deepseek-v4-flash）与多模态模型之间可以随意切换。

前提：~/.qwen-mm-plugins/config 里配好 DASHSCOPE_API_KEY（用于把图转成文字）。 没有该配置时会自动回退到"落盘 + 让 agent 调视觉 MCP 工具"的旧方案，不会报错。

兼容性

项	值
dsh 版本	0.1.0-rc.6（其他版本需自行核对，脚本会自动拦截版本不匹配）
平台	Windows（PowerShell）/ macOS / Linux（bash）
前置	Node.js 22.19+、通过 npx 安装运行的 dsh、一个视觉 MCP 工具

⚠️ 这是对 dsh 第三方 npm 编译产物的非官方改动。dsh 升级或重装后补丁会被覆盖， 重跑一次安装脚本即可。本补丁只改一个文件，且有备份，可随时回滚。

安装

有两种方式，任选其一。方式一（推荐）：让 dsh 里的 agent 帮你装，你只需复制一段提示词； 方式二：自己跑脚本（见下文分步说明）。

方式一：让 dsh 的 agent 代装

先把本仓库克隆或解压到本地，然后复制下面这段提示词，粘贴到你的 dsh 对话里发给 agent：

帮我安装 dsh-Sight（仓库在本地路径：<填你的路径>），让 dsh 拥有视觉能力。
按仓库里的 INSTALL-BY-AGENT.md 执行：配置 Qwen-MM-Plugins 的 api/search 两个 MCP 能力、
给 pi-ai 适配器打补丁、在 ~/.dsh/AGENTS.md 追加读图规则。
要求：①key（DASHSCOPE_API_KEY、SERPER_API_KEY）由我自己填到 ~/.qwen-mm-plugins/config，
你不要替我编造、也不要回显；②重启 dsh 前必须先征得我同意；③任何一步失败就停下告诉我报错。
完成后报告：改了哪些文件、备份在哪、怎么回滚。

agent 会按仓库里的完整说明（INSTALL-BY-AGENT.md）执行安装，你只需在它停下时 填 key、并在最后同意重启。

方式二：自己跑脚本

整个流程分三步：装 MCP 能力 → 打补丁 → 填 key 重启。用户需要自己动手的只有 "装 uv（如未装）"和"填两个 key"。

第 0 步：安装 uv（如已装可跳过）

MCP 服务器通过 uvx 启动（来自 Qwen-MM-Plugins 的官方机制）。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

装完重新打开终端，确认 uvx --version 能输出。

第 1 步：配置视觉/搜索 MCP

powershell -ExecutionPolicy Bypass -File setup-mcp.ps1    # Windows
bash setup-mcp.sh                                          # macOS / Linux

脚本自动完成：预构建 qwen-mm-plugins-api 和 qwen-mm-plugins-search 两个能力的运行环境 → 生成 ~/.qwen-mm-plugins/config 骨架 → 在 dsh 的 ~/.dsh/profiles/web/cordis.patch.yml 写入两个 MCP 注册行（已存在则不重复）。

如果你已经装过 Qwen-MM-Plugins（~/.qwen-mm-plugins/config 已存在）：脚本会跳过覆盖 你的现有配置，只做 dsh 侧的注册，不会动你已经填好的 key。

然后编辑 ~/.qwen-mm-plugins/config，把两个占位符换成自己的 key：

• DASHSCOPE_API_KEY：阿里云百炼的 API Key（申请）
• SERPER_API_KEY：Serper 的免费 key（申请，用于网页搜索/反向图搜）

关于 DASHSCOPE_BASE_URL（端点）：脚本默认写入官方地址 https://dashscope.aliyuncs.com/compatible-mode/v1，配合你自己申请的阿里云百炼 key 即可使用。 如果你是通过第三方聚合网关（如带专属标识的 ws-xxx.maas.aliyuncs.com 地址）接入的， 保留你已有的端点地址，不要换成官方的——那种端点的 key 与官方地址不匹配，换过去会报 403。

第 2 步：打 pi-ai 补丁

powershell -ExecutionPolicy Bypass -File install.ps1    # Windows
bash install.sh                                          # macOS / Linux

脚本自动完成：检测 dsh 版本（不是 0.1.0-rc.6 会拒绝并退出）→ 定位 npx 缓存 → 备份原文件到 backup/ → 打补丁 → 追加读图规则到 ~/.dsh/AGENTS.md → 语法检查。

第 3 步：重启并测试

重启 dsh（用你平时启动 dsh 的方式），粘贴一张图片测试即可。

回滚

powershell -ExecutionPolicy Bypass -File uninstall.ps1   # Windows
bash uninstall.sh                                        # macOS / Linux

脚本从 backup/index.js.orig 恢复原文件，并移除 AGENTS.md 里加的那条规则，重启后即还原。 （backup/ 里的备份是你本机安装时生成的，不会提交到仓库。）

常见问题

我机器上的 DASHSCOPE_BASE_URL 和 README 里写的不一样？

README 里是官方默认地址（dashscope.aliyuncs.com），配你自己申请的阿里云百炼 key 用。 如果你的环境里已经有 ~/.qwen-mm-plugins/config，里面的地址可能是第三方聚合网关 （形如 ws-一串随机字符.cn-beijing.maas.aliyuncs.com/compatible-mode/v1），那是你之前 配 Qwen-MM-Plugins 时用的接入点。这种情况保留你现有的地址和配套的 key，不要改成 README 的官方地址——key 和端点不匹配会报 403。

打补丁后粘贴图片还是失败？

先确认三件事：①dsh 版本是 0.1.0-rc.6（install.ps1 会自动校验，版本不符会拒绝）； ②~/.qwen-mm-plugins/config 里的 key 已填且端点匹配；③重启过 dsh。如果都满足仍失败， 把报错原文发到 Issues。

图片读出来了，但 agent 没有自动调用视觉工具？

这是正常现象——补丁把图片转成文字后，agent 本就不需要再调视觉工具。按消息里的占位文字区分：

• 看到"[已自动转为文字描述（无需再读取图片文件或调用视觉工具）：...]"：图片内容已经在会话里，agent 直接引用即可；新版读图规则也明确要求此时不要去找文件或调工具。
• 看到"[已保存到文件路径 ...，请调用可用的视觉工具...]"：这是兜底路径（视觉 API 不可用），图片以文件形式存在，agent 是否去调视觉 MCP 才取决于系统提示里的指引——install.ps1 会在 ~/.dsh/AGENTS.md 追加第 4 条读图规则。若这种情况 agent 仍不调工具，手动确认该文件存在且包含"读图规则"字样。

手动打补丁（不想用脚本时）

1. 找到你的 dsh-llm-pi-ai 包：npx 缓存目录下的 node_modules/@deepseek-ai/dsh-llm-pi-ai/lib/index.js；
2. 备份原文件；
3. 按 patch/pi-ai-textify-images.patch 手动修改，或直接用 git apply / patch 应用；
4. 追加第 4 条读图规则到 ~/.dsh/AGENTS.md（见 agents-rule.md）；
5. 重启 dsh。

文件说明

├── setup-mcp.ps1 / setup-mcp.sh  # 配置视觉/搜索 MCP（预构建能力+写config骨架+插dsh注册行）
├── install.ps1 / install.sh      # 打 pi-ai 补丁（自动备份+打补丁+写规则）
├── uninstall.ps1 / uninstall.sh  # 回滚脚本
├── patch/
│   └── pi-ai-textify-images.patch  # 针对 dsh-llm-pi-ai 的补丁 diff
├── agents-rule.md                  # 需要追加到 ~/.dsh/AGENTS.md 的读图规则
└── backup/                         # 安装时生成的本地备份（不入库）

致谢 / 相关项目

本项目依赖 Qwen-MM-Plugins（Apache-2.0）提供视觉与搜索能力：

• api 能力：Qwen VL/Omni 视觉理解、OCR、grounding、ASR、分割与音视频理解；
• search 能力：网页搜索、页面抽取与反向图像搜索。

dsh-Sight 只负责打通 dsh 侧的"图片进会话 + 自动转文字（必要时兜底教会 agent 调用视觉工具）"通路；实际的图片理解 由 Qwen-MM-Plugins 的能力完成。安装时使用的 uvx 启动机制与 ~/.qwen-mm-plugins/config 配置格式均来自该项目的官方约定。

免责声明

本项目非 dsh 官方项目，与 DeepSeek 无关。使用本补丁即表示你了解：它修改了 dsh 的第三方 npm 包内容，dsh 升级会覆盖补丁；如因使用本补丁造成任何问题，项目维护者不承担责任。 建议在生产或重要会话前先备份。