3分钟装好dsh-vision-router：一条命令、零Python、免Key的完整安装指南

本文是一份面向新手的 dsh-vision-router 安装教程：只需一条命令，无需 Python 环境，也不需要申请任何 API Key，即可为 DeepSeek Harness 的纯文本 Agent 装上"眼睛"，实现图片问答、目标定位、裁剪、OCR 等像素级视觉能力。

一、dsh-vision-router 是什么？30秒了解核心价值

dsh-vision-router 是 DeepSeek Harness（DSH）生态中的一个开源视觉路由插件：

• 免 Key 免费视觉链：内置 OVHcloud 匿名视觉模型兜底，装完就能用，不用注册任何账号；
• 零 Python 依赖：整条图像管线基于 sharp / potrace / tesseract / 系统 Chrome，纯 Node.js 运行；
• 一条命令安装：插件自带组合补丁，dsh plugin add自动完成挂载，不用手改任何配置文件；
• DeepSeek 始终是大脑：视觉模型只当"眼睛"，按需调用，日常文字对话的模型、成本、上下文完全不受影响。

安装后，Agent 可以连续多步"看"一张图：定位按钮 → 裁剪放大 → 识别文字 → 像素对比，就像调用普通工具一样自然。

上图展示的就是安装后真实的能力之一：Agent 根据参考图复刻 UI，再用vision_pixel_diff实测最终差异仅 2.54%——"目测还原"变成了"实测还原"。

二、安装前准备：环境要求 30 秒自查

在敲下第一条命令前，请确认以下条件（不满足任一项请先补齐）：

💡 只需终端里能执行node -v看到 22 或更高版本即可开始。

三、一条命令安装：dsh plugin add 完整步骤

第 1 步：把插件装进正在使用 Web 界面的 profile

普通 npm / npx 用户，在终端执行这一条命令即可完成 dsh-vision-router 安装：

npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router

⚠️--profile选哪个？这决定插件装到哪里：

两个新手最容易踩的坑：

• 请装进"已存在且自带 Web 界面"的 profile。全新创建的 profile 只含基础包，dsh web不会绑定端口（没有 Web 页面可看）。
• Oh-DSH Desktop 用户必须先把DSH_HOME指到它的数据目录，否则会装错环境：

DSH_HOME=~/.ohdsh npx @deepseek-ai/dsh plugin --profile desktop add dsh-vision-router

（Windows PowerShell 先执行$env:DSH_HOME = "$env:USERPROFILE\.ohdsh"再运行同一命令。）

第 2 步：重新加载或重启 DSH

• 网页版：如果 DSH Web 进程已长期运行，让它重新加载一次（刷新即可发现新插件）；
• 桌面版：在应用内重新加载插件，或直接重启应用。

插件加载完成后，后续新增/删除模型、调整识图范围都会热更新，不再需要重启。

源码仓库用户（pnpm 工作区）

如果你是从 DeepSeek Harness 源码检出运行的，dsh通常不在系统 PATH 中，改用工作区脚本：

cd deepseek-harness pnpm dsh plugin --profile web add dsh-vision-router

四、验证安装是否成功：2 条命令快速确认

检查插件是否已挂载

npx @deepseek-ai/dsh --profile web --dump-config | grep vision-router

输出中出现dsh-vision-router相关条目，说明插件已正确进入 profile 配置。

运行健康诊断

dsh-vision-router 自带独立的 doctor 诊断工具，即使 DSH 没启动也能检查 profile：

npx dsh-vision-router doctor --profile web

它会区分"配置文件能解析"和"插件真正健康"两层状态，并报告缺失、重复注册、BOM 污染等问题。完整说明见 docs/doctor.md。

五、安装后首次使用：开启识图并发送第一张图

安装不需要任何 Key 配置，首次使用只需两步：

第 1 步：在聊天输入框旁点击「👁 识图」，按钮变为👁 识图 ✓。

📌 注意：粘贴或上传图片不会自动开启识图，发图前请确认按钮处于 ✓ 状态。右下角的原生模型选择器只选"脑子"（日常会话模型），识图开关是独立的一键。

第 2 步：直接往对话里粘贴或上传图片，像发消息一样提问即可。Agent 会自动调用vision_describe等工具看图并作答。

下面是一次真实的图片问答过程——左侧是用户发图提问、Agent 发起工具调用：

右侧是 Agent 返回的结构化解读，包含主题、画面主体、元素细节与画风分析：

六、进阶一步：免费视觉链与本地后端配置

默认内置免费链已够用；如果用量大或希望完全离线，可在设置 → Vision Router页面调整：

• 挂更高额度的免费 Key：内置 OVH 匿名链限速为每 IP、每模型 2 次/分钟；接入阿里云百炼、智谱等免费视觉渠道后额度大增（均免费注册）。可用仓库自带的预设模板，只需填一个 Key：presets/dashscope.yaml、presets/zhipu.yaml、presets/openrouter.yaml。渠道对比调研见 docs/free-models.zh-CN.md；
• 纯本地离线识别：开启 Ollama 或 LM Studio 本地后端后免 Key 离线看图，配合「仅本地视觉」开关可彻底阻断图片出网；
• 严格隐私场景：开启常规 → 仅本地视觉后，只有回环地址（localhost）上的视觉端点可执行。

📌 隐私提醒：默认免费兜底是匿名上云服务，"免费免 Key"不等于离线。涉密、受限材料请勿使用云端链路。

七、常见问题排查：doctor 与 repair 两条修复命令

repair只处理两类已知的 profile 级故障（BOM 与过期版本豁免），修复前保守、可预测；doctor默认只读。完整排障清单见 docs/doctor.md 与 README.zh.md 的"故障排查"章节。

总结：3 分钟回顾整个安装流程

1. 环境自查：Node ≥ 22、DSH ≥ 0.1.5-rc.1，无需 API Key、无需 Python；
2. 一条命令安装：npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router；
3. 重载 DSH，用--dump-config | grep vision-router和doctor双验证；
4. 点击「👁 识图 ✓」，粘贴图片即可开始像素级看图。

从敲下命令到发出第一张图，全程不超过 3 分钟。更多细节（隐身模式、工具清单、配置项全表）请阅读官方中文文档 README.zh.md。