任意格式转 Markdown — Any File to Markdown

你现在运行 any-to-markdown 技能。目标：把一坨现实里的杂格式文件——.docx / .xlsx / .pptx / .epub / .html / .zip / .csv / .json / .xml / 简单 .pdf——一口气转成干净、可签入仓库、可入 RAG、可贴进笔记的标准化 Markdown。批量进，批量出，每个输入文件一份同名 .md，全程本地、零商业 API key。

底层是微软官方的 MarkItDown（Python pip 包 + 单一 CLI）：MIT、134k+ stars、活跃维护。课程不再包一层 wrapper —— 直接用上游 CLI，shell 一行就把批处理串起来。

这门课做什么（边界写在第一屏）

• ✅ 做：把 DOCX / XLSX / PPTX / EPUB / HTML / ZIP / CSV / JSON / XML / 简单文本型 PDF 批量 → 标准化 .md（同名落盘）。
• ❌ 不做：扫描件 OCR、复杂 PDF 表格深度还原、LaTeX 公式从图片里抠出来、音频转写、图片 LLM 描述。
• 📎 复杂 PDF 怎么办：如果你的 PDF 是扫描件、含公式、多栏排版或表格密集，请改用 parse-docs 课程（MinerU + Marker）—— 那才是 PDF 深度解析的正确入口。本课程在 SOP 与 popularTask 2 都会显式分流。
• 🔒 铁律：禁用任何会引入第三方 key 的 plugin——--use-docintel（Azure Document Intelligence）、image description（需要 OpenAI/Anthropic key）、Whisper 音频转写 plugin、第三方 OCR plugin 全部不开。课程承诺零 API key、零联网，所有转换都在你本地完成，不调用任何远端服务做兜底。

与 parse-docs 的区别一句话：广度 vs 深度。本课收一坨杂格式文件做标准化流水线；parse-docs 专攻硬 PDF / 扫描件的精解析。两门正交，按文档类型选一门即可。

前置条件

• Python ≥ 3.10（python3 --version 检查；低于 3.10 先升级）
• 能访问公开 PyPI（首次安装拉 markitdown 及其依赖，免 key）
• 完全本地、无需登录、无需后端、无需 clone 任何私有仓库
• 没有 GPU 也能跑，CPU 即可；内存几百 MB 量级

安装（一次到位）

强烈建议装在 venv 里，避免和系统 Python 打架（Ubuntu 24+ 的 PEP 668 会拒绝直接 pip install 到系统环境）：

python3 -m venv .mdvenv
source .mdvenv/bin/activate
pip install --upgrade pip
pip install 'markitdown[all]'
markitdown --version

[all] extra 拉齐 markitdown 支持的所有本地格式解析依赖（docx / xlsx / pptx / epub / html / zip / pdf 等）。装好后 markitdown --version 应当打出版本号（例如 markitdown 0.1.x）。

工作流程

1. 单文件即时转

markitdown ./report.docx -o ./report.md

或者直接 stdout（管道友好）：

markitdown ./report.docx > ./report.md

支持的扩展名：.docx .pptx .xlsx .xls .pdf .epub .html .htm .csv .json .xml .zip .txt .md .rss .atom，以及常见图片/音频容器（图片/音频本课不开启 LLM/Whisper 描述）。

2. 批量目录转

把 ./docs_in/ 下所有支持的格式一口气标准化到 ./docs_out/，每个输入文件 → 同名 .md：

mkdir -p docs_out
shopt -s nullglob nocaseglob
for f in docs_in/*.{docx,xlsx,pptx,epub,html,htm,csv,json,xml,zip,pdf,txt}; do
  base="$(basename "$f")"
  out="docs_out/${base%.*}.md"
  if markitdown "$f" -o "$out" 2>/dev/null; then
    echo "  ✓ $f → $out"
  else
    echo "  ✗ $f (跳过)"
  fi
done
shopt -u nullglob nocaseglob

3. 产出 INDEX.md（让用户一眼看全）

跑完批处理后，给用户一份索引：列出每个源文件 → 对应 .md 路径 → 字数 → 是否含表格 → 是否疑似空白。最简单的实现：

{
  echo "# Conversion Index"
  echo ""
  echo "| Source | Markdown | Words | Has table | Status |"
  echo "| --- | --- | ---: | :---: | :---: |"
  for md in docs_out/*.md; do
    base="$(basename "$md" .md)"
    src=$(ls docs_in/${base}.* 2>/dev/null | head -1)
    words=$(wc -w < "$md" | tr -d ' ')
    has_table=$(grep -q "^|" "$md" && echo "✓" || echo "—")
    status=$([ "$words" -gt 5 ] && echo "ok" || echo "⚠ empty?")
    echo "| ${src:-?} | $md | $words | $has_table | $status |"
  done
} > docs_out/INDEX.md

4. 解析后自检（务必做）

每份 .md 在交付前肉眼或脚本核对一遍：

1. 标题层级还在（DOCX 的 H1/H2 → # / ##，PPTX 每页有 <!-- Slide number: N --> 分隔）。
2. 列表 / 编号没崩，缩进正常。
3. 表格有真实的 | ... | 单元格（XLSX 至少有一行表头 + 几行数据）。
4. 链接、加粗、斜体保留。
5. 无明显乱码或纯空 .md（空文档可能是源文件本身就空，或扩展名说谎；在 console 把这些挑出来让用户决定）。

铁律 / 反模式

• 不开任何 plugin。-d / --use-docintel / OpenAI image-description / Whisper / 第三方 OCR 一律不要带，原因是它们会拖你和用户进 OpenAI/Azure/HF key 的 onboarding 漏斗，违反本课「零商业 API key」的承诺。
• 复杂 PDF 不要硬啃：扫描件、公式、多栏论文请告知用户改用 parse-docs 课程，那才是 PDF 深度解析的工具链。
• 不要伪造内容：markitdown 是确定性转换器，不会脑补；如果某份文件转出来是空的，把那份文件名列给用户，不要替它编内容。
• 不要写入用户系统 Python：始终在 venv 或 pipx 里装；遇到 error: externally-managed-environment 不是 markitdown 的问题，是 PEP 668，按上面 venv 指引即可。

产出物（用户拿到的就是这些）

• docs_out/<同名>.md —— 每个输入文件一份干净 Markdown（标题/列表/表格/链接保留，PPTX 每页带 slide 分隔注释）。
• docs_out/INDEX.md —— 整批转换的总览表：源 → md → 字数 → 含表格 → 状态。
• 转换报告（console / 回复里）：哪些文件成功、哪些跳过、哪些疑似空。

学习完成后

告诉用户：

我已经学会了 any-to-markdown。给我一个文件或一个文件夹（DOCX/XLSX/PPTX/EPUB/HTML/ZIP/CSV/JSON/XML/简单 PDF），我在本地用官方 MarkItDown 一键转成同名 .md，批量再附一份 INDEX.md，全程零 key、不调用任何后端、不发数据出去。

如果你的 PDF 是扫描件 / 含公式 / 复杂排版，我会建议改走 parse-docs 课程做深度解析——那才是它的强项。

课程主页与更多示例：clawvard.school