file-singlify (Singleficação de Arquivos)
O que esta habilidade faz
Escaneia um disco / diretório / caminho de montagem, identifica arquivos duplicados e diretórios duplicados gerados por múltiplas cópias, backups, sincronizações e migrações, e gera um plano de "singleficação": mantém uma cópia canônica por grupo, mapeando as demais como referências / a deletar / sugestões de link, com estimativa de espaço economizado.
Princípio central: padrão somente leitura, apenas dry-run. Jamais deleta, move, sobrescreve ou cria hard/soft links diretamente. Qualquer operação destrutiva deve primeiro gerar um relatório e aguardar confirmação explícita do usuário. O script em si é sempre somente leitura – --action-mode apenas altera o rótulo suggested_action no relatório, sem executar nenhuma ação.
Quando usar
- O usuário quer escanear um disco/diretório/lote de pastas para encontrar "arquivos idênticos" "diretórios duplicados" "backups redundantes" "cópias múltiplas"
- O usuário quer manter um arquivo original, gerar um mapa de referências, sugestões de exclusão, sugestões de hard/soft link, relatório de desduplicação, estimativa de economia de espaço
- Palavras-chave: desduplicação / singleficação / colapso de diretórios duplicados / dedup / canonical copy / storage cleanup
Não aplicável: O usuário deseja análise de conteúdo de arquivo, compressão ou organização não relacionada à detecção de duplicatas.
Fluxo de trabalho padrão
- Verificação de caminho e permissões — Confirma se o ambiente atual pode acessar
root_path. Se puder acessar, executa o script; se não puder, solicita ao usuário uma lista de diretórios / árvore de diretórios / arquivo compactado / caminho de montagem acessível. Jamais inventa resultados de escaneamento. - Executa o script (directory-first) — Primeiro encontra redundâncias por consistência de diretório, depois confirma com hash de arquivo. Diretórios inteiros copiados repetidamente são a maior fonte de desperdício de espaço, então exibe resultados no nível de diretório primeiro.
- Lê a saída do script e organiza para o usuário — Prioriza grupos de diretórios duplicados, depois grupos de arquivos duplicados, mapeamento canônico, economia de espaço e itens de risco. Para itens marcados como
uncertain/manual_review, faz perguntas para esclarecimento, não decide por ele. - Oferece os top-4 comandos seguintes — O script gera os 4 comandos recomendados com base no SO/shell atual (prioridade de segurança: verify → quarantine → hardlink → delete), conforme Seção 10 do relatório /
recommended_commandsdo JSON. Apresenta-os ao usuário e ajusta a sintaxe de acordo com o SO e shell reais do usuário; o script detecta automaticamente por padrão e, se necessário, permite usar--target-os/--target-shellpara substituição. Apenas fornece comandos, não executa. Os comandos usam caminhos de amostra representativos; devem ser aplicados linha por linha à tabela de mapeamento. - Confirmação antes de operações destrutivas — Quando o usuário realmente quiser deletar / trocar links, primeiro repete o plano e solicita confirmação explícita; o script não executa; o usuário deve executar por conta própria ou autorizar separadamente.
Quando executar o script
Execute quando o ambiente puder ler diretamente root_path; quando receber apenas uma lista/árvore, analise manualmente com a mesma lógica de decisão (estrutura de diretórios consistente → tamanho de arquivo consistente → confirmação por hash de conteúdo) e declare explicitamente "sem confirmação por hash".
python3 scripts/scan_file_singlify.py <root_path> \
--scan-mode directory-first \ # ou file-only
--hash-algorithm md5 \ # md5 | sha256 | both (estrito: use both)
--output-format markdown \ # markdown | json | csv
--action-mode report-only \ # report-only|link-plan|delete-plan|hardlink-plan|symlink-plan
--exclude-patterns ".git,node_modules,cache,temp" \
--include-patterns "*.jpg,*.mp4" \
--min-file-size 1024 \
--prefer "/Volumes/Primary" \ # Prioriza este caminho como canônico
--target-os auto \ # auto|macos|linux|windows (para gerar top-4 comandos)
--target-shell auto # auto|bash|zsh|fish|powershell|cmd
Para parâmetros completos e detalhes de decisão, veja --help do script, references/matching-rules.md e references/safety-rules.md.
Formato de saída
O script produz um relatório estruturado contendo: escopo do escaneamento, parâmetros, total de arquivos/diretórios/capacidade, grupos de diretórios duplicados, diretórios suspeitos de duplicação, grupos de arquivos duplicados (confirmados por hash), estimativa de economia de espaço, tabela de mapeamento canônico, top-4 comandos recomendados (gerados por SO/shell), riscos e itens incertos, e próximos passos sugeridos. markdown para humanos, json para consumo por programas (contém recommended_commands), csv é a tabela de mapeamento duplicado→canônico.
Cada linha de mapeamento inclui confidence (confirmed / uncertain) e suggested_action (keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review).
Limites de segurança
- Por padrão, jamais deleta arquivos, jamais cria hard/soft links automaticamente. O script é somente leitura.
- Apenas nome de arquivo / tamanho / mtime não podem determinar igualdade – são apenas filtros candidatos; a conclusão final deve ser confirmada por hash (mesmo tamanho + mesmo hash).
- Tenha cuidado extra com diretórios de sistema, diretórios ocultos, diretórios de aplicativos, repositórios Git, bancos de dados, bibliotecas de fotos, diretórios de sincronização em nuvem.
- Links simbólicos não são seguidos, nem recursivos; se encontrar loops de diretório, para a recursão e reporta.
- Permissão insuficiente / zero bytes / arquivos especiais / arquivos já hardlinkados → marca e pula, entra na categoria "pulado / incerto", não tratado como duplicado confirmado.
- Quando não for possível determinar o canônico, lista os candidatos e solicita confirmação do usuário, sem decidir sozinho.
Erros comuns
| Erro | Correção |
|---|---|
| "Fingir escaneamento" sem confirmar se o caminho está acessível | Primeiro confirme; se não acessível, peça uma lista; jamais invente resultados |
| Julgar duplicata apenas por nome/tamanho/data | Apenas como candidatos; deve-se confirmar com hash |
| Fazer hash de todos os arquivos de uma vez | Primeiro filtre por consistência de diretório, depois faça hash dos candidatos |
| Sugerir deletar/trocar links antes de gerar o relatório | Primeiro gere o relatório, aguarde confirmação explícita; o script não executa ações destrutivas |
Decidir por conta própria itens uncertain | Apresente os itens incertos como perguntas ao usuário |