Favio8 / dsh-plugin-deepeye

DeepEye Vision for DSH

为 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 = "<你的智谱 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