dsh-eyes

给 DeepSeek Harness（@deepseek-ai/dsh）里没有视觉能力的模型装上一双"眼睛"。

English · MIT

✨ 效果预览

| 原图 | 无视觉模型粘贴图片,自动转写 | 视觉模型设置页(独立配置) | 识图效果 | | --- | --- | --- | --- | | | | | |

特性

• vision_read 工具 —— 无视觉模型需要看图时,把图片交给视觉模型转写,以文本返回;不注入 image 块,不触发适配器模态闸门(UNSUPPORTED_CONTENT)。
• GUI 直接粘贴图片 —— 覆写宿主准入(admitPastedImages,默认开启),选 deepseek-v4-flash 这类无视觉模型也能贴图,发送时自动转写。
• 独立视觉模型配置页 —— 设置侧边栏"视觉模型"页,勾选即生效,与主模型配置(llm-pi-ai)完全独立;provider/模型管理复用 dsh 自带 Models 页。
• 热加载 —— settings.yaml 的 vision-bridge: 分节改动即时生效,无需重启。

工作原理

vision_read(file_path)
  ├─ 校验扩展名 / 附件服务 / 图片大小上限(同 read_image)
  ├─ 当前路由模型声明 image?
  │    ├─ 是 → 返回图片本身(native,同内置 read_image)
  │    └─ 否 → visionRoutes 逐个探测(已注册 + 可解析 + 声明 image)
  │           └─ 视觉模型收图,返回转写文本(translated)

转写路径只向会话注入文本,因此无视觉模型的后续请求不会被 pi-ai 的模态闸门卡死。

安装

方式一:直接安装

dsh plugin --profile web add dsh-eyes

方式二:从源码安装(开发/调试)

git clone https://github.com/JY626/dsh-eyes.git
cd dsh-eyes
pnpm install                       # 安装插件依赖
dsh plugin --profile web add .     # 安装到 profile

然后重启 web 应用并刷新页面,设置侧边栏即出现"视觉模型"页。验证:dsh --profile web --dump-config 应看到 vision-bridge 行。

卸载:dsh plugin --profile web remove dsh-eyes

配置

方式一:视觉模型页(推荐)

设置 → 视觉模型:勾选已注册路由中的模型 → 保存。选择写入 vision-bridge.visionRoutes,与 Models 页互不影响;留空则自动发现所有声明 image 输入的模型。

方式二:settings.yaml

vision-bridge:
  visionRoutes: []                          # 留空 = 自动发现
  admitPastedImages: true                   # GUI 粘贴图片转写开关
  visionPrompt: "You are an image recognition assistant. ..."
  maxTokens: 2048
  maxOutputChars: 16000
  temperature: 0.1

视觉模型必须逐模型声明图像输入(在 Models 页的 llm-pi-ai 分节或手写):

llm-pi-ai:
  providers:
    opencode-go:
      apiKeyEnv: OPENCODE_GO_API_KEY
      models:
        - id: minimax-m3
          name: MiniMax-M3
          contextWindow: 1000000
          maxTokens: 131072
          input: [text, image]    # ← 关键:声明图像输入

⚠️ catalog 外的模型有协议门槛:需声明 api + baseURL(见"独立视觉路由"示例),否则 llm-pi-ai 校验失败。

完整配置项

| 字段 | 默认 | 说明 | |---|---|---| | toolName | vision_read | 注册的工具名 | | visionRoutes | [](自动发现) | 有序视觉路由备选,逐个探测取第一个可用 | | visionPrompt | 见 cordis.patch.yml | 发给视觉模型的 system prompt | | maxTokens | 2048 | 视觉模型输出 token 上限 | | maxOutputChars | 16000 | 返回文本字符上限(超出截断加注) | | temperature | 0.1 | 视觉模型采样温度 | | admitPastedImages | true | 无视觉模型也能粘贴图片(发送时转写) |

排障

| 现象 | 原因与修法 | |---|---| | 粘贴图片发送失败("当前模型不支持图片") | 插件未生效:确认 profile 已加载(见安装)并重启 web | | 工具报 "no usable vision route" | 没有可用视觉模型:检查模型条目是否声明 input: [text, image],路由是否已注册 | | 报 UNSUPPORTED_CONTENT | 视觉模型未声明 image 输入 | | 报 NO_ADAPTER / UNKNOWN_MODEL | 路由未注册 / 模型 id 不在 catalog 中 | | 报 IMAGE_TYPE_MISMATCH | 扩展名与实际图片格式不符 |

开发

pnpm check    # 语法检查(host / client / format)
pnpm test     # 纯函数测试(node:test)

lib/index.js      # 插件入口:工具注册 + 桥接逻辑 + 准入覆写
lib/client.js     # client bundle:设置页"视觉模型"(__ModuleLoader__.load 格式)
lib/format.js     # 零依赖纯函数
test/             # node:test 测试

许可证

MIT