InkoraInkora

更新与计划

查看我们的最新功能改进和未来规划

下个版本计划

我们正在努力开发更多强大功能，让 PDF 转换体验更加完美

预计发布时间：12 月 28 日 到 1 月 3 日
📱

提供桌面端应用和 iOS 应用

推出桌面端和 iOS 专用应用，方便后续给用户提供更多的本地功能和提高移动端使用的便利性

📚

支持更多电子书格式

新增多种电子书格式支持，包括 AZW3、MOBI 等，满足更多阅读器和设备需求

∑

继续优化公式的显示

进一步改进数学公式和化学方程式的渲染效果，提升复杂公式的识别准确度

历史更新

欧洲语言扩展（fr-FR / de-DE / it-IT / es-ES）

发布日期: 2026-03-04

新增功能

  • 在 i18n 资源中新增 4 种语言：
    • fr-FR
    • de-DE
    • it-IT
    • es-ES
  • 语言列表改为从 src/i18n/common/*.json 数据驱动加载。
  • 增加基础语言到地区语言的映射能力：
    • fr / fr-CA -> fr-FR
    • de / de-AT -> de-DE
    • it -> it-IT
    • es / es-MX -> es-ES

改进

  • 新增术语表，统一关键产品词汇：
    • docs/i18n-glossary.md
  • 新增语言验收检查模板：
    • docs/i18n-acceptance-checklist.md

说明 / 已知限制

  • 英语（en）仍是统一兜底语言。
  • 第三方组件 locale 包目前仅覆盖 zh-CN 和 en；缺失对应 locale 包时会退回英文显示。

此版本添加了对 GitHub 风格 Markdown(GFM)表格渲染的支持,增强了中断场景的错误处理,并包含重要的错误修复和依赖项更新。

更新内容

功能

  • GFM 表格支持:添加了 HTML 表格到 GitHub 风格 Markdown 格式的智能转换 https://github.com/oomol-lab/pdf-craft/pull/345

    • 简单表格自动转换为简洁的 GFM 管道表格语法
    • 复杂表格(带有 colspan、rowspan 或多个 tbody 部分)优雅地回退到 HTML 格式以保留结构
    • 防止 GFM 格式中不支持的表格功能导致的数据丢失
    • 为各种表格场景添加了全面的测试覆盖
    • 新依赖项:markdownify 库用于表格转换

  • 增强 InterruptedError API:为 InterruptedError 添加公共属性以便更好地进行错误内省 https://github.com/oomol-lab/pdf-craft/pull/346

    • 新的 kind 属性公开中断类型(中止或超出令牌限制)
    • 新的 metering 属性提供对 OCR 令牌使用数据的直接访问
    • OCRTokensMetering 现在从公共 API 导出以方便使用
    • 使用户能够以编程方式处理不同的中断场景并跟踪资源消耗

错误修复

  • 修复错误传播:修正了页面提取期间关键错误类型的处理 https://github.com/oomol-lab/pdf-craft/pull/343
    • AbortError 和 TokenLimitError 现在正确传播,而不是包装在 OCRError 中
    • 确保中断信号被调用代码正确接收和处理
    • 防止掩盖用户发起的中止操作和令牌限制违规

依赖项

迁移说明

InterruptedError 变更

如果您正在捕获 InterruptedError 异常,现在可以访问有关中断的详细信息:

from pdf_craft import transform_markdown, InterruptedError, InterruptedKind

try:
    transform_markdown(
        pdf_path="input.pdf",
        markdown_path="output.md",
    )
except InterruptedError as error:
    # v1.0.11 新增:访问中断详细信息
    if error.kind == InterruptedKind.ABORT:
        print("用户中止了操作")
    elif error.kind == InterruptedKind.TOKEN_LIMIT_EXCEEDED:
        print(f"超出令牌限制:使用了 {error.metering.input_tokens} 个输入令牌")

    # 访问令牌使用统计信息
    print(f"总令牌数:{error.metering.input_tokens + error.metering.output_tokens}")

表格渲染

PDF 文档中的表格现在会在可能的情况下转换为 GFM 格式,使其在 markdown 查看器中更具可读性。复杂表格将自动回退到 HTML 以保留其结构。

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.10...v1.0.11

此版本通过用布尔标志替换基于枚举的模式来简化目录(TOC)提取 API,同时添加 LLM 驱动的章节标题分析功能以改进 TOC 层级检测。

更新内容

破坏性变更

  • 简化 TOC API:用更简单的 toc_assumed 布尔参数替换 TocExtractionMode 枚举 https://github.com/oomol-lab/pdf-craft/pull/341
    • 从 transform_markdown() 和 transform_epub() 函数中删除了 toc_mode 参数
    • 从公共 API 导出中删除了 TocExtractionMode
    • 引入 toc_assumed 布尔标志来控制 TOC 检测行为

功能

  • LLM 驱动的章节标题分析:添加了对基于 LLM 的章节标题分析的支持,以提高 TOC 提取准确性 https://github.com/oomol-lab/pdf-craft/pull/341
    • 在配置 toc_llm 时自动分析章节标题层级
    • 为复杂书籍结构提供更准确的章节层级检测
    • 当 LLM 不可用或遇到错误时,智能回退到标准分析

改进

  • 增强错误处理:为基于 LLM 的分析添加了具有自动恢复机制的健壮错误处理 https://github.com/oomol-lab/pdf-craft/pull/341
    • 更好的 LLM 分析失败诊断
    • LLM 分析失败时优雅降级,确保转换成功继续

迁移指南

如果您在以前的版本中使用 toc_mode,请按以下方式更新代码:

旧 API(v1.0.9 及更早版本)

from pdf_craft import transform_markdown, TocExtractionMode

# Markdown 转换
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    toc_mode=TocExtractionMode.NO_TOC_PAGE,  # 旧参数
)

# EPUB 转换
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.AUTO_DETECT,  # 旧参数
)

新 API(v1.0.10)

from pdf_craft import transform_markdown

# Markdown 转换(默认假设没有 TOC 页面)
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    toc_assumed=False,  # 新的布尔参数(默认:False)
)

# EPUB 转换(假设存在 TOC 页面)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # 新的布尔参数
)

迁移映射

旧的 toc_mode 值新的 toc_assumed 值
TocExtractionMode.NO_TOC_PAGEFalse
TocExtractionMode.AUTO_DETECTTrue
TocExtractionMode.LLM_ENHANCEDTrue(配置 toc_llm)

LLM 增强的 TOC 提取

使用 LLM 驱动的章节标题分析:

from pdf_craft import transform_epub, BookMeta, LLM

# 为 TOC 增强配置 LLM
toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="cl100k_base",
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # 启用 TOC 检测
    toc_llm=toc_llm,   # 启用 LLM 驱动的分析
    book_meta=BookMeta(
        title="书名",
        authors=["作者"],
    ),
)

注意事项

  • toc_assumed 参数对于 Markdown 转换默认为 False,对于 EPUB 转换默认为 True(保持向后兼容的行为)
  • LLM 驱动的章节标题分析是可选的,如果未配置或发生错误,会自动回退到标准分析
  • 新 API 更简单直观,减少了在多个枚举值之间选择的认知负担

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.9...v1.0.10

此版本引入了使用 LLM 驱动分析的增强目录(TOC)提取功能,实现更准确的章节结构检测和层级识别。

更新内容

功能

重构

背景

以前,pdf-craft 使用统计分析来检测 TOC 页面并提取章节结构。虽然对基本情况有效,但这种方法在准确确定章节层级和处理复杂 TOC 布局方面存在局限性。此版本引入了 LLM 驱动的分析,以更好地理解 TOC 结构并提取层级信息。

工作原理

新的 TOC 提取流程:

  1. 识别 TOC 页面:使用统计分析检测哪些页面包含目录
  2. 收集所有 TOC 页面:收集所有识别的 TOC 页面进行综合分析
  3. LLM 分析:将所有 TOC 页面传递给 LLM 以提取章节标题及其层级
  4. 结构生成:使用提取的层级信息构建准确的 EPUB 导航结构

这种方法将统计检测的效率与 LLM 的语义理解能力相结合,从而在最终输出中实现更准确的章节组织。

使用方法

在使用适当的 toc_mode 时,TOC 提取改进会自动应用:

from pdf_craft import transform_epub, BookMeta, TocExtractionMode

# 使用 AUTO_DETECT 进行统计分析(EPUB 的默认值)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.AUTO_DETECT,
    book_meta=BookMeta(
        title="书名",
        authors=["作者"],
    ),
)

# 使用 LLM_ENHANCED 进行 LLM 驱动的提取(需要 toc_llm 配置)
from pdf_craft import LLM

toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="cl100k_base",
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.LLM_ENHANCED,
    toc_llm=toc_llm,
    book_meta=BookMeta(
        title="书名",
        authors=["作者"],
    ),
)

注意事项

  • 重要:使用 TocExtractionMode.LLM_ENHANCED 时,必须配置 toc_llm 参数。如果未提供 toc_llm,转换将失败。
  • 此功能对具有复杂章节层级的书籍最有益
  • 统计 TOC 页面检测仍作为第一步,LLM 分析增强提取质量

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.8...v1.0.9

此版本带来了增强的错误处理灵活性、改进的 OCR 文本质量以及重要的安全修复。

更新内容

功能

安全

其他

使用示例

使用函数的自定义错误处理

from pdf_craft import transform_markdown, OCRError

def should_ignore_ocr_error(error: OCRError) -> bool:
    # 仅忽略特定类型的 OCR 错误
    return error.kind == "recognition_failed"

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=should_ignore_ocr_error,  # 传递自定义函数
)

传统布尔错误处理(仍然支持)

from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=True,  # 简单布尔标志
)

API 变更

以下参数已增强,可接受布尔值和可调用函数:

  • ignore_pdf_errors: bool | Callable[[PDFError], bool]
  • ignore_ocr_errors: bool | Callable[[OCRError], bool]

此更改完全向后兼容 - 使用布尔值的现有代码无需修改即可继续工作。

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.7...v1.0.8

此版本增加了在 Markdown 和 EPUB 转换中包含封面图片的支持,增强了输出格式选项。

更新内容

功能

  • 封面图片支持:在 transform_markdown 和 transform_epub 函数中添加了 includes_cover 参数,允许您在输出中包含 PDF 的封面页作为图片 https://github.com/oomol-lab/pdf-craft/pull/319
    • 对于 Markdown 转换:封面图片保存到 images 文件夹,可以在文档中引用
    • 对于 EPUB 转换:封面图片正确嵌入到 EPUB 文件结构中
    • Markdown 默认值为 False(保持向后兼容性),EPUB 默认值为 True

使用示例

带封面的 Markdown

from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
    includes_cover=True,  # 包含封面图片
)

带封面的 EPUB

from pdf_craft import transform_epub, BookMeta

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    includes_cover=True,  # 包含封面图片(默认)
    book_meta=BookMeta(
        title="书名",
        authors=["作者"],
    ),
)

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.6...v1.0.7

发布 v1.0.6

此版本在 PDF 渲染控制、文本质量和错误处理能力方面带来了重大改进。

更新内容

新功能

文档

依赖项

  • 更新 epub-generator 至 0.1.6

使用示例

from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    dpi=300,  # 控制渲染分辨率
    max_page_image_file_size=5242880,  # 每页 5MB 限制
    ignore_ocr_errors=True,  # OCR 失败时继续处理
)

完整变更日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.5...v1.0.6

发布 v1.0.5

更新内容

Bug 修复

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.4...v1.0.5

发布 v1.0.4

新功能

🎯 目录检测与智能移除

pdf-craft 现在可以自动检测并移除最终输出中的目录页面,防止生成的 EPUB 文件中出现重复的目录内容。系统使用统计分析,通过将章节标题与页面内容进行匹配来识别目录页面,然后智能地排除这些页面,同时保留导航结构。

相关 Issue:https://github.com/oomol-lab/pdf-craft/issues/268

主要特性:

  • 使用 Aho-Corasick 子串匹配算法自动检测目录页面
  • 层级目录分析,改进章节组织结构
  • 基于 XML 的目录存储,性能和灵活性更佳
  • 新增 toc_assumed 参数来控制目录检测行为(EPUB 默认为 True,Markdown 默认为 False)

实现相关的 PR:

📝 Markdown 原始 HTML 标签支持

完全支持 Markdown 输出中符合 CommonMark 规范的原始 HTML 标签。DeepSeek OCR 在处理扫描书籍时经常生成 HTML 标签(如用于上标的 <sup>),这些标签现在可以在 Markdown 和 EPUB 格式中正确保留和渲染。

相关 Issue:https://github.com/oomol-lab/pdf-craft/issues/283

支持的标签包括:

  • 行内标签:<sup>、<sub>、<mark>、<u>、<kbd>
  • 块级标签:<div>、<center>、<details>、<summary>
  • 自动安全过滤和属性验证

实现相关的 PR:

📊 增强的表格渲染

表格现在在 Markdown 和 EPUB 输出中均以原生 HTML 格式渲染,提供更好的结构和可读性。资源元数据现在支持公式、图片和表格的结构化标题和说明。

https://github.com/oomol-lab/pdf-craft/pull/306

📖 PDF 元数据提取

自动从 PDF 文件中提取图书元数据(标题、作者、出版社、ISBN 等),并用于填充 EPUB 元数据。当 PDF 已包含这些信息时,无需手动指定图书信息。

https://github.com/oomol-lab/pdf-craft/pull/284

📰 多栏布局检测

通过直方图谷值检测和变异系数分割,改进了多栏布局的处理(常见于学术论文和杂志)。现在会在处理前按列段正确分组布局。

https://github.com/oomol-lab/pdf-craft/pull/286

🐛 Bug 修复

🔧 改进

📚 文档

🔄 API 变更

新增参数

  • transform_markdown() 和 transform_epub() 中的 toc_assumed 参数:
    • 当为 True 时:尝试从 PDF 中定位并提取目录以构建文档结构
    • 当为 False 时:仅基于文档标题生成目录
    • 默认值:EPUB 为 True,Markdown 为 False

新增导出

  • PDFDocumentMetadata:用于 PDF 元数据提取的数据类

🙏 贡献者

感谢所有为本次发布做出贡献的人!

📦 安装

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install pdf-craft==1.0.4

详细安装说明请参阅安装指南。

完整变更日志:https://github.com/oomol-lab/pdf-craft/compare/v1.0.3...v1.0.4

发布 v1.0.3

更新内容

许可证改进

  • 移除 PyMuPDF (fitz) 依赖: 用 Poppler 替换 PyMuPDF (AGPL-3.0) 进行 PDF 解析和渲染,保持 pdf-craft 的 MIT 许可证兼容性
    • pdf-craft 现在通过 pdf2image (MIT) 使用 Poppler 进行所有 PDF 操作
    • 此变更确保整个项目保持在宽松的 MIT 许可证下

新功能

  • 自定义 PDF 处理器支持: 在 predownload_models()、transform_markdown() 和 transform_epub() 函数中添加了 pdf_handler 参数,允许用户自定义 PDF 渲染实现
  • Poppler 集成: 迁移到 Poppler (通过 pdf2image) 进行 PDF 解析和渲染,提供更好的兼容性和控制
  • 新的公共 API: 导出了 PDFHandler、PDFDocument、DefaultPDFHandler 和 DefaultPDFDocument 用于高级自定义
  • RENDERED 事件: 添加了 OCREventKind.RENDERED 事件来跟踪 PDF 页面渲染进度

破坏性变更

⚠️ 参数重命名: ignore_fitz_errors → ignore_pdf_errors

  • 更新您的代码:transform_markdown(..., ignore_pdf_errors=True) 而不是 ignore_fitz_errors=True
  • 更新您的代码:transform_epub(..., ignore_pdf_errors=True) 而不是 ignore_fitz_errors=True

⚠️ 异常重命名: FitzError → PDFError

  • 相应更新您的异常处理代码

依赖项

Bug 修复

  • 升级 doc-page-extractor 以修复 bug (#280)

迁移指南

如果您从 v1.0.2 升级,请:

  1. 安装 Poppler,按照安装指南操作

  2. 更新代码中的参数名称:

    # 之前 (v1.0.2)
transform_markdown(..., ignore_fitz_errors=True)

# 之后 (v1.0.3)
transform_markdown(..., ignore_pdf_errors=True)

  3. 更新异常处理,如果您捕获 FitzError:

    # 之前 (v1.0.2)
from pdf_craft import FitzError

# 之后 (v1.0.3)
from pdf_craft import PDFError

完整更新日志

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.2...v1.0.3

v1.0.2

本版本改进了 EPUB 生成、行内 LaTeX 支持,并增强了脚注和表格的处理。

更新内容

新功能

改进

Bug 修复

破坏性变更

⚠️ API 参数变更: transform_markdown() 和 transform_epub() 函数中的 model 参数已重命名为 ocr_size。此外,类型 DeepSeekOCRModel 已重命名为 DeepSeekOCRSize。

迁移:

# 之前
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    model="gundam"
)

# 之后 (v1.0.2)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    ocr_size="gundam"
)

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.1...v1.0.2

v1.0.1 新增内容

  • 增强的错误处理:添加了结构化错误类型(FitzError、OCRError、InterruptedError),包含详细的页码和步骤信息,便于调试
  • 改进的稳定性:修复了遇到单页 PyMuPDF 错误时的崩溃问题 - 现在可以优雅地处理页面级别的失败
  • 在线演示:现在可以直接在浏览器中访问 PDF Craft 试用 PDF Craft,无需任何安装

更新内容

完整更新日志: https://github.com/oomol-lab/pdf-craft/compare/v1.0.0...v1.0.1

🎉 PDF Craft v1.0.0 正式发布

PDF Craft v1.0.0 现已正式发布。此版本包含重大架构变更,并带来了显著的性能提升。

🚀 核心变化:全面拥抱 DeepSeek OCR

v1.0.0 最大的变化是基于 DeepSeek OCR 完全重写,消除了对 LLM 进行文本校正的依赖。

DeepSeek OCR 是一个强大的开源 OCR 引擎,支持复杂内容识别(表格、公式、图片、脚注等),并具有出色的文档结构理解能力。得益于 DeepSeek OCR,pdf-craft 现在提供:

  • 完全本地处理:整个转换过程完全在本地运行,无需任何网络请求。无需配置 LLM API,也不会因网络问题或 API 故障导致转换失败——在旧版本中,单个 LLM 请求失败就会导致整个转换过程中断。
  • 更快的速度:相比需要多次调用 LLM 进行文本校正的 v0.2.8,新版本使用直接的 OCR 识别,速度显著提升。
  • 更高的准确性:DeepSeek OCR 在文档结构分析、表格识别和公式提取方面表现出色,无需二次校正即可提供高质量结果。
  • 更简单的 API:移除了复杂的 LLM 配置和多步处理工作流程。现在只需一个函数调用即可完成转换。

此外,v1.0.0 已完全迁移到 DeepSeek OCR(MIT 许可证),移除了之前的 AGPL-3.0 依赖。整个项目现在使用更宽松的 MIT 许可证,使商业使用和集成更加容易!

⚠️ 重要变化:需要 CUDA 环境

新版本需要 CUDA 环境才能运行。 这是因为 DeepSeek OCR 依赖 CUDA 加速来实现高效的文档识别。旧版本(v0.2.8)可以在纯 CPU 环境下使用 LLM 工作,但新版本没有 GPU 无法运行。

如果您的环境不支持 CUDA,请不要升级到 v1.0.0。继续使用 v0.2.8:

pip install pdf-craft==0.2.8

有关 CUDA 环境安装的具体说明,请参阅安装指南。

🚫 何时不应升级

在以下情况下请继续使用 v0.2.8:

  1. 没有 GPU 或 CUDA 环境:新版本需要 CUDA,没有 GPU 无法运行
  2. 需要 LLM 文本校正:新版本已移除 LLM 校正功能。如果您的使用场景需要对 OCR 结果进行二次校正,请继续使用旧版本或将其与 epub-translator 结合使用

🙏 致谢

感谢 DeepSeek OCR 开源,以及所有为 pdf-craft 贡献代码和反馈的社区成员!

如果您有 CUDA 环境,现在就升级到 v1.0.0,体验更快、更稳定、更简单的 PDF 转换! 🚀