前言¶
在 DeepSeek Harness（DSH）里用纯文本模型处理图片，常见做法是手动 OCR 或切到多模态模型。前者步骤多、证据零散；后者依赖外部视觉 API，成本和隐私边界也不好控。
picturereader 是维护者 jing-hy 发布的 DSH 插件（GitHub 约 33 stars，分类为模型推理）。它把「看图 / 读文档 / 修图」转成纯文本模型能消费的结构化证据：本地像素扫描、OCR、可选外部 VLM，以及视觉孪生 adapter 让文本模型在 DSH 里也能显示原生缩略图。当前版本为 v3.2.0，MIT 许可证。
这是什么¶
一句话定位：面向纯文本模型的像素级读图插件，默认纯本地运行，可选 PaddleOCR 与外部视觉 API。
它主要解决三件事：
- 把图片内容翻译成结构化文本证据（像素分析 + OCR + 可选 VLM 语义），并附带
image-reading读图方法论 skill。 - 通过视觉孪生 adapter，为勾选的文本模型生成「(视觉)」变体，解锁 DSH 原生缩略图与图片块粘贴，同时把 image block 拦截为文本路径，避免
UNSUPPORTED_CONTENT。 - 提供本地修图工具
image_edit（v3.2.0），纯 CPU 完成缩放、水印、合成等操作，图片不出本机。
版本兼容性（来自 README）：专门适配 dsh 0.1.1-rc.2、dsheac 5.1.0；同时兼容 DeepSeek Harness EAC 4.2.0 与 @deepseek-ai/dsh-client-ui-workspace rc.7。
核心功能¶
视觉孪生 adapter¶
对被勾选模型所属 provider 做 Proxy 原位包装：在 listModels / resolveModel 中声明 inputModalities: ['text','image']，名称加「(视觉)」后缀。DSH 因此认为模型支持图片，原生缩略图、图片块进会话、粘贴准入一并解锁。
stream 拦截会捕获请求里的 image block，导出到 ~/.dsh/picturereader-vision/images/，再替换成文本路径与本地工具引导后转发给原始 adapter。下游收到的是纯文本，不会触发 UNSUPPORTED_CONTENT。v3.1.0 起还拦截内置 read_image 工具返回的 image block，同样降级为文本引导。
三模式路由¶
路由逻辑集中在 routing.js 与 runtime.js，供各工具、视觉孪生 stream、vision_analyze 共用：
| 模式 | 默认像素扫描 | 默认 OCR | 默认外部 VLM | 特点 |
|---|---|---|---|---|
| 隐私（privacy） | 是 | 是 | 否（硬禁） | 图片字节不出本机，即使配置了 API 也不外呼 |
| 智能（smart，默认） | 是 | 按需 | 值得才调 | 先本地看图，文字走 OCR，复杂内容才外呼 VLM |
| 严谨（strict） | 是 | 是 | 是 | 多路证据交叉验证，可靠性优先 |
本地工具链¶
| 工具 | 作用 |
|---|---|
image_scan |
颜色网格、色块区域、纹理与结构分析；支持 focus / region 定向放大 |
image_ocr |
三引擎：windows（内置）、paddle（选装）、rapid（选装）；失败自动降级 |
image_sample |
N×N 像素取样，判断材质与纹理 |
image_crop |
按区域裁剪并导出 PNG |
image_palette |
主色提取（hex、名称、占比）与色相家族 |
image_compare |
两图或两区域像素对比，可选差异可视化 |
image_batch |
批量扫描、类型判定与是否值得深入的建议 |
vision_analyze |
统一入口：按模式组合像素扫描、OCR、可选 VLM |
document_to_image |
将 pdf / docx / doc / xlsx / xls / pptx / ppt 逐页转 PNG（需 LibreOffice + PyMuPDF） |
image_edit |
本地修图：22 种纯 CPU 动作（Pillow + OpenCV，可选 rembg / rawpy / realesrgan） |
外部 VLM 桥（可选）¶
配置 OpenAI 兼容端点（LM Studio、llama-server、云端网关等）后，模型在智能 / 严谨模式下可自行决定是否调用 vision_analyze(include_vlm=true)。隐私模式下 host 侧强制禁用，图片绝不外发。外部 API 是增强能力，不是必须依赖。
设置卡片¶
Web 设置页注册「图片阅读」卡片：使用模式、外部视觉 API、视觉桥模型多选、OCR 引擎与高级参数。改动写入 ~/.dsh/settings.yaml 即时生效；视觉桥模型勾选变更需重启 DSH。
安装与启用¶
下面命令来自插件 README 的快速上手章节。SkillHub 社区目录（https://www.skillhub.cn/plugins/jing-hy/picturereader）收录了该插件，安装方式与 README 一致。
1、安装插件：
dsh plugin --profile web add picturereader
dsh plugin --profile headless add picturereader
从源码安装时，在插件目录执行 dsh plugin --profile web add .。
2、（推荐）复制读图方法论 skill 到 DSH skills 目录：
cp skills/image-reading.md ~/.dsh/skills/
3、按需安装可选依赖：
node scripts/setup-ocr.mjs # PaddleOCR
node scripts/setup-rapid.mjs # RapidOCR
node scripts/setup-doc-venv.mjs # 文档转图片（需已装 LibreOffice）
node scripts/setup-image-venv.mjs # image_edit 核心依赖
node scripts/setup-image-venv.mjs --full # 再加 rembg、rawpy
重启 DSH Desktop 后，模型工具列表出现全部工具，设置页出现「图片阅读」卡片。
启用视觉孪生：
- 在设置页「图片阅读」勾选目标文本模型，保存后重启 DSH。
- 模型选择器中选择对应模型的「(视觉)」变体。
- 粘贴或拖入图片，即可看到原生缩略图，图片块自动分析为文本证据。
典型用法¶
读一张本地图片：
用 image_scan 看一下 <路径> 这张图，细看感兴趣的部分
复杂场景可接着用 vision_analyze；以文字为主时先 image_ocr；多图用 image_batch；Office / PDF 文档先用 document_to_image 逐页转图再分析。
image_edit 修图示例：
用 image_edit 把 <路径> 缩放到宽 800：action=resize, file_path=<路径>, width=800, height=600
给 <路径> 加左下角文字水印：action=watermark, file_path=<路径>, type=text, text="©2026", position=bottom_left, font_size=40
把 <IMG1>、<IMG2> 水平拼接：action=stitch, file_path=<IMG1>, file_paths=[<IMG2>], direction=horizontal
若会话处于 DSH code 工具模式，需通过 run_code 间接调用（如 await tools.image_scan({"file_path": "..."})），或把部署的 tools.mode 设为 both。
适用场景与注意¶
适合在 DSH 中继续使用纯文本模型、又需要读图、读文档或本地修图的场景。隐私模式下可处理敏感截图、合同扫描件，全程不走外部 API。
使用前注意：
- 插件以当前 dsh 进程权限运行，安装前应自行检查源码与 MIT 许可证。
- 原生缩略图需启用视觉孪生并选择「(视觉)」变体；未勾选时文本模型不被 DSH 视为支持图片。
image_scan/vision_analyze暂不支持 WebP，可先经image_edit的convert转成 PNG / JPEG。remove_background、raw_convert、upscale等动作需--full安装或额外 CLI；缺失时返回安装提示，不会崩溃。- DSH attachment 单图默认约 5MB，超大图片可能被宿主上传限制拦截。
按计划，该插件后续将作为 DeepSeek Harness EAC 的内置视觉插件，替换 dsh-tool-vision；当前仍以独立包形式发布，方便非 EAC 或旧版用户安装。
picturereader 把纯文本模型的读图链路收敛到一套本地工具 + 可选 VLM 桥 + 视觉孪生 adapter，在 DSH「一切皆插件」的生态里补上了模型推理侧的看图能力。
- 社区目录：https://www.skillhub.cn/plugins/jing-hy/picturereader
- GitHub：https://github.com/jing-hy/picturereader
