硬盘清理工具是系统维护里最高频的需求之一。临时文件清理、重复文件查找、大目录定位听起来很简单但一旦这类小工具被批量生成出来而且生成方式不是开发者从零手写的版本风险点就完全不同了。标题里说的“都不是人写的”并不是贬义它更像今天很多开发者的工作方式把需求描述给 AI 编程助手让它直接生成脚本。问题在于硬盘清理工具的本质是“找出文件并删除”删除一旦发生就很难回退。代码能不能跑是一回事代码删错了能不能兜底是另一回事。这篇文章会把“三连发”拆成三个最小场景临时文件清理器、重复文件检测器、Top 大目录扫描器。重点不是展示某个 AI 工具多好用而是回答三个问题这类代码初稿有哪些通病如何用工程手段补齐安全边界以及生成式代码要经过哪些审查才能进入真实环境。1. 先理解硬盘清理工具的代码为什么需要一套安全护栏很多人拿到磁盘快满的电脑第一反应就是搜“硬盘清理工具”。但一个真正可用的清理脚本并不是把“删文件”三个字翻译成代码那么简单。它本质上是一个由“枚举候选文件、判断是否可清理、执行移动或删除”组成三段式流程。三段式里的每一步都可能因为路径、权限、占用、后缀匹配宽度而产生不可逆后果。1.1 硬盘清理的底层操作并不复杂但不可逆从代码层面看硬盘清理主要做了三件事遍历目标目录找出可能的候选文件。对候选文件做规则过滤例如后缀、大小、修改时间、文件名关键字。对通过过滤的文件执行删除或归档操作。这里的核心矛盾是第二步过滤得再严格也无法百分之百模拟人的判断。后缀名为.tmp的文件大部分可以清理但可能有一个正在被某软件占用的临时文件.bak文件通常是备份但也可能承载着唯一一份配置历史用户手动指定--root /home/user后代码如果递归所有子目录就可能碰到不该碰的项目工程目录。删除操作天然不可逆。普通文件走回收站还能恢复很多脚本直接用os.remove物理删除后恢复只能依赖专业文件恢复工具成功率很不稳定。因此清理工具的第一条安全原则不是“删得快”而是“先别删”。一套稳妥的清理工具至少要包含候选清单、确认步骤、可恢复通道三部分。1.2 AI 生成代码适合做什么不适合直接做什么把需求交给 AI 后生成的结果通常语法正确、结构完整也基本能覆盖用户描述的功能。这很容易让人放松警惕。AI 比较擅长的是通用能力部分遍历目录的代码怎么写。计算文件哈希的代码怎么写。递归统计目录体积的代码怎么写。命令行参数解析怎么写。这些能力属于“常见套路”模型训练数据里见得足够多生成的代码可用性很高。不适合直接照搬的是包含副作用的部分哪些目录绝对不应该进入删除范围。符号链接是否会指向系统目录。备份目录放在哪里是否会再次被扫描到。文件被占用或权限不足时要不要中断整个脚本。如果提示词只写“清理临时文件删除超过 100MB 的文件”AI 通常会给出最简单直接的实现。这个实现能运行但不等于它理解了你真正想清理的范围。可以把 AI 生成的代码当成“初稿资产”而不能当成“生产最终品”。初稿负责把骨架搭出来人负责补上不可逆操作的兜底逻辑。1.3 三个工具的目标、输入与验收标准为了让“三连发”足够具体下面统一成三个命令行子命令。工具输入输出安全底线clean-temp根目录、后缀白名单、大小下限待清理文件清单或移动结果默认 dry-run不直接物理删除find-dup根目录、最小文件大小重复文件分组和节省空间估算只输出报告不自行删除top-dir根目录、Top N、最大深度目录体积排行对权限错误容错不追踪符号链接把三个工具放在一个工程里而不是散成三份临时脚本原因也很简单清理代码需要共享同一套安全删除逻辑否则每个脚本各写各的很容易出现一个工具删得小心翼翼另一个工具直接递归清空目录。2. 三连发初稿的常见写法能跑但多数不敢直接执行网上被反复生成的硬盘清理脚本写法大多集中在几个固定模式里。这些模式足够简单但离“可用且安全”还有明显距离。2.1 工具一临时文件清理初稿直接把目标目录整树删除常见初稿写法是遍历目录里的所有内容然后对整个文件或目录调用删除操作。from pathlib import Path import shutil root Path(./temp_target) for item in root.iterdir(): if item.is_dir(): shutil.rmtree(item) else: item.unlink()这段代码能跑通但存在几个明显问题没有过滤规则目录里的任何文件都会被动过。对目录直接使用shutil.rmtree如果目录内部有嵌套数据会被一次性全部删除。没有 dry-run执行前用户看不到到底删了哪些。一旦删除时遇到文件占用或权限异常脚本会中断前面的操作也已经生效难以恢复到中间状态。更关键的是这种代码读起来很“痛快”执行起来却像一次不可回滚的批量操作。真实场景里应该先列出候选文件清单逐条确认再进入执行阶段。2.2 工具二重复文件扫描初稿对每个文件都做完整哈希重复文件查找是典型的算法题很多人第一反应是计算文件的 MD5 或 SHA-1然后把哈希值相同的文件归为一组。import hashlib from pathlib import Path hash_map {} for file in Path(.).rglob(*): if not file.is_file(): continue digest hashlib.md5(file.read_bytes()).hexdigest() hash_map.setdefault(digest, []).append(file)这个初稿的问题非常具体file.read_bytes()会把整个文件一次性读进内存。遇到 4GB 的视频文件内存会直接被占满。对每个文件都做完整文件读取而文件数量多时磁盘 IO 会成为瓶颈。没有先用文件大小过滤。理论上文件内容相同的文件大小必然相同。大小不同的文件不可能重复完全没必要参与哈希计算。没有处理PermissionError和文件被占用的场景。正确方案是“文件大小分组 分块哈希”的二段式判断后面的实现会展开。2.3 工具三Top 目录扫描初稿没有深度限制和权限容错大目录定位工具的逻辑是递归统计子目录体积然后按体积从大到小排序。import os def get_dir_size(path): total 0 for entry in os.scandir(path): if entry.is_dir(follow_symlinksFalse): total get_dir_size(entry.path) else: total entry.stat().st_size return total这个初稿有三个隐患无限递归。如果目录层级非常深脚本会一直向下扫描用户可能只是想看二级目录分布。符号链接循环。即使follow_symlinksFalse避免了递归进入链接目录有些场景下仍需要额外判断硬链接和重复挂载点。权限错误没有捕获。扫描一个包含无权限子目录的根目录时脚本会在中途抛异常最终无法输出结果。Top 目录工具并不需要全量精确统计每个子目录下的每一个文件。日常定位磁盘占用时先限制扫描深度再粗略估算顶层目录体积已经能满足绝大多数场景。2.4 初稿到可执行版本之间缺的是状态管理三份初稿有一个共同短板缺少状态管理。一份脚本执行时应该清楚自己处在哪个阶段枚举阶段只收集文件信息。计划阶段输出将要处理的目标文件数量、总体积。执行阶段已经确认需要移动或删除。日志阶段记录操作结果方便回溯。AI 生成的初稿通常把“枚举”和“执行”混在一段循环里边遍历边删除。这种方式最危险因为你在遍历过程中修改目录结构很容易导致跳过文件、重复处理、遍历中断等意外行为。因此改造这三份代码的第一步不是优化算法而是把所有删除操作从“直接删”改成“先移动到备份目录”。3. 先封装安全层dry-run、软删除、路径逃逸检查无论哪个子工具只要涉及文件变更都应该共享同一个安全层。设计原则可以用一句话概括任何删除动作都要过“先备份、再确认、后清理”的流程。3.1 把所有删除动作改成“移动到备份目录”普通清理场景中直接调用unlink()或rmtree()很危险。最简单有效的方案是软删除在同一个盘符下创建一个备份目录把筛选出的文件移动进去。这样用户还能恢复系统也不会因为跨盘复制而长时间卡住。import shutil from pathlib import Path from datetime import datetime class SoftDelete: def __init__(self, backup_root: str cleanup_backup): self.backup_root Path(backup_root) self.backup_root.mkdir(parentsTrue, exist_okTrue) def build_dest(self, src: Path) - Path: timestamp datetime.now().strftime(%Y%m%d_%H%M%S) candidate self.backup_root / f{timestamp}_{src.name} index 1 while candidate.exists(): candidate self.backup_root / f{timestamp}_{index}_{src.name} index 1 return candidate def move_to_backup(self, src: Path) - Path: dest self.build_dest(src) shutil.move(str(src), str(dest)) return dest注意这里使用shutil.move而不是Path.rename是因为Path.rename只能在同一文件系统内工作。如果备份目录和源目录不在同一个磁盘分区shutil.move会先复制再删除源文件虽然速度慢一点但至少不会直接抛错。移动完成后磁盘上的文件仍然存在只是从原位置转移到了备份目录。这符合“先给后悔机会”的设计原则。3.2 路径与符号链接检查AI 生成代码时很少主动处理路径逃逸问题。如果用户传入的根目录是C:\Users\test\cleanup里面有一个符号链接指向D:\重要资料遍历代码一旦顺着符号链接进入目标目录删除范围就被扩大了。检查路径是否存在于根目录内部需要使用resolve()获取真实路径而不是比较字符串。from pathlib import Path class PathPolicy: def __init__(self, root: Path): self.root Path(root).resolve() def inside(self, target: Path) - bool: target_resolved Path(target).resolve() if target_resolved self.root: return False return self.root in target_resolved.parents def is_symlink(self, target: Path) - bool: return target.is_symlink()真实路径比较的核心逻辑是先解析出目标文件在磁盘上的绝对真实位置再看目标文件的父目录链里是否包含根目录。根目录内发生目录跳转时例如/data/project/tmp中的tmp是符号链接resolve()会把路径还原成符号链接指向的真实位置从而发现它并不在project目录下。3.3 命令行设计默认不改文件清理工具的命令行参数必须遵循一个原则默认只输出计划不执行变更。用户加上--apply之后代码才执行真正的移动操作。python disk_cleaner.py clean-temp --root ./demo --dry-run python disk_cleaner.py clean-temp --root ./demo --apply这种设计让清理工具和数据库的“事务确认”思路一致。第一次运行时用户看到的是[dry-run] 发现文件: ./demo/cache/old.tmp, 大小: 1.0 MB [dry-run] 发现文件: ./demo/app.log, 大小: 2.0 MB [dry-run] 合计: 2 个文件, 3.0 MB确认无误后再执行--apply。这样做能避免“命令一执行文件立刻消失”的恐怖体验。4. 三个工具的落地实现与运行验证安全层确定后三个子工具的实现就变成“收集候选文件”的问题。4.1 clean-temp 子命令临时文件清理器的核心逻辑是遍历根目录按后缀白名单过滤再按最小文件大小过滤。import argparse from pathlib import Path def collect_candidates( root: Path, suffixes: tuple[str, ...], min_size: int ) - list[Path]: root Path(root).resolve() results [] for file in root.rglob(*): if not file.is_file(): continue if suffixes and file.suffix.lower() not in suffixes: continue if file.stat().st_size min_size: continue results.append(file) return results为什么先判断is_file()因为rglob(*)会同时拿到目录和普通文件目录不应该进入候选清单。后续处理以文件为单位避免递归删除目录。后缀判断要使用lower()归一化。同一个文件扩展名在 Windows 和 Linux 上可能呈现出不同大小写例如.TMP和.tmp不处理会产生漏删。min_size参数的作用是过滤掉过小文件。建议默认设置在 1MB 以上否则清理工具会高频扫到大量几十字节的配置临时文件输出清单很难阅读而且容易误伤真正有用的运行时文件。4.2 find-dup 子命令重复文件检索采用二段式判断第一段按文件大小分组。第二段只对同组内文件做分块哈希。import hashlib from pathlib import Path from collections import defaultdict def file_md5(path: Path, chunk_size: int 1024 * 1024) - str: digest hashlib.md5() with path.open(rb) as file_obj: while True: block file_obj.read(chunk_size) if not block: break digest.update(block) return digest.hexdigest() def find_duplicates(root: Path, min_size: int 0) - dict[str, list[Path]]: by_size defaultdict(list) root Path(root).resolve() for file in root.rglob(*): if not file.is_file(): continue try: size file.stat().st_size except OSError: continue if size min_size: by_size[size].append(file) duplicate_groups defaultdict(list) for files_with_same_size in by_size.values(): if len(files_with_same_size) 2: continue for file_path in files_with_same_size: digest file_md5(file_path) duplicate_groups[digest].append(file_path) return { digest: paths for digest, paths in duplicate_groups.items() if len(paths) 1 }为什么要额外做try except OSError文件可能刚好在访问前被删除或移动也可能所在目录权限不足导致stat()失败。单文件失败不应该中断整个扫描否则几千个文件里只要有少数几个异常后续就没法继续了。分块哈希把每次读取量限制在 1MB无论文件多大内存占用都保持稳定。对超大文件这段逻辑只是读取更多轮次不会把整个文件塞进内存。4.3 top-dir 子命令大目录扫描不需要追求绝对精确更看重响应速度和结果可读性。因此这里用“最大深度 权限容错”的递归方式。import os from pathlib import Path def dir_size(path, max_depth: int, current_depth: int 0) - int: total 0 if current_depth max_depth: return 0 try: with os.scandir(path) as entries: for entry in entries: if entry.is_dir(follow_symlinksFalse): total dir_size( entry.path, max_depth, current_depth 1 ) elif entry.is_file(follow_symlinksFalse): total entry.stat().st_size except PermissionError: return 0 return total def top_directories(root: Path, top_n: int 10, max_depth: int 3) - list[tuple[str, int]]: sorted_dirs [] for path in Path(root).rglob(*): if not path.is_dir(): continue if path.is_symlink(): continue size dir_size(path, max_depthmax_depth) sorted_dirs.append((str(path), size)) sorted_dirs.sort(keylambda item: item[1], reverseTrue) return sorted_dirs[:top_n]使用follow_symlinksFalse是为了不跟随符号链接。符号链接可能指向根目录之外也可能形成目录循环跟随会导致无限递归或越界扫描。递归函数里PermissionError 会被捕获并直接返回 0。这个处理思路是“缺一段统计不能毁掉整个结果”。生产环境还可以把无权限的具体路径写入日志方便后续排查。4.4 最小测试目录与预期输出为了验证三个工具可以先构造一个小型测试目录。from pathlib import Path demo Path(./demo) (demo / cache).mkdir(parentsTrue, exist_okTrue) (demo / cache / old.tmp).write_bytes(bx * (2 * 1024 * 1024)) (demo / cache / image.bak).write_bytes(by * (3 * 1024 * 1024)) (demo / app.log).write_bytes(bz * (1024 * 1024)) (demo / 素材 / video.mp4).parent.mkdir(parentsTrue, exist_okTrue) (demo / 素材 / video.mkv).write_bytes(bcopy * (1024 * 1024))运行clean-temp的 dry-runpython disk_cleaner.py clean-temp --root ./demo --dry-run预期输出[dry-run] ./demo/cache/old.tmp, size2.0 MB [dry-run] ./demo/app.log, size1.0 MB [dry-run] 候选项: 2 files, total size3.0 MBimage.bak因为后缀是bak且大小是 3MB会出现在候选中而video.mp4后缀不在默认白名单所以不会出现。运行find-duppython disk_cleaner.py find-dup --root ./demo --min-size 1如果两个video文件长度相同代码会先按大小分组再哈希比较。如果内容不同则不会归进重复组。最终确认安全清理时可以先执行--apply查看移动结果再从备份目录中确认文件完整性最后再物理删除备份区。注意不要只验证工具能“跑起来”。真正要验证的是 dry-run 清单里的文件是否与预期一致、备份目录能否正常恢复、以及 backup 目录本身会不会被再次扫描。5. 硬盘清理最容易踩的坑与排查顺序硬盘清理工具运行时不报错不代表一切正常。下面这些现象在真实环境中出现频率很高。5.1 高频现象对照表问题现象常见原因检查方式处理建议dry-run 后没有任何输出根目录路径错误、文件后缀不匹配、min-size 设置太大检查根目录是否真实存在打印 root.resolve()先用一个已知的测试文件验证移动文件后磁盘空间没有变化备份目录设在同一个磁盘分区文件只是换了一个位置查看备份目录大小、确认物理删除阶段未执行真正释放空间需清理 backup 目录或使用外接硬盘备份循环开始时刚遍历完文件又被删除边遍历目录边删除导致遍历结果不完整检查代码里 rglob 和 unlink 是否在同一循环先收集 candidates 列表再单独执行软删除清理过程遇到 PermissionError 中断文件被占用或无权限异常没有被捕获查看报错堆栈指向哪个文件在单文件处理上做 try except跳过并记录重复文件扫描特别慢所有文件都做了完整哈希没有先按文件大小过滤观察 CPU 使用率和磁盘 IO使用“大小分组 分块哈希”二段式方案脚本扫描范围越界根目录内存在符号链接指向范围外目录打印 resolve() 后路径检查备份目录真实位置遍历时跳过符号链接5.2 现象到根因的排查链路硬盘清理类问题排查顺序可以固定为“输入 → 路径 → 规则 → 权限 → 日志”。第一步确认输入。清理命令敲下去之前先确认根目录路径是不是真的存在。路径写错后续任何逻辑都不会生效。第二步确认路径有没有被解析成预期位置。在 Windows 上尤其要注意大小写、盘符和符号链接问题。代码中应使用resolve()并在 dry-run 输出完整绝对路径方便人工核对。第三步确认过滤规则。临时文件清理必须看白名单后缀、文件大小下限和是否排除备份目录。文件没有进候选清单大多是规则太松或太严。第四步确认权限和文件占用。Windows 下常见的错误是文件正在被 Excel、Word、浏览器或系统服务占用。这类文件无法删除或移动脚本如果直接抛出PermissionError后面的文件就处理不了。第五步查看日志。清理工具必须记录每个文件的操作结果。缺少日志时误删文件后连“到底删了什么”都说不清。5.3 清理同一盘上的 backup 目录为什么空间没有释放这个问题很容易被人忽略。很多临时文件清理工具为了安全先把目标文件移动到cleanup_backup备份目录。如果备份目录和文件原位置在同一个磁盘分区则磁盘剩余空间不会变化。例如用户想清理 C 盘方案是“先把 C 盘文件移动到 C 盘 backup 目录”这从物理空间角度没有任何效果。文件只是换了一个目录仍然占用着 C 盘空间。正确做法有两种把备份目录放在另一块磁盘例如源文件在 C 盘备份目录在 D 盘。把软删除当成“临时中转站”在人工确认备份文件有效后再从 backup 目录执行物理删除。第一种方式适合生产服务器和重要数据第二种方式适合个人电脑的小规模整理。无论哪种方式都要把“释放空间”和“文件归档”两个目标分开描述否则用户执行完会误以为工具没有生效。6. 让 AI 生成代码可用需要在工程上补齐什么回到开头的问题既然三个工具都不是人写的那能不能放心用答案是能但前提是有一套明确的安全约束和人工审查流程。6.1 给 AI 的提示词要把安全约束写进去想让 AI 生成一份可用的硬盘清理脚本提示词不能只写“帮我清理临时文件”。更稳定的做法是把功能和约束一起描述。请生成一个 Python 命令行工具功能如下 1. 输入 root 路径输出该目录下后缀为 .tmp、.log、.bak 且大小大于等于 1MB 的文件。 2. 默认执行 dry-run只输出候选文件清单禁止修改原文件。 3. 只有传入 --apply 后才把候选文件移动到 backup_root 目录不要直接物理删除。 4. backup_root 默认在 root 的同级目录但不能被 scan 逻辑递归扫描到。 5. 遍历时跳过符号链接避免目录越界。 6. 对每个文件单独捕获权限异常避免单个失败中断整体任务。 7. 使用 pathlib不使用第三方库。 8. 最后给出三个测试用例。这些约束不是为了限制 AI而是为了把人类对“文件安全”的理解写进生成流程。AI 生成代码时更依赖提示词中的自然语言约束约束越具体代码越不会用暴力的方式实现删除。6.2 人审清单和最小测试集代码生成后不能直接进正式环境。可以按下面这份清单逐项过一遍代码中是否出现unlink、rmtree、os.remove等直接删除调用。如果出现物理删除是否满足用户显式指定了不可逆模式。遍历根目录是否使用resolve()做真实路径锁定。备份目录是否排除在扫描范围之外。是否默认 dry-rundry-run 模式下是否绝对没有任何写操作。单文件权限异常时是否会中断整个任务。是否输出完整操作日志包含源路径、目标路径、时间戳。是否提供了测试目录场景而不是只在真实目录里试。是否有显式参数控制文件后缀、文件大小和扫描深度。最小测试集可以只包含三个用例正常后缀文件、超大文件、无权限目录。正常后缀文件用于确认过滤规则超大文件用于观察内存占用无权限目录用于确认异常处理。6.3 从学习环境升级到生产环境的加固项个人电脑上跑clean-temp和学习环境里的跑法差异很大。生产环境还要额外考虑配置外置化根目录、后缀白名单、备份目录、是否启用定时任务都放到配置文件里。删除前导出 CSV 清单包含文件路径、大小、最后修改时间、处理结果。备份目录保留策略例如保留 7 天后自动清理过期备份或超过多少 GB 后触发告警。运行账号最小权限避免使用管理员账号执行清理任务。对系统目录执行更严格的黑名单机制例如根目录不能是C:\Windows或 Linux 的/usr。在 CI 环境增加代码扫描规则禁止自动提交包含危险递归删除的代码。这些项目不需要一次性全部实现但代码进入自动清理流程前至少要有一个可用的日志和备份恢复通道。6.4 最后说回这次“三连发”“都不是人写的”不应该成为判断标准。判断一段代码能不能用于清理硬盘标准只有一个代码作者能不能为它产生的每个文件变更负责。AI 能写出不错的遍历和哈希逻辑 AI生成硬盘清理工具？安全护栏设计是生命线
硬盘清理工具是系统维护里最高频的需求之一。临时文件清理、重复文件查找、大目录定位听起来很简单但一旦这类小工具被批量生成出来而且生成方式不是开发者从零手写的版本风险点就完全不同了。标题里说的“都不是人写的”并不是贬义它更像今天很多开发者的工作方式把需求描述给 AI 编程助手让它直接生成脚本。问题在于硬盘清理工具的本质是“找出文件并删除”删除一旦发生就很难回退。代码能不能跑是一回事代码删错了能不能兜底是另一回事。这篇文章会把“三连发”拆成三个最小场景临时文件清理器、重复文件检测器、Top 大目录扫描器。重点不是展示某个 AI 工具多好用而是回答三个问题这类代码初稿有哪些通病如何用工程手段补齐安全边界以及生成式代码要经过哪些审查才能进入真实环境。1. 先理解硬盘清理工具的代码为什么需要一套安全护栏很多人拿到磁盘快满的电脑第一反应就是搜“硬盘清理工具”。但一个真正可用的清理脚本并不是把“删文件”三个字翻译成代码那么简单。它本质上是一个由“枚举候选文件、判断是否可清理、执行移动或删除”组成三段式流程。三段式里的每一步都可能因为路径、权限、占用、后缀匹配宽度而产生不可逆后果。1.1 硬盘清理的底层操作并不复杂但不可逆从代码层面看硬盘清理主要做了三件事遍历目标目录找出可能的候选文件。对候选文件做规则过滤例如后缀、大小、修改时间、文件名关键字。对通过过滤的文件执行删除或归档操作。这里的核心矛盾是第二步过滤得再严格也无法百分之百模拟人的判断。后缀名为.tmp的文件大部分可以清理但可能有一个正在被某软件占用的临时文件.bak文件通常是备份但也可能承载着唯一一份配置历史用户手动指定--root /home/user后代码如果递归所有子目录就可能碰到不该碰的项目工程目录。删除操作天然不可逆。普通文件走回收站还能恢复很多脚本直接用os.remove物理删除后恢复只能依赖专业文件恢复工具成功率很不稳定。因此清理工具的第一条安全原则不是“删得快”而是“先别删”。一套稳妥的清理工具至少要包含候选清单、确认步骤、可恢复通道三部分。1.2 AI 生成代码适合做什么不适合直接做什么把需求交给 AI 后生成的结果通常语法正确、结构完整也基本能覆盖用户描述的功能。这很容易让人放松警惕。AI 比较擅长的是通用能力部分遍历目录的代码怎么写。计算文件哈希的代码怎么写。递归统计目录体积的代码怎么写。命令行参数解析怎么写。这些能力属于“常见套路”模型训练数据里见得足够多生成的代码可用性很高。不适合直接照搬的是包含副作用的部分哪些目录绝对不应该进入删除范围。符号链接是否会指向系统目录。备份目录放在哪里是否会再次被扫描到。文件被占用或权限不足时要不要中断整个脚本。如果提示词只写“清理临时文件删除超过 100MB 的文件”AI 通常会给出最简单直接的实现。这个实现能运行但不等于它理解了你真正想清理的范围。可以把 AI 生成的代码当成“初稿资产”而不能当成“生产最终品”。初稿负责把骨架搭出来人负责补上不可逆操作的兜底逻辑。1.3 三个工具的目标、输入与验收标准为了让“三连发”足够具体下面统一成三个命令行子命令。工具输入输出安全底线clean-temp根目录、后缀白名单、大小下限待清理文件清单或移动结果默认 dry-run不直接物理删除find-dup根目录、最小文件大小重复文件分组和节省空间估算只输出报告不自行删除top-dir根目录、Top N、最大深度目录体积排行对权限错误容错不追踪符号链接把三个工具放在一个工程里而不是散成三份临时脚本原因也很简单清理代码需要共享同一套安全删除逻辑否则每个脚本各写各的很容易出现一个工具删得小心翼翼另一个工具直接递归清空目录。2. 三连发初稿的常见写法能跑但多数不敢直接执行网上被反复生成的硬盘清理脚本写法大多集中在几个固定模式里。这些模式足够简单但离“可用且安全”还有明显距离。2.1 工具一临时文件清理初稿直接把目标目录整树删除常见初稿写法是遍历目录里的所有内容然后对整个文件或目录调用删除操作。from pathlib import Path import shutil root Path(./temp_target) for item in root.iterdir(): if item.is_dir(): shutil.rmtree(item) else: item.unlink()这段代码能跑通但存在几个明显问题没有过滤规则目录里的任何文件都会被动过。对目录直接使用shutil.rmtree如果目录内部有嵌套数据会被一次性全部删除。没有 dry-run执行前用户看不到到底删了哪些。一旦删除时遇到文件占用或权限异常脚本会中断前面的操作也已经生效难以恢复到中间状态。更关键的是这种代码读起来很“痛快”执行起来却像一次不可回滚的批量操作。真实场景里应该先列出候选文件清单逐条确认再进入执行阶段。2.2 工具二重复文件扫描初稿对每个文件都做完整哈希重复文件查找是典型的算法题很多人第一反应是计算文件的 MD5 或 SHA-1然后把哈希值相同的文件归为一组。import hashlib from pathlib import Path hash_map {} for file in Path(.).rglob(*): if not file.is_file(): continue digest hashlib.md5(file.read_bytes()).hexdigest() hash_map.setdefault(digest, []).append(file)这个初稿的问题非常具体file.read_bytes()会把整个文件一次性读进内存。遇到 4GB 的视频文件内存会直接被占满。对每个文件都做完整文件读取而文件数量多时磁盘 IO 会成为瓶颈。没有先用文件大小过滤。理论上文件内容相同的文件大小必然相同。大小不同的文件不可能重复完全没必要参与哈希计算。没有处理PermissionError和文件被占用的场景。正确方案是“文件大小分组 分块哈希”的二段式判断后面的实现会展开。2.3 工具三Top 目录扫描初稿没有深度限制和权限容错大目录定位工具的逻辑是递归统计子目录体积然后按体积从大到小排序。import os def get_dir_size(path): total 0 for entry in os.scandir(path): if entry.is_dir(follow_symlinksFalse): total get_dir_size(entry.path) else: total entry.stat().st_size return total这个初稿有三个隐患无限递归。如果目录层级非常深脚本会一直向下扫描用户可能只是想看二级目录分布。符号链接循环。即使follow_symlinksFalse避免了递归进入链接目录有些场景下仍需要额外判断硬链接和重复挂载点。权限错误没有捕获。扫描一个包含无权限子目录的根目录时脚本会在中途抛异常最终无法输出结果。Top 目录工具并不需要全量精确统计每个子目录下的每一个文件。日常定位磁盘占用时先限制扫描深度再粗略估算顶层目录体积已经能满足绝大多数场景。2.4 初稿到可执行版本之间缺的是状态管理三份初稿有一个共同短板缺少状态管理。一份脚本执行时应该清楚自己处在哪个阶段枚举阶段只收集文件信息。计划阶段输出将要处理的目标文件数量、总体积。执行阶段已经确认需要移动或删除。日志阶段记录操作结果方便回溯。AI 生成的初稿通常把“枚举”和“执行”混在一段循环里边遍历边删除。这种方式最危险因为你在遍历过程中修改目录结构很容易导致跳过文件、重复处理、遍历中断等意外行为。因此改造这三份代码的第一步不是优化算法而是把所有删除操作从“直接删”改成“先移动到备份目录”。3. 先封装安全层dry-run、软删除、路径逃逸检查无论哪个子工具只要涉及文件变更都应该共享同一个安全层。设计原则可以用一句话概括任何删除动作都要过“先备份、再确认、后清理”的流程。3.1 把所有删除动作改成“移动到备份目录”普通清理场景中直接调用unlink()或rmtree()很危险。最简单有效的方案是软删除在同一个盘符下创建一个备份目录把筛选出的文件移动进去。这样用户还能恢复系统也不会因为跨盘复制而长时间卡住。import shutil from pathlib import Path from datetime import datetime class SoftDelete: def __init__(self, backup_root: str cleanup_backup): self.backup_root Path(backup_root) self.backup_root.mkdir(parentsTrue, exist_okTrue) def build_dest(self, src: Path) - Path: timestamp datetime.now().strftime(%Y%m%d_%H%M%S) candidate self.backup_root / f{timestamp}_{src.name} index 1 while candidate.exists(): candidate self.backup_root / f{timestamp}_{index}_{src.name} index 1 return candidate def move_to_backup(self, src: Path) - Path: dest self.build_dest(src) shutil.move(str(src), str(dest)) return dest注意这里使用shutil.move而不是Path.rename是因为Path.rename只能在同一文件系统内工作。如果备份目录和源目录不在同一个磁盘分区shutil.move会先复制再删除源文件虽然速度慢一点但至少不会直接抛错。移动完成后磁盘上的文件仍然存在只是从原位置转移到了备份目录。这符合“先给后悔机会”的设计原则。3.2 路径与符号链接检查AI 生成代码时很少主动处理路径逃逸问题。如果用户传入的根目录是C:\Users\test\cleanup里面有一个符号链接指向D:\重要资料遍历代码一旦顺着符号链接进入目标目录删除范围就被扩大了。检查路径是否存在于根目录内部需要使用resolve()获取真实路径而不是比较字符串。from pathlib import Path class PathPolicy: def __init__(self, root: Path): self.root Path(root).resolve() def inside(self, target: Path) - bool: target_resolved Path(target).resolve() if target_resolved self.root: return False return self.root in target_resolved.parents def is_symlink(self, target: Path) - bool: return target.is_symlink()真实路径比较的核心逻辑是先解析出目标文件在磁盘上的绝对真实位置再看目标文件的父目录链里是否包含根目录。根目录内发生目录跳转时例如/data/project/tmp中的tmp是符号链接resolve()会把路径还原成符号链接指向的真实位置从而发现它并不在project目录下。3.3 命令行设计默认不改文件清理工具的命令行参数必须遵循一个原则默认只输出计划不执行变更。用户加上--apply之后代码才执行真正的移动操作。python disk_cleaner.py clean-temp --root ./demo --dry-run python disk_cleaner.py clean-temp --root ./demo --apply这种设计让清理工具和数据库的“事务确认”思路一致。第一次运行时用户看到的是[dry-run] 发现文件: ./demo/cache/old.tmp, 大小: 1.0 MB [dry-run] 发现文件: ./demo/app.log, 大小: 2.0 MB [dry-run] 合计: 2 个文件, 3.0 MB确认无误后再执行--apply。这样做能避免“命令一执行文件立刻消失”的恐怖体验。4. 三个工具的落地实现与运行验证安全层确定后三个子工具的实现就变成“收集候选文件”的问题。4.1 clean-temp 子命令临时文件清理器的核心逻辑是遍历根目录按后缀白名单过滤再按最小文件大小过滤。import argparse from pathlib import Path def collect_candidates( root: Path, suffixes: tuple[str, ...], min_size: int ) - list[Path]: root Path(root).resolve() results [] for file in root.rglob(*): if not file.is_file(): continue if suffixes and file.suffix.lower() not in suffixes: continue if file.stat().st_size min_size: continue results.append(file) return results为什么先判断is_file()因为rglob(*)会同时拿到目录和普通文件目录不应该进入候选清单。后续处理以文件为单位避免递归删除目录。后缀判断要使用lower()归一化。同一个文件扩展名在 Windows 和 Linux 上可能呈现出不同大小写例如.TMP和.tmp不处理会产生漏删。min_size参数的作用是过滤掉过小文件。建议默认设置在 1MB 以上否则清理工具会高频扫到大量几十字节的配置临时文件输出清单很难阅读而且容易误伤真正有用的运行时文件。4.2 find-dup 子命令重复文件检索采用二段式判断第一段按文件大小分组。第二段只对同组内文件做分块哈希。import hashlib from pathlib import Path from collections import defaultdict def file_md5(path: Path, chunk_size: int 1024 * 1024) - str: digest hashlib.md5() with path.open(rb) as file_obj: while True: block file_obj.read(chunk_size) if not block: break digest.update(block) return digest.hexdigest() def find_duplicates(root: Path, min_size: int 0) - dict[str, list[Path]]: by_size defaultdict(list) root Path(root).resolve() for file in root.rglob(*): if not file.is_file(): continue try: size file.stat().st_size except OSError: continue if size min_size: by_size[size].append(file) duplicate_groups defaultdict(list) for files_with_same_size in by_size.values(): if len(files_with_same_size) 2: continue for file_path in files_with_same_size: digest file_md5(file_path) duplicate_groups[digest].append(file_path) return { digest: paths for digest, paths in duplicate_groups.items() if len(paths) 1 }为什么要额外做try except OSError文件可能刚好在访问前被删除或移动也可能所在目录权限不足导致stat()失败。单文件失败不应该中断整个扫描否则几千个文件里只要有少数几个异常后续就没法继续了。分块哈希把每次读取量限制在 1MB无论文件多大内存占用都保持稳定。对超大文件这段逻辑只是读取更多轮次不会把整个文件塞进内存。4.3 top-dir 子命令大目录扫描不需要追求绝对精确更看重响应速度和结果可读性。因此这里用“最大深度 权限容错”的递归方式。import os from pathlib import Path def dir_size(path, max_depth: int, current_depth: int 0) - int: total 0 if current_depth max_depth: return 0 try: with os.scandir(path) as entries: for entry in entries: if entry.is_dir(follow_symlinksFalse): total dir_size( entry.path, max_depth, current_depth 1 ) elif entry.is_file(follow_symlinksFalse): total entry.stat().st_size except PermissionError: return 0 return total def top_directories(root: Path, top_n: int 10, max_depth: int 3) - list[tuple[str, int]]: sorted_dirs [] for path in Path(root).rglob(*): if not path.is_dir(): continue if path.is_symlink(): continue size dir_size(path, max_depthmax_depth) sorted_dirs.append((str(path), size)) sorted_dirs.sort(keylambda item: item[1], reverseTrue) return sorted_dirs[:top_n]使用follow_symlinksFalse是为了不跟随符号链接。符号链接可能指向根目录之外也可能形成目录循环跟随会导致无限递归或越界扫描。递归函数里PermissionError 会被捕获并直接返回 0。这个处理思路是“缺一段统计不能毁掉整个结果”。生产环境还可以把无权限的具体路径写入日志方便后续排查。4.4 最小测试目录与预期输出为了验证三个工具可以先构造一个小型测试目录。from pathlib import Path demo Path(./demo) (demo / cache).mkdir(parentsTrue, exist_okTrue) (demo / cache / old.tmp).write_bytes(bx * (2 * 1024 * 1024)) (demo / cache / image.bak).write_bytes(by * (3 * 1024 * 1024)) (demo / app.log).write_bytes(bz * (1024 * 1024)) (demo / 素材 / video.mp4).parent.mkdir(parentsTrue, exist_okTrue) (demo / 素材 / video.mkv).write_bytes(bcopy * (1024 * 1024))运行clean-temp的 dry-runpython disk_cleaner.py clean-temp --root ./demo --dry-run预期输出[dry-run] ./demo/cache/old.tmp, size2.0 MB [dry-run] ./demo/app.log, size1.0 MB [dry-run] 候选项: 2 files, total size3.0 MBimage.bak因为后缀是bak且大小是 3MB会出现在候选中而video.mp4后缀不在默认白名单所以不会出现。运行find-duppython disk_cleaner.py find-dup --root ./demo --min-size 1如果两个video文件长度相同代码会先按大小分组再哈希比较。如果内容不同则不会归进重复组。最终确认安全清理时可以先执行--apply查看移动结果再从备份目录中确认文件完整性最后再物理删除备份区。注意不要只验证工具能“跑起来”。真正要验证的是 dry-run 清单里的文件是否与预期一致、备份目录能否正常恢复、以及 backup 目录本身会不会被再次扫描。5. 硬盘清理最容易踩的坑与排查顺序硬盘清理工具运行时不报错不代表一切正常。下面这些现象在真实环境中出现频率很高。5.1 高频现象对照表问题现象常见原因检查方式处理建议dry-run 后没有任何输出根目录路径错误、文件后缀不匹配、min-size 设置太大检查根目录是否真实存在打印 root.resolve()先用一个已知的测试文件验证移动文件后磁盘空间没有变化备份目录设在同一个磁盘分区文件只是换了一个位置查看备份目录大小、确认物理删除阶段未执行真正释放空间需清理 backup 目录或使用外接硬盘备份循环开始时刚遍历完文件又被删除边遍历目录边删除导致遍历结果不完整检查代码里 rglob 和 unlink 是否在同一循环先收集 candidates 列表再单独执行软删除清理过程遇到 PermissionError 中断文件被占用或无权限异常没有被捕获查看报错堆栈指向哪个文件在单文件处理上做 try except跳过并记录重复文件扫描特别慢所有文件都做了完整哈希没有先按文件大小过滤观察 CPU 使用率和磁盘 IO使用“大小分组 分块哈希”二段式方案脚本扫描范围越界根目录内存在符号链接指向范围外目录打印 resolve() 后路径检查备份目录真实位置遍历时跳过符号链接5.2 现象到根因的排查链路硬盘清理类问题排查顺序可以固定为“输入 → 路径 → 规则 → 权限 → 日志”。第一步确认输入。清理命令敲下去之前先确认根目录路径是不是真的存在。路径写错后续任何逻辑都不会生效。第二步确认路径有没有被解析成预期位置。在 Windows 上尤其要注意大小写、盘符和符号链接问题。代码中应使用resolve()并在 dry-run 输出完整绝对路径方便人工核对。第三步确认过滤规则。临时文件清理必须看白名单后缀、文件大小下限和是否排除备份目录。文件没有进候选清单大多是规则太松或太严。第四步确认权限和文件占用。Windows 下常见的错误是文件正在被 Excel、Word、浏览器或系统服务占用。这类文件无法删除或移动脚本如果直接抛出PermissionError后面的文件就处理不了。第五步查看日志。清理工具必须记录每个文件的操作结果。缺少日志时误删文件后连“到底删了什么”都说不清。5.3 清理同一盘上的 backup 目录为什么空间没有释放这个问题很容易被人忽略。很多临时文件清理工具为了安全先把目标文件移动到cleanup_backup备份目录。如果备份目录和文件原位置在同一个磁盘分区则磁盘剩余空间不会变化。例如用户想清理 C 盘方案是“先把 C 盘文件移动到 C 盘 backup 目录”这从物理空间角度没有任何效果。文件只是换了一个目录仍然占用着 C 盘空间。正确做法有两种把备份目录放在另一块磁盘例如源文件在 C 盘备份目录在 D 盘。把软删除当成“临时中转站”在人工确认备份文件有效后再从 backup 目录执行物理删除。第一种方式适合生产服务器和重要数据第二种方式适合个人电脑的小规模整理。无论哪种方式都要把“释放空间”和“文件归档”两个目标分开描述否则用户执行完会误以为工具没有生效。6. 让 AI 生成代码可用需要在工程上补齐什么回到开头的问题既然三个工具都不是人写的那能不能放心用答案是能但前提是有一套明确的安全约束和人工审查流程。6.1 给 AI 的提示词要把安全约束写进去想让 AI 生成一份可用的硬盘清理脚本提示词不能只写“帮我清理临时文件”。更稳定的做法是把功能和约束一起描述。请生成一个 Python 命令行工具功能如下 1. 输入 root 路径输出该目录下后缀为 .tmp、.log、.bak 且大小大于等于 1MB 的文件。 2. 默认执行 dry-run只输出候选文件清单禁止修改原文件。 3. 只有传入 --apply 后才把候选文件移动到 backup_root 目录不要直接物理删除。 4. backup_root 默认在 root 的同级目录但不能被 scan 逻辑递归扫描到。 5. 遍历时跳过符号链接避免目录越界。 6. 对每个文件单独捕获权限异常避免单个失败中断整体任务。 7. 使用 pathlib不使用第三方库。 8. 最后给出三个测试用例。这些约束不是为了限制 AI而是为了把人类对“文件安全”的理解写进生成流程。AI 生成代码时更依赖提示词中的自然语言约束约束越具体代码越不会用暴力的方式实现删除。6.2 人审清单和最小测试集代码生成后不能直接进正式环境。可以按下面这份清单逐项过一遍代码中是否出现unlink、rmtree、os.remove等直接删除调用。如果出现物理删除是否满足用户显式指定了不可逆模式。遍历根目录是否使用resolve()做真实路径锁定。备份目录是否排除在扫描范围之外。是否默认 dry-rundry-run 模式下是否绝对没有任何写操作。单文件权限异常时是否会中断整个任务。是否输出完整操作日志包含源路径、目标路径、时间戳。是否提供了测试目录场景而不是只在真实目录里试。是否有显式参数控制文件后缀、文件大小和扫描深度。最小测试集可以只包含三个用例正常后缀文件、超大文件、无权限目录。正常后缀文件用于确认过滤规则超大文件用于观察内存占用无权限目录用于确认异常处理。6.3 从学习环境升级到生产环境的加固项个人电脑上跑clean-temp和学习环境里的跑法差异很大。生产环境还要额外考虑配置外置化根目录、后缀白名单、备份目录、是否启用定时任务都放到配置文件里。删除前导出 CSV 清单包含文件路径、大小、最后修改时间、处理结果。备份目录保留策略例如保留 7 天后自动清理过期备份或超过多少 GB 后触发告警。运行账号最小权限避免使用管理员账号执行清理任务。对系统目录执行更严格的黑名单机制例如根目录不能是C:\Windows或 Linux 的/usr。在 CI 环境增加代码扫描规则禁止自动提交包含危险递归删除的代码。这些项目不需要一次性全部实现但代码进入自动清理流程前至少要有一个可用的日志和备份恢复通道。6.4 最后说回这次“三连发”“都不是人写的”不应该成为判断标准。判断一段代码能不能用于清理硬盘标准只有一个代码作者能不能为它产生的每个文件变更负责。AI 能写出不错的遍历和哈希逻辑