前言¶
在 DeepSeek Harness（DSH）里做本地项目或资料整理时，磁盘上常会出现「文件名不同、字节却完全一样」的副本：下载重复、备份叠加、拷贝遗漏都会留下这类文件。手工对比既慢，也容易误删仍需要的版本。
DSH 社区插件 dsh-file-dedupe（维护者 zizhuang）面向上述场景：扫描指定本地目录，用 SHA-256 内容哈希找出字节级相同的重复文件，通过可视化面板或对话工具查看结果，并把冗余副本移入可恢复的隔离区，而不是一上来就永久删除。
这是什么¶
dsh-file-dedupe 是 DSH 的客户端类插件：在宿主里提供左下角「文件查重」入口（README 中描述为浮动按钮）以及 设置 → 文件查重 配置区块，同时注册 Agent 工具 file_dedupe_scan、file_dedupe_cleanup、file_dedupe_restore。
查重判定与文件名无关：内容哈希相同即视为同一重复组；同名但内容不同不会归为一组。
插件当前版本在仓库 package.json 中为 1.0.0，许可证 MIT。社区目录页：SkillHub - dsh-file-dedupe；源码与说明：GitHub - zizhuang/dsh-file-dedupe。
工作原理¶
README 给出的流程可以概括为三步：
- 遍历目标目录，先按文件大小分组；
- 只对「同大小且存在多个成员」的候选文件计算 SHA-256（1 MiB 流式分块，避免大文件占满内存）；
- 哈希相同的文件划入同一重复组。
扫描结果包含：重复组数量、冗余文件数、可释放空间，以及每组文件清单。
核心功能¶
可视化面板¶
安装并重启或刷新 DSH 后，可在应用左下角打开文件查重面板；相关选项也在 设置 → 文件查重 中集中展示。
对话工具¶
Agent 可直接调用以下工具（参数名以 README 为准）：
file_dedupe_scan：对目录发起扫描，返回重复组与可释放空间；file_dedupe_cleanup：将选定的冗余副本移入隔离区；file_dedupe_restore：从隔离区恢复到原路径。
安全与清理策略¶
- 只处理确实属于某个重复组的路径；每个重复组至少保留一个文件。
- 通过 Agent 的
file_dedupe_cleanup只能移入隔离区；永久删除仅在面板中操作，且需二次确认。 - 隔离文件目录：
$DSH_HOME/dsh-file-dedupe/quarantine/，并记录清单；恢复时尽量回到原路径，若目标已被占用则拒绝覆盖。
安装与启用¶
README 推荐从 GitHub 安装（尚未发布到 npm，因此 add dsh-file-dedupe 暂不可用）：
dsh plugin --profile web add github:zizhuang/dsh-file-dedupe
将命令中的 web 换成你实际使用的 profile 名（如 desktop、headless、tui 等）。安装完成后重启或刷新 DSH，即可看到文件查重入口。社区插件市场收录后，也可在应用内 设置 → 插件市场 一键安装（README 说明为后续能力）。
配置¶
可在 profile 的 cordis.patch.yml 中覆盖下表字段：
| 字段 | 默认值 | 含义 |
|---|---|---|
minFileSize |
1 |
忽略小于该字节数的文件 |
maxFiles |
100000 |
单次扫描最多收录的文件数 |
maxGroups |
500 |
展示的重复组上限（按可释放空间排序） |
超大目录扫描耗时较长时，可先用 minFileSize 或 maxFiles 缩小范围。
典型用法¶
面板¶
- 打开左下角文件查重面板（或经设置进入）；
- 选择要扫描的根目录，查看重复组与可释放空间；
- 勾选要处理的冗余副本：移入隔离区，或在面板中经二次确认后永久删除；
- 需要回滚时，从隔离区恢复对应路径。
Agent 工具示例¶
README 中的调用形式如下：
file_dedupe_scan(root="D:\\file store") → 重复组清单 + 可释放空间
file_dedupe_cleanup(scanId="scan-…", paths=[…]) → 把冗余副本移入隔离区
file_dedupe_restore(paths=[…]) → 从隔离区恢复
实际 root、 scanId、paths 以扫描返回结果为准。
适用场景与注意¶
适合：本地资料库、下载目录、备份盘等需要「按内容找重复、先看能省多少空间再动手」的场景；希望在 DSH 对话里让 Agent 代扫、代隔离的用户。
务必知晓：
- 查重是字节级相同判定，不是「相似文件」或「同名文件」逻辑。
- 插件以当前 DSH 进程权限读写磁盘；安装前请自行查看 源码 与 MIT 许可证，确认路径与数据可接受。
- README 记载在 DSH 0.2.0-rc.2（Windows 桌面版）上完成安装、浮动按钮/设置面板、扫描 → 隔离 → 恢复全流程实测；其他 profile 或版本需自行验证。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-file-dedupe 把「按 SHA-256 找真重复、算可释放空间、隔离可恢复、永久删除需面板确认」串成一条可复现路径，适合在 DSH 客户端内做本地磁盘整理。
- 目录页：https://www.skillhub.cn/plugins/zizhuang/dsh-file-dedupe
- GitHub：https://github.com/zizhuang/dsh-file-dedupe
