picturereader-zcode 1.0.3 → 2.0.0

package/README.md

@@ -1,24 +1,33 @@
-# picturereader
+# picturereader（ZCode 版）
 
-> 给纯文本模型（如 deepseek-v4-flash）的"读图"能力——**双版本发布**：
-> - **DSH 版**：DeepSeek Harness 插件（`dsh-plugin`，含 DSH EAC 桌面端）
-> - **ZCode 版**：ZCode 桌面端插件（`zcode-plugin`，经 MCP 暴露工具）
+> **v2.0.0** —— 给纯文本模型（如 deepseek-v4-flash）的**全能"读图"能力**。
+> 融合 **独立伪多模态识图** 与 **外部视觉 API 接口**，一个插件搞定全部，**无需另装任何插件**。
+> 本分支为 **ZCode 桌面端插件**（经 MCP 暴露工具）；DSH 版见 [main 分支](https://github.com/jing-hy/picturereader)。
 
-> 把图片 **降分辨率 + 降色深 + 结构/色彩指纹提取**，渲染成文本网格喂回对话，
-> 让模型像多模态模型一样"看"图：描述场景、主体、环境、光线与语义内容。
-> **纯本地、零外部模型依赖、零 API key、零 Python（PaddleOCR 为可选增强）**。
+> - **DSH 版**：DeepSeek Harness 插件（`dsh-plugin`，含 DSH EAC 桌面端）—— [main 分支](https://github.com/jing-hy/picturereader)
+> - **ZCode 版**：ZCode 桌面端插件（`zcode-plugin`，经 MCP 暴露工具）—— 本分支
 
-[![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 接口**（`src/vlm.js`）：桥接任意 OpenAI 兼容的视觉端点（本地 llama-server / LM Studio / vLLM / 云端网关），让模型获得真正的**语义理解**能力（场景、角色、界面、风格）。
+2. **新增统一分析工具 `vision_analyze`**：一次调用即可取回「低信息拦截 + 像素扫描 + OCR + VLM」多路证据。
+3. **新增低信息量拦截**（`src/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 分支](https://github.com/jing-hy/picturereader) | `dsh plugin --profile web add picturereader` |
+| **ZCode 版** | ZCode 桌面端 | 本地 marketplace 插件（MCP server + skill） | 本分支 | `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 版为插件内直接调用）。
@@ -26,13 +35,14 @@
 
 ## 这是什么
 
-DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturereader 把"看图"翻译成**模型能理解的结构化文本证据**，并提供一套经过大量真实图片迭代验证的**读图方法论 skill（image-reading）**，让模型像人一样分步看图：
+纯文本模型没有视觉编码器，无法直接看图。picturereader 把"看图"翻译成**模型能理解的结构化文本证据**，并提供一套经过大量真实图片迭代验证的**读图方法论 skill（image-reading）**，让模型像人一样分步看图：
 
 1. **全局定调**：hue families（纯色指纹）→ structure（条纹/对称）→ texture（写实度）→ regions（色块结构）
 2. **主动找主体**：px_per_cell 定向放大（深色/低对比/小色块不会漏）
 3. **文字验证**：PaddleOCR 实读（防多模态幻觉）
 4. **材质判断**：image_sample 像素取样
-5. **综合描述**：带证据等级的连贯画面描述
+5. **（可选）VLM 语义理解**：外部视觉 API 提供场景/角色/界面/风格的自然语言描述
+6. **综合描述**：带证据等级的连贯画面描述，伪多模态与 VLM 交叉验证
 
 ## 工具
 
@@ -41,50 +51,59 @@ 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）
 
-`skills/image-reading.md`（DSH 版）/ `skills/image-reading/SKILL.md`（ZCode 版）是一套**经大量真实图片场景迭代验证**的读图方法论
+`skills/image-reading/SKILL.md`（ZCode 版）是一套**经大量真实图片场景迭代验证**的读图方法论
 （按 experience / skill / principle / insight 分层，教训有据可依、找得到主模型模式），
 安装后模型自动掌握：
 - **hue 场景指纹**：cyan 高=水/雾/湖泊，green 高=森林，orange/red 高=暖色人物/火光，blue 高=夜空科幻，achromatic+rough=废墟，green+yellow=翠绿能量/浮空仙境
 - **多模态模型校验规则**：游戏名/品牌等文字必须 OCR 实读（多模态模型会猜错）；发光元素颜色以 hue 实测为准（多模态模型对发光色的描述系统性不可靠）；低对比主体（暗色人物/小色块）必须放大确认
 - **主动验证**：低对比主体（暗色人物/小色块）必须放大确认
+- **vision_analyze 使用**（v2.0.0）：先 image_scan 自己看，简单图用像素，复杂图再调 VLM；描述与实测冲突时以实测为准
 
 ## 安装
 
-### DSH 版
+ZCode 版通过 **MCP server**（`mcp/server.js`，stdio）把四个工具暴露给 ZCode，
+读图方法论作为 **skill** 随插件分发，业务逻辑 `src/core.js` 与 DSH 版完全一致。
 
 ```sh
-# 1. 插件
-dsh plugin --profile web add picturereader        # 或从源码: dsh plugin --profile web add .
-dsh plugin --profile headless add picturereader
-
-# 2. 读图方法论 skill（推荐）
-copy skills\image-reading.md %USERPROFILE%\.dsh\skills\   # Windows
-# macOS/Linux: cp skills/image-reading.md ~/.dsh/skills/
-
-# 3.（可选）PaddleOCR 增强引擎：node scripts/setup-ocr.mjs
+npm install picturereader-zcode
 ```
 
-重启 DSH Desktop 后，模型工具列表出现 `image_scan` / `image_ocr` / `image_sample`，
-技能目录出现 `image-reading`。
-
-### ZCode 版
+### （可选）PaddleOCR 增强引擎
 
-ZCode 版是**独立仓库**：[jing-hy/picturereader-zcode](https://github.com/jing-hy/picturereader-zcode)。
+```sh
+node scripts/setup-ocr.mjs
+```
 
-ZCode 版通过 **MCP server**（`mcp/server.js`，stdio）把三个工具暴露给 ZCode，
-读图方法论作为 **skill**（`skills/image-reading/`）随插件分发，业务逻辑 `src/core.js`
-与本仓库完全一致。安装与使用请见其 README。
+PaddleOCR 缺失时 `image_ocr` 自动降级为 Windows OCR。
 
 ## 使用
 
-直接对模型说：
+对 ZCode 模型说：
 
 > 用 image_scan 看一下 <路径> 这张图，细看感兴趣的部分
+> （复杂场景可接着用 vision_analyze 获取语义描述并交叉验证）
+
+### vision_analyze 用法（v2.0.0）
 
-模型会加载 `image-reading` 方法论自动执行完整流程（定调 → 找主体 → 验证 → 描述）。
+```
+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,61 +117,56 @@ 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 个测试全绿
-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
-npm install
-npm test            # node:test
+npm test            # node:test（DSH 版 76 个测试全绿）
 node scripts/setup-ocr.mjs   # 可选
 ```
 
-**热插拔（DSH 版）**：DSH 本身不支持代码热重载，但本插件自带执行层热加载——业务逻辑全在
-`src/core.js` 单文件，工具每次执行按 mtime 动态加载（cache-bust），**改 core.js
-下次调用即生效**；工具定义（schema/描述）改动需重启桌面端。
-
 **热插拔（ZCode 版）**：MCP server 从所选目录运行，改 `src/core.js` 下次调用即生效
-（详见 picturereader-zcode 仓库 README）。
+（详见 zcode 分支 README）。
 
 ## 优势
 
-- **零外部模型依赖**：核心链路（扫描/取样/解码）纯本地纯 JS，不调任何视觉 API；
-  语义理解完全交给主模型（DeepSeek），不依赖 YOLO 等固定类别检测器（遇未知物体不失效）
-- **可追溯、可验证**：每个结论都有数据支撑（hue 占比、色块坐标、OCR 文本+置信度），
-  能主动识别并纠正多模态模型的幻觉（游戏名乱猜、发光颜色误标、小字脑补）
-- **隐私友好**：原始图片不出本机，只有降采样文本进模型上下文
+- **一个插件全包含，无需另装**：独立的伪多模态识图 + 可选外部视觉 API，融合在一个包里，不需要再装 `dsh-universal-vision` 或其他读图插件
+- **核心链路零外部依赖**：扫描/取样/解码纯本地纯 JS，不调任何视觉 API；语义理解要么交给主模型，要么按需桥接你自己的 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 强很多但需选装，且对极小文字/极端艺术字仍可能失败（可配合放大）
+- **性能 / MCP 开销**：ZCode 版工具经 MCP stdio 子进程通信，单次调用比 DSH 版慢；高频/批量看图建议用 DSH 版
 - **WebP 不支持**（提示转 PNG/JPEG）；GIF 只读首帧
 - **多模态模型的描述不可全信**（本插件可交叉验证，但最终语义仍需人工判断关键场景）
 

package/mcp/server.js

@@ -2,10 +2,11 @@
  * picturereader MCP server — exposes the image-reading tools to ZCode as a
  * Model Context Protocol stdio server.
  *
- * Three tools, identical in behavior to the original DSH plugin:
- * - `image_scan`    coarse pixel grid + hue/color/structure analysis
- * - `image_ocr`     text recognition (Windows OCR default, PaddleOCR optional)
- * - `image_sample`  exact-pixel texture sampling for material judgment
+ * Four tools, identical in behavior to the original DSH plugin:
+ * - `image_scan`      coarse pixel grid + hue/color/structure analysis
+ * - `image_ocr`       text recognition (Windows OCR default, PaddleOCR optional)
+ * - `image_sample`    exact-pixel texture sampling for material judgment
+ * - `vision_analyze`  unified pipeline: low-info guard + optional scan/OCR/VLM
  *
  * The entire business logic lives in `src/core.js`, loaded dynamically with a
  * cache-busting query keyed on the file's mtime (see `importCore`), so editing
@@ -22,6 +23,8 @@ import { extname, isAbsolute, resolve as resolvePath } from 'node:path';
 import { stat, readFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
+import { isLowInformationImage } from '../src/guard.js';
+import { ensureServer, stopServer, sendVisionRequest, defaultVlmConfig, isVlmConfigured } from '../src/vlm.js';
 
 /** The MCP protocol version this server speaks. */
 export const PROTOCOL_VERSION = '2025-06-18';
@@ -314,9 +317,120 @@ export async function executeSample(args) {
   };
 }
 
+/**
+ * Parse a boolean argument with fallback.
+ * @param {any} value - the argument value.
+ * @param {boolean} fallback - default value.
+ * @returns {boolean} parsed boolean.
+ */
+function boolArg(value, fallback = false) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  return String(value) === 'true' || String(value) === '1';
+}
+
+/**
+ * `vision_analyze`: unified image understanding pipeline.
+ * Runs low-information guard, optional scan, optional OCR, optional VLM.
+ * @param args - tool arguments.
+ * @returns the combined analysis result.
+ */
+export async function executeVisionAnalyze(args) {
+  const { core, filePath, ext } = await loadImageArgs(args, 'vision_analyze');
+  const absolutePath = resolveImagePath(filePath);
+  const data = await readImageFile(absolutePath, 'vision_analyze');
+  const image = decodeBounded(core, data, ext, 'vision_analyze');
+
+  const includeScan = args.include_scan === undefined ? true : boolArg(args.include_scan, true);
+  const includeOcr = args.include_ocr === undefined ? false : boolArg(args.include_ocr, false);
+  const includeVlm = args.include_vlm === undefined ? true : boolArg(args.include_vlm, true);
+  const allowLowInfo = boolArg(args.allow_low_info, false);
+  const stopAfter = boolArg(args.stop_after, false);
+  const prompt = args.prompt ?? 'Describe this image in detail.';
+
+  // Check if VLM is configured
+  const vlmAvailable = isVlmConfigured();
+  const shouldCallVlm = includeVlm && vlmAvailable;
+
+  const lowInfo = isLowInformationImage(image.data, image.width, image.height);
+  const blocks = [];
+  let ocrText = '';
+  let scanText = '';
+  let vlmText = '';
+
+  if (lowInfo && !allowLowInfo) {
+    const message =
+      '[vision_analyze] 低信息量拦截：图片空白或内容极少，为避免 VLM 幻觉，未调用 VLM。' +
+      '请检查截图是否空白/未渲染/窗口在屏幕外；如确需识别请设置 allow_low_info=true。';
+    return { path: absolutePath, lowInformation: true, message, combined: message };
+  }
+
+  if (includeScan) {
+    const analysis = core.analyzeImage(image.data, image.width, image.height, {
+      size: 32,
+      mode: 'auto',
+      region: undefined,
+      palette: 'auto'
+    });
+    scanText = core.renderImageScan({
+      path: absolutePath,
+      width: image.width,
+      height: image.height,
+      ...analysis
+    });
+    blocks.push(`[scan]\n${scanText}`);
+  }
+
+  if (includeOcr) {
+    const engine = args.ocr_engine ?? 'windows';
+    const ocr = await core.ocrImage(data, ext, { engine });
+    ocrText = core.renderOcr({
+      path: absolutePath,
+      width: ocr.width,
+      height: ocr.height,
+      region: 'full',
+      engine: ocr.engine,
+      lines: ocr.lines
+    });
+    blocks.push(`[ocr]\n${ocrText}`);
+  }
+
+  if (shouldCallVlm) {
+    const config = defaultVlmConfig();
+    let startedByUs = false;
+    try {
+      const child = await ensureServer(config);
+      startedByUs = child !== null;
+      const base64 = data.toString('base64');
+      const mime = ext === '.jpg' || ext === '.jpeg' ? 'image/jpeg' : ext === '.png' ? 'image/png' : ext === '.gif' ? 'image/gif' : 'image/bmp';
+      const safePrompt =
+        prompt +
+        '\n\n重要：只描述图中明确可见的内容。如果图中没有明显物体/文字/界面元素，请直接回答：画面空白或内容极少。不要推测、不要脑补不存在的角色/场景/文字。';
+      vlmText = await sendVisionRequest(config, [{ mime, base64 }], safePrompt);
+      blocks.push(`[vlm]\n${vlmText}`);
+    } finally {
+      if (stopAfter && startedByUs) {
+        await stopServer();
+      }
+    }
+  } else if (includeVlm && !vlmAvailable) {
+    blocks.push('[vlm] VLM 未配置（SEE_BASE 环境变量为空）');
+  }
+
+  const combined = blocks.join('\n\n---\n\n');
+  return {
+    path: absolutePath,
+    lowInformation: false,
+    ...(scanText ? { scan: scanText } : {}),
+    ...(ocrText ? { ocr: ocrText } : {}),
+    ...(vlmText ? { vlm: vlmText } : {}),
+    combined
+  };
+}
+
 /**
  * Dispatch a tool call to its implementation.
- * @param name - tool name ('image_scan' | 'image_ocr' | 'image_sample').
+ * @param name - tool name ('image_scan' | 'image_ocr' | 'image_sample' | 'vision_analyze').
  * @param args - tool arguments object.
  * @returns the structured tool result.
  */
@@ -326,6 +440,7 @@ export async function executeTool(name, args) {
     case 'image_scan': return executeScan(cleanArgs);
     case 'image_ocr': return executeOcr(cleanArgs);
     case 'image_sample': return executeSample(cleanArgs);
+    case 'vision_analyze': return executeVisionAnalyze(cleanArgs);
     default: throw new Error(`unknown tool: ${name}`);
   }
 }
@@ -453,11 +568,65 @@ export const TOOLS = [
       },
       required: ['file_path', 'region']
     }
+  },
+  {
+    name: 'vision_analyze',
+    description: [
+      'Unified image understanding: decode an image, run a low-information guard, optionally scan pixels, OCR text, and/or ask the VLM for a semantic description.',
+      'Use this when you need one call to both verify what is in the image and get a natural-language interpretation.',
+      'Returns evidence blocks: scan (pixel stats), ocr (real text), vlm (model description). If low-information guard triggers and allow_low_info is false, it will not call the VLM.',
+      'Supported formats: PNG, JPEG, GIF (first frame), BMP. WebP is not supported yet.',
+      'VLM is optional: if SEE_BASE is not configured, VLM calls are skipped automatically.',
+      'Smart API calling: simple images (low color diversity, high dominant color coverage) skip VLM automatically.',
+      'Multiple questions: call this tool multiple times with different prompts on the same image for comprehensive analysis.',
+      'Cross-validation: main model should verify VLM results against pixel scan and OCR evidence.'
+    ].join(' '),
+    inputSchema: {
+      type: 'object',
+      additionalProperties: true,
+      properties: {
+        file_path: { type: 'string', description: IMAGE_PATH_DESCRIPTION },
+        prompt: {
+          type: 'string',
+          description: 'Question/instruction for the VLM, e.g. "Describe this UI" or "What is wrong with this map rendering?"'
+        },
+        include_scan: {
+          type: 'boolean',
+          description: 'Include pixel scan evidence (default true).'
+        },
+        include_ocr: {
+          type: 'boolean',
+          description: 'Include OCR text evidence (default false; set true when text matters).'
+        },
+        ocr_engine: {
+          type: 'string',
+          enum: ['windows', 'paddle'],
+          description: 'OCR engine: windows (default) or paddle (better for glowing/curved/game text).'
+        },
+        include_vlm: {
+          type: 'boolean',
+          description: 'Include VLM description (default true, but skipped if SEE_BASE not configured).'
+        },
+        allow_low_info: {
+          type: 'boolean',
+          description: 'Skip the low-information guard and force VLM even on blank/simple images (default false).'
+        },
+        stop_after: {
+          type: 'boolean',
+          description: 'Stop the local llama-server after this call if this plugin started it (default false).'
+        }
+      },
+      required: ['file_path']
+    }
   }
 ];
 
 /** Render a structured tool result as the text block fed back to the model. */
 async function renderResult(name, value) {
+  // vision_analyze has its own combined field
+  if (name === 'vision_analyze') {
+    return value.combined ?? value.message ?? JSON.stringify(value);
+  }
   const core = await importCore();
   const renderer =
     name === 'image_scan' ? core.renderImageScan
@@ -571,7 +740,7 @@ export function runServer(input = process.stdin, output = process.stdout, log =
   };
   rl.on('line', onLine);
   rl.on('error', onError);
-  log.write('picturereader MCP server ready (image_scan / image_ocr / image_sample)\n');
+  log.write('picturereader MCP server ready (image_scan / image_ocr / image_sample / vision_analyze)\n');
   return () => {
     rl.off('line', onLine);
     rl.off('error', onError);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name":  "picturereader-zcode",
-    "version":  "1.0.3",
-    "description":  "ZCode 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 it can \u0027see\u0027 layout, colors and rough shapes without a vision model. Ported from the picturereader DSH plugin.",
+    "version":  "2.0.0",
+    "description":  "ZCode plugin: unified image understanding for text-only models. Fuses frame-free pseudo-multimodal reading (pixel scan + OCR + sample) with an optional external vision API bridge (LM Studio / llama-server / any OpenAI-compatible endpoint) for full semantic understanding. No extra plugin needed.",
     "type":  "module",
     "main":  "src/core.js",
     "exports":  {
@@ -33,7 +33,10 @@
                      "paddleocr",
                      "hue",
                      "multimodal",
-                     "mcp"
+                     "mcp",
+                     "vlm",
+                     "vision-analyze",
+                     "llm-vision"
                  ],
     "license":  "MIT",
     "author":  "picturereader",

package/skills/image-reading.md

@@ -94,3 +94,26 @@ Gogomoe 知识框架分类，教训均来自对真实图片的实测复盘）。
   → 教训沉淀为 insight 4。
 
 （新增经验会持续按以上分类沉淀进本 skill。）
+
+## vision_analyze 统一工具
+
+当需要一次性获取多种证据时，使用 `vision_analyze`：
+- 自动检测空白/简单图片（低信息量拦截）
+- 可选像素扫描（include_scan）
+- 可选 OCR 文字识别（include_ocr）
+- 可选 VLM 语义描述（include_vlm，需配置 SEE_BASE）
+- 所有证据以文本形式返回，供主模型推理
+
+### 推荐的工作流程
+
+建议先用 `image_scan` 自己看，了解图片内容后再决定是否需要调用 VLM。简单图片用像素扫描就够了，复杂场景可以调用 VLM。
+
+### 多次提问
+
+对同一张图可以进行多次不同角度的提问，获取更全面的理解。
+
+### 交叉验证
+
+VLM 描述与像素/OCR 证据冲突时，以实测为准。
+
+详细用法见 `skills/vision-analyze.md`。