Skip to content

About

Windows 彻底卸载助手:官方卸载 + 注册表/文件残留清理 + 图片/文档资料清理,解决卸载卡死问题。Thorough uninstaller & personal file cleaner for Windows.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

CleanSweep 彻底卸载助手

English | 简体中文

Windows 桌面工具:列出电脑上所有已安装软件,一键调用软件官方卸载程序,卸载完成后自动扫描并清理残留的文件/文件夹与注册表项,并生成清理报告。

运行时零第三方依赖(纯 Python 标准库 + ctypes/Win32 API + tkinter),打包后是单个 exe。

适用平台:Windows 10 / 11 | 源码运行需 Python 3.8+ | 许可证:MIT

项目介绍

常见的软件卸载存在两类问题:一是卸载程序本身"不干净",卸载后在 Program Files、AppData、ProgramData 和注册表中留下大量残留;二是部分流氓软件的卸载器会卡住不退出,甚至反复弹窗。

CleanSweep 的思路是"官方卸载 + 兜底清理 + 全程可控":

  1. 读取注册表 4 个 Uninstall 键(HKLM/HKCU × 原生/WOW6432Node)枚举全部已安装软件;
  2. 先运行软件官方卸载程序完成正常卸载(支持 MSI / Inno Setup / NSIS 及任意自定义卸载器);
  3. 等待阶段有硬超时、心跳日志和一键强杀,流氓卸载器卡不住它;
  4. 卸载完成后自动扫描残留候选,经用户逐项确认后删除(默认进回收站);
  5. 全程自动备份(注册表 .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 新增,详见下文)

资料文件清理(v1.1.0 新增)

主窗口点击 「资料清理(图片/文档/PPT…)」 打开独立窗口:

  1. 选类别:图片(jpg/png/heic…)、文档(doc/docx/ppt/pptx/xls/xlsx/wps…)、PDF、文本、音视频、压缩包,任意组合;
  2. 选范围:默认扫描用户常用目录(桌面/文档/下载/图片/视频,自动识别重定向位置),可添加任意文件夹;系统与程序目录默认跳过(扫描快、噪音少),扫描本身全程只读、可随时取消;
  3. 逐项确认:结果列表显示类别/大小/修改时间/创建时间/路径;点击列标题即可排序(再次点击切换升降序,时间/大小默认降序);单击图片行,右侧立即显示缩略图预览(GDI+ 解码,无需第三方库),拖动列表与预览之间的分隔条或缩放窗口,图片会按面板实际大小自动重新生成;双击行用系统默认程序打开(看大图/Office 文档),另有「打开所在位置」按钮;默认一项都不勾选,勾选后才可删除;
  4. 删除:默认删除到回收站(可还原),"永久删除"需要额外一次确认;删除在工作线程执行并生成 Markdown 清理报告。

这是直接面向个人资料的删除功能,请务必先核对路径再勾选;不确定的项目宁可保留。

窗口左上角随时可点 「← 返回卸载主界面」 回到软件列表(关闭窗口等效)。

卸载流氓软件卡死问题:根因与修复(v1.0.0 重点)

现象

对某些"流氓"软件(如哔哩哔哩 PC 客户端)执行彻底卸载时,程序彻底卡死、界面无响应,只能从任务管理器强杀整个进程。

根因分析

排查确认是三个问题叠加,其中第 1 条是真正的死锁链核心:

  1. 日志逐条阻塞工作线程。卸载流程的每条日志都通过 call_in_main() 提交到 Tk 主线程执行,并调用 threading.Event.wait() 阻塞等待。一旦主线程被模态对话框占住(例如一个被流氓卸载器的置顶窗口挡住、用户看不见的确认框),事件队列就停止消费,工作线程永远卡在 wait() 上——形成死锁。
  2. 静默等待无反馈。等待官方卸载程序退出 120 秒、再轮询注册表条目 300 秒,期间一条日志都不输出,也没有任何干预手段。不退出的卸载器会让界面看起来彻底死机。
  3. 启动阶段不可逃逸。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 支持取消检查点,扫描中可随时点「取消整个流程」
窗口被挡"假死" 所有对话框弹出前强制提到最前并短暂置顶,防止被流氓卸载器的窗口挡住造成无响应假象

使用说明

  1. 启动后自动加载软件列表并后台评估每个软件的「残留风险」(列表着色:红=高、橙=中、绿=低)。
  2. 点击列标题可按 大小 / 安装日期 / 风险 / 名称 / 发布者 排序;顶部搜索框实时过滤。
  3. 选中软件后下方显示详情(版本、注册表条目、卸载命令、风险原因)。
  4. 彻底卸载:确认对话框 →(可选)创建还原点 → 运行官方卸载程序(最长等待 60 秒,卡住可一键强杀)→ 自动扫描残留(可取消)→ 在残留清单中逐项勾选 → 选择「删除到回收站」或「永久删除」→ 生成报告。
  5. 仅扫描残留:不运行卸载程序,只列出候选残留(适合清理"失效条目")。
  6. 报告位于 文档\CleanSweepReports\<时间>_<软件名>\清理报告.md,同目录 registry-backup\ 内是所有被删注册表键的 .reg 备份(双击导入即可还原)。
  7. 资料清理(v1.1.0):主窗口点「资料清理」→ 选类别与目录 → 开始扫描 → 勾选文件 → 删除(默认回收站),生成独立报告。

安全机制(删除的每一道防线)

  1. 两段确认:卸载前确认 + 残留清单逐项勾选后再次最终确认(默认勾选项可取消)。
  2. 路径硬白名单:只可能删除标准软件目录之下的内容;Windows、Microsoft、Package Cache、Common Files、Users 等受保护目录名出现在路径任何一段即拒绝;用户桌面/文档/下载等目录永远不在扫描范围。自定义盘符上只放行该软件自己的安装目录。
  3. junction/符号链接防护:删除时只移除链接本身,绝不进入链接目标。
  4. 回收站优先:文件/文件夹默认进回收站(可还原),永久删除需主动选择。
  5. 注册表先备份后删除:reg export 失败时跳过删除并记录;仅允许 HKLM\SOFTWARE、HKLM\SOFTWARE\WOW6432Node、HKCU\Software 之下的键。
  6. 系统还原点:勾选后在卸载前通过 Checkpoint-Computer 创建(需管理员)。
  7. 进程强杀保护名单:见上节修复方案表格。

⚠️ 风险提示

  • 删除操作的固有风险:文件默认进回收站可还原,但「永久删除」不可恢复;注册表删除虽有 .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 跳过询问)。

打包为 exe

双击 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 秒超时 / 强制结束 / 进程保护名单)

许可证

MIT

About

Windows 彻底卸载助手:官方卸载 + 注册表/文件残留清理 + 图片/文档资料清理,解决卸载卡死问题。Thorough uninstaller & personal file cleaner for Windows.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages