book-converter

Book Converter Skill

将 EPUB 图书转换为格式专业的 Markdown 图书，并通过 AI 提升质量。

概述

此技能通过以下步骤将 EPUB 文件转换为高质量的 Markdown 文档：

1. 使用 pandoc 从 EPUB 提取原始 Markdown
2. 创建结构化的项目目录
3. 规划并执行 AI 驱动的格式修正
4. 按章节生成格式化内容
5. 生成包含目录的合并图书文件

快速开始

用户提供 EPUB 文件路径：

/Users/username/Downloads/Book.Name.2024.epub

执行转换工作流：

python3 scripts/convert_book.py "/path/to/book.epub"

这将启动完整的转换流程。

工作流

重要：所有格式处理工作都必须使用子 Agent，以避免污染主上下文。

阶段 1：设置与提取（主 Agent）

运行转换脚本：

python3 scripts/convert_book.py "/path/to/book.epub"

此脚本将：

1. 验证 EPUB 文件是否存在
2. 创建项目结构：
   • books/book-name/ - 主目录
   • books/book-name/raw/ - Pandoc 输出
   • books/book-name/chapters/ - 格式化后的章节
   • books/book-name/images/ - 提取的图片
3. 运行 pandoc 提取 Markdown
4. 将格式规范复制到项目目录

输出：books/book-name/raw/book-parsed.md 中的原始 Markdown

阶段 2：分析与规划（脚本 + 子 Agent）

步骤 1：运行结构分析脚本（主 Agent）：

python3 books/book-name/analyze_structure.py books/book-name

此脚本将：

• 提取所有标题及其行号
• 通过抽样检测格式问题
• 建议章节边界
• 创建 STRUCTURE_ANALYSIS.md 报告（约 5-10 KB，而不是 35k+ 行）

步骤 2：启动一个通用子 Agent 来创建映射文件：

Task(
  subagent_type="general",
  description="Create chapter map and formatting plan",
  prompt="""Create CHAPTER_MAP.md and FORMATTING_PLAN.md:

1. Read books/book-name/STRUCTURE_ANALYSIS.md (concise report with headers and issues)
2. Read books/book-name/references/chapter-map-template.md for format
3. Read books/book-name/references/formatting-plan-template.md for format
4. Create books/book-name/CHAPTER_MAP.md:
   - Use suggested chapter boundaries from analysis
   - Verify line ranges make sense
   - Create proper slugged filenames
5. Create books/book-name/FORMATTING_PLAN.md:
   - Document issues found in analysis
   - Add severity and priority
   - Note book-specific patterns
6. Update books/book-name/progress.md to mark Phase 2 complete

Return: Summary of chapters found and major issues identified."""
)

输出：CHAPTER_MAP.md、FORMATTING_PLAN.md 和更新后的 progress.md

阶段 3：章节格式处理（使用子 Agent）

为每个章节分别启动一个通用子 Agent：

# Example for Chapter 1
Task(
  subagent_type="general",
  description="Format Chapter 1",
  prompt="""Format Chapter 1 following the chapter formatting workflow.

**Critical Instructions:**
1. Read and follow ALL steps in books/book-name/references/chapter-workflow.md
2. Apply formatting rules from books/book-name/references/formatting-standards.md
3. Use books/book-name/CHAPTER_MAP.md to find line ranges for Chapter 1
4. Read books/book-name/FORMATTING_PLAN.md for known issues to watch for

**Workflow Summary (see chapter-workflow.md for complete details):**

Step 1: Read Standards and Chapter Map
- Read references/formatting-standards.md
- Read CHAPTER_MAP.md for your chapter's line ranges
- Read FORMATTING_PLAN.md for known issues

Step 2: Extract Chapter Content
- Extract Chapter 1 from raw/book-parsed.md using line ranges

Step 3: Identify Issues follow the standards
- Headers using bold instead of #
- Shattered code blocks
- Split paragraphs
- Missing code language identifiers
- Emphasis artifacts [word]
- Corrupted footnotes
- Missing image alt text
- Broken links

Step 4: Apply Formatting Fixes
- Follow the three-pass approach in chapter-workflow.md:
  * First pass: Structure (headers, code blocks)
  * Second pass: Content (paragraphs, emphasis)
  * Third pass: Details (footnotes, images, links)

Step 5: Create Output File
- Write to books/book-name/chapters/chapter-01-title.md
- Use structure from chapter-workflow.md

Step 6: Update Progress
- Update books/book-name/progress.md with completion status
- Document fixes applied

**Quality Checklist (from chapter-workflow.md):**
- [ ] All headers use proper # syntax
- [ ] All code blocks have language identifiers
- [ ] No shattered code blocks remain
- [ ] Text flows naturally without mid-sentence breaks
- [ ] All footnotes have [^N] format with definitions
- [ ] Images have descriptive alt text

Return: Confirmation with summary of fixes applied."""
)

重要：

• 为提高效率，按批次并行启动子 Agent（每次 3-5 个）
• 每个子 Agent 都必须阅读 chapter-workflow.md 和 formatting-standards.md
• 遵循系统化工作流，确保质量一致

输出：books/book-name/chapters/ 中的格式化章节

阶段 4：图书组装（主 Agent）

merge_book.py 脚本已复制到项目目录。只需运行：

python3 books/book-name/merge_book.py books/book-name

脚本将：

1. 根据 CHAPTER_MAP.md 确定章节顺序
2. 从 chapters/ 加载所有格式化后的章节
3. 提取标题以生成目录
4. 修正图片路径（相对于最终位置）
5. 按顺序合并所有章节
6. 生成完整目录
7. 输出到 books/book-name-book.md

输出：包含完整格式化图书的 books/book-name-book.md

注意：合并脚本可重复使用，无需为每本书单独创建！

重要：章节格式处理要求

阶段 3 中的每个子 Agent 都必须：

1. 首先阅读 chapter-workflow.md - 包含完整的分步流程
2. 阅读 formatting-standards.md - 包含所有格式规则（678 行）
3. 系统地遵循工作流 - 不要跳过步骤
4. 采用三遍处理法：
   • 第一遍：修正结构（标题、代码块）
   • 第二遍：修正内容（段落、强调）
   • 第三遍：修正细节（脚注、图片、链接）
5. 完成质量检查清单 - 完成前核实所有项目

这很重要，因为：

• 确保所有章节的质量一致
• 避免常见错误（遗漏问题、风格不一致）
• 这是经过 Clean Code Collection 验证的流程（35k+ 行）
• 每个章节只格式处理一次，因此必须彻底

工作流文档就是完整的操作说明，请遵循它们！

子 Agent 使用原则

切勿在主上下文中处理书籍内容。 始终使用子 Agent 来：

1. 保持主上下文整洁：书籍内容庞大，会污染上下文
2. 支持并行处理：同时排版多个章节
3. 隔离排版工作：每个章节都使用全新的上下文
4. 避免令牌限制：原始内容可能超出上下文窗口

子 Agent 选择：所有书籍处理任务始终使用 subagent_type="general"。

进度跟踪

创建并维护 books/book-name/progress.md：

# Book Name - Conversion Progress

## Phase 1: Setup ✓
- [x] EPUB extracted
- [x] Project structure created

## Phase 2: Planning ✓
- [x] Chapter map created (15 chapters identified)
- [x] Formatting plan documented

## Phase 3: Chapter Formatting (5/15 complete)
- [x] Front Matter
- [x] Chapter 1: Introduction
- [x] Chapter 2: Getting Started
- [x] Chapter 3: Advanced Topics
- [x] Chapter 4: Best Practices
- [ ] Chapter 5: Performance
- [ ] ...

## Phase 4: Assembly
- [ ] Merge script created
- [ ] Final book generated

每个子 Agent 完成后更新。

质量标准

所有排版后的输出都必须满足以下标准：

• 标题：使用正确的 # 语法，而非粗体文本
• 代码块：包含语言标识符，并合并被拆散的代码块
• 文本流：将拆开的句子合并为自然段落
• 强调：使用 *italic* 和 **bold**，而非 [brackets]
• 脚注：使用标准的 [^1] 格式并附带定义
• 图片：使用描述性替代文本，而非通用文件名
• 链接：使用简洁的锚点，避免 PDF 转换产生的瑕疵

完整标准参考：references/formatting-standards.md

使用示例

用户请求：

“将此 EPUB 转换为 Markdown：/Users/john/Downloads/Effective.Java.3rd.Edition.epub”

技能执行：

1. 运行转换脚本以提取内容
2. 分析结构并创建章节映射
3. 使用 AI 子 Agent 排版各章节
4. 合并为包含目录的最终书籍
5. 向用户提供 books/effective-java-final.md

脚本

• convert_book.py：主转换脚本（阶段 1）——提取 EPUB 并设置项目
• analyze_structure.py：结构分析器（阶段 2）——提取标题并高效检测问题
• merge_book.py：可复用的合并脚本（阶段 4）——将所有章节合并为最终书籍

参考资料

• formatting-standards.md：完整的排版规则（排版时按需加载）
• chapter-workflow.md：详细的章节排版工作流（按需加载）
• progress-template.md：进度跟踪文件模板
• chapter-map-template.md：章节映射模板
• formatting-plan-template.md：排版问题文档模板

备注

• 注重高质量：通过 AI 手动排版，确保行文自然流畅
• 不使用自动化脚本：合并文本行需要类似人类的判断力
• 保留内容：切勿更改含义或删除内容
• 代码准确性：确保代码块在语法上完整