convert-excel-to-md

将 Excel 转换为 Markdown

何时使用此技能

只要存在需要理解或处理的 .xlsx 文件，就触发此技能——例如，用户附上了一个电子表格并就其提问、想要数据摘要、想要提取特定的行或值，或者想要一并处理某个文件夹中的多个工作簿。Excel 原生的 .xlsx 格式是一个压缩的 XML 包，无法作为纯文本可靠读取，因此请始终先使用此技能中的脚本将其转换为 Markdown，而不要尝试直接打开或解析该文件。

此技能仅支持 .xlsx。如果被要求转换旧版 .xls 文件，请告知用户该格式不受支持，并请其先将其重新保存为 .xlsx（Excel：文件 > 另存为 > Excel 工作簿 (.xlsx)）。

混合文件类型： 当用户引用包含多种受支持文件类型（.pdf、.docx、.xlsx）的文件夹或文档集合时，此技能只处理 .xlsx 文件。Agent 还必须并行调用同类技能：

• convert-pdf-to-md 用于任何 .pdf 文件
• convert-word-to-md 用于任何 .docx 文件

绝不要处理一个文件夹却静默跳过某种受支持的文件类型。当存在混合类型时，必须同时调用这三个技能。

环境设置（每个环境一次）

在给定环境中进行首次转换之前，请逐步遵循 references/setup.md，以确保已安装 Python、pip 和 markitdown 包。请主动执行此操作，而不要猜测环境是否已就绪——如果发现缺少 markitdown，脚本本身也会失败并给出指向该文件的明确提示，因此如果你相当确信设置已经完成，也可以安全地先尝试转换。

用法

转换脚本位于 scripts/convert_excel_to_md.py。

输出结构： MarkItDown 的 XLSX 转换器会将每个工作表渲染为各自的 ## <SheetName> Markdown 表格——它完全不支持嵌入图像。此脚本会单独提取真正的嵌入图像（光栅图片，而非图表），并将它们映射到所属的工作表，为每个文档写入一个自包含的文件夹：

<name>/
    img/
        sheet001_<sheetname>_img001.<ext>
        sheet002_<sheetname>_img001.<ext>
        ...
    <name>.md          (each sheet's images appear right after its table,
                         under a "#### Images in this sheet" heading)

这是按工作表放置，而非精确的单元格位置——这是 MarkItDown 稳定输出锚点（## <SheetName> 标题）所能允许的最细粒度。如果工作簿没有嵌入图像，则不会创建 img/ 文件夹或图像部分。原生 Excel 图表不会作为图像提取（只有实际嵌入的图片才会被提取——图表需要由 Excel/LibreOffice 渲染，而此轻量级技能不会这样做）。

单个文件：

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"

这会在源文件旁边创建一个 workbook\ 文件夹（其中包含 workbook.md，以及存在时的 workbook\img\）。要显式控制目标文件夹：

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"

一个包含多个工作簿的文件夹（批处理模式）：

python scripts\convert_excel_to_md.py "C:\path\to\folder"

添加 --recursive 以同时包含子文件夹：

python scripts\convert_excel_to_md.py "C:\path\to\folder" --recursive

默认情况下，每个找到的 .xlsx 文件都会在其旁边获得各自的 <name>\ 输出文件夹。传入 -o "C:\path\to\output_parent" 可将所有生成的 <name>\ 文件夹集中到单独的父目录下（与 --recursive 组合使用时，会保留子文件夹结构）。

转换后，请读取生成的 .md 文件，以执行用户所要求的实际分析——脚本的任务只是生成准确的 Markdown（和图像），而不会解释内容。

决定输出去向

默认 — 始终输出到源文件旁边。 <name>/ 文件夹 创建在源 .xlsx 所在的同一目录中。这是所有情况下都必须遵循的 默认行为。除非用户明确要求 其他位置，否则不要覆盖此行为。

仅当用户明确提供输出路径时（例如， "将输出保存到 C:\output"、"将结果放到 D:\work"），才使用 -o。不要 基于 Agent 的当前工作目录、会话状态 文件夹或任何隐含位置来传递 -o。

如果无法完全解析源文件路径 — 例如， 用户只提供了文件名而没有目录，或者路径不明确 — 在运行转换之前，使用 ask_user 确认完整的绝对路径。绝不要 猜测或假定目录。

故障排除

症状	可能原因	修复方法
ModuleNotFoundError: No module named 'markitdown' / 退出码 2	未安装 MarkItDown	遵循 references/setup.md
ERROR: Unsupported file type '.xls' / 退出码 3	旧版 .xls，而非 .xlsx	请用户重新保存为 .xlsx
ERROR: Input path not found / 退出码 3	路径错误，或文件已移动	与用户确认正确的路径
批量输出中出现 FAILED <file> -> ...	该特定文件已损坏、受密码保护，或无法读取	报告哪些文件失败；批次中的其他文件仍然成功
NOTE: skipped N non-.xlsx file(s)	文件夹中包含非 Excel 文件	预期行为 — 这些文件会被有意忽略
工作表的图表未显示为图像	图表是图表对象，而非嵌入的图片 — 此技能仅提取真正嵌入的栅格图像	预期行为；如果用户特别需要图表图像，请说明此限制