docs-extractor 是一组面向截断、分割或轻度损坏办公文档的文本与图片提取工具。项目重点不是还原完整版式，而是在文件结构不完整、常规解析库无法打开时，尽可能从片段中恢复可读内容，适用于数据安全风控、文档恢复、内容审计和格式预研场景。
- 支持从 Office Open XML、OLE2、BIFF、PDF 对象流和 WPS 私有格式片段中提取内容。
- 支持文本提取、图片识别、媒体目录输出、质量统计和调试日志。
- 对截断文件采用多层容错策略，包括字节扫描、结构重建、流式解压、XML/BIFF/OLE 解析降级和文本过滤。
- 对 PDF 采用最小化重建思路，优先重建可读 PDF，再借助成熟库提取文本和图片。
- 每个格式模块尽量保持单独入口，便于独立测试、替换和扩展。
| 格式 | 模块目录 | 主要入口 | 提取内容 | 技术路线 |
|---|---|---|---|---|
.docx |
src/docs_extractor/docx/ |
word_recovery.py |
文本、图片 | OOXML ZIP 扫描、XML 提取、<w:t> 文本解析、media 目录恢复 |
.xlsx |
src/docs_extractor/xlsx/ |
xlsx_fragment_text_extractor.py |
文本、图片 | 字节级 XML 标签扫描、文本分类、图片签名识别 |
.pptx |
src/docs_extractor/pptx/ |
pptx_fragment_text_extractor.py |
文本、图片 | OOXML ZIP/XML 恢复、幻灯片/备注/表格/SmartArt 文本解析 |
.pdf |
src/docs_extractor/pdf/ |
extract.py |
文本、图片 | PDF 对象扫描、最小化重建、PyMuPDF/pdfplumber 提取 |
.doc |
src/docs_extractor/doc/ |
doc_fragment_extractor.py |
文本、图片 | OLE2 复合文档解析、WordDocument 流解析、文本过滤 |
.xls |
src/docs_extractor/xls/ |
xls_fragment_extractor.py |
文本、图片 | OLE2 + BIFF 记录解析、SST/工作表/绘图记录处理 |
.ppt |
src/docs_extractor/ppt/ |
ppt_fragment_extractor.py |
文本、图片 | OLE2 复合文档解析、PowerPoint 记录扫描、多层降级 |
.wps |
src/docs_extractor/wps/ |
wps_extractor.py |
文本、图片 | OLE 结构化解析、WPS 文本流和图像流提取 |
.et |
src/docs_extractor/et/ |
et_fragment_extractor.py |
文本、图片 | BIFF8 记录增量解析、SST/单元格/图像记录提取 |
建议使用 Python 3.7+。大部分模块以标准库为主，PDF 模块建议安装第三方库以提升提取质量。
cd D:\PR\docs-extractor
pip install -e .PDF 推荐依赖：
pip install -e ".[pdf]"DOC 文本过滤可选依赖：
pip install -e ".[doc]"推荐使用统一入口：
python -m docs_extractor extract --format pdf --input .\test\fixtures\pdf\pdf_part_aa --output .\output\pdf格式专用入口仍可使用：
python -m docs_extractor.pdf.extract .\test\fixtures\pdf\pdf_part_aa .\output\pdf常用格式示例：
python -m docs_extractor extract --format docx --input .\test\fixtures\docx --output .\output\docx
python -m docs_extractor extract --format xlsx --input .\test\fixtures\xlsx --output .\output\xlsx
python -m docs_extractor extract --format pptx --input .\test\fixtures\pptx --output .\output\pptx
python -m docs_extractor extract --format doc --input .\test\fixtures\doc\doc_part_aa --output .\output\doc
python -m docs_extractor extract --format xls --input .\test\fixtures\xls\xls_part_aa --output .\output\xls
python -m docs_extractor extract --format ppt --input .\test\fixtures\ppt\ppt_part_aa --output .\output\ppt
python -m docs_extractor extract --format wps --input .\test\fixtures\wps\wps_part_aa --output .\output\wps
python -m docs_extractor extract --format et --input .\test\fixtures\et\et_part_aa --output .\output\et输出通常包含：
output/
├── output.txt
└── media/
PDF 模块还会生成用于调试的 rebuilt.pdf。
不同模块的历史实现略有差异，但推荐统一关注以下产物：
output.txt：所有提取文本的汇总文件。media/：提取出的图片或媒体文件目录。*.log/*_report.txt/*_summary.txt：调试、统计和质量报告。rebuilt.pdf：PDF 模块用于调试的最小化重建文件。
如果需要统一对接下游系统，建议以 output.txt 和 media/ 作为稳定交付边界。
.docx、.xlsx、.pptx 本质上是 ZIP 容器加 XML 文件。片段提取的关键是尽量绕过完整 ZIP 中央目录依赖，通过局部文件头扫描、流式解压和 XML 标签解析恢复内容。
文档片段 -> ZIP/字节扫描 -> XML/媒体条目定位 -> 多策略解压 -> 文本与图片输出
.doc、.xls、.ppt、.wps、.et 主要依赖 OLE2 复合文档结构或 BIFF 记录。片段提取需要解析扇区、目录项、流数据和格式专有记录，并在结构损坏时降级为记录扫描。
文档片段 -> OLE2 头解析 -> FAT/目录/流定位 -> 格式记录解析 -> 文本与图片输出
PDF 片段通常缺少完整交叉引用表或尾部结构。项目采用最小化重建策略：先扫描可用对象，补齐 Catalog、Pages、Resources 等最小结构，再交给成熟 PDF 库提取。
PDF片段 -> 对象扫描 -> 最小结构重建 -> 第三方库提取 -> 输出质量比较
docs-extractor/
├── src/docs_extractor/ # 正式源码
├── docs/ # 架构、实践、格式技术文档和归档材料
├── test/fixtures/ # 各格式样本片段
├── test/tests/ # 自动化 smoke test
├── scripts/ # 辅助脚本
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
└── README.md
- 数据安全风控中的办公文档内容扫描。
- 文件分片、传输中断或轻度损坏后的文本恢复。
- 对未知办公格式进行技术预研和可行性验证。
- 为后续 AI 分析、检索或审计流程准备文本和图片输入。
- 片段提取不是完整文件修复，无法保证恢复原始版式、页码、单元格坐标或动画效果。
- 压缩流、OLE 扇区链、PDF 字体映射严重缺失时，文本可能不完整或顺序错乱。
- 图片提取依赖片段中是否包含完整图片数据，部分格式在截断片段中可能只能恢复部分图片。
.et多工作表场景仍存在覆盖不完整的问题。- 除 PPT 模块外，部分模块在特定样本中可能出现图片截断，需要结合输出报告人工判断。
docs/architecture.md：项目结构和入口约定。docs/reports/AI赋能技术预研成果汇报.md：项目背景、AI 辅助预研过程和成果总结。docs/ai-research-practice.md：使用 Claude Code 做格式预研的实践经验。docs/implementation-comparison.md：PPTX 与 PDF 模块实现方式对比。docs/formats/：各格式的原理、实现方案和历史模块 README。src/docs_extractor/*/CLAUDE.md：对应模块的 Agent 工作指导。