file-singlify (Deduplicación de archivos)
Qué hace este skill
Escanea un disco / directorio / punto de montaje para encontrar archivos duplicados y directorios duplicados generados por múltiples copias, copias de seguridad, sincronizaciones o migraciones. Genera un plan de deduplicación: para cada grupo se conserva una copia canónica y el resto se asigna como referencia / pendiente de eliminación / sugerencia de enlace. Estima el espacio que se puede ahorrar.
Principio fundamental: por defecto es de solo lectura, solo ejecuta dry-run. Nunca elimina, mueve, sobrescribe, modifica ni crea enlaces duros o simbólicos directamente. Cualquier operación destructiva debe primero generar un informe y luego esperar la confirmación explícita del usuario. El script en sí es siempre de solo lectura: --action-mode solo cambia la etiqueta suggested_action en el informe, no ejecuta ninguna acción.
Cuándo usarlo
- El usuario quiere escanear un disco / directorio / conjunto de carpetas para encontrar «archivos idénticos», «directorios duplicados», «copias de seguridad redundantes», «copias múltiples».
- El usuario quiere conservar una copia original, generar un mapa de referencias, sugerencias de eliminación, sugerencias de enlaces duros/simbólicos, un informe de deduplicación y una estimación de ahorro de espacio.
- Palabras clave: deduplicación / copia única / plegado de directorios duplicados / dedup / copia canónica / limpieza de almacenamiento.
No aplica cuando: El usuario necesita análisis de contenido de archivos, compresión u organización no relacionada con la detección de duplicados.
Flujo de trabajo predeterminado
- Verificación de ruta y permisos — Se confirma si el entorno actual puede acceder a
root_path. Si es accesible, se ejecuta el script; si no, se solicita al usuario que proporcione una lista de directorios / un árbol de directorios / un archivo comprimido / una ruta de montaje accesible. Nunca se inventan resultados de escaneo. - Ejecución del script (primero directorios) — Primero se buscan redundancias por consistencia de directorios, luego se confirman con hash de archivos. La duplicación de directorios completos es la mayor fuente de desperdicio de espacio, por lo que los resultados a nivel de directorio se presentan primero.
- Lectura de la salida del script y presentación al usuario — Se priorizan los grupos de directorios duplicados, luego los grupos de archivos duplicados, el mapeo canónico, el ahorro de espacio y los riesgos. Los elementos marcados como
uncertainomanual_reviewse presentan al usuario como preguntas para aclarar, sin decidir por él. - Presentación de los 4 comandos principales — El script genera los 4 comandos recomendados según el SO/shell actual (prioridad de seguridad: verify → quarantine → hardlink → delete), que se encuentran en la sección 10 del informe /
recommended_commandsdel JSON. Se presentan al usuario y se ajustan la sintaxis según el SO y shell reales del usuario; el script detecta automáticamente de forma predeterminada, y se puede sobrescribir con--target-os/--target-shellsi es necesario. Solo se proporcionan los comandos, no se ejecutan. Los comandos usan rutas de muestra representativas; se deben aplicar línea por línea al mapa de mapeo. - Reconfirmación antes de operaciones destructivas — Cuando el usuario desea eliminar o cambiar enlaces, se repite el plan y se solicita confirmación explícita; el script no ejecuta, el usuario debe ejecutar por su cuenta o autorizar aparte.
Cuándo ejecutar el script
Ejecutar si el entorno puede leer root_path directamente; cuando solo se proporciona una lista / árbol, se analiza manualmente con la misma lógica de decisión (estructura de directorios consistente → tamaño de archivo consistente → confirmación por hash de contenido) y se indica explícitamente que «no se ha realizado la verificación por hash».
python3 scripts/scan_file_singlify.py <root_path> \
--scan-mode directory-first \ # o file-only
--hash-algorithm md5 \ # md5 | sha256 | both (riguroso usar 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" \ # priorizar esta ruta como canónica
--target-os auto \ # auto|macos|linux|windows (para generar los 4 comandos principales)
--target-shell auto # auto|bash|zsh|fish|powershell|cmd
Para detalles completos de parámetros y reglas de decisión, consulta --help del script, references/matching-rules.md y references/safety-rules.md.
Formato de salida
El script produce un informe estructurado que incluye: alcance del escaneo, parámetros, total de archivos/directorios/capacidad, grupos de directorios duplicados, directorios sospechosos de duplicación, grupos de archivos duplicados (confirmados por hash), estimación de ahorro de espacio, mapa de mapeo canónico, 4 comandos recomendados (generados según SO/shell), riesgos e incertidumbres, y sugerencias para próximos pasos. markdown para humanos, json para consumo por programas (incluye recommended_commands), csv como mapa de mapeo duplicado→canónico.
Cada línea de mapeo incluye confidence (confirmed / uncertain) y suggested_action (keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review).
Límites de seguridad
- Por defecto, nunca se eliminan archivos ni se crean enlaces duros/simbólicos automáticamente. El script es de solo lectura.
- Solo con nombre de archivo / tamaño / mtime no se puede determinar que sean iguales — solo se usan como filtro de candidatos; la conclusión final debe ser confirmada por hash (mismo tamaño + mismo hash).
- Especial cuidado con directorios del sistema, directorios ocultos, directorios de aplicaciones, repositorios Git, bases de datos, fototecas y directorios de sincronización en la nube.
- Los enlaces simbólicos no se siguen ni se recorren de forma recursiva; si se encuentra un ciclo de directorios, se detiene la recursión y se informa.
- Archivos con permisos insuficientes / cero bytes / archivos especiales / archivos ya enlazados duros → se marcan y se omiten, y se clasifican como «omitido / incierto», no como duplicados confirmados.
- Cuando no se puede determinar la copia canónica, se listan los candidatos y se solicita confirmación al usuario, sin decidir por sí mismo.
Errores comunes
| Error | Corrección |
|---|---|
| «Fingir escaneo» sin confirmar si se puede acceder a la ruta | Confirmar primero; si no es accesible, solicitar lista, nunca inventar resultados |
| Determinar duplicados solo por nombre/tamaño/hora | Solo como candidatos; debe confirmarse con hash |
| Hacer hash de todos los archivos de inmediato | Primero filtrar por consistencia de directorios, luego hash solo a los candidatos |
| Sugerir eliminar/cambiar enlaces antes de generar el informe | Primero generar el informe, esperar confirmación explícita; el script no ejecuta acciones destructivas |
Decidir por el usuario los elementos uncertain | Presentar los elementos inciertos como preguntas al usuario |