@qizhen2021/dsh-plugin-vision：DeepSeek Harness 的视觉分析工具

前言¶

DeepSeek Harness (DSH) 采用“一切皆插件”的架构。纯文本模型（例如 deepseek-v4-flash）无法直接声明 image 输入，导致无法直接处理视觉任务。@qizhen2021/dsh-plugin-vision 插件注册了一个 see 工具。它对任意图片输出纯文本的三通道分析：离线 OCR（带坐标）、ASCII 布局图、以及视觉模型（VLM）的语义描述。这使得任何模型（包括纯文本模型）都能通过该工具“看”图。

核心功能¶

该插件提供三个处理通道：

1. OCR（离线）：使用 macOS Vision 框架，支持自动语言检测。输出格式为 x y w h\|text，坐标为归一化百分比 ×100，Y 轴原点在左下，已按行排序。
2. ASCII 布局图：使用 PIL 生成灰度图，转换为 88 列宽的字符画，梯度为 ' .:-=+*#%@'。纯文本模型可直接“看”布局。
3. 语义描述：通过 opencode.ai 的 mimo-v2.5 模型（默认）进行结构化报告输出。支持将 OCR 识别结果作为 ground truth 注入，保证字符串逐字准确。

安装与启用¶

DSH 的 GUI 插件清单页是只读的，不支持本地安装。需通过 Profile Bundles 方式安装。

1. 安装包：

    cd ~/.dsh/profiles/web && pnpm add @qizhen2021/dsh-plugin-vision

2. 修改 ~/.dsh/profiles/web/package.json，在 dsh.profile.bundles 数组中追加：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "@deepseek-ai/dsh-base",
            "@deepseek-ai/dsh-web-app",
            "@qizhen2021/dsh-plugin-vision"   // ← 追加这一行
          ]
        }
      }
    }

3. 重启 dsh web 使插件生效。

配置¶

插件支持多种配置项，可在 ~/.dsh/profiles/web/cordis.patch.yml 中覆盖默认值。

密钥采用双层读取策略：优先从 ctx.credentials 服务读取，未挂载时回退到 credentialPath YAML 直读。密钥不进代码、不进日志、不进 schema。

工具使用¶

调用 see 工具，参数如下：

• 参数：file_path（必填），ocr?/ascii?/vlm?（默认均为 true），model?（默认使用配置的 defaultModel）。
• 返回值：JSON 格式的结构化报告，包含三个通道的结果。任一通道失败不会导致整体失败，仅标记为 ok: false 并附带错误信息。
• 错误处理：
  • 文件相关错误返回 FsError。
  • 视觉处理错误返回 VisionError。

注意事项与限制¶

• 平台限制：OCR 功能仅支持 macOS（Vision 框架），ASCII 和 VLM 支持跨平台。
• 性能开销：swift 首次调用包含编译过程，耗时约 1-2 秒，超时设置为 90s。
• 无截图模式：当前版本不支持截图功能。
• 密钥安全：密钥处理完全在进程内进行，不暴露在代码或日志中。
• 图像处理：大图需通过 prep.py 缩至最长边 ≤1600，否则可能导致网关或内存问题。