PDF、Word、PPT、EPUB 一键变 Markdown——这个 Agent Skill 把文档解析做了

做 AI Agent 工作流的人大概都遇到过这个痛点:用户扔过来一份 PDF、Word 或 PPT,想让 Agent 理解里面的内容,但 Agent 只会给你一段「这份文档大约有 10 页」的空话。问题的根源很简单——大多数 Agent 没有靠谱的本地文档解析能力,它们擅长处理文本,但拿到二进制文件就傻眼了。

Scribe MD 解决的就是这件事。它是一个独立的 Agent Skill,也可以当命令行工具用,能把你本地的 PDF、Word、PowerPoint、EPUB、HTML、RTF、CSV、Excel,甚至部分电子书格式(MOBI/AZW),忠实转成一份 Markdown 文件。

为什么是 Agent Skill,不只是命令行工具

大多数文档转换工具是独立 CLI:你手动调用,拿到输出,再手动喂给 Agent。Scribe MD 不同,它设计了一个 SKILL.md 文件,把自己「注册」为 Agent 的内置能力。安装后 Agent 会自动发现这个 Skill,当你扔过来一份 PDF 并说「帮我转成 Markdown」时,Agent 知道该调用哪个命令、该读哪个参考文档。

目前支持 Grok、Claude Code、Cursor、Codex 等主流 Agent,安装方式很简单:把整个文件夹拷到对应 Skills 目录即可。

• Grok:~/.grok/skills/scribe-md/
• Claude Code:~/.claude/skills/scribe-md/
• Cursor:~/.cursor/skills/scribe-md/
• Codex:按工具文档的 skills 目录放置
• 也可以放在当前项目目录下,仅对当前项目生效。

支持哪些格式

• PDF:普通 PDF 直接解析;扫描件和复杂排版可走 MinerU 云端或本地 PyMuPDF。
• Word:DOCX 精准还原标题、列表、表格和图片引用。
• PowerPoint:PPTX 是输入,不生成幻灯片;只提取文字和图片内容。
• EPUB / 电子书:直出 Markdown,配合 Calibre 还能处理 MOBI/AZW。
• HTML / RTF / Markdown:原生支持,不需要额外转换。
• 表格:CSV、TSV、XLSX,旧版 .xls 通过 xlrd 支持。
• 视频:配合 Whisper 做本地语音转写,输出带时间戳的 Markdown。

输出不只是 Markdown

运行 convert_with_media.py 后,--out 目录里会有三样东西:

• stem.md:转出的 Markdown 文本,忠实还原原文结构。
• manifest.json:来源元数据和媒体清单,记录每张图片/视频的来源页和位置。
• media/:抽出的图片和视频文件,按文档内引用组织。

如果开启 --emit-chunks,还会额外输出 JSONL 分块文件,方便直接喂给 RAG 系统或向量数据库。

几个实用特性

• 布局保真模式(--layout-fidelity high):对扫描件和复杂排版 PDF 做更细致的解析。
• 视觉模型描述图片(--image-analysis llm):调用 GPT-4o 等视觉模型为文档中的图片生成描述文字。
• Agent 自省模式(--image-analysis agent):不调外部 API,只写出任务文件,由当前 Agent 自己看图。
• MinerU 集成:可选走 MinerU 云端做 PDF 布局分析,适合扫描件和学术论文。
• 自包含设计:整个 Skill 目录是独立的,拷到任何地方都能跑,不依赖原仓库路径。
• 向后兼容:旧命令 doc-to-md 仍可用,Python import 名仍是 doc_to_md。

如果你在做 Agent 工作流,需要让 Agent 理解本地文档内容,Scribe MD 提供了一条比较干净的路径:装一次 Skill,之后 Agent 自己知道怎么处理 PDF、Word、PPT 和表格。不依赖外部服务(除非你选择开启 MinerU 或视觉模型),数据不离开本机。

项目地址:https://github.com/zwt0204/scribe-md