图片结构化分析SKL-666666/image-analysis-skill

🖼️ image-analysis — 图片结构化分析工具

让 DeepSeek 等纯文本 AI 模型"看懂"图片：OCR 文字提取 + 形状/颜色/控件/图标识别 + 表格识别 + 布局与层级分析，输出结构化 Markdown 报告。

一句话：把图片"翻译"成模型能读的文字报告，纯文本模型也能看图。

适用于：UI 截图、网页、流程图、架构图、表格报表、表单页面、聊天记录、文字文档。照片/海报可给出配色与版面（内容理解有限）。

✨ 功能特性

| 能力 | 说明 |
|---|---|
| 🔤 双引擎 OCR | Windows 内置 OCR + RapidOCR 并行识别、去重取并集，识别率更高 |
| 🔷 形状识别 | 矩形 / 圆形 / 线段 / 按钮 / 徽章，带坐标（百分比）、颜色、功能猜测 |
| 🧱 布局与层级 | 区域归纳 + 父子包含树（哪个元素在哪个卡片内） |
| 📊 表格识别 | 有竖线的网格表格 + 无竖线表格（列位置从文字推断） |
| 🎨 彩色字符画 | 文本色码渲染，模型可直接读取版面 |
| 📐 公式规范化 | 数学符号自动规范化（x²、≥、− 等） |
| ⚡ 缓存与批量 | 按文件 MD5 缓存秒回；多图/目录并行分析 |
| 🎛️ 零门槛 | 无需配置，Windows 开箱即用（install_deps.bat 一键装依赖） |

🧠 工作原理

当前主流大模型（如 DeepSeek）是纯文本模型，无法直接处理图片输入。本工具在本地完成图像理解：

图片 → 双引擎 OCR + 形状/颜色/表格/图标/布局分析 → 八段式 Markdown 报告 → 喂给模型

报告包含文字、坐标、颜色、结构、层级等全部信息，模型据此回答"图里有什么"。

📦 环境要求

- Windows 10/11（OCR 使用系统内置引擎）
- Python 3.9+（安装时勾选 Add Python to PATH）
- 中文语言包（可选但推荐）：设置 → 时间和语言 → 语言，包含中文（否则 OCR 只认英文）
- 可选加速：python -m pip install rapidocr_onnxruntime（约 100MB），装后自动启用双引擎

🚀 安装（2 步）

:: 1. 安装 Python 3.9+（见上）
:: 2. 双击 install_deps.bat —— 等价于：
python -m pip install pillow numpy opencv-python-headless

验证：python scripts\analyze_image.py 任意图片.png --plain，看到八段式报告即成功。

🤖 导入为 Agent 技能

scripts/ 目录是自包含的技能包（SKILL.md 技能定义 + 脚本），可直接导入到支持 Agent Skills 的客户端，让 agent 获得"看图"能力：

① 先安装依赖（二选一）
install_deps.bat            # Windows 下双击运行
或 python -m pip install pillow numpy opencv-python-headless

② 把 scripts/ 目录复制为技能（以 ZCode 为例）
cp -r scripts ~/.zcode/skills/image-analysis      # ZCode

导入后向 agent 发送图片或截图的本地路径并提问（如"分析这张图""截图里是什么"），agent 会按 SKILL.md 中的流程自动调用脚本，输出结构化报告。

⚠️ 兼容性声明：部分 Agent 工具不允许向单模态（纯文本）模型发送图片，图片内容会被忽略或直接报错——本技能正是通过"本地脚本分析 + 文字报告"来规避该限制。目前仅在 ZCode 上测试验证成功，在其它客户端使用前请先自行验证其行为。

提示：技能目录名即技能名，可自行修改；SKILL.md 中的 description 决定了 agent 何时自动触发该技能。

📖 快速上手

单张图（推荐加 --plain，色码为文本标签更易读）
python scripts\analyze_image.py 截图.png --plain

批量并行（多图或目录，默认 3 进程）
python scripts\analyze_image.py 图1.png 图2.png 某目录 --plain --out-dir 结果目录 --workers 4

深色主题图 / 小图自动处理，无需额外参数

命令行参数

| 参数 | 说明 | 默认 |
|---|---|---|
| 图片路径... | 可多个图片或目录（自动扫描 png/jpg/jpeg/webp/bmp） | 必填 |
| --plain | 字符画用 [#RRGGBB] 文本色码（模型易读） | 关（ANSI 色码） |
| --width N | 字符画宽度 | 72 |
| --no-ascii | 不生成字符画（省 token） | 关 |
| --out 文件 | 单图输出文件 | 图片名_分析.md |
| --out-dir 目录 | 批量输出目录 | 当前目录 |
| --ocr {auto,windows,rapid,both} | OCR 引擎选择 | auto |
| --workers N | 多图并行进程数 | 3 |
| --cache-dir 目录 | 报告缓存目录（按文件 MD5） | ~/.cache/image-analysis |
| --no-cache | 禁用缓存（强制重新分析） | 关 |

📋 输出报告（八段式）

1. 识别置信度 — 高/中/低，决定数据引用力度
2. 整体信息 — 原图尺寸、主要颜色及占比
3. 元素清单 — 父容器、功能(猜测)、类型/形状、坐标、大小、颜色、文字
4. 布局结构 — 顶栏/侧边栏/内容容器/连线/图标归纳
5. 层级关系 — 父子包含树
6. 文本块聚类 — 文字按段落/卡片分组
7. 表格识别 — 自动转 Markdown 表格
8. OCR 全文 — 全部文字及位置，公式行标注 [公式]

⚠️ 能力边界（如实告知）

- 图标识别：内置 15 种常见图标（搜索/设置/菜单/关闭/返回/加号/扫码/分享/收藏/点赞/下载/更多/播放/用户/时钟/删除），风格不匹配会漏报（宁缺勿错）
- 照片/复杂插画：只能给出主色和色块分布，内容理解有限
- 小字/美术字： 📦 完整交付包 zip（含本说明 + 技能 + 脚本 + 安装器，解压即用）不随源码存储，请到 GitHub Releases 下载：v1.0.0 · image-analysis-skill-v1.0.0.zip

🤝 使用建议

- 作为 ZCode Agent Skills 使用时，将 scripts/ 目录导入技能目录即可生效（见上文「导入为 Agent 技能」），SKILL.md 包含完整使用流程
- 与多模态视觉模型配合使用效果更佳：本工具负责结构化提取，视觉模型负责语义理解