📝 Supplementary documentation for beginners

GUIDE.md

@@ -0,0 +1,163 @@
+# Mole Mac 清理工具 - 小白使用指南
+
+> 一个完全不懂技术的 Mac 用户也能轻松使用的清理工具教程
+
+## 第一步：打开终端
+
+终端是 Mac 自带的一个工具，用来输入命令操作电脑。
+
+**方法一：快捷键（推荐）**
+
+1. 按下键盘上的 `Command (⌘)` + `空格键`
+2. 在弹出的搜索框中输入 `终端` 或 `Terminal`
+3. 按回车键，会打开一个黑色或白色的窗口
+
+**方法二：应用程序**
+
+1. 打开"访达"（Finder）
+2. 点击左侧的"应用程序"
+3. 找到"实用工具"文件夹
+4. 双击"终端"图标
+
+> 💡 小提示：这个窗口看起来可能有点专业，但别担心，接下来的操作都很简单！
+
+---
+
+## 第二步：安装 Mole
+
+1. **复制安装命令**
+   用鼠标选中下面这一行，然后按 `Command (⌘)` + `C` 复制：
+
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
+   ```
+
+2. **粘贴到终端**
+   - 在终端窗口中，按 `Command (⌘)` + `V` 粘贴
+   - 或者右键点击终端窗口，选择"粘贴"
+
+3. **开始安装**
+   - 按下 `回车键`
+   - 等待几秒钟，会自动安装完成
+   - 看到类似"安装成功"的提示就完成了
+
+> ⚠️ 注意：第一次安装可能会要求你输入 Mac 的登录密码（输入时不会显示任何字符，这是正常的）
+
+---
+
+## 第三步：开始使用
+
+1. **启动 Mole**
+   在终端中输入以下命令并按回车：
+
+   ```bash
+   mole
+   ```
+
+2. **了解界面操作**
+   - 用键盘的 `↑` `↓` 方向键 选择菜单项
+   - 按 `空格键` 选中或取消选中
+   - 按 `回车键` 确认执行
+   - 按 `q` 键退出当前界面
+
+---
+
+## 第四步：常见操作
+
+### 清理垃圾文件
+
+**安全预览模式（推荐第一次使用）：**
+
+```bash
+mole clean --dry-run
+```
+
+这个命令只会**显示**哪些文件会被清理，**不会真的删除**。你可以先看看效果再决定。
+
+**正式清理：**
+
+```bash
+mole clean
+```
+
+会清理系统缓存、日志、临时文件等，释放磁盘空间。
+
+### 卸载应用（彻底删除）
+
+```bash
+mole uninstall
+```
+
+这个功能会：
+
+- 显示你电脑上所有已安装的应用
+- 用方向键选择要卸载的应用
+- 按空格键标记（可以多选）
+- 按回车确认删除
+- **会连同应用的残留文件一起删除**
+
+### 查看帮助
+
+```bash
+mole --help
+```
+
+可以查看所有可用的命令和说明。
+
+---
+
+## 第五步：注意事项
+
+### 建议做的事
+
+- **第一次使用先用 `--dry-run` 预览**，看看会清理什么
+- **定期清理**，比如每个月或磁盘快满的时候
+- **卸载应用前确认**，避免误删正在使用的软件
+
+### 不要做的事
+
+- 不要频繁清理（一周一次足够了）
+- 不要删除系统应用（工具会自动保护，但还是要注意）
+- 不要在运行重要程序时清理缓存
+
+### 安全保障
+
+Mole 有智能保护机制：
+
+- 不会删除系统关键文件
+- 会跳过正在运行的应用
+- 清理前会显示即将删除的内容
+
+---
+
+## 常见问题
+
+### 为什么输入密码时看不到字符？
+
+这是 Mac 终端的安全设计，密码不会显示，直接输入后按回车就行。
+
+### 安装失败怎么办？
+
+1. 检查网络连接是否正常
+2. 尝试重新运行安装命令
+3. 如果还不行，可以去 [GitHub Issues](https://github.com/tw93/mole/issues) 寻求帮助
+
+### 清理后能恢复吗？
+
+一般的缓存文件清理后会自动重新生成，但应用卸载后无法恢复，请谨慎操作。
+
+### 多久清理一次比较好？
+
+- 磁盘空间充足：1-2 个月一次
+- 磁盘快满了：立即清理
+- 日常使用：看个人习惯
+
+---
+
+## 需要更多帮助？
+
+- [GitHub 项目主页](https://github.com/tw93/mole)
+- [提交问题反馈](https://github.com/tw93/mole/issues)
+- [完整使用文档](./README.md)
+
+**祝你使用愉快！如果觉得有用，欢迎分享给朋友 ✨**

README.md

@@ -6,7 +6,7 @@
 
 ## Highlights
 
-- 🦡 **Deep System Cleanup** - Remove hidden caches, logs, and temp files in one sweep
+- 🐦 **Deep System Cleanup** - Remove hidden caches, logs, and temp files in one sweep
 - 📦 **Smart Uninstall** - Complete app removal with all related files and folders
 - ⚡️ **Fast Interactive UI** - Arrow-key navigation with pagination for large lists
 - 🧹 **Massive Space Recovery** - Reclaim 100GB+ of wasted disk space
@@ -17,6 +17,8 @@
 curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
 ```
 
+> 📖 **不会用终端？** 查看 [小白使用指南](./GUIDE.md) 了解详细的图文教程
+
 ## Usage
 
 ```bash
@@ -99,6 +101,9 @@ Select Apps to Remove
 **Protect Important Files:** Create `~/.config/mole/whitelist` to preserve critical caches:
 
 ```bash
+# View current whitelist
+mole clean --whitelist
+
 # Example: Protect Playwright browsers and build tools
 echo '~/Library/Caches/ms-playwright*' >> ~/.config/mole/whitelist
 ```