本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

picturereader

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add picturereader

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• Proxy 原位包装：对被勾选的模型所属 provider，用 Proxy 把其 adapter 包装成「孪生」并原位替换（registerTwinAdapters，卸载经 ctx.effect 还原），不重复注册。
• listModels / resolveModel：对被勾选模型声明 inputModalities: ['text','image']、名称加「(视觉)」后缀 → DSH 认为它支持图片 → 原生缩略图渲染、图片块进会话、粘贴准入全部解锁。
• 隐私模式下分析只走本地工具，绝不外发。
• 绝不调用任何外部视觉端点，即使你在设置卡配了 API。
• 约束是 host 侧强制：runtime.js 使 isVlmConfigured() 恒为 false，vision_analyze 强制 include_vlm=false，视觉孪生 stream 的降级文本也明确"只用本地工具"。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

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

不必须。内置 Windows OCR 引擎开箱即用；PaddleOCR、RapidOCR、文档转图片依赖才需要先跑 scripts/setup-*.mjs 建 Python venv。源码 README.md:144-159 / src/index.js 全文。

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

隐私模式是 host 侧硬门禁：src/runtime.js 让 isVlmConfigured() 在此模式恒返回 false，vision_analyze 强制把 include_vlm 改 false，图片桥引导也写明"只用本地工具"，即便设置卡里填了 baseURL/Key 也不会发图片字节出去。src/runtime.js:24-127 / README.md:62-66。

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

dsh plugin 命令移除条目即可。插件会在 ~/.dsh/picturereader-vision/images/ 存导出的图片、在 ~/.dsh/settings.yaml 写自己命名空间下的小节；彻底清理需手动删除上述目录并把 settings.yaml 中 picturereader 段移除（README.md:269-276、src/picturereader-vision.mjs:21-22）。

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

vision_models 改动不会热加载，必须重启 DSH 桌面端（README.md:218-222、274-275）；并且模式选为代码（code）时插件仍生效，只是要通过 await tools.image_scan(...) 程序内调用而非直呼。

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

转为 PNG 或 JPEG 后再传。源码 src/core.js:316 明确把 .webp 列入 UNSUPPORTED_EXTENSIONS 并直接抛错，image_scan/image_ocr/image_batch/document_to_image 都遵守同一规则。src/core.js:316 / src/image-batch.js:297-301。

配置文件里的 vlm_key 安全吗？

字段声明为 role:'secret'，且代码里只写不读、不回显；可用 vlm_key_env 让插件从你指定的环境变量名读取，凭据不再进 y 文件。src/index.js:74-78、src/config.js:62-69。

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

不会，picturereader 视觉孪生只对 vision_models 列表里勾选的那几个模型生效，并把其 provider 的 adapter 用 Proxy 改成"孪生"，未勾选模型不受影响。src/picturereader-vision.mjs:108-163。

单张图最大能处理多大？

工具层硬上限为 50 MB、24,000,000 解码像素；DSH 附件上传侧约 5 MB，超大图会被宿主拦截，可先用 image_crop 切图或降低分辨率再传。src/tool.js:19-21、src/image-batch.js:297-314。

— 源: plugin_wiki.faq_json

兼容性

• DSH: 0.1.0-rc.6+（peerDependencies 声明 @deepseek-ai/dsh-settings ^0.1.0-rc.6、@deepseek-ai/dsh-llm ^0.1.0-rc.6）
• Node: ^22.19 || >=24（engines.node 字段）

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则