English | 简体中文
Windows 桌面工具:列出电脑上所有已安装软件,一键调用软件官方卸载程序,卸载完成后自动扫描并清理残留的文件/文件夹与注册表项,并生成清理报告。
运行时零第三方依赖(纯 Python 标准库 + ctypes/Win32 API + tkinter),打包后是单个 exe。
适用平台:Windows 10 / 11 | 源码运行需 Python 3.8+ | 许可证:MIT
常见的软件卸载存在两类问题:一是卸载程序本身"不干净",卸载后在 Program Files、AppData、ProgramData 和注册表中留下大量残留;二是部分流氓软件的卸载器会卡住不退出,甚至反复弹窗。
CleanSweep 的思路是"官方卸载 + 兜底清理 + 全程可控":
- 读取注册表 4 个 Uninstall 键(HKLM/HKCU × 原生/WOW6432Node)枚举全部已安装软件;
- 先运行软件官方卸载程序完成正常卸载(支持 MSI / Inno Setup / NSIS 及任意自定义卸载器);
- 等待阶段有硬超时、心跳日志和一键强杀,流氓卸载器卡不住它;
- 卸载完成后自动扫描残留候选,经用户逐项确认后删除(默认进回收站);
- 全程自动备份(注册表 .reg 导出 + 可选系统还原点),并生成清理报告。
| 功能 | 说明 |
|---|---|
| 软件列表 | 名称、发布者、安装位置、大小(后台实测目录体积)、安装日期 |
| 排序与搜索 | 点击任意列标题排序(大小/日期/风险默认从大到小),顶部搜索框实时过滤 |
| 彻底卸载 | 官方卸载 → 残留扫描 → 逐项确认 → 删除 → 生成报告 |
| 残留扫描 | Program Files、Program Files (x86)、%LocalAppData%、%APPDATA%、%ProgramData%、%LocalAppData%\Programs、开始菜单;注册表 HKLM\SOFTWARE、HKLM\SOFTWARE\WOW6432Node、HKCU\Software |
| 残留风险等级 | 高/中/低三档启发式评分,列表着色,高风险软件卸载前红色重点提醒 |
| 防卡死设计 | 60 秒硬超时、10 秒心跳日志、「强制结束卸载进程并继续」一键强杀、批量日志刷新、扫描可取消(详见下节) |
| 备份与恢复 | 删除注册表前自动 reg export 为 .reg(双击即可还原);可选创建系统还原点;文件默认删除到回收站 |
| 清理报告 | 每次操作生成 Markdown 报告,列出删除的每个文件/文件夹(含文件数、大小)和每个注册表键及备份位置 |
| 资料文件清理 | 一键查找本机的图片、Word/PPT/Excel 文档、PDF、文本、音视频、压缩包(v1.1.0 新增,详见下文) |
主窗口点击 「资料清理(图片/文档/PPT…)」 打开独立窗口:
- 选类别:图片(jpg/png/heic…)、文档(doc/docx/ppt/pptx/xls/xlsx/wps…)、PDF、文本、音视频、压缩包,任意组合;
- 选范围:默认扫描用户常用目录(桌面/文档/下载/图片/视频,自动识别重定向位置),可添加任意文件夹;系统与程序目录默认跳过(扫描快、噪音少),扫描本身全程只读、可随时取消;
- 逐项确认:结果列表显示类别/大小/修改时间/创建时间/路径;点击列标题即可排序(再次点击切换升降序,时间/大小默认降序);单击图片行,右侧立即显示缩略图预览(GDI+ 解码,无需第三方库),拖动列表与预览之间的分隔条或缩放窗口,图片会按面板实际大小自动重新生成;双击行用系统默认程序打开(看大图/Office 文档),另有「打开所在位置」按钮;默认一项都不勾选,勾选后才可删除;
- 删除:默认删除到回收站(可还原),"永久删除"需要额外一次确认;删除在工作线程执行并生成 Markdown 清理报告。
这是直接面向个人资料的删除功能,请务必先核对路径再勾选;不确定的项目宁可保留。
窗口左上角随时可点 「← 返回卸载主界面」 回到软件列表(关闭窗口等效)。
对某些"流氓"软件(如哔哩哔哩 PC 客户端)执行彻底卸载时,程序彻底卡死、界面无响应,只能从任务管理器强杀整个进程。
排查确认是三个问题叠加,其中第 1 条是真正的死锁链核心:
- 日志逐条阻塞工作线程。卸载流程的每条日志都通过
call_in_main()提交到 Tk 主线程执行,并调用threading.Event.wait()阻塞等待。一旦主线程被模态对话框占住(例如一个被流氓卸载器的置顶窗口挡住、用户看不见的确认框),事件队列就停止消费,工作线程永远卡在wait()上——形成死锁。 - 静默等待无反馈。等待官方卸载程序退出 120 秒、再轮询注册表条目 300 秒,期间一条日志都不输出,也没有任何干预手段。不退出的卸载器会让界面看起来彻底死机。
- 启动阶段不可逃逸。
ShellExecuteExW(带SEE_MASK_NOASYNC)在弹出 UAC 或遇到畸形卸载器时会在工作线程内同步阻塞,此时连"取消"按钮都无法生效。
| 问题 | 修复 |
|---|---|
| 日志阻塞死锁 | 日志改为线程安全缓冲区,主线程定时器每 0.3 秒批量刷新一次;工作线程写日志永不阻塞,死锁链彻底拆除 |
| 超长静默等待 | 等待官方卸载程序最长 60 秒,期间每 10 秒输出一次心跳日志(带时间戳),用户随时知道程序还活着 |
| 卡住无干预手段 | 日志窗口新增 「强制结束卸载进程并继续」 按钮:点击后 ≤1 秒内 taskkill /F /T 结束卸载进程树并直接进入残留扫描;等待超时也会自动强杀 |
| 强杀误伤风险 | 强杀前先用「卸载命令 + 安装目录顶层 exe」推导进程名,经 tasklist 精确匹配正在运行的进程后逐个结束;系统进程(explorer.exe、svchost.exe、csrss.exe…)、各类浏览器、Python/本工具自身在硬编码保护名单中永不被杀;推导不出进程名时跳过强杀,仅提示手动处理 |
msiexec 特殊处理 |
强杀 Windows Installer 事务可能损坏其数据库,因此 MSI 超时不自动强杀,由用户在界面二次确认后仅结束该 MSI 事务的 PID |
| 启动阶段阻塞 | ShellExecuteExW 移入独立启动线程,UAC 卡死不再拖住流程线程 |
| 扫描不可取消 | scan_filesystem / scan_registry 支持取消检查点,扫描中可随时点「取消整个流程」 |
| 窗口被挡"假死" | 所有对话框弹出前强制提到最前并短暂置顶,防止被流氓卸载器的窗口挡住造成无响应假象 |
- 启动后自动加载软件列表并后台评估每个软件的「残留风险」(列表着色:红=高、橙=中、绿=低)。
- 点击列标题可按 大小 / 安装日期 / 风险 / 名称 / 发布者 排序;顶部搜索框实时过滤。
- 选中软件后下方显示详情(版本、注册表条目、卸载命令、风险原因)。
- 彻底卸载:确认对话框 →(可选)创建还原点 → 运行官方卸载程序(最长等待 60 秒,卡住可一键强杀)→ 自动扫描残留(可取消)→ 在残留清单中逐项勾选 → 选择「删除到回收站」或「永久删除」→ 生成报告。
- 仅扫描残留:不运行卸载程序,只列出候选残留(适合清理"失效条目")。
- 报告位于
文档\CleanSweepReports\<时间>_<软件名>\清理报告.md,同目录registry-backup\内是所有被删注册表键的.reg备份(双击导入即可还原)。 - 资料清理(v1.1.0):主窗口点「资料清理」→ 选类别与目录 → 开始扫描 → 勾选文件 → 删除(默认回收站),生成独立报告。
- 两段确认:卸载前确认 + 残留清单逐项勾选后再次最终确认(默认勾选项可取消)。
- 路径硬白名单:只可能删除标准软件目录之下的内容;
Windows、Microsoft、Package Cache、Common Files、Users等受保护目录名出现在路径任何一段即拒绝;用户桌面/文档/下载等目录永远不在扫描范围。自定义盘符上只放行该软件自己的安装目录。 - junction/符号链接防护:删除时只移除链接本身,绝不进入链接目标。
- 回收站优先:文件/文件夹默认进回收站(可还原),永久删除需主动选择。
- 注册表先备份后删除:
reg export失败时跳过删除并记录;仅允许HKLM\SOFTWARE、HKLM\SOFTWARE\WOW6432Node、HKCU\Software之下的键。 - 系统还原点:勾选后在卸载前通过
Checkpoint-Computer创建(需管理员)。 - 进程强杀保护名单:见上节修复方案表格。
- 删除操作的固有风险:文件默认进回收站可还原,但「永久删除」不可恢复;注册表删除虽有
.reg备份,请仍以人工确认为准。 - 强杀进程的代价:被强杀的软件进程会有未保存数据丢失;强杀
msiexec可能损坏 Windows Installer 数据库(工具已对此做二次确认并默认禁止自动强杀)。 - 启发式匹配:残留候选由名称特征推导,存在漏报与极小概率误报——请逐项阅读路径后再勾选,宁可不删。
- 系统还原点受 Windows 限制:24 小时内只会创建一次;进行批量卸载前,建议在「系统保护」中手动创建一个还原点。
- 杀毒软件误报:PyInstaller 打包的未签名 exe 可能被杀软/SmartScreen 拦截,属常见误报;可从源码运行或自行签名。
- 适用边界:不处理 UWP/商店应用;请勿用于清理系统组件与驱动(隐藏的系统条目已默认过滤)。
- 资料清理直接面向个人文档与照片:勾选前请逐项核对路径;默认只扫用户常用目录、默认进回收站,但「永久删除」不可恢复;删除后可在
CleanSweepReports查看报告。
git clone https://github.com/Yangxbao/CleanSweep.git
cd CleanSweep
run.bat或直接 python main.py。启动时会弹 UAC 询问是否以管理员身份运行——建议选"是",否则无法清理 HKLM 注册表项和 Program Files(受限模式仍可运行,也可 python main.py --no-elevate 跳过询问)。
双击 build.bat,或手动执行:
pip install pyinstaller
pyinstaller --noconfirm --clean --onefile --windowed --uac-admin --name CleanSweep main.py产物:dist\CleanSweep.exe(单文件)。--windowed 不显示控制台;--uac-admin 启动时自动请求管理员权限;自定义图标加 --icon=app.ico。
CleanSweep/
├── main.py # 入口:管理员提权 + 启动 GUI
├── run.bat # 双击从源码运行
├── build.bat # 一键打包为 dist\CleanSweep.exe
├── requirements.txt # 运行时无第三方依赖
├── app/
│ ├── winutil.py # Win32 API:提权/ShellExecuteEx/回收站/junction/tasklist/taskkill
│ ├── matcher.py # 软件名 ↔ 文件夹/注册表键 的启发式匹配
│ ├── scanner.py # 注册表枚举已安装软件 + 目录大小统计
│ ├── leftovers.py # 残留扫描(文件系统 + 注册表)+ 风险评估,支持取消
│ ├── uninstaller.py # 调用官方卸载程序:60s 超时 + 心跳日志 + 受控强杀
│ ├── cleaner.py # 删除执行 + 硬编码安全检查
│ ├── backup.py # 注册表导出备份 + 系统还原点
│ ├── filefinder.py # 资料文件搜索:按类别查找,可取消/跳过系统目录(只读)
│ ├── cleaner_window.py# 资料清理窗口:勾选确认 + 回收站优先 + 报告
│ ├── reporter.py # 清理报告生成
│ └── gui.py # tkinter 界面:批量日志刷新 / 卸载向导 / 可取消扫描
├── docs/ # 发布说明
└── tools/selftest.py # 只读自检(不删除任何内容)
python tools/selftest.py只读验证(匹配器单元测试、安全检查用例、真实环境枚举与扫描、注册表导出、进程保护名单),不会删除任何内容。
- Microsoft Store(UWP)应用不走注册表 Uninstall 机制,不在列表中(它们也几乎不留残留)。
- "静默卸载"依赖软件提供
QuietUninstallString或属于 Inno/NSIS 家族,其余仍会弹官方界面。 - 超长路径(>260 字符)的回收站删除可能失败,报告中会记录原因。
- 界面为英文/简体中文混合(中文为主),暂无多语言切换。
| 版本 | 日期 | 内容 |
|---|---|---|
| v1.1.1 | 2026-10-11 | 资料清理界面优化:列表/预览之间可拖动分隔条(消除空白)、图片随面板大小自适应重新生成、新增返回主界面按钮 |
| v1.1.0 | 2026-10-11 | 新增资料文件清理:按类别查找图片/文档/音视频等,图片预览、创建时间排序、安全删除 |
| v1.0.0 | 2026-10-11 | 首个公开版本:彻底卸载 + 残留清理 + 防卡死设计(60 秒超时 / 强制结束 / 进程保护名单) |