dsh-vision-router doctor命令行排障指南:DSH起不来时也能快速修复
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。
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、重新打开受影响会话即可。
常用参数速查表:--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
读懂运行时探测:路由 405 校验与"需要登录"的说明
DSH Web 可达时,doctor 会对每条 Vision Router 路由发送一个故意不被支持的 DELETE 请求:正常注册的路由会精确返回 405 Method Not Allowed 及其 Allow 契约,且不会真正执行更新检查、模型发现、设置变更等任何动作。这样能抓出"插件半加载、路由悄悄丢失、被 SPA 兜底吞掉"这类回归。
两个容易误读的提示:
- 探测不到 DSH → 只是参考信息,离线检查照常完成;
- 全部路由返回 401 → 报告"可达但需要浏览器登录态",路由健康记为"未知",而不会伪造绿色结果(JSON 报告里为
runtime.authenticationRequired: true)。
相关源码与资料
- 官方文档:docs/doctor.md
- CLI 入口与参数解析:src/lib/doctor-cli.js
- profile 检查核心:src/lib/doctor.js
- 运行时路由探测:src/lib/doctor-runtime.js
- 会话离线修复:src/lib/legacy-session-repair.js
- 中文 README 故障排查章节:README.zh.md
- 回归测试:tests/doctor-cli.test.js、tests/doctor-v2.test.js
排障口诀:先 doctor 看只读报告 → 按提示跑 repair → 会话打不开再 repair-sessions(先停 DSH)→ 仍有问题就贴 --json 报告提问。

