文件去重器 - 查找并移除重复文件

Vernox 实用工具技能 - 清理您的数字囤积物。

概述

文件去重器是一款智能的文件重复项查找与移除工具。它通过内容哈希来识别跨目录的相同文件，然后提供安全移除重复项的选项。

功能特点

✅ 重复项检测

• 基于内容的哈希（MD5）以实现快速比较
• 基于大小的检测（精确匹配、近似匹配）
• 基于名称的检测（相似文件名）
• 目录扫描（递归）
• 排除特定模式（如 .git、node_modules 等）

✅ 移除选项

• 自动删除重复项（保留最新/最旧）
• 删除前进行交互式审阅
• 移至归档而非直接删除
• 保留权限和元数据
• 试运行模式（预览更改）

✅ 分析工具

• 重复项计数摘要
• 空间节省估算
• 最大重复文件
• 最常见的重复模式
• 详细报告生成

✅ 安全特性

• 删除前确认提示
• 备份至归档文件夹
• 大小阈值（防止误删大文件）
• 白名单重要目录
• 撤销功能（恢复日志）

安装

clawhub install file-deduplicator

快速开始

查找目录中的重复项

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}`);

自动移除重复项

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}`);

模拟运行预览

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（数组|字符串，必需）：要扫描的目录路径
• 选项（对象，可选）：
  • method（字符串）：'content' | 'size' | 'name' - 比较方法
  • includeSubdirs（布尔值）：是否递归扫描（默认：true）
  • minSize（数字）：最小文件大小，单位为字节（默认：0）
  • maxSize（数字）：最大文件大小，单位为字节（默认：0）
  • excludePatterns（数组）：要排除的全局模式（默认：['.git', 'node_modules']）
  • whitelist（数组）：永不扫描的目录（默认：[]）

返回值：

• duplicates（数组）：重复文件组的数组
  • duplicateCount（数字）：找到的重复文件组数量
  • totalFiles（数字）：扫描的文件总数
  • scanDuration（数字）：扫描所用时间（毫秒）
  • spaceWasted（数字）：重复文件浪费的总字节数
  • spaceSaved（数字）：如果删除重复文件，可能节省的空间

removeDuplicates

根据扫描结果移除重复文件

参数：

• directories（数组|字符串，必需）：与 findDuplicates 相同
• options（对象，可选）：
  • keep（字符串）：'newest' | 'oldest' | 'smallest' | 'largest' - 保留哪个文件
  • action（字符串）：'delete' | 'move' | 'archive'
  • archivePath（字符串）：当 action='move' 时，文件移动的目标位置
  • dryRun（布尔值）：预览操作，但不实际执行
  • autoConfirm（布尔值）：自动确认删除操作
  • sizeThreshold（数值）：不要删除大于此大小的文件

返回：

• filesRemoved（数值）：已移除/移动的文件数量
• spaceSaved（数值）：节省的字节数
• groupsProcessed（数值）：已处理的重复文件组数量
• logPath（字符串）：操作日志的路径
• errors（数组）：遇到的任何错误

analyzeDirectory

分析单个目录中的重复文件。

参数：

• directory（字符串，必需）：目录路径
• options（对象，可选）：与 findDuplicates 选项相同

返回：

• fileCount（数值）：目录中的文件总数
• totalSize（数字）：目录总字节数
• 重复文件大小（数字）：重复文件的字节数
• 重复比例（数字）：重复文件的百分比

使用场景

数字囤积清理

• 查找重复的照片/视频
• 识别浪费的存储空间
• 移除旧重复文件，保留最新版本
• 清理下载文件夹

文档管理

• 查找重复的PDF、文档、报告
• 保留最新版本，归档旧版本
• 防止版本混淆
• 减少备份膨胀

项目清理

• 查找重复的源文件
• 移除重复的构建产物
• 清理 node_modules 重复项
• 节省 SSD/HDD 存储空间

备份优化

• 查找重复的备份文件
• 删除冗余备份
• 识别实际重复的内容
• 节省备份驱动器空间

配置

编辑config.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）

示例

查找文档中的重复项

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`);
});

删除重复项，保留最新版本

const result = await removeDuplicates({
  directories: '~/Documents',
  options: {
    keep: 'newest',
    action: 'delete'
  }
});

console.log(`Removed ${result.filesRemoved} files`);
console.log(`Saved ${result.spaceSaved} bytes`);

移至归档而非直接删除

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`);

模拟运行预览更改

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个文件）：<1秒
• 中型目录（1000-10000个文件）：1-5秒
• 大型目录（10000+个文件）：5-20秒

检测准确率

• 基于内容：100%（完全重复文件）
• 基于大小：快速但可能遗漏重命名文件
• 基于名称：仅检测命名模式

内存使用

• 哈希缓存：每10万个文件约占用1MB内存
• 批量处理：每次处理1000个文件
• 峰值内存：处理100万个文件约占用200MB

安全特性

文件大小阈值

不会删除超过可配置阈值（默认：10MB）的文件。防止意外删除重要的大文件。

归档模式

将文件移至归档目录而非直接删除。无数据丢失，完全可恢复。

操作日志

所有删除/移动操作均记录到日志文件中，便于恢复和审计。

撤销功能

可使用日志文件恢复意外删除的文件（撤销窗口有限）。

错误处理

权限错误

• 清晰的错误提示
• 建议使用sudo权限运行
• 跳过无法访问的文件

文件锁定错误

• 检测被锁定的文件
• 跳过并报告
• 建议关闭使用文件的应用程序

空间错误

• 删除前检查可用磁盘空间
• 空间严重不足时发出警告
• 防止磁盘满的情况

故障排除

未找到预期的重复项

• 检查检测方法（内容、大小、名称）
• 验证排除模式是否过于宽泛
• 检查文件是否在白名单目录中
• 尝试设置 includeSubdirs: false

删除操作无效

• 检查目录的写入权限
• 确认操作不是 'delete' 且 autoConfirm: true
• 检查大小阈值是否阻止了所有删除操作
• 检查文件锁定（是否有其他程序在使用文件？）

扫描速度慢

• 减少 includeSubdirs 的范围
• 使用基于大小的检测（更快）
• 排除大型目录（node_modules、.git）
• 逐个处理目录而非批量处理

提示

最佳实践

• 对文档使用基于内容的检测（100%准确）
• 先运行试用以预览更改
• 对重要文件进行归档而非删除
• 检查日志以防意外删除

性能优化

• 优先处理常用目录
• 使用大小阈值跳过大型媒体文件
• 扫描时排除隐藏目录
• 尽可能并行处理目录

空间管理

• 定期清理重复文件防止存储膨胀
• 定期删除临时目录
• 清理下载文件夹中的安装程序
• 大型扫描前清空回收站

路线图

• 通过图像相似性检测重复文件
• 近重复检测（相似但不完全相同）
• 跨网络驱动器重复检测
• 云存储集成（S3、Google Drive）
• 自动安排扫描
• 启发式重复检测（基于机器学习）
• 从备份恢复已删除文件
• 基于文件内容相似度的重复检测（不仅限于哈希值）

许可证

MIT

查找重复文件。节省空间。保持系统整洁。🔮