基于Electron+Vue3+Vite+FastAPI 开发的跨平台深度文件扫描清理工具.
- 微信历史消息大附件扫描
- 系统级大文件扫描
- 用户级大文件扫描
- Python和Node等语言开发环境依赖包文件夹扫描
- AI 智能分析：对扫描出的文件/文件夹一键 AI 分析（数据来源、用途、删除风险评估、压缩/迁移建议），并支持基于分析的追问对话
- 全局 Dashboard：系统状态（磁盘/内存/交换区仪表盘）与清理成果统计（累计释放空间/删除操作/删除条目/卸载应用/清理残留）上移到 Tab 之上全局展示，任一删除成功即联动刷新；「删除历史」弹窗支持按来源筛选、分页加载与清空
- 删除历史与贡献统计：所有删除操作（文件扫描/应用卸载/残留清理）统一在后端落账 JSON（原子持久化，
DEEPCLEAN_HISTORY_PATH可注入测试路径），既可追踪删过哪些内容，也可统计该软件的贡献 - 残留清理（无主残留）：扫描已被删除的应用/文件遗留的残留（本体已不存在），按证据分级——无主 Bundle ID（未找到对应应用）与历史关联（本软件卸载过的应用，含二级目录/
~/.dotfile）默认勾选，疑似（历史删除文件的同类）需手动确认；系统组件（com.apple 等前缀）永不放行，删除目标复用卸载的安全校验（残留根内 + 名称证据 + 整体拒绝） - macOS 应用深度卸载：列出已安装应用（含版本/Bundle ID/体积/运行状态），默认按体积降序（表头可按名称/体积排序），搜索支持显示名 / 多语言别名（InfoPlist.strings，如 Finder 中的中文名）/ Bundle ID；按 Bundle ID 与应用名在
~/Library（含 Application Support 二级目录如 CrashReporter）、/Library、/private/var/db/receipts、/private/var/folders/<x>/<y>/C|T、~/Downloads、/Users/Shared/PKGs中定位全部残留（偏好设置、缓存、应用数据、沙盒容器、群组容器、网络缓存、Cookie、日志、崩溃报告、启动项、特权助手、安装收据、应用下载数据、安装包、系统临时缓存、~/.<AppName>隐藏配置），弹窗勾选确认后移入废纸篓（默认）或永久删除；卸载前可自动退出运行中的进程，支持pkgutil --forget忘记安装收据，系统目录自动提权。- 匹配分两层：强关联（Bundle ID/应用名边界匹配）默认勾选；疑似关联（如
i4ToolsDownloads这类纯包含关键字的模糊命中）与用户数据/安装包分类只列出、默认不勾选，带「疑似关联/默认未选」标签由用户确认。弹窗汇总按强关联/疑似分栏报数（列表"大小"列仅为本体口径，弹窗内"本体 N · 强关联合计 · 疑似合计"分别列示），清单中强关联项排在疑似项之前。 - 安全设计：每个删除目标经后端二次校验（必须位于允许的残留根之内 + 名称与应用边界匹配，模糊项仅限用户手动勾选且仍须在残留根内 + 符号链接解析后不得逃逸），任一目标不合法则整体拒绝、一个文件都不删；系统应用/永久删除需经「取消 / 强制执行」危险确认。
- 匹配分两层：强关联（Bundle ID/应用名边界匹配）默认勾选；疑似关联（如
AI 分析支持任何 OpenAI 兼容接口（火山方舟 Ark / OpenAI / DeepSeek / Ollama 等）。
方式一（推荐）：界面配置 —— 扫描列表点任意记录的「AI 分析」→ 弹窗右下角「AI 设置」，填写接口地址 / API Key / 模型后保存（配置持久化在 backend/.env，Key 不入库不上传）。
方式二：手动配置 —— 复制模板并填写：
cp backend/.env.example backend/.envbase_url=https://ark.cn-beijing.volces.com/api/v3
api_key=<你的Key>
model=<模型ID或推理接入点>- 扫描完成后，在文件列表「操作」列点击 AI 分析
- 弹窗内自动开始流式输出四段结构化分析：① 这个数据是怎么产生的 ② 用来干嘛的/有什么用 ③ 该不该删/能否压缩 ④ 处理建议
- 分析完成后可在底部输入框继续追问（如「删掉之后需要时怎么恢复」），AI 基于分析上下文流式回复
- 「重新分析」按钮可重跑；「AI 设置」可随时修改模型配置
注：AI 分析走后端转发到所配置的 LLM 接口，API Key 仅保存在本地
backend/.env；前端通过VITE_API_BASE（默认同源/代理）访问后端，开发直连模式见frontend/.env.development。
- 相册最大文件扫描器
- 其实扫描 [此处](~/Pictures/Photos Library.photoslibrary/) 即可.
- 微信最大文件扫描器
- 其实扫描此处即可.
- 结合到Immich的python上传脚本, 实现先上传到Immich, 然后进行删除
- 当然是先要给用户一个选择(直接删除/备份再删除本地副本)
- 大文件扫描
- 特殊文件包扫描
- Node环境依赖包(node_modules)
- .next
- Python环境(.env)
- ...
- 特殊文件包扫描
-
利用Tkinter先实现简单的可视化界面. -
后期用WPF为Windows系统出一个更完美的UI和使用体验. -
后期使用Swift给MacOS系统出一个更完美的UI和使用体验. - 得好好研究一下
/Users/shadikesadamu/Library/Caches缓存目录 - 可能后期要增加病毒扫描(初衷: 不是增加额外的功能, 而是在文件扫描时发现可疑文件, 就顺便做个警告即可.)
直接从Release中下载,安装即可使用.
首先, 克隆项目到本地:
git clone https://github.com/Haoke98/DeepClean.git- 安装依赖 进入到项目根目录进行如下操作
# 安装后端依赖
pip install -r backend/requirements.txt
cd frontend && npm install
- 运行 启动后端：
python backend/main.py start-ui --port 5173启动前端:
npm run dev开发端口动态分配：vite 从 5173 起探测空闲端口（被占用则顺延，
strictPort保证不静默退避），真实端口通过环境变量 +frontend/.dev-port文件传给 Electron；Electron 加载前会按页面标题校验"这确实是 DeepClean 的页面"，不会误加载恰好占用 5173 的其它项目。也可用DEEPCLEAN_DEV_PORT=6000 npm run dev固定端口；无 GUI 环境可用DEEPCLEAN_SKIP_ELECTRON=1只起 vite 不拉起 Electron。 最后, 执行如下脚本:
bash run-dev.sh后端测试套件在沙盒中仿真一棵 macOS 目录树（/Applications、~/Library、/Library、安装收据等）做端到端验证，不触碰真实数据，覆盖应用发现、残留精确匹配、删除目标安全校验、真实卸载与 HTTP 接口：
cd backend && python3 -m unittest tests.test_app_uninstaller -v提示：设置环境变量
DEEPCLEAN_APP_UNINSTALL_SANDBOX=<沙盒根目录>可让整个后端（列表/分析/卸载接口）指向一棵仿真 macOS 目录树，用于本机联调演示。
- 安装Python环境 可以用Anaconda 或者 miniConda
- 安装依赖
pip install -r requirements.txt- 运行脚本
Usage: main.py[OPTIONS]
COMMAND[ARGS]...
Options:
--help
Show
this
message and exit.
Commands:
compare
比较两个文件的内容是否一致(有利于, 同内容不同名文件的比较和唯一性确认和重复率计算)
scan
浅扫描(目录级普通扫描)
smart - deep - scan
深度智能扫描(包含微信文件扫描 + MacOS相册扫描)