picturereader

一句话定位

给 DeepSeek Harness 里的纯文本模型补全"看图"能力：视觉孪生让原生缩略图真的渲染出来，本地像素工具链把图片翻译成模型可读的文本证据，外部视觉端点按需调用，隐私模式下图片字节全程不出本机。

核心能力

• 视觉孪生 adapter：把被勾选的文本模型声明为支持图片，模型选择器里出现"deepseek-v4-flash (视觉)"变体；粘贴图片触发原生缩略图，图片块被透明替换为本地像素分析文本（src/picturereader-vision.mjs:108-163）
• 本地像素工具：image_scan（颜色/分区/纹理扫描）、image_sample（N×N 精确取样）、image_crop（按区域裁剪导出 PNG）、image_palette（主色+色相家族）、image_compare（两图/两区域像素 diff）
• 多引擎 OCR：image_ocr 支持 windows（内置）、paddle（PaddleOCR，对发光/弯曲/游戏字更强）、rapid（RapidOCR，轻量快速）三套引擎，失败自动降级（src/tool.js / src/more-tools.js）
• 统一入口 vision_analyze：按当前使用模式路由——隐私硬走本地、智能先本地判断再决定是否外呼、严谨模式会做多路证据交叉验证；附 low-information 拦截，空白/纯色图不外呼（src/vision-analyze.js / src/guard.js）
• 批量与上下文：image_batch 给一堆图片做"自动扫描 + 类型判定 + 是否值得深入"评估；image_batch_ocr 自动全量 OCR 后按字符截断
• 文档转图片：document_to_image 把 PDF / DOCX / PPTX / XLSX 逐页渲染为 PNG（dpi、max_pages 可配），供视觉孪生/工具链按页读
• 可选外部 VLM 桥：模型按路由策略自行决定调用 sendVisionRequest，OpenAI 兼容端点 baseURL 自动补 /v1/chat/completions（src/vlm.js）
• 隐私/智能/严谨三模式：设置卡顶部切换，运行时 src/runtime.js 拉快照、隐私模式硬门禁 isVlmConfigured()=false

技术实现

• 语言: JavaScript（ESM，"type": "module"）
• 关键依赖: jpeg-js（纯 JS JPEG 解码）、pngjs（PNG 解码）、omggif（GIF 解码）、@deepseek-ai/dsh-settings + dsh-llm（宿主服务注入）、@deepseek-ai/schemastery（设置 schema 声明与运行时校验）
• 架构模式: 单一 cordis bundle + 双半区 patch。host 侧 src/index.js 把命名空间写进 settings.yaml、用 Proxy 包裹被勾选 adapter 注册视觉孪生、按 ctx.inject 阶段依次就位（tools/llm/attachments/webServer/settings）；client 侧 client.js 在 Web 设置页注册"图片阅读"卡片。cordis.patch.yml 只插入插件行，不动宿主代码
• 入口文件: src/index.js（host 半区入口）、client.js（web 设置页入口，dsh.client.platform=web）

适用场景

DSH 里跑 DeepSeek 这类没有视觉编码器的纯文本模型，又经常处理截图、扫描件、UI 视觉稿、合同照片、跨页长 PPT；想让模型读到图里信息但又不想让原始字节全部外发。日常轻度读图用"智能模式"省成本，处理证件照、隐私材料切到"隐私模式"全程本地，审图/批量校对则切"严谨模式"做交叉验证。

前置依赖与兼容性

安装方式

dsh plugin --profile web add picturereader

配置项

常见问题

Q: 必须安装 Python 或 LibreOffice 才能用吗？

A: 不必须。Windows OCR 是内置引擎，开箱即用；想解锁 PaddleOCR、RapidOCR 才需要跑 scripts/setup-ocr.mjs / scripts/setup-rapid.mjs 建 Python venv；想用 document_to_image 转 PDF/Office 才需要装 LibreOffice 并跑 scripts/setup-doc-venv.mjs。

Q: 隐私模式真的不会调用外部 API 吗？怎么保证？

A: 隐私模式是 host 侧的硬门禁，不是模型承诺。src/runtime.js 的运行时配置在这个模式下会让 isVlmConfigured() 恒为 false，vision_analyze 入口强制把 include_vlm 改成 false，视觉孪生 stream 也只会导出本地证据文本。即便你在设置卡里填了 baseURL 和 vlm_key，图片字节也一样不会走外部端点。

Q: 用完想把插件卸载干净，需要做什么？

A: dsh plugin remove picturereader 即可。插件会向宿主持久化两个东西：导出的图片存在 ~/.dsh/picturereader-vision/images/、设置写进 ~/.dsh/settings.yaml 的 picturereader 段；彻底清理需手动删掉这两个位置。

Q: 视觉孪生勾选后没反应，怎么排查？

A: vision_models 列表的改动不会热加载，必须重启 DSH 桌面端才能生效。如果你当前的 tools.mode 是 code，插件照样能用，只是要写成 await tools.image_scan({...}) 调用而不是直呼工具名。

Q: WebP 图片传进去报错怎么办？

A: 报错是预期的，把文件先转成 PNG 或 JPEG 再传。src/core.js 明确把 .webp 列入 UNSUPPORTED_EXTENSIONS 并直接抛错，image_scan / image_ocr / image_batch / document_to_image 全都遵守同一规则。

Q: 配置文件里的 vlm_key 安全吗？

A: 字段声明 role:'secret'，代码里只写不读、不会回显；想完全不让凭据进配置文件的话，把 Key 写在环境变量里，并通过 vlm_key_env 字段告诉插件变量名即可。

Q: 视觉孪生会影响所有 provider 的模型吗？

A: 不会。视觉孪生只对 vision_models 列表里勾选的那几个模型起作用，并通过 Proxy 把它们所属 provider 的 adapter 改成"孪生"，未勾选的模型行为不变。

Q: 单张图最大能处理多大？

A: 工具层硬上限是 50 MB 字节、24,000,000 解码像素；不过 DSH 附件上传侧默认约 5 MB，超大图会在上传阶段被宿主拦截，可以先用 image_crop 切图或降低分辨率再传。

上手难度

进阶 — 需要在 DSH 设置卡里至少指定"使用模式"、可选地填视觉端点 / 启用视觉孪生；想用增强 OCR 还要跑 setup 脚本建 Python venv。日常看图用默认模式即可，进阶玩法在隐私 vs 外呼、视觉孪生生效条件上需要理解。

已知问题与限制

• WebP 格式不支持：image_scan / image_ocr / image_batch / document_to_image 都拒绝 .webp 入口，需先转 PNG / JPEG（src/core.js:316）
• DSH 附件上传单图约 5 MB：超大图片可能在宿主层被拦截（README.md:269-276）
• 视觉孪生需手动重启 DSH：vision_models 列表改动不会热加载（README.md:218-222）
• BMP 限制：16 位 BMP、RLE 压缩 BMP 均不支持（src/core.js:200-209）
• 跨包兼容敏感：v3.0.5 修复了 scope.load() 缺失的场景；v3.0.6 修复了 jpeg-js/omggif/pngjs 在 plugin 包内未正确安装导致 core.js 顶层 import 失败（README.md:301-315）
• dsh-file-drop 与视觉孪生冲突：若同 profile 同时启用，可能出现"拖入图片即注入文本"与"视觉孪生自动分析"双路注入，建议停用 dsh-file-drop（README.md:275）
• 外部 VLM 桥需要联网：未配置 / 离线时会自动跳过并给提示，隐私模式恒不调用（README.md:276）
• image_batch 输出字符截断：单图 OCR 文本按 batch_ocr_limit_chars（默认 800 字符）截断，超长文本会丢尾部（src/image-batch.js:175-264）

v3.0.6 — 给纯文本模型（DeepSeek / text-only）的全能「看图 / 读文档」能力：粘贴即用、原生缩略图。 融合 视觉孪生 adapter（把任意文本模型原位包装成「支持图片」→ DSH 原生缩略图 + 图片块自动分析）、三模式路由、本地像素级工具链（scan / OCR×3 引擎 / crop / palette / compare / batch）、文档转图片（pdf / word / excel / ppt）与可选外部 VLM 桥。一个插件全包，无需另装。

---

定位

DeepSeek 等纯文本模型没有视觉编码器，无法直接看图片；DSH 原生缩略图也需要模型被声明为「支持图片」才会渲染。

⭐ 已支持外部视觉 API（OpenAI 兼容端点 / LM Studio / 云端 VLM），由 LLM 自行按需调用：配置好端点后，模型会在智能/严谨模式下自主判断"这张图值不值得外呼视觉模型"，需要时用 vision_analyze 调外部 API 做语义理解，简单内容则本地像素/OCR 搞定——外部 API 是即插即用的增强能力，不是必须依赖。

picturereader 解决两件事：

1. 把「看图/读文档」翻译成纯文本模型能理解的结构化证据（像素级 huel/结构/材质分析 + OCR 实读 + 可选 VLM 语义描述），并沉淀为读图方法论 skill。
2. 通过「视觉孪生 adapter」让纯文本模型在 DSH 里获得原生缩略图体验：勾选模型即生成「(视觉)」变体，粘贴图片显示原生缩略图、图片块进会话、并被自动分析成文本路径 + 本地证据再交给模型——模型拿到的永远是纯文本，不会触发 UNSUPPORTED_CONTENT。

版本徽章与兼容性：已验证兼容 DeepSeek Harness EAC 4.2.0 与 @deepseek-ai/dsh-client-ui-workspace rc.7。

🚀 后续将作为 DeepSeek Harness EAC 的内置视觉插件：本插件计划替换内置的 dsh-tool-vision，随 DSH EAC 桌面版直接捆绑发布，开箱即用（见上游 PR）。作为独立包发布的目的，是让非 EAC / 旧版用户也能通过 dsh plugin add picturereader 或 Git/npm 安装获得同等「看图 / 读文档」能力。

功能总览

① 视觉孪生 adapter（原生缩略图 + 自动分析）

• Proxy 原位包装：对被勾选的模型所属 provider，用 Proxy 把其 adapter 包装成「孪生」并原位替换（registerTwinAdapters，卸载经 ctx.effect 还原），不重复注册。
• listModels / resolveModel：对被勾选模型声明 inputModalities: ['text','image']、名称加「(视觉)」后缀 → DSH 认为它支持图片 → 原生缩略图渲染、图片块进会话、粘贴准入全部解锁。
• stream 拦截：捕获请求里的 image block → 导出到 ~/.dsh/picturereader-vision/images/ → 替换成文本路径 + 本地工具链引导 → 转发给原始 adapter。pi-ai 收到的是纯文本，不会报 UNSUPPORTED_CONTENT；opencode-go 等走 @earendil-works/pi-ai 的 provider 同样经此孪生获得原生缩略图能力。
• 隐私模式下分析只走本地工具，绝不外发。

② 智能路由（隐私 / 智能 / 严谨 三模式）

这是 picturereader 的"大脑"：统一在 routing.js + runtime.js 收敛「什么时候走外部 VLM、什么时候只用本地、要不要交叉验证」，供各工具 / 图片桥 / 视觉孪生 stream / vision_analyze 共享，保证整条图链都遵守同一套路由策略。

路由决策原理

每次看图，模型面对的问题其实是同一个：「这张图，值得花什么成本、用哪条路线读懂它？」picturereader 把答案预置成三种策略，模型据此自主决策，同时 host 侧做硬约束兜底：

图片进来 → 孪生 stream 拦截 / 工具被调用
        → 读入当前「模式」→ 得到该模式的路由策略
        → 模型 / 工具按策略选路线：
            本地像素分析（image_scan / image_sample）
            本地文字识别（image_ocr：windows / paddle / rapid）
            外部语义理解（vision_analyze include_vlm=true → VLM）
            交叉验证（多路证据对照）

核心决策函数 visionAnalyzeDefaults(mode) 定义各模式"默认的证据组合"：

三种模式的路线策略

🕶 隐私模式（Privacy）——零外呼硬门禁

• 绝不调用任何外部视觉端点，即使你在设置卡配了 API。
• 约束是 host 侧强制：runtime.js 使 isVlmConfigured() 恒为 false，vision_analyze 强制 include_vlm=false，视觉孪生 stream 的降级文本也明确"只用本地工具"。
• 模型只能用本地工具：image_scan / image_ocr / image_sample / image_crop / image_palette / image_compare。图片字节不出本机。
• 适用：敏感图片（身份证、合同、私人截图）、离线、零外部流量审计场景。

⚡ 智能模式（Smart）——省轮数、省时间（默认）

• 目标：先把成本压到最低，复杂内容才值得外呼。
• 决策流程：先 image_scan 快速看整体 → 自行判断：
  1. 图片以文字为主 → image_ocr 读文字即可，不必调 VLM；
  2. 普通图表 / 界面 / 简单内容 → image_scan + image_sample 自己看就能说清，不必调 VLM；
  3. 仅当内容复杂、需语义理解（照片、抽象画面）且配置了端点时，才 vision_analyze(include_vlm=true) 走外部 VLM。
• 视觉孪生死活都会先把图片导出成本地路径，模型可随时本地深挖，不会被困在"必须外呼"的死路。

🎯 严谨模式（Strict）——交叉验证、细看细节

• 目标：可靠性优先，不贪省。
• 决策：先 image_scan 了解整体 → 必要时 image_ocr 读文字、image_sample 细看细节 → 对关键判断做交叉验证（把像素证据、OCR 证据、（可选）VLM 语义描述相互对照，不轻信单一来源）。
• 允许使用外部 VLM（需配置），但强度更高、可追溯。
• 适用：需要高准确率与可复现结论的场景（审图、校对、数据分析）。

隐私硬门禁贯穿所有入口：无论走哪个工具/桥，runtime.js 的模式快照都会在调用点做校验，routePolicyText(mode) 还会把当前策略注入给模型的提示里，双保险。

与视觉孪生 adapter 的协同

三模式不仅约束 vision_analyze，也约束视觉孪生 registerTwinAdapters 的 stream 拦截：图片块总是被无条件替换成文本（路径 + 本地证据引导，这是模型能读懂的前提），但是否/何时进一步外呼 VLM 由当前模式决定——隐私模式恒不透传图片、不发起外部调用；智能/严谨模式在需要且已配置时才走外部语义理解。因此"原生缩略图"与"隐私零外呼"可以同时成立，互不冲突。

③ 本地工具链（纯本地、纯 JS 像素级）

④ 文档转图片 document_to_image

把 pdf / docx / doc / xlsx / xls / pptx / ppt 逐页转成 PNG（LiberOffice headless → PDF → PyMuPDF），供模型逐页 OCR / 扫描分析。纯本地、零网络；支持 dpi / max_pages / out_dir / 批量 file_paths。

⑤ 外部 VLM 桥（已支持，由 LLM 自行调用）

已支持外部视觉 API，且调用时机完全交给 LLM 自主判断：配置好 OpenAI 兼容端点后（LM Studio / llama-server / 云端网关 / GLM-4V-Flash 免费模型），模型在智能 / 严谨模式下会自行判断"这张图是否值得外呼视觉模型"——简单内容用本地像素/OCR 就够，复杂内容（照片、抽象画面、需语义理解）才通过 vision_analyze(include_vlm=true) 调 sendVisionRequest 以 data URI 送图给外部 VLM，取回语义描述。baseURL 自动补 /v1/chat/completions（无需手写完整路径）。

• LLM 自行调用 = 你不用手动切模型/手动发图，模型按模式策略在该外呼时自己调外部 API。
• 隐私模式仍为硬门禁：即使配置了外部 API 也绝不调用、绝不外发图片字节。

⑥ 设置卡片「图片阅读」

Web 设置页注册「图片阅读」卡片：使用模式、外部视觉 API、视觉桥模型多选、高级设置（详见「设置卡字段」）。改动写 ~/.dsh/settings.yaml 即时生效。

⑦ 粘贴即用 + 缩略图

开启视觉孪生并选择「(视觉)」模型变体后：粘贴/拖入图片 → 原生缩略图 → 图片块进会话 → 被孪生 stream 拦截 → 导出文本路径 + 本地证据 → 纯文本模型拿到结果，可继续用 image_scan / image_ocr 深挖。

与主流多模态插件的差异 / 优势

对比常见方案（dsh-tool-vision、dsh-image-paste、dsh-vision-bridge 等）：

1. 不绑定单一厂商：视觉孪生对任意 provider 生效（含 opencode-go / xiaomi / qiu 等 pi-ai 系），不是只适配某一家 API。
2. 全链路可离线：隐私模式零外呼；本地纯 JS 像素工具 + 3 引擎 OCR，不依赖云端。
3. 工具链完整：裁剪 / 取色 / 对比 / 批量 / 文档转图，一个插件全覆盖。
4. 原生缩略图：真正 DSH 原生图片块（inputModalities 声明），非文本路径模拟。
5. 快：本地工具毫秒级；可控 VLM 调用（低信息拦截 + 智能模式"值得才调"）省轮数与耗时。
6. 只写不读 key、隐私硬门禁：API Key 以 role:'secret' 保存、只写不读不回显；隐私模式经 runtime.js 强制 isVlmConfigured()=false。

快速上手

# 1. 安装插件
dsh plugin --profile web add picturereader        # npm 包；或从源码: dsh plugin --profile web add .
dsh plugin --profile headless add picturereader

# 2.（推荐）安装读图方法论 skill
copy skills\image-reading.md %USERPROFILE%\.dsh\skills\          # Windows
# cp skills/image-reading.md ~/.dsh/skills/                      # macOS / Linux

# 3.（可选）增强 OCR 引擎
node scripts/setup-ocr.mjs       # PaddleOCR（发光/弯曲/游戏字更强）
node scripts/setup-rapid.mjs     # RapidOCR（轻量快速）

# 4.（可选）文档转图片依赖（需已装 LibreOffice）
node scripts/setup-doc-venv.mjs  # 建 doc_venv 装 PyMuPDF

重启 DSH Desktop 后：模型工具列表出现全部工具，设置页出现「图片阅读」卡片。

启用视觉孪生（原生缩略图）

1. 在设置页「图片阅读」勾选要作为视觉孪生的文本模型，保存后重启 DSH。
2. 模型选择器中选择对应模型的「(视觉)」变体（如 deepseek-v4-flash (视觉)）。
3. 粘贴 / 拖入图片 → 原生缩略图 → 图片块自动分析为文本证据。

使用示例

用 image_scan 看一下 <路径> 这张图，细看感兴趣的部分
（复杂场景可接着用 vision_analyze；如有文字先 image_ocr；一批图用 image_batch；
  文档用 document_to_image 逐页转成图片再看）

Code Mode（工具折叠）兼容说明

DSH 的 tools 呈现有三种 mode：native（默认，模型可直呼所有工具）、code（只允许模型直呼 run_code，其它工具折叠进 run_code 的生成 SDK 内调用）、both（两种都能用）。

• picturereader 所有工具与 mode 无关：native / both 下全部可直呼；code 下也完全可用，只是要经 run_code 程序内调用（await tools.image_scan(...) / await tools.vision_analyze(...)）。工具会被自动投影进 run_code 生成的 SDK，一个都不少。
• 若报错 Error: unknown tool "vision_analyze" ... only run_code is callable directly ...——这不是插件坏了，而是当前会话处于 code 模式、仍以直呼方式发起了调用。两种情况任选其一：
  1. 把该部署的 tools.mode 设为 both（最省心：直呼 + run_code 都能用，不会降速）；
  2. 保持 code 模式，改用 run_code 程序调用（见下方示例）。
• 推荐：日常使用直接保持 native 或 both；code 是平台级的"只留 run_code"硬化模式，对本地看图工具是净亏（更多轮数、更多 token），非必要不开。

在 code 模式下用 run_code 调用示例（Python）：

async def main():
    r = await tools.image_scan({"file_path": r"C:\path\to\img.png"})
    return r

await main()

三模式（使用模式）

在 Web 设置 →「图片阅读」卡片顶部选择，修改即时生效。

隐私模式约束是 host 侧硬门禁（runtime.js）：isVlmConfigured() 在此模式下恒返回 false，vision_analyze 强制 include_vlm=false，图片桥引导也明确「只用本地工具」。

设置卡字段（图片阅读）

• 使用模式：隐私 / 智能 / 严谨（mode）。
• 启用外部视觉 API（选配）：勾选后才显示并允许调用外部视觉端点；不勾选一律走本地，图片绝不外发（vlm_enabled）。
• 勾选后显示：
  • 视觉 API Base URL（vlm_base，如 https://api.openai.com/v1 或 http://127.0.0.1:1234；留空=禁用外部 VLM）
  • 视觉模型（vlm_model）
  • 视觉 API Key（vlm_key，password+secret：只写不读，留空保持当前，填写保存即覆盖、不回显）
  • Key 环境变量（vlm_key_env，apiKey 为空时回退读取）
  • 默认 OCR 引擎（ocr_engine：windows / paddle / rapid）
• 视觉桥模型多选（vision_models）：勾选即生成该模型的「(视觉)」变体；改动需重启 DSH 生效；已勾选模型会被兜底并入列表保持打钩，与孪生注入一致。
• 高级设置（折叠）：

环境变量

OCR（选装）

文档转图片（选装）

外部视觉 API / VLM（可选，也可在设置卡填）

设置卡 vlm_base / vlm_model / vlm_key 优先于环境变量；隐私模式下即使配置也不调用。端点未写 /v1 时自动补 /v1/chat/completions。

已知限制

• DSH attachment 单图默认约 5MB：超大图片可能被宿主上传限制拦截；工具端的 max_image_bytes（默认 50MB）是读取上限。
• 原生缩略图需启用视觉孪生：文本模型默认不被 DSH 视为「支持图片」，需在设置卡勾选生成「(视觉)」变体并重启。
• WebP 暂不支持：image_scan / vision_analyze 等对 WebP 报错，请先转成 PNG / JPEG。
• 视觉桥模型勾选需重启 DSH 生效（vision_models 的改动不会热加载）。
• dsh-file-drop 需停用：其「拖入图片即注入文本」与视觉孪生/图片桥的自动分析可能冲突（重复/竞争注入），建议在对应 profile 停用；原生缩略图 + 图片桥自动分析已覆盖该需求。
• 外部 VLM 依赖网络/端点：未配置端点或离线时自动跳过并给出提示；隐私模式恒不调用。

测试情况

v3.0.3 集成测试（2026-08-20）

132/132 单元测试通过 + 13/13 文档转换测试通过 + 全功能集成测试：

v3.0.6 修复

• 依赖安装完整性修复：修复了 picturereader 安装后图像分析功能（scan / ocr / vision）静默失败的问题。根因是 npm install 未完整执行，jpeg-js、omggif、pngjs 三个运行时依赖没有正确安装到 node_modules/ 目录下，导致 core.js 顶层 import 失败。修复方案：在内置插件打包时预装依赖，确保 node_modules/ 随插件一起分发。

v3.0.5 修复

• scope.load() 兼容性修复：修复了在某些 DSH 版本中设置页「图片阅读」卡片打开空白的问题。根因是 client.js 直接调用 scope.load() 但该宿主版本的 settingsScope API 没有 load 方法（只有 getSnapshot/subscribe/set/unset），导致组件渲染时抛出 TypeError: scope.load is not a function。修复方案：在调用前检查 typeof scope.load === "function"，不存在时直接从 scope.getSnapshot() 读取。

v3.0.3 修复

• 视觉桥模型列表持久化修复：修复了设置页「视觉桥模型」勾选后重新打开设置丢失勾选状态的问题。根因是 settings/document-updated 事件触发 scope.load() 覆盖本地修改，改为通过 lastSavedRef 跟踪保存值，跳过同步覆盖。
• OCR 引擎/模式设置持久化修复：修复了 ocr_engine 和 mode 等 select 字段修改后重新打开设置恢复默认的问题。根因是 onSave 函数未正确处理 select 类型字段的默认值回退。
• cordis 4 兼容性修复：修复了 image-batch.js 和 doc-tools.js 中访问未声明 ctx 属性导致的报错。
• PaddleOCR 字段名修复：w/h 字段改为 width/height 以匹配 schema。
• 本地 VLM 端点检测修复：isManagedEndpoint 扩展为识别所有 127.0.0.1/localhost 地址，不再要求 API key。

开发 / 仓库布局

# DSH 版（本仓库 main，代码在 dsh/）
npm install
npm test                       # node:test
node scripts/setup-ocr.mjs     # 可选
node scripts/setup-rapid.mjs   # 可选
node scripts/setup-doc-venv.mjs# 可选（文档转换）
node scripts/preview.mjs       # 生成 fixtures 并预览渲染

• 热插拔：业务逻辑集中在 src/core.js 单文件，工具每次执行按 mtime 动态加载；工具定义（schema/描述）与设置卡改动需重启桌面端。
• ZCode 版：位于本仓库 zcode 分支（源码在 zcode/），经 MCP server 暴露工具，安装 npm install picturereader-zcode。两版共用 src/core.js 与读图方法论 skill。

License

MIT