picturereader 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,122 @@
+# picturereader
+
+> DSH 插件（`dsh-plugin`）— 给纯文本模型（如 deepseek-v4-flash）的"读图"能力。
+> 把图片**降分辨率 + 降色深 + 结构/色彩指纹提取**，渲染成文本网格喂回对话，
+> 让模型像多模态模型一样"看"图：描述场景、主体、环境、光线与语义内容。
+> **纯本地、零外部模型依赖、零 API key、零 Python（PaddleOCR 为可选增强）**。
+
+[![dsh-plugin](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+
+## 这是什么
+
+DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturereader 把"看图"翻译成
+模型能理解的**结构化文本证据**，并提供一套经过真实图片训练验证的**读图方法论
+skill（image-reading）**，让模型像人一样分步看图：
+
+1. **全局定调**：hue families（纯色相指纹）→ structure（条带/对称）→ texture（写实度）→ regions（色块结构）
+2. **主动找主体**：px_per_cell 定向放大（深色/低对比/小色块不会漏）
+3. **文字验证**：PaddleOCR 实读（防多模态幻觉）
+4. **材质判断**：image_sample 像素取样
+5. **综合描述**：带证据等级的连贯画面描述
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `image_scan` | 全局/区域扫描：亮度/颜色网格 + regions 色块 + shade diversity + texture mix + structure（条带/对称）+ **像素级 colors** + **hue families 纯色相指纹**；支持 `focus`/`region` 局部放大、`px_per_cell` 像素密度定向放大 |
+| `image_ocr` | 文字识别双引擎：`windows`（内置，默认）/ `paddle`（选装，发光/弯曲/游戏字远强），失败自动降级不崩溃 |
+| `image_sample` | 8×8 精确像素取样，判断材质/纹理（金属/木纹/织物/皮肤/雾） |
+
+### 读图方法论 skill（image-reading）
+
+`skills/image-reading.md` 是经 **34 张真实游戏截图训练 + gemma-4-12b 对照验证**沉淀的
+读图方法论（按 experience / skill / principle / insight 分层），安装后模型自动掌握：
+- **hue 场景指纹**：cyan 高=水/雾/湖泊，green 高=森林，orange/red 高=暖色人物/火光，
+  blue 高=夜晚科幻，achromatic+rough=废墟，green+yellow=翠绿能量/浮空仙境
+- **多模态模型校验规则**：游戏名/品牌必须 OCR 实读（gemma 会猜"原神/崩坏3"）；
+  发光元素颜色以 hue 实测为准（多模态模型系统性误标成"粉红/紫"）
+- **主动验证**：低对比主体（暗色人物/小色块）必须放大确认
+
+## 安装
+
+```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
+```
+
+重启 DSH Desktop 后，模型工具列表出现 `image_scan` / `image_ocr` / `image_sample`，
+技能目录出现 `image-reading`。
+
+## 使用
+
+直接对模型说：
+
+> 用 image_scan 看一下 <路径> 这张图，细看感兴趣的部分
+
+模型会加载 `image-reading` 方法论自动执行完整流程（定调 → 找主体 → 验证 → 描述）。
+
+## 输出示例
+
+```
+image: chart.png (600x400 -> 32x21 cells, ~18.8x19px per cell, region=full, palette=full, mode=color)
+shade diversity: 10 distinct shades | texture: smooth 24.2%, medium 19.3%, rough 56.5%
+structure: 6 vertical stripes (4 alternating colors) at cols 4..7; left-right symmetry 45%
+hue families: cyan 88.2%, green 4.5%, yellow 1%          ← 真实主调（colors 灰白占比是假象）
+regions: ...（色块结构）
+colors by area: ...（像素级真实占比）
+luminance grid / color grid
+```
+
+## 开发
+
+```sh
+npm install
+npm test            # node:test，76 个测试全绿
+node scripts/setup-ocr.mjs   # 可选：装 PaddleOCR
+node scripts/preview.mjs     # 生成 fixtures 并预览渲染
+```
+
+**热插拔**：DSH 本身不支持代码热重载，但本插件自带执行层热加载——业务逻辑全在
+`src/core.js` 单文件，工具每次执行按 mtime 动态加载（cache-bust），**改 core.js
+下次调用即生效**；工具定义（schema/描述）改动需重启桌面端。
+
+## 优势
+
+- **零外部模型依赖**：核心链路（扫描/取样/解码）纯本地纯 JS，不调任何视觉 API；
+  语义理解完全交给主模型（DeepSeek），不依赖 YOLO 等固定类别检测器（遇未知物体不失效）
+- **可追溯、可验证**：每个结论都有数据支撑（hue 占比、色块坐标、OCR 文本+置信度），
+  能主动识别并纠正多模态模型的幻觉（游戏名乱猜、发光颜色误标、小字脑补）
+- **隐私友好**：原始图片不出本机，只有降采样文本进模型上下文
+- **成本低**：一次扫描 ≈0.6–2.2K tokens；PaddleOCR 本地跑，无 API 费用
+- **可选增强**：PaddleOCR 一键安装（`scripts/setup-ocr.mjs`），缺失自动降级不崩溃
+- **方法论沉淀**：附带的 image-reading skill 把读图经验固化（场景指纹/校验规则），
+  模型每次看图都带着经过 34 张真实截图验证的经验
+
+## 局限性（重要）
+
+- **不是真正的视觉模型**：文本网格信息量有限，**人脸/表情/花纹等像素级细节读不出**；
+  这是文本模态的硬上限，放大（px_per_cell）只能缩小差距，不能消除
+- **语义推断依赖主模型能力**：物体识别（"这是树/空间站"）是 LLM 基于结构证据的推测，
+  不是视觉模型的确证——复杂/罕见物体可能推断错误
+- **OCR 引擎边界**：Windows OCR 对发光/弯曲/艺术字失效；PaddleOCR 强很多但需选装，
+  且对极小文字/极端艺术字仍可能失败（可配合放大）
+- **性能**：4K 图解码 ~230ms；PaddleOCR 每次调用需 ~2s 加载模型；大图网格渲染
+  token 随 size 增长（64×64 color ≈ 3–5K tokens）
+- **WebP 不支持**（提示转 PNG/JPEG）；GIF 只读首帧
+- **多模态模型的描述不可全信**（本插件可交叉验证，但最终语义仍需人工判断关键场景）
+
+## License
+
+MIT
+
+---
+
+**DSH 插件生态**：GitHub topic `dsh-plugin` 会被 [dsh-plugin-marketplace](https://github.com/AwesomeHou/dsh-plugin-marketplace)
+自动同步识别；精选列表见 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)。

package/cordis.patch.yml

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "picturereader",
+  "version": "0.1.0",
+  "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 'see' layout, colors and rough shapes without a vision model.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "image",
+    "vision",
+    "pixels",
+    "ascii",
+    "ocr",
+    "paddleocr",
+    "hue",
+    "multimodal"
+  ],
+  "license": "MIT",
+  "author": "picturereader",
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "jpeg-js": "^0.4.4",
+    "omggif": "^1.0.10",
+    "pngjs": "^7.0.0"
+  }
+}

package/skills/image-reading.md

@@ -0,0 +1,96 @@
+---
+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。）