dsh-plugin-vision：DeepSeek Harness 视觉辅助插件

前言¶

DeepSeek Harness (DSH) 采用插件化架构，目前官方 API 仅提供文本模型，缺乏视觉能力。dsh-plugin-vision 通过注册 vision_describe 工具，允许主模型调用任意 OpenAI 兼容的视觉 API 来描述图片。这解决了在没有原生视觉模型的主模型上处理图片的需求。

安装¶

使用官方提供的安装脚本，将插件挂载到对应的 Profile。

git clone https://github.com/MoneShadow/dsh-plugin-vision && cd dsh-plugin-vision
./install.sh                 # 安装到 web profile
./install.sh headless        # 安装到其他 profile（如 headless 模式）

脚本会自动探测 DSH 安装位置，将插件实体复制到全局依赖树，并建立软链。

注意：不要使用 dsh plugin add file: 命令安装本插件。这会导致向 profile 注入 @deepseek-ai/dsh-tools 依赖副本，与全局依赖树冲突，引发工具调用崩溃（Cannot read properties of undefined (reading 'prepare')）。请务必使用上述安装脚本。

配置¶

编辑 ~/.dsh/settings.yaml，在文件末尾添加或修改 vision: 段。

vision:
  enabled: true
  autoPath: true                        # 桌面端粘贴图片自动转路径（DSH Desktop 功能）
  baseURL: https://api.openai.com/v1   # 任意 OpenAI 兼容服务地址
  apiKey: ""                            # 视觉模型 API 密钥
  model: gpt-4o-mini                    # 视觉模型名称（如 qwen-vl-max）
  timeoutMs: 60000
  cache: true                           # 启用答案缓存
  cacheTtlSeconds: 3600                 # 缓存有效期（秒）
  cacheMaxEntries: 200                  # 缓存条目上限（LRU 淘汰）

保存后，引擎会自动监视文件变化并热更新配置，无需重启。

核心功能与用法¶

1. 工具注册与调用¶

插件运行在引擎侧，会向全局 Agent 注册 vision_describe 工具。
主模型在对话中可以直接调用该工具，传入图片参数：

vision_describe(image, prompt?)

支持的图片源包括：
* 本地文件路径
* file:// 协议路径
* http(s) URL

2. 答案缓存¶

为了减少 API 消耗，插件内置了答案缓存机制。
* 缓存键：图片内容哈希 + 接口地址 + 模型 + 提问内容。
* 行为：同一张图、同一提问再次调用时，直接返回缓存结果，不重复请求视觉 API。
* 错误处理：请求失败的描述不会缓存。
* 策略：基于 TTL（有效期）和 LRU（最少使用）淘汰策略。

3. 配置开关¶

当 enabled: false 时，vision_describe 工具依然会被注册，但会返回明确的提示信息。主模型在接收到提示后，通常会引导用户开启该功能。

4. 密钥安全¶

API 密钥以 secret 角色存储，在官方设置界面中不可见（write-only），避免明文泄露。

与 DSH Desktop 的配合¶

注意：“粘贴图片自动转路径”功能由 DSH Desktop 实现，并非本插件的一部分。

DSH 插件运行在引擎（dsh 进程）侧，无法感知浏览器的粘贴事件。DSH Desktop 通过向官方 UI iframe 注入补丁，监听粘贴操作，将图片存盘并自动插入 [图片] /真实路径，最终由主模型调用本插件的 vision_describe 工具查看。

配置中的 autoPath 字段由 DSH Desktop 读取并控制该行为。若未安装 DSH Desktop，需手动将图片路径/URL 传给工具。

注意事项与依赖¶

依赖项：本插件依赖 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery（均为 MIT 许可证）。
官方 API 限制：DeepSeek 官方 API 目前无视觉模型，必须接第三方 OpenAI 兼容服务（如通义千问、智谱、SiliconFlow 等）。
故障排查：如果安装后任何工具调用（包括 bash）导致引擎崩溃，请检查是否误用了 dsh plugin add file: 安装，并按照安装脚本的说明重新安装或卸载重装。