redasadki/epub2md

epub2md 是做什么的？

将 EPUB 转换为 Markdown，支持目录（TOC）和 spine 感知的章节分组。

何时使用此技能

在以下情况下使用此技能：

• 用户提供一个 EPUB 文件（.epub）并请求将其转换为 Markdown。
• 用户请求将电子书的文本输出为一个 Markdown 文件，或每个章节一个 Markdown 文件。
• 用户希望按章节分割 EPUB 以进行后续处理（如索引、嵌入、翻译、审阅）。
• 用户请求检查 EPUB 的结构（spine、TOC、章节）。

请勿将此技能用于 PDF、Word 文档或网页。请改用特定格式的工具。

输入

• 一个 EPUB 文件路径。
• 可选的输出目录（默认：./output）。
• 可选模式：single（单一文件）、chapters（按章节）或 both（两者全部），默认：both。
• 可选分组方式：toc（按目录）、spine（按 spine）或 auto（自动），默认：auto。

输出

始终在输出目录中生成以下内容：

• book-extracted/ —— 原始解压后的 EPUB 内容。
• book-assets/ —— 书籍引用的图片和媒体文件。
• chapters/NN-slug.md —— 每个章节一个 Markdown 文件。
• chapters.json —— 章节清单，包含标题、源文件、锚点、输出路径。
• combined.html —— 所有章节合并后的 HTML 文件，供检查使用。
• book.md —— 整本书作为一个 Markdown 文件。
• metadata.json —— 元数据，包括标题、作者、语言、标识符、出版商、EPUB 版本、章节数量。

如何运行

该技能附带一个运行脚本 scripts/run.sh，它会自动找到 epub2md 命令行工具并转发所有参数。无论是否安装了 epub2md，它都能工作：

1. 如果 epub2md 已在系统 PATH 中，则直接使用。
2. 否则，如果 epub2md Python 包可导入，则使用 python3 -m epub2md。
3. 否则，该运行脚本会回退到其相邻的源码目录（scripts/epub2md/），因此即使从全新克隆的仓库中运行也无需任何安装步骤。

bash scripts/run.sh path/to/book.epub -o output/ --overwrite

对于重复使用，推荐一次性安装该软件包：

pip install .
epub2md path/to/book.epub -o output/ --overwrite

为了获得高保真转换，请安装 Pandoc。当 Pandoc 在系统 PATH 中可用时，epub2md 会优先使用它；否则会回退到纯 Python 转换器。

常用方案

转换为单一 Markdown 文件

bash scripts/run.sh book.epub -o out/ --mode single --overwrite
# 读取：out/book.md

使用目录（TOC）按章节分割

bash scripts/run.sh book.epub -o out/ --mode chapters --group-by toc --overwrite
# 读取：out/chapters/NN-slug.md 和 out/chapters.json

强制使用 spine 分组

当目录（TOC）缺失、格式错误或具有误导性时使用此方式：

bash scripts/run.sh book.epub -o out/ --group-by spine --overwrite

作为 Python 库使用

from epub2md import convert

result = convert("book.epub", output_dir="out", mode="both", overwrite=True)
print(result.book_md)
print(len(result.chapters))

分组逻辑

• 如果存在目录（TOC），默认的 auto 模式会使用它。每个顶级 TOC 条目成为一个章节。该章节包含从该条目的起始文件到下一个条目的起始文件之间的所有 spine 文档。这样可以重新组合那些分散在多个 XHTML 文件中的章节。
• 如果目录（TOC）缺失，工具会回退到使用 spine。每个 spine 文档成为一个章节。
• 在第一个 TOC 条目之前出现在 spine 中的前页内容会被合并为一个“前页”章节。

错误处理

• 缺少 container.xml 或 OPF 文件：工具会退出并显示清晰的错误信息；表明 EPUB 无效。
• 格式错误的 XHTML 片段：使用宽松模式解析。当某个片段的转换失败时，原始的 HTML 会被嵌入到一个围栏代码块中，从而确保不丢失任何内容。
• 缺失引用的图片：发出警告，并在 Markdown 输出中保留原始的 src 属性。
• 未安装 Pandoc：工具会静默地回退到自动模式下的 markdownify 库。

参考

• references/spec.md —— 完整规范、分组算法和输出布局。
• references/troubleshooting.md —— 针对常见 EPUB 转换问题的实用修复方法。