dsh-vision-toolkit故障排查清单:429、超时、Chrome缺失等8个常见问题快速修复
dsh-vision-toolkit故障排查清单:429、超时、Chrome缺失等8个常见问题快速修复
dsh-vision-toolkit 是专为 DeepSeek Harness 纯文本模型打造的视觉工具箱:粘贴图片直接识别、多张图片问答、长截图 OCR、截图到前端 UI 还原,一行命令即可安装使用。本文整理为一份 dsh-vision-toolkit 故障排查清单,覆盖 429 限流、timed out 超时、Chrome 缺失、API 地址写错等 8 个新手最常遇到的问题,每个问题都给出「现象 → 原因 → 修复步骤」,照着做即可快速恢复视觉能力。
排查前先做这一步:健康检查
打开 设置 → 视觉工具(Settings → Vision Toolkit),面板会分别显示「视觉服务」「运行时」「浏览器」等健康状况。绝大多数故障都能在这里先定位到原因,再对照下面的清单逐项修复。
问题1:视觉服务返回 429(限流)
现象:工具调用或连接测试提示 429 / rate limit / quota,设置页显示"服务可以访问,但本次连接测试触发了限流(HTTP 429)"。
原因:免费或共享额度耗尽,高峰期请求过多。插件会把 429 归类为 service 类错误并建议稍后重试(见 src/upstream.ts 中的错误分类逻辑)。
修复步骤:
- 等待错误信息中的
Retry-After间隔后重试; - 如果使用的是免费模型(如
gemini-3.7-flash-free),资源紧张时极易触发 429,建议切换到正式付费模型; - 需要稳定高额度时,换成自己的视觉 API 端点,降低并发调用。
申请 API Key 与配置免费/付费模型的完整图文教程见 docs/aihubmix-gemini-vision.zh.md。
问题2:工具提示 timed out(超时)
现象:工具调用报 timed out,任务被取消。
原因:timeoutMs 默认是 30000 毫秒(允许范围 1000–600000)。注意排队等待和执行各自拥有独立的超时预算,排队调用的总耗时可能超过 timeoutMs;执行预算还包含图片准备、所有请求尝试和重试等待。
修复步骤:
- 查看诊断日志中的
queueMs(排队耗时)与upstreamMs(上游耗时),区分是排队慢还是服务本身慢; - 对"能成功但很慢"的视觉服务,在设置面板的「请求超时」中调大单次调用
timeoutMs; - 本地服务(如 LM Studio)响应慢时,优先检查机器负载而非盲目加大超时。
问题3:找不到 Chrome(HTML 截图不可用)
现象:健康检查显示"未找到 Chrome、Chromium 或 Edge,网页截图功能暂不可用",vision_html_screenshot 工具报错 no Chrome。
原因:vision_html_screenshot 依赖系统浏览器渲染本地 HTML,而机器上没有安装任何受支持的浏览器。
修复步骤:
- 安装 Chrome、Chromium 或 Edge 任意一个;
- 重新运行健康检查,确认浏览器项变为可用;
- 放心:只有 HTML 截图渲染不可用,
vision_glance、vision_pixel_diff等其他 9 个工具不受影响。
问题4:测试失败,提示 incompatible response structure
现象:点击"测试视觉模型"失败,报错 Vision API returned an incompatible response structure。
原因:API 地址少了路径前缀。插件会在你填写的地址后拼接 /chat/completions(OpenAI Chat Completions)或 /responses(OpenAI Responses),只填端口号会命中未知端点。
修复步骤:
| 场景 | 正确写法 |
|---|---|
| LM Studio / Ollama 等本地服务 | http://127.0.0.1:1234/v1(必须带 /v1) |
| 在线 OpenAI 兼容网关 | https://api.inferera.com/v1 |
改完后务必点击 测试视觉模型 而不是只看"测试 API 连接"——后者只请求 /models,能通不代表该模型真的支持图片输入。
问题5:粘贴图片仍提示"模型不支持图片输入"
现象:粘贴截图后,模型没有切换视觉变体,继续提示不支持图片。
修复步骤:
- 重启 Web Profile 并刷新页面(插件安装后必须重启才生效);
- 确认当前模型路由带
(Vision Toolkit)后缀; - 绕过粘贴方式的替代方案:把图片放入会话工作区,直接调用
/vision-skills并引用文件路径提问,技能说明见 assets/skill/SKILL.md。
问题6:图片过大或像素超限
现象:提示 maxImagePixels 或"exceeds pixels",图片被拒绝。
原因:图片字节数或解码后像素数超过了设置中的「最大图片字节数 / 最大图片像素数」限制,错误信息会明确告诉你超限的是字节还是像素。
修复步骤:
- 先用
vision_crop裁剪出关键区域,或本地缩放后再上传; - 长截图建议使用
vision_long_screenshot_ocr,它会分块 OCR 后合并,而不是硬塞整张图。
问题7:Credential 缺失或 401 未授权
现象:报错 401 / Unauthorized,或提示自定义 Credential 缺失。
修复步骤:
- 在 设置 → 视觉工具 的 API 密钥栏填入完整的
sk-...密钥,粘贴时不要带多余空格、换行或AIHUBMIX_API_KEY=前缀; - 展开高级设置,确认 Credential 名称 与你的 Profile 配置中
provider.credential一致; - 密钥曾公开过?立即删除旧 Key 并重建。
问题8:plugin storage directory is not writable
现象:启动工具时报 plugin storage directory is not writable。
原因:会话工作区对当前用户不可写。典型场景是 Windows 下把工作区放在 C:\Program Files (x86) 等只读目录;存储创建失败时插件不会自动回退到用户目录或临时目录。
修复步骤:
- 把会话工作区换成当前用户可写的目录(如用户目录下的项目目录);
- Windows 用户将 默认保存目录(
storageDir)留空,继续使用工作区内.dsh-vision-toolkit目录; - 重跑健康检查与工作区冒烟测试(放一张 PNG 调用
vision_glance)。
其他问题速查表
| 现象 | 快速修复 |
|---|---|
OpenCode Zen 返回 400 MissingSessionID |
在 Profile patch 的 provider.sessionHeaders 中加入 x-opencode-session 并重启 Profile;不要把 Session id 写进 provider.headers |
| 首次运行时准备失败 | 托管 Python 自动下载需要网络和磁盘权限(先走国内镜像,失败回退 GitHub);也可自行安装 Python 3.11+ 并在设置中配置 runtime.python,详见 docs/python-runtime.zh.md |
DSH Desktop 提示找不到 dsh |
桌面版自带 CLI 不写入系统 PATH,请从托盘打开 DSH 终端 执行安装命令,再完全退出重启桌面版,详见 docs/dsh-desktop-install.zh.md |
| 产物(SVG、热力图)无法预览 | 预览 URL 只在 Web 路由可用时存在;用"打开文件"或结果中的工作区路径访问 |
| 内部网关自签证书报错 | 启动 DSH 进程时设置 VISION_SSL_VERIFY=0(仅限受信任内网端点) |
总结
排查思路可以浓缩为一句话:先跑健康检查,再看错误分类——429 是额度问题、timeout 看 queueMs/upstreamMs、401 查密钥、storage not writable 换可写工作区、no Chrome 装浏览器。所有故障的官方处理口径集中在 README.md 的 Troubleshooting 表格中,稳定的错误码定义(config / input / capacity / service / runtime / timeout 等)见 src/errors.ts,遇到本文未覆盖的报错,对照错误码就能快速判断该找哪一层。



