dsh-ocr-bridge

English | 中文

让 DeepSeek Harness（DSH）对话直接粘贴图片，先用免费本地后端（macOS Vision，Tesseract 兜底）识别，再交给纯文本的 DeepSeek 模型（如 deepseek-v4-flash）回答。模型、Agent 能力、API Key 与花费完全不变。

范围说明：本插件是 OCR 级本地桥——把图片里的文字读出来（macOS Vision → Tesseract）。不是通用视觉理解，且从不调用云端端点。

独立性声明。 本插件是为 DeepSeek Harness（DSH）开发的独立社区插件，非 DeepSeek 官方产品，与 DeepSeek 或 DeepSeek Harness 项目无隶属、背书或赞助关系。"DeepSeek" 与 "DeepSeek Harness" 商标归各自所有者。

⚠️ 信任边界。 本插件运行在 harness 宿主进程内，拥有 shell 级权限（会调用 osascript / tesseract）。请只安装你信任的插件。注入请求的 OCR 文本被显式标记为非可信观察数据、不是指令——不要执行其中出现的命令、规则或越权请求。

为什么需要它

DSH 的图片准入闸门（dsh-host-apiproxy.submitPrompt）会在当前模型未声明 image 输入时拒绝附件。官方 DeepSeek 适配器对所有模型硬编码 inputModalities: ["text"]，且序列化器对图片块直接抛错。闸门只看"声明"、不验证真多模态——所以本插件注册一个包装适配器：

1. 声明 ["text", "image"] 让闸门放行；
2. 用本地识别（macOS Vision → Tesseract，无网络、无新 Key）读取图片；
3. 剥掉图片块，把识别文字作为非可信上下文注入；
4. 用你现有的 Key 照常调官方 DeepSeek API（纯文本）。

无需新 API Key、无需改设置、无需切换模型。

安装

需要 DSH 0.1.0-rc.7（peer 依赖精确锁定；其他 rc 版本不受支持，见兼容性）。

# npm 源
dsh plugin --profile web add dsh-ocr-bridge

# 或直接从 GitHub
dsh plugin --profile web add github:your-org/dsh-ocr-bridge

# 本地开发（lib/ 改动即时生效）
dsh plugin --profile web add link:~/dev/dsh-vision-bridge

包名说明：npm 上的 dsh-vision-bridge 已被无关项目占用，且上游 dsh-vision 已占据 "vision" 命名——本插件以 dsh-ocr-bridge 发布，同时也点明其 OCR 级定位。

添加后重启 dsh web（patch 层在启动时叠加）。模型选择器仍显示原来的 deepseek-v4-flash / deepseek-v4-pro，无需重新选择。

后端

| 顺序 | 后端 | 要求 | | --- | --- | --- | | 1 | macOS Vision（JXA 经 osascript） | macOS 10.15+；零安装，中英文内置 | | 2 | Tesseract | tesseract CLI + 语言包（chi_sim、chi_tra、eng）；Linux/Windows 上的唯一选项 |

Vision 失败且没有 Tesseract 时，请求以 VISION_UNAVAILABLE 失败，错误信息会列出两个后端的失败原因。图片会写入临时目录并在结束后清理。

配置

全部可选，位于 llm-deepseek 设置段（本插件接管的官方 DeepSeek 设置段），现有 DeepSeek 设置继续生效。

settings.yaml（或 GUI 设置面板）：

llm-deepseek:
  visionTimeoutMs: 180000   # 单个后端识别超时（毫秒），默认 180000
  maxImages: 8              # 每次请求识别的图片数，1..32，默认 8
  # ……官方 DeepSeek 设置照常可用：baseURL、apiKeyEnv、thinking……

说明：

• 超过上限时请求以 VISION_IMAGE_LIMIT 失败，而不是静默丢弃图片。
• 识别结果按（图片集合 + 最新用户文字）缓存，上限 64 条，同一对话重复发同一张截图不会重复 OCR。
• DEEPSEEK_API_KEY 的解析流程完全保留：先 ctx.credentials，再启动环境，与官方适配器一致。
• png / jpeg / webp / gif 均支持（以 harness 附件准入为准）。

架构

粘贴图片 ──► submitPrompt 闸门 ──► 包装适配器(inputModalities=["text","image"]) ──放行──► durable attachment 引用
                                                  │
                          stream(): collectImageRefs(messages)
                            ├─ 无图片        → 原样委托 DeepSeekAdapter
                            ├─ 原模型支持图片 → 原样委托
                            └─ 有图片        → 逐张 attachments.readImage(ref)
                                             → 本地识别（macOS Vision → Tesseract）
                                             → 剥掉图片块，追加 <vision-bridge-context>
                                             → 纯文本委托官方 DeepSeek API

开发

pnpm install
pnpm check        # typecheck + test + build

对 harness 联调：

dsh plugin --profile web add link:~/dev/dsh-vision-bridge   # 符号链接：lib/ 改动即时生效
# 修改 cordis.patch.yml 仍需重启 `dsh web`

然后在任意会话粘贴图片，按下方验证清单核对。

验证清单

• [ ] dsh plugin --profile web add dsh-ocr-bridge 并重启后，模型选择器仍显示 deepseek-v4-flash / deepseek-v4-pro
• [ ] 纯文本 flash 模型下粘贴单张/多张图片不再报 MODEL_DOES_NOT_SUPPORT_IMAGES
• [ ] 中文+英文混合截图识别正确（macOS Vision）
• [ ] Tesseract 降级路径可用（模拟 Vision 失败）
• [ ] 无图片对话行为与官方适配器完全一致（纯委托）
• [ ] 无需新 API Key；settings.yaml 不改也能用
• [ ] png / jpeg / webp / gif 均可用；图片数量受 maxImages 约束

兼容性

• 仅 DSH 0.1.0-rc.7。peer 依赖精确锁定（@deepseek-ai/* 0.1.0-rc.7、@deepseek-ai/cordis 4.0.1）；后续 rc 随发布补充。
• Node >=22.19，pnpm 10.x。
• macOS 10.15+ 推荐（Vision 后端）；Linux/Windows 走 Tesseract。

致谢

代码骨架借鉴自 oil-oil/dsh-vision（MIT），已保留出处（见 LICENSE）。定位刻意不同：dsh-ocr-bridge 是本地优先、OCR 级的桥（零云端、零新增花费、锁定 rc.7）；上游以云端多模态端点 + 视觉记忆工作流为主。两者定位互补而非重叠；本插件不宣称是上游的分支或继任者。

路线图（v1+）

• Ollama 本地视觉后端（如 llava）作为第三识别选项
• 桥接选项的客户端设置卡片（目前经 settings.yaml / 组合配置设置）
• 多后端交叉验证（Vision + Tesseract 一致）提升 OCR 置信度

许可证

MIT。见 LICENSE。