文件夹层级拍平 - 免费把嵌套七八层的文件一次性提到一层，重名自动让位（其它工具）

这个工具解决什么问题

从网盘或群里下载的资料包，解压出来往往是这个样子：资料包\2024年\第三季度\会议纪要\原始附件\最终版\会议记录.pdf。想把这一堆文件统一放到一层里慢慢看，只能一层层点进去、Ctrl+X、再退回目标文件夹 Ctrl+V，来回几十次；更麻烦的是两个不同分支里有同名的「会议记录.pdf」，粘到第二份时系统弹出「要替换吗」，手快点错，前一份就没了。

• 原来的做法：一层层点进深层目录，全选、剪切，退回目标文件夹粘贴，遇到同名文件靠人眼判断要不要替换，重复几十次
• 用这个工具：选定源文件夹 → 看一眼预览表格（改过名的行会标红）→ 点一下「开始拍平」，所有文件落到同一层，重名自动加序号
• 省下来的：一个嵌套五六层、上百个文件的资料包，手工整理要十几分钟并且有覆盖风险；用这个工具大约十秒，且不可能覆盖任何已有文件

技术实现

工具用 Python 标准库写成，界面是 tkinter 窗体，运行时零第三方依赖，打包成一个 exe 双击即用。整体分两层：flatten_core.py 是纯逻辑（扫描、建计划、执行、撤销、导出清单），folder_flatten.py 只负责把结果画到界面上。这样拆的好处是逻辑可以脱离界面被自动化测试覆盖——tkinter 界面没法在无人值守环境里自动点按钮，但核心逻辑可以，114 项断言全部跑在真实文件系统上。

• 扫描用 os.walk 剪枝，而不是 Path.rglob：os.walk 允许在遍历时改写 dirnames[:] 把整棵子树剪掉：跳过隐藏目录时不会白跑一遍它下面的内容。隐藏判定同时看「点开头」和 Windows 文件属性位（st_file_attributes 里的 FILE_ATTRIBUTE_HIDDEN / FILE_ATTRIBUTE_SYSTEM），所以 desktop.ini、Thumbs.db 这类带系统属性的文件也能滤掉。
• 文件名清洗：让计划里的名字一定合法：拍平必然要给文件改名，名字不合法会在搬到一半时抛 OSError。sanitize_filename() 处理四件事：非法字符 <>:"/\|?* 与控制字符换成下划线；去掉结尾的点和空格（Windows 会静默丢弃它们，导致计划名与落盘名不一致、下一轮判重误判）；保留设备名 CON/PRN/AUX/NUL/COM1-9/LPT1-9 加前缀；超过 180 字符从中间截断并保留扩展名。
• 判重必须忽略大小写，而且跨文件累计：Windows 文件名不区分大小写，Report.pdf 与 report.pdf 看着是两个名字，落到 NTFS 上是同一个文件——第二个会把第一个悄悄覆盖。所以判重统一用 name.lower()，并且在两个环节各做一次：建计划时避让输出目录里已有的名字；真正落盘前再从输出目录实际内容重建一次名字集合，跨文件累计判重（而不是逐个文件单独判断），避免 item1 被改成「封面_2.png」而 item2 计划里叫「封面_2.PNG」这种撞车。
• 「绝不覆盖」的三道闸门：第一道在建计划：输出目录已有文件名全部先占位，计划里不会出现被占用的名字；第二道在执行：落盘前重新采集一次实际名字并跨文件判重；第三道在撤销搬回：原路径若已被占用，另起名字而不是覆盖。三道叠加的结果是不论走哪条路径，都不会写掉用户已有的文件。
• 界面线程模型：主线程只画，工作线程只算：tkinter 不是线程安全的，所以扫描和执行都在 daemon 线程里跑，通过 queue.Queue 单向发 status / progress / scanned / done / error 消息，主线程用 after(80) 定时取出来更新控件。大目录扫描时界面不假死、进度条正常走。「取消」只是一个布尔位，工作线程每个文件之前检查一次——取消不回滚已完成的部分，但记录照写，用户可整体撤销。
• 撤销只认记录，绝不通配删除：每次执行都在输出目录写一份「拍平记录.json」，只含「相对路径 → 新名字」。撤销时严格按这份记录逐条处理：复制模式删掉记录里列出的产物，移动模式按相对路径重建目录层级搬回去。全程不做 glob 或通配删除——撤销功能本身绝不能成为数据损失的风险点。

技术栈：Python 3.8+、tkinter 标准库（零第三方依赖）、os.walk 目录剪枝遍历、PyInstaller 单文件打包

已知局限：只处理文件，不处理文件夹本身（空文件夹在移动模式下会被清理，撤销时可重建路径但不会恢复原本就空的目录）；不解析压缩包，处理对象是已经解压好的目录树；预览会把整个计划一次性载入表格，十万级文件的大目录下内存占用会上升、扫描也需要等待，实际速度与内存占用视机器与磁盘而定。

操作教程

1. 选择要拍平的源文件夹
   点「源文件夹」右侧的「浏览…」，在弹出的目录对话框里选中那个装着嵌套资料的文件夹（不要手动输入路径）。
   预期结果：路径填进输入框，输出位置自动变成「源文件夹\_拍平结果」
2. 确认输出位置
   默认勾选了「输出到源文件夹下新建的『_拍平结果』里」，原始文件一份都不动。想放到别处就取消这个勾选，再点右侧「浏览…」另选一个目录。
   预期结果：「输出到」输入框显示最终的目标目录；默认勾选状态下该框是灰色锁定的
3. 设置处理方式与重名规则
   处理方式默认「复制」（源文件保持不动，最安全），需要把文件搬走就选「移动」（会顺带清理搬空的文件夹）。重名处理在下拉框里选：自动加序号（推荐）、加来源文件夹前缀、或直接跳过。
   预期结果：单选按钮与下拉框显示你选中的项
4. 点「扫描并预览」看一遍计划
   工具会遍历源文件夹（不含最上层文件，除非勾选对应选项），在表格里逐行列出「拍平后的文件名 / 大小 / 原位置 / 说明」。被改过名的行会用红色标出，说明列写明改名原因。
   预期结果：表格列出所有将被处理的文件，上方统计显示「共 N 个文件 · 来自 M 个子文件夹 · 最深 K 层 · 改名 X 个 · 跳过 Y 个」
5. 确认无误后点「开始拍平」
   会先弹一个确认框告诉你要复制还是移动多少个文件到哪里；确认后进度条开始走，状态栏实时显示正在处理第几个文件。中途想停可以点「取消」。
   预期结果：完成后弹出结果提示，输出目录里出现全部文件 + 拍平清单.csv + 拍平记录.json
6. 核对结果，不满意就点「撤销上次」
   用「打开输出目录」直接看结果，或用「导出清单 CSV」把对照表存到别处。如果发现选错了源目录或规则不合适，点「撤销上次」即可：复制模式会删掉这次生成的文件，移动模式会按原来的层级把文件搬回去。
   预期结果：撤销完成后弹出「撤销完成」，输出目录被清空并自动删除

源文件夹最上层的文件默认不处理——「拍平」针对的是被嵌套的那些。如果连最上层的一起要，在「处理选项」里勾上「连同源文件夹最上层的文件一起处理」。

常见问题

技术实现与后续维护

本工具由我们自行开发并持续维护，每次迭代都会先跑一遍核心逻辑回归测试再发布。下面说明它的技术构成与可扩展方向，方便你判断是否契合自己的场景。

技术构成：

• src/flatten_core.py —— 核心逻辑层：扫描 / 建计划 / 执行 / 撤销 / 导出清单，纯函数，可脱离界面独立测试
• src/folder_flatten.py —— tkinter 界面层：四步式窗体（选文件夹 / 设选项 / 预览 / 执行），通过消息队列与工作线程协作
• src/selftest.py —— 核心逻辑回归测试：在临时目录里搭真实嵌套结构，114 项断言覆盖全部写盘路径
• DOCS/开发文档.md —— 开发文档：工程结构、技术取舍、编译方式、扩展点与维护约定

运行环境：

Windows 10 / 11（64 位）。运行版是单个 exe，免安装、免配置，解压后双击即可使用；不需要安装 Python，也不需要任何运行库；程序不联网，所有处理都在本机完成。

可扩展方向：

• 扩展名白名单：只拍平指定类型的文件（比如只要图片），其余原样留在原处
• 按类型或修改日期分目录：拍平的同时分到「图片/文档/表格」这类子目录里
• 把上层目录名拼进文件名：例如生成 2024年_第三季度_会议记录.pdf，保留来源信息
• 批量处理多个源文件夹：一次选多个目录，合并拍平到同一个目标目录
• 拍平后生成带缩略图的 HTML 索引页，方便快速浏览整理结果

本工具免费提供使用，但不对外分发源码。如果你需要在本工具基础上做功能调整、对接内部系统或长期维护，可以联系我们做二次开发，源码与工程文档可在定制合作中一并交付。

使用说明与免责声明

• 本工具在本地运行，不联网、不上传任何数据到服务器。
• 涉及文件改写的功能，请在使用前备份原始文件。
• 软件完全免费，可自由使用与转发，请勿用于倒卖。
• 因误操作造成的数据问题请自行承担。

本工具会改动文件系统，虽然默认使用最安全的「复制」模式、且在任何情况下都不会覆盖已有文件，使用前仍建议对重要资料做好备份。移动模式下搬空的文件夹会被清理，撤销可以重建路径，但原本就是空的文件夹不会被恢复。