磁盘清理大虾

安全、智能、说人话的磁盘清理 AI Agent。

不是清理脚本，是可运行的桌面 AI 清理 Agent。

本地扫描 → 风险分级 → LLM 智能规划 → 隔离区执行， 帮助用户安全地发现空间问题、理解清理建议，逐步完成磁盘治理。

快速开始 · 能力速览 · 架构设计 · API 参考 · 版本路线

打开软件，一键扫描，DiskClaw 自动完成整个分析链路：

用户操作：选择目录 → 点击「一键扫描」

DiskClaw 自动执行：
  扫描阶段:  递归遍历目录，按类型分类（缓存/临时/日志/安装包/大文件/陈旧文件）
  分析阶段:  识别重复文件、热点目录，白名单保护系统路径，三级风险评估
  LLM 规划:   将分析结果发给 AI，生成用户能看懂的清理建议和优先级
  清理执行:  隔离区（默认）、归档、回收站、永久删除、DryRun — 五种模式可选

• AI 智能规划 — 接入第三方 LLM（OpenAI 兼容 API），自动生成清理方案和用户友好说明；LLM 不可用时自动降级为纯本地分析
• 安全优先 — 默认隔离区模式，文件先移入 .diskclaw/quarantine/ 而非直接删除；系统关键路径白名单保护
• 五种清理模式 — 隔离区 / 归档 / 回收站 / 永久删除 / DryRun，按需选择
• 三级风险评估 — low（可清理）/ medium（需确认）/ high（需人工审查），高风险项跳过
• 重复文件识别 — 基于文件哈希比对，自动建议保留策略
• 热点目录识别 — 找出占用空间最大的目录，优先治理
• 零运行时依赖 — 纯 Node.js 原生实现，HTTP 服务用 node:http，无需 Express/Koa 等第三方框架
• AES-256-GCM 加密 — API Key 本地加密存储，消息中脱敏显示
• Electron 桌面壳 — 系统托盘（动态状态图标）、Windows 通知、diskclaw:// 自定义协议
• 任务队列 — 异步任务支持暂停/恢复/取消，实时进度反馈
• 定时任务 — 支持每日/每周/每月自动扫描和清理
• 完整报告系统 — 自动保存所有操作报告，支持 JSON/Markdown 导出，7 天/30 天统计分析
• 配置管理 — 全量备份/恢复/出厂重置，所有状态 JSON 文件化

• Node.js ≥ 18.x（ES Modules）
• Windows 10/11（当前优先支持）
• 可选：OpenAI 兼容 API Key（不配置也能离线使用）

# 1. 克隆仓库
git clone https://github.com/Unclecheng-li/DiskClaw.git
cd DiskClaw

# 2. 安装依赖（仅 electron + electron-builder）
npm install

# 3. 本地服务模式 — 浏览器访问 http://localhost:3100
npm start

# 4. 桌面客户端模式 — Electron 窗口运行
npm run electron

在项目根目录创建 config.json，参考 config.example.json：

{
  "llm": {
    "enabled": true,
    "provider": "openai-compatible",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-your-api-key",
    "models": {
      "chat": "gpt-4.1-mini",
      "reason": "gpt-4.1",
      "summary": "gpt-4.1-mini"
    }
  },
  "scan": {
    "maxDepth": 5,
    "maxFiles": 3000,
    "largeFileThresholdBytes": 536870912,
    "staleDays": 90
  }
}

💡 不配置 LLM 也能完整使用扫描、分析和清理功能，只是跳过 AI 规划环节。

npm run electron

启动后出现 Windows 原生窗口，底部系统托盘显示动态状态图标：

托盘右键菜单支持：显示主窗口、开始扫描、暂停/恢复任务、退出。

npm start

浏览器打开 http://localhost:3100，即可使用完整功能的仪表盘界面。

┌──────────────────────────────────────────────┐
│              Electron 桌面壳                  │
│  单实例锁 | 系统托盘 | 通知 | diskclaw://协议  │
├──────────────────────────────────────────────┤
│         Node HTTP Server (port 3100)          │
│              30+ REST API 端点                │
├──────────────────────────────────────────────┤
│          DiskCleanupAgent (编排层)            │
│        scan → analyze → LLM → execute         │
├──────────────────────────────────────────────┤
│             15 个独立 Service 模块             │
│  FileScanner / ScanAnalyzer / RiskEngine      │
│  CleanupExecutor / LlmGateway / Scheduler     │
│  ReportStore / TaskStore / ConfigService ...  │
├──────────────────────────────────────────────┤
│  Utils (crypto / fs / http / validation)      │
│  存储层: .diskclaw/ 目录 (JSON 文件持久化)     │
└──────────────────────────────────────────────┘

所有接口��返回 JSON。异步任务接口返回 202 + 任务对象，同步接口返回 200。

⚠️ permanent 模式不可逆，需显式确认。高风险文件（系统路径、用户桌面/文档等）在任何模式下都会被跳过。

# 生成解包目录（调试用）
npm run pack
# 输出: dist/win-unpacked/

# 生成 Windows 安装包
npm run dist:win
# 输出: dist/DiskClaw-Setup-0.1.0.exe

安装包包含：

• NSIS 安装向导（自定义安装路径）
• 桌面快捷方式 + 开始菜单
• diskclaw:// 自定义协议注册
• 右键菜单「用磁盘清理大虾扫描」

• 本地优先：所有文件扫描和清理操作在本地完成，不上传任何文件内容到云端
• 加密存储：LLM API Key 使用 AES-256-GCM 加密后存储于 .diskclaw/master.key
• 隔离区设计：默认不删除文件，先进入隔离区，30 天自动清理
• LLM 可选：AI 功能完全可选，不配置 API Key 仍可使用完整的扫描和清理功能

MIT License