dsh-omni-vision

> 本插件全由 DeepSeek v4 Flash（deepseek-v4-flash）编写。

让 Agent 自己"看见"文字与图形的 DSH 插件，全程本地、不依赖视觉模型：

• eyes_render — 在 Web GUI 对话流里渲染画布（文字、线条、矩形、圆形、椭圆），PNG 落盘到工作区 renders/（读完即焚），并一式两份另存永久副本到 pics/。
• eyes_paste — 让用户把剪贴板图片（截图/照片）直接 Ctrl+V 粘贴或拖进页面：浏览器捕获图片、归一化为 PNG 存到工作区，供本地 OCR/像素分析读取。只写 renders/（读完即焚，不留 pics/ 永久副本）。全本地读图路径（不限流、离线），独立于 DSH 原生发图链路（DSH 输入框本身支持图片粘贴/拖放，但发图需要选择支持图片的模型，见"限制"）。
• eyes_ocr — 用 Windows 自带 OCR（Windows.Media.Ocr，完全离线）把 PNG 里的文字读回成文本。这是 Agent "看见文字"的途径：DeepSeek 是纯文本模型，但识别出的文本可以原样喂回给模型引用。
• eyes_analyze — 把 PNG 解码成像素数据（N×N 颜色网格、主色占比、内容包围盒）。这是 Agent "看见图形/颜色"的途径：无需视觉模型，图形以结构化数据呈现。

全程本地闭环：浏览器 canvas → 本机 HTTP → 本机磁盘 → Windows OCR / 像素分析。所有下载均按需、不盲目下载（详见"下载策略"）；出网环节仅限：模型推理本身，以及（可选）首次渲染 Mermaid 图且本地无副本时按需获取一次 Mermaid 库。

平台要求

仅支持 Windows。 eyes_ocr 通过 PowerShell 调用 Windows 自带 OCR 引擎（Windows.Media.Ocr，完全离线）；eyes_render / eyes_paste / eyes_analyze 本身不依赖 Windows 特性，但整个插件在非 Windows 上无法提供"读字"能力，按 Windows 平台维护。

下载策略：全部按需，不盲目下载

安装与启动阶段零下载；所有获取均按需发生：

• 插件本体：本地 link: / file: 安装，无任何下载。
• Mermaid 库：唯一可能发生的运行时下载——仅在首次实际渲染 Mermaid 图且本地无副本时，浏览器按需从 CDN 获取一次（成功后缓存）；不渲染 Mermaid 就完全不会下载。
• 其余全部本地：渲染、OCR、像素分析、图片接收，均不产生任何网络下载。

工作原理

模型 ──eyes_render──▶ 服务端工具 execute
  │                      │ 按 callId 注册"待渲染"承诺（15s 超时）
  │                      ▼
  │          会话事件流（tool/call 事件实时推送浏览器）
  │                      ▼
  │          浏览器 keyed tool.call.toolview 卡片
  │                      │ 解析命令 → canvas 绘制 → toBlob → PNG base64
  │                      ▼
  │          POST /eyes/render（同源校验，按 callId 匹配）
  │                      ▼
  │          工具恢复：写 <workspace>/renders/eyes-<callId>.png（读完即焚）
  │                    + 永久副本 <workspace>/pics/eyes-<callId>.png
  │                    + attachments.saveImage（内容寻址存储）
  │                      ▼
  │          工具结果 = 文本信封（路径/尺寸/命令数/OCR 文本）
  └──────────────────────（模型声明支持图片时，结果额外带 image 图片块）

模型 "看见"文字：eyes_render（或任意 PNG）→ eyes_ocr ──▶ 行文本
模型 "看见"图形：PNG → eyes_analyze ──▶ 颜色网格 / 主色 / 内容包围盒

用户图片进来：模型 ──eyes_paste──▶ 粘贴卡片（Ctrl+V 提示）
  │                      │ 浏览器捕获剪贴板图片 → canvas → PNG base64
  │                      ▼
  │          POST /eyes/paste（同源校验，按 callId 匹配）
  │                      ▼
  │          写 <workspace>/renders/paste-<callId>.png（读完即焚，无永久副本）
  └────────── 之后 eyes_ocr / eyes_analyze 读取

• 图片能力探测 + 降级：执行时探测当前模型路由是否声明 image 输入（llm.resolveModelInfo().inputModalities）。支持 → 结果带 {type:'image', attachment} 图片块，模型下一轮起能看见；不支持（如 DeepSeek API，适配器声明 ["text"] 且遇图片块抛 UNSUPPORTED_CONTENT）→ 只返回文本信封，会话绝不报错。画布仍渲染在 GUI 里，用户可见。
• 本地感知（文字）：eyes_ocr 通过 PowerShell 5.1 调用 Windows 自带 OCR 引擎，离线识别，支持已安装的语言包（如 zh-Hans-CN 中文简体）。识别结果按行返回文本。
• 本地感知（图形）：eyes_analyze 自带纯 Node PNG 解码器（zlib + 反滤波，支持 8-bit RGB/RGBA 非交错 PNG），输出网格平均色、主色直方图、内容包围盒。
• 渲染匹配：客户端把工具调用的 callId 随 PNG 一起 POST 回来，服务端按 exec.callId 匹配待渲染条目，天然支持并行调用与多标签页（先到先得，其余 404 被客户端静默忽略）。
• 重放：刷新页面后，历史会话里的卡片从工具参数（block.call.argsRaw）重放绘制，不再上传。
• 读完即焚 + 一式两份：eyes_render 每次产出都写两份——renders/ 下的临时副本在 eyes_ocr / eyes_analyze 读取成功后自动删除（返回结果带 fileDeleted 标记，renders/ 不会越积越多）；pics/ 下的永久副本（返回结果带 keptPath）不会被删除，用户随时可以打开查看。eyes_paste 只写 renders/（读完即焚），不保留 pics/ 永久副本。用户放在其他目录的图片（截图、照片等）绝不会被删除。

安装

cd <你的工作区>
dsh plugin --profile web add link:<你的工作区>\dsh-omni-vision
# 若链接失败：dsh plugin --profile web add file:<你的工作区>\dsh-omni-vision

安装后校验 %USERPROFILE%\.dsh\profiles\web\package.json：dependencies 与 dsh.profile.bundles 都应包含 dsh-omni-vision。

可选：npm i mermaid@11 仅在需要全离线渲染 Mermaid 图时安装；不装也能用——首次实际渲染时浏览器会按需从 CDN 加载（成功后缓存）。安装/启动阶段不会盲目下载任何东西。

必须重启 web 服务（生产启动时插件列表与客户端 bundle 在启动时固化）：

1. 在运行 dsh web 的窗口按 Ctrl+C（或结束监听 3080 端口的进程）。 2. 重新运行 start-dsh.ps1（或 npx --yes @deepseek-ai/dsh web）。 3. 浏览器硬刷新（Ctrl+Shift+R）。

使用

eyes_render —— 画

参数：width/height（64–2048）、background（CSS 颜色）、title、description、commands（数组）、mermaid（字符串，可选）、ocr（布尔，渲染后顺带本地 OCR，默认 false）。

Mermaid 连线图：传 mermaid 参数（Mermaid 源码字符串，如 graph LR\n A[start] --> B[process] --> C[end]）即可让浏览器渲染出流程图/时序图等，无需手工计算坐标；mermaid 存在时优先于 commands。支持 flowchart / sequenceDiagram / classDiagram / stateDiagram 等 Mermaid 语法。渲染结果走同一套 PNG 存档（一式两份）+ 可选 OCR（可把节点文字读回给模型）。按需加载（本插件所有下载均按需，见"下载策略"）：只有实际传 mermaid 参数渲染时才加载，优先用本地副本（在插件目录 npm i mermaid@11 后全离线可用），缺失时才回退 CDN（首次需浏览器联网，成功后浏览器缓存）。加载或语法失败时工具返回明确错误。

落盘 PNG 的像素尺寸与 width/height 完全一致（不做设备像素比缩放），命令坐标与 PNG 像素一一对应——eyes_analyze 看到的网格坐标、contentBox 都与命令里的 x/y 直接可比。

text 的 y 是首行字形顶部的坐标：绘制时用 measureText 量出字形顶部相对字母基线的距离（actualBoundingBoxAscent），在 y + ascent 处画基线，字形顶精确落在 y 上（跨引擎一致，不随字体/字号/浏览器解释差异偏下），中文、拉丁文混排时顶部对齐一致。

PNG 一式两份：renders/eyes-<callId>.png（ocr:true 且读回成功后自动删除，读完即焚）+ pics/eyes-<callId>.png（永久保留，结果里的 keptPath）。

eyes_ocr —— 读文字

参数：path（PNG 绝对路径，如 eyes_render 返回的 path）。返回 ok、text（全文）、lines（逐行）、language，以及 fileDeleted（renders/ 下的源文件读取后自动删除）。

eyes_analyze —— 看图形

参数：path（PNG 绝对路径）、grid（采样网格 N×N，2–32，默认 8）、maxColors（主色数量，1–16，默认 6）。返回 gridCells（网格平均色）、dominantColors（主色及占比）、contentBox（内容包围盒），以及 fileDeleted（同上，读完即焚）。

eyes_paste —— 收图

参数：hint（可选，显示在粘贴卡片上的说明）。调用后 GUI 出现粘贴卡片，用户选择一张图片复制后ctrl+v或直接拖到浏览器界面（批量读取时，可把多张图片副本直接放入 renders/ 文件夹并告诉所用AI），浏览器捕获并保存为 <workspace>/renders/paste-<callId>.png（读完即焚，无 pics/ 永久副本读完即焚；未读取的文件会留在 renders/ 中，可手动清理）。返回 path、width、height、bytes、fileSaved、fileError。

示例

> 用 eyes_paste 让用户粘贴一张截图，然后用 eyes_ocr 读出里面的文字并复述给我

> 用 eyes_render 画一张 800x400 的画布，写上文字"Hello 世界 123"，设 ocr:true，然后告诉我你看到了什么

> 用 eyes_render 画一张 900x500 的 Mermaid 流程图：graph TD\n A[登录] --> B{校验}\n B -->|成功| C[进入主页]\n B -->|失败| D[提示错误]，设 ocr:true 读回节点文字

> eyes_ocr 读取 <workspace>\renders\eyes-xxx.png，把识别出的文字逐行复述给我

> eyes_analyze 分析 <workspace>\renders\eyes-xxx.png，网格 12，然后描述画面布局和主要颜色

限制

• 仅支持 Windows：eyes_ocr 依赖 Windows 自带 OCR（Windows.Media.Ocr + PowerShell 5.1），其他平台无法读字；渲染/粘贴/像素分析不依赖 Windows，但插件整体按 Windows 平台维护。
• 需要浏览器 GUI 打开：eyes_render / eyes_paste 会等浏览器回传——普通渲染 15 秒、Mermaid 首次加载放宽到 45 秒、eyes_paste 等人粘贴放宽到 60 秒；GUI 未开时返回明确错误。无服务端渲染兜底。
• Mermaid 依赖（按需）：本插件所有下载均按需（见"下载策略"）——Mermaid 仅在实际渲染时才加载，优先取宿主 /eyes/mermaid.min.js（在插件目录 npm i mermaid@11 后提供，全离线），否则回退 jsDelivr CDN（仅首次需浏览器联网，成功后浏览器缓存）；不渲染就完全不会下载。渲染与语法错误会作为工具报错返回。
• OCR 效果：依赖 Windows 自带语言包（需已安装对应语言包，如 zh-Hans-CN）；Windows.Media.Ocr 对中英混排会在中文字符间插入空格，效果一般但可读；纯图形内容识别为空属正常。
• OCR 路径：WinRT StorageFile 要求反斜杠路径，脚本已自动把 / 规范化为 \。
• eyes_analyze 仅支持 8-bit RGB/RGBA 非交错 PNG（覆盖本插件的渲染输出与常见截图）；其他变体返回明确错误。
• 无 attachments 服务时不注册工具（与 read_image 相同门槛）。
• DSH 输入框原生支持图片（粘贴/拖放，"图片拖动到此处即可添加，最多 20 张/20MB"，UI 在 dsh-client-ui-conversation）；发图被拒是因为当前 DeepSeek 路由是纯文本（错误码 MODEL_DOES_NOT_SUPPORT_IMAGES，提示"当前模型不支持图片"）——切换到 dsh-vision-router 的「自动识图」模型即可原生发图。eyes_paste 是全本地读图路径（不依赖云/不限流），适合 OCR/像素细看用户图。

开发

• 服务端半区：lib/index.js（纯 ESM，无构建）、lib/png.js（PNG 解码+分析）、lib/ocr.ps1（Windows OCR 封装）。
• 客户端半区：client/client.js（手写 window.__ModuleLoader__.load factory bundle，无构建；loader 表提供 react）。
• 改动后需重启 dsh web 才生效（生产启动无 HMR watcher）。