xls-skill:Excel → Markdown,图片保留在单元格中
为什么需要这个技能
大多数 Excel 读取器(openpyxl、pandas、CSV 导出)只能看到单元格的值。两类图片会丢失:
- 单元格内图片。图片是单元格的内容。
- WPS Office 的“嵌入单元格”:单元格仅显示
=DISPIMG("ID_...",1);图片位于xl/cellimages.xml中。 - Microsoft 365 的“置于单元格内”/
IMAGE:单元格显示#VALUE!;图片通过xl/metadata.xml和xl/richData/访问。
- WPS Office 的“嵌入单元格”:单元格仅显示
- 浮动图片和文本框 绘制在网格上方(处理照片、标签、表单编号)。
该技能提取所有这些内容,将每张图片保存为文件,并将其写回 Markdown 表格中图片所在的单元格位置,以便读者同时看到表格及其图片:
| # | A | B | C | D |
|---|---|---|---|---|
| 2 | 支架 |  | 支架 \| 单元格内图片 | 4 |
如何运行
python <skill-dir>/scripts/xlsx_to_md.py <文件或文件夹> [...] -o <输出目录> [--ocr auto|off] [--ocr-lang eng+chi_sim]
- 接受
.xlsx、.xlsm、.xls或文件夹(递归)。每本工作簿打印一行,包含图片计数。 - 需要 Python 3.9+ 和
openpyxl。可选项:Pillow(图片尺寸)、Tesseract OCR(图片中的文本)、Microsoft Excel 或 LibreOffice(用于打开.xls)。 - 自测:
python <skill-dir>/tests/run_tests.py构建合成的 WPS 和 Microsoft 365 工作簿,并检查每张图片是否位于其单元格中。
每本工作簿的输出(<输出目录>/<名称>/)
| 文件 | 内容 |
|---|---|
<名称>.md | 工作簿索引,然后每个工作表作为完整的 Markdown 表格(不截断),图片内联在单元格中;每个表格上方显示工作表事实(隐藏状态、合并范围、隐藏行/列、批注、文本框、图表计数) |
<名称>.images.md | 每张图片一个条目:图片、工作表!单元格、类型、尺寸、附近单元格文本、OCR 文本和描述槽位 |
images/ | 每张图片作为文件,命名格式:`<工作表编号><工作表名称><单元格>_<单元格 |
sheets_csv/ | 工作表值;图片单元格持有 [image: images/...] |
image_manifest.csv | 工作表、单元格、类型(in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / floating)、文件、包部件、替换文本、尺寸、OCR、附近文本 |
formula_manifest.csv | 每个单元格的公式文本和缓存值 |
shapes_manifest.csv | 浮动文本框/形状中的文本,附有锚定单元格 |
conversion_report.json | 计数、警告、review_required |
代理的工作流程
- 转换。对工作簿运行脚本。
- 首先阅读报告。打开
conversion_report.json。对每个警告采取行动:image not found in package-> 该单元格标记为[image missing: ID];如实说明,不要猜测图片内容。.emf/.wmf saved as-is-> 在查看之前转换为 PNG(例如 Windows 上用 Pillow,其他平台用 LibreOffice)。charts> 0 -> 图表已计数但未渲染;如果图表重要,请打开或导出工作表。- 跳过 OCR 或缺少语言 -> 依赖你自己查看图片。
- 查看图片。打开
<名称>.images.md中列出的每个文件,并将每个description占位符替换为图片显示的内容:对象、可读文本(标签、型号、标记)、符号及其与附近单元格的关系。OCR 是提示而非答案;小标签文本通常需要裁剪或缩放。 - 结合表格和图片回答。使用 Markdown 表格获取确切的单元格值、公式和结构;使用图片获取“它看起来像什么/部件上写了什么”。对两者都引用
工作表!单元格。 - 如实报告差距。如果步骤 2 中的任何问题未解决,则将该工作簿标记为需要人工审核。
规则
- 当工作簿包含图片、文本框、颜色或隐藏内容时,CSV 或仅值的表格不是完整的证据。请检查工作表事实和清单。
- 将每张图片与其单元格和相邻单元格配对;切勿仅依赖图片顺序。
- 重要的文本可能位于单元格外部:文本框(表单编号、修订标记)、批注、页眉/页脚。文本框和批注会被提取;页眉/页脚不会被提取——如果缺少文档编号,请在 Excel 中检查它们。
- 颜色可能是数据(通过/失败、风险级别、状态)。此脚本不解码填充或条件格式;如果颜色承载含义,请使用 openpyxl 或页面导出进行检查,并说明映射关系。
- 合并范围仅保留左上角单元格的值;在解释空白单元格之前,请阅读
merged:行。 - 隐藏的工作表、行和列会被转换并列出,不会丢弃。如果答案来自隐藏内容,请说明。
- 不要在终端中信任乱码路径;在报告文件丢失之前,请检查实际路径是否存在。
限制
- 浮动图片链接到其左上角锚定单元格;跨多个单元格的图片会在清单中列出其
to_cell。 - 组合形状会被读取,但绘制为独立形状的箭头和标注在页面渲染中仅保持与照片的关系。当布局很重要时(“哪个箭头指向哪里”),请使用 Excel 或 LibreOffice 将工作表导出为 PDF/PNG,并与 Markdown 一起查看。
- 页眉/页脚(VML)和批注中的图片不会被提取。
.xls需要先使用 Microsoft Excel(Windows、pywin32)或 LibreOffice 转换;否则只能读取单元格值,并且报告会说明这一点。
