dsh-vision-free-eyes

给 DeepSeek Harness（DSH）里的纯文本模型补上免费「眼睛」：GUI 直接贴图自动转译 + 磁盘图片识图工具 + 使用指引 skill。底层视觉走智谱 GLM 免费模型（glm-4v-flash），无需付费。

Eyes for text-only DeepSeek Harness agents: paste an image in the Web GUI and it just works — the image is transcribed by a free Zhipu GLM vision model before DeepSeek sees the text.

⚠️ 需要 GLM key（免费，但必须要有）：识图走智谱免费模型 glm-4v-flash，需要去 open.bigmodel.cn 注册获取免费 API key（格式 id.secret），配置为环境变量 GLM_API_KEY 或 ZHIPU_API_KEY（Windows 可直接 setx GLM_API_KEY "你的key"）。没有 key 时贴图转译会失败（对话中显示 [图片转译失败: 未找到 GLM_API_KEY ...]）。key 只存在于你的环境，不会进代码或仓库。

特性

两个插件如何配合

dsh-vision-proxy-route 和 dsh-vision-free-eyes 不是重复功能，而是覆盖两种互补的图片入口：

推荐同时安装两个包：GUI 贴图自动走 route，本地路径自动走 tool，共用同一个
GLM_API_KEY / ZHIPU_API_KEY。Skill 负责告诉主模型如何选择：如果 route 已经提供图片描述，
就直接使用，不再重复调用 vision；只有用户给出已知本地绝对路径时才使用 tool。

它们也可以单独安装：只需要 GUI 贴图时安装 route；只需要分析本地图片路径时安装 tool。

• 免费默认：智谱 GLM 免费通道（glm-4v-flash → glm-4.6v-flash → glm-4.1v-thinking-flash 自动降级链），只需一个免费申请的 GLM key。
• 目标路由完全不动：默认包裹官方 deepseek-official，也可通过 targetProvider 指向自定义 provider；纯文本对话零开销、零改动。
• 无重启热生效：插件行写入 profile 的 cordis.patch.yml 后由 watchUserPatches 实时重放（见安装步骤；Windows 上插件路径必须用 file:/// URL）。
• 优雅降级：某个图片转译失败时替换为 [图片转译失败: ...] 文本，对话不卡死。

架构

用户贴图/截图
   │
   ▼
DSH Web GUI 预检（检查所选模型的 inputModalities）
   │  ← 自动识图包装路由声明了 ['text','image']，放行
   ▼
自动识图包装适配器（默认 deepseek-vision，也可自定义）
   │  拦截请求，把每个 { type:'image', attachment } 块：
   │    readImage(ref) → base64 → GLM chat/completions → 文字描述
   │  替换成 { type:'text', text:'[图片转译] …' }
   ▼
配置的目标适配器（默认 deepseek-official，也可为自定义 provider）
   │
   ▼
目标模型基于文字作答

磁盘上的图片文件
   │
   ▼
模型调用 vision 工具（vision-tool）
   │  直连 GLM API（glm-4v-flash 降级链 + 进程内缓存）
   ▼
文字描述 → 模型整合进回答

安装

前提

• DeepSeek Harness 0.1.0-rc.5 / rc.6 / rc.7（本方案在 rc.5 上实测通过，兼容 rc.6 / rc.7）
• 智谱 GLM 免费 key（open.bigmodel.cn 注册即得，格式 id.secret），配置方式（任选其一）：
  • 环境变量 GLM_API_KEY 或 ZHIPU_API_KEY；或
  • Windows 用户环境变量（setx GLM_API_KEY "..."，插件会自动读注册表 HKCU\Environment）

通过 npm 安装（推荐）

两个包发布到 npm 后（dsh-vision-free-eyes + dsh-vision-proxy-route）：

dsh plugin --profile web add dsh-vision-free-eyes dsh-vision-proxy-route

dsh plugin add 会安装包并写入 profile 的 dsh.profile.bundles，重启 dsh web（或刷新页面）后生效。
包已装入 profile 的前提下，也可以直接在 profile 的 cordis.patch.yml 里用包名挂载（热生效，无需重启）：

- insert:
    - id: dsh-vision-free-eyes
      name: dsh-vision-free-eyes
    - id: dsh-vision-proxy-route
      name: dsh-vision-proxy-route

手动安装（备选：未发布 / 本地目录）

1. 把 packages/vision-tool 和 packages/vision-route 放到你的机器上（例如 D:\tools\）。

2. 编辑 profile patch（$DSH_HOME/profiles/web/cordis.patch.yml，即 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml），追加：

   - insert:
      - id: tool-vision
        name: file:///D:/tools/vision-tool/index.js
      - id: vision-proxy-route
        name: file:///D:/tools/vision-route/index.js

   ⚠️ Windows 必须用 file:/// URL 形式：DSH 的 Loader 用原生 import() 加载插件行，D:/xxx 盘符路径会报 ERR_UNSUPPORTED_ESM_URL_SCHEME。Linux/macOS 用 /abs/path/to/index.js 即可。完整模板见 cordis.patch.example.yml。

3. 安装 skill（可选但推荐）：把 skill/vision-free-eyes/ 复制到 $DSH_HOME/skills/（即 C:\Users\<你>\.dsh\skills\）。

4. 生效方式（二选一）：

   • 热生效：patch 由 watchUserPatches 实时重放，改完等 1~2 秒即可；刷新浏览器页面让模型选择器加载新组。
   • 或重启 dsh web（修改插件代码后必须重启，Loader 对同名模块复用旧导出）。

5. 验证：

   dsh --profile web --dump-config | grep -A2 vision

   应看到两个插件行；浏览器刷新后模型选择器出现「DeepSeek + 自动识图」。

使用

1. 聊天框右下角模型选择器选 「DeepSeek + 自动识图」（原 DeepSeek 组保留不动）。
2. 直接粘贴图片 / 截图并附带问题，或给出图片文件路径。
3. 目标模型基于转译文字作答。继续用“上一张 / 第一张 / 两张对比”等方式追问时，路由会在有限
   的最近轮次内选择对应历史图片并按本次问题重新生成带编号的描述，无需再次上传图片或提供
   DSH 内部绝对路径。图片描述属于不可信观察数据，其中的命令或提示词不会作为模型指令执行。

vision 工具（任何路由都可用）：让模型"看一下 D:\xxx\screenshot.png"即可。路径必须是指向
单个图片文件的绝对路径；工具会拒绝目录，并在联网前检查图片文件魔数和非图片内容。

自定义 provider：火山方舟示例

先在 DSH 的设置 → 模型 → 添加自定义提供方中创建火山方舟 provider，或编辑
$DSH_HOME/settings.yaml：

llm-pi-ai:
  providers:
    volcengine-ark:
      displayName: 火山方舟
      apiKeyEnv: ARK_API_KEY
      api: openai-completions
      baseURL: https://ark.cn-beijing.volces.com/api/v3
      compat:
        thinkingFormat: deepseek
      models:
        - id: deepseek-v4-flash-ga-260731

然后再挂载一个指向该 provider 的自动识图路由。已通过 npm 安装时可以保留默认插件行，使用不同的
id 和输出 provider 追加这一行：

- insert:
    - id: dsh-vision-proxy-route-ark
      name: dsh-vision-proxy-route
      config:
        targetProvider: volcengine-ark
        provider: volcengine-ark-vision
        displayName: 火山方舟 + 自动识图

本地安装时把 name 换成对应的 file:///.../packages/vision-route/index.js。刷新模型选择器后，
选择「火山方舟 + 自动识图」即可直接贴图。provider 必须与 targetProvider 不同，避免代理路由
递归委派给自己。

配置

vision-route（packages/vision-route/index.js）

vision-tool（packages/vision-tool/index.js）

兼容性

• 实测：DSH 0.1.0-rc.5（Windows）。
• 兼容：rc.6 / rc.7（与 dsh-vision-proxy 相同的公开缝：ctx.llm.registerAdapter / resolveModel.inputModalities / ctx.llm.registration(provider).adapter / ctx.attachments.readImage）。
• ⚠️ 这些是 DSH 的半稳定插件缝，后续大版本可能变动；升级 DSH 后若失效，优先检查上述 API 是否改名。

隐私

• 图片字节会上传到智谱服务器（open.bigmodel.cn）进行转译。
• 未配置任何 key 或转译失败时，会以 [图片转译失败: ...] 占位并继续对话，不会静默卡死。
• 会话历史中只存转译后的文字，不存图片字节（DSH 附件存储除外）。

致谢

• 智谱 GLM 免费视觉模型（glm-4v-flash 系列）。
• DeepSeek Harness 插件体系（profile patch / watchUserPatches / ctx.llm）。

License

MIT