epub

EPUB — 电子书创建、提取与增强

专业级 EPUB 处理：读取、编写、编辑、验证 EPUB 2 和 EPUB 3 文件，并从中提取知识。包含五个 Python 命令行脚本和五份详细参考资料，涵盖完整的 EPUB 领域。

何时不应使用

• 非 EPUB 文档 — Word、PDF、纯 Markdown 或网页转换任务都不适用于此处的任何脚本；请将它们交给文档处理技能，而不要把 EPUB 工具硬套到非 EPUB 文件上。
• 受 DRM 保护的电子书 — 这些脚本可以读取和写入标准 OCF/EPUB 容器，但不会移除或绕过数字版权管理。
• Mobi/AZW/Kindle 原生格式 — 请先使用专用转换器；此技能既不读取也不写入 Amazon 专有容器。

EPUB 格式基础

EPUB 文件是一个具有特定内部布局的 ZIP 归档文件（开放容器格式，OCF）。W3C EPUB 3.3 标准采用“三平面”模型：

平面	包含内容	关键规则
清单	所有资源（XHTML、图片、CSS、字体）	每个文件都必须列在 OPF <manifest> 中
阅读顺序	线性阅读顺序	默认仅支持 XHTML/SVG；其他类型需要回退项
内容	嵌入文档中的资源	保证支持核心媒体类型；其他类型需要回退项

包文档（content.opf）包含元数据（都柏林核心）、清单（所有资源）和阅读顺序。EPUB3 使用 XHTML nav 文档进行导航；EPUB2 使用 .ncx XML。两者可以共存以确保兼容性。

关键规则： mimetype 必须是 ZIP 中的第一个条目，且不得压缩。所有内容文档都必须是格式良好的 XML（XHTML，而非 HTML5）。清单必须列出渲染时使用的每个文件。完整结构请参阅 references/epub-format-internals.md。

决策表 — 使用哪个脚本

任务	脚本	说明
查看结构、元数据、清单、阅读顺序、目录	epub-info	JSON 输出；使用 --summary 获取精简结果
提取按阅读顺序排列的纯文本	epub-text	按章节输出或合并为单个文件
从头创建最简有效 EPUB	epub-scaffold	无需依赖项
提取事实、引言、定义、论点	epub-extract-knowledge	启发式或 LLM 模式（自动检测环境变量）
根据 EPUB 规范进行验证	epub-validate	EPUBCheck 或 Python 回退方案
编辑 EPUB（元数据、章节、阅读顺序、CSS）	epub-edit	v2 旗舰工具 — 8 个子命令，非侵入式
提取图片	epub-images	列出图片或提取到目录
批量处理多个 EPUB	epub-batch	使用 glob 封装现有脚本
将 EPUB2 转换为 EPUB3	epub-convert	添加 NAV、更新 NS、保留 NCX
诊断并修复结构问题	epub-repair	自动修复常见验证失败问题

脚本

所有脚本都位于相对于此技能目录的 scripts/ 中。每个脚本都遵循 cli-builder 约定：使用 --json 输出机器可读结果，使用 --dry-run 预览，采用非交互方式运行，并将错误输出到 stderr。运行 --help 可查看完整的标志详情。

epub-info — 结构与元数据转储

scripts/epub-info book.epub --json
scripts/epub-info book.epub --summary      # compact manifest
scripts/epub-info book.epub --dry-run      # preview

输出：EPUB 版本、元数据（标题、作者、语言、标识符）、清单（包含 id/href/media-type 的所有项目）、阅读顺序、目录（嵌套结构）。--summary 会将清单精简为 id+href+media-type。

epub-text — 纯文本提取

scripts/epub-text book.epub                           # plain text to stdout
scripts/epub-text book.epub --json                    # JSON with chapter array
scripts/epub-text book.epub --chapters                # one .txt per chapter
scripts/epub-text book.epub --output book.txt         # single file
scripts/epub-text book.epub --format markdown         # markdown output

从按阅读顺序排列的内容文档中提取文本。移除 HTML 标签，并保留段落结构。需要 beautifulsoup4。遵循阅读顺序的线性排列——只处理阅读顺序中的文档。

epub-scaffold — 从头创建有效的 EPUB

scripts/epub-scaffold --title "My Book" --author "Jane Doe"
scripts/epub-scaffold --title "Novel" --author "Me" --chapters 12 --output novel.epub
scripts/epub-scaffold --title "Guide" --author "Me" --cover cover.jpg
scripts/epub-scaffold --title "Guide" --author "Me" --cover cover.jpg --toc-hidden --dry-run

创建一个有效的 EPUB3，所有内容都位于 OEBPS/ 中，这是兼容 Apple Books 的必要条件。无外部依赖，仅使用 Python 标准库。

封面处理： 提供 --cover 时，脚手架会自动：

• 将图像复制到 OEBPS/Images/cover.{ext}
• 生成 OEBPS/Text/cover.xhtml，这是一个带有全视口 CSS 的 XHTML 包装页
• 将封面页设为 spine 中的第一个项目
• 为原始图像设置 properties="cover-image"，以用于书库缩略图

这遵循 Apple Books 的要求：封面必须是 spine 中的 XHTML 页面，而不能是原始图像引用（原始图像会显示为空白页）。

导航可见性： --toc-hidden 会为 nav spine 项设置 linear="no"，使其不出现在阅读流中（仍可通过应用内置的目录浏览器访问）。默认值为 --toc-visible（nav 会作为页面显示）。

CSS： 随附 OEBPS/Styles/default.css，采用兼容 Apple Books 的排版样式：不使用已弃用的 page-break-before，在 body 上设置 margin: 0（通过内边距留白），采用正确的标题层级，并使用响应式样式。

封面图指南： --cover 标志接受现有图像文件。如果用户没有封面图，可提议使用 Agent 的 image_gen 功能生成一张。完整的封面 XHTML 和 CSS 规范请参阅 references/apple-books-compatibility.md。

epub-cover — 为现有 EPUB 添加封面

scripts/epub-cover wrap book.epub --image cover.png --output with-cover.epub
scripts/epub-cover wrap book.epub --image cover.png --in-place

为清单中已有封面图像的 EPUB 添加封面 XHTML 包装页。适用于图像存在但未能在 Apple Books 中显示的情况。需要 epublib。

epub-extract-knowledge — 知识提取工作流

# LLM mode — set env vars first (see references below), then run without flags:
scripts/epub-extract-knowledge book.epub --format json
scripts/epub-extract-knowledge book.epub --format atoms
scripts/epub-extract-knowledge book.epub --format memory

# Force heuristic mode (ignore env vars):
scripts/epub-extract-knowledge book.epub --no-llm --format json

# Custom prompt override:
scripts/epub-extract-knowledge book.epub --prompt "Extract all definitions" --format json

从 EPUB 内容中提取知识：事实、定义、要点和论据。自动选择两种模式之一：

• LLM 模式（自动检测）： 设置 EPUB_LLM_URL 和 EPUB_LLM_KEY 环境变量后，会将章节文本和提取提示词发送给配置好的 LLM。生成高质量的结构化见解。如果 LLM 调用失败，则回退到启发式模式。
• 启发式模式（回退）： 未设置环境变量或传入 --no-llm 时，使用模式匹配（标题、强调标记、定义性语言、段落密度）来识别承载知识的段落。无需 LLM。

输出格式：json（原始结构化 JSON）、atoms（Obsidian 知识库 atom 模板）、memory（适用于 Agent 持久化的键值条目）。有关环境变量配置约定、知识类型检测表、LLM 提示词设计以及各平台的输出目标选项，请加载 references/llm-config-and-extraction.md。

epub-edit — 精细编辑 EPUB（v2）

scripts/epub-edit info book.epub --json
scripts/epub-edit metadata book.epub --title "New Title" --output out.epub
scripts/epub-edit add-chapter book.epub --content new.xhtml --after chapter3 --output out.epub
scripts/epub-edit remove-chapter book.epub --id chapter5 --output out.epub
scripts/epub-edit reorder-spine book.epub --order chapter3,chapter1,chapter2 --dry-run
scripts/epub-edit rename-resource book.epub --from Images/old.jpg --to Images/new.jpg
scripts/epub-edit inject-css book.epub --css dark.css --output out.epub
scripts/epub-edit update-manifest book.epub --output out.epub

通过 epublib 进行非侵入式 EPUB 编辑。八个子命令覆盖完整的编辑范围。绝不覆盖原文件，默认输出到 --output out.epub；使用 --in-place 提交修改。所有子命令均支持 --json、--dry-run。

epub-images — 图像提取

scripts/epub-images book.epub --list --json           # list all images
scripts/epub-images book.epub --extract images/       # extract all to directory
scripts/epub-images book.epub --type cover --extract .  # cover image only

epub-batch — 多文件处理

scripts/epub-batch extract-text "books/*.epub" --output texts/
scripts/epub-batch validate "books/*.epub" --json
scripts/epub-batch metadata "books/*.epub" --set-author "Author" --output-dir fixed/
scripts/epub-batch info "books/*.epub" --json

epub-convert — EPUB2 → EPUB3

scripts/epub-convert old.epub --output new-v3.epub
scripts/epub-convert old.epub --validate --json

epub-repair — 诊断与修复

scripts/epub-repair broken.epub --diagnose --json     # list fixable issues
scripts/epub-repair broken.epub --output fixed.epub   # auto-fix

epub-validate — 结构验证

scripts/epub-validate book.epub --json
scripts/epub-validate book.epub --dry-run

优先尝试使用 EPUBCheck（Java JAR）进行权威验证。失败时回退到纯 Python 结构检查：mimetype 的位置／压缩／内容、container.xml 的可解析性、OPF 架构、清单完整性、spine 引用完整性、必需元数据以及 NAV 文档是否存在。

能力发现与流水线构建

在执行多步骤 EPUB 流水线之前，先发现你的 Agent 平台上有哪些工具可用——此技能可移植，具体的流水线形态取决于你的运行环境所具备的能力。协议如下：枚举你的工具（文件写入、网页访问、子 Agent、cron、持久化记忆、向量数据库、保险库、大模型），将它们映射到流水线阶段（摄取 → 解析 → 提取 → 格式化 → 输出），用可用组件构建流水线，并在执行前向用户提出计划。

完整协议（包括阶段映射表，以及适用于不同平台的流水线示例：配备保险库和 RAG 的完整 Agent、仅终端的最简运行环境，以及批量多文件处理），请参阅 references/agent-capability-discovery.md。

常见工作流

根据 Markdown 文件创建 EPUB

# 1. Scaffold the EPUB
scripts/epub-scaffold --title "My Book" --author "Me" --chapters 3 --output book.epub

# 2. Use epublib (Python) to inject real content into each chapter
# See references/tutorials-and-guides.md for the editing pattern

从 EPUB 中提取所有图片

scripts/epub-images book.epub --extract images/

编辑 EPUB

# Update metadata
scripts/epub-edit metadata book.epub --title "New Title" --output revised.epub

# Add a chapter
scripts/epub-edit add-chapter book.epub --content new.xhtml --output expanded.epub

# Inject dark theme
scripts/epub-edit inject-css book.epub --css dark.css --output dark.epub

修复损坏的 EPUB

scripts/epub-repair broken.epub --diagnose --json     # see what's broken
scripts/epub-repair broken.epub --output fixed.epub   # auto-fix

从书库中批量提取文本

scripts/epub-batch extract-text "books/*.epub" --output texts/

将 EPUB2 转换为 EPUB3

scripts/epub-convert old.epub --output old-v3.epub --validate

Apple Books 兼容性

macOS/iOS 上的 Apple Books 执行的要求超出 EPUB 规范；这些规则已在 macOS 26 上通过构建和测试验证。要点：所有内容都必须放在 OEBPS/ 内；封面必须是 spine 中的 XHTML 页面（原始图片 spine 项会显示为空白）；正文应通过 padding 避免使用 margin: 0；不得使用已弃用的 page-break-before；xmlns:epub 仅用于 nav 文档；原始封面图片须保留 properties="cover-image"；linear="no" 可让页面（例如 nav）不出现在阅读流程中，但仍显示在应用的目录浏览器中。spine 排序模式：无封面（nav → chapters）、仅封面（cover-page → nav(linear="no") → chapters）、完整模式（cover-page → nav → chapters；脚手架默认值）。

不要依赖记忆来遵循这些规则——每当构建或修复面向 Apple Books 的 EPUB 时，都应加载 references/apple-books-compatibility.md，查看逐条规则表、CSS 示例、封面 XHTML 模板和验证注意事项。

注意事项

• mimetype 压缩： Python 的 zipfile 默认会进行压缩。mimetype 条目始终使用 ZIP_STORED。压缩 mimetype 会导致阅读系统无法正常工作，且不会显示任何提示。
• XHTML ≠ HTML5： 内容文档必须是格式良好的 XML。必须使用自闭合标签（<br/>，而非 <br>）。使用 xmlns:epub="http://www.idpf.org/2007/ops"。
• 清单必须完整： EPUB 中的每个文件都必须列出。缺少清单条目会导致验证失败。图片、CSS、字体等均不例外。
• AGPL 边界： EbookLib 使用 AGPL 许可；脚本会在运行时调用它，但不会将其打包。用户需自行通过 pip 安装。此技能及其脚本采用 MIT 许可。
• EPUBCheck 需要 Java： 权威验证器需要 Java。备用 Python 检查可以发现结构问题，但无法检测 XHTML 架构违规或 CSS 有效性问题。
• Spine 引用清单 ID： spine 中的 idref 必须与清单中的 id 匹配。引用错误会导致 EPUB 验证失败。
• 导航文档： EPUB3 要求 NAV 带有 properties="nav"。缺少该项时，阅读系统可能不会显示目录。
• 必须指定语言： 必须同时设置 <dc:language> 和内容文档上的 xml:lang/lang 属性。缺少语言会导致 EPUB 无效。

注意事项

• 不要跳过能力发现。 假设某个不存在的工具可用，会导致流水线中断。构建前务必检查。
• 不要假设大模型可用。 提取时务必提供 --no-llm 回退选项。对于结构良好的书籍，启发式模式的效果往往出乎意料地好。
• 不要在没有备份的情况下直接修改 EPUB。 编辑 EPUB 就像做外科手术——务必保留原件。
• 不要在同一会话中使用 EbookLib 和 epublib 处理同一个文件。 它们的内存模型不同，可能会产生冲突。每项任务选择一个库即可。
• 不要假设 OPF 位于 OEBPS/content.opf。 务必读取 container.xml 以查找实际路径。根目录因书而异。

参考资料

• references/epub-format-internals.md — 完整的结构参考（OCF、OPF、 XHTML、NCX/NAV、spine、三个平面、核心媒体类型、EPUB2 与 EPUB3）
• references/python-libraries.md — EbookLib 与 epublib 的比较、代码 示例、使用场景及许可证说明
• references/spec-and-validation.md — W3C EPUB 3.3 规范入口、 EPUBCheck 用法、Ace 无障碍验证及关键约束摘要
• references/tutorials-and-guides.md — 从入门到进阶的指南、常见 工作流、手动编辑 OPF、批量操作及注意事项
• references/agent-capability-discovery.md — 探测 Agent 工具的协议、 构建提取流水线，以及跨平台的完整示例
• references/fixed-layout-epub.md — 固定版式检测与属性 （rendition:layout、orientation、spread、viewport meta）
• references/accessibility.md — WCAG 一致性、替代文本、标题层级、 ARIA 角色、Ace 集成及无障碍元数据
• references/media-overlays.md — SMIL 同步、音频与文本配对、 可跳过性／可跳出性，以及从 manifest 中检测
• references/apple-books-compatibility.md — 规范之外的 Apple Books 规则： OEBPS 布局、封面 XHTML 包装、CSS 约定、spine 模式及特殊行为
• references/llm-config-and-extraction.md — EPUB_LLM_* 环境变量约定、 大模型与启发式提取模式、知识类型检测、提示词设计、 按平台划分的接收端选项