Microsoft MarkItDown：把本地文档转成 Agent 可读的 Markdown

它能产出什么

MarkItDown 是将多种文件转换为 Markdown 的 Python 工具。官方命令可把 PDF 输出到 document.md；这个文件可被人工检查，也可作为后续检索或 Agent 处理的输入。

最低门槛与安装入口

需要可用 Python 环境。README 给出 pip install 'markitdown[all]'，也允许只安装 pdf、docx、pptx 等所需可选依赖。首轮不要启用第三方插件、云端内容理解或真实机密文件。

本站实测：四种办公文件同题转换

四份自有文件都放入同一个标题、三项动作、四列表格、同一链接和只存在于图片里的暗号，再固定 0.1.6 转换。4/4 保留可见文字和表格；只有 DOCX 保留链接 URL；4/4 都没读出图片暗号；XLSX 还出现 NaN 和 Unnamed 噪音。

1. 转换并逐项核对

   操作

   用 uvx 固定 markitdown[pdf,docx,pptx,xlsx]==0.1.6，分别转换 DOCX、PPTX、XLSX 和 PDF，再检查标题、编号、表格、链接 URL、图片暗号和噪音。

   你应该看到

   四份 Markdown、机器核对 JSON、输入输出哈希和离线复跑记录都可下载复查。

   如何确认

   四次首次运行退出码均为 0；UV_OFFLINE=1 复跑后四份输出与首次运行逐字节一致；独立 Reviewer 复核结论与哈希。

   卡住时

   • 命令不存在时确认虚拟环境与安装位置。
   • 扫描件没有文本时先记录能力缺口，再评估 OCR；不要立即上传真实文件到外部服务。

权限、安全与可选费用

README 警告工具按当前进程权限执行 I/O，能访问进程有权访问的资源；不可信环境应清理输入并调用最窄的 convert_* 函数。第三方插件默认禁用。Azure 内容理解调用可能计费，因此基础转换与云增强要分开记录。

适用、不适用与当前证据

适合把可公开或已获授权文档变成可搜索文本，并愿意人工抽查的人。不适合期待复杂排版、图片语义和表格在所有文件中零损失，也不适合直接处理来源不明或高度敏感文件。本站已完成四份合成样本实测；合并单元格、扫描 PDF、密码文件、真实合同和超大文件仍未覆盖。若核心需求是传统文档格式之间的结构化转换而不是面向 LLM 的文本提取，可把 draft 节点 Pandoc 纳入后续对照；它并非已验证替代。

真实使用摩擦样本

以下为所有者仓库 Issue 中的单个用户报告样本，不能估计发生率或频率。维护者确认仅在页面存在明确 owner 回应或关联修复时成立；社区复现或插件说明也不自动构成维护者确认，本站编辑推断不等于复现。

• 用户报告：#1845 描述学术 PDF 转换后 Markdown 结构与格式失效，说明默认 PDF 转换不能被当作版面理解。
• 用户报告：#1601 描述 PDF 图片中的文字没有被 OCR 到输出，说明扫描内容与可选 OCR 路径必须分开验收。
• 用户报告：#1942 描述 ImageConverter 在 LLM API 鉴权、限流或网络失败时中断转换流程，提示可选图片描述路径需要单独记录 API 错误。