picturereader

v3.4.0 — 给纯文本模型（DeepSeek / text-only）的全能「看图 / 读文档 / 修图」能力。 融合 视觉孪生 adapter（把任意文本模型原位包装成「支持图片」→ DSH 原生缩略图 + 图片块自动分析）、三模式路由、本地像素级工具链（scan / OCR×4 引擎 / crop / palette / compare / batch）、文档转图片（pdf / word / excel / ppt）、本地修图工具 image_edit（Pillow/OpenCV 纯 CPU：缩放 / 旋转 / 滤镜 / 合成 / 水印 / 去背景 / 超分等）与可选外部 VLM 桥。一个插件全包。

v3.4.0 新增：原生识图能力感知。插件现在从模型能力元数据（inputModalities，与 DSH 内核的图片门控同源）判断当前会话的模型是否自己就能看图：命中时在系统提示词里明确说明「不要用 image_scan / image_sample 这类"伪多模态"替代路径，但 image_ocr 仍应正常使用」，并让粘贴/读取的图片直通该模型、不再降级成文本引导；纯文本模型与元数据缺失（未知）时行为与 v3.3.3 完全一致。判定走未包装的原始 adapter，因此不会被本插件自己的视觉孪生误判成原生识图。

v3.3.0 新增：macOS 原生 Vision OCR 引擎（engine="macos"，scripts/setup-macos.mjs 一键编译，PR #4 合入）；OCR 引擎选项按平台条件显示（macos 仅 macOS、windows 仅 Windows，paddle/rapid 跨平台始终显示）；修复 PaddleOCR 新环境首次调用三个缺陷（stdout 污染 / w/h→width/height / 缓存路径写死，issue #2）；设置卡 UI 重做（settings-panel 设计语言）；调试日志门控（llm/stream 桥不再刷屏）；peerDependencies 兼容 DSH 0.1.1-rc.2（issue #3）。

定位

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

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

picturereader 现在解决三件事：

1. 把「看图/读文档」翻译成纯文本模型能理解的结构化证据（像素级 hue/结构/材质分析 + OCR 实读 + 可选 VLM 语义描述），并沉淀为读图方法论 skill。
2. 通过「视觉孪生 adapter」让纯文本模型在 DSH 里获得原生缩略图体验：勾选模型即生成「(视觉)」变体，粘贴图片显示原生缩略图、图片块进会话、并被自动分析成文本路径 + 本地证据再交给模型。即使上游先降级为 attachment sha256 文本，图片桥也会仅从本机附件对象库恢复经过文件头校验的图片并注入本地工具路径；模型拿到的永远是纯文本，不会触发 UNSUPPORTED_CONTENT。
3. 本地直接修图 / 批量处理图片：image_edit 提供缩放、旋转、滤镜、合成、水印、去背景、拼接、透视校正等纯 CPU 动作，图片不出本机。

版本兼容性：本版本专门兼容 dsh 0.1.3-alpha.1 / dsheac 5.4.0（并实测兼容 dsh 0.2.0-rc.2），同时向后兼容 dsh 0.1.1-rc.2 与 dsheac 5.1.0，以及 DeepSeek Harness EAC 4.2.0 与 @deepseek-ai/dsh-client-ui-workspace rc.7。peerDependencies 采用 ^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.2.0-rc.2 || ^0.1.3-alpha.1 联合区间，覆盖 0.1.x 三条发布线并延伸到 0.2.x。

⚠️ 升级到 dsh 0.1.3 必须使用 v3.3.2 之后的版本：内核 0.1.3 起 @deepseek-ai/dsh-settings 不再导出 settingsNamespace() 品牌函数（命名空间校验收进 register() 内部）。ESM 静态导入不存在的符号会让模块整体加载失败，进而拖垮整棵插件树、触发 EAC 的 guard 安全模式（表现为「一对话就报错」+ 插件大范围消失）。v3.3.3 已适配。

🚀 后续将作为 DeepSeek Harness EAC 的内置视觉插件：本插件计划替换内置的 dsh-tool-vision，随 DSH EAC 桌面版直接捆绑发布，开箱即用。作为独立包发布的目的，是让非 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 / macos / 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 / image_edit。图片字节不出本机。
• 适用：敏感图片（身份证、合同、私人截图）、离线、零外部流量审计场景。

⚡ 智能模式（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 由当前模式决定——隐私模式恒不透传图片、不发起外部调用；智能/严谨模式在需要且已配置时才走外部语义理解。因此"原生缩略图"与"隐私零外呼"可以同时成立，互不冲突。

③ 本地工具链（纯本地读取）

OCR 引擎平台说明：windows 引擎仅在 Windows 平台可用、macos 引擎仅在 macOS 平台可用（设置卡按平台条件显示对应选项）；paddle / rapid 为跨平台选装引擎，任何平台都可使用。未配置时默认跟随当前平台原生引擎（Windows→windows、macOS→macos、其他→paddle），跨平台迁移的旧配置会自动回落到平台默认值。

④ 文档转图片 document_to_image

把 pdf / docx / doc / xlsx / xls / pptx / ppt 逐页转成 PNG（LibreOffice 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 设置页注册「图片阅读」卡片（settings-panel 设计语言：卡片分组 + 胶囊按钮 + 折叠高级项）：使用模式、外部视觉 API、视觉桥模型多选、OCR 引擎（平台条件显示）、高级设置（详见「设置卡字段」）。改动写 ~/.dsh/settings.yaml 即时生效。

⑦ 粘贴即用 + 缩略图

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

⑨ 原生识图能力感知（v3.4.0）

给"自己就能看图"的模型让路：picturereader 的本地工具链是为没有视觉编码器的模型准备的替代路径，而原生多模态模型用它们只会更慢更不准。插件因此从底层元数据判断能力，并据此调整提示词与图片链路。

• 判定与内核同源：读 llm 适配器的 inputModalities（'text' | 'image'），三态语义与内核一致 —— 显式含 image = 原生识图；显式不含 = 纯文本（negative capability）；字段缺失 = 未知（不注入、不改变行为，零回归）。
• 提示词注入：以 ctx.systemPrompt.section() 注册动态 section（name picturereader:image-capability，order 3000）。原生识图时注入：不建议用 image_scan / image_sample 这些把图片降采样成像素网格的替代手段（信息损失大、易把结论建立在残缺数据上），image_ocr 仍应正常使用（原生视觉对小字／发光字／艺术字会幻觉，文字以 OCR 实读为准），image-reading skill 的 5 步扫描流程也不必遵循。
• 图片直通：判定为原生识图（或命中 multimodal_models 白名单）时，llm/stream 图片桥不再降级图片块，粘贴的图直达模型；read_image 返回的图片块同样不再被替换成文本说明。
• 不被孪生污染：能力判定用 realAdapterOf() 取未包装的原始 adapter —— 本插件的视觉孪生会把被勾选模型的 inputModalities 改写成 ['text','image']，若直接读 llm.listModels()，会把「伪识图（孪生）」误判成「真·原生识图」。
• 当前模型跟踪：system-prompt/assemble（内核每轮写入的 variables.provider/model）→ agent 级缓存（WeakMap，多会话/子代理互不干扰）→ llm/stream 兜底；模型切换后最迟下一轮生效。
• 可回退：高级开关 native_vision_auto（默认 true）。关闭后提示词注入与图片直通全部回到 v3.3.3 的行为（只认 multimodal_models 白名单）。

⑧ 本地修图工具 image_edit

一个工具、多个 action 分发，后端为隔离的 image_venv Python（Pillow + OpenCV-headless，可选 rembg / rawpy / realesrgan CLI），纯 CPU、无需 GPU / 大模型。所有图片字节不出本机。

依赖安装：node scripts/setup-image-venv.mjs（核心）/ node scripts/setup-image-venv.mjs --full（再加 rembg + rawpy）。详见下方专门章节。

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
把 <背景> 和 <前景> 合成（贴图）：action=composite, file_path=<背景>, file_paths=[<前景>], position=bottom_right, alpha=0.8
把 <IMG1>、<IMG2> 水平拼接：action=stitch, file_path=<IMG1>, file_paths=[<IMG2>], direction=horizontal

支持的 action（P0 / P1 / P2）

依赖与降级策略

• P0 全部仅需 Pillow；P1 除 remove_background 外仅需 OpenCV-headless。
• remove_background 需要 rembg（--full）；raw_convert 需要 rawpy（--full）；upscale 需要外部 realesrgan-ncnn-vulkan CLI（环境变量 DSH_REALESRGAN_EXE）。
• 可选依赖缺失时，不是崩溃，而是返回清晰的中文提示（"请先运行 node scripts/setup-image-venv.mjs [--full]" / "请设置 DSH_REALESRGAN_EXE"）。
• image_venv Python 未搭建时，工具返回 node scripts/setup-image-venv.mjs 安装提示（与 document_to_image 的 doc_venv 一致）。
• 全部动作默认超时 120s；remove_background 300s；upscale / denoise 更长，避免后台阻塞。

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

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

1. 不绑定单一厂商：视觉孪生对任意 provider 生效（含 opencode-go / xiaomi / qiu 等 pi-ai 系），不是只适配某一家 API。
2. 全链路可离线：隐私模式零外呼；本地纯 JS 像素工具 + 4 引擎 OCR（含平台原生引擎），不依赖云端。
3. 工具链完整：裁剪 / 取色 / 对比 / 批量 / 文档转图 / 本地修图 image_edit，一个插件全覆盖。
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（轻量快速；跨平台选装）
node scripts/setup-macos.mjs     # macOS 原生 Vision OCR（仅 macOS，需 Xcode 命令行工具）

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

# 5.（可选）本地修图 image_edit 依赖
node scripts/setup-image-venv.mjs          # 建 image_venv 装 Pillow + OpenCV-headless + piexif
node scripts/setup-image-venv.mjs --full   # 再加 rembg（背景移除）+ rawpy（RAW）

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

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

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

使用示例

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

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.image_edit(...) / 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，图片桥引导也明确「只用本地工具」。

设置卡字段（图片阅读）

设置卡片采用 settings-panel 设计语言（卡片分组 / 胶囊按钮 / 折叠高级项），包含：

• 使用模式：隐私 / 智能 / 严谨（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 显示 windows/paddle/rapid，macOS 显示 macos/paddle/rapid，其他平台显示 paddle/rapid；未配置时默认跟随平台原生引擎）
• 视觉桥模型多选（vision_models）：勾选即生成该模型的「(视觉)」变体；改动需重启 DSH 生效；已勾选模型会被兜底并入列表保持打钩，与孪生注入一致。
• 高级设置（折叠）：

环境变量

以下 venv 解释器默认路径指向作者开发环境，普通用户请按本机实际 venv 路径设置对应环境变量（或仅使用平台原生引擎：Windows 的 windows / macOS 的 macos 零依赖）。

本地修图 image_edit（选装，Pillow+OpenCV）

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；image_edit 的 convert 可把 WebP 转成 PNG/JPEG。
• 平台引擎不可跨平台：windows / macos OCR 引擎分别限定对应平台（设置卡按平台显示）；跨平台迁移后旧配置会自动回落到当前平台默认引擎。
• image_edit 部分动作需可选依赖：remove_background（rembg）、raw_convert（rawpy）、upscale（realesrgan CLI）需 --full 安装或外部 CLI；缺失时返回安装提示而非崩溃。
• rembg 首次运行需联网下载 U²-Net 模型：约 35–176MB，缓存于 ~/.u2net；之后离线可用。
• paddle 引擎首次调用会下载模型（多源 fallback，缓存于 ~/.paddlex-cache）：下载过程可能打印干扰行，插件已做防御过滤，首次调用不再失败（issue #2 已修复）。
• 视觉桥模型勾选需重启 DSH 生效（vision_models 的改动不会热加载）。
• dsh-file-drop 需停用：其「拖入图片即注入文本」与视觉孪生/图片桥的自动分析可能冲突（重复/竞争注入），建议在对应 profile 停用；原生缩略图 + 图片桥自动分析已覆盖该需求。
• 外部 VLM 依赖网络/端点：未配置端点或离线时自动跳过并给出提示；隐私模式恒不调用。

拖拽上传问题排查

如果遇到图片拖拽上传不工作的问题，请按以下步骤排查：

1. 检查 dsh-file-drop 插件状态：在 DSH 设置中检查 dsh-file-drop 插件是否启用。如果启用，请尝试禁用它，因为该插件可能与 picturereader 的图片桥冲突。

2. 检查视觉孪生配置：确保在设置页「图片阅读」中已勾选需要视觉桥的模型，并重启 DSH。

3. 检查浏览器控制台：打开浏览器开发者工具，查看控制台是否有 [picturereader] 相关的日志输出。如果有错误信息，请记录并反馈。

4. 检查网络请求：在开发者工具的 Network 标签中，查看是否有 /picturereader/models 等请求。如果没有，可能是插件未正确加载。

5. 重启 DSH：某些配置更改需要重启 DSH 才能生效。

测试情况

v3.4.0

• node --test 全量 162 通过 / 0 失败，其中新增：
  • tests/vision-capability.test.js（11 例）：三态判定与内核 inputModalities 语义一致（含 [] = 显式省略、undefined = 未知）、能力缓存读写、seedCapabilityFromAdapter 三条路径（resolveModel / listModels / 抛错退化为未知）、agent 级当前模型跟踪的优先级、白名单覆盖、提示词文案（native 注入且明确"不用 scan、ocr 照用"；text-only 与 unknown 不注入）、section 名/order 常量稳定。
  • tests/prompt-injection.test.js（3 例集成冒烟）：用最小 ctx 桩真跑一遍 apply()，验证 ① 原始 adapter 扫描 → 能力缓存；② system-prompt/assemble → section 注册并注入原生识图说明；③ native 模型图片原样放行、纯文本模型仍降级为 image_scan 引导、native_vision_auto=false 完全回退。

v3.3.0

• node --test 全量 146 通过 / 0 失败：
  • tests/macos.test.js：macOS Vision OCR 引擎套件（Windows 平台自动跳过，需编译 macos-ocr 二进制后实跑）。
  • tests/image-edit.test.js：8 项单测（action 校验、参数构造、超时、错误透传）。
  • tests/ocr.test.js：paddle 引擎真实用例（本机 paddle_venv 实测 image_ocr(engine="paddle") 通过，验证 w/h→width/height 修复）。
  • 其余读图工具链、三模式、视觉孪生、document_to_image、batch、decode、sample 等全部通过。
• 后端 scripts/image-edit.py 端到端冒烟（Pillow + OpenCV）：24/24 通过。

v3.1.0 集成测试

内置 node:test 单测（工具、三模式、桥）+ 真实素材集成测试通过：本地工具链、文档转图片（pdf/docx/pptx/xlsx）、外部 VLM 真调通路（LM Studio）、三模式路由、视觉孪生 Proxy 均验证通过（24/24）。

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

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

版本更新日志

v3.5.0（本次）

• 0.2.x 设置卡片回归（新功能）：0.2.x 移除了 settingsScope（命名空间式设置模型整体退役），v3.4.1 只能在老内核上显示自绘卡片。本版按官方契约把卡片注册为 「设置 → 内置插件」页里的一个 tab（slots.register 到 settings.plugins.tab，与官方 dsh-client-ui-settings-plugin-inventory 同一写法），并把数据通道换成插件自有的 loopback 路由：
  • GET /picturereader/config 读当前生效配置（entry config + 用户级覆盖层，Schema 默认值由 Config() 补齐）；
  • PUT /picturereader/config 增量写 {set, unset} 到 $DSH_HOME/picturereader-config.json（原子写；vision_models 这类对象数组用 JSON 天然承载）；
  • 沿用 loopback 信任围栏（非本机 Host / 跨站请求一律 403）。
  • 内核代次用 ctx.get("settingsScope") 运行时探测（不能直接读 ctx.settingsScope：cordis 对未 inject 的服务属性一读即抛），0.1.x 仍走原 settings.section + settingsScope 路径，两代界面同源。
  • 副作用：保存后立即刷新视觉孪生包装（勾选模型无需重启）。
• 修复 0.2.x 下卡片完全不可用：ctx.settingsScope 探测与 snapshot.writable 缺失导致的按钮恒禁用/模块加载失败。
• 配色与控件 token 保持不变：--dsw-alias-* 系列 token 在 0.2.0-rc.2 全部存在（已核对），无需改样式。
• 无障碍实测（dsh 0.2.0-rc.2 + Edge/Playwright）：无障碍树确认 tab "图片阅读" [selected] → tabpanel 内 heading/combobox/checkbox/button 结构完整（5 张卡片、15 个输入、2 个下拉、保存按钮）；交互链路实测选择「严谨模式」→ 点「保存」→ UI 显示「已保存」→ picturereader-config.json 落盘 mode: "strict"。
• 测试：npm test 全量 162 通过 / 0 失败。

v3.4.1

• 适配 dsh 0.2.0-rc.2（关键修复）：0.2.x 的设置模型整体换代 —— @deepseek-ai/dsh-settings 不再提供「插件注册命名空间」的 register(ns, Config, opts)（实测服务方法只剩 describe / schema / mutate / update / replace / write / configure 等），客户端服务 settingsScope 也已移除；插件改为直接读自身 entry 的 Config，表单由内核按 Config schema 生成。
  • host：sctx.settings.register(...) 改为两代兼容分支 —— 有 register 走 0.1.x 原逻辑；没有则 sourceGetter 回退到 ctx.config 并监听 config 事件刷新孪生；注册异常一律降级并告警，不再中断后续的模型扫描与 registerTwinAdapters（0.2.x 上 register 抛 TypeError 曾让视觉孪生与 available_text_models 扫描全部静默失效）。
  • client：settingsScope 缺失时跳过自绘设置卡并告警，不再让客户端模块 apply 抛错（抛错会连带工具卡片一起失效）。
  • 导出 Config：按 cordis 约定改为 export const Config，使 0.2.x 的 settings 表单能识别本插件的配置 schema（0.1.x 下无副作用）。
• 附件读取两代兼容：新增 readAttachmentImage()，按 readImage(ref, signal)（0.1.x 与 0.2.x 本地 provider 均实现，但 0.2.x 起抽象基类不再声明）→ imageHostPath(ref) + 读盘（0.2.x 官方路径）→ readImageRequest(ref, target, signal) 的顺序兜底；bridge.js 与视觉孪生共用同一实现。
• peerDependencies 追加 ^0.2.0-rc.2（@deepseek-ai/dsh-settings / @deepseek-ai/dsh-llm）：0.2.x 的插件版本门禁在启动时比对 peer 声明，区间不含 0.2.x 的插件会被「skipping profile bundle」静默跳过、必须人工 dsh plugin allow-version 放行；本版起直接加载，无需豁免。
• 实测（dsh 0.2.0-rc.2，官方桌面版 desktop profile）：模型扫描产物 ~/.dsh/picturereader-models.json 由「不生成」（改前）恢复为正常写入（改后）；image_scan 多轮 + image_ocr(engine=rapid) 端到端任务通过。
• 测试：npm test 全量 162 通过 / 0 失败。
• 已知缺口（v3.5.0 起已解决）：0.2.x 下自绘设置卡片曾不显示；v3.5.0 已改为注册到「设置 → 内置插件」页的 tab，并走插件自有的 loopback 配置路由。

v3.4.0

• 原生识图能力感知（新功能）：新增 src/vision-capability.js，从模型能力元数据 inputModalities（与内核图片门控同源）做三态判定 native / text-only / unknown。
  • 提示词：经 ctx.systemPrompt.section() 注入动态段落（name picturereader:image-capability，order 3000，空串自动丢弃）。原生识图时明确：不要用 image_scan / image_sample 这类伪多模态替代路径，但 image_ocr 仍应正常使用（原生视觉对小字/发光字会幻觉，文字以 OCR 实读为准）。image_scan / image_sample / image_ocr 的工具描述也各补了一句能力前提。
  • 图片链路：判定为原生识图（或命中 multimodal_models 白名单）时 llm/stream 桥不再降级图片块，粘贴图片直达模型。
  • 不被孪生污染（关键）：能力判定走新增的 realAdapterOf() 取未包装的原始 adapter —— 孪生会把被勾选模型的 inputModalities 改写成 ['text','image']，直接读 llm.listModels() 会把「伪识图」误判成「真识图」；拿不到原始 adapter 时宁可记 unknown，也不用可能被污染的数据。
  • 当前模型跟踪：system-prompt/assemble 读内核每轮写入的 variables.provider/model → agent 级 WeakMap 缓存（多会话/子代理隔离）→ llm/stream 兜底 + 冷启动异步补种；模型切换后最迟下一轮生效。
  • 设置项：新增高级开关 native_vision_auto（默认 true，设置卡同步显示）。未知（无元数据）不注入、不改变任何行为，保证零回归。
• 修复 read_image 拦截从未生效：tools/post-execute 的处理器原先只改了局部 result 却没返回 PostToolDecision（应为 { kind:'accept', content }），替换实际从未发生。现已修正，并且比原逻辑更保守：只在明确判定为纯文本时才替换成 image_scan / image_ocr 引导，原生识图与未知一律放行。
• 测试：npm test 全量 162 通过 / 0 失败（新增 11 例单测 + 3 例 apply() 集成冒烟）。

v3.3.3

• 适配 dsh 0.1.2 / 0.1.3 的破坏性变更（关键修复，含 @FreyHsia 贡献）：

  • settings 命名空间 API：内核移除 settingsNamespace() 导出（校验收进 register() 内部，见内核 parseSettingsNamespace），原先顶层 import { settingsNamespace } from '@deepseek-ai/dsh-settings' 在 ESM 链接期即失败 —— 模块整体加载失败会拖垮整棵插件树，在 EAC 上表现为「一对话就报错」并触发 guard 安全模式（配套插件行被大范围剥离）。现改为把裸 NS 直接交给 sctx.settings.register(NS, Config, { base: config })，返回的 scope 仍具备 get / watch / update / replace，行为不变。
  • 设置页重新打开后写入失效（0.1.2+ 回归）：卸载时只退订、不 dispose() scope —— scope 属于插件 fiber 生命周期，组件卸载销毁它会导致关闭设置页再打开后所有写入静默失败、必须重启 DSH 才能改设置。
  • 视觉孪生链路：适配 dsh-llm 的流调度变更（prepareCall(...).stream，不再走 adapter.stream），并在设置变更时 refreshTwinAdapters() 热更新孪生包装，避免「勾选模型后仍需重启」。
  • WebP 附件可分析：dsh-attachment 会把带 alpha 的 PNG 归一化为 WebP，而本地工具链只读 png/jpg/gif/bmp —— 现以 webp-wasm（纯 WASM，全平台零安装）解码 + pngjs 落盘转为 PNG，分析链不再因格式中断。
  • 设置页模型勾选交互：vision_models 改为草稿态由「保存」按钮统一提交（空列表走 unset 回落 schema 默认），不再在每次勾选时立即写盘。

• peerDependencies 补齐 0.1.2 / 0.1.3 线：^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.3-alpha.1（@deepseek-ai/dsh-settings 与 @deepseek-ai/dsh-llm），避免新环境安装时被旧的版本区间误导。

• 逐项复核其余 @deepseek-ai/* 导入：contentHasImage（dsh-llm）与 schemastery 默认导出在 0.1.3 上均仍存在，无需改动。

• 兼容性保持不变：0.1.1-rc.2 / dsheac 5.1.0 及更早内核下行为与 v3.3.2 一致。

  v3.3.2

• 修复文本模型附件降级链路：当模型入口将图片改写为 [image omitted ...; attachment sha256:…] 时，图片桥会在本地附件对象库中按 SHA 前缀查找唯一对象，验证 PNG/JPEG/GIF/BMP/WebP 文件头后导出并注入 image_scan / image_ocr 引导；找不到、前缀歧义或非图片对象时保持原文本，不猜测路径。

• 修复全局 SHA 匹配正则的状态残留，避免同轮多次检测后遗漏附件。

• 新增 SHA 降级恢复与无效 SHA 保持原文本的回归用例；npm test 全量 148 通过 / 0 失败。

v3.3.1

• 元数据修正：npm description 中 OCR 引擎数量更正为 ×4（windows / macos / paddle / rapid）。

v3.3.0

• 新增 macOS 原生 Vision OCR 引擎：engine="macos"（scripts/macos-ocr.swift + scripts/setup-macos.mjs 一键编译，默认中文优先、BCP-47 language 参数、像素坐标框契约与 paddle/rapid 一致），供 macOS 用户零第三方依赖使用（PR #4 合入）。
• OCR 引擎按平台条件显示：设置卡 windows 引擎仅 Windows、macos 引擎仅 macOS（paddle/rapid 跨平台始终显示），未配置时默认平台原生引擎；跨平台迁移旧配置自动回落。
• 修复 PaddleOCR 新环境首次调用必失败（issue #2）：① AI Studio 下载源的 <Response [404]> stdout 污染 → 解码前过滤非 base64 行；② paddle 输出 w/h → 改为 schema 要求的 width/height；③ paddleCacheHome() 默认路径从作者开发机改为 ~/.paddlex-cache。
• peerDependencies 兼容 DSH 0.1.1-rc.2（issue #3）：^0.1.0-rc.6 || ^0.1.1-rc.2 联合区间。
• 设置卡 UI 重做：settings-panel 设计语言（卡片分组、胶囊按钮、32px 输入框、chevron 下拉、折叠箭头）；scope.load() 兼容无 load 宿主（EAC 桌面壳）。
• 调试日志门控：llm/stream 图片桥诊断日志改由 debug 设置项控制，默认不再刷屏。

v3.2.0

• 新增 image_edit 本地修图工具：22 种纯 CPU 动作（Pillow + OpenCV-headless，可选 rembg / rawpy / realesrgan CLI）——P0 基础（resize/rotate/flip/convert/adjust/blur/sharpen/composite/watermark/thumbnail）、P1 进阶（edges/equalize_hist/denoise/perspective/stitch/remove_background）、P2 高级（exif_read/write/raw_convert/upscale/colorspace/morphology）。
• 新增 scripts/setup-image-venv.mjs（--full 装 rembg+rawpy）与 scripts/image-edit.py 后端。
• 新增环境变量 DSH_IMAGE_PYTHON / DSH_REALESRGAN_EXE。
• 新增 tests/image-edit.test.js 单测 8 项 + 后端 24/24 冒烟，全部通过。

v3.1.x（前版）

• v3.1.0：新增 read_image 工具拦截（避免 image block 触发 UNSUPPORTED_CONTENT）；内置 image-reading 技能注册；内置依赖安装完整性修复落地。

v3.0.x（前版）

• v3.0.6：修复依赖安装完整性（jpeg-js/omggif/pngjs 随插件预装），图析功能不再静默失败。
• v3.0.5：修复 scope.load() 兼容（设置页「图片阅读」空白）。
• v3.0.4：Code Mode 工具折叠兼容说明。
• v3.0.3：设置持久化修复、PaddleOCR 字段名、本地 VLM 端点检测、cordis4 兼容。
• v3.0.0：视觉孪生 adapter、三模式路由、本地工具链、文档转图片、3 引擎 OCR、设置卡。

开发 / 仓库布局

# 本仓库 main（DSH 版，源码位于仓库根目录）
npm install
npm test                       # node:test
node scripts/setup-ocr.mjs     # 可选（PaddleOCR）
node scripts/setup-rapid.mjs   # 可选（RapidOCR）
node scripts/setup-macos.mjs   # 可选（仅 macOS Vision OCR）
node scripts/setup-doc-venv.mjs# 可选（文档转换）
node scripts/setup-image-venv.mjs  # 可选（本地修图 image_edit，--full 加 rembg/rawpy）
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