视觉增强插件Favio8/dsh-plugin-deepeye

面向 DSH 的 DeepEye Vision

为 DeepSeek Harness 提供视觉能力的原生 Cordis 插件。

让纯文本模型获得“眼睛”：图片描述、OCR 文字提取、视觉问答、UI 布局分析、剪贴板截图分析，以及粘贴图片自动翻译（在纯文本模型会话里直接粘贴图片也能发）。

特性

- 原生集成 — 直接注册到 ctx.tools，无 MCP 中间层开销
- 多后端 — 支持 OpenAI (GPT-4o)、Google Gemini、自定义 OpenAI-compatible 端点
- 智能预处理 — 自动缩放过大图片、转换 JPEG 以节省 token
- 结果缓存 — LRU 缓存减少重复 API 调用（含 TTL，键覆盖后端/模型，切换后端不会误命中）
- 友好错误处理 — 鉴权失败/限流/超时给出可执行的修复建议，不再回显原始 API 报错
- 非阻塞剪贴板读取 — vision_clipboard 异步读取系统剪贴板（不卡事件循环、可取消），且能区分「剪贴板是文本」「没有内容」并给出引导
- System Prompt — 自动注入提示段落，让模型知道何时使用视觉能力
- 粘贴图片兼容 — 纯文本模型（如 DeepSeek）会话中直接粘贴图片，自动翻译成文字后交给模型（见下文 pasteCompat）

安装

本插件是一个标准 dsh bundle（声明了 dsh.bundle.patch），通过 dsh 的 profile 插件机制安装：

发布后（npm 安装）
dsh plugin --profile web add dsh-plugin-deepeye

本地开发时（从插件源码目录的上一级执行）
dsh plugin --profile web add ./dsh-plugin-deepeye

安装时 dsh 会：
1. 首次使用自动初始化 profile（含 @deepseek-ai/dsh-base）
2. 用 pnpm 把本包链接进 profile 目录
3. 因本包声明了 dsh.bundle，自动追加到 dsh.profile.bundles 层叠

验证与启动：

dsh --profile web --dump-config   # 确认出现 dsh-plugin-deepeye 层
dsh web                           # web 是 --profile web 的别名

配置

API Key 解析优先级

插件支持多层 API Key 解析，用户可以选择最方便的方式：

1. cordis.yml 显式配置 — config.apiKey: !!js process.env.XXX
2. 自动环境变量回退 — 根据 provider 自动匹配对应环境变量
3. 通用变量 — DEEPEYE_API_KEY（适用于所有 provider）

| provider | 自动回退的环境变量 |
|---|---|
| openai | OPENAI_API_KEY |
| gemini | GEMINI_API_KEY |
| custom | DEEPEYE_API_KEY |

最简配置：只需设置环境变量，无需在 cordis.yml 中显式写 apiKey：

.env 或系统环境变量
export OPENAI_API_KEY=sk-xxx

cordis.yml - 无需 apiKey 字段，自动从 OPENAI_API_KEY 读取
- id: deepeye-vision
name: 'dsh-plugin-deepeye'
config:
provider: openai

使用 OpenAI

- id: deepeye-vision
name: 'dsh-plugin-deepeye'
config:
provider: openai
apiKey: !!js process.env.OPENAI_API_KEY  # 可省略，自动回退
model: gpt-4o                    # 可选，默认 gpt-4o
baseUrl: ''                    # 可选，代理或 Azure 端点

使用 Gemini

- id: deepeye-vision
name: 'dsh-plugin-deepeye'
config:
provider: gemini
model: gemini-2.0-flash          # 可选，默认 gemini-2.0-flash

使用智谱 GLM-4V（免费）

智谱的 glm-4v-flash 是免费视觉模型，走 OpenAI-compatible 端点，对应 provider: custom。

把 examples/zhipu-glm4v.cordis.patch.yml 的内容合并到 profile 的用户 patch 层（%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml，Linux/macOS 为 ~/.dsh/profiles/web/cordis.patch.yml）：

- id: deepeye-vision
config:
provider: custom
baseUrl: https://open.bigmodel.cn/api/paas/v4
model: glm-4v-flash
maxTokens: 1024

API Key 通过环境变量提供（custom provider 自动读取 DEEPEYE_API_KEY）：

PowerShell
$env:DEEPEYE_API_KEY = ""

使用自定义端点

适用于 vLLM、Ollama、LM Studio 等 OpenAI-compatible 服务：

- id: deepeye-vision
name: 'dsh-plugin-deepeye'
config:
provider: custom
baseUrl: http://localhost:8080/v1   # 必填：端点地址
model: qwen-vl-plus                 # 必填：模型名
apiKey: !!js process.env.DEEPEYE_API_KEY  # 可省略

完整配置参考

- id: deepeye-vision
name: 'dsh-plugin-deepeye'
config:
provider: openai              # 'openai' | 'gemini' | 'custom'
apiKey: ''                    # 留空则自动读 env（见上表）
baseUrl: ''                   # custom 端点或代理地址
model: ''                     # 留空使用 provider 默认模型
cacheEnabled: true            # 结果缓存开关
cacheMaxSize: 200             # 缓存最大条目
cacheTtlSeconds: 86400        # 缓存条目有效期（秒，0 表示不过期）
maxImageDimension: 1536     # 图片最大尺寸（超过自动缩放）
jpegQuality: 85               # JPEG 压缩质量
maxTokens: 4096               # OpenAI-compatible 视觉模型最大输出 token
requestTimeout: 30000         # 单次请求超时（毫秒）
maxRetries: 2                 # 瞬时失败（429/5xx/网络错误）重试次数
retryDelay: 1000              # 首次重试前的基础延迟（毫秒，指数退避）
maxImageDownloadBytes: 20971520  # URL 图片最大下载字节数
pasteCompat: auto             # 'off' | 'auto' | 'force'，粘贴图片兼容模式

缓存键包含「provider + baseUrl + 图片 + prompt + model」：切换后端或模型不会误命中旧缓存；条目按 cacheTtlSeconds 过期。

粘贴图片兼容（pasteCompat）

DSH 前端原生支持把图片粘贴/拖拽进输入框（以附件形式存储，消息里是一个 image 引用块）。但有两道关卡会让带图消息发不出去：

1. 宿主网关准入：dsh-host-apiproxy 在发送时校验模型能力——DeepSeek 等纯文本模型被显式声明为不支持图片（MODEL_DOES_NOT_SUPPORT_IMAGES），前端直接提示"当前模型不支持图片"，请求根本不会发出
2. 适配器拒绝：即使消息提交成功，dsh-llm-deepseek 适配器也会拒绝 image 块（UNSUPPORTED_CONTENT）

本插件通过两层机制解决：

| 层 | 机制 |
|---|---|
| 准入 | 包装 ctx.llm.resolveModelInfo：纯文本模型的 inputModalities 报告为"未知"而非"明确不支持"，通过网关准入，图片消息得以进入会话 |
| 翻译 | llm/stream 瀑布钩子：把 image 附件交给视觉后端翻译成文字，替换后重放请求——模型以文本形式"看到"图片 |

| 模式 | 行为 |
|---|---|
| off | 不介入，粘贴图片行为与未安装插件时一致 |
| auto（默认） | 仅当目标模型不支持图片输入时自动翻译；支持图片的模型（如 pi-ai）原样放行 |
| force | 无论模型是否支持图片，一律翻译后重放 |

- 翻译用的视觉后端与工具共用同一套配置（provider / apiKey / model / 缓存）
- 视觉翻译失败时自动降级为友好提示文本，不会让会话报错
- 仅改写含 image 块的请求，重放请求不含图片，不会重复改写
- resolveModelInfo 包装有防重复标记（HMR 安全），且不改动模型路由与请求内容
- 已实测：DeepSeek deepseek-v4-flash + 智谱 glm-4v-flash，粘贴截图后模型正常收到图片的文字翻译

启用方式

安装为 bundle 后（见上文「安装」），插件默认以 provider: openai 配置随 profile 自动加载。需要换后端或调整参数时，在 profile 的用户 patch 层按 id 定向覆盖其 config：

%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml
- id: deepeye-vision
config:
provider: openai
apiKey: !!js process.env.OPENAI_API_KEY

开发期也可以不落盘，直接用 --patch 临时叠加：

dsh web --patch ./examples/zhipu-glm4v.cordis.patch.yml

提供的工具

| 工具名 | 功能 | 必填参数 |
|---|---|---|
| vision_describe | 详细描述图片内容 | image_source |
| vision_ocr | 提取图片文字（OCR） | image_source |
| vision_ask | 根据图片回答问题 | image_source, question |
| vision_layout | UI 布局结构化分析（JSON） | image_source |
| vision_clipboard | 分析剪贴板截图 | 无（自动读取剪贴板） |

图片来源格式

所有 image_source 参数支持四种格式：
- 本地路径: /path/to/image.png 或相对路径
- file:// URL: file:///path/to/image.png
- HTTP(S) URL: https://example.com/screenshot.png
- Data URI: data:image/png;base64,iVBOR...

环境变量
复制 .env.example 为 .env 并填入你的 key：

| 变量 | 用途 | 对应 provider |
|---|---|---|
| OPENAI_API_KEY | OpenAI API Key | openai |
| GEMINI_API_KEY | Gemini API Key | gemini |
| DEEPEYE_API_KEY | 通用 Key / 自定义端点 | custom / 所有 |

开发

cd dsh-plugin-deepeye
pnpm install        # 首次需安装依赖（含 sharp 原生库）
pnpm run typecheck  # 类型检查
pnpm test           # 单元测试（vitest）
pnpm run build      # 构建 lib/（tsdown）

pnpm install 会通过 prepare 自动构建 lib/。开发期修改 src/ 后需
重新 pnpm run build 并重启 dsh（或热重载）才会生效；
若 sharp 未安装，插件仍可运行，但图片不会缩放/转 JPEG（token 开销更大），
启动日志会给出一次性警告。

架构

src/
├── index.ts          # Cordis 插件入口 (name/inject/Config/apply)
├── config.ts         # 配置 schema (schemastery)
├── engine.ts         # VisionEngine: 统一执行管道
├── cache.ts          # LRU 缓存
├── image-utils.ts    # 图片加载 + 预处理
├── errors.ts         # 错误分类与友好提示
├── http.ts           # 超时/重试/退避 HTTP 封装
├── layout.ts         # 布局 JSON 健壮提取
├── prompts.ts        # 默认提示词
├── paste-compat.ts   # 粘贴图片兼容：resolveModelInfo 能力包装（通过网关准入）+ llm/stream 瀑布钩子（图片→文字翻译重放）
└── vision/
├── base.ts       # VisionAdapter 接口
├── openai.ts     # OpenAI 适配器
├── gemini.ts     # Gemini 适配器
└── factory.ts    # 适配器工厂

License

MIT