rust crate undoc 介绍

一、工具基础信息

定位：一款高性能 Rust 库，主打 Microsoft Office 文档（DOCX、XLSX、PPTX）内容提取，支持转换为多种格式。
版本与更新：当前版本 0.1.10，2025 年 12 月 21 日发布；历史版本从 0.1.1 到 0.1.9，多集中在 2025 年 12 月 20-21 日更新，且自带通过 GitHub Releases 实现的自更新机制（可检查更新、更新到最新版、强制重装）。
文档覆盖与规模：文档覆盖率 91.49%（235 个项目中 215 个有文档，38 个项目中 14 个带示例）；源码大小 368.97 kB，文档大小 3.9 MB。
依赖项：包含 quick-xml（^0.37）、rayon（^1.10）、regex（^1.11）、serde（^1.0）、serde_json（^1.0）、thiserror（^2.0）、tokio（^1.42，可选）、unicode-normalization（^0.1）、zip（^2.2）、tempfile（^3.14）等。
所有权：由 iyulab-caveman 维护，仓库地址为 iyulab/undoc000，可在 crates.io 获取。

二、核心功能特性

格式支持
- 输入格式：DOCX（Word）、XLSX（Excel）、PPTX（PowerPoint），均已实现完整支持。
- 输出格式：Markdown（带结构化排版，含标题、列表、表格等）、Plain Text（纯文本，无格式标记）、JSON（含完整元数据，如标题、作者、创建时间等）。
内容处理能力
- 保留文档结构：包括标题层级、列表（有序 / 无序及嵌套）、表格、行内格式（粗体、斜体、下划线、删除线）。
- 专项功能：PPTX 表格完整解析、CJK 文本智能间距（支持中韩日内容）、资源提取（图片、图表、嵌入式媒体）、文本清理（多预设，适配 LLM 训练数据准备）。
技术优势：基于 Rayon 实现并行处理（多章节 / 工作表 / 幻灯片）、通过 quick-xml 实现高效 XML 解析、支持大文档内存高效处理，还提供 C-ABI FFI（可作为 C#、Python 等语言的原生库）。

三、安装方式

（一）预编译二进制包（推荐）

平台	架构	下载与安装命令
Windows	x64	1. 下载：`Invoke-WebRequest -Uri "https://github.com/iyulab/undoc/releases/latest/download/undoc-cli-x86_64-pc-windows-msvc.zip" -OutFile "undoc.zip"`2. 解压：`Expand-Archive -Path "undoc.zip" -DestinationPath "."`3. （可选）移动到 PATH 目录：`Move-Item -Path "undoc.exe" -Destination "$env:LOCALAPPDATA\Microsoft\WindowsApps"`4. 验证：`undoc version`
Linux	x64	1. 下载：`curl -LO https://github.com/iyulab/undoc/releases/latest/download/undoc-cli-x86_64-unknown-linux-gnu.tar.gz`2. 解压：`tar -xzf undoc-cli-x86_64-unknown-linux-gnu.tar.gz`3. 安装：`sudo mv undoc /usr/local/bin/`（系统级）或`mkdir -p ~/.local/bin && mv undoc ~/.local/bin/ && echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc`（用户级）4. 验证：`undoc version`
macOS	Intel	1. 下载：`curl -LO https://github.com/iyulab/undoc/releases/latest/download/undoc-cli-x86_64-apple-darwin.tar.gz`2. 解压：`tar -xzf undoc-cli-x86_64-apple-darwin.tar.gz`3. 安装：`sudo mv undoc /usr/local/bin/`4. 验证：`undoc version`
macOS	Apple Silicon（M1/M2/M3）	1. 下载：`curl -LO https://github.com/iyulab/undoc/releases/latest/download/undoc-cli-aarch64-apple-darwin.tar.gz`2. 解压：`tar -xzf undoc-cli-aarch64-apple-darwin.tar.gz`3. 安装：`sudo mv undoc /usr/local/bin/`4. 验证：`undoc version`

（二）Cargo 安装（需已安装 Rust）

安装 CLI：cargo install undoc-cli
项目添加库依赖：cargo add undoc

四、使用指南

（一）CLI 命令使用

核心命令

命令	功能	示例
`undoc <file> [output]`	提取所有格式（Markdown、文本、JSON）+ 媒体到输出目录（默认命令）	`undoc document.docx ./output`
`undoc convert <file> [OPTIONS]`	同默认命令，显式指定转换	-
`undoc markdown/<file> [OPTIONS]`（别名`md`）	仅转换为 Markdown	`undoc md document.docx --frontmatter -o report.md`（带 YAML 前端 matter）
`undoc text <file> [OPTIONS]`	仅转换为纯文本	`undoc text document.docx --cleanup standard -o output.txt`（带文本清理）
`undoc json <file> [OPTIONS]`	仅转换为 JSON	`undoc json document.docx --compact -o output.json`（紧凑 JSON 格式）
`undoc info <file>`	显示文档信息（格式、章节数、资源数、标题、作者等）	`undoc info document.docx`
`undoc extract <file> [OPTIONS]`	仅提取资源（图片等）	`undoc extract presentation.pptx -o ./media`
`undoc update [OPTIONS]`	自更新	`undoc update --check`（检查更新）
`undoc version`	显示版本信息	-

Markdown 转换关键选项

选项	描述	默认值
`-o, --output`	输出文件路径	stdout（标准输出）
`-f, --frontmatter`	包含 YAML 前端 matter	false
`--table-mode`	表格渲染模式（`markdown`/`html`/`ascii`）	markdown
`--cleanup`	文本清理预设（`minimal`/`standard`/`aggressive`）	none
`--max-heading`	最大标题层级（1-6）	6

批量转换示例
- Shell：for f in *.docx; do undoc md "$f" -o "${f%.docx}.md"; done
- PowerShell：Get-ChildItem *.docx | ForEach-Object { undoc md $_.FullName -o "$($_.BaseName).md" }

（二）Rust 库使用

快速开始

rust 复制代码

use undoc::{parse_file, render};
fn main() -> undoc::Result<()> {
    // 解析文档
    let doc = parse_file("document.docx")?;
    // 转换为Markdown
    let options = render::RenderOptions::default();
    let markdown = render::to_markdown(&doc, &options)?;
    println!("{}", markdown);
    // 获取纯文本
    let text = render::to_text(&doc, &options)?;
    // 获取JSON
    let json = render::to_json(&doc, render::JsonFormat::Pretty)?;
    Ok(())
}

自定义渲染选项

rust 复制代码

use undoc::render::{RenderOptions, CleanupPreset, TableFallback};
let options = RenderOptions::new()
    .with_frontmatter(true) // 带YAML前端matter
    .with_table_fallback(TableFallback::Html) // 表格 fallback 为HTML
    .with_cleanup_preset(CleanupPreset::Aggressive) // 激进文本清理
    .with_max_heading(3); // 最大标题层级3
let markdown = render::to_markdown(&doc, &options)?;

文档结构操作：可访问元数据（标题、作者、创建时间）、迭代章节与元素、提取资源文件。
格式检测 ：支持从文件路径（detect_format_from_path）或字节数组（detect_format_from_bytes）检测文档格式。

（三）C# /.NET 集成

获取原生库 ：从 GitHub Releases 下载（Windows x64 为undoc.dll、Linux x64 为libundoc.so、macOS 为libundoc.dylib），或通过cargo build --release --features ffi从源码构建。
C# 包装器使用

csharp 复制代码

using Undoc;
// 解析并转换为Markdown
string markdown = UndocNative.ToMarkdown("document.docx");
// 解析并转换为纯文本
string text = UndocNative.ToText("document.docx");
// 解析并转换为JSON
string json = UndocNative.ToJson("document.docx");
// 从字节数组解析
byte[] data = File.ReadAllBytes("document.docx");
string markdown = UndocNative.ToMarkdownFromBytes(data);

rust 复制代码

#![allow(warnings)]
fn main() -> Result<(), Box<dyn std::error::Error>> {
    use undoc::{to_json, render::JsonFormat};
    use undoc::{parse_file, to_markdown};

    let path = "E:/demo.xlsx";

    // Simple text extraction
    let text = undoc::extract_text(path)?;
    println!("{}", text);

    // Convert to Markdown
    let markdown = to_markdown(path)?;
    std::fs::write("output.md", markdown)?;


    let json = to_json(path, JsonFormat::Compact)?;
    std::fs::write("output.json", json)?;

    // Full parsing with access to structure
    let doc = parse_file(path)?;
    println!("Sections: {}", doc.sections.len());
    println!("Resources: {}", doc.resources.len());
    Ok(())
}