Community生产力与协作github.com

xls-skill

将 Excel 工作簿(.xlsx/.xlsm/.xls)转换为 AI 可读的 Markdown,保留每张图片在其单元格中的位置——包括嵌入单元格内部的图片(WPS Office 的 =DISPIMG 和 Microsoft 365 的“置于单元格内”),普通 Excel 读取器会无声地遗漏它们——以及浮动图片、文本框、公式、合并/隐藏结构和 OCR。适用于读取、转换、审计或回答包含照片、标签、徽标、屏幕截图、绘图或签名(单元格内或网格上)的电子表格。

xls-skill 是什么?

该技能用于将 Excel 工作簿(.xlsx/.xlsm/.xls)转换为 AI 可读的 Markdown 格式,并保留所有图片在单元格中的原始位置。它解决了普通 Excel 读取器(如 openpyxl、pandas)无法读取嵌入单元格内部图片的问题,包括 WPS Office 的 `=DISPIMG("ID_...",1)` 和 Microsoft 365 的“Place in Cell”功能。此外,它还提取浮动图片、文本框、公式、合并/隐藏结构和 OCR 文本。用户可通过命令行运行脚本,输出 Markdown 表格、图片文件、CSV 清单和转换报告。该技能在读取、转换、审计或回答包含照片、标签、徽标、屏幕截图、绘图或签名的电子表格时特别有用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hougw/xls-skill/tree/HEAD

Installed? Explore more 生产力与协作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

Parts!B2

文档

xls-skill:Excel → Markdown,图片保留在单元格中

为什么需要这个技能

大多数 Excel 读取器(openpyxl、pandas、CSV 导出)只能看到单元格的值。两类图片会丢失:

  1. 单元格内图片。图片是单元格的内容。
    • WPS Office 的“嵌入单元格”:单元格仅显示 =DISPIMG("ID_...",1);图片位于 xl/cellimages.xml 中。
    • Microsoft 365 的“置于单元格内”/ IMAGE:单元格显示 #VALUE!;图片通过 xl/metadata.xml 和 xl/richData/ 访问。
  2. 浮动图片和文本框 绘制在网格上方(处理照片、标签、表单编号)。

该技能提取所有这些内容,将每张图片保存为文件,并将其写回 Markdown 表格中图片所在的单元格位置,以便读者同时看到表格及其图片:

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | 支架 | ![Parts!B2](images/01_Parts_B2_cell1.png) | 支架 \| 单元格内图片 | 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

代理的工作流程

  1. 转换。对工作簿运行脚本。
  2. 首先阅读报告。打开 conversion_report.json。对每个警告采取行动:
    • image not found in package -> 该单元格标记为 [image missing: ID];如实说明,不要猜测图片内容。
    • .emf/.wmf saved as-is -> 在查看之前转换为 PNG(例如 Windows 上用 Pillow,其他平台用 LibreOffice)。
    • charts > 0 -> 图表已计数但未渲染;如果图表重要,请打开或导出工作表。
    • 跳过 OCR 或缺少语言 -> 依赖你自己查看图片。
  3. 查看图片。打开 <名称>.images.md 中列出的每个文件,并将每个 description 占位符替换为图片显示的内容:对象、可读文本(标签、型号、标记)、符号及其与附近单元格的关系。OCR 是提示而非答案;小标签文本通常需要裁剪或缩放。
  4. 结合表格和图片回答。使用 Markdown 表格获取确切的单元格值、公式和结构;使用图片获取“它看起来像什么/部件上写了什么”。对两者都引用 工作表!单元格。
  5. 如实报告差距。如果步骤 2 中的任何问题未解决,则将该工作簿标记为需要人工审核。

规则

  • 当工作簿包含图片、文本框、颜色或隐藏内容时,CSV 或仅值的表格不是完整的证据。请检查工作表事实和清单。
  • 将每张图片与其单元格和相邻单元格配对;切勿仅依赖图片顺序。
  • 重要的文本可能位于单元格外部:文本框(表单编号、修订标记)、批注、页眉/页脚。文本框和批注会被提取;页眉/页脚不会被提取——如果缺少文档编号,请在 Excel 中检查它们。
  • 颜色可能是数据(通过/失败、风险级别、状态)。此脚本不解码填充或条件格式;如果颜色承载含义,请使用 openpyxl 或页面导出进行检查,并说明映射关系。
  • 合并范围仅保留左上角单元格的值;在解释空白单元格之前,请阅读 merged: 行。
  • 隐藏的工作表、行和列会被转换并列出,不会丢弃。如果答案来自隐藏内容,请说明。
  • 不要在终端中信任乱码路径;在报告文件丢失之前,请检查实际路径是否存在。

限制

  • 浮动图片链接到其左上角锚定单元格;跨多个单元格的图片会在清单中列出其 to_cell。
  • 组合形状会被读取,但绘制为独立形状的箭头和标注在页面渲染中仅保持与照片的关系。当布局很重要时(“哪个箭头指向哪里”),请使用 Excel 或 LibreOffice 将工作表导出为 PDF/PNG,并与 Markdown 一起查看。
  • 页眉/页脚(VML)和批注中的图片不会被提取。
  • .xls 需要先使用 Microsoft Excel(Windows、pywin32)或 LibreOffice 转换;否则只能读取单元格值,并且报告会说明这一点。

相关技能