dsh-vision-router doctor命令行排障指南:DSH起不来时也能快速修复

原创2026-10-14 09:17:472,189 阅读

dsh-vision-router doctor命令行排障指南:DSH起不来时也能快速修复

dsh-vision-router 是 DeepSeek Harness(DSH)的免费视觉插件,而它内置的 doctor 命令行是官方排障工具:DSH 起不来时,它能独立检查 profile、定位故障,并可用 repair 命令快速修复 UTF-8 BOM、过期版本豁免、会话损坏这三类最常见的"起不来 / 打不开"问题。

一分钟认识 doctor:DSH 坏掉时的"体检医生"

doctor 是一个独立诊断 CLI,不依赖 DSH 先成功启动,因此当 dsh web 直接报错退出时,它照样能工作。三条命令的分工刻意保持保守:

命令 性质 作用
doctor 默认只读 检查安装、profile 组成、运行时路由、日志、本地视觉能力
repair 有限修改 只修两类已知 profile 故障:BOM 前缀、过期的 minimumReleaseAgeExclude 版本钉死项
repair-sessions 有限修改 只修两类已知会话损坏签名,且每次都先做逐字节备份

命令细节与参数说明见官方文档 docs/doctor.md,CLI 入口实现在 src/lib/doctor-cli.js。

dsh-vision-router 视觉设置界面截图,含打开配置文件入口,可用于 BOM 问题排查

5分钟完成第一次体检:运行 doctor 只读诊断

在项目根目录执行:

npx dsh-vision-router doctor

它会扫描 <DSH_HOME>/profiles 下的所有 profile,并默认探测运行中的 DSH Web(http://127.0.0.1:3080)。只想查单个 profile 时加上 --profile web。典型输出如下:

DSH home: ~/.dsh
✓ web — JSON valid — install bundle@3.0.3
✓ Node 22.19.0
✓ Tesseract — 5.3.x
– Chromium/Chrome — not found (HTML screenshot tool unavailable)

符号含义很直观:✓ 通过、✗ 失败、! 警告、– 参考信息。关键判断点:

  • "JSON 能解析" ≠ "健康"。doctor 会进一步检查包缺失、声明了没装、装了没挂载、重复注册等,只有形成一条有效激活路径才算健康;
  • 检测到可修复项时,结尾会直接给出提示:Run 'npx dsh-vision-router repair' to fix the detected profile issues safely.;
  • 探测不到运行中的 DSH 只是"参考信息",不会让整个诊断失败。

本地能力(Tesseract、Chromium、sharp)缺失均为提示性质——对应工具可能未使用,或由 Host 通过其他路径提供。

症状一:DSH 启动即报 "is not valid JSON"?一条命令去掉 BOM

这是最高频的"DSH 起不来"场景。启动时插件加载前就退出,错误类似:

SyntaxError: Unexpected token ... is not valid JSON
at readProfileManifest (.../profile.ts:...)

原因:~/.dsh/profiles/<profile>/package.json 被某些编辑器保存成了 UTF-8 with BOM,文件开头多了不可见的 \uFEFF,JSON.parse 直接拒绝。

修复(不需要 DSH 先启动):

npx dsh-vision-router repair --profile web

repair 只删除开头的 3 字节 BOM(EF BB BF),然后重新验证 JSON——不会重排格式、不会猜测重写其他内容。如果去掉 BOM 后 JSON 仍然非法,命令会如实报错并停下,此时再手动检查文件。兜底手改方式:用 VS Code 以 "UTF-8(无 BOM)"重新保存。更多细节见 README.zh.md 的故障排查章节。

症状二:更新不生效?repair 同时清理过期的发布时效豁免

pnpm v11 默认 minimumReleaseAge 为 1440 分钟。如果 profile 里写死了版本钉死的豁免(如 dsh-vision-router@1.2.0),它只豁免那一个版本,下个版本发布后即失效——表现就是"跑了更新却像没生效"。

doctor 会标记这些 dsh-vision-router 与 @deepseek-ai/* 的钉死项,同一条 repair 命令会把它们只改回裸包名,其余条目不动:

npx dsh-vision-router repair --profile web

症状三:重启 DSH 后旧会话打不开?用 repair-sessions 离线修复

有两类历史缺陷会让已持久化的会话无法冷恢复,即使当前版本已不产生这类事件:

  • 缺少消息 id:早期构建把自动视觉挂载提醒存成了无 id 的 user/message,报 lacks an identified message;
  • 重复 guard-stop id:旧版结构化流把同一条 guard 消息存了两次(如 vision-router-structured-guard-stop-1),重载时报 received more than one start Match。

先只读扫描确认:

npx dsh-vision-router doctor --sessions

确认有损坏后,先停掉 DSH,再运行(实现见 src/lib/legacy-session-repair.js):

npx dsh-vision-router repair-sessions

这个修复是"窄而 fail-closed"的:只匹配精确的历史签名;每次改动都在原文件旁生成逐字节备份;修复后重读校验通过才报告成功;重复执行是幂等的。完成后重启 DSH、重新打开受影响会话即可。

dsh-vision-router 像素级复刻演示,用 vision_pixel_diff 验证最终差异 2.54%

常用参数速查表:--json、--sessions、--runtime-url 怎么搭配

参数 命令 说明
--profile <name> doctor / repair 只检查指定 profile(如 web)
--json doctor 输出可分享、已脱敏的 JSON 诊断报告:不含原始 manifest、日志行、API key、本地路径、会话 id,适合贴进 issue
--sessions doctor 只读扫描会话日志中的已知损坏签名(日志多时稍慢)
--runtime-url <url> doctor 指定要探测的 DSH Web 地址(默认读 DSH_WEB_URL 或 http://127.0.0.1:3080)
--no-runtime doctor 只做离线检查,跳过运行时探测
--fix doctor 兼容旧用法,新流程请优先用显式的 repair

提 issue 时一条组合命令即可附上完整证据:

npx dsh-vision-router doctor --profile web --sessions --json

dsh-vision-router 图片问答对话界面,vision_describe 工具返回结构化图片内容

读懂运行时探测:路由 405 校验与"需要登录"的说明

DSH Web 可达时,doctor 会对每条 Vision Router 路由发送一个故意不被支持的 DELETE 请求:正常注册的路由会精确返回 405 Method Not Allowed 及其 Allow 契约,且不会真正执行更新检查、模型发现、设置变更等任何动作。这样能抓出"插件半加载、路由悄悄丢失、被 SPA 兜底吞掉"这类回归。

两个容易误读的提示:

  • 探测不到 DSH → 只是参考信息,离线检查照常完成;
  • 全部路由返回 401 → 报告"可达但需要浏览器登录态",路由健康记为"未知",而不会伪造绿色结果(JSON 报告里为 runtime.authenticationRequired: true)。

相关源码与资料

排障口诀:先 doctor 看只读报告 → 按提示跑 repair → 会话打不开再 repair-sessions(先停 DSH)→ 仍有问题就贴 --json 报告提问。

登录后查看全文
dsh-vision-router