小白我要学实用 Agent 教程与工具实测
目录

Episode 004

Word、PPT、Excel、PDF 转成 Markdown，哪些内容会丢？

把同一份自有测试内容分别做成 Word、PPT、Excel 和 PDF，再用 MarkItDown 0.1.6 转成 Markdown。四种文件的可见文字和表格都能拿出来，但标题层级、编号列表、链接地址和图片文字的保留情况差很多。

一句话结论四种文件都能拿到可见文字和表格；只有 Word 同时保留了标题层级、编号列表和链接地址。四种都没读出图片里的暗号。

实测版本
MarkItDown 0.1.6，固定 docx、pptx、xlsx、pdf extras
同题样本
四份文件都含标题、三项动作、表格、同一链接和同一张图片暗号
离线复跑
UV_OFFLINE=1 再跑四份，输出 SHA-256 与首次运行逐字节一致
本次未用
API key、外部 LLM、OCR 插件、Azure 和任何付费服务

68 秒看懂四种格式的差别

四份真实 Markdown 输出和四张说明卡

MarkItDown 0.1.6 将测试 Word 文件转出的真实 Markdown，能看到标题、编号列表、表格、链接和图片占位。
Word：真实 Markdown 输出 · 桌面真实输出截图：Word 保留了有效标题、Markdown 编号列表、表格和链接 URL；图片只剩占位，没有暗号文字。
说明卡显示 Word 保留标题层级、编号列表、表格和链接地址，但丢失图片暗号。
Word：五项检查说明卡 · 手机说明卡，不是产品界面：Word 是这次结构保留最完整的格式，但默认转换仍没有读图片里的字。
MarkItDown 0.1.6 将测试 PPT 转出的真实 Markdown，包含分片注释、正文、表格和图片文件引用。
PPT：真实 Markdown 输出 · 桌面真实输出截图：PPT 保留 slide boundary 和表格；标题与编号语义、链接 URL 丢失，图片只剩 Picture4.jpg 引用。
说明卡显示 PPT 只保留表格，没有保留标题层级、编号列表、链接地址和图片暗号。
PPT：五项检查说明卡 · 手机说明卡，不是产品界面：文字能拿到，但结构不能直接照原稿理解，图片引用也不能单独携带。
MarkItDown 0.1.6 将测试 Excel 转出的真实 Markdown，表格中出现 NaN 和 Unnamed 占位。
Excel：真实 Markdown 输出 · 桌面真实输出截图：单元格数据和表格保留，但空白区域变成 NaN、列名出现 Unnamed，链接地址和图片文字丢失。
说明卡显示 Excel 保留表格，但没有保留标题层级、编号列表、链接地址和图片暗号。
Excel：五项检查说明卡 · 手机说明卡，不是产品界面：Excel 适合先抽出可见单元格，但交给 AI 前要清掉 NaN 和 Unnamed 噪音。
MarkItDown 0.1.6 将测试 PDF 转出的真实 Markdown，包含纯文字和 Markdown 表格。
PDF：真实 Markdown 输出 · 桌面真实输出截图：可见文字和表格都拿到了，但标题、编号、链接 URL 和图片暗号没有保留。
说明卡显示 PDF 保留表格，但没有保留标题层级、编号列表、链接地址和图片暗号。
PDF：五项检查说明卡 · 手机说明卡，不是产品界面：这份可搜索 PDF 能抽出文字，但不等于结构、链接和图片文字都被理解。

五项内容保留检查

组别总分标题层级编号列表表格链接地址图片暗号
Word / DOCX411110
PowerPoint / PPTX100100
Excel / XLSX100100
PDF100100
  • Word / DOCX：五项里保留四项；图片暗号未识别，图片只剩不可携带的占位。
  • PowerPoint / PPTX：表格和分片信息在，但标题、列表、链接地址和图片文字没有通过。
  • Excel / XLSX：表格内容在，但 NaN、Unnamed 噪音明显，链接地址和图片文字没有通过。
  • PDF：可见文字与表格在，但原来的标题、编号、链接地址和图片文字没有通过。

我们怎么做同题实测

适合经常把办公文件交给 AI 整理、又想先确认 AI 到底能读到什么的人。这里测试的是四份内容相同的自有合成文件，不代表所有真实合同、报表、课件或扫描件。

  • 先做一组自有测试内容：同一个标题、说明、三项动作、四列表格、同一个 GitHub 链接，以及只存在于图片里的暗号“珊瑚-4729”。
  • 分别生成 DOCX、PPTX、XLSX 和可搜索 PDF，保存文件大小与 SHA-256；不是拿四份内容不同的网上样本做比较。
  • 固定 MarkItDown 0.1.6 和 docx、pptx、xlsx、pdf extras，四份文件都用同一种 `markitdown input -o output.md` 方式转换。
  • 机器逐项检查标题、列表、表格、链接 URL、图片暗号、NaN/Unnamed 和图片占位，再用 UV_OFFLINE=1 复跑并比较输出哈希。

哪些结论不能从这次测试推出

  • 只测试了四份内容相同的自有合成文件；复杂合并单元格、目录锚点、扫描 PDF、密码文件、真实合同和超大文件都没有覆盖。
  • 官方把输出定位为给 LLM 和文本分析使用，不是高保真的人工阅读版式转换；不能拿本次结果承诺排版还原。
  • 本次没有启用 markitdown-ocr、外部 LLM、Azure Document Intelligence 或 Azure Content Understanding；图片暗号没读出，不能外推这些可选能力也读不出。
  • GitHub Issue #20、#167、#1156 和 #314 只是公开个案，能提醒我们补测合并单元格、扫描件和目录链接，不能当成故障发生率。
  • MarkItDown 会继承当前进程的文件和网络访问权限。只处理可信文件；做服务时按官方安全建议使用最窄的 convert_local、convert_stream 等入口。

官方资料和真实 Issue 案例

Release v0.1.6

本次固定的最新非预发布版本；不要把它写成官方 GA。

PyPI 0.1.6

版本、安装包和 Beta 分类的公开记录。

MIT LICENSE

仓库许可原文；使用和分发仍应阅读原文。

SECURITY.md

安全问题上报入口和官方安全边界。

在自己电脑上复测一份文件

如果你想先检查一份办公文件交给 AI 后会剩下什么，可以用下面的最短步骤。第一次请用不重要的副本，不要直接处理来源不明的文件。

  • 确认电脑有 Python 3.10 或更高版本。官方建议使用单独的虚拟环境，避免和现有 Python 包冲突。
  • 按官方全量方式安装：`pip install 'markitdown[all]'`。如果只要本期四种格式，可按需安装：`pip install 'markitdown[pdf,docx,pptx,xlsx]'`。
  • 最短转换命令：`markitdown your-file.docx -o your-file.docx.md`。把扩展名换成 pptx、xlsx 或 pdf 就能分别处理。
  • 想完全复现本期版本，可用：`uvx --from "markitdown[pdf,docx,pptx,xlsx]==0.1.6" markitdown your-file.docx -o your-file.docx.md`。
  • 打开生成的 `.md`，逐项搜标题、编号、表格关键数字、链接 URL 和图片里的文字。不要只看到文件生成成功就直接交给 AI。
  • Excel 先搜索 `NaN` 和 `Unnamed`；PPT 检查 slide 分片、链接和图片引用；PDF 先判断是不是可搜索文本，扫描件要另做 OCR 复测。
  • 如果要把它接进自己的服务，别把用户给的任意路径或 URL 直接交给宽泛的 `convert()`；按官方安全建议优先使用 `convert_local()`、`convert_stream()` 等更窄入口。
  • 需要 OCR 时，要单独阅读 `markitdown-ocr` 的安装、LLM client/model、费用与隐私边界；本期默认转换结果不能代替 OCR 测试。

下载测试文件、输出和机器记录