百万级文件自动化整理：去重、归档与Office格式清洗实战

1. 项目概述与需求拆解

先说结论：这不是一个单纯的"整理文件"的小活儿，而是一个典型的整机级数据治理工程。300GB、100万+文件、跨年级分类、重复备份堆积、Office文档格式错乱——这几件事叠加在一起，靠手工整理是绝对不可能在假期前完成的，必须上自动化流水线。

我理解你的核心痛点有三个层级：

• 最痛的是格式错乱：文档在你自己电脑上显示正常，发出去就乱。这是因为字体嵌入缺失、页码域未更新、页眉页脚样式漂移、默认打印机影响分页等一堆"隐性依赖"问题。这个问题优先级最高，因为直接影响你交付成果的质量。
• 次痛的是重复文件：导出、备份、复制的过程中积累了海量重复文件，占空间、碍眼、还容易误用旧版本。
• 最不紧急但最基础的是归档混乱：所有文件散落在大量文件夹里，命名不规范、层级混乱，必须"先收集、再清洗、后归档"。

整体策略我建议用一句话概括：逢整即整——整机级散落文件的"收集 + 清洗 + 归档"闭环。所谓"逢整即整"，就是把整台电脑当作一个整体来治理，不是零敲碎打地清理某个文件夹，而是把所有散落文件先收拢到一个"仓库"，再由仓库统一管理。

关于"模拟项目X"，我理解为你希望把这个整理工程当作一个独立的、可复现的"项目"来对待，而不是一次性临时操作。所以整个方案会以"项目文件夹"为单位，所有脚本、配置、日志、报告都收纳在同一个目录下，以后再有文件要整理，一键重跑即可。

先给你一张全局架构图（文字版）：

+---------------------------+ | 入口：run.py 一键执行 | +------------+--------------+ | v +------------+--------------+ | 预检模块（环境/空间/权限/Office） | +------------+--------------+ | v +------------+--------------+ | 收集模块（扫描全盘指定目录） | | 按扩展名/年级/日期分流 | +------------+--------------+ | v +------------+--------------+ | 归档模块（复制/移动到仓库目录） | | 保持原始元数据 + 生成归档清单 | +------------+--------------+ | v +------------+--------------+ | 去重模块（多级哈希比较） | | 精确重复 -> 近重复候选 | +------------+--------------+ | v +------------+--------------+ | 清理模块（回收站暂存/事务性删除） | | 生成回收清单，可一键回滚 | +------------+--------------+ | v +------------+--------------+ | 格式清洗模块（Office COM 批量重存）| | Word/Excel/PPT/PDF 四大类 | +------------+--------------+ | v +------------+--------------+ | 报告模块（汇总报告/日志/统计） | +---------------------------+

下面按阶段详细展开。

2. 整体策略与目录设计

2.1 策略核心：先收拢，再清洗，后归档

这九个字是整个方案的核心顺序逻辑。很多人做整理时习惯先"边整边删"，但在百万级文件规模下，这是灾难——你会陷入"删了又怕有用、留着又占空间"的纠结中。

正确的做法是：

1. 先收拢：把散落在各处的文件全部复制到一个统一的"原始文件仓"区域，建立快照。这个过程不做任何修改、删除，保证安全。
2. 再清洗：在收拢后的副本上做重复识别、格式修复。原始文件保留一份完整备份，万一清洗出问题可以回滚。
3. 后归档：清洗完成后，才把文件按规则移动到最终归档目录，建立"仓库终态"。

这样做的本质是把"整理"这件事从用户交互中解耦出来，让每一步都有独立的安全边界。

2.2 项目目录结构

我建议整个项目做成一个自包含目录，比如放在D:\ArchiveProject（如果你的C盘空间充裕也可以放C盘根目录）。目录结构如下：

D:\ArchiveProject\ ├── run.py # 一键入口 ├── config\ │ ├── settings.yaml # 全局配置 │ ├── scan_sources.txt # 要扫描的源目录列表 │ └── exclude_patterns.txt# 排除规则 ├── modules\ │ ├── __init__.py │ ├── precheck.py # 环境预检 │ ├── scanner.py # 全盘扫描器 │ ├── collector.py # 文件收集器 │ ├── dedup.py # 重复识别器 │ ├── cleaner.py # 清理执行器 │ ├── office_formatter.py # Office格式清洗 │ ├── reporter.py # 报告生成器 │ └── utils.py # 通用工具 ├── workspace\ │ ├── staging\ # 暂存区（收拢后的原始副本） │ ├── archive\ # 归档仓库（最终状态） │ ├── quarantine\ # 隔离区（待删除文件暂存） │ ├── logs\ # 运行日志 │ └── reports\ # 报告输出 ├── backup\ │ └── manifest_backups\ # 清单备份（可回滚依据） └── requirements.txt

这个目录设计的核心思想是：配置、代码、数据、日志、备份彻底分离。以后任何时刻你想知道"当时处理了什么"，只需要看logs和reports两个目录。

2.3 配置管理：宁可配置复杂，不可逻辑复杂

我强烈建议用 YAML 做配置。原因很简单：百万级文件的处理策略调整，绝对不能靠改代码，必须靠改配置。你可能会在调试过程中反复调整源目录、排除规则、去重阈值，如果这些都写死在代码里，每次都要改代码、重启程序，效率太低。

settings.yaml的核心配置项：

# config/settings.yaml project: name: "ArchiveProject" version: "1.0.0" paths: workspace: "D:/ArchiveProject/workspace" staging: "workspace/staging" archive: "workspace/archive" quarantine: "workspace/quarantine" logs: "workspace/logs" reports: "workspace/reports" scan: sources: - "D:/Documents" - "D:/Downloads" - "C:/Users/你的用户名/Desktop" exclude_dirs: - "D:/ArchiveProject" - "$RECYCLE.BIN" - "System Volume Information" exclude_exts: - ".tmp" - ".lnk" - ".ini" include_exts: # 空则全部包含 - ".doc" - ".docx" - ".xls" - ".xlsx" - ".ppt" - ".pptx" - ".pdf" dedup: algorithm: "murmur3" # 第一层快速哈希 strong_hash: "sha256" # 第二层强哈希 chunk_size: 1048576 # 1MB 分块读取 parallel_workers: 8 # 并行进程数 near_duplicate_threshold: 0.95 # 近重复相似度阈值 cleanup: use_recycle_bin: true # 优先使用回收站 transaction_batch: 500 # 每批次删除文件数 dry_run: true # 默认演练模式 office: enabled_formats: ["docx", "xlsx", "pptx", "pdf"] embed_fonts: true update_fields: true fix_page_numbers: true timeout_seconds: 120 # 单文档超时 max_concurrent_instances: 1 # COM实例并发数（必须为1） report: output_formats: ["markdown", "csv"] include_duplicate_report: true include_cleanup_report: true

配置里特别要注意两个点：

• dedup.parallel_workers：8个并行进程对100万文件做哈希计算，速度提升很明显，但要注意不要超过CPU线程数。
• office.max_concurrent_instances：Office COM 接口不允许并发，必须串行调用，设置了并发反而会引发崩溃。这一点后面会详细解释。

3. 核心功能一：超大批量文件迁移与自动整理归档

3.1 扫描策略：不遍历目录树，而是用增量快照

百万文件级别的扫描，第一反应是递归os.walk()，但这样做有几个问题：速度慢、内存消耗大、重复扫描浪费时间。我建议采用增量快照 + 索引文件的方式。

具体做法是：

1. 第一次扫描时，遍历所有源目录，生成一个完整的文件清单（包含路径、大小、修改时间、哈希值），保存到logs/file_index.json。
2. 后续扫描时，先读取上次的索引文件，只扫描"变化的部分"——通过对比目录修改时间mtime来判断哪些目录需要重新扫描。
3. 扫描结果与旧索引合并，生成新索引。

核心伪代码：

# modules/scanner.py import os import json from hashlib import sha256 def scan_directory(root_path, index_path): # 读取旧索引 old_index = load_json(index_path) if os.path.exists(index_path) else {} new_index = {} for dirpath, dirnames, filenames in os.walk(root_path): # 跳过排除目录 dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS] for fname in filenames: fpath = os.path.join(dirpath, fname) try: stat = os.stat(fpath) rel_path = os.path.relpath(fpath, root_path) # 如果旧索引中该文件大小和mtime一致，则复用哈希值 if rel_path in old_index: old_entry = old_index[rel_path] if old_entry['size'] == stat.st_size and old_entry['mtime'] == stat.st_mtime: new_index[rel_path] = old_entry continue new_index[rel_path] = { 'path': fpath, 'size': stat.st_size, 'mtime': stat.st_mtime, 'hash': quick_hash(fpath), } except (PermissionError, FileNotFoundError): continue save_json(index_path, new_index) return new_index

这里有一个关键优化：mtime + size 不变的文件，直接复用哈希。在重复扫描场景下，这意味着只看一眼目录就能跳过大量文件，不用重新计算哈希。

3.2 归档规则：按类型 + 年级 + 日期三级分流

归档不能只按扩展名分，那样会造成大量碎片。我建议按类型/年级/月份三层结构归档：

archive\ ├── 01_Office文档\ │ ├── 高三年级\ │ │ ├── 2024-01\ │ │ │ ├── 期末数学试卷.docx │ │ │ └── 语文作文素材.xlsx │ │ └── 2024-02\ │ ├── 高二年级\ │ └── 高一年级\ ├── 02_PDF文档\ ├── 03_图片素材\ └── 04_其他\

这个规则的优势是：按年级归类符合你的使用习惯，按月份归档保证时间维度的可追溯性。某个年级的文件不会无限堆积，而是按月切分，后期查文件时路径容易记忆。

归档时要注意保留原文件的元数据（创建时间、修改时间），否则特殊格式（如文档属性里的作者、创建日期）会丢失。Python 里可以用shutil.copy2()保留元数据，也可以用下面的方式：

# modules/collector.py import shutil import os def archive_file(src_path, target_root, classification): """将文件复制到归档目录，保留元数据""" # 计算目标路径 target_dir = os.path.join(target_root, classification) os.makedirs(target_dir, exist_ok=True) # 目标文件名冲突处理：追加序号 target_path = os.path.join(target_dir, os.path.basename(src_path)) counter = 1 while os.path.exists(target_path): stem, ext = os.path.splitext(os.path.basename(src_path)) target_path = os.path.join(target_dir, f"{stem}_{counter}{ext}") counter += 1 # 复制并保留元数据 shutil.copy2(src_path, target_path) return target_path

3.3 迁移中的安全策略：复制优先，移动最后

在整体策略里，我已经强调"复制优先"。在具体实现上，我建议分三步：

1. 演练模式（dry-run）：只扫描、只生成清单，不实际复制任何文件。
2. 复制模式：把源文件复制到 staging 区域，校验文件大小和哈希一致后，标记为"已收集"。
3. 移动模式（可选）：确认 staging 中的文件完整无误后，再删除源文件（或移入回收站）。

这样做的好处是：即使中途断电、磁盘故障、脚本崩溃，最坏情况下只是 staging 里多了一些半成品，源文件毫发无损。

4. 核心功能二：超大批量重复文件识别与清理

4.1 多级哈希去重：从快到准，分三关

百万级文件的重复识别，如果上来就对每个文件做 SHA-256 哈希，速度虽然可以接受，但仍然有优化空间。我建议采用三级筛选：

第一关：文件大小过滤。大小完全不同的文件不可能重复（这不是绝对的，但极大概率不重复），这一层用字典按size分组即可，只是 O(n) 操作，开销极小。

第二关：快速哈希（murmur3）。对大小相同的文件，计算一个更快、但不具备强碰撞安全性的哈希（比如mmh3），把哈希值相同的文件视为"疑似重复"。

第三关：强哈希（SHA-256）。对通过快速哈希聚类的文件，再做 SHA-256 强校验，完全一致则为精确重复。

用一句话概括：大小过滤是粗筛，快速哈希是重点筛，SHA-256是定案。

伪代码：

# modules/dedup.py import os from collections import defaultdict import mmh3 def quick_hash(filepath): """murmur3快速哈希，计算整个文件""" h = mmh3.hash_bytes(open(filepath, 'rb').read()) return h def strong_hash(filepath): """SHA-256强哈希""" import hashlib sha = hashlib.sha256() with open(filepath, 'rb') as f: for block in iter(lambda: f.read(1 * 1024 * 1024), b''): sha.update(block) return sha.hexdigest() def find_duplicates(file_index): # 第一关：按大小分组 by_size = defaultdict(list) for rel_path, entry in file_index.items(): by_size[entry['size']].append(rel_path) # 只对大小相同的组进行处理 size_groups = {k: v for k, v in by_size.items() if len(v) > 1 and k > 0} # 第二关：按快速哈希分组 by_quick = defaultdict(list) for group in size_groups.values(): for rel_path in group: qh = quick_hash(file_index[rel_path]['path']) by_quick[qh].append(rel_path) # 第三关：按强哈希确认 duplicates = {} for qh, group in by_quick.items(): if len(group) < 2: continue by_strong = defaultdict(list) for rel_path in group: sh = strong_hash(file_index[rel_path]['path']) by_strong[sh].append(rel_path) for sh, final_group in by_strong.items(): if len(final_group) > 1: duplicates[sh] = final_group return duplicates

4.2 近重复检测：内容相似的文件

除了完全相同的重复文件，你还会遇到"内容相似但略有差异"的文件（比如同一份文档的 v1 和 v2 版本）。这一层不是必选功能，但建议做。

近重复检测的常见思路是使用感知哈希（pHash）——先将文件转换成某种标准化表示（图片转缩略图、文本提取关键词），然后计算感知哈希，再比较汉明距离。但要注意：对办公文档做近重复检测，计算成本较高，100万级文件全部做相似度计算会很耗时间。

我建议只对以下两类做近重复检测：

• 按文件名相似度聚类（基于编辑距离或Jaccard相似度）
• 按文件大小相近聚类（差距在1KB以内）

然后人工确认是否真的需要保留多个版本。这一个功能不要全自动，因为"近重复"本质上是模糊概念，机器判断会有误判风险。

4.3 清理策略：回收站 + 事务批处理

一旦确定了重复文件，如何处理才是关键。

我强烈建议：任何删除操作，一律先移动到一个专门的"隔离区"目录，而不是直接删除。隔离区相当于你的"后悔药"，处理完一批后，等确认无误再清空隔离区。

具体流程：

1. 在 staging 区域中，对每个重复组，选出"保留文件"（通常是路径最短、文件名最规范、日期最新的那个）。
2. 其余文件移动到quarantine目录，保留元数据，文件名追加标记[DUPLICATE]。
3. 生成清理清单，记录原路径、隔离路径、判定原因。
4. 每一批移动 500 个文件后暂停，记录日志，方便中途介入。
5. 全部处理完后，由人工确认隔离区内容，再彻底清空。

有一个细节值得注意：清理隔离区时，不要用shutil.rmtree直接删目录，因为文件量太大时容易出问题。推荐用批量删除 + 错误重试机制，或者干脆把隔离区拖进系统回收站，给系统自己去处理。

5. 核心功能三：Office 文档批量格式清洗

5.1 格式错乱的根因：为什么"自己打开正常，发出去就乱"

这是整个项目里技术含量最高、坑最多的一环。你需要先理解Office文档格式错乱的本质原因，才能对症下药。

用通俗的话讲，Office 文档（尤其是 docx、xlsx、pptx）本质上是一个ZIP 压缩包，里面装着 XML 文件。XML 里描述的是"逻辑结构"（段落、字体、单元格、样式等），但渲染出来的样子依赖本机的环境。

最常见的格式错乱原因：

• 字体缺失：文档里指定了某字体，但接收方电脑上没有。Office 会自行替换成默认字体，导致排版错乱。
• 页码域未更新：Word 的页码、目录是"域（Field）"，需要更新后才会显示正确的页码。如果文档在导出时没有更新域，打开时页码可能显示为 0 或错误。
• 默认打印机影响分页：Word 的分页取决于"当前打印机"的纸张大小和页边距。本机默认打印机是 A4，接收方默认打印机可能是 Letter，分页就会变。
• 页眉页脚样式漂移：不同节（Section）的页眉页脚设置不同，复制粘贴时容易丢失样式关联。
• 宏与嵌入对象：文档中嵌入了 OLE 对象、宏代码，打开时触发安全警告，甚至导致布局错乱。

5.2 清洗整体方案：Office COM 强制重存

解决上述问题的最有效手段就是让 Office 自己打开文档，重新设置关键属性，然后用固定的规范设置重新另存。这有点像"用Word重新排版一遍"。

我推荐的清洗流程分四步：

1. 打开文档：使用 Office COM 接口打开。
2. 设置规范：设置字体嵌入、更新所有域、设置页面尺寸为标准 A4、设置页边距标准值。
3. 强制重存：SaveAs为同格式（docx→docx），或者转换为标准化格式（统一转 docx 或 PDF）。
4. 关闭文档：释放 COM 对象，处理异常。

以下是 Word 的清洗函数示例：

# modules/office_formatter.py import win32com.client import os import pythoncom def clean_word_document(src_path, dst_path=None, config=None): """清洗单个Word文档""" pythoncom.CoInitialize() word = win32com.client.DispatchEx("Word.Application") word.Visible = False word.DisplayAlerts = 0 # 禁止弹窗 try: doc = word.Documents.Open( src_path, ReadOnly=False, AddToRecentFiles=False, Visible=False, ) # 1. 更新所有域（页码、目录等） doc.Fields.Update() # 2. 设置页面尺寸为标准A4 for section in doc.Sections: section.PageSetup.PaperSize = 7 # 7 = wdPaperA4 section.PageSetup.TopMargin = 2.5 * 72 / 2.54 # 约2.5cm section.PageSetup.BottomMargin = 2.5 * 72 / 2.54 section.PageSetup.LeftMargin = 3 * 72 / 2.54 section.PageSetup.RightMargin = 3 * 72 / 2.54 # 3. 嵌入字体 if config and config.get('embed_fonts', True): doc.FontPreferences.EmbedTrueTypeFonts = True doc.FontPreferences.SaveSubsetFonts = True # 4. 另存为 if dst_path is None: dst_path = src_path doc.SaveAs(dst_path, FileFormat=16) # 16 = wdFormatDocumentDefault (docx) doc.Close(SaveChanges=False) except Exception as e: print(f"Error processing {src_path}: {e}") raise finally: word.Quit() pythoncom.CoUninitialize()

注意几个关键点：

• DispatchEx而不是Dispatch：DispatchEx会创建独立的 Word 实例，避免与用户已打开的Word实例冲突。
• DisplayAlerts = 0：关闭所有弹窗。
• AddToRecentFiles=False：防止打开文件污染"最近使用列表"。

5.3 COM 调用崩溃与卡死的应对预案

这是你的标题专门提到要解决的问题，也是实际执行时最恶心的坑。

大量调用 Office COM 可能触发几类问题：

问题一：Word 弹出宏/权限/恢复对话框

原因：Word 检测到文件来源不可信（网络位置、宏代码），会弹出"安全警告"或"文件恢复"窗格。虽然设了DisplayAlerts=0，但某些安全提示仍然会弹。

应对方案：

• 在word.Options.ConfirmConversions = False、word.DisplayAlerts = 0的基础上，还需要设置word.AutomationSecurity = 3（msoAutomationSecurityForceDisable），强制禁用宏。
• 在注册表中关闭 Word 的"受保护视图"。打开注册表，定位到：HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Word\Security创建 DWORD 值ProtectedViewSettings，设为0。这一步需要谨慎，只针对你自己本机的账号。

问题二：文档恢复窗格堆积

原因：Word 上次崩溃后，"文档恢复"窗格保留了很多待恢复文档，下次启动时会自动弹出。

应对方案：

• 启动 Word 后，主动关闭恢复任务窗格：word.Documents.Open后调用word.Documents.Close可能不彻底。建议在 COM 初始化后，先主动清空%APPDATA%\Microsoft\Word\下的.asd文件。
• 每次处理完毕后，调用word.Application.Quit()，而不是word.Documents.Close()，确保实例彻底退出。

问题三：单个文档超时卡死

应对方案：在代码层面加超时控制。Python 操作 COM 是同步阻塞的，如果 Word 卡住了，你的脚本会一直卡在那里。解决办法是使用子进程 + 超时 kill：

import subprocess import multiprocessing def clean_word_with_timeout(src, dst, timeout=120): ctx = multiprocessing.get_context('spawn') q = ctx.Queue() p = ctx.Process(target=clean_word_document, args=(src, dst, q)) p.start() p.join(timeout) if p.is_alive(): # 超时，强制kill p.terminate() p.join() return False, "Timeout" return True, q.get()

问题四：COM 对象不释放导致内存爆炸

应对方案：Python 中对 COM 对象引用必须显式释放。很多教程让你用word.Quit()，但实际上word对象如果是 Python 变量，Quit后可能还留有 COM 引用。需要在finally块里加word = None、doc = None，并调pythoncom.CoUninitialize()。

5.4 Excel 与 PowerPoint 的清洗要点

Excel 清洗的重点是：重新计算所有公式（wb.Calculate()）、清除外部链接（BreakLink）、将图表数据源设为本地。

# 启动Excel COM excel = win32com.client.DispatchEx("Excel.Application") excel.Visible = False excel.DisplayAlerts = False wb = excel.Workbooks.Open(src_path, UpdateLinks=0) # 重算所有公式 wb.Calculate() # 断开外部链接 for link in wb.LinkSources(1) or []: wb.BreakLink(link, 1) wb.SaveAs(dst_path, FileFormat=51) # 51 = xlsx wb.Close(False)

PowerPoint 清洗的重点是：统一字体、处理嵌入对象、规范幻灯片尺寸。

ppt = win32com.client.DispatchEx("PowerPoint.Application") pres = ppt.Presentations.Open(src_path, ReadOnly=False, WithWindow=False) # 统一字体 for slides in pres.Slides: for shape in slides.Shapes: if shape.HasTextFrame: for paragraph in shape.TextFrame.TextRange.Paragraphs: paragraph.Font.Name = "微软雅黑" # 设置幻灯片尺寸（widescreen） pres.PageSetup.SlideWidth = 13.333 * 72 pres.PageSetup.SlideHeight = 7.5 * 72 pres.SaveAs(dst_path, 24) # 24 = ppSaveAsOpenXMLPresentation pres.Close()

5.5 PDF 的清洗思路

PDF 的格式清洗比 Office 简单很多，因为 PDF 本身就是"显示即终态"的格式。但如果 PDF 是从 Office 导出的，可能仍然存在字体嵌入不全的问题。这里有两种思路：

• 使用 Adobe/Direct PDF 打印机重新打印：思路是用某个虚拟 PDF 打印机重新打印一遍，强制所有字体嵌入。这个方案稳定性高，但需要装虚拟打印机驱动。
• 使用开源库改造：用pypdf或reportlab做字体子集嵌入。这个方案可控性高，但处理效果有限。
• 推荐方案：既然你已经用 Office COM 把 Word/Excel/PPT 统一清洗重存了，PDF 直接由清洗后的 Office 文件重新导出，一步到位。如果源文件本身是 PDF，且没有格式问题，只做归档即可。

考虑到你的时间有限，我建议把 PDF 清洗优先级放到最后，只处理"由Office导出的PDF"这个场景。

6. 分阶段规划与时间表

你要求必须在端午节假期（假设7月31日）前完成。基于"每天可投入3~4小时"的假设，我给你排一个可执行的时间表：

日期 任务 交付物 ----------------------------------------------- 第1天 环境搭建 + 项目骨架 + 预检脚本 可运行的 run.py 骨架 第2天 扫描器 + 收集器 + 归档规则 能扫描、能按规则归档 第3天 去重模块（多级哈希） 输出重复文件清单 第4天 清理模块（隔离区 + 回滚） 能安全隔离重复文件 第5天 Office COM 格式清洗（Word优先） 能批量清洗Word 第6天 Excel/PPT/PDF 清洗 + 报告模块 全格式清洗 + 报告 第7天（7.30） 全流程联调 + 演练模式跑通 一键运行闭环 第8天（7.31） 线上执行，完成最终整理 全部文件归档 + 报告

如果你的时间更紧张，可以做减法：

• 必保核心：收集归档 + 精确重复识别清理 + Word格式清洗。
• 可延后：Excel/PPT清洗、近重复检测、PDF重新导出。
• 建议砍掉：如果你对Excel/PPT的格式输出要求不高，先不处理，等核心流程跑通后再增量清洗。

7. 一键运行闭环与交互式命令设计

7.1 主入口：run.py 设计

我希望你最终交付的是一个"跑一次脚本、看一次报告"的产品，而不是一个需要你手动分步执行的工具。所以run.py的设计非常重要。

主流程：

# run.py import sys from modules.precheck import run_precheck from modules.scanner import scan_sources from modules.collector import archive_all_staged from modules.dedup import find_duplicates from modules.cleaner import quarantine_duplicates from modules.office_formatter import batch_format_clean from modules.reporter import generate_report import config.settings as cfg def main(): # 0. 预检 if not run_precheck(cfg): print("[FAIL] 预检未通过，终止执行") sys.exit(1) if cfg.get("dry_run"): print("[DRY-RUN] 演练模式，只生成清单不执行") # 1. 扫描 file_index = scan_sources(cfg) # 2. 收集归档 staging_index = archive_all_staged(file_index, cfg) # 3. 重复识别 dup_groups = find_duplicates(staging_index, cfg) # 4. 清理（隔离） quarantine_duplicates(dup_groups, cfg) # 5. 格式清洗 batch_format_clean(staging_index, cfg) # 6. 最终归档 finalize_archive(staging_index, cfg) # 7. 报告 generate_report(cfg) print("[DONE] 所有任务已完成，请查看 reports 目录") if __name__ == "__main__": main()

7.2 交互式命令设计

虽然目标是"一键"，但预处理和中间确认环节仍然建议保留交互。我设计了三个命令级别：

• python run.py --dry-run：演练模式，跑一遍所有流程，但所有写操作都不执行。
• python run.py --stage collect：只执行到收集阶段。
• python run.py --stage dedup：执行到去重阶段。
• python run.py --stage clean：执行到格式清洗阶段。
• python run.py：全自动执行到报告输出。

7.3 性能优化建议

百万级文件规模下，性能优化是必修课：

1. 并行化：扫描、哈希计算都可以用concurrent.futures.ProcessPoolExecutor，但注意要控制进程数（你的CPU是6核12线程，建议8进程）。
2. 内存管理：不要一次性把所有文件信息加载到内存。file_index中保存的是"路径、大小、mtime、hash"，如果文件非常多，可以考虑用 SQLite 存储而不是 JSON。
3. 批量化：复制/移动/清洗操作，一次性处理一批（如500个文件），批与批之间写 checkpoint，崩溃后可以断点续跑。
4. 缓存复用：mtime 不变的哈希复用（前面扫描部分已经提到）。

关于内存，我再强调一点：100万文件的全路径字符串，在 Python 里大约会占用几百MB内存，你的32GB不用担心，但如果是8GB小内存机器就要谨慎了。建议用__slots__或者 SQLite 存储。

7.4 安全与回滚方案

最后重申安全底线。所有步骤必须遵守这几条铁律：

• 任何写操作都要可回滚：删除进隔离区；覆盖前先备份原始文件；重命名记录在案。
• 每个阶段输出一个 manifest（清单）：JSON格式，记录本阶段输入、输出、每个操作的动作。
• 全局事务计数：每处理完一个文件就写一个状态，崩溃后重新运行时只处理未完成任务。
• 全流程演练先行：上线前用--dry-run跑两遍，确认行为符合预期再执行真操作。

8. 常见问题与避坑技巧

我在实际接触这类项目时，踩过不少坑，列几个高频问题：

问：Word COM 打开文档后，文档里出现"兼容模式"，SaveAs 后格式仍乱？

答：这是"兼容模式"的典型问题。文档打开时，Word 检测到文档格式是旧版（.doc），会进入兼容模式，导致新版样式不生效。解决办法是先把 .doc 统一转换为 .docx（FileFormat=16），再对该 docx 做二次清洗。

问：Excel 打开时弹出"外部链接"警告，导致脚本卡死？

答：设置DisplayAlerts = False并不能完全取消外部链接警告。需要显式断开链接。用wb.BreakLink处理。如果不想改原文件，可以用xlUpdateLinksNever参数（值为3）打开文档。

问：去重时发现大量文件是 "快捷方式" 或 ".lnk"，要不要清理？

答：清理时要格外小心。.lnk文件里记录的是目标路径，如果原始路径失效，快捷方式就是死文件；如果路径有效，删除可能导致桌面图标失效。建议在配置里单独给.lnk一个分类，不要和普通文件混在一起。

问：扫描时遇到"无法访问"的目录（权限不足）怎么办？

答：你有 WSL2 环境，可以用 WSL2 下的 Linux 文件系统视角来规避部分 Windows 权限问题（NTFS 的 ACL 限制较复杂）。但要注意：WSL2 只能做文件操作，不能做 COM 格式清洗。建议在 Windows 主系统下用管理员权限运行 Python，并设置scan.exclude_dirs排除那些临时目录（比如$RECYCLE.BIN）。

问：100万个文件怎么存？一个目录下文件多了会不会访问变慢？

答：会变慢。NTFS 单目录下上万文件后，资源管理器打开就卡。所以归档规则一定要细分。建议归档目录按类型/年级/月份三级划分，每个子目录文件数控制在 500 以内。另外，文件命名尽量保留有意义的前缀，避免重名冲突时追加_1导致后期难认。

9. 最后的经验之谈

我在构建这套方案时，核心考虑是"机器能干的事，绝不让人手工做；但机器做完的事，一定要让人能复查**"。所以整个流程被拆成了"扫描→收集→去重→清理→清洗→归档→报告"七步，每一步都有独立日志、独立清单，关键时刻还有人工确认点。

坦白说，百万级文件规模的整理，任何自动化方案都不可能做到 100% 完美。你一定会遇到一些"机器判断不了"的边界情况（比如两个 docx 内容完全相同但文件名不同、某个 Word 文档是学生交来的特殊模板）。所以方案里我特意保留了"人工介入"的口子——出发前先跑演练模式，看看报告里的分类结果是否合理，再放行真实执行。

最后再给你一个黄金建议：先把整个流程在一个小规模数据集上跑通（比如先在某个几百MB的测试目录里做全链路演练），再去碰 300GB 的真实数据。一旦你的全链路脚本能在小规模数据上输出一份"分类合理、去重准确、格式完好"的报告，你就有信心让它在真实数据上跑。

动手吧，别等。