重复文件审计

一个零第三方依赖的 Python 命令行工具。先按文件大小筛选候选，再计算 SHA-256，输出内容相同的文件组，帮助人工审查重复数据。工具只读取文件，不删除、移动或修改文件。

功能与适用场景

查看检查规则与边界，了解具体统计口径及限制。所有工具离线运行，运行时仅使用 Python 标准库；审计不会修改输入文件。报告输出选项可能覆盖指定报告文件。

环境要求

Python 3.10 或更新版本，支持 Windows、Linux 和 macOS。当前验收环境为 Windows；其他平台兼容性尚未实际验证。

获取与安装

git clone https://www.gitlink.org.cn/ZHENAN/duplicate-file-auditor.git
cd duplicate-file-auditor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS 激活命令为 source .venv/bin/activate。安装会用到 setuptools 构建依赖；不安装也可以直接运行下面的 Python 命令。

快速开始

python auditor.py examples --json

安装后可使用 duplicate-audit --help；直接运行 python auditor.py --help 也可查看全部参数。示例文件保存在 examples。

输出和退出码

主要报告字段：root、duplicate_groups（size_bytes、sha256、paths）、errors。

退出码：0：扫描完成（包括发现重复）；1：扫描错误；2：参数错误。发现问题或差异的示例返回非零状态属于正常业务结果，不等同于程序崩溃。详细语义及限制见行为说明。

项目结构

duplicate-file-auditor/
├── auditor.py        # 核心实现与 CLI 入口
├── tests/            # unittest 自动化测试
├── examples/         # 可直接运行的最小示例
├── docs/behavior.md  # 规则、报告及已知限制
├── pyproject.toml    # 安装元数据和命令入口
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── .gitignore
└── LICENSE

项目保持单模块结构，便于阅读和维护；测试、样例和说明分别存储。

开发与验证

python -B -m unittest discover -s tests -v

测试使用临时文件验证真实行为。重复文件项目的符号链接测试在 Windows 权限不足时跳过。贡献时请提供可复现输入和预期结果，详见贡献指南。

常见问题

如果 Windows 应用控制策略拦截安装生成的命令启动器，可使用 python -m auditor --help，或在仓库目录使用 python auditor.py --help。无需修改系统安全策略。安装时下载构建依赖失败，可先直接运行脚本，运行本身不需要第三方依赖。

数据与限制

报告可能包含输入原值或本地路径，公开分享前请检查敏感信息。工具采用内存报告，适合日常中小规模数据；大文件或大目录请评估资源开销。当前版本为 0.1.0，未承诺完整格式解析或业务规则判断。

许可证

采用 MIT 许可证。版本记录见 CHANGELOG.md。