Data Cleaner - 文档数据清洗工具

概述

对 PDF、Word(DOC/DOCX)、纯文本(TXT) 和 Markdown(MD) 文档进行选择性内容清洗。支持移除页眉页脚、页码、指定关键词/句子、正则匹配内容以及空白格式清理，可按需组合多种清洗规则。

格式自由切换：清洗后可在 PDF / DOCX / DOC 三种格式之间自由转换输出。例如输入 .doc 清洗后输出 .pdf，或输入 .pdf 清洗后输出 .docx。

.doc 格式支持：旧版 Word (.doc) 文件优先通过 LibreOffice 转换为 .docx 处理（保留完整排版）；LibreOffice 不可用时自动回退到 Spire.Doc.Free 提取正文（不含页眉页脚）。两种方案均支持清洗后输出为 .doc / .docx / .pdf。

何时使用

当用户提出以下需求时触发本 skill：

"帮我去掉这个 PDF 的页眉页脚"
"移除文档中的页码"
"把这个文件里包含'机密'的行都删掉"
"用正则去掉文档里的日期"
"清理文档里的多余空行"
"清洗这个 Word 文档"
"去掉文档里的某些关键词和关键句"

依赖安装

首次使用前需安装 Python 依赖（PyMuPDF、python-docx 和 Spire.Doc.Free）：

<python> <skill_dir>/scripts/install_deps.py

其中 <python> 为当前 Python 解释器路径，<skill_dir> 为本 skill 目录路径。

LibreOffice 为可选依赖（用于排版保真的格式转换）。未安装时自动回退到 Spire.Doc + PyMuPDF 备选方案。

使用方式

根据文件格式选择脚本

| 文件格式 | 脚本 | 可选输出格式 | |----------|------|-------------| | PDF (.pdf) | scripts/clean_pdf.py | pdf / docx / doc / txt | | Word (.docx) | scripts/clean_docx.py | docx / doc / pdf | | Word (.doc) | scripts/clean_docx.py（自动转换） | doc / docx / pdf | | TXT (.txt) | scripts/clean_text.py | txt | | Markdown (.md) | scripts/clean_text.py | md |

统一入口：也可使用 scripts/clean.py 自动检测输入格式并路由到对应脚本，所有参数透传：

<python> <skill_dir>/scripts/clean.py input.doc --remove-headers-footers --output-format pdf -o output.pdf
<python> <skill_dir>/scripts/clean.py input.pdf --keywords "机密" --output-format docx -o output.docx

通用参数（所有脚本共享）

--remove-headers-footers    移除页眉页脚
--remove-page-numbers       移除页码
--keywords KW [KW ...]      移除包含指定关键词的行/段落
--sentences S [S ...]       精确移除指定句子
--patterns P [P ...]        使用正则表达式移除匹配内容（用 r"..." 格式）
--clean-whitespace          清理多余空行、空格、制表符
--dry-run                   仅预览清洗结果，不写入文件
--output PATH / -o PATH     输出文件路径（不指定则在原文件名后加 _cleaned）

Word (DOC/DOCX) 专用参数

--output-format doc|docx|pdf  输出格式（默认跟随输入格式）

PDF 专用参数

--extract-mode              仅输出清洗后的纯文本（.txt），等同于 --output-format txt
--output-format pdf|docx|doc|txt  输出格式（默认 pdf）
--margin-ratio RATIO        页眉页脚边距比例（默认 0.08，即页面高度 8%）

TXT/MD 专用参数

--encoding ENC              指定文件编码（默认自动检测 UTF-8/GBK/GB2312）
--remove-markdown-extra     [MD专用] 移除多余的 Markdown 标记（连续分割线等）

执行流程

确认文件格式：根据用户提供的文件扩展名选择对应脚本
确认清洗需求：根据用户描述确定需要启用哪些清洗选项
安装依赖：首次使用时运行 install_deps.py 安装 PyMuPDF、python-docx 和 Spire.Doc.Free；LibreOffice 为可选依赖（排版保真输出）
预览（可选）：使用 --dry-run 参数预览清洗效果，确认无误后再正式执行
执行清洗：运行对应脚本，传入用户指定的参数
返回结果：告知用户清洗后的文件路径和清洗统计

使用示例

PDF 清洗

# 移除页眉页脚和页码，输出新 PDF
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --remove-headers-footers --remove-page-numbers -o cleaned.pdf

# 清洗后输出为 DOCX（格式切换）
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --remove-headers-footers --output-format docx -o cleaned.docx

# 清洗后输出为 DOC（格式切换）
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --keywords "机密" --output-format doc -o cleaned.doc

# 提取清洗后的纯文本
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --remove-headers-footers --remove-page-numbers --extract-mode -o cleaned.txt

# 移除关键词并清理空白
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --keywords "机密" "内部使用" --clean-whitespace -o cleaned.pdf

# 使用正则移除日期和邮箱
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --patterns r"\d{4}-\d{2}-\d{2}" r"[\w.]+@[\w.]+" -o cleaned.pdf

# 预览清洗效果（不写入文件）
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --remove-headers-footers --remove-page-numbers --dry-run

# 调整页眉页脚检测边距（增大到 12%）
<python> <skill_dir>/scripts/clean_pdf.py input.pdf --remove-headers-footers --margin-ratio 0.12 -o cleaned.pdf

Word (DOC/DOCX) 清洗

# 移除页眉页脚
<python> <skill_dir>/scripts/clean_docx.py input.docx --remove-headers-footers -o cleaned.docx

# .doc 文件清洗（自动转换为 .docx 处理，默认输出 .doc）
<python> <skill_dir>/scripts/clean_docx.py input.doc --remove-headers-footers --keywords "北大法宝" -o cleaned.doc

# .doc 文件清洗，输出为 .docx
<python> <skill_dir>/scripts/clean_docx.py input.doc --remove-headers-footers --output-format docx -o cleaned.docx

# .docx 清洗后输出为 PDF（格式切换）
<python> <skill_dir>/scripts/clean_docx.py input.docx --remove-headers-footers --output-format pdf -o cleaned.pdf

# .doc 清洗后输出为 PDF（格式切换）
<python> <skill_dir>/scripts/clean_docx.py input.doc --remove-headers-footers --output-format pdf -o cleaned.pdf

# 移除关键词和指定句子
<python> <skill_dir>/scripts/clean_docx.py input.docx --keywords "草稿" "待审核" --sentences "本文件仅供参考" -o cleaned.docx

# 正则匹配 + 空白清理
<python> <skill_dir>/scripts/clean_docx.py input.docx --patterns r"\d{4}-\d{2}-\d{2}" --clean-whitespace -o cleaned.docx

# 预览清洗效果
<python> <skill_dir>/scripts/clean_docx.py input.docx --remove-headers-footers --dry-run

TXT / Markdown 清洗

# 移除页码并清理空白
<python> <skill_dir>/scripts/clean_text.py input.txt --remove-page-numbers --clean-whitespace -o cleaned.txt

# 移除关键词 + 正则匹配
<python> <skill_dir>/scripts/clean_text.py input.md --keywords "机密" --patterns r"\d{4}-\d{2}-\d{2}" -o cleaned.md

# 完整清洗（页眉页脚 + 页码 + 空白 + Markdown 标记）
<python> <skill_dir>/scripts/clean_text.py input.md --remove-headers-footers --remove-page-numbers --clean-whitespace --remove-markdown-extra -o cleaned.md

# 指定编码读取（GBK 编码的文件）
<python> <skill_dir>/scripts/clean_text.py input.txt --encoding gbk --remove-page-numbers -o cleaned.txt

# 预览清洗效果
<python> <skill_dir>/scripts/clean_text.py input.txt --remove-headers-footers --dry-run

页码识别规则

脚本自动识别以下页码格式并移除（使用 --remove-page-numbers 时生效）：

纯数字：1、12、123
带分隔符：- 1 -、– 12 –
中文格式：第 1 页、第1页/共10页
英文格式：Page 1、Page 1 of 10
分数式：1/10、12 / 50
罗马数字：i、iv、XII（论文前言常用）

清洗执行顺序

多个清洗选项可组合使用，执行顺序为：

页眉页脚移除
页码移除
关键词移除（整行/整段）
句子精确移除
正则匹配移除
空白格式清理

注意事项

原文件不受影响：脚本默认输出新文件，不会修改原始文件
PDF 限制：扫描版 PDF（图片型）无法提取文本，需先进行 OCR
PDF 中文输出：生成新 PDF 时会尝试使用内置 CJK 字体，如遇字体问题建议使用 --extract-mode 输出纯文本
正则表达式：传入 --patterns 参数时使用 r"..." 原始字符串格式
编码：TXT/MD 文件自动检测 UTF-8/GBK/GB2312 编码，输出统一为 UTF-8
预览：建议首次使用 --dry-run 预览清洗效果，确认无误后再正式执行
DOCX 表格：正则移除功能同时处理正文段落和表格单元格内容
.doc 格式：优先用 LibreOffice 转换（保留排版），LibreOffice 不可用时自动回退到 Spire.Doc.Free 提取正文（不含页眉页脚，--remove-headers-footers 自动生效）
页眉页脚深度清除：直接操作 XML 级别的 header/footer part，确保引用 part 中的内容（包括图片、文本框）被彻底清除
格式切换：使用 --output-format 参数在 PDF/DOCX/DOC 之间自由切换。docx→pdf 优先用 LibreOffice 转换（保留排版），不可用时回退到 PyMuPDF 渲染（内容准确但丢失原排版）；pdf→docx 通过文本提取
统一入口：scripts/clean.py 自动检测输入格式并路由到对应脚本，无需手动选择脚本
备选方案：LibreOffice 不可用时，.doc→.docx 和 .doc→.pdf 自动回退到 Spire.Doc.Free + PyMuPDF；.docx→.pdf 回退到 PyMuPDF 文本渲染。备选方案只提取正文段落，不保留原始排版格式

参考资源

references/cleaning_patterns.md - 详细的清洗模式参考，包含页码识别模式、页眉页脚识别策略和常见使用场景