最近在整理内部归档资料时被一个老问题折腾得够呛目录里散着上千个素材文件命名方式五花八门有叫“aaa.txt”的有叫“最终版_2023_改改.doc”的还有一堆图片只有IMG_0001这种流水号。想从中找出哪些文件对应什么主题只能靠人工一个个打开看。为了解决这个重复性劳动我基于模拟项目X的归档背景在内部写了一个不起眼的小工具代号叫rea。rea是“resource extraction assistant”的缩写说白了就是“资源抽取助手”。听起来很高大上实际情况是它的核心功能只有三条扫描指定目录的所有文件按规则抽取文件的关键信息最后汇总成一张结构化表格。但这三条真正跑稳之后一个原本要花两三天的活确实被压到了几分钟。这篇文章不是讲某个成熟框架的用法而是把一个内部小工具从想法、设计、实现到踩坑的全过程做一次复盘希望对做自动化归档、批量文件处理的读者有点帮助。1. “rea”最初要解决的不只是文件乱而是“没有索引”1.1 手动整理资源库的真正痛点当时我在维护模拟项目X的素材目录里面大概有3200多个文件分散在几十个子文件夹里。类型有纯文本、Word文档、PDF、图片、压缩包来源不太统一命名规范更是各搞各的。比如一个关于“用户调研报告”的文件夹里可能既有“调研报告.docx”又有“final_report_version2.pdf”还有一串无意义编号的图片附件。如果只是“文件乱”倒还好说。真正耗时的其实不是整理文件名而是“没有索引”。你想知道某个主题下有哪些素材只能靠人工一层层翻目录你想统计原始文件里都包含哪些日期、负责人、版本状态也得一个个打开文件去找。这活儿做一次觉得麻烦做十次就忍不住想写脚本了。我第一次做这种统计时整整花了三天。先把所有文件按扩展名筛了一遍再逐个打开看内容把关键信息手动填进表格。填的过程中还经常发现同一个文件在多个目录下出现了副本统计口径乱成一团。第二周又来了一轮更新我一想再这么搞下去精力全耗在复制粘贴上了这才决定动手写rea。1.2 目标很克制只做索引不改文件不做语义理解rea最初的定位非常明确不修改任何原文件不去理解文件的业务语义只负责把“能自动读到的信息”快速抽出来形成一份可检索、可筛选的索引。例如文件名、扩展名、路径、大小、修改时间、文本前几行的标题关键字、图片尺寸和拍摄时间等。这个“克制”很关键。我见过不少自动化工具最后烂尾不是功能不够而是想做的太多。有的工具非要做全文分词有的想自动判断“这段文字讲的是哪个活动”结果变成维护成本极高的半成品。rea刻意不碰这些它只做字段级抽取拿到关键信息后把判断工作留给人来完成。这样反而让工具变得非常稳定因为“抽取规则”是可以枚举的而“语义理解”永远会碰到边界情况。所以你在设计类似工具时第一件事不是选技术栈而是把边界划清楚做什么、不做什么、哪些交给后续人工处理。划清楚这些后面才不会不断被需求带偏。2. rea的主干设计按“扫描—抽取—合并”三条流水线来拆2.1 扫描跨平台的目录遍历与格式分类扫描阶段我用的是Python的pathlib和os.walk结合。为什么坚持用pathlib因为跨平台的路径拼接更干净不会出现Windows下斜杠混用、字符串转义之类的老问题。遍历所有文件后按扩展名归类成文本类、表格类、图片类、可执行文件类、归档类等为后面的抽取阶段做准备。这里有个容易犯的错很多人直接用Path.rglob(*)一条调用走到底遇到没有权限访问的深层次目录时直接抛异常整个扫描就断了。实际处理中应该用os.walk并显式捕获PermissionError对无法访问的目录做好标记让扫描继续跑完最后在报告里列出“未访问目录”给用户看。import os from pathlib import Path def scan_dir(root: Path): for current_dir, sub_dirs, files in os.walk(root): try: for name in files: full_path Path(current_dir) / name if not full_path.is_file(): continue stat full_path.stat() yield { path: str(full_path), rel: str(full_path.relative_to(root)), ext: full_path.suffix.lower(), size: stat.st_size, mtime: stat.st_mtime, } except PermissionError: print(f[skip] no permission: {current_dir})目录结构在这一步会输出成一个“文件清单”一次性拿到相对路径、扩展名、大小和修改时间。这层不追求花哨功能但输出质量直接影响后面的抽取效率。2.2 抽取文件名正则、文本关键字、图片EXIF三类规则抽取是rea的核心也是最容易失控的地方。我从一开始就没有做“万能解析”而是设计了三种规则的组合遇到什么形态的文件就套用什么规则。类型一文件名正则。像“最终版_2023_改改.doc”这种文件可以用正则抽出“日期2023”“标注最终版”等关键信息。但正则面对“IMG_0001”就没意义所以抽取采取“匹配上就取匹配不上就保留原名并标记为未识别”。类型二文本关键字。对文本文件和可解析的Office文档读取前N行用关键词表去定位“标题”“日期”“版本”“主题”等常见字段。这里不追求复杂解析很多业务文件的前几行其实已经写清了最核心的信息。如果前20行还找不到说明这个文件的格式本身就不适合做自动抽取放到待人工处理列表里就行。类型三图片元数据。用Pillow读取图片的EXIF信息提取拍摄时间、相机型号、GPS位置等。这个对归档照片素材特别有用很多项目资料里混杂着现场照片自动拿到拍摄时间能省下大量人工核对成本。这三类规则用配置文件驱动而不是把规则写死在代码里。这个设计后面会单独展开但先记住一个结论凡是可能会变的判别逻辑都尽量外置。2.3 合并去重策略与输出格式的选择抽取完每个文件得到一条记录之后要合并成统一格式。合并之前必须先做去重否则一份索引里出现大量重复文件后续统计全是错的。我用MD5哈希识别完全相同的文件。重名的、内容一样的文件在索引里保留所有路径但增加一个duplicate_of字段指向最先出现的文件。这个决策让后面清理重复素材时非常方便只需要对duplicate_of列表做一次筛选。输出格式我选了CSV和JSON。为什么不用Excel因为Excel需要额外依赖库而且CSV可以被后续脚本直接处理、被任意文本工具读取。当记录里包含换行符和逗号时要注意用csv模块的QUOTE_ALL策略否则表格列会错位。JSON格式则用来给程序对接方便后续接数据库或可视化看板。合并操作的另一个重点是“冲突检测”。比如两个文件都抽出了“date”字段但值一个写“2023/05/01”另一个写“2023年5月1日”rea不会强行统一格式而是同时保留两个原始值并加一个format_conflict标记。索引的价值首先是记录事实而不是盲目地把事实清洗成统一的形态。3. 跑通之后才开始“真正的坑”三个实测问题的定位过程3.1 编码识别失败导致中文乱码不迷信自动检测第一次跑rea时大量txt文件抽出来的中文全是乱码。我第一反应是抽取逻辑写错了但单独打开文件看编辑器里显示完全正常。之后我打印了文件前100字节才发现文件实际是GBK编码而我统一用UTF-8去读自然全变乱码。当时我引入了一个编码检测库来做自动判断但这个库在短文本上的误判率并不低。尤其是只有几行的文件它会把GBK内容判成别的编码导致乱码依旧。最终我把读取策略改成优先级明确的分级尝试先按UTF-8-SIG试再UTF-8再GBK最后用GB18030兜底而不是完全依赖自动检测。def read_text_head(path: str, head_bytes: int 2048): with open(path, rb) as f: raw f.read(head_bytes) for enc in (utf-8-sig, utf-8, gbk, gb18030): try: return raw.decode(enc), enc except UnicodeDecodeError: continue return raw.decode(utf-8, errorsreplace), unknown这个改动让乱码率从大概15%降到接近零。事后复盘我发现自动检测编码并不是万能的短文本、混合编码、文件头被截断这些情况都会让检测失效。与其追求“自动识别”不如配合业务场景里最常见的编码列表做顺序回退。如果你的资源库主要来自中文环境GB18030兜底几乎是必须的。3.2 大文件读入内存导致假死索引工具不需要读全文有一段时间rea处理到某个200MB的XML文件时进程直接卡住CPU飙升但迟迟没有输出。根因很明确抽取文本信息时用了Path.read_text()一次性把整个文件读进内存再去做关键字搜索。文件一大内存直接爆。排查过程不算复杂我在关键步骤前后加了耗时和内存打印很快就锁定了读取大文件的代码。解决方法是改成流式读取文本类文件只读头部和尾部若干KB用于抽取标题、日期、版本等字段正文超过阈值就只取片段不做全文加载。核心思路是“索引工具不需要理解全文只需要取得足够特征”。务必要注意当文件超过几百MB时即使用流式读取也可能因为文件被其他进程占用而出现IO异常。需要在抽取逻辑里把这类文件单独拎出来标记成“超大可执行文件跳过内容抽取”而不是让整个任务中断。3.3 长路径和中文路径问题路径拼接不能靠字符串硬拼有部分文件路径非常长Windows下访问时报“系统找不到指定的路径”。原因是Windows对路径有长度限制而归档目录往往嵌套很深文件名又很长。后来用\\?\前缀处理绝对路径并把rea的临时输出路径放到盘符根目录附近问题解决了。另外有些目录名带空格和中文如果我用手工拼接字符串的方式构造路径很容易出现转义错误。这也是从第一版起就坚持用pathlib的原因。类似问题不难但不实际跑一遍很难预料。比如文件夹叫“项目资料最终”括号是中文全角这段路径在命令行里复制粘贴没问题但通过字符串拼接时如果少了一个引号后面全乱套。这类问题的根子是路径本质上是二进制字节序列不是给人读的字符串。任何路径处理都应该交给标准库的Path对象而不是自己用/或\\去拼。4. 让rea活得更久的改造规则外置和回归验证4.1 把抽取规则从代码里拆出来工具才算真正成型第一版rea把所有抽取规则硬编码在脚本里。结果第二周拿到一批新格式文件发现又要改代码、重启脚本、测试。我意识到这种“一次性脚本”很难长期维护于是把规则抽到外部配置文件里脚本读取配置执行抽取。这样做的最大好处是非开发同事也可以通过改配置来适配新格式不需要等我改代码。这也让rea从一个“我自己的小工具”变成了“团队可以一起维护的小工具”。配置取代代码意味着改规则的试错成本大幅降低。原来改一次代码可能要重新走一遍环境搭建、依赖安装、语法检查现在改几行JSON重新跑一下就行。4.2 配置示例规则只做字段级定位不做业务判断下面是一个简化的配置结构集中展示文件名规则、文本关键字规则和图片元数据规则{ filename_rules: [ {name: date, pattern: (20\\d{2})}, {name: version, pattern: v(\\d)} ], text_rules: { head_lines: 20, keywords: { 标题: ^(标题|title)[:]*(.), 日期: ^(日期|date)[:]*(.) } }, image_rules: [exif_time, exif_model] }请注意配置里只描述“字段怎么提取”不包含“这个字段应该是什么语义”的判断。也就是说rea不会去猜“2023”到底是日期还是编号它只负责把匹配到的内容原样记录下来。真正需要判断时rea会把抽取结果中不确定的字段标记为needs_review让后续人工处理。4.3 固定样本集做回归避免修好一个格式、弄坏另一个格式修改规则时最怕“修好一种格式弄坏另一种格式”。我准备了一个固定的小样本库大约30个文件覆盖常见类型、边界情况、虚构的乱码文件。每次调整规则后先在这个样本库上跑一遍对比输出差异。具体做法是写一个对比脚本对两次输出的JSON做逐字段diff。只允许出现预期中的字段变化比如日期格式调整、新增版本号字段等。如果某个无关字段突然变了说明这次规则改动可能影响到了其他文件需要重新检查。这个回归机制相当重要。如果没有它我会陷入“这周适配了新格式下周发现旧格式抽出来的日期全变了”的循环。有了这个简单的防线规则修改才会变得越来越放心。5. 真正投入日常使用前值得做的几处性能和可靠性加固5.1 并行抽取IO密集型的活儿用多线程就够了rea第一版单线程扫描3000多个文件要几分钟主要耗时在文本字段抽取和哈希计算上。后来用ThreadPoolExecutor做并行抽取同样一批文件缩短到不到40秒。因为没有特别复杂的计算多线程就足够了不需要上多进程。有个小建议线程数量不要无脑开几十个否则磁盘IO会被拖垮速度反而下降。实测在我当时的机器上8个线程最稳。如果你的文件主要放在机械硬盘上线程数越大磁头寻道越频繁反而更慢如果是SSD可以稍微多开几个。from concurrent.futures import ThreadPoolExecutor def process_many(file_list, workers8): with ThreadPoolExecutor(max_workersworkers) as executor: results list(executor.map(process_one, file_list)) return results5.2 增量扫描靠mtime和size跳过没变化的文件后续我给rea加了“是否处理过”的判断记录每个文件的mtime和size如果两者都没变就跳过抽取直接从上次缓存里读取结果。这个改动让第二次跑整个资源库几乎秒开。为什么用mtime和size而不用哈希因为哈希计算本身就有IO成本每次全量哈希等于把文件全部读一遍失去了增量的意义。mtime和size虽然不能保证文件内容一定没变但对绝大多数归档场景来说够用了。如果实在需要严格校验可以对“mtime变化了但size没变”的少数文件做补充哈希而不是对所有文件都做。5.3 输出JSON Lines比CSV更适合程序对接CSV适合给人看JSON Lines适合给程序处理。我给rea增加了输出JSON Lines格式的能力每行一个JSON对象。原因是后续如果要把索引接入其他系统JSON Lines比CSV更好解析也不用担心字段中包含逗号或换行符导致错列。如果你还要做可视化看板JSON Lines可以直接被大多数数据处理工具读取不用二次转换。这条属于经验之谈了很多脚本只输出CSV短期看方便长期看反而多了一道转换工序。最后再分享一个从rea里沉淀下来的小技巧做批量文件处理时永远先跑小样本再跑全量。我第一次用它直接全量跑结果遇到一个畸形压缩包就中断了前面跑了一小时的进度全废。后来改成在临时目录放20个有代表性的文件先验证确认输出结构无误后再上全量配合增量扫描基本不会再出现“跑了一半需要重来”的情况。这个工具本身很简单但把边界划清楚、把规则外置、把回归验证补齐之后它就成了一个可以长期依赖的自动化底座。