scientific-agent-skills 中的 MarkItDown 文件格式转换指南：内置转换器矩阵、行为边界与格式级实战

本篇技术指南围绕 scientific-agent-skills 仓库中 markitdown 技能的核心参考文档展开，系统讲解 Microsoft MarkItDown 0.1.6 对 PDF、DOCX、PPTX、XLSX、图片、音频、EPUB、ZIP、HTML、CSV 等常见格式的内置转换行为、依赖边界、网络/外部服务前提以及格式提示（Format Hints）机制。读完本文，你将能够按格式精确选装依赖、判断每种格式的输出能力与局限、规避"扫描件被本地 OCR""GIF 可转图片"等常见误判，并借助仓库自带脚本完成批量与文献级转换。

1. 文档定位与版本基线

[file_formats.md](https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills/blob/cc37669ed0f354619b1ae586e958609a87680718/skills/markitdown/references/file_formats.md?utm_source=gitcode_repo_files) 是 markitdown 技能的格式权威参考，其全文针对 MarkItDown 0.1.6（2026 年 5 月 26 日发布）编写。文中反复出现的 "Built-in"（内置）指转换器随 markitdown 包一并分发；需要特别注意的是，"内置"不等于"零依赖"——部分内置转换器仍需安装对应的 optional extra 才能真正工作。

该技能整体在 SKILL.md 中明确了两个 API 使用原则：

• 新代码统一使用 result.markdown 获取转换结果；
• result.text_content 仅作为软弃用（soft-deprecated）的兼容别名保留，不再作为新代码的推荐写法。

这一版本基线贯穿本文所有安装命令与代码示例，请勿混用其他版本。

2. 按格式安装：先选对 extra，再谈转换

MarkItDown 的 extras 设计决定了"最小可用包"与"全功能包"之间的选择权在用户手中。参考文档给出了三个典型的安装档位：

# 全量内置功能（含所有格式 extra）
uv pip install "markitdown[all]==0.1.6"

# 常见文档子集：PDF、Word、PPT、Excel
uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.6"

# 最小包：仅满足纯文本/HTML/CSV/ZIP/EPUB/IPYNB 路径
uv pip install "markitdown==0.1.6"

0.1.6 提供的 extras 全集为：pptx、docx、xlsx、xls、pdf、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding 以及 all。需要强调一个容易踩坑的点：[all] 并不包含独立的 markitdown-ocr 插件，也不包含 OpenAI 兼容客户端（见 SKILL.md 安装章节）。

仓库为此提供了环境自检脚本 inspect_installation.py：

markitdown --version
python scripts/inspect_installation.py

从源码看，该脚本会：

• 读取 markitdown 的已安装版本并与其内置目标版本 TARGET_VERSION = "0.1.6" 比对，版本不符时默认以非零码退出，除非传入 --allow-version-mismatch；
• 扫描 markitdown.plugin entry points 来发现已注册插件，但只发现、不加载；
• 探测 markitdown、markitdown-mcp、exiftool、ffmpeg 四个可执行文件是否存在；
• 支持 --json 输出机器可读报告，供自动化流程消费。

对应的 tests/markitdown/test_scripts.py 中 InstallationReportTests 验证了报告必须可 JSON 序列化、缺失的发行版应返回 None 而非抛异常等行为，可直接作为集成时的契约参考。

3. 内置转换器矩阵：一张表看懂全部格式

以下是参考文档中的核心转换器矩阵，它同时标注了每个格式的 extra 依赖、主要行为与关键局限，是本篇指南的主骨架：

输入	典型扩展名/来源	Extra	主要行为	重要局限/网络
纯文本	.txt、.md、可识别文本、JSON/XML 文本	Core	解码文本并保留内容	JSON/XML 不保证被规范化或美化打印
CSV	.csv、text/csv	Core	专门的 CSV 转 Markdown 表格转换	超宽/超大表格会产生很大的 Markdown
HTML	.html、.htm	Core	标题、链接、列表、表格与可读文本	不保留 CSS 布局、客户端渲染与视觉保真
RSS/类 Atom XML	feed 内容/URL	Core	面向 feed 的 Markdown	提供 URI 时需联网远程抓取
Wikipedia 页面	Wikipedia URL	Core	面向页面的 Markdown	需联网；URL 专用转换器
Bing 结果页	Bing 搜索 URL	Core	面向搜索结果页的 Markdown	需联网；HTML 与服务行为可能变化
YouTube	https://www.youtube.com/watch?...	youtube-transcription（获取字幕）	元数据、描述与可用字幕	抓取 YouTube 页面/字幕；字幕可能缺失或被限制
ZIP	.zip	Core	遍历成员并递归调用嵌套转换器	将不可信压缩包视为敌意输入；输出可能急剧膨胀
EPUB	.epub	Core	书籍元数据与结构化文本	复杂样式、固定版式、DRM 与交互内容不保留
Jupyter Notebook	.ipynb	Core	Notebook 单元格与内容转 Markdown	不重现运行时状态；转换期间单元格保持惰性文本
PDF	.pdf	pdf	提取既有文本与表格	扫描页无内置本地 OCR；多栏顺序与复杂表格需人工验证
Word	.docx	docx	标题、列表、链接、表格、图片/alt 文本、OMML 数学公式	修订痕迹、浮动版式与可视化分页无法忠实还原
PowerPoint	.pptx	pptx	幻灯片文本、表格、备注与形状排序	动画与版式保真丢失；图片描述需 LLM 客户端
Excel	.xlsx	xlsx	工作表渲染为 Markdown 表格	公式、图表、合并单元格与格式需到源文件层验证
旧版 Excel	.xls	xls	工作表渲染为 Markdown 表格	旧版解析器限制；无可视化工作簿保真
Outlook 邮件	.msg	outlook	邮件头与正文	附件与富格式可能需要单独处理
图片	.jpg、.jpeg、.png	Core	选定的 ExifTool 元数据；可选的 LLM 描述	内置转换器不做本地 OCR；图片可能被发送至外部 LLM
音/视频音频轨	.wav、.mp3、.m4a、.mp4	audio-transcription	元数据加语音转写文本	转写使用 SpeechRecognition 调 Google Web Speech；内容会离开本机

3.1 常见被过度宣称的格式能力（务必对照）

参考文档专门列出五条"常被夸大"的边界，用于纠正对 MarkItDown 的常见误解，实践时应逐条核对：

• 0.1.6 内置的 ImageConverter 只接受 JPEG 与 PNG，不支持 GIF 或 WebP；
• 内置 PDF 转换提取的是文本层；Tesseract 不在 MarkItDown 的 PDF 路径内（它不是本地 OCR 工具）；
• 该包不承诺页面范围、边界框、坐标或像素级忠实输出；
• JSON 与 XML 是按文本输入处理的，不是 schema 感知的转换；
• 一次成功的转换不意味着图表、公式、表格或阅读顺序被完整还原。

这些边界在 SKILL.md 的"Choose the Right Path"决策表中也有呼应：需要边界框、页面坐标或截图时应改用布局感知解析器（如仓库中的 LiteParse），需要 PDF 拆分/合并/表单/水印时应改用 pdf 技能——MarkItDown 的输出定位是"索引、文本分析、搜索与 LLM 摄取"，而非高保真视觉复现。

4. 分格式实战：行为、代码与验证清单

4.1 PDF：提取文本层，而非 OCR

适用于文本可选中的原生（born-digital）PDF：

from markitdown import MarkItDown

result = MarkItDown().convert_local("paper.pdf")
print(result.markdown)

0.1.5 版本改进了对齐/宽表格输出并部分支持编号列表；0.1.6 修复了跨 PDF 页面的线性内存增长问题。

对于扫描版 PDF（无文本层），参考文档给出四条可选路径，按序选择其一：

1. markitdown-ocr==0.1.0 搭配已获批准的视觉模型供应商；
2. Azure Document Intelligence；
3. Azure Content Understanding；
4. 内容不能离开环境时，使用本地 OCR/版式解析器。

不要宣称执行了 OCR，除非所选路径确实提供了 OCR。 转换后的验证清单至少包括：多栏论文的阅读顺序、公式/上标/符号、表头与行对齐、图注与脚注、参考文献与超链接、缺失页或空白的扫描区段。这一"成功转换≠完整转换"的理念贯穿本文所有格式。

4.2 DOCX：语义转换与 Mammoth 自定义映射

uv pip install "markitdown[docx]==0.1.6"

0.1.2 版本起支持 DOCX 数学公式（OMML）渲染。转换是语义级的，不是页面版式保留。验证重点：标题层级与列表嵌套、表格与合并单元格、OMML 公式、超链接与图片 alt 文本、脚注/尾注、修订痕迹与批注。

参考文档还提供了自定义 Mammoth style map 的用法，可用于把带特定段落样式的稿件映射为 Blockquote：

from markitdown import MarkItDown

converter = MarkItDown(style_map="p[style-name='Abstract'] => blockquote.abstract")
result = converter.convert_local("manuscript.docx")

4.3 PPTX：形状排序模拟阅读顺序

uv pip install "markitdown[pptx]==0.1.6"

转换器对形状排序以近似阅读顺序，并提取幻灯片文本内容。可选参数 llm_client、llm_model、llm_prompt 用于为幻灯片中的图片生成描述（该路径会把图片发送给外部 LLM）。验证清单：幻灯片顺序与边界、演讲者备注、组合/重叠形状、表格与图表标签、含关键文字的图片、仅靠位置/颜色/动画传达的内容。

4.4 XLSX 与 XLS：表格化方向，而非工作簿往返

uv pip install "markitdown[xlsx,xls]==0.1.6"

结果适合文本审阅与 LLM 摄取，但不是工作簿的往返（round trip）。验证清单：工作表名称与顺序、隐藏的行/列/工作表、合并单元格、公式文本与缓存/显示值的区别、日期/数字解释、图表/图片/批注/条件格式。

参考文档给出了一条重要建议：需要数值分析时，应先用 MarkItDown 做方向性了解，再直接用 dataframe 或电子表格库读取工作簿本身。

4.5 图片：元数据 + 可选 LLM 描述，而非本地 OCR

内置转换器支持 .jpg、.jpeg、.png。没有 LLM 客户端时，输出可能只包含选定的元数据，且当 ExifTool 不可用或文件无相关元数据时可能为空。

from markitdown import MarkItDown

result = MarkItDown(exiftool_path="/opt/homebrew/bin/exiftool").convert_local(
    "figure.png"
)

安全提示：只使用可信的 ExifTool 可执行文件。MarkItDown 0.1.3 起对 ExifTool 12.24 或更高版本有安全要求。视觉描述与 OCR 都属于外部处理路径，细节见 cloud_and_ocr.md。

4.6 音频：在线转写，不是离线能力

接受的扩展名为 .wav、.mp3、.m4a、.mp4：

uv pip install "markitdown[audio-transcription]==0.1.6"

实现方式是把音频转换为 SpeechRecognition 输入并调用 recognize_google()——这不是离线转写，转换保密录音前必须获得批准。该转换器不提供说话人分离（diarization）、时间戳、置信度或领域适配。

4.7 YouTube：页面 + 字幕抓取

uv pip install "markitdown[youtube-transcription]==0.1.6"
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o transcript.md

行为依次为：下载页面 → 提取标题、描述与选定元数据 → 请求可用字幕 → 优先英语，其次可用语言，并提供翻译回退。字幕可用性取决于 YouTube、视频本身、地理区域、cookies/网络策略与字幕权限。

4.8 CSV、JSON 与 XML：CSV 有专属表格转换器

CSV 有专门的表格转换器：

result = MarkItDown().convert_local("measurements.csv")

JSON 与 XML 通常按类文本格式处理。如果下游需要经过验证的记录，应使用 json、defusedxml 或 schema 感知的库直接解析源数据，而不是解析生成的 Markdown。

4.9 ZIP 与 EPUB：递归转换与安全边界

ZIP 转换会对归档成员递归调用 MarkItDown。参考文档要求转换前施加以下限制：

• 最大归档大小
• 最大成员数量
• 最大嵌套深度
• 压缩比限制
• 按成员类型的 allowlist

不要将转换本身当作压缩包的安全边界。 EPUB 转换面向文本型书籍结构；DRM 保护或固定版式的出版物可能失败或丢失关键视觉信息。

5. 远程与特殊来源：convert_uri 的四种 scheme

convert_uri() 接受四种 URI scheme：

• file:
• data:
• http:
• https:

file: 与 data: 在用户可控时依然可能危险；http: 与 https: 必须施加 SSRF、重定向、大小与超时控制。这与 SKILL.md 的核心操作规则一致：优先使用最窄的转换方法——本地路径用 convert_local()，受控字节用 convert_stream()，应用自行抓取后的 HTTP 响应用 convert_response()，convert_uri() 仅用于经过验证的可信 URI，而多态分发的 convert() 只在来源可信时才使用。完整安全边界见 security.md。

6. Azure 云端格式集：路由能力 ≠ 本地解析能力

6.1 Document Intelligence

0.1.6 集成支持：

• 文档：DOCX、PPTX、XLSX
• OCR/版式：PDF、JPEG、PNG、BMP、TIFF
• HTML 虽在枚举中存在，但不在转换器的默认文件类型列表中

默认 API 版本为 2024-07-31-preview。文档字节会被发送到 Azure。

6.2 Content Understanding

0.1.6 集成可路由：

• 文档：PDF、DOCX、PPTX、XLSX、HTML、TXT、Markdown、RTF、XML
• 邮件：EML、MSG
• 图片：JPEG、PNG、BMP、TIFF、HEIF/HEIC
• 视频：MP4、M4V、MOV、AVI、MKV、WebM、FLV、WMV
• 音频：WAV、MP3、M4A、FLAC、OGG、AAC、WMA

"支持"在这里指 Azure Content Understanding 的路由能力，而非本地内置解析。 每一次路由转换都是外部的、可能计费的操作。两类 Azure 服务的凭据、数据流与成本细节，参见 cloud_and_ocr.md。

7. 格式提示（Format Hints）：字节无文件名时如何自救

当字节流缺少有意义的文件名时，用 StreamInfo 显式声明格式：

from markitdown import MarkItDown, StreamInfo

with open("upload.bin", "rb") as stream:
    result = MarkItDown().convert_stream(
        stream,
        stream_info=StreamInfo(
            extension=".pdf",
            mimetype="application/pdf",
            filename="upload.pdf",
        ),
    )

CLI 等价写法：

markitdown < upload.bin -x .pdf -m application/pdf -o output.md

值得注意的是，非可寻址（non-seekable）流在转换前会被完整拷贝进内存，超大流应预先分流或限制大小。

8. 仓库源码纵深：三个脚本如何落实格式边界

markitdown 技能目录下有三个配套脚本（scripts/），它们恰好把参考文档中的格式边界落实为可运行的工程实现，tests/markitdown/test_scripts.py 则逐一验证了这些行为。

8.1 batch_convert.py：批量转换的安全护栏

核心设计（DEFAULT_EXTENSIONS 与 EXTERNAL_SERVICE_EXTENSIONS 两个常量）直接对应文档的格式矩阵：

• 默认扩展名集合为 .csv、.docx、.epub、.htm、.html、.ipynb、.jpeg、.jpg、.json、.msg、.pdf、.png、.pptx、.txt、.xls、.xlsx、.xml——刻意排除音视频；
• EXTERNAL_SERVICE_EXTENSIONS = {".m4a", ".mp3", ".mp4", ".wav"}，因为 markitdown[all] 下这些本地文件会触发 Google Web Speech，把文件送离本机；
• 测试 test_the_defaults_carry_no_audio_or_video_formats 断言两个集合交集为空，从机制上杜绝默认批量任务意外外发数据；
• CLI 传入这些音频扩展名时必须显式加 --allow-external-services，否则直接报错。

其他工程细节：输出名保留源后缀（paper.pdf.md 而非 paper.md，避免 report.pdf 与 report.docx 相互覆盖）、跳过符号链接、递归时镜像子目录、通过临时文件 + replace 实现原子写入、--max-bytes 默认 256 MiB 限制源文件大小、可选 JSON manifest 记录每次转换的 status/title/characters/error。调用示例：

python scripts/batch_convert.py documents/ markdown/ \
  --recursive \
  --extensions .pdf .docx .pptx .xlsx \
  --manifest markdown/manifest.json

8.2 convert_literature.py：带溯源信息的文献集合转换

面向 Author_Year_Title.pdf 命名约定的论文目录，infer_metadata 用 FILENAME_PATTERN = ^(?P<author>.+?)_(?P<year>(?:19|20)\d{2})_(?P<title>.+)$ 推断作者/年份/标题，并只信任 1900–2099 之间的年份（测试用例覆盖了 Smith_1899_Old.pdf 被拒绝的场景）。每个输出文件都会写入带 YAML front matter 的溯源信息：标题、作者、年份、来源路径、流式分块计算的 SHA-256、转换时间与 markitdown 版本；--create-index 还会生成按年份分组的 INDEX.md 与 catalog.json：

python scripts/convert_literature.py papers/ literature-markdown/ \
  --recursive \
  --create-index

这与参考文档"记录来源路径/URI、包版本、转换模式"的质量检查要求一一对应，也印证了"保留原始文档为权威工件"的原则。

8.3 质量检查总览

SKILL.md 的 Quality Checks 章节给出了转换后五步检查法：确认输出非空且为 UTF-8；比对标题、列表、链接、表格、公式、注释与工作表边界；目视检查图表、扫描页与多栏版式；记录来源/版本/模式/插件与失败项；保留原始文档为权威工件。配合参考文档的分格式验证清单使用，即可建立完整的转换验收流程。

9. 常见问题速查

问题	对应修复
MissingDependencyException	安装匹配的固定版本 extra，或直接 [all]
UnsupportedFormatException	补充 StreamInfo/CLI 提示（-x/-m）、安装所需 extra，或改用插件/其他解析器
图片输出为空	安装 ExifTool 获取元数据，或配置已批准的视觉客户端
扫描版 PDF 文本很少	使用 markitdown-ocr、Document Intelligence 或 Content Understanding
text_content 警告或旧示例	一律替换为 result.markdown
插件未被使用	先确认 markitdown --list-plugins，再显式开启插件
内存占用大	避免巨型 data: URI 与非可寻址流；拆分输入或做有界预处理
远程 URI 风险	在 convert_response() 前验证 scheme、目标、重定向、大小与超时
Windows 控制台字符丢失	优先 -o output.md，其以 UTF-8 写入

更多 API 细节（类、结果对象、CLI 参数、异常）、批量/RAG 工作流配方与 0.0.x→0.1.6 的迁移差异，可继续阅读 api_reference.md、workflows.md 与 migration.md。

10. 一句话总结

MarkItDown 0.1.6 的价值在于"以合理的结构保真度把异构文档统一转为 Markdown"，其边界同样清晰：不做本地 OCR、不做版式还原、不承诺 PDF 坐标/页范围、部分格式依赖外部服务。掌握本文的转换器矩阵与格式级验证清单，即可在 scientific-agent-skills 的 Agent 工作流中安全、可审计地完成科学文献与数据的 LLM/RAG 摄取。