| name | epub-source-intake |
| description | 从非 EPUB 源材料建立 EPUB 制作入口，包括纯文本、Markdown、HTML、PDF、扫描件 OCR 结果和图片素材的抽取、结构化、校对与后续排版验证。用于用户还没有 EPUB，需要先从文本或 PDF 生成可排版 XHTML/source bundle，再进入 EPUB 排版优化流程时。 |
EPUB 源材料接入
当用户没有现成 EPUB，而是提供文本、Markdown、HTML、PDF 或扫描件时使用这个 skill。目标不是直接做最终精排，而是生成可校对、可验证、可继续排版的 EPUB source bundle。
输入判断
- 已有
.epub：不要使用本 skill，先用 epub-layout-auditor。
.txt / .md：走文本结构化，重点是章节、段落、注释和空行语义。.html / .xhtml：走 HTML 清理，重点是语义标签、资源路径和 XML 合法性。- born-digital PDF：优先抽取文本和图片，再人工抽样校对。
- 扫描 PDF / 图片：先 OCR，再把 OCR 结果作为不可信 source 处理。
- 多源目录：先建立 manifest plan，明确每个文件的角色，再生成 XHTML/Images/CSS。
固定目标
输出应当是可继续处理的源材料包，而不是最终交付 EPUB：
- 章节切分清楚，保留原始顺序。
- 正文、标题、注释、图注、表格、公式和页码残留有明确分类。
- 抽取日志记录工具、参数、抽样页和已知风险。
- XHTML 保持真实文本，不把可编辑正文转成图片。
- 图片素材保留原始文件和派生交付文件的对应关系。
- 后续排版交给
epub-typography-optimizer、epub-image-layout-optimizer、epub-popup-footnote-converter 等专项 skill。
工作流
- 运行 harness 初判输入：
scripts/epub_ai_harness.py <source-path>
- 建立 source map：
- 输入文件列表。
- 每个文件的角色：正文、封面、插图、注释、目录、附录、未知。
- 抽取工具和参数。
- 需要人工确认的页码、脚注、表格、公式和图片。
- 抽取文本：
- 文本/Markdown：保留段落和空行，不先做花哨样式。
- HTML：清理非语义 wrapper，保留真实标题层级。
- PDF：优先尝试
pdftotext / mutool 等外部工具；本项目不内置 PDF 抽取器。
- 扫描件：先 OCR，记录 OCR 工具、语言、置信度和抽样校对结果。
- 结构化：
- 标题转成
h1/h2 或章节 metadata。
- 正文段落转成
p。
- 注释先保留成可追踪结构，再交给 popup footnote skill。
- 表格、公式和图片不要强行扁平成普通段落。
- 抽样校对：
- 第一页/目录页。
- 每个章节边界。
- 至少一个脚注密集页。
- 至少一个表格或公式页。
- 至少一个图片页。
- 进入排版链路：
- 字体/正文：
epub-typography-optimizer
- 图片：
epub-image-layout-optimizer
- 注释：
epub-popup-footnote-converter
- 竖排/Ruby：
epub-vertical-ruby-optimizer
- OPF/nav：
epub-package-nav-auditor
- Kindle：
epub-kindle-compatibility-checker
PDF 处理边界
- 本仓不实现 PDF 解析、OCR、图片压缩或版面识别引擎。
- 可以调用用户环境已有工具，但必须记录工具名和版本。
- born-digital PDF 也可能有断行、页眉页脚、连字符、阅读顺序和多栏问题；不要默认抽取结果正确。
- 扫描 PDF 必须标记为 OCR 风险输入，不能直接当作可靠正文。
- PDF 中的页码、脚注编号、图题和表题要单独检查，不要只看首章。
图片压缩边界
图片压缩不属于本项目实现范围。本项目只做：
- 标记图片格式风险，例如 WebP、TIFF、CMYK JPEG、SVG-only Kindle 路径。
- 检查 OPF manifest、封面声明、figure 包装和图注。
- 建议外部压缩/转码后回到本项目验证。
外部压缩完成后，使用 epub-image-layout-optimizer 和 epub-kindle-compatibility-checker 复查。
禁止事项
- 不在没有抽样校对的情况下把 PDF/OCR 文本当成最终正文。
- 不自动改写作者文字来修复抽取错误。
- 不丢弃脚注、边注、图注、表格标题或公式。
- 不把 PDF 页面截图当作可重排正文主路径。
- 不把图片压缩结果直接纳入规则结论，除非有阅读器验证。
- 不在本 skill 中决定最终视觉样式；这里只负责接入、结构化和校验入口。
验证
接入完成后至少检查：
scripts/epub_ai_harness.py <source-or-output-path>
scripts/validate_skills_basic.py
git diff --check
如果已经形成 EPUB source tree 或 .epub，再使用 epub-package-nav-auditor 和对应专项 skill 做排版验证。
