picturereader 1.0.2 → 2.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 picturereader
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 picturereader
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,24 +1,34 @@
 # picturereader
 
-> 给纯文本模型（如 deepseek-v4-flash）的"读图"能力——**双版本发布**：
-> - **DSH 版**：DeepSeek Harness 插件（`dsh-plugin`，含 DSH EAC 桌面端）
-> - **ZCode 版**：ZCode 桌面端插件（`zcode-plugin`，经 MCP 暴露工具）
+> **v2.0.0** —— 给纯文本模型（如 deepseek-v4-flash）的**全能"读图"能力**。
+> 融合 **独立伪多模态识图** 与 **外部视觉 API 接口**，一个插件搞定全部，**无需另装任何插件**。
 
-> 把图片 **降分辨率 + 降色深 + 结构/色彩指纹提取**，渲染成文本网格喂回对话，
-> 让模型像多模态模型一样"看"图：描述场景、主体、环境、光线与语义内容。
-> **纯本地、零外部模型依赖、零 API key、零 Python（PaddleOCR 为可选增强）**。
+> - **DSH 版**：DeepSeek Harness 插件（`dsh-plugin`，含 DSH EAC 桌面端）—— 本分支（main）
+> - **ZCode 版**：ZCode 桌面端插件（`zcode-plugin`，经 MCP 暴露工具）—— [zcode 分支](https://github.com/jing-hy/picturereader/tree/zcode)
 
 [![dsh-plugin](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
 
+## 本轮工作（v2.0.0 新增）
+
+在原有的**本地伪多模态识图**（像素扫描 + OCR + 取样，零外部依赖）之上，融合了社区 `dsh-universal-vision` 的优势，形成一套**统一、可交叉验证的完整识图栈**：
+
+1. **新增外部视觉 API 接口**（`vlm.js`）：桥接任意 OpenAI 兼容的视觉端点（本地 llama-server / LM Studio / vLLM / 云端网关），让模型获得真正的**语义理解**能力（场景、角色、界面、风格）。
+2. **新增统一分析工具 `vision_analyze`**（`vision-analyze.js`）：一次调用即可取回「低信息拦截 + 像素扫描 + OCR + VLM」多路证据。
+3. **新增低信息量拦截**（`guard.js`）：自动识别空白/未渲染/简单图片，避免小 VLM 在空图上幻觉，也节省调用成本。
+4. **证据交叉验证**：VLM 描述与像素/OCR 实测冲突时，以实测为准——伪多模态与真 VLM 互为印证，抑制幻觉。
+5. **多次提问**：可对同一张图用 `vision_analyze` 以不同 `prompt` 反复提问，从多角度复核同一内容。
+
+> **核心优势一句话**：**独立伪多模态识图（零依赖、可离线） + 外部 API 语义接口（可选、即插即用）** —— 简单图用像素就够，复杂图一键接 VLM，一个插件全包含，不需要再装 `dsh-universal-vision` 或任何其他读图插件。
+
 ## 版本总览
 
 | 版本 | 平台 | 形态 | 源码 | 安装 |
 |---|---|---|---|---|
-| **DSH 版** | DeepSeek Harness（含 EAC 桌面端） | npm 插件（`dsh.bundle`） | 仓库根目录 | `dsh plugin --profile web add picturereader` |
-| **ZCode 版** | ZCode 桌面端 | 本地 marketplace 插件（MCP server + skill） | [jing-hy/picturereader-zcode](https://github.com/jing-hy/picturereader-zcode)（独立仓库） | 见其 README |
+| **DSH 版** | DeepSeek Harness（含 EAC 桌面端） | npm 插件（`dsh.bundle`） | 本仓库（main） | `dsh plugin --profile web add picturereader` |
+| **ZCode 版** | ZCode 桌面端 | 本地 marketplace 插件（MCP server + skill） | [zcode 分支](https://github.com/jing-hy/picturereader/tree/zcode) | `npm install picturereader-zcode` |
 
 两个版本共用同一套业务核心（`src/core.js`）与读图方法论 skill（`image-reading`），
-三个工具行为完全一致：`image_scan` / `image_ocr` / `image_sample`。
+四个工具行为完全一致：`image_scan` / `image_ocr` / `image_sample` / `vision_analyze`。
 
 > **ZCode 版性能说明**：ZCode 版通过 MCP（stdio 子进程）暴露工具，每次调用都要
 > 经历进程通信与序列化开销，**速度明显慢于 DSH 版**（DSH 版为插件内直接调用）。
@@ -32,7 +42,8 @@ DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturer
 2. **主动找主体**：px_per_cell 定向放大（深色/低对比/小色块不会漏）
 3. **文字验证**：PaddleOCR 实读（防多模态幻觉）
 4. **材质判断**：image_sample 像素取样
-5. **综合描述**：带证据等级的连贯画面描述
+5. **（可选）VLM 语义理解**：外部视觉 API 提供场景/角色/界面/风格的自然语言描述
+6. **综合描述**：带证据等级的连贯画面描述，伪多模态与 VLM 交叉验证
 
 ## 工具
 
@@ -41,6 +52,7 @@ DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturer
 | `image_scan` | 全局/区域扫描：亮度/颜色网格 + regions 色块 + shade diversity + texture mix + structure（条纹/对称） + **像素级 colors** + **hue families 纯色指纹**；支持 `focus`/`region` 局部放大、`px_per_cell` 像素密度定向放大 |
 | `image_ocr` | 文字识别双引擎：`windows`（内置，默认）/ `paddle`（选装，发光/弯曲/游戏字更强），失败自动降级不崩溃 |
 | `image_sample` | 8×8 精确像素取样，判断材质/纹理（金属/木纹/织物/皮肤/噪点） |
+| `vision_analyze` | **统一入口（v2.0.0 新增）**：低信息拦截 + 可选像素扫描/OCR/VLM，组合证据返回；VLM 可选配置 |
 
 ### 读图方法论 skill（image-reading）
 
@@ -50,6 +62,7 @@ DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturer
 - **hue 场景指纹**：cyan 高=水/雾/湖泊，green 高=森林，orange/red 高=暖色人物/火光，blue 高=夜空科幻，achromatic+rough=废墟，green+yellow=翠绿能量/浮空仙境
 - **多模态模型校验规则**：游戏名/品牌等文字必须 OCR 实读（多模态模型会猜错）；发光元素颜色以 hue 实测为准（多模态模型对发光色的描述系统性不可靠）；低对比主体（暗色人物/小色块）必须放大确认
 - **主动验证**：低对比主体（暗色人物/小色块）必须放大确认
+- **vision_analyze 使用**（v2.0.0）：先 image_scan 自己看，简单图用像素，复杂图再调 VLM；描述与实测冲突时以实测为准
 
 ## 安装
 
@@ -67,25 +80,44 @@ copy skills\image-reading.md %USERPROFILE%\.dsh\skills\   # Windows
 # 3.（可选）PaddleOCR 增强引擎：node scripts/setup-ocr.mjs
 ```
 
-重启 DSH Desktop 后，模型工具列表出现 `image_scan` / `image_ocr` / `image_sample`，
+重启 DSH Desktop 后，模型工具列表出现 `image_scan` / `image_ocr` / `image_sample` / `vision_analyze`，
 技能目录出现 `image-reading`。
 
 ### ZCode 版
 
-ZCode 版是**独立仓库**：[jing-hy/picturereader-zcode](https://github.com/jing-hy/picturereader-zcode)。
+ZCode 版位于本仓库的 **[zcode 分支](https://github.com/jing-hy/picturereader/tree/zcode)**。
 
-ZCode 版通过 **MCP server**（`mcp/server.js`，stdio）把三个工具暴露给 ZCode，
+ZCode 版通过 **MCP server**（`mcp/server.js`，stdio）把四个工具暴露给 ZCode，
 读图方法论作为 **skill**（`skills/image-reading/`）随插件分发，业务逻辑 `src/core.js`
-与本仓库完全一致。安装与使用请见其 README。
+与 DSH 版完全一致。安装：`npm install picturereader-zcode`。
 
 ## 使用
 
 直接对模型说：
 
 > 用 image_scan 看一下 <路径> 这张图，细看感兴趣的部分
+> （复杂场景可接着用 vision_analyze 获取语义描述并交叉验证）
 
 模型会加载 `image-reading` 方法论自动执行完整流程（定调 → 找主体 → 验证 → 描述）。
 
+### vision_analyze 用法（v2.0.0）
+
+```
+vision_analyze(
+  file_path="C:/shot.png",
+  prompt="描述这个界面，有哪些元素？布局是否正常？",
+  include_scan=true,    # 像素扫描证据（默认 true）
+  include_ocr=true,     # OCR 文字证据（默认 false）
+  include_vlm=true,     # 外部 VLM 语义描述（默认 true，但未配置 SEE_BASE 时自动跳过）
+  allow_low_info=false, # 空白/简单图是否强制调 VLM（默认 false）
+  stop_after=false      # 调用后是否关闭本插件启动的本地服务器
+)
+```
+
+- **先自己看，再决定**：建议先用 `image_scan` 了解图片，简单图用像素就够；复杂/精密场景再开 VLM。
+- **多次提问**：对同一张图换不同 `prompt` 反复调用，从多角度复核。
+- **交叉验证**：VLM 描述与像素/OCR 冲突时，以实测为准。
+
 ## 输出示例
 
 ```
@@ -98,25 +130,38 @@ colors by area: ...（像素级真实占比）
 luminance grid / color grid
 ```
 
-## 环境变量（ZCode 版）
+## 环境变量
+
+### PaddleOCR（可选）
 
 | 变量 | 默认值 | 作用 |
 |---|---|---|
 | `DSH_PADDLE_PYTHON` | `C:\Users\Administrator\paddle_venv\Scripts\python.exe` | PaddleOCR 解释器路径（与原插件同名，便于直接迁移） |
 | `DSH_PADDLE_CACHE` | `<插件目录>\.paddlex-cache` | PaddleX 模型缓存目录 |
 
+### 外部视觉 API / VLM（可选，**默认不配置**）
+
+| 变量 | 默认值 | 作用 |
+|---|---|---|
+| `SEE_BASE` | `（空）` | OpenAI 兼容视觉端点（留空 = VLM 禁用；本地 llama-server / LM Studio / vLLM / 云端网关） |
+| `SEE_MODEL` | `（空）` | 视觉模型名（如 `google/gemma-4-12b-qat`） |
+| `SEE_API_KEY` | `（空）` | API key（本地端点可随便填，云端需要真实 key） |
+| `SEE_SERVER_EXE` / `SEE_SERVER_MODEL` / `SEE_SERVER_MMPROJ` | `（空）` | 本地 llama-server 自启路径（可选，配置后插件可自动拉起本地视觉服务器） |
+| `SEE_SERVER_PORT` / `SEE_SERVER_NGL` / `SEE_SERVER_CTX` | `8080` / `20` / `16384` | 本地服务器参数 |
+
+> **VLM 配置说明**：默认不配置 VLM，`vision_analyze` 会跳过 VLM 调用，只返回像素扫描和 OCR 证据（保持零外部依赖）。需要语义理解时，设置 `SEE_BASE` + `SEE_MODEL` 即可，例如指向本地 LM Studio（`http://127.0.0.1:1234/v1`）。
+
 ## 开发
 
 ```sh
 # DSH 版（本仓库）
 npm install
-npm test            # node:test，76 个测试全绿
+npm test            # node:test
 node scripts/setup-ocr.mjs   # 可选：装 PaddleOCR
 node scripts/preview.mjs     # 生成 fixtures 并预览渲染
 
-# ZCode 版（独立仓库 jing-hy/picturereader-zcode）
-git clone https://github.com/jing-hy/picturereader-zcode.git
-cd picturereader-zcode
+# ZCode 版（本仓库 zcode 分支）
+git checkout zcode
 npm install
 npm test            # node:test
 node scripts/setup-ocr.mjs   # 可选
@@ -127,32 +172,27 @@ node scripts/setup-ocr.mjs   # 可选
 下次调用即生效**；工具定义（schema/描述）改动需重启桌面端。
 
 **热插拔（ZCode 版）**：MCP server 从所选目录运行，改 `src/core.js` 下次调用即生效
-（详见 picturereader-zcode 仓库 README）。
+（详见 zcode 分支 README）。
 
 ## 优势
 
-- **零外部模型依赖**：核心链路（扫描/取样/解码）纯本地纯 JS，不调任何视觉 API；
-  语义理解完全交给主模型（DeepSeek），不依赖 YOLO 等固定类别检测器（遇未知物体不失效）
-- **可追溯、可验证**：每个结论都有数据支撑（hue 占比、色块坐标、OCR 文本+置信度），
-  能主动识别并纠正多模态模型的幻觉（游戏名乱猜、发光颜色误标、小字脑补）
-- **隐私友好**：原始图片不出本机，只有降采样文本进模型上下文
+- **一个插件全包含，无需另装**：独立的伪多模态识图 + 可选外部视觉 API，融合在一个包里，不需要再装 `dsh-universal-vision` 或其他读图插件
+- **核心链路零外部依赖**：扫描/取样/解码纯本地纯 JS，不调任何视觉 API；语义理解要么交给主模型（DeepSeek），要么按需桥接你自己的 VLM
+- **可选 VLM / 外部 API**：默认不配置保持纯本地；配了 `SEE_BASE` 即接入语义理解，本地/云端 OpenAI 兼容端点通吃
+- **低信息量拦截**（v2.0.0）：自动识别空白/简单图，避免小 VLM 幻觉、省调用成本
+- **可追溯、可验证**：每个结论都有数据支撑（hue 占比、色块坐标、OCR 文本+置信度），VLM 描述与像素/OCR 交叉验证
+- **隐私友好**：默认模式下原始图片不出本机，只有降采样文本进模型上下文
 - **成本低**：一次扫描 ≈0.6–2.2K tokens；PaddleOCR 本地跑，无 API 费用
-- **可选增强**：PaddleOCR 一键安装（`scripts/setup-ocr.mjs`），缺失自动降级不崩溃
-- **方法论沉淀**：附带的 image-reading skill 把读图经验固化（场景指纹/校验规则），
-  模型每次看图都带着经过大量图片验证的经验
+- **方法论沉淀**：附带的 image-reading skill 把读图经验固化（场景指纹/校验规则），模型每次看图都带着经过大量图片验证的经验
 
 ## 局限性（重要）
 
-- **不是真正的视觉模型**：文本网格信息量有限，**人脸/表情/花纹等像素级细节读不出**；
-  这是文本模态的硬上限，放大（px_per_cell）只能缩小差距，不能消除
-- **语义推断依赖主模型能力**：物体识别（"这是树/空间站"）是 LLM 基于结构证据的推测，
-  不是视觉模型的确证——复杂/罕见物体可能推断错误
-- **OCR 引擎边界**：Windows OCR 对发光/弯曲/艺术字失效；PaddleOCR 强很多但需选装，
-  且对极小文字/极端艺术字仍可能失败（可配合放大）
-- **性能**：4K 图解码 ~230ms；PaddleOCR 每次调用需 ~2s 加载模型；大图网格渲染
-  token 随 size 增长（64×64 color ≈ 3–5K tokens）
-- **ZCode 版 MCP 开销**：ZCode 版工具经 MCP stdio 子进程通信，单次调用比 DSH 版慢
-  （进程启动 + JSON-RPC 序列化）；高频/批量看图建议用 DSH 版
+- **不是真正的视觉模型**：伪多模态部分文本网格信息量有限，**人脸/表情/花纹等像素级细节读不出**；这是文本模态的硬上限，放大（px_per_cell）只能缩小差距，不能消除
+- **语义推断依赖主模型或外部 API 能力**：物体识别是 LLM 基于结构证据的推测，不是视觉编码器的确证；接入 VLM 可大幅增强，但外部 API 也可能出错
+- **VLM 可选即插即用**：未配置 `SEE_BASE` 时无语义描述；配置后依赖端点可用性与网络/本地资源
+- **OCR 引擎边界**：Windows OCR 对发光/弯曲/艺术字失效；PaddleOCR 强很多但需选装，且对极小文字/极端艺术字仍可能失败（可配合放大）
+- **性能**：4K 图解码 ~230ms；PaddleOCR 每次调用需 ~2s 加载模型；VLM 调用需 2-5s（取决于端点）；大图网格渲染 token 随 size 增长（64×64 color ≈ 3–5K tokens）
+- **ZCode 版 MCP 开销**：ZCode 版工具经 MCP stdio 子进程通信，单次调用比 DSH 版慢；高频/批量看图建议用 DSH 版
 - **WebP 不支持**（提示转 PNG/JPEG）；GIF 只读首帧
 - **多模态模型的描述不可全信**（本插件可交叉验证，但最终语义仍需人工判断关键场景）
 

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# picturereader — bundle patch: inserts the image_scan plugin row.
-- insert:
-    - id: picturereader
-      name: 'picturereader'
+# picturereader — bundle patch: inserts the image_scan plugin row.
+- insert:
+    - id: picturereader
+      name: 'picturereader'

package/package.json

@@ -1,7 +1,7 @@
 {
     "name":  "picturereader",
-    "version":  "1.0.2",
-    "description":  "DSH plugin: pixel-to-text image reading for text-only models. Downscales and color-quantizes PNG/JPEG/GIF/BMP and feeds the coarse pixel grid to the model so DeepSeek can \u0027see\u0027 layout, colors and rough shapes without a vision model.",
+    "version":  "2.0.0",
+    "description":  "Unified image understanding plugin for DeepSeek Harness (DSH). Fuses frame-free pseudo-multimodal reading (pixel scan + OCR + sample) with an optional external vision API bridge (local llama-server / LM Studio / any OpenAI-compatible endpoint) for full semantic understanding. No extra plugin needed.",
     "type":  "module",
     "main":  "src/index.js",
     "exports":  {
@@ -11,6 +11,7 @@
                 },
     "files":  [
                   "src",
+                  "scripts",
                   "cordis.patch.yml",
                   "skills",
                   "README.md",
@@ -30,7 +31,10 @@
                      "ocr",
                      "paddleocr",
                      "hue",
-                     "multimodal"
+                     "multimodal",
+                     "vlm",
+                     "vision-analyze",
+                     "llm-vision"
                  ],
     "license":  "MIT",
     "author":  "picturereader",

package/scripts/preview.mjs

@@ -0,0 +1,40 @@
+/**
+ * Generate fixture images on disk and print the image_scan render for a
+ * quick visual sanity check without booting a harness.
+ * Usage: node scripts/preview.mjs
+ * @module picturereader/scripts/preview
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyzeImage, renderImageScan } from '../src/core.js';
+import { makeChartRgba, makeQuadrantRgba, pngFromRgba, jpegFromRgba, gifFromRgba, bmpFromRgba } from '../tests/fixtures.mjs';
+
+const outDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'tests', 'fixtures-out');
+mkdirSync(outDir, { recursive: true });
+
+const images = [
+  { name: 'chart', width: 600, height: 400, rgba: makeChartRgba(), formats: ['png', 'jpeg', 'gif', 'bmp'] },
+  { name: 'quadrant', width: 100, height: 100, rgba: makeQuadrantRgba(), formats: ['png'] }
+];
+
+for (const image of images) {
+  for (const format of image.formats) {
+    const buffer =
+      format === 'png' ? pngFromRgba(image.width, image.height, image.rgba)
+        : format === 'jpeg' ? jpegFromRgba(image.width, image.height, image.rgba)
+          : format === 'gif' ? gifFromRgba(image.width, image.height, image.rgba)
+            : bmpFromRgba(image.width, image.height, image.rgba, 24);
+    writeFileSync(join(outDir, `${image.name}.${format}`), buffer);
+  }
+  const analysis = analyzeImage(image.rgba, image.width, image.height, { size: 32, mode: 'auto', region: undefined });
+  console.log(renderImageScan({
+    path: join(outDir, `${image.name}.png`),
+    width: image.width,
+    height: image.height,
+    region: 'full',
+    ...analysis
+  }));
+  console.log();
+}

package/scripts/setup-ocr.mjs

@@ -0,0 +1,96 @@
+/**
+ * Optional install helper for the PaddleOCR engine (image_ocr engine="paddle").
+ * PaddleOCR is RECOMMENDED (far better at glowing/curved/game text) but
+ * OPTIONAL — image_ocr degrades to the Windows engine when it is missing.
+ *
+ * What this does:
+ *  1. Ensures a Python 3.12+ interpreter exists (downloads the official
+ *     3.12.10 installer from the npmmirror mirror if missing).
+ *  2. Creates/repairs the paddle_venv.
+ *  3. Installs paddlepaddle + paddleocr from the Tsinghua PyPI mirror.
+ *  4. Warms the model cache by running one recognition on a test image.
+ *
+ * Usage: node scripts/setup-ocr.mjs
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PY312 = 'C:\\Users\\Administrator\\Python312\\python.exe';
+const VENV = 'C:\\Users\\Administrator\\paddle_venv\\Scripts\\python.exe';
+const INSTALLER = 'C:\\Users\\Administrator\\Downloads\\python-3.12.10-amd64.exe';
+const INSTALLER_URL = 'https://registry.npmmirror.com/-/binary/python/3.12.10/python-3.12.10-amd64.exe';
+const PYPI = 'https://pypi.tuna.tsinghua.edu.cn/simple';
+const CACHE = join(dirname(fileURLToPath(import.meta.url)), '..', '.paddlex-cache');
+
+function run(cmd, args, opts = {}) {
+  console.log(`> ${cmd} ${args.join(' ')}`);
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.status !== 0) {
+    console.error(`!! command failed (exit ${result.status})`);
+    process.exit(1);
+  }
+}
+
+// 1. base Python 3.12
+if (!existsSync(PY312)) {
+  console.log('[1/4] Python 3.12 missing — downloading installer (npmmirror mirror)...');
+  run('curl.exe', ['-L', '-o', INSTALLER, INSTALLER_URL]);
+  console.log('[1/4] Installing Python 3.12 to C:\\Users\\Administrator\\Python312 (user-level, silent)...');
+  spawnSync(INSTALLER, [
+    '/quiet', 'InstallAllUsers=0', 'TargetDir=C:\\Users\\Administrator\\Python312',
+    'Include_pip=1', 'PrependPath=0', 'Include_test=0', 'Include_launcher=0'
+  ], { stdio: 'inherit' });
+  if (!existsSync(PY312)) {
+    console.error('!! Python install did not produce ' + PY312);
+    process.exit(1);
+  }
+} else {
+  console.log('[1/4] Python 3.12 found at ' + PY312);
+}
+
+// 2. venv
+if (!existsSync(VENV)) {
+  console.log('[2/4] Creating paddle_venv...');
+  mkdirSync(dirname(VENV), { recursive: true });
+  run(PY312, ['-m', 'venv', 'C:\\Users\\Administrator\\paddle_venv']);
+} else {
+  console.log('[2/4] paddle_venv found');
+}
+
+// 3. paddlepaddle + paddleocr
+const probe = spawnSync(VENV, ['-c', 'import paddleocr; print(paddleocr.__version__)'], { encoding: 'utf8' });
+if (probe.status !== 0) {
+  console.log('[3/4] Installing paddlepaddle + paddleocr (Tsinghua mirror, ~1-3 min)...');
+  run(VENV, ['-m', 'pip', 'install', '-i', PYPI, '--upgrade', 'pip']);
+  run(VENV, ['-m', 'pip', 'install', '-i', PYPI, 'paddlepaddle==3.3.1', 'paddleocr']);
+} else {
+  console.log(`[3/4] paddleocr already installed (${probe.stdout.trim()})`);
+}
+
+// 4. warm the model cache with one recognition
+console.log('[4/4] Warming the model cache (first run downloads detection/recognition models)...');
+const testImage = join(dirname(fileURLToPath(import.meta.url)), '..', 'tests', 'fixtures-out', 'ocr-test.png');
+mkdirSync(join(CACHE), { recursive: true });
+if (existsSync(testImage)) {
+  const warm = spawnSync(VENV, ['-c', [
+    'from paddleocr import PaddleOCR',
+    "ocr = PaddleOCR(lang='ch', use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, enable_mkldnn=False)",
+    `result = ocr.predict(r'${testImage.replaceAll("'", "''")}')`,
+    'print("warm-up OCR ok, lines:", sum(len(r.get("rec_texts") or []) for r in result))'
+  ].join('; ')], {
+    env: { ...process.env, PADDLE_PDX_CACHE_HOME: CACHE, PYTHONIOENCODING: 'utf-8' },
+    encoding: 'utf8'
+  });
+  if (warm.status !== 0) {
+    console.error('!! warm-up failed — see output above; the engine may still work once models download');
+    process.exit(1);
+  }
+  console.log(warm.stdout.trim());
+} else {
+  console.log('[4/4] test image missing — skip warm-up (first image_ocr paddle call will download models)');
+}
+
+console.log('\nDone. image_ocr engine="paddle" is now available.');
+console.log('Verify: ask the model to read an image with image_ocr(engine="paddle").');