点了更新却没生效?dsh-vision-router 一键更新背后的原理与 pnpm 发布龄拦截陷阱
点了更新却没生效?dsh-vision-router 一键更新背后的原理与 pnpm 发布龄拦截陷阱
dsh-vision-router 是为 DeepSeek Harness(DSH)纯文本 Agent 装上"眼睛"的开源插件:内置免 key 的免费视觉链路,外加问答、定位、裁剪、像素对比、OCR、截图等像素级识图工具。它自带版本检查 + 一键更新能力,但不少用户遇到过"点了更新、提示成功、重启后版本却没变"的怪事。这篇文章拆解一键更新的完整工作原理,并讲清 pnpm 11 的"发布龄拦截"是如何制造假成功的,以及一条命令的修复方法。
先认识一下:这个插件在做什么
装上插件后,图片轮次会像普通工具调用一样工作:Agent 调用视觉模型对图片做问答、grounding 定位、裁剪、像素 diff 对比等,结果直接回灌到对话里,无需额外配置 key。
它的像素级工具也自带实测验证——用 vision_pixel_diff 对比复刻前后的截图,差异一目了然:
一键更新是怎么工作的
一键更新入口在 DSH 设置卡的"插件"页。它分四步走,每一步都偏向"宁可不做,也不乱做":
第一步:安静的只读版本检查
插件随 DSH 启动时会异步查一次 registry 上 dsh-vision-router 的 latest 版本;打开设置卡时复用本进程的结果,不重复发请求。规则很克制:
- 优先沿用 DSH 进程继承的
npm_config_registry(你的镜像); - 镜像超时或返回不可用元数据时,自动改试 npm 官方 registry,每次尝试有独立超时上限;
- 版本比较遵循 SemVer:本地源码或预发布版本比 registry 新时,绝不提示降级。
核心逻辑见 update-check.js 的 checkPackageUpdate:它只检查、不安装、不改动任何东西,网络失败也永远不会阻塞插件启动。
第二步:先验证你的 DSH 是怎么装上的
用户可能用 npx、全局 CLI、pnpm 源码仓库或别的包装器启动 DSH。插件不猜测 npm / pnpm / npx / bun 命令,而是检查当前进程真正使用的 DSH CLI 入口:
- 能向上验证到真实的
@deepseek-ai/dsh包、且当前 Node 运行时可安全执行 → 才显示"一键更新"按钮; - 否则(比如源码仓库里用
pnpm dsh启动的 TypeScript 入口)→ 不显示按钮,只给出手动命令。
判断逻辑在 self-update.js 的 detectDshSelfUpdatePlan,采用 fail-closed 策略:profile 归属无法确认时,宁可不出按钮。
第三步:显式安装"已确认的目标版本"
发现新版本后,插件执行的是:
dsh plugin --profile <当前 profile> add dsh-vision-router@<最新版>
注意是 add 包名@版本号,不是裸的 update。为什么?下一节揭晓。
同时,子进程通过 execFile 且 shell: false 启动,浏览器输入不会被拼成 shell 命令;更新接口还要求本进程临时 token,远程暴露的设置页拿不到 token,无法触发更新。
第四步:退出码 0 不算数,实测版本才算
命令跑完后,插件会读取 profile node_modules 下 dsh-vision-router 的 package.json,核对安装版本确实达到目标:
- 版本没动 → 明确报
update did not take effect,并附上诊断提示; - 版本到位 → 才提示你重启 DSH,让新插件 bundle 真正加载。
校验函数见 self-update.js 的 updateTookEffect。
pnpm 发布龄拦截:假成功是怎么来的 ⚠️
pnpm 11 默认启用 minimumReleaseAge 策略(默认 1440 分钟,即 24 小时):当候选新版本发布不足 24 小时,裸 pnpm update 会静默保留当前版本,却仍以退出码 0 结束、输出 "Already up to date"。
这就是"点了更新、提示成功、重启后版本没变"的真相——一个假成功。
dsh-vision-router 的三层对策:
- 用
add <包名>@<版本>显式安装 registry 已确认的版本,pnpm 需要时会自动为该版本写入策略豁免,直接绕过 24h 窗口; - 对 git / file / link / workspace 等非 registry 安装,保持
update语义,只校验结果; - 更新后强制实测安装版本——仅凭退出码 0 永远不报成功。
版本还是没变?两步手动兜底 💡
如果执行后版本仍未变化,大概率是 profile 残留了版本钉住的过期豁免。比如 pnpm-workspace.yaml 里写着 dsh-vision-router@1.2.0——这种钉住写法只对 1.2.0 生效,下个新版本就再次被 24h 窗口拦住。一条命令即可修复,doctor.md 有完整说明:
npx dsh-vision-router repair --profile web
它只把过期的钉住条目改写为裸包名,文件其余内容原样保留。
如果一键更新按钮压根没出现(源码仓库启动等场景),设置卡会给出带版本号的手动命令:
pnpm dsh plugin --profile web add dsh-vision-router@<最新版>
普通 npm / npx 用户则运行:
npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router@<最新版>
完整规则见中文文档 update-check.zh-CN.md。
一张表看懂常见现象 ✅
| 现象 | 原因 | 解法 |
|---|---|---|
| 提示成功但版本没变 | pnpm 24h 发布龄拦截,静默退出 0 | 显式 add 包名@版本;或等版本发布满 24h |
| 之后又出现同样问题 | minimumReleaseAgeExclude 钉住了旧版本 |
npx dsh-vision-router repair --profile web |
| 没有一键更新按钮 | 源码仓库 / 无法验证当前 CLI | 按设置卡给的手动命令更新 |
一句话记住:dsh-vision-router 的一键更新不信任退出码、不猜测包管理器,只相信"装完之后的实测版本"——这正是它能绕开 pnpm 发布龄陷阱的关键。

