dsh-vision-toolkit故障排查清单:429、超时、Chrome缺失等8个常见问题快速修复

原创2026-10-23 13:17:092,211 阅读
文章标签:dsh-plugin计算机视觉OCRAI 插件GUI 自动化AI 技能大模型

dsh-vision-toolkit故障排查清单:429、超时、Chrome缺失等8个常见问题快速修复

dsh-vision-toolkit 是专为 DeepSeek Harness 纯文本模型打造的视觉工具箱:粘贴图片直接识别、多张图片问答、长截图 OCR、截图到前端 UI 还原,一行命令即可安装使用。本文整理为一份 dsh-vision-toolkit 故障排查清单,覆盖 429 限流、timed out 超时、Chrome 缺失、API 地址写错等 8 个新手最常遇到的问题,每个问题都给出「现象 → 原因 → 修复步骤」,照着做即可快速恢复视觉能力。

dsh-vision-toolkit 视觉工具设置面板

排查前先做这一步:健康检查

打开 设置 → 视觉工具(Settings → Vision Toolkit),面板会分别显示「视觉服务」「运行时」「浏览器」等健康状况。绝大多数故障都能在这里先定位到原因,再对照下面的清单逐项修复。

问题1:视觉服务返回 429(限流)

现象:工具调用或连接测试提示 429 / rate limit / quota,设置页显示"服务可以访问,但本次连接测试触发了限流(HTTP 429)"。

原因:免费或共享额度耗尽,高峰期请求过多。插件会把 429 归类为 service 类错误并建议稍后重试(见 src/upstream.ts 中的错误分类逻辑)。

修复步骤:

  1. 等待错误信息中的 Retry-After 间隔后重试;
  2. 如果使用的是免费模型(如 gemini-3.7-flash-free),资源紧张时极易触发 429,建议切换到正式付费模型;
  3. 需要稳定高额度时,换成自己的视觉 API 端点,降低并发调用。

AIHubMix 免费视觉模型页面显示图像输入能力

申请 API Key 与配置免费/付费模型的完整图文教程见 docs/aihubmix-gemini-vision.zh.md。

问题2:工具提示 timed out(超时)

现象:工具调用报 timed out,任务被取消。

原因:timeoutMs 默认是 30000 毫秒(允许范围 1000–600000)。注意排队等待和执行各自拥有独立的超时预算,排队调用的总耗时可能超过 timeoutMs;执行预算还包含图片准备、所有请求尝试和重试等待。

修复步骤:

  1. 查看诊断日志中的 queueMs(排队耗时)与 upstreamMs(上游耗时),区分是排队慢还是服务本身慢;
  2. 对"能成功但很慢"的视觉服务,在设置面板的「请求超时」中调大单次调用 timeoutMs;
  3. 本地服务(如 LM Studio)响应慢时,优先检查机器负载而非盲目加大超时。

问题3:找不到 Chrome(HTML 截图不可用)

现象:健康检查显示"未找到 Chrome、Chromium 或 Edge,网页截图功能暂不可用",vision_html_screenshot 工具报错 no Chrome。

原因:vision_html_screenshot 依赖系统浏览器渲染本地 HTML,而机器上没有安装任何受支持的浏览器。

修复步骤:

  1. 安装 Chrome、Chromium 或 Edge 任意一个;
  2. 重新运行健康检查,确认浏览器项变为可用;
  3. 放心:只有 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:粘贴图片仍提示"模型不支持图片输入"

现象:粘贴截图后,模型没有切换视觉变体,继续提示不支持图片。

在 DSH 会话中粘贴图片调用视觉工具进行识别

修复步骤:

  1. 重启 Web Profile 并刷新页面(插件安装后必须重启才生效);
  2. 确认当前模型路由带 (Vision Toolkit) 后缀;
  3. 绕过粘贴方式的替代方案:把图片放入会话工作区,直接调用 /vision-skills 并引用文件路径提问,技能说明见 assets/skill/SKILL.md。

问题6:图片过大或像素超限

现象:提示 maxImagePixels 或"exceeds pixels",图片被拒绝。

原因:图片字节数或解码后像素数超过了设置中的「最大图片字节数 / 最大图片像素数」限制,错误信息会明确告诉你超限的是字节还是像素。

修复步骤:

  1. 先用 vision_crop 裁剪出关键区域,或本地缩放后再上传;
  2. 长截图建议使用 vision_long_screenshot_ocr,它会分块 OCR 后合并,而不是硬塞整张图。

问题7:Credential 缺失或 401 未授权

现象:报错 401 / Unauthorized,或提示自定义 Credential 缺失。

修复步骤:

  1. 在 设置 → 视觉工具 的 API 密钥栏填入完整的 sk-... 密钥,粘贴时不要带多余空格、换行或 AIHUBMIX_API_KEY= 前缀;
  2. 展开高级设置,确认 Credential 名称 与你的 Profile 配置中 provider.credential 一致;
  3. 密钥曾公开过?立即删除旧 Key 并重建。

问题8:plugin storage directory is not writable

现象:启动工具时报 plugin storage directory is not writable。

原因:会话工作区对当前用户不可写。典型场景是 Windows 下把工作区放在 C:\Program Files (x86) 等只读目录;存储创建失败时插件不会自动回退到用户目录或临时目录。

修复步骤:

  1. 把会话工作区换成当前用户可写的目录(如用户目录下的项目目录);
  2. Windows 用户将 默认保存目录(storageDir)留空,继续使用工作区内 .dsh-vision-toolkit 目录;
  3. 重跑健康检查与工作区冒烟测试(放一张 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(仅限受信任内网端点)

使用视觉工具比较 UI 还原图片差异的会话示例

总结

排查思路可以浓缩为一句话:先跑健康检查,再看错误分类——429 是额度问题、timeout 看 queueMs/upstreamMs、401 查密钥、storage not writable 换可写工作区、no Chrome 装浏览器。所有故障的官方处理口径集中在 README.md 的 Troubleshooting 表格中,稳定的错误码定义(config / input / capacity / service / runtime / timeout 等)见 src/errors.ts,遇到本文未覆盖的报错,对照错误码就能快速判断该找哪一层。

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