前言

最近在做標書的時候發現，有些文檔文字量很大，想讓大模型完全解讀不太現實，先不說 context 長度夠不夠，首先 token 消耗量就爆炸了

于是想到使用取巧的方式，提取 PDF 的目錄來進行分析，于是說干就干，用 C# 寫了一個工具來實現目錄提取，結果效果還不錯

后續我又繼續完善這個工具，增加了語義識別等功能

繼續沿用 C# + AOT + GitHub Actions + dotnet tool + nuget 這套流程的開發

項目地址: https://github.com/star-plan/pdf-toc-extractor

類似項目：

• SharpIco
• ImageGlider

為什么是目錄提??？

PDF 轉 word、markdown 等格式的工具太多了

咱不卷這個賽道

（說是這么說，我最近也做了一個??，不排除后續把 PDF 轉文檔的功能集成到這個項目里）

咱就專注于這個小眾的需求，把 PDF 目錄提取這個功能做好

后續又增加了語義識別功能，有些 PDF 并沒有內嵌目錄，這時候就需要從 PDF 的內容中分析提取出目錄。

我一開始使用了模式匹配，結果效果很差，后面換成 NLP 的思路，雖然只是用了最簡單的語義識別，但效果的提升非常可觀！

可見選對工具還是很重要的

PdfTocExtractor

PdfTocExtractor 是一個純 C# AOT 實現的輕量級PDF目錄提取工具，用于從PDF文件中提取目錄（TOC）并導出為多種格式。支持Markdown、JSON、XML、純文本等格式，完全擺脫命令行依賴，無需額外的PDF處理工具，適合在 .NET 項目中內嵌、分發或集成自動化流程中使用。

通過PdfTocExtractor，您可以輕松從PDF文檔中提取書簽和目錄結構，生成清晰的導航文檔。v2.0新增的語義分析功能讓您即使在PDF沒有嵌入書簽的情況下，也能通過基于NLP的智能分析自動識別章節標題，完美適用于文檔處理、內容分析和自動化工作流。

?? 跨平臺、零依賴、極速提取，一切盡在 PdfTocExtractor！

? 功能特點

• ?? 從PDF文件提取書簽/目錄信息
• ?? 語義分析功能：基于NLP的智能章節標題識別，適用于無書簽PDF
• ?? 支持多種輸出格式：Markdown、JSON、XML、純文本
• ?? 可配置的導出選項（層級深度、頁碼格式等）
• ?? 可擴展的導出器架構，支持自定義格式
• ? 異步操作支持，高性能處理
• ??? 提供命令行工具和NuGet包
• ?? 支持AOT編譯，原生性能無需.NET運行時
• ?? 跨平臺支持：Windows、Linux、macOS
• ??? 多種分析模式：默認、嚴格、寬松模式可選

?? 支持的輸出格式

• Markdown (md, markdown) - 適合文檔和網頁顯示，支持層級結構
• JSON (json) - 適合程序處理和API集成，包含完整元數據
• XML (xml) - 結構化數據交換，標準化格式
• Text (txt, text) - 純文本格式，簡潔易讀

使用方法

依然和其他工具一樣

提供了 nuget 庫和 dotnet tool 命令行工具

可以作為庫引入使用，也可以在命令行使用

命令行

安裝 CLI 工具

dotnet tool install --global PdfTocExtractor.Cli

命令行使用

# ?? 智能提取（推薦）- 自動選擇最佳方法
pdftoc smart document.pdf -o output.md

# ?? 提取PDF書簽（傳統方法）
pdftoc extract document.pdf -o output.md

# ?? 語義分析（v2.0新功能 - 適用于無書簽的PDF）
pdftoc semantic document.pdf -o output.md

# 指定輸出格式
pdftoc smart document.pdf -o output.json -f json

# 設置最大層級深度
pdftoc smart document.pdf -o output.xml --max-depth 3

# 自定義標題和頁碼格式
pdftoc smart document.pdf -o output.txt --title "我的文檔目錄" --page-format "第 {0} 頁"

# 語義分析 - 嚴格模式（更精確的標題識別）
pdftoc semantic document.pdf -o output.md --mode strict --confidence 0.7

# 語義分析 - 調試模式（查看分析過程）
pdftoc semantic document.pdf -o output.md --debug --verbose

# 結構分析 - 寬松模式（識別更多潛在標題）
pdftoc analyze document.pdf -o output.md --relaxed

# 結構分析 - 自定義參數
pdftoc analyze document.pdf -o output.md --min-font-size 14 --use-bold --debug

# 智能提取 - 帶結構分析配置
pdftoc smart document.pdf -o output.md --analysis-preset strict --debug-analysis

# 顯示詳細輸出
pdftoc smart document.pdf -o output.md --verbose

# 診斷PDF文件問題
pdftoc diagnose document.pdf

作為庫使用

安裝核心庫

dotnet add package PdfTocExtractor

代碼示例

using PdfTocExtractor;
using PdfTocExtractor.Exporters;
using PdfTocExtractor.Models;

// 創建提取器實例
var extractor = new PdfTocExtractor();

// ?? 智能提取（推薦）- 自動選擇最佳方法
var tocItems = await extractor.ExtractTocSmartAsync("document.pdf");

// ?? 傳統方法：提取PDF書簽
var bookmarkItems = await extractor.ExtractTocAsync("document.pdf");

// ?? 結構分析：適用于無書簽的PDF
var structureItems = await extractor.AnalyzeStructureAsync("document.pdf");

// ?? 結構分析：使用自定義配置
var analysisOptions = new StructureAnalysisOptions
{
    MinFontSizeForHeading = 14f,
    UseBoldAsIndicator = true,
    MaxHeadingLevels = 4,
    RequireStandaloneHeadings = true,
    DebugMode = false
};
var customStructureItems = await extractor.AnalyzeStructureAsync("document.pdf", analysisOptions);

// ?? 使用預設配置
var strictItems = await extractor.AnalyzeStructureAsync("document.pdf", StructureAnalysisOptions.Strict);
var relaxedItems = await extractor.AnalyzeStructureAsync("document.pdf", StructureAnalysisOptions.Relaxed);

// 導出為Markdown
await extractor.ExportToFileAsync(tocItems, "output.md", "markdown");

// 導出為JSON（帶自定義選項）
var exportOptions = new ExportOptions
{
    MaxDepth = 3,
    IncludePageNumbers = true,
    CustomTitle = "文檔目錄"
};
await extractor.ExportToFileAsync(tocItems, "output.json", "json", exportOptions);

// 智能提取并直接導出
await extractor.ExtractSmartAndExportAsync("document.pdf", "output.xml",
    exportOptions: exportOptions,
    structureOptions: StructureAnalysisOptions.Default);

擴展性

可以通過實現 IExporter 接口來創建自定義導出器：

public class CustomExporter : IExporter
{
    public string FormatName => "Custom";
    public string FileExtension => "custom";

    public string Export(IEnumerable<TocItem> tocItems, ExportOptions? options = null)
    {
        // 實現自定義導出邏輯
        return "custom format content";
    }

    public async Task ExportToFileAsync(IEnumerable<TocItem> tocItems, string filePath, ExportOptions? options = null)
    {
        var content = Export(tocItems, options);
        await File.WriteAllTextAsync(filePath, content);
    }
}

// 注冊自定義導出器
extractor.RegisterExporter("custom", new CustomExporter());

技術實現

PdfTocExtractor 使用以下技術：

• .NET 9.0 - 現代化的.NET平臺
• iText 9.2.0 - 強大的PDF處理庫
• iText7.bouncy-castle-adapter 9.2.0 - 加密PDF支持（必需）
• Newtonsoft.Json 13.0.3 - JSON序列化
• System.CommandLine 2.0.0 - 命令行參數解析
• AOT編譯支持 - 原生性能，無需.NET運行時

TODO 計劃

AI 增強功能

• AI 目錄識別 - 使用機器學習技術識別沒有書簽/大綱數據的PDF文檔目錄結構
  • 集成 OCR 技術識別掃描版PDF中的目錄頁面
  • 基于文本分析和格式識別的智能目錄提取
  • 支持多語言目錄識別（中文、英文、日文等）
  • 目錄層級結構智能推斷
  • 頁碼與目錄項的自動匹配算法

Web 服務接口

• RESTful API 開發 - 提供基于 HTTP 的 Web API 服務
  • PDF 文件上傳接口
  • 目錄提取 API 端點
  • 多格式導出 API（JSON、XML、Markdown等）
  • 批量處理接口
  • 任務狀態查詢接口
  • API 文檔和 Swagger 集成

Web 前端界面

• 現代化 Web UI - 開發用戶友好的 Web 前端界面
  • 拖拽式 PDF 文件上傳
  • 實時目錄提取進度顯示
  • 目錄結構可視化預覽
  • 多格式導出選項界面
  • 歷史記錄和文件管理
  • 響應式設計，支持移動端訪問

技術架構優化

• 微服務架構 - 將功能模塊化為獨立的微服務
  • PDF 處理服務
  • AI 識別服務
  • 文件存儲服務
  • 用戶管理服務
  • 容器化部署支持（Docker）

高級功能

• 智能分析 - 提供更多文檔分析功能
  • 文檔結構分析和統計
  • 目錄質量評估
  • 重復內容檢測
  • 文檔相似度比較
  • 批量文檔處理和分析報告

企業級功能

• 安全和權限 - 企業級安全特性
  • 用戶認證和授權
  • 文件訪問權限控制
  • 審計日志記錄
  • 數據加密存儲
  • API 訪問限制和配額管理

小結

到這里，PdfTocExtractor 的核心能力已經完整亮相：不管你的 PDF 有沒有書簽，都能一鍵生成結構化目錄；想要命令行批處理還是在代碼里靈活調用，都不在話下。??

在實際項目中，這個工具已經幫我節省了大量手動整理目錄的時間，也避免了 OCR 誤識別、格式混亂等繁瑣問題。尤其是新版的 Smart 與 Semantic 雙引擎，既快又準，真香！??

當然，項目還遠遠沒有到“終點”。后續的 AI 目錄識別、Web API、現代化 UI 乃至企業權限體系，都在 Roadmap 上等著逐步落地。如果你也對這些方向感興趣，歡迎 issue / PR / Star，一起把它打造成最好用的 PDF 目錄工具！??

最后，如果本文對你有所幫助，別忘了給倉庫點個 Star，讓更多小伙伴受益；也歡迎在評論區交流使用體驗或提功能建議，我們下篇文章再見～??