picturereader 0.1.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -21
- package/package.json +50 -50
package/README.md
CHANGED
|
@@ -1,19 +1,34 @@
|
|
|
1
1
|
# picturereader
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
>
|
|
3
|
+
> 给纯文本模型（如 deepseek-v4-flash）的"读图"能力——**双版本发布**：
|
|
4
|
+
> - **DSH 版**：DeepSeek Harness 插件（`dsh-plugin`，含 DSH EAC 桌面端）
|
|
5
|
+
> - **ZCode 版**：ZCode 桌面端插件（`zcode-plugin`，经 MCP 暴露工具）
|
|
6
|
+
|
|
7
|
+
> 把图片 **降分辨率 + 降色深 + 结构/色彩指纹提取**，渲染成文本网格喂回对话，
|
|
5
8
|
> 让模型像多模态模型一样"看"图：描述场景、主体、环境、光线与语义内容。
|
|
6
9
|
> **纯本地、零外部模型依赖、零 API key、零 Python（PaddleOCR 为可选增强）**。
|
|
7
10
|
|
|
8
11
|
[](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
|
|
9
12
|
|
|
13
|
+
## 版本总览
|
|
14
|
+
|
|
15
|
+
| 版本 | 平台 | 形态 | 源码 | 安装 |
|
|
16
|
+
|---|---|---|---|---|
|
|
17
|
+
| **DSH 版** | DeepSeek Harness（含 EAC 桌面端） | npm 插件（`dsh.bundle`） | 仓库根目录 | `dsh plugin --profile web add picturereader` |
|
|
18
|
+
| **ZCode 版** | ZCode 桌面端 | 本地 marketplace 插件（MCP server + skill） | [jing-hy/picturereader-zcode](https://github.com/jing-hy/picturereader-zcode)（独立仓库） | 见其 README |
|
|
19
|
+
|
|
20
|
+
两个版本共用同一套业务核心（`src/core.js`）与读图方法论 skill（`image-reading`），
|
|
21
|
+
三个工具行为完全一致：`image_scan` / `image_ocr` / `image_sample`。
|
|
22
|
+
|
|
23
|
+
> **ZCode 版性能说明**：ZCode 版通过 MCP（stdio 子进程）暴露工具，每次调用都要
|
|
24
|
+
> 经历进程通信与序列化开销，**速度明显慢于 DSH 版**（DSH 版为插件内直接调用）。
|
|
25
|
+
> 高频看图、批量看图任务请优先使用 DSH 版；ZCode 版适合轻量、偶发看图。
|
|
26
|
+
|
|
10
27
|
## 这是什么
|
|
11
28
|
|
|
12
|
-
DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturereader 把"看图"
|
|
13
|
-
模型能理解的**结构化文本证据**，并提供一套经过大量真实图片迭代验证的**读图方法论
|
|
14
|
-
skill（image-reading）**，让模型像人一样分步看图：
|
|
29
|
+
DeepSeek 等纯文本模型没有视觉编码器，无法直接看图。picturereader 把"看图"翻译成**模型能理解的结构化文本证据**，并提供一套经过大量真实图片迭代验证的**读图方法论 skill（image-reading）**，让模型像人一样分步看图：
|
|
15
30
|
|
|
16
|
-
1. **全局定调**：hue families
|
|
31
|
+
1. **全局定调**：hue families（纯色指纹）→ structure（条纹/对称）→ texture（写实度）→ regions（色块结构）
|
|
17
32
|
2. **主动找主体**：px_per_cell 定向放大（深色/低对比/小色块不会漏）
|
|
18
33
|
3. **文字验证**：PaddleOCR 实读（防多模态幻觉）
|
|
19
34
|
4. **材质判断**：image_sample 像素取样
|
|
@@ -23,23 +38,23 @@ skill（image-reading）**，让模型像人一样分步看图：
|
|
|
23
38
|
|
|
24
39
|
| 工具 | 作用 |
|
|
25
40
|
|---|---|
|
|
26
|
-
| `image_scan` | 全局/区域扫描：亮度/颜色网格 + regions 色块 + shade diversity + texture mix + structure
|
|
27
|
-
| `image_ocr` | 文字识别双引擎：`windows`（内置，默认）/ `paddle
|
|
28
|
-
| `image_sample` | 8×8
|
|
41
|
+
| `image_scan` | 全局/区域扫描：亮度/颜色网格 + regions 色块 + shade diversity + texture mix + structure（条纹/对称） + **像素级 colors** + **hue families 纯色指纹**；支持 `focus`/`region` 局部放大、`px_per_cell` 像素密度定向放大 |
|
|
42
|
+
| `image_ocr` | 文字识别双引擎：`windows`（内置，默认）/ `paddle`（选装，发光/弯曲/游戏字更强），失败自动降级不崩溃 |
|
|
43
|
+
| `image_sample` | 8×8 精确像素取样，判断材质/纹理（金属/木纹/织物/皮肤/噪点） |
|
|
29
44
|
|
|
30
45
|
### 读图方法论 skill（image-reading）
|
|
31
46
|
|
|
32
|
-
`skills/image-reading.md`
|
|
33
|
-
（按 experience / skill / principle / insight
|
|
47
|
+
`skills/image-reading.md`（DSH 版）/ `skills/image-reading/SKILL.md`（ZCode 版）是一套**经大量真实图片场景迭代验证**的读图方法论
|
|
48
|
+
（按 experience / skill / principle / insight 分层，教训有据可依、找得到主模型模式），
|
|
34
49
|
安装后模型自动掌握：
|
|
35
|
-
- **hue 场景指纹**：cyan 高=水/雾/湖泊，green 高=森林，orange/red 高=暖色人物/火光，
|
|
36
|
-
|
|
37
|
-
- **多模态模型校验规则**：游戏名/品牌等文字必须 OCR 实读（多模态模型会猜错）；
|
|
38
|
-
发光元素颜色以 hue 实测为准（多模态模型对发光色的描述系统性不可靠）
|
|
50
|
+
- **hue 场景指纹**：cyan 高=水/雾/湖泊，green 高=森林，orange/red 高=暖色人物/火光，blue 高=夜空科幻，achromatic+rough=废墟，green+yellow=翠绿能量/浮空仙境
|
|
51
|
+
- **多模态模型校验规则**：游戏名/品牌等文字必须 OCR 实读（多模态模型会猜错）；发光元素颜色以 hue 实测为准（多模态模型对发光色的描述系统性不可靠）；低对比主体（暗色人物/小色块）必须放大确认
|
|
39
52
|
- **主动验证**：低对比主体（暗色人物/小色块）必须放大确认
|
|
40
53
|
|
|
41
54
|
## 安装
|
|
42
55
|
|
|
56
|
+
### DSH 版
|
|
57
|
+
|
|
43
58
|
```sh
|
|
44
59
|
# 1. 插件
|
|
45
60
|
dsh plugin --profile web add picturereader # 或从源码: dsh plugin --profile web add .
|
|
@@ -55,6 +70,14 @@ copy skills\image-reading.md %USERPROFILE%\.dsh\skills\ # Windows
|
|
|
55
70
|
重启 DSH Desktop 后，模型工具列表出现 `image_scan` / `image_ocr` / `image_sample`，
|
|
56
71
|
技能目录出现 `image-reading`。
|
|
57
72
|
|
|
73
|
+
### ZCode 版
|
|
74
|
+
|
|
75
|
+
ZCode 版是**独立仓库**：[jing-hy/picturereader-zcode](https://github.com/jing-hy/picturereader-zcode)。
|
|
76
|
+
|
|
77
|
+
ZCode 版通过 **MCP server**（`mcp/server.js`，stdio）把三个工具暴露给 ZCode，
|
|
78
|
+
读图方法论作为 **skill**（`skills/image-reading/`）随插件分发，业务逻辑 `src/core.js`
|
|
79
|
+
与本仓库完全一致。安装与使用请见其 README。
|
|
80
|
+
|
|
58
81
|
## 使用
|
|
59
82
|
|
|
60
83
|
直接对模型说：
|
|
@@ -75,19 +98,37 @@ colors by area: ...（像素级真实占比）
|
|
|
75
98
|
luminance grid / color grid
|
|
76
99
|
```
|
|
77
100
|
|
|
101
|
+
## 环境变量（ZCode 版）
|
|
102
|
+
|
|
103
|
+
| 变量 | 默认值 | 作用 |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| `DSH_PADDLE_PYTHON` | `C:\Users\Administrator\paddle_venv\Scripts\python.exe` | PaddleOCR 解释器路径（与原插件同名，便于直接迁移） |
|
|
106
|
+
| `DSH_PADDLE_CACHE` | `<插件目录>\.paddlex-cache` | PaddleX 模型缓存目录 |
|
|
107
|
+
|
|
78
108
|
## 开发
|
|
79
109
|
|
|
80
110
|
```sh
|
|
111
|
+
# DSH 版（本仓库）
|
|
81
112
|
npm install
|
|
82
113
|
npm test # node:test，76 个测试全绿
|
|
83
114
|
node scripts/setup-ocr.mjs # 可选：装 PaddleOCR
|
|
84
115
|
node scripts/preview.mjs # 生成 fixtures 并预览渲染
|
|
116
|
+
|
|
117
|
+
# ZCode 版（独立仓库 jing-hy/picturereader-zcode）
|
|
118
|
+
git clone https://github.com/jing-hy/picturereader-zcode.git
|
|
119
|
+
cd picturereader-zcode
|
|
120
|
+
npm install
|
|
121
|
+
npm test # node:test
|
|
122
|
+
node scripts/setup-ocr.mjs # 可选
|
|
85
123
|
```
|
|
86
124
|
|
|
87
|
-
|
|
125
|
+
**热插拔（DSH 版）**：DSH 本身不支持代码热重载，但本插件自带执行层热加载——业务逻辑全在
|
|
88
126
|
`src/core.js` 单文件，工具每次执行按 mtime 动态加载（cache-bust），**改 core.js
|
|
89
127
|
下次调用即生效**；工具定义（schema/描述）改动需重启桌面端。
|
|
90
128
|
|
|
129
|
+
**热插拔（ZCode 版）**：MCP server 从所选目录运行，改 `src/core.js` 下次调用即生效
|
|
130
|
+
（详见 picturereader-zcode 仓库 README）。
|
|
131
|
+
|
|
91
132
|
## 优势
|
|
92
133
|
|
|
93
134
|
- **零外部模型依赖**：核心链路（扫描/取样/解码）纯本地纯 JS，不调任何视觉 API；
|
|
@@ -110,14 +151,11 @@ node scripts/preview.mjs # 生成 fixtures 并预览渲染
|
|
|
110
151
|
且对极小文字/极端艺术字仍可能失败（可配合放大）
|
|
111
152
|
- **性能**：4K 图解码 ~230ms；PaddleOCR 每次调用需 ~2s 加载模型；大图网格渲染
|
|
112
153
|
token 随 size 增长（64×64 color ≈ 3–5K tokens）
|
|
154
|
+
- **ZCode 版 MCP 开销**：ZCode 版工具经 MCP stdio 子进程通信，单次调用比 DSH 版慢
|
|
155
|
+
（进程启动 + JSON-RPC 序列化）；高频/批量看图建议用 DSH 版
|
|
113
156
|
- **WebP 不支持**（提示转 PNG/JPEG）；GIF 只读首帧
|
|
114
157
|
- **多模态模型的描述不可全信**（本插件可交叉验证，但最终语义仍需人工判断关键场景）
|
|
115
158
|
|
|
116
159
|
## License
|
|
117
160
|
|
|
118
161
|
MIT
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
**DSH 插件生态**：GitHub topic `dsh-plugin` 会被 [dsh-plugin-marketplace](https://github.com/AwesomeHou/dsh-plugin-marketplace)
|
|
123
|
-
自动同步识别；精选列表见 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)。
|
package/package.json
CHANGED
|
@@ -1,50 +1,50 @@
|
|
|
1
|
-
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "picturereader",
|
|
3
|
+
"version": "1.0.2",
|
|
4
|
+
"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.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "src/index.js",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.js",
|
|
9
|
+
"./cordis.patch.yml": "./cordis.patch.yml",
|
|
10
|
+
"./package.json": "./package.json"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"src",
|
|
14
|
+
"cordis.patch.yml",
|
|
15
|
+
"skills",
|
|
16
|
+
"README.md",
|
|
17
|
+
"LICENSE"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"test": "node --test"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [
|
|
23
|
+
"dsh",
|
|
24
|
+
"dsh-plugin",
|
|
25
|
+
"deepseek-harness",
|
|
26
|
+
"image",
|
|
27
|
+
"vision",
|
|
28
|
+
"pixels",
|
|
29
|
+
"ascii",
|
|
30
|
+
"ocr",
|
|
31
|
+
"paddleocr",
|
|
32
|
+
"hue",
|
|
33
|
+
"multimodal"
|
|
34
|
+
],
|
|
35
|
+
"license": "MIT",
|
|
36
|
+
"author": "picturereader",
|
|
37
|
+
"engines": {
|
|
38
|
+
"node": "^22.19 || \u003e=24"
|
|
39
|
+
},
|
|
40
|
+
"dsh": {
|
|
41
|
+
"bundle": {
|
|
42
|
+
"patch": "./cordis.patch.yml"
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
"dependencies": {
|
|
46
|
+
"jpeg-js": "^0.4.4",
|
|
47
|
+
"omggif": "^1.0.10",
|
|
48
|
+
"pngjs": "^7.0.0"
|
|
49
|
+
}
|
|
50
|
+
}
|