dsh-vision — 给纯文本 DeepSeek 的「眼睛」（DSH 视觉方案总入口）

本仓库是 DeepSeek Harness（DSH）视觉方案的总入口：让没有视觉能力的 DeepSeek 模型 在 Web 端与 CLI 端都能看图、贴图、OCR、追问细节。核心插件 view_image（本仓库维护） 负责「任意视觉问答」；方案还整合了 ModLens（粘贴链路与 请求前图片转换）、macOS 本地 OCR（免费离线）与多 provider 兜底脚本。

方案修订：2026-08-15（ModLens 架构落地 + autoRead 修复 + dsh-parse 文档解析层）｜审查报告见 docs/REVIEW.md

配套 vision skill（五层使用手册，与本仓库同步维护）：docs/vision-skill.md

为什么需要这套方案

• DSH 的 DeepSeek chat-completions 适配器是纯文本的：消息或历史中出现任何图片块会整轮报 UNSUPPORTED_CONTENT，且历史重放会把图片永久带进每次请求——即「贴一张图，会话永久瘫痪」。
• 本方案在五层上把图片在进入模型前转成文字证据：贴图链路 → 请求前转换 → 模型工具 → 本地兜底（OCR/文档解析）→ 模型变体。

架构总览

端到端链路

用户在输入框贴图
   │ DSH 原生附件入库（准入声明 ["text","image"] 放行）→ 聊天里显示整张图缩略图
   ▼
发给模型的 wire：L2 图片块 →「已保存为本地文件：<路径>」文本 ──▶ 模型调 view_image / dsh-ocr 读图

• 历史含图的老会话：序列化补丁在重放时同样转换，不再 UNSUPPORTED_CONTENT（2026-08-15 已实测修复）。
• autoRead 已关闭（autoRead: false）：它会在 pre-step 改写消息本身，把聊天里的图替换成 OCR 英文文字（2026-08-15 实测踩坑），序列化补丁是保留整张图的正确层。
• paste-to-path 已关闭（pasteToPath: false）：它会把贴图换成路径文字、吞掉图片预览。

实现效果（2026-08-15 实测）

• view_image（qwen3-vl-flash）：任意视觉问答、OCR、数数、读图表、UI 分析，中文回答。
• dsh-ocr：中文+英文离线 OCR，PNG/JPEG/HEIC/PDF 逐页，零费用零网络。
• dsh-parse：PDF/Word/PPT/Excel 保结构转 Markdown（标题/列表/表格），本地 ~0.4s，免费不联网（2026-08-15 实测，见 docs/dsh-parse.md）。
• vision.py：view_image 不可用时自动按可用 key 选 provider 兜底，实测可用。
• modlens_read_image：结构化 JSON 证据（ocr.full_text、布局阅读序、语义、不确定性清单）。
• 贴图：原生入库显示整张图缩略图，序列化层转成路径文本后模型正常读图回答（实测）。
• 修复前：默认路由历史含图会话每轮必崩 UNSUPPORTED_CONTENT；修复后：正常响应。

准度与速率优化（2026-08-15）

• 文字提取永远先走 dsh-ocr（本地 ~0.5s、免费、中文 OCR 强）；视觉问答走 view_image（qwen3-vl-flash 免费快档 ~1–3s）；需要可引用证据时用 modlens_read_image。

• 文档保结构解析：只提文字走 dsh-ocr；整篇文档要保留标题/表格结构走 dsh-parse（markitdown 本地封装，~0.4s）；扫描件无文字层时先 dsh-ocr 逐页提文字再 view_image 复核。

• 同图同问秒回：本地图片答案带 LRU 缓存（内容寻址附件天然不可变；用户文件按大小+mtime 失效），重复读图零成本。

• 大图自动压缩：上传前长边 >1600px 的 macOS 本地图自动 sips 降采样（实测 3.3MB→1.4MB），输入 token 是 VLM 耗时主因。

• 高精度自动路由：问题含「高精度/仔细/精确」等词时自动切 precisionModel（默认 qwen-vl-plus），日常仍走免费 flash。

• 双免费线故障转移（modlens 引擎）：gemini-api（gemini-flash-latest）→ openai（qwen3-vl-flash） 跨厂商自动切换；modlens doctor 可查链状态。第三线 antigravity-cli（谷歌账号免 key）可随时接入。

• 回退链：view_image 已配 fallbackModels: [qwen-vl-plus]——免费档被 429/404/5xx 限流时自动回退付费档（仅在失败时计费），消除「免费档限流即彻底不可用」的单点。

• 并发：view_image / modlens_read_image 均并发安全，多图可并行读。

• 高精度场景：临时把 model 改为 qwen-vl-plus / qwen-vl-max（付费档精度更高），或 vision.py --provider <name> 换引擎对比；结构化证据用 modlens_read_image（含不确定性清单，可交叉验证）。

• 已知取舍：序列化层方案下模型要先花一轮工具调用读图（相比 autoRead 多一次往返，但保住了聊天里的整张图）。

• 实测基准（1740×928 截图，单样本）：dsh-ocr ~0.5s；view_image/vision.py（qwen3-vl-flash）~4–9s 波动；modlens 结构化管线 ~24s（多轮调用，仅证据场景用）。

部署（双端）

一键安装 dsh-vision 插件：见下方 Install（Windows/macOS/Linux 预构建包或源码）。

Install（dsh-vision 插件本身）

下载预构建包（推荐）

1. 从 Releases 获取 dsh-vision-0.1.0.zip，用 SHA256SUMS.txt 校验。
2. 解压后双击 install.bat（Windows）/ install.command（macOS/Linux）。
3. 重启 dsh web，浏览器硬刷新（macOS Cmd+Shift+R / Windows Ctrl+Shift+R）。

卸载：uninstall.bat / uninstall.command。

从源码

git clone https://github.com/xzyonline/dsh-vision.git
cd dsh-vision && npm install && node scripts/install.mjs

Configuration（view_image）

安全模型

• 密钥只存 0600 文件（~/.dsh/.env、~/.dsh/cordis.patch.yml、~/.modlens/config.json）；错误消息全程 key 脱敏。
• 本地文件扩展名白名单 + 体积上限 + 硬超时；响应体 2 MB 硬上限。
• 图片外发面：view_image/modlens_read_image 会把（白名单内）本地图片发给所配 VLM——单用户工具的模型判断风险面，已在 docs/REVIEW.md 评估。
• 更多见 SECURITY.md 与 docs/REVIEW.md。

测试与截图

• 完整验收矩阵（14 用例）与实测基准：docs/TESTING.md
• 可视化测试报告：assets/test-report.html（截图 assets/test-report.jpg）· 测试样图 assets/test-image.png

已知问题与修复记录

见 docs/REVIEW.md（2026-08-15 审查：4 个 bug 全修复、1 个观察项、4 项安全评估）。

引用与致谢

License

• BSD-3-Clause，见 LICENSE；依赖归因见 THIRD_PARTY_NOTICES.md。
• 不捆绑任何模型权重或第三方服务密钥；识图能力由你配置的端点提供。