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
