dsh-vision

一句话定位

给纯文本 DeepSeek 模型装上视觉能力：把图片转成模型能"看到"的占位符并暴露一个 vision 工具，让模型在对话中主动调用识图。默认走豆包 Web 通道，浏览器登录即可使用，不要求任何 API key。

核心能力

• 图片占位化：把用户消息里的图片块转成文字占位符，喂给原本只吃文本的 DeepSeek，避免"粘贴图片被拒"
• 注册 vision 工具：让模型主动调用，单图/多图/OCR/区域细查/多图对比都能识别
• 自动档位升级：detail=auto 时先跑标准检查，被判定为复杂画面再自动跑深度检查
• 视觉证据记忆：识别结果写入会话时间线，跨轮复用、会话压缩后还能自动恢复
• 内容哈希缓存：同图同问同通道同档位，进程内只识一次，避免重复扣费或重跑
• 多通道自动降级：豆包 Web / Antigravity IDE 额度 / Gemini API / Cockpit 反代 / aicode 直连 / 通用 IDE CLI（Claude Code、Gemini CLI 等），按配置自动选择

技术实现

• 语言: TypeScript（服务端 + React 客户端）
• 关键依赖: @deepseek-ai/dsh-tools（注册工具）、@deepseek-ai/schemastery（Config 校验）、@deepseek-ai/dsh-llm（消息构造）
• 架构模式: 双端插件——服务端 src/index.ts 注册 LLM 适配器和 vision 工具并暴露 /api/vision，客户端 src/client/plugin.tsx 在会话头部挂"识图"面板；豆包 Web 通道额外需要在 Windows 侧跑 bridge.mjs（puppeteer-core 驱动已登录 Chrome）
• 入口文件: 服务端 src/index.ts（导出 apply、Config），客户端 src/client/plugin.tsx（导出 apply），队列桥接 bridge.mjs

适用场景

DSH 用户在对话里粘贴图片想让 DeepSeek 帮忙看，但模型本身只吃文本。比如问"截这张报错给我解释"、"对比这两张 UI 截图哪张更好"、"把这段聊天记录 OCR 出来"。如果不想配 API key 又想看图，默认通道登录一次豆包就行；如果有 Antigravity/Gemini/Claude Code 订阅，还能换通道用额度。

前置依赖与兼容性

安装方式

dsh plugin --profile web add dsh-vision-web

配置项

本地覆盖：所有配置都可在 ~/.dsh/dsh-vision.json 里以 JSON 覆盖（由 loadOverrides 加载，路径取 $DSH_HOME 或 ~/.dsh）。

常见问题

Q: 装好后能直接用吗？

A: 默认通道是豆包 Web（零成本、免 API key）。WSL 环境需要在 Windows 侧运行一次 node bridge.mjs，并在那个已打开的 Chrome 里登录豆包，之后粘贴图片即可。

Q: 没有 Windows 浏览器也能用吗？

A: 可以，但需要换通道。配置 genlangKey（Gemini API）或 cockpitKey（Cockpit 反代），再把 defaultChannel 改为对应通道；Antigravity 通道仅在运行该 IDE 时可用。

Q: 同一张图重复提问会重复扣费或重跑吗？

A: 不会。插件按图片字节哈希 + 提示词 + 档位 + 模式 + 区域 + 模型 + 通道 + 提示版本算缓存键，同一进程内同一请求只识图一次（src/vision-core.ts:124）。

Q: 一次最多能传几张图？

A: 最多 8 张，单张不超过 8MB，总大小不超过 32MB，HTTP 请求体不超过 48MB；OCR/区域/对比模式各自有额外校验（src/index.ts:731,902-904,1004）。

Q: 为什么网页通道在 WSL 上不直接连 Chrome？

A: WSL 默认无法主动连 Windows 端口，所以插件在 WSL 侧开队列服务（默认 127.0.0.1:9340），由 Windows 侧的 bridge.mjs 主动轮询并驱动已登录的 Chrome（src/web-channels.ts:43，README.md:113-127）。

Q: 怎么卸载？

A: 配置文件在 ~/.dsh/dsh-vision.json（由 loadOverrides 读取）；删除该文件即可清除本地 key/路径覆盖。插件本体通过 dsh plugin --profile web remove dsh-vision-web 卸载（src/index.ts:109-122）。

上手难度

入门 — 默认零配置就能在 WSL + Windows 浏览器组合下用起来；要切到 API/Antigravity/IDE CLI 通道才需要写一段 YAML。

已知问题与限制

• 单图 8MB / 单次总 32MB / HTTP 请求体 48MB 上限，超出会返回错误（src/index.ts:902-904,1004）
• 一次最多 8 张图；对比模式至少 2 张；区域细查必须提供区域坐标或自然语言（src/index.ts:731-733）
• 默认豆包 Web 通道必须在 Windows 侧持续运行 bridge.mjs，且该 Chrome 必须已登录豆包；未登录桥接会报"豆包输入框未找到"
• Ant antigravity 通道依赖运行中的 Antigravity IDE 与 language_server.exe；PID/端口/CSRF 每调用自动发现，但如果 IDE 完全关闭会直接报错（src/index.ts:320-323,509）
• API 通道依赖 WSL 调用 Windows curl.exe（默认 /mnt/c/Windows/System32/curl.exe），网络受限环境需要确保该路径存在
• Gemini API 过载（503）会触发自动重试 2 次，仍失败才会把错误回给模型（src/index.ts:211-229）
• aicode 通道（oauthAccount）返回 500 时，需要 Antigravity IDE 的 workspace 绑定才能用；插件会提示改用 cockpit 通道（src/index.ts:279-281）
• 客户端面板暂未提供"删除单张图"快捷键以外的高级编辑（如裁剪/旋转），预处理请在外部完成
• 错误信息会自动截断（如 stderr 限 500 字符、agentapi 错误限 1200 字符）以便日志可读，但排查时可能要靠完整日志（src/index.ts:141-148）

给 DeepSeek Harness 的纯文本 DeepSeek 一双眼睛——默认走豆包 Web，零成本、免 API key。

English | 简体中文

一句话：不用 API key、不用付费——浏览器里登录一次豆包，DeepSeek 就能在每轮对话里看图。粘贴、识图、回答。

✨ 为什么值得用

🎯 真实效果（2026-08 实测，全链路真实调用）

输入：一张橘猫照片 + 这是什么动物？它在做什么？请用中文回答。

输出（豆包 Web 通道——默认）：

这是一只橘猫（家猫），它四仰八叉仰躺在床上睡觉，肚皮露在外面，四肢舒展，睡得十分放松惬意。猫咪把肚子露出来，说明它对周围环境很有安全感。

输出（反重力通道 · flash 档）：

这是一只橘猫（橘色虎斑家猫）。它正仰面熟睡/惬意放松：四脚朝天、露出圆滚滚毛茸茸的肚子，正舒适地躺在深色床垫/毯子上睡觉。

你粘贴图片 + 提问
  → dsh-vision 把图片转成占位符，DeepSeek（大脑）看到
  → DeepSeek 调用 vision 工具 → 豆包 Web（默认）/ 其他通道识图
  → 文字证据回填 → DeepSeek 继续回答

🚀 快速开始

方式零：豆包 Web（默认，零成本）

1. 装插件：

   dsh plugin --profile web add dsh-vision-web
   

2. 启动 Windows 桥接（驱动你已登录的 Chrome）：

   # 在 Windows 侧：连接一个开了调试端口的 Chrome，然后运行
   node bridge.mjs    # 详见下方「豆包桥接」章节
   

3. 在那个 Chrome 里登录一次 doubao.com。
4. 重启 dsh web，粘贴图片——搞定。全程不需要任何 API key。

方式一：反重力额度（如果你用 Antigravity）

配置好工作区后，插件自动优先走反重力（按模型名选 flash/pro 档）：

- insert:
    - id: vision
      name: dsh-vision
      config:
        antigravityWorkspace: /path/to/workspace
        antigravityProjectId: your-project-id
        antigravityLsExe: /path/to/language_server.exe
        antigravityWindowsHome: /mnt/c/Users/you
        antigravityBrainDir: /mnt/c/Users/you/.gemini/antigravity/brain

端口/CSRF 每次调用自动发现，IDE 重启也不用改配置。

方式二：Gemini API（降级通道）

      config:
        genlangKey: AIza...   # https://aistudio.google.com/apikey

方式三：任意 IDE CLI（Claude Code / Gemini CLI / Qwen Code / MiMo…）

如果你有编程软件的会员，用它的本地 CLI 来识图（配置驱动，无需改代码）：

      config:
        ideCli:
          enabled: true
          exe: claude                      # 或 gemini / qwen / 任意 CLI
          argsTemplate: "-p {prompt}"      # {prompt} 替换为提问 + 图片引用
          imageRefTemplate: "{path}"       # Gemini CLI 用 "@{path}"
          timeoutMs: 120000

通道把提问 + 图片文件路径传给 CLI，stdout 即回复——Claude Code、Gemini CLI、Qwen Code、MiMo 等都用同一套配置接入。

使用

1. 面板：会话头部点「识图」→ 添加/粘贴图片 → 提示词 → 模式/档位/通道 → 识别。
2. 对话流：模型选择器选 deepseek-vision 路由，粘贴图片发送——模型自动调用识图。

🌉 豆包桥接（零成本通道怎么跑）

豆包 Web 通道自动化的是你已登录的浏览器，而不是调 API：

DSH 插件 (WSL) ──submit──▶ 队列服务 (127.0.0.1:9340)
                                ▲ 轮询
Windows 桥接 (node + puppeteer-core) ──┘
        │ CDP 连接 Chrome（调试端口）
        ▼
豆包侧边栏：上传图片 → 输入提问 → 回车 → 等回复
        │
        ▼ 回复文本 → POST /result → DSH 插件

• 一次登录：在桥接用的 Chrome profile 里登录一次豆包，之后一直复用。
• Windows→WSL localhost 转发承载队列通信，无需改防火墙。
• 桥接以 bridge.mjs 随仓库分发——在 DSH 旁边跑一次（node bridge.mjs），永久轮询。
• WSL 无法直连 Windows 端口，所以队列放在 WSL 侧、桥接从 Windows 侧主动轮询。

🧠 识图引擎——复杂识图到底怎么工作

天真的"看图→描述"循环在密集截图、表格、UI 原型和多图对比面前会崩。dsh-vision 把识图做成了结构化、自动升级、带记忆的流水线：

1. 档位自动升级——它知道一遍不够

detail: auto 走两遍策略：

第一遍（standard + 预判）──▶ complexity == "simple" ──▶ 完成
                            └─▶ complexity == "complex" ──▶ 第二遍（deep）──▶ escalated 结果

视觉模型自己判断复杂度。以下情况都判为 complex 并自动触发深度检查：

• 多主体关系 · 密集小字 · OCR 密集内容
• 表格 / 图表 / 代码 / 界面 · 计数 · 对比 / 找差异
• 专业画面 · 多步空间推理

2. 四种任务模式，一个工具

3. 结构化证据，不是流水账

每次识图都要求输出严格 JSON 证据对象：

{
  "complexity": "simple|complex",
  "base_evidence": {
    "summary": "中性概述",
    "ocr": "可见文字（没有则为空）",
    "layout": ["布局观察"],
    "entities": ["实体"],
    "relations": ["关系"],
    "uncertainty": ["明确的不确定项"]
  },
  "query_answer": "直接回答用户"
}

观察与推断分离、不确定性显式写出（绝不脑补）、每项列表限长——上下文保持紧凑。

4. 长上下文视觉记忆——模型永远不会"忘"它看过什么

• 每次结果作为持久化 <dsh-vision-evidence> 记录写入会话时间线。
• 跨轮复用：同一张图 + 同一个问题命中已有记录——识别一次，永远记住。
• 视觉记忆清单：每次请求流自动附带近期证据目录，模型可以主动追问——放大区域、重新 OCR、跟新截图对比——你什么都不用重新粘贴。
• compaction 恢复：长会话压缩后，近期视觉记录自动恢复。

5. 内容哈希缓存——同样的像素绝不付两次钱

缓存键 = SHA-256(图片字节) + prompt + detail + mode + region + model + channel + prompt版本，进程内 LRU。

⚙️ 完整配置

🔧 Troubleshooting

🔒 隐私

• 豆包 Web：图片发给你自己登录的豆包会话——和手动用网页一样。
• API key：只存本地配置；错误信息自动脱敏，绝不写日志。
• OAuth 凭据：不内置——aicode 通道要求用户自带，存本地配置。

🏗️ 架构

src/
├── index.ts        # 服务端：适配器、vision 工具、/api/vision、compaction 恢复
├── vision-core.ts  # 提示词构建、响应归一、证据记录、流修复
├── web-channels.ts # 豆包 Web 队列服务（WSL 侧）
└── client/
    └── plugin.tsx  # 客户端面板（多图/粘贴/模式/档位/通道）

bridge.mjs          # Windows 桥接：轮询队列，CDP 驱动豆包

🛠️ 开发

git clone https://github.com/54xkeee/dsh-vision
cd dsh-vision
npm install
npm run build     # esbuild → lib/index.js + lib/client.js
npm test          # node --test

📄 License

MIT

🙏 Credits

• vision-toolkit 架构（占位符 + vision 工具 + 包装适配器 + 证据记忆）与 dsh-youreyes 共享
• 通道与错误处理约定参考 dsh-vision-proxy 等社区插件