picturereader 1.0.2 → 2.0.0

package/skills/image-reading.md

@@ -1,96 +1,119 @@
----
-name: image-reading
-description: Read and understand images like a multimodal model using the picturereader tools (image_scan / image_ocr / image_sample). Applies a verified 5-step workflow (global tone → find subjects → verify text → judge material → synthesize) guided by grounded principles and cross-image insights. Use whenever you need to look at an image.
----
-
-# 读图方法论（image-reading）
-
-目标：**像多模态模型一样"看"图并输出连贯描述**，每个结论可追溯、可验证。
-本 skill 由 experience / skill / principle / insight 四层知识构成（按
-Gogomoe 知识框架分类，教训均来自对真实图片的实测复盘）。
-
-## 操作流程（skill）
-
-### 1. 全局定调（第一轮扫描）
-
-用默认参数（size=40）全图扫描，读四个字段：
-- **`hue families`（最高优先级）**：按纯色相分族的真实占比。暗调/低饱和场景的
-  真实颜色只在这里——`colors by area` 灰白占比高不代表画面灰白。
-- **`structure`**：平行条带/对称性（解读见 insights）。
-- **`texture`**：rough 高=写实照片；smooth 高=扁平或水面/天空/雾（见 insights）。
-- **`regions`**：大结构的位置/大小/颜色。
-
-### 2. 找主体（全局→局部，主动验证）
-
-- 对**颜色异常区、深色大块、相邻竖长色块、小色块密集区**用 `px_per_cell` 定向放大
-  （值越小越细：8-12 看轮廓，4-6 看结构，2-3 看细节；区域不够小时工具会提示实际密度，缩小 focus/region 重试）。
-- 放大后按**形状**解读：头+肩+躯干=人物；弧线+对称明暗=圆柱/球/装置；
-  竖直细长结构=石柱/塔/杆；交替细条=面板/栅格。
-- **主体可能与背景低对比而"隐形"**（见 insights 4）——怀疑处必须放大确认，不能因 regions 未单列就跳过。
-
-### 3. 文字验证
-
-- 疑似文字/标识/UI → `image_ocr`（region/focus 限定）。
-- Windows 引擎读不出但怀疑有字 → `engine="paddle"` 重试（发光/弯曲/游戏渲染文字）。
-- **OCR 结果优先于模型描述**（见 insights 3）。
-
-### 4. 材质判断
-
-`image_sample` 对小块区域 8×8 取样，看 RGB 分布与 contrast 统计
-（平滑渐变=天空/皮肤/水面；高对比条纹=金属/木纹；暗绿 G>R>B=植物/涂装）。
-
-### 5. 综合描述
-
-输出连贯描述（场景/主体/环境光线/细节），**每个结论标注证据等级**：
-实锤（有像素/OCR/取样数据）vs 推断（基于结构推测，用"看起来像"）。
-优先引用具体数字；不确定就说不确定，绝不编造。
-
-## 行为准则（principles）
-
-1. **证据分级**：任何结论标注"实测"或"推断"；推断必须说明依据。
-2. **数字优先**：用具体指标（"蓝色调 74%""对称 80%""OCR 读出 1.00"）支撑描述，不用模糊形容词代替。
-3. **先全局后局部**：第一轮定调，第二轮定向放大验证，不跳步。
-4. **怀疑即验证**：对任何"可能漏掉的主体"，用放大/取样/OCR 验证后再下结论。
-5. **不编造**：不确定就说明；模型（含多模态）的描述不可直接当作事实（见 insights 3）。
-
-## 规律性洞察（insights，跨图归纳）
-
-1. **暗调场景的真实颜色只在 hue families 里**：低饱和/暗色调（暮色、雾中、夜景）
-   会被 14 色色板压成灰黑，`colors` 的灰白占比是假象——hue families 按纯色相分族不受影响。
-2. **高对称 ≠ 一定人造物**：水面倒影/镜像构图也高度对称。区分看：平滑大面积
-   （水面/天空 smooth 高）+ 水天分界线（上亮下暗、上下镜像）+ 竖直细长结构（石柱）
-   = 湖泊/自然镜像；纹理复杂、颜色单调、几何硬边 = 人造建筑/装置。
-3. **小模型读小字不可靠**：多模态小模型对低分辨率文字会幻觉（全图"读出"内容、
-   裁剪后承认没有）；发光/弯曲/艺术字 Windows OCR 也失效——**文字一律以 OCR 实读为准**。
-4. **低对比主体"隐形"**：暗色物体（如深色服装人物）在暗背景中融入背景黑块，
-   粗网格和 regions 都不会标出——对深色区域主动放大是唯一可靠发现方式。
-5. **平滑大面积 ≠ 扁平简笔画**：水面、天空、雾气、墙面都平滑（smooth 高），
-   需结合色调/结构/场景判断，不能仅凭 smooth 判定"扁平"。
-6. **"像什么"和"是什么"要分开**：结构证据（对称/形状/色调）支撑"像什么"；
-   "是什么"需要 OCR/取样/更强证据，不满足时保持推断。
-7. **hue families 是场景类型指纹**（34 张图训练归纳）：
-   - cyan 高（>60%）= 水/雾/湖泊/晨雾场景（东方水景、浓雾遗址）
-   - green 高（>40%）= 森林/竹林/草地/苔藓
-   - orange 或 red 高 = 红披风/暖色服饰人物、火光、晚霞
-   - blue 高（>70%）= 夜晚/冷色科幻场景
-   - achromatic 高 + rough 高 = 废墟/岩石/暗环境
-   - green + yellow 双高 = 翠绿能量带/发光植被/浮空仙境
-   - 对称高 + 中央竖直结构 = 中央主体（瀑布/树/大门）居中构图
-8. **多模态模型的颜色描述对"发光/能量"不可靠**（训练中反复出现）：把实测为
-   cyan/blue/green 的冷色发光（屏幕光、能量屏障、雾中光柱）系统性说成"粉红/紫色"。
-   发光元素的颜色一律以 hue 实测为准。
-9. **人物识别信号**：orange/red 主调 + 局部暖色小块 + 对称 = 人物服饰候选；
-   游戏角色常穿红/橙（红披风、红发、暖色战斗服），识别到暖色主调时应主动放大找人物。
-10. **品牌/游戏名/标题文字**：多模态模型会猜错（"原神""崩坏3"实际是明日方舟终末地），
-   必须 PaddleOCR 实读（游戏 HUD 底部常带游戏名/参数/水印）。
-
-## 案例参考（experience，简短）
-
-- 湖泊仙侠图：对称 97% 被误判为"人造立面"，实为水面倒影+湖中石柱+粉紫雾气
-  → 教训沉淀为 insight 2。
-- 游戏发光标语图：Windows OCR 12 格全空、多模态幻觉"问问答写"，
-  PaddleOCR 一次读出「勇于探索叩问苍穹」→ 教训沉淀为 insight 3。
-- 暗背景人物图：黑服人物融入背景被漏检，px_per_cell=3 放大后头肩躯干清晰
-  → 教训沉淀为 insight 4。
-
-（新增经验会持续按以上分类沉淀进本 skill。）
+---
+name: image-reading
+description: Read and understand images like a multimodal model using the picturereader tools (image_scan / image_ocr / image_sample). Applies a verified 5-step workflow (global tone → find subjects → verify text → judge material → synthesize) guided by grounded principles and cross-image insights. Use whenever you need to look at an image.
+---
+
+# 读图方法论（image-reading）
+
+目标：**像多模态模型一样"看"图并输出连贯描述**，每个结论可追溯、可验证。
+本 skill 由 experience / skill / principle / insight 四层知识构成（按
+Gogomoe 知识框架分类，教训均来自对真实图片的实测复盘）。
+
+## 操作流程（skill）
+
+### 1. 全局定调（第一轮扫描）
+
+用默认参数（size=40）全图扫描，读四个字段：
+- **`hue families`（最高优先级）**：按纯色相分族的真实占比。暗调/低饱和场景的
+  真实颜色只在这里——`colors by area` 灰白占比高不代表画面灰白。
+- **`structure`**：平行条带/对称性（解读见 insights）。
+- **`texture`**：rough 高=写实照片；smooth 高=扁平或水面/天空/雾（见 insights）。
+- **`regions`**：大结构的位置/大小/颜色。
+
+### 2. 找主体（全局→局部，主动验证）
+
+- 对**颜色异常区、深色大块、相邻竖长色块、小色块密集区**用 `px_per_cell` 定向放大
+  （值越小越细：8-12 看轮廓，4-6 看结构，2-3 看细节；区域不够小时工具会提示实际密度，缩小 focus/region 重试）。
+- 放大后按**形状**解读：头+肩+躯干=人物；弧线+对称明暗=圆柱/球/装置；
+  竖直细长结构=石柱/塔/杆；交替细条=面板/栅格。
+- **主体可能与背景低对比而"隐形"**（见 insights 4）——怀疑处必须放大确认，不能因 regions 未单列就跳过。
+
+### 3. 文字验证
+
+- 疑似文字/标识/UI → `image_ocr`（region/focus 限定）。
+- Windows 引擎读不出但怀疑有字 → `engine="paddle"` 重试（发光/弯曲/游戏渲染文字）。
+- **OCR 结果优先于模型描述**（见 insights 3）。
+
+### 4. 材质判断
+
+`image_sample` 对小块区域 8×8 取样，看 RGB 分布与 contrast 统计
+（平滑渐变=天空/皮肤/水面；高对比条纹=金属/木纹；暗绿 G>R>B=植物/涂装）。
+
+### 5. 综合描述
+
+输出连贯描述（场景/主体/环境光线/细节），**每个结论标注证据等级**：
+实锤（有像素/OCR/取样数据）vs 推断（基于结构推测，用"看起来像"）。
+优先引用具体数字；不确定就说不确定，绝不编造。
+
+## 行为准则（principles）
+
+1. **证据分级**：任何结论标注"实测"或"推断"；推断必须说明依据。
+2. **数字优先**：用具体指标（"蓝色调 74%""对称 80%""OCR 读出 1.00"）支撑描述，不用模糊形容词代替。
+3. **先全局后局部**：第一轮定调，第二轮定向放大验证，不跳步。
+4. **怀疑即验证**：对任何"可能漏掉的主体"，用放大/取样/OCR 验证后再下结论。
+5. **不编造**：不确定就说明；模型（含多模态）的描述不可直接当作事实（见 insights 3）。
+
+## 规律性洞察（insights，跨图归纳）
+
+1. **暗调场景的真实颜色只在 hue families 里**：低饱和/暗色调（暮色、雾中、夜景）
+   会被 14 色色板压成灰黑，`colors` 的灰白占比是假象——hue families 按纯色相分族不受影响。
+2. **高对称 ≠ 一定人造物**：水面倒影/镜像构图也高度对称。区分看：平滑大面积
+   （水面/天空 smooth 高）+ 水天分界线（上亮下暗、上下镜像）+ 竖直细长结构（石柱）
+   = 湖泊/自然镜像；纹理复杂、颜色单调、几何硬边 = 人造建筑/装置。
+3. **小模型读小字不可靠**：多模态小模型对低分辨率文字会幻觉（全图"读出"内容、
+   裁剪后承认没有）；发光/弯曲/艺术字 Windows OCR 也失效——**文字一律以 OCR 实读为准**。
+4. **低对比主体"隐形"**：暗色物体（如深色服装人物）在暗背景中融入背景黑块，
+   粗网格和 regions 都不会标出——对深色区域主动放大是唯一可靠发现方式。
+5. **平滑大面积 ≠ 扁平简笔画**：水面、天空、雾气、墙面都平滑（smooth 高），
+   需结合色调/结构/场景判断，不能仅凭 smooth 判定"扁平"。
+6. **"像什么"和"是什么"要分开**：结构证据（对称/形状/色调）支撑"像什么"；
+   "是什么"需要 OCR/取样/更强证据，不满足时保持推断。
+7. **hue families 是场景类型指纹**（34 张图训练归纳）：
+   - cyan 高（>60%）= 水/雾/湖泊/晨雾场景（东方水景、浓雾遗址）
+   - green 高（>40%）= 森林/竹林/草地/苔藓
+   - orange 或 red 高 = 红披风/暖色服饰人物、火光、晚霞
+   - blue 高（>70%）= 夜晚/冷色科幻场景
+   - achromatic 高 + rough 高 = 废墟/岩石/暗环境
+   - green + yellow 双高 = 翠绿能量带/发光植被/浮空仙境
+   - 对称高 + 中央竖直结构 = 中央主体（瀑布/树/大门）居中构图
+8. **多模态模型的颜色描述对"发光/能量"不可靠**（训练中反复出现）：把实测为
+   cyan/blue/green 的冷色发光（屏幕光、能量屏障、雾中光柱）系统性说成"粉红/紫色"。
+   发光元素的颜色一律以 hue 实测为准。
+9. **人物识别信号**：orange/red 主调 + 局部暖色小块 + 对称 = 人物服饰候选；
+   游戏角色常穿红/橙（红披风、红发、暖色战斗服），识别到暖色主调时应主动放大找人物。
+10. **品牌/游戏名/标题文字**：多模态模型会猜错（"原神""崩坏3"实际是明日方舟终末地），
+   必须 PaddleOCR 实读（游戏 HUD 底部常带游戏名/参数/水印）。
+
+## 案例参考（experience，简短）
+
+- 湖泊仙侠图：对称 97% 被误判为"人造立面"，实为水面倒影+湖中石柱+粉紫雾气
+  → 教训沉淀为 insight 2。
+- 游戏发光标语图：Windows OCR 12 格全空、多模态幻觉"问问答写"，
+  PaddleOCR 一次读出「勇于探索叩问苍穹」→ 教训沉淀为 insight 3。
+- 暗背景人物图：黑服人物融入背景被漏检，px_per_cell=3 放大后头肩躯干清晰
+  → 教训沉淀为 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`。

package/skills/vision-analyze.md

@@ -0,0 +1,256 @@
+---
+name: vision-analyze
+description: Unified image understanding tool that combines pixel scan, OCR, and optional VLM for complete image analysis. Use when you need one call to both verify what is in the image and get a natural-language interpretation.
+whenToUse: 需要一次性获取图片的多种证据（像素扫描 + OCR + VLM 描述）时使用。
+---
+
+# vision_analyze 统一识图工具
+
+## 工具概述
+
+`vision_analyze` 是 picturereader 的统一识图入口，一次调用可获取：
+- **像素扫描证据**（image_scan）
+- **OCR 文字识别**（image_ocr）
+- **VLM 语义描述**（可选，需配置 SEE_BASE）
+
+## 核心特性
+
+### 1. 低信息量拦截
+自动检测空白/简单图片，防止 VLM 幻觉：
+- 颜色种类太少（≤8 种）
+- 单一颜色占比过高（≥90%）
+- 主导颜色且边缘稀少
+- 亮度方差太小
+
+### 2. 证据交叉验证
+- VLM 描述与像素/OCR 冲突时，以像素/OCR 实测为准
+- 所有证据以文本形式返回，供主模型推理
+
+### 3. VLM 可选配置
+- 默认不配置 VLM，只返回像素扫描和 OCR 证据
+- 需要 VLM 时，设置 `SEE_BASE` 环境变量
+
+### 4. 智能调用策略
+- **简单图片**：不调用外部 API，使用像素扫描 + OCR 即可
+- **复杂/精密图片**：调用外部 API 获取语义理解
+- **多次提问**：支持对同一张图进行多次不同角度的提问
+
+## 使用建议
+
+### 推荐的工作流程
+
+建议先用 `image_scan` 自己看，了解图片内容后再决定是否需要调用 VLM：
+
+```
+# 先看图片内容
+image_scan(file_path="C:/shot.png", size=32)
+
+# 根据结果决定下一步
+# - 简单图片 → 直接描述，不需要 VLM
+# - 需要文字 → image_ocr
+# - 复杂场景 → vision_analyze（含 VLM）
+```
+
+### 何时调用 VLM
+
+简单图片用像素扫描就够了，复杂场景可以调用 VLM 获取语义理解。具体由你根据图片内容判断。
+
+### 交叉验证
+
+主模型需要对 VLM 结果进行交叉验证：
+
+1. **像素证据优先**：VLM 描述与像素扫描冲突时，以像素证据为准
+2. **OCR 优先**：VLM 识别的文字与 OCR 冲突时，以 OCR 为准
+3. **逻辑验证**：VLM 描述不符合逻辑时（如"天空是绿色的"），标记为幻觉
+4. **多次提问验证**：对同一张图进行多次不同角度的提问，验证一致性
+
+### 多次提问策略
+
+对同一张图可以进行多次不同角度的提问，以获取更全面的理解：
+
+```
+# 第一次：整体描述
+vision_analyze(
+  file_path="C:/shot.png",
+  prompt="描述这个图片的整体内容",
+  include_scan=true,
+  include_ocr=true,
+  include_vlm=true
+)
+
+# 第二次：细节询问
+vision_analyze(
+  file_path="C:/shot.png",
+  prompt="图片中有哪些文字？请详细列出",
+  include_scan=false,
+  include_ocr=false,
+  include_vlm=true
+)
+
+# 第三次：推理判断
+vision_analyze(
+  file_path="C:/shot.png",
+  prompt="这个界面设计是否合理？有哪些问题？",
+  include_scan=false,
+  include_ocr=false,
+  include_vlm=true
+)
+```
+
+## 使用方法
+
+### 基本用法（无 VLM）
+```
+vision_analyze(
+  file_path="C:/shot.png",
+  include_scan=true,
+  include_ocr=false,
+  include_vlm=false
+)
+```
+
+### 完整用法（含 VLM）
+```
+vision_analyze(
+  file_path="C:/shot.png",
+  prompt="描述这个界面，有哪些元素？布局是否正常？",
+  include_scan=true,
+  include_ocr=true,
+  include_vlm=true,
+  allow_low_info=false,
+  stop_after=false
+)
+```
+
+### 多次提问用法
+```
+# 对同一张图进行多次不同角度的提问
+vision_analyze(file_path="C:/shot.png", prompt="整体描述", include_vlm=true)
+vision_analyze(file_path="C:/shot.png", prompt="有哪些文字？", include_vlm=true)
+vision_analyze(file_path="C:/shot.png", prompt="设计是否合理？", include_vlm=true)
+```
+
+## 参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `file_path` | string | 必需 | 图片路径（PNG/JPEG/GIF/BMP） |
+| `prompt` | string | "Describe this image in detail." | VLM 提示词 |
+| `include_scan` | boolean | true | 是否包含像素扫描证据 |
+| `include_ocr` | boolean | false | 是否包含 OCR 文字识别 |
+| `ocr_engine` | string | "windows" | OCR 引擎：windows 或 paddle |
+| `include_vlm` | boolean | true | 是否包含 VLM 描述（需配置 SEE_BASE） |
+| `allow_low_info` | boolean | false | 是否允许低信息量图片调用 VLM |
+| `stop_after` | boolean | false | 调用后是否停止本地 llama-server |
+
+## 输出格式
+
+```json
+{
+  "path": "C:/shot.png",
+  "lowInformation": false,
+  "scan": "[scan]\nimage: C:/shot.png (1920x1080 -> 32x18 cells, ...)\n...",
+  "ocr": "[ocr]\nocr: C:/shot.png (1920x1080, region=full, engine=windows)\n...",
+  "vlm": "[vlm]\n这是一个桌面应用程序的截图，包含...",
+  "combined": "[scan]\n...\n\n---\n\n[ocr]\n...\n\n---\n\n[vlm]\n..."
+}
+```
+
+## 使用场景
+
+### 1. UI/界面验证
+```
+vision_analyze(
+  file_path="C:/ui_screenshot.png",
+  prompt="这个界面有哪些按钮？布局是否正常？有没有错位？",
+  include_scan=true,
+  include_ocr=true,
+  include_vlm=true
+)
+```
+
+### 2. 游戏截图分析
+```
+vision_analyze(
+  file_path="C:/game_screenshot.png",
+  prompt="这是什么游戏？画面中有什么角色/物体？",
+  include_scan=true,
+  include_ocr=true,
+  include_vlm=true
+)
+```
+
+### 3. 文档/图片 OCR
+```
+vision_analyze(
+  file_path="C:/document.png",
+  include_scan=false,
+  include_ocr=true,
+  include_vlm=false,
+  ocr_engine="paddle"
+)
+```
+
+### 4. 长任务视觉验证
+```
+# 循环验证流程
+1. 截图
+2. vision_analyze(file_path="C:/step1.png", include_scan=true, include_ocr=true)
+3. 与预期比对
+4. 不一致则修正
+5. 再截图验证
+```
+
+## 配置说明
+
+### PaddleOCR（可选）
+```bash
+# 安装 PaddleOCR
+node scripts/setup-ocr.mjs
+
+# 环境变量
+DSH_PADDLE_PYTHON=C:\Users\Administrator\paddle_venv\Scripts\python.exe
+DSH_PADDLE_CACHE=<插件目录>\.paddlex-cache
+```
+
+### VLM（可选，默认不配置）
+```bash
+# 本地 llama-server
+SEE_BASE=http://127.0.0.1:8080/v1
+SEE_MODEL=Huihui-Qwen3-VL-4B-Instruct-abliterated
+SEE_SERVER_EXE=E:\llama\llama-server.exe
+SEE_SERVER_MODEL=E:\llama\models\model.f16.gguf
+SEE_SERVER_MMPROJ=E:\llama\models\mmproj-f16.gguf
+SEE_SERVER_PORT=8080
+SEE_SERVER_NGL=20
+SEE_SERVER_CTX=16384
+
+# 远程 API
+SEE_BASE=https://api.openai.com/v1
+SEE_MODEL=gpt-4-vision-preview
+SEE_API_KEY=sk-xxx
+```
+
+## 注意事项
+
+1. **VLM 可选**：默认不配置 VLM，`vision_analyze` 会跳过 VLM 调用，只返回像素扫描和 OCR 证据
+2. **低信息量拦截**：空白/简单图片会自动拦截，不调用 VLM（防止幻觉）
+3. **证据优先级**：像素扫描 > OCR > VLM（冲突时以实测为准）
+4. **性能考虑**：VLM 调用需要 2-5 秒，建议在需要语义理解时才启用
+5. **WebP 不支持**：需要先转换为 PNG/JPEG
+
+## 与其他工具的关系
+
+- **image_scan**：像素级扫描，返回详细的颜色/结构证据
+- **image_ocr**：文字识别，返回 OCR 文本
+- **image_sample**：材质/纹理取样
+- **vision_analyze**：统一入口，组合以上证据 + 可选 VLM
+
+**必须遵守的工作流程**：
+1. **先用 `image_scan` 自己看**（像素扫描）→ 了解图片内容和复杂度
+2. 根据扫描结果判断：
+   - 简单图片（颜色单一、结构简单）→ 不需要 VLM，直接描述
+   - 需要文字 → 用 `image_ocr`
+   - 复杂场景（多人物、多物体、复杂背景）→ 用 `vision_analyze`（含 VLM）
+   - 需要材质细节 → 用 `image_sample`
+3. **不要直接调用 VLM**，先自己看再决定是否需要外部 API