介绍
# File-Deduplicator - Find and Remove Duplicates
**Vernox Utility Skill - 清理您的数字囤积。**
## 概述
File-Deduplicator 是一个智能的重复文件查找和删除工具。使用内容哈希来识别跨目录的相同文件，然后提供安全删除重复文件的选项。
## 功能
### ✅ 重复检测 - 基于内容的哈希（MD5）用于快速比较 - 基于大小的检测（精确匹配，近似匹配） - 基于名称的检测（相似文件名） - 目录扫描（递归） - 排除模式（.git, node_modules 等）
### ✅ 删除选项 - 自动删除重复文件（保留最新/最旧） - 删除前交互式审查 - 移动到存档而不是删除 - 保留权限和元数据 - 试运行模式（预览更改）
### ✅ 分析工具 - 重复文件计数摘要 - 空间节省估算 - 最大的重复文件 - 最常见的重复模式 - 生成详细报告
### ✅ 安全功能 - 删除前确认提示 - 备份到存档文件夹 - 大小阈值（防止误删大文件） - 重要目录白名单 - 撤销功能（用于恢复的日志）
## 安装
```bash clawhub install file-deduplicator ```
## 快速开始
### 查找目录中的重复文件
```javascript const result = await findDuplicates({ directories: ['./documents', './downloads', './projects'], options: { method: 'content', // content-based comparison includeSubdirs: true } });
console.log(`Found ${result.duplicateCount} duplicate groups`); console.log(`Potential space savings: ${result.spaceSaved}`); ```
### 自动删除重复文件
```javascript const result = await removeDuplicates({ directories: ['./documents', './downloads'], options: { method: 'content', keep: 'newest', // keep newest, delete oldest action: 'delete', // or 'move' to archive autoConfirm: false // show confirmation for each } });
console.log(`Removed ${result.filesRemoved} duplicates`); console.log(`Space saved: ${result.spaceSaved}`); ```
### 试运行预览
```javascript const result = await removeDuplicates({ directories: ['./documents', './downloads'], options: { method: 'content', keep: 'newest', action: 'delete', dryRun: true // Preview without actual deletion } });
console.log('Would remove:'); result.duplicates.forEach((dup, i) => { console.log(`${i+1}. ${dup.file}`); }); ```
## 工具函数
### `findDuplicates` 查找跨目录的重复文件。
**参数:** - `directories` (array|string, 必填): 要扫描的目录路径 - `options` (object, 可选): - `method` (string): 'content' | 'size' | 'name' - 比较方法 - `includeSubdirs` (boolean): 递归扫描 (默认: true) - `minSize` (number): 最小字节数 (默认: 0) - `maxSize` (number): 最大字节数 (默认: 0) - `excludePatterns` (array): 要排除的 Glob 模式 (默认: ['.git', 'node_modules']) - `whitelist` (array): 永不扫描的目录 (默认: [])
**返回:** - `duplicates` (array): 重复组数组 - `duplicateCount` (number): 找到的重复组数量 - `totalFiles` (number): 扫描的总文件数 - `scanDuration` (number): 扫描耗时 (毫秒) - `spaceWasted` (number): 重复文件浪费的总字节数 - `spaceSaved` (number): 如果删除重复文件可节省的空间
### `removeDuplicates` 根据查找结果删除重复文件。
**参数:** - `directories` (array|string, 必填): 与 findDuplicates 相同 - `options` (object, 可选): - `keep` (string): 'newest' | 'oldest' | 'smallest' | 'largest' - 保留哪个 - `action` (string): 'delete' | 'move' | 'archive' - `archivePath` (string): action='move' 时移动文件的位置 - `dryRun` (boolean): 预览而不实际执行 - `autoConfirm` (boolean): 自动确认删除 - `sizeThreshold` (number): 不删除大于此大小的文件
**返回:** - `filesRemoved` (number): 删除/移动的文件数 - `spaceSaved` (number): 节省的字节数 - `groupsProcessed` (number): 处理的重复组数 - `logPath` (string): 操作日志路径 - `errors` (array): 遇到的任何错误
### `analyzeDirectory` 分析单个目录中的重复文件。
**参数:** - `directory` (string, 必填): 目录路径 - `options` (object, 可选): 与 findDuplicates 选项相同
**返回:** - `fileCount` (number): 目录中的总文件数 - `totalSize` (number): 目录中的总字节数 - `duplicateSize` (number): 重复文件中的字节数 - `duplicateRatio` (number): 重复文件所占的百分比
## 使用场景
### 数字囤积清理 - 查找重复的照片/视频 - 识别浪费的存储空间 - 删除旧重复文件，保留最新的 - 清理下载文件夹
### 文档管理 - 查找重复的 PDF、文档、报告 - 保留最新版本，归档旧版本 - 防止版本混淆 - 减少备份膨胀
### 项目清理 - 查找重复的源文件 - 删除重复的构建产物 - 清理 node_modules 重复 - 节省 SSD/HDD 存储空间
### 备份优化 - 查找重复的备份文件 - 删除冗余备份 - 识别实际重复的内容 - 在备份驱动器上节省空间
## 配置
### 编辑 `config.json`: ```json { "detection": { "defaultMethod": "content", "sizeTolerancePercent": 0, // exact match only "nameSimilarity": 0.7, // 0-1, lower = more similar "includeSubdirs": true }, "removal": { "defaultAction": "delete", "defaultKeep": "newest", "archivePath": "./archive", "sizeThreshold": 10485760, // 10MB threshold "autoConfirm": false, "dryRunDefault": false }, "exclude": { "patterns": [".git", "node_modules", ".vscode", ".idea"], "whitelist": ["important", "work", "projects"] } } ```
## 方法
### 基于内容（推荐） - 快速 MD5 哈希 - 无论文件名如何，都能检测精确的重复项 - 适用于重命名的文件 - 非常适合文档、代码、压缩包
### 基于大小 - 比较文件大小 - 比内容哈希更快 - 适合内容哈希较慢的媒体文件 - 查找近似重复项（相似但不完全相同）
### 基于名称 - 比较文件名 - 检测相似名称的文件 - 适合查找版本重复项（file_v1, file_v2）
## 示例
### 查找文档中的重复文件 ```javascript const result = await findDuplicates({ directories: '~/Documents', options: { method: 'content', includeSubdirs: true } });
console.log(`Found ${result.duplicateCount} duplicate sets`); result.duplicates.slice(0, 5).forEach((set, i) => { console.log(`Set ${i+1}: ${set.files.length} files`); console.log(` Total size: ${set.totalSize} bytes`); }); ```
### 删除重复文件，保留最新的 ```javascript const result = await removeDuplicates({ directories: '~/Documents', options: { keep: 'newest', action: 'delete' } });
console.log(`Removed ${result.filesRemoved} files`); console.log(`Saved ${result.spaceSaved} bytes`); ```
### 移动到存档而不是删除 ```javascript const result = await removeDuplicates({ directories: '~/Downloads', options: { keep: 'newest', action: 'move', archivePath: '~/Documents/Archive' } });
console.log(`Archived ${result.filesRemoved} files`); console.log(`Safe in: ~/Documents/Archive`); ```
### 试运行预览更改 ```javascript const result = await removeDuplicates({ directories: '~/Documents', options: { dryRun: true // Just show what would happen } });
console.log('=== Dry Run Preview ==='); result.duplicates.forEach((set, i) => { console.log(`Would delete: ${set.toDelete.join(', ')}`); }); ```
## 性能
### 扫描速度 - **小型目录** (<1000 个文件): <1s - **中型目录** (1000-10000 个文件): 1-5s - **大型目录** (10000+ 个文件): 5-20s
### 检测准确性 - **基于内容:** 100%（精确重复） - **基于大小:** 速度快但可能会漏掉重命名的文件 - **基于名称:** 仅检测命名模式
### 内存使用 - **哈希缓存:** 每 100,000 个文件约 1MB - **批处理:** 每次处理 1000 个文件 - **峰值内存:** 1M 个文件约 200MB
## 安全功能
### 大小阈值 不会删除大于可配置阈值的文件（默认：10MB）。防止意外删除重要的大文件。
### 存档模式 将文件移动到存档目录而不是删除。无数据丢失，完全可恢复。
### 操作日志 所有删除/移动操作都记录到文件中，以便恢复和审计。
### 撤销功能 日志文件可用于恢复意外删除的文件（有限的撤销窗口）。
## 错误处理
### 权限错误 - 清晰的错误消息 - 建议使用 sudo 运行 - 跳过无法访问的文件
### 文件锁定错误 - 检测锁定的文件 - 跳过并报告 - 建议关闭正在使用文件的应用程序
### 空间错误 - 删除前检查可用磁盘空间 - 如果空间严重不足则警告 - 防止磁盘已满的情况
## 故障排除
### 未找到预期的重复文件 - 检查检测方法（content vs size vs name） - 验证排除模式是否过于宽泛 - 检查文件是否在白名单目录中 - 尝试使用 includeSubdirs: false
### 删除不起作用 - 检查目录的写入权限 - 验证操作不是 'delete' 且 autoConfirm: true - 检查大小阈值是否阻止了所有删除 - 检查文件锁定（是否有其他程序正在使用文件？）
### 扫描缓慢 - 减少 includeSubdirs 范围 - 使用基于大小的检测（更快） - 排除大目录（node_modules, .git） - 单独处理目录而不是批量处理
## 提示
### 最佳效果 - 对文档使用基于内容的检测（100% 准确） - 首先运行试运行以预览更改 - 将重要文件归档而不是删除 - 如果意外删除了任何内容，请检查日志
### 性能优化 - 首先处理常用目录 - 使用大小阈值跳过大型媒体文件 - 从扫描中排除隐藏目录 - 尽可能并行处理目录
### 空间管理 - 定期清理重复文件可防止存储膨胀 - 定期删除临时目录 - 清理下载文件夹中的安装程序 - 在大型扫描前清空回收站
## 路线图
- [ ] 通过图像相似度进行重复检测 - [ ] 近似重复检测（相似但不完全相同） - [ ] 跨网络驱动器的重复检测 - [ ] 云存储集成（S3, Google Drive） - [ ] 自动安排扫描 - [ ] 启发式重复检测（基于 ML） - [ ] 从备份恢复已删除的文件 - [ ] 通过文件内容相似度进行重复检测（不仅仅是哈希）
## 许可证
MIT
---
**查找重复文件。节省空间。保持系统清洁。** 🔮