---

name: image-to-xlsx

description: 从图片中提取表格数据并生成Excel文件。当用户提供截图、照片或扫描件中的表格数据，要求转成Excel/xlsx时触发。支持多张图片批量提取，自动识别列结构，数值类型自动识别（Excel可直接计算）。触发词：图片转Excel、截图转表格、图片提取数据、图片转xlsx、image to xlsx、screenshot to spreadsheet。

agent_created: true

version: "2.0.0"

---



# 图片转Excel (Image to XLSX)



## 概述



从用户提供的图片中提取表格/列表数据，生成标准 `.xlsx` 文件。适用于 CRM 截图、报表截图、客户名单照片等场景。



**零第三方依赖** — 纯 Python 标准库（zipfile + json + tempfile），无需安装 openpyxl、pandas 等。



**v2.0 升级**：

- 数值自动识别为数字类型（非文本），Excel 可直接 SUM/AVG/IF

- 支持多工作表（multi-sheet）

- 输入容错：空数据、短行、None 值、非法 JSON 均有优雅处理



## 触发条件



- 用户提供1张或多张包含表格/列表数据的图片

- 要求输出为 Excel/xlsx 格式

- 典型表述："把这些图片里的内容生成Excel"、"截图转表格"、"图片数据提取"



## 完整工作流



### Step 1: 读取所有图片，提取数据



1. 逐张 Read 读取图片文件，用视觉能力识别表格内容

2. 按图片顺序和图片内行顺序，提取每行数据

3. 确定列名（用户指定，或从图片表头推断）



### Step 2: 生成 JSON 数据文件



将提取的数据写成 JSON 文件。



**单工作表格式**：



```json

{

    "sheet_name": "客户列表",

    "freeze_header": true,

    "headers": ["序号", "客户ID", "客户姓名", "当前跟进人"],

    "columns": [

        {"name": "序号", "width": 8},

        {"name": "客户ID", "width": 12},

        {"name": "客户姓名", "width": 16},

        {"name": "当前跟进人", "width": 14}

    ],

    "data": [

        [1, 61459, "魏国祥", "赵巍"],

        [2, 77780, "戴慧敏", "赵巍"]

    ]

}

```



**多工作表格式**：



```json

{

    "sheets": [

        {

            "sheet_name": "客户列表",

            "headers": ["序号", "姓名", "金额"],

            "data": [[1, "张三", 5800.50]]

        },

        {

            "sheet_name": "订单明细",

            "headers": ["订单号", "状态"],

            "data": [["ORD-001", "已付款"]]

        }

    ]

}

```



字段说明：

- `sheet_name`: 工作表名称，可选，默认 "Sheet1"

- `freeze_header`: 是否冻结首行，可选，默认 true

- `headers`: 列名列表，必填

- `columns`: 列宽配置，可选，默认全部 width=12

- `data`: 二维数组，每行对应一行数据，必填（可为空数组）

- `sheets`: 多工作表数组，每个元素包含上述字段



**数值类型规则**（自动识别，无需手动标记）：

- 整数（int 或 `"123"` 样字符串）→ Excel 数字格式 `#,##0`

- 小数（float 或 `"1.5"` 样字符串）→ Excel 数字格式 `#,##0.00`

- 文本（含中文/字母等）→ Excel 文本格式

- `null` / `None` → 空单元格



JSON 文件保存到临时目录。



### Step 3: 运行 build_xlsx.py 生成 xlsx



```bash

python SKILL_DIR/scripts/build_xlsx.py <input.json> <output.xlsx>

```



> `SKILL_DIR` 为本 Skill 的安装目录。Windows 环境需加 `PYTHONUTF8=1`：

> `PYTHONUTF8=1 python SKILL_DIR/scripts/build_xlsx.py <input.json> <output.xlsx>`



输出路径默认保存到当前工作目录下，文件名由用户指定或自动命名。



### Step 4: 验证并交付



用 zipfile 快速验证生成的 xlsx：



```bash

python -c "

import zipfile, xml.etree.ElementTree as ET

z = zipfile.ZipFile('<output.xlsx>')

ns = {'m': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}

with z.open('xl/worksheets/sheet1.xml') as f:

    rows = ET.parse(f).findall('.//m:row', ns)

    print(f'Rows: {len(rows)} (1 header + {len(rows)-1} data)')

print('XLSX valid!')

"

```



验证通过后用 present_files 交付给用户。



## 重要注意事项



1. **Windows 环境加 PYTHONUTF8=1**：Python 默认用系统编码，不加此变量中文可能乱码

2. **数值自动识别为数字类型**：整数和小数会自动写入为 Excel 数字格式（非文本），可做 SUM/AVG/IF 等计算；文本内容仍为文本格式

3. **支持多工作表**：通过 `sheets` 数组可生成包含多个 sheet 的 xlsx

4. **输入容错**：空数据生成仅含表头的文件；行数据比表头短/长自动截断/跳过；None 值生成空单元格；缺失 headers 报错提示

5. **支持超过 26 列**：内置 AA、AB... 列名计算，支持任意列数

6. **列宽可自定义**：通过 columns 字段指定，不指定则默认 12

7. **临时文件自动清理**：build_xlsx.py 在工作目录生成 XML 后自动删除



## 脚本路径



- `scripts/build_xlsx.py` — 核心生成脚本，接收 JSON 输入，输出 xlsx



## Python 依赖



- **无第三方依赖**（纯标准库 zipfile + tempfile + json + re）

- Python 3.8+ 即可运行