markdown-to-epub（Markdown TO epub 控制）

markdown-to-epub Skill

把 Markdown 手稿（含本地图片）稳定构建为 EPUB：规范化图片引用、拷贝资产到可重复的构建目录、调用 Calibre ebook-convert 转换，并输出可核查报告。

When to Use This Skill

触发条件（满足其一即可）：

• 需要把一份（或多份）Markdown 手稿打包交付为 EPUB。
• 图片引用混乱（URL 编码、路径飘忽、扩展名不可信如 .bin/.idunno），需要自动归一化。
• 需要在转换后做最基本的 EPUB 包结构检查（OPF/NCX/NAV、图片数量等）。

Not For / Boundaries

• 不负责生成/改写正文内容（不会修改源手稿，只在构建目录里产出规范化版本）。
• 不下载远程图片（http(s)/data: 引用会保持原样）。
• 不替代真正的排版/校对流程（这里只做可交付构建与结构验证）。

Quick Start

从仓库根目录执行（推荐 python3）：

python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --title "Book Title" \
  --authors "Author Name" \
  --language "zh-CN"

脚本会创建构建工作区（默认 build_epub/），包含：

• book.normalized.md
• assets/：拷贝后的图片（会按真实文件签名推断扩展名）
• conversion.log
• report.json

依赖

• 需要安装 Calibre，并确保 ebook-convert 在 PATH 中（或用 --ebook-convert-bin 指定路径）。

Missing Asset Recovery

如果 Markdown 里引用了图片但文件找不到，可以提供一个 JSON 映射表（按「basename」匹配）：

{
  "missing-file.idunno": "replacement-file.idunno"
}

然后重跑（示例）：

python3 assets/skills/markdown-to-epub/scripts/build_epub.py \
  --input-md "./book.md" \
  --output-epub "./book.epub" \
  --fallback-map "./fallback-map.json"

Operational Rules

• 优先使用 ebook-convert；缺失时明确报错并快速失败。
• 源手稿只读；所有输出写入 build_dir/。
• TOC 以标题层级（h1/h2/h3）为准。
• 缺失资产必须显式报告；严格模式下不允许静默跳过。
• 命令保持非交互式。

Script Interface

scripts/build_epub.py 参数：

• --input-md（必选）：源 Markdown 路径
• --output-epub（可选）：输出 EPUB 路径，默认 <input-stem>.epub
• --source-root（可选）：解析图片引用的根目录，默认使用 Markdown 所在目录
• --build-dir（可选）：构建工作区目录，默认 <cwd>/build_epub
• --fallback-map（可选）：JSON 映射（缺失图片 basename → 替换 basename）
• --title / --authors / --language：传给 ebook-convert 的元数据
• --input-encoding：输入 Markdown 编码，默认 utf-8
• --strict-missing：严格模式（有任何本地图片无法解析则失败，默认开启）
• --no-strict-missing：关闭严格模式（保留未解析链接，继续转换）
• --ebook-convert-bin：ebook-convert 可执行文件名/路径，默认 ebook-convert

Validation Checklist

• 确认 EPUB 文件生成且大小不是「几 KB 的空壳」。
• 确认 EPUB（zip）内包含 OPF 与 NCX/NAV。
• 确认 EPUB 内图片数量不低于对手稿的预期。
• 严格模式下确认 report.json 的 missing_images 为空。