# dsh-file-dedupe

[中文](README.md) | English

A DeepSeek Harness (DSH) plugin that finds **byte-identical duplicate files** in any local directory by **SHA-256 content hash**, then cleans them up safely.

- **Web panel** — a floating `🔍 File Dedupe` button at the bottom-left of the app (opens a modal), plus a **Settings → File Dedupe** section.
- **Agent tools** — `file_dedupe_scan`, `file_dedupe_cleanup`, `file_dedupe_restore`, so you can just ask the agent to deduplicate a folder.
- **Safe by design** — cleanup only accepts paths that belong to a duplicate group; every group keeps at least one file; the agent tool can only move files into a **reversible quarantine**; permanent deletion requires an explicit user confirmation in the panel.

## Install

Install straight from GitHub:

```bash
dsh plugin --profile web add github:zizhuang/dsh-file-dedupe
```

Replace `web` with your profile name (`desktop`, `headless`, `tui`, …). Restart/refresh the app and the floating button appears.

> Not published to npm yet (so `add dsh-file-dedupe` is unavailable); once the community catalog indexes this repository you can also install it from **Settings → Plugin Market** inside the app.

## How it works

1. Walk the target directory and group files by **size**.
2. Hash only the candidates that share a size with another file (**SHA-256**, 1 MiB streaming chunks).
3. Report groups whose content hash matches — these are true duplicates, independent of file names.

Reports include the number of duplicate groups, redundant files, and the reclaimable space.

## Cleanup model

| Action | Where | Reversible |
|---|---|---|
| Move to quarantine | Panel + `file_dedupe_cleanup` | ✅ `file_dedupe_restore` |
| Permanent delete | Panel only, with a confirm dialog | ❌ |

Quarantined files live in `$DSH_HOME/dsh-file-dedupe/quarantine/` with a manifest, and are restored to their exact original paths (refusing to overwrite an occupied path).

## Configuration

Override in the profile's `cordis.patch.yml`:

| Field | Default | Meaning |
|---|---|---|
| `minFileSize` | `1` | Ignore files smaller than this many bytes |
| `maxFiles` | `100000` | Cap on collected files per scan |
| `maxGroups` | `500` | Reported duplicate groups (sorted by reclaimable space) |

## Agent tool example

```
file_dedupe_scan(root="D:\\file store")          → duplicate groups + reclaimable space
file_dedupe_cleanup(scanId="scan-…", paths=[…])  → move redundant copies to quarantine
file_dedupe_restore(paths=[…])                   → restore from quarantine
```

## Notes

- Duplicate detection is **byte-level**: same name with different content is not a duplicate.
- Scanning very large trees takes time — narrow it with `minFileSize` / `maxFiles`.
- Removal always affects only the redundant copies you selected; one copy per group is always kept.

## License

MIT