DeepClean 🧹 深度扫描-文件清理工具

基于Electron+Vue3+Vite+FastAPI 开发的跨平台深度文件扫描清理工具.

核心功能

• 微信历史消息大附件扫描
• 系统级大文件扫描
• 用户级大文件扫描
• Python和Node等语言开发环境依赖包文件夹扫描
• AI 智能分析：对扫描出的文件/文件夹一键 AI 分析（数据来源、用途、删除风险评估、压缩/迁移建议），并支持基于分析的追问对话

AI 分析配置

AI 分析支持任何 OpenAI 兼容接口（火山方舟 Ark / OpenAI / DeepSeek / Ollama 等）。

方式一（推荐）：界面配置 —— 扫描列表点任意记录的「AI 分析」→ 弹窗右下角「AI 设置」，填写接口地址 / API Key / 模型后保存（配置持久化在 backend/.env，Key 不入库不上传）。

方式二：手动配置 —— 复制模板并填写：

cp backend/.env.example backend/.env

base_url=https://ark.cn-beijing.volces.com/api/v3
api_key=<你的Key>
model=<模型ID或推理接入点>

AI 分析使用

1. 扫描完成后，在文件列表「操作」列点击 AI 分析
2. 弹窗内自动开始流式输出四段结构化分析：① 这个数据是怎么产生的 ② 用来干嘛的/有什么用 ③ 该不该删/能否压缩 ④ 处理建议
3. 分析完成后可在底部输入框继续追问（如「删掉之后需要时怎么恢复」），AI 基于分析上下文流式回复
4. 「重新分析」按钮可重跑；「AI 设置」可随时修改模型配置

注：AI 分析走后端转发到所配置的 LLM 接口，API Key 仅保存在本地 backend/.env；前端通过 VITE_API_BASE（默认同源/代理）访问后端，开发直连模式见 frontend/.env.development。

开发计划 & TODO

• 相册最大文件扫描器
  • 其实扫描 [此处](~/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

2. 安装依赖 进入到项目根目录进行如下操作

# 安装后端依赖
pip install -r backend/requirements.txt
cd frontend && npm install

3. 运行 启动后端：

python backend/main.py start-ui --port 5173

启动前端:

npm run dev

最后, 执行如下脚本:

bash run-dev.sh

命令行版本

1. 安装Python环境 可以用Anaconda 或者 miniConda
2. 安装依赖

pip install -r requirements.txt

3. 运行脚本

Usage: main.py[OPTIONS]
COMMAND[ARGS]...

Options:
--help
Show
this
message and exit.

Commands:
compare
比较两个文件的内容是否一致(有利于, 同内容不同名文件的比较和唯一性确认和重复率计算)
scan
浅扫描(目录级普通扫描)
smart - deep - scan
深度智能扫描(包含微信文件扫描 + MacOS相册扫描)