---
name: disk-cleaner
description: Mac 智能磁盘清理助手，基于 Mole (https://github.com/tw93/Mole) 的用户友好包装器
---

# Disk Cleaner - Mac 智能磁盘清理助手

基于 Mole (https://github.com/tw93/Mole) 的用户友好包装器，负责「安装 + 执行 + 解释 + 把关 + 指路 + 统计 + 分享」。

## Description

Disk Cleaner 是对 tw93 开发的 Mole 清理工具的增强封装。它提供了更友好的中文界面、分类报告、三档清理策略（Air/Pro/Max）、CSV 完整清单、白名单配置，以及清理完成后的精美成就页面（包含省钱计算和趣味统计）。

## When to Use

Use this skill when users:
- 说硬盘空间不够、磁盘满了、存储不足
- 想清理 Mac 缓存或临时文件
- 询问如何释放磁盘空间
- 提到 Mole 工具

## Features

- **🔍 环境检测**: 自动检测 Homebrew 和 Mole 安装状态
- **📦 自动安装**: 支持一键安装缺失依赖
- **📊 分类报告**: 按类别展示可清理项目，区分安全/谨慎
- **🧭 三档策略**: Air（最安全）/ Pro（推荐）/ Max（最大化）
- **📋 CSV 清单**: 生成完整文件清单，保存到桌面
- **⚙️ 白名单配置**: 预设模板 + 自定义路径保护
- **🎉 成就页面**: 清理后展示省钱计算、趣味统计、可分享
- **🔒 安全保护**: 显示已保护项目，支持确认机制

## Usage

### 环境检查

```bash
python scripts/mole_cleaner.py --check
```

### 预览清理内容

```bash
python scripts/mole_cleaner.py --preview          # 终端文本报告
python scripts/mole_cleaner.py --preview --html   # HTML 报告（自动打开浏览器）
python scripts/mole_cleaner.py --preview --csv    # CSV 完整清单（保存到桌面）
python scripts/mole_cleaner.py --preview --json   # JSON 格式输出
```

### 执行清理（三档选择）

```bash
python scripts/mole_cleaner.py --clean --tier air --confirm   # Air: 最安全
python scripts/mole_cleaner.py --clean --tier pro --confirm   # Pro: 推荐
python scripts/mole_cleaner.py --clean --tier max --confirm   # Max: 最大化
python scripts/mole_cleaner.py --clean --confirm              # 默认全量清理
```

### 白名单配置

```bash
python scripts/mole_cleaner.py --whitelist --show                    # 查看当前白名单
python scripts/mole_cleaner.py --whitelist --preset office           # 添加白领办公预设
python scripts/mole_cleaner.py --whitelist --preset developer        # 添加开发者预设
python scripts/mole_cleaner.py --whitelist --add ~/Documents/重要项目  # 添加自定义路径
```

### 查看磁盘状态

```bash
python scripts/mole_cleaner.py --status
```

### 显示成就页（测试）

```bash
python scripts/mole_cleaner.py --show-achievement
```

## Workflow (Claude 交互流程)

### 1. 环境检测与安装
首先检查 Mole 是否已安装：
```bash
python scripts/mole_cleaner.py --check
```
如果未安装，引导用户安装或使用 `--auto-install`。

### 2. 预览扫描
运行预览获取分析报告：
```bash
python scripts/mole_cleaner.py --preview
```

### 3. 向用户展示选项
根据预览结果，向用户展示清理方案：

```
请选择你想执行的方案：

1. 🌬️ Air - 最安全，只清浏览器和日志     → X.XX GB
2. ⚡ Pro - 推荐，平衡安全与空间          → X.XX GB
3. 🚀 Max - 最大化释放硬盘空间            → X.XX GB
4. 📋 先看完整清单 - 生成 CSV 详细列表
5. ⚙️ 配置白名单 - 保护特定路径
```

### 4. 处理用户选择

**选择 1-3 (Air/Pro/Max)**:
```bash
# 确认后执行
python scripts/mole_cleaner.py --clean --tier air --confirm   # 或 pro/max
```

**选择 4 (CSV 清单)**:
```bash
python scripts/mole_cleaner.py --preview --csv
```
告知用户文件已保存到桌面并自动打开。

**选择 5 (白名单配置)**:
展示预设选项：
- `office`: 白领办公 - 保护 .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pdf 等
- `developer`: 开发者 - 保护代码和配置文件
- `media`: 媒体创作 - 保护视频、音频、图像项目

```bash
python scripts/mole_cleaner.py --whitelist --preset office
# 或添加自定义路径
python scripts/mole_cleaner.py --whitelist --add ~/Documents/重要项目
```

### 5. 清理完成
清理完成后自动生成成就页面，包含：
- 释放空间大小
- 省钱计算（基于 SSD 价格）
- 趣味等价物（相当于多少张照片/首歌曲）
- 随机 tw93 夸夸
- GitHub 链接方便 Star

## Safety Features

- **预览优先**: 默认只预览，需要 `--confirm` 才执行清理
- **分档策略**: Air/Pro/Max 让用户根据风险偏好选择
- **白名单保护**: 支持预设模板和自定义路径
- **保护清单**: 显示 Mole 的 whitelist 保护项目
- **日志记录**: 所有操作保存日志到 `~/.config/mole-cleaner/logs/`

## Tier Definitions

| 档位 | 清理范围 | 风险等级 |
|------|---------|---------|
| 🌬️ Air | 浏览器缓存、系统日志 | 低风险 |
| ⚡ Pro | Air + 用户应用缓存、包管理器缓存、废纸篓 | 中等风险 |
| 🚀 Max | 所有可清理项目 | 较高风险 |

## Whitelist Presets

| 预设 | 保护内容 |
|------|---------|
| office | 办公文档 (.doc, .docx, .xls, .xlsx, .ppt, .pptx, .pdf, .pages, .numbers, .key) |
| developer | 代码和配置 (.py, .js, .ts, .go, .rs, .java, .swift, .json, .yaml, .toml) |
| media | 媒体项目 (.psd, .ai, .sketch, .fig, .aep, .prproj, .fcpx, .mov, .mp4) |

## Dependencies

- macOS
- Homebrew
- Mole (`brew install tw93/tap/mole`)
- Python: `pip install jinja2`

## Output Structure

```
~/.config/mole-cleaner/
├── logs/                    # 操作日志
├── reports/                 # HTML 报告
└── achievements/            # 成就页面

~/Desktop/
└── mole-clean-list-YYYYMMDD-HHMMSS.csv  # CSV 完整清单
```

## Credits

- **Mole**: https://github.com/tw93/Mole
- **作者**: tw93 (https://tw93.fun)