下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/user_515026d2--duplicate-file-cleaner.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_515026d2/duplicate-file-cleaner。清理任意目录里的重复文件。用硬链接技术(不是删除)回收磁盘空间——所有文件路径、文件名、大小全部保持不变,微信/网盘/下载工具里原有的记录照常能打开,但磁盘只保留一份数据。适用于微信文件目录、下载目录、网盘同步目录、项目素材目录等任何出现「同一文件多份副本」的场景。按 MD5 精确识别真重复,同名但内容不同的版本文件绝不误判。
自带图形界面(选目录→扫描→勾选→清理)与命令行两种用法,纯 Python 标准库零依赖。触发词:重复文件、重复文件清理、文件去重、硬链接去重、硬链接、磁盘空间不够、清理磁盘、C盘满了、D盘满了、微信文件太占空间、微信去重、清理微信文件、msg/file 太大、文件夹里有重复、删除重复文件、磁盘瘦身。
阅读全文 (展开查看完整说明)
概述
重复文件清理与硬链接去重
处理任意目录里的重复文件:微信文件目录、浏览器下载目录、网盘同步目录、素材库、项目归档……
核心手法不是删除,而是硬链接。 所有文件路径、文件名、显示大小全部保持不变,原程序照常能打开,但磁盘上同一份内容只存一次。
这个技能解决什么
重复文件几乎无处不在。按来源分四类:
| 级别 | 问题 | 典型来源 | 处理方式 |
|---|---|---|---|
| A | MD5 完全相同的真重复 — 同一文件被反复发送/下载/复制,程序自动改名 (1) (2) (1)(1)(1) 而不覆盖 | 微信/QQ 反复转发、浏览器重复下载、网盘同步冲突 | ✅ 硬链接去重 |
| B | 解压出来的软件目录 — 当年直接在下载/缓存目录里解压运行的绿色软件,一直没搬走 | 下载目录、微信文件目录 | 搬到 D:Tools 或删除 |
| C | 安装包 / 压缩包 — exe / msi / rar / zip,装完就忘 | 下载目录 | 装完即清 |
| D | 同名但内容不同 = 不同版本 | 方案文档多版本 | ❌ 绝不自动删,需人工判断 |
典型场景:微信文件目录
微信(新版 xwechat)把收发过的所有文件统一落在 ...xwechat_files<你的wxid>msgfile<年-月> 下,是重复文件的头号重灾区 —— 一个文件反复发给多人会留下多份带括号后缀的副本。
实测案例:某微信目录 5,522 个文件 / 6.85 GB。其中 MD5 完全相同的真重复 434 个(可回收 236 MB),
另有解压残留的软件目录 770 MB、安装包与压缩包约 1.6 GB。全部处理后可压到 3 GB 上下。
但本技能不限于微信,任何目录都能跑,包括微信、QQ、钉钉的文件目录,浏览器下载目录,OneDrive / 坚果云同步目录,以及你自己的素材库和项目归档。
核心原则(必须遵守)
- 绝不通过删除文件来"去重"。 很多程序(微信、网盘客户端、各类资料库)都按文件路径索引文件。
删掉 xxx(1).pdf 后,程序里那条记录点开就会显示「文件已过期或已被清理」,历史记录永久残缺。
- 硬链接是唯一正解。 让多个路径指向磁盘上同一份数据块:文件名不变、大小显示不变、位置不变、
原程序照常打开,但磁盘只占一份。删除任一链接,其余毫发无损。
- 只对 MD5 完全一致的文件建链接。 同大小不算数,必须哈希级验证。
- 只处理用户明确指定的目录。 绝不越界触碰其他目录。
- 默认干演,必须用户确认后才执行。
调用约定(skill 被激活时立即执行)
本技能被调用 / 激活后,agent 必须严格按以下流程行事,不得跳步、不得提前执行:
- 立即启动图形界面(GUI)。 运行
python scripts/run_gui.py
(默认会自动弹出 GUI 窗口;不要加 --no-browser,该参数仅用于无显示环境调试)。GUI 启动后,通过预览面板或本机浏览器向用户展示界面。
- 展示扫描选项,由用户自主选择。 GUI 须向用户呈现:
- 目录选择(路径输入框 / 网页内目录树 / 浏览按钮)
- 扫描选项开关(只看文档类、同时列出可清理安装包等)
- 由用户自主选择要扫描的目标目录与范围;agent 不得代选、不得假设默认目录、不得预填路径。
- 禁止在未展示界面的情况下自动执行扫描。 在用户于 GUI 中确认目标并主动点击「开始扫描」之前,
任何情况下都不得直接调用 scripts/scan_dupes.py、scripts/dedup_hardlink.py 等底层脚本执行扫描、生成报告或去重;也不得静默跑只读体检、不得预先生成任何扫描结果。
- 用户确认后才继续。 仅当用户在界面中明确发起扫描 / 去重操作时才执行对应动作;
若涉及去重,仍须沿用 GUI 内的二次确认与「默认干演、需用户确认」原则(见核心原则第 5 条)。
一句话:先弹界面 → 用户选目标 → 用户确认 → 再执行。 绝不在未向用户展示界面的前提下自动执行任何扫描或清理。
快速开始 —— 按手上的环境挑一条路
路径约定:下文所有相对路径都相对于本技能包根目录。
不确定技能包在哪时,用
scripts/run_gui.py(它靠__file__自动定位,永远不会找错)。
| 路线 | 前提条件 | 入口 |
|---|---|---|
| A. 图形界面(推荐) | 本机有 Python 3.9+,只需标准库 | python scripts/run_gui.py |
| B. 纯命令行 | 同上 | python scripts/scan_dupes.py "<目录>" "<输出目录>" |
| C. 零依赖单文件 exe | 需先自建一次(见「自建单文件 exe」) | 双击生成出来的 exe |
先探测环境:
# Windows
where python || where py
# macOS / Linux
which python3本技能包纯 Python 标准库实现,不需要 pip install 任何东西。若本机完全没有 Python 而又想要开箱即用,见文末「自建单文件 exe」——在任一有 Python 的机器上打包一次,换个机器就能零依赖双击运行。
技能包结构
duplicate-file-cleaner/
├─ SKILL.md ← 本文件
├─ README.md ← 给人看的说明(可直接转发给使用者)
├─ LICENSE.md ← MIT
├─ gui/
│ ├─ app.py ← 本地服务(纯标准库,ThreadingHTTPServer 绑 127.0.0.1)
│ ├─ ui.html ← 单页界面
│ ├─ pick_folder.py ← tkinter 原生目录选择(独立子进程)
│ ├─ make_exe.py ← 一键打包成单文件 exe
│ ├─ version_info.txt ← PE 版本资源
│ └─ make_icon.py ← 纯 Python 生成 ico(不依赖 PIL)
└─ scripts/
├─ run_gui.py ← 图形界面启动器(自动定位 gui/app.py)
├─ scan_dupes.py ← 只读扫描体检
├─ dedup_hardlink.py ← 干演 / 执行 / 校验
├─ demo_hardlink.py ← 原理演示(隔离目录,用完自删)
├─ test_tool.py ← 端到端测试
└─ test_exts.py ← 扩展名过滤回归(防「扫出 0 个文件」复发)路线 A:图形界面(推荐给所有人)
cd <技能包根目录>
python scripts/run_gui.py # 自动定位 gui/app.py 并启动
# 或
python gui/app.py --no-browser # 不想自动开浏览器时Windows 用户也可以直接双击 scriptsrun_gui.py(前提:.py 已关联到 Python;否则右键 →「打开方式」选 Python,或照旧用命令行)。
会启动本地服务并自动开一个独立窗口(探测到 Edge/Chrome 时用 --app= 模式,看起来像原生程序;保底退回系统默认浏览器)。
四步操作:
- 选目录 — 三种选法:原生「浏览文件夹…」对话框、网页内目录树、直接手输路径。会记住上次选的目录。
- 开始扫描 — 实时进度条。全程只读:只遍历 + 算 MD5,不改任何文件。
- 在列表里勾选 — 按重复组展开,每组一行一个文件;绿色高亮那行是被保留的"正本"
(默认挑名字最干净的,带 (1)(2) 的被链接掉)。想换正本?点那行的圆点。现已支持整组全部清理——把同组所有副本都勾选(或点「全选批量删除」)即不再强制保留,整组一起移入回收站。
- (快速定位) 每个文件下方显示完整路径,点击路径文字或右侧「📂 打开」按钮,即可在资源管理器中打开该文件所在的文件夹并自动选中该文件(仅限扫描根目录内,路径越界会被拒绝)。
- (文件大小统一以 KB 展示) 列表里每个文件和每组的单份大小都统一显示为 KB(千字节),自适应小数位(<10KB 两位小数、<1000KB 一位、更大取整并加千分位),例如
1.50 KB、100.0 KB、204,800 KB;底部状态栏的「可回收空间」仍用人性化单位(KB/MB/GB)以便快速估算。 - (重复文件分组排序) 在「重复文件」标签页的工具栏提供排序控件,可分别按 文件大小 / 文件名 / 修改时间 与 升序 / 降序 组合排列:不仅各重复组之间按所选维度排序(组按代表文件/组内最新修改时间计算),组内每个文件也按同一维度重排,方便快速定位最大的、最新的或同名散落的副本。排序切换即时生效,与「显示筛选」「勾选状态」互不干扰。「可清理文件」标签页同样遵循该排序。
- (副本序号) 每个重复组内的每一份副本前面都标有序号徽标(按当前排序顺序
1、2、3…,保留正本的那一份序号高亮为绿色),一眼即可看出「这是本组第几份副本」,配合排序控件快速核对与勾选。 - (批量删除全部副本) 在「重复文件」标签页的工具栏有 🗑 全选批量删除 按钮:一键选中全部重复副本(含正本)并移入回收站(可还原);每个重复组标题右侧另有 🗑 删整组 按钮,便于在逐组筛选时直接清空本组所有副本。两者都不强制保留正本、都在界面二次确认后才执行,且只移入回收站(可从回收站还原),不会永久删除。
- 点右下角执行:
- 硬链接去重(推荐)— 文件全保留,路径/名字/大小都不变,只省磁盘
- 移入回收站 — 彻底清走,但可从回收站还原
另有「可清理文件」标签页,自动挑出安装包和压缩包,可单独勾选清理。
两个开关的含义(默认值已按最不容易踩坑的方式设定):
- 「只看文档类」默认不勾选 → 默认扫描全部类型,不会漏掉图片/视频/程序类重复。
勾上则只扫 doc/docx/ppt/pptx/xls/xlsx/pdf/txt/csv/md/wps/et/常见图片/zip/rar/7z。(注意:勾上时安装包 exe/msi 仍会被收进「可清理文件」列表,不受影响。)
- 「同时列出可清理的安装包 / 压缩包」默认勾选。
tkinter只用于「浏览文件夹…」原生对话框。没有 tkinter 也不影响主体功能(扫描、去重、回收站、网页内目录树全部正常),只是该按钮不可用。
路线 B:纯命令行(只需标准库)
第 0 步:向用户确认
- 目标目录(必须由用户指定,不要自行猜测)
- 是否要跨目录去重(需要用户提供自己的工作目录清单)
第 1 步:扫描体检(只读)
python scripts/scan_dupes.py "<目标目录>" "<输出目录>"产出 dupes_report.json:A 类真重复组、命名重复组、按月分布。同时统计:总计大小、扩展名占用、子文件夹占用(用于找出 B 类解压残留)。
第 2 步:生成去重计划(仍不动文件)
python scripts/dedup_hardlink.py --root "<目标目录>" --plan产出 dedup_plan.json。
保留规则(pick_keeper):文件名最干净的优先(带 (1)(2)/「副本」的被链接掉)→ 其次 mtime 最早 → 再次路径最短。所以留下当"正本"的通常正好是没有括号后缀的那份。
第 3 步:把计划摘要给用户确认
必须明确告知:处理文件数、预计回收空间、目录范围、操作方式(删副本 + 原位建链接)、可逆性。
第 4 步:执行
python scripts/dedup_hardlink.py --root "<目标目录>" --plan --apply
# 会要求输入 YES;CI/自动化场景可加 --yes执行时的原子性保证(脚本已实现,勿随意改动):
- 前置校验:文件存在、大小一致、双方 MD5 均等于计划中的哈希
os.link(keeper, tmp)— 先建临时硬链接,失败则中止,无副作用os.replace(tmp, target)— 原子替换,任何时刻 target 都指向有效数据- 后置校验:
st_ino一致 + MD5 一致 - 全过程写 CSV 日志(
dedup_log.csv),逐条可追溯 - 已是硬链接的自动跳过(
SKIP_ALREADY)
第 5 步:校验
python scripts/dedup_hardlink.py --verify前置检查(每次执行前必做)
# 1) 目标卷必须是 NTFS(Windows)/ ext4·APFS 等支持硬链接的文件系统,且所有重复文件在同一卷内(硬链接不支持跨卷)
python -c "
import ctypes
k=ctypes.windll.kernel32
b=ctypes.create_unicode_buffer(256); f=ctypes.create_unicode_buffer(256)
s=ctypes.c_ulong(); m=ctypes.c_ulong(); fl=ctypes.c_ulong()
k.GetVolumeInformationW('<盘符>:\\', b,256,ctypes.byref(s),ctypes.byref(m),ctypes.byref(fl), f,256)
print('FileSystem:', f.value)"
# 预期输出 FileSystem: NTFS
# 2) 实测硬链接能力(临时目录,用完即删)
python scripts/dedup_hardlink.py --self-test
# 预期:os.replace 硬链接替换: PASS / st_ino 可用: PASS三个坑(安全相关,务必注意)
- 原地写入会污染同组链接。 硬链接的多个路径共享数据块,若某程序对文件做原地写入(而非另存为新文件再替换),改动会同步到同组其他链接上。
- Office 系(Word / PPT / Excel)一律走「另存 + 替换」的安全保存 → docx/pptx/xlsx 基本无风险。
- 脚本默认跳过 1KB 以下小文件,减小扰动面。
- 若要彻底规避:改用引用计数为 1 的独立副本策略,但那就不省空间了。
- 硬链接不支持跨卷,且不能对文件夹建链接。所有重复文件必须与保留文件在同一分区。
- 不要对 A 类以外的文件建硬链接。 D 类(同名不同内容)是不同版本,强行链接会丢版本。
工具开发/维护中的八个坑(改代码前必读)
- 【最隐蔽,优先看这条】扩展名过滤:前端传不带点,后端比的是带点,结果恒为 0 个文件。
界面里 DOC_EXT = ['docx','pdf', ...](不带点),而后端用 os.path.splitext(name)[1].lower()拿到的是 '.docx'(带点)。于是 '.docx' not in {'docx', ...} 恒为真 → 每个文件都被continue 掉 → 扫描结果永远是 0 个文件。表象极难定位:界面不报任何错、进度条正常走完、显示"扫描完成",只是列表全空。修复:后端 norm_exts() 统一归一化为「带点小写」,兼容 docx / .docx / DOCX / .Docx 。教训:凡"前端传参 + 后端比对"的字段,格式必须由后端兜底归一化,绝不能假定前端格式。
- 安装包必须在扩展名过滤之外单独放行。 否则勾了「只看文档类」时,
JUNK_EXT里的
.exe/.msi 会跟着被滤掉,用户勾了「同时列出可清理的安装包」却什么也看不到。正确判据:is_junk = include_junk and ext in JUNK_EXT,if exts and ext not in exts and not is_junk: continue。
- 回归测试必须包含一组「界面默认参数」用例。 直接调 API 传
exts=[](不过滤)能全绿,
但界面默认勾着过滤器时走的是完全不同的代码分支 —— 上面那个 bug 就是这么漏掉的。
- 扫描结果为 0 时界面必须给出明确原因提示,不能静默空白。要列全三种可能:
目录选错 / 「小于此大小忽略」设太大 / 勾了「只看文档类」。
SHFileOperationW返回码在 Win10/11 上恒为 2,这不是失败。 判据必须是
「原路径是否消失 + 回收站 $I 条目数是否增加」两个事实。结构体本身没问题(sizeof=56,各字段偏移正确)。
- Bash/终端里用
&启的后台进程会随命令结束被回收。 需要长驻时用工具提供的
后台运行能力,或让脚本自己在线程里 serve_forever()。
- urllib 请求
127.0.0.1可能被系统代理拦成 502。 必须
build_opener(ProxyHandler({})) 绕过。
- 大列表(数百组)不要整表重绘 DOM。 按组替换:
renderGroup(id)里用
el.replaceWith(tmp.firstChild),只重绘被操作的那一组。
排查提效:遇到"界面显示正常但结果为空"这类问题,绕过 HTTP 层直接调
run_scan()就能立刻分清是内核问题还是传参问题。随包提供、可独立运行的自证脚本是
scripts/test_exts.py(自己造测试数据,任何机器一条命令跑出结论)。
编辑源码的两条纪律
- 同一个文件不要在同一条消息里并行发多个编辑操作。 曾出现过并行编辑
ui.html两次、
其中一次改动被静默覆盖(工具仍返回"成功")的情况。
- 改完必须回读验证,不要相信工具的"成功"回执。
scripts/test_exts.py可做回归。
自建单文件 exe(想要零依赖分发时)
技能包不含预编译 exe(保持纯源码、便于审计、也避免安全扫描对未签名二进制产生疑虑)。需要"双击即用、目标机不装 Python"时,按下面两步在任一有 Python 的机器上打一次包。
构建环境(一次性)
# 关键:必须用【自带 tkinter】的 Python 建 venv,否则打出的 exe 里 tkinter 会缺失
python -m venv <某路径>/dup-build
<某路径>/dup-build/Scripts/python.exe -m pip install pyinstaller打包
<某路径>/dup-build/Scripts/python.exe gui/make_exe.py
# 约 25~40 秒,产物在 gui/dist/,拷到任意位置即可运行make_exe.py 会自动完成:生成图标(可选)→ 组装 PyInstaller 参数 → 打包 → 清理中间产物。它已经帮你处理好了三个关键点:--add-data ui.html(界面文件必须随包)、--noconsole (隐藏黑窗口,才像正常软件)、以及显式 --hidden-import tkinter*(因为 app.py 里 tkinter 是惰性导入写在函数内部,PyInstaller 静态分析扫不到)。图标是可选步骤 —— 脚本发现没有 app.ico 会自动调 make_icon.py 生成,生成失败也照样能打包,只是 exe 用默认图标。包名与版本信息分别来自 --name 与 version_info.txt。
打包必踩的五个坑
console=False的 exe 里sys.stdout is None,所有print()直接抛异常。- 全项目统一用
safe_print()(内部判断sys.stdout is not None)。 - 目录选择框的返回值绝不能走 stdout(无控制台时拿不到),改为:父进程建临时文件 →
- 全项目统一用
把路径作为 argv 传给 exe --pick-folder <tmpfile> → 子进程写文件 → 父进程读取。
- 打包后路径要分两套。
RES_DIR = sys._MEIPASS(放 ui.html 等资源),
APP_DIR = os.path.dirname(sys.executable)(放日志,用户看得见)。用 res_path() 取资源。
ctypes.windll.xxx的返回值默认是 32 位c_int,句柄会被截断。
核验图标/模块句柄时必须显式设 restype = ctypes.c_void_p,否则 FindResourceW 永远返回 0,误判成"没有图标"。
wmic在新版 Windows 已被移除。 查/杀进程改用tasklist /FO CSV /NH+
taskkill /F /PID(输出编码用 gbk)。
- 从 Git Bash 用
cmd //c start "" "中文名.exe"启动会失败(中文文件名转换被搞乱),
直接 ./"中文名.exe" --no-browser & 即可。另外 env -i 清空环境会让单文件版无法解包(需要 TEMP),这不是 bug。排查崩溃先看 exe 同级的 startup.log(log_startup() 写入)。
已知限制(如实告知用户):
- 自建 exe 没有代码签名,首次运行可能被 SmartScreen/杀软拦(点「更多信息 → 仍要运行」即可)。
- 单文件版启动需向系统临时目录解包(约 1~3 秒),系统 TEMP 必须可写。
把这份技能分享给别人
三种分发形态,按对方情况选:
| 方式 | 对方需要什么 | 怎么给 |
|---|---|---|
| 本技能包(zip) | 装了 WorkBuddy / 支持 skill 的客户端 | 把整个技能目录压成 zip,对方在「添加技能 → 上传技能」里拖入即可 |
| 单文件 exe | 只要有 Windows,什么都不用装 | 按上一节自建后,把 exe 发过去 |
| 开源仓库 | 能访问 GitHub | 推到仓库后,别人用 npx skills add <owner/repo>@duplicate-file-cleaner 安装 |
打包成可分发的 zip 时:
- 要包含
SKILL.md、README.md、LICENSE.md、gui/、scripts/ - 要排除
gui/build/、gui/__pycache__/、gui/dist/(重打包产物)、logs/、startup.log - 排除项可以用一条命令清掉:
rm -rf gui/build gui/__pycache__ gui/dist logs gui/startup.log
命令速查
# —— 命令行三件套(只需标准库)——
python scripts/demo_hardlink.py # 原理演示(隔离目录,用完自删)
python scripts/dedup_hardlink.py --self-test # 自检
python scripts/scan_dupes.py "<目标目录>" "<输出目录>" # 扫描 + 报告
python scripts/dedup_hardlink.py --root "<目标目录>" --plan # 生成计划(干演)
python scripts/dedup_hardlink.py --root "<目标目录>" --plan --apply # 执行
python scripts/dedup_hardlink.py --verify # 校验
# —— 图形界面 ——
python scripts/run_gui.py # 启动(自动定位 gui/app.py)
# —— 回归测试 ——
python scripts/test_tool.py # 端到端(造临时数据,测完自清)
python scripts/test_exts.py # 扩展名过滤回归
# —— 查看某文件被哪些路径共享 ——
fsutil hardlink list "<文件路径>" # Windows
stat -c '%i %n' <文件路径> # Linux/macOS 看 inode长期机制建议
扫描脚本可做成每周 / 每两周自动跑的定时任务,出报告 + 可选自动硬链接去重。跨目录去重(例如微信目录 vs 用户工作目录)通常收益最大的一层,需先取得用户的工作目录清单。