前言¶
在 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
