Storage Analyzer: mapa do disco antes de qualquer exclusão

ANÁLISE EDITORIAL

Quando um disco fica cheio, o impulso mais perigoso é começar pela exclusão. Storage Analyzer propõe outra ordem: medir o uso, organizar os maiores diretórios, separar cache de dados pessoais e só então decidir o que merece uma ação. A Skill trabalha com macOS e Windows, gera um inventário em JSON e orienta a construção de um relatório visual por níveis de risco.

Essa descrição exige uma ressalva importante. O scanner é somente leitura, mas o modo de servidor recomendado pelo projeto pode mover caminhos para a lixeira e também apagar diretamente itens classificados como verdes. Por isso, a curadoria do Bastidores separa as duas fases: primeiro análise estática, depois uma decisão humana individual para cada remoção. O ZIP local é documental e não contém os scripts de execução.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre blocos de armazenamento examinados por uma lente antes de atravessarem um portão de confirmação. Não é captura de tela, interface real, logotipo oficial, resultado de varredura nem prova de espaço recuperado.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado descreve quatro etapas. A primeira executa um scanner de armazenamento. A segunda pede ao agente que leia o resultado e classifique os maiores consumidores. A terceira transforma a análise em relatório HTML. A quarta resume as prioridades na conversa.

O scanner oficial usa somente a biblioteca padrão do Python. No macOS, chama ferramentas como du, diskutil e sw_vers. No Windows, percorre diretórios com os.scandir e consulta volumes com shutil.disk_usage. O código ignora links simbólicos e tenta continuar quando encontra diretórios sem permissão.

O resultado não é um limpador automático. É um JSON com sistema, discos e grupos de diretórios maiores que os limites definidos pelo código. A interpretação posterior, inclusive a decisão de chamar um item de cache, dado de usuário ou aplicativo, é feita pelo agente. Essa classificação pode errar e precisa ser confrontada com o caminho real e com a função do aplicativo.

Para quem serve

Serve para quem precisa descobrir por que o SSD está cheio antes de comprar espaço, remover aplicações ou apagar pastas. Pode ajudar profissionais de suporte, desenvolvedores com caches grandes, usuários com muitos downloads e pessoas que receberam um alerta de pouco espaço, mas ainda não sabem onde investigar.

É especialmente útil quando a pergunta correta é “o que ocupa espaço?” e não “o que posso apagar agora?”. A separação importa porque um diretório grande pode conter cache regenerável, projeto ativo, biblioteca de fotos, máquina virtual, dados de mensageria ou uma aplicação inteira. Tamanho sozinho não define descarte.

Não serve para analisar RAM, processos em execução ou consumo de memória volátil. Também não substitui backup, ferramenta de gestão de armazenamento do sistema, política corporativa de retenção ou diagnóstico de falha física do disco. Em servidores e estações administradas, a execução deve respeitar o escopo autorizado e a política de dados.

Compatibilidade e pré-requisitos

O projeto declara macOS como implementação completa e testada. Para Windows, o próprio arquivo da Skill informa que o código foi escrito, inclusive o envio à Lixeira por SHFileOperationW, mas não foi testado em uma máquina Windows real no commit auditado. Linux não é suportado pelo scanner.

É necessário Python 3. No macOS, os comandos do sistema usados pelo scanner costumam estar disponíveis. No Windows, Python pode não estar instalado e o comando pode ser python ou py -3, não python3. Leia a referência oficial de Windows antes de adaptar qualquer caminho.

A varredura lê nomes, caminhos e tamanhos de diretórios. O JSON pode revelar projetos, clientes, aplicativos, perfis e hábitos de uso. Guarde o arquivo localmente, não envie para um modelo ou serviço externo sem autorização e remova dados identificáveis antes de compartilhar uma captura ou relatório.

Instalação recomendada

O ZIP do Bastidores contém somente SKILL.md, LICENSE e ORIGEM.md. Ele não inclui scan.py, build_report.py, server.py, template HTML ou referências de plataforma. Para executar a Skill, obtenha a pasta completa no repositório oficial fixado e revise todos os arquivos antes de usá-los.

git clone https://github.com/KKKKhazix/khazix-skills.git
cd khazix-skills
git checkout 7a5c4934be4106ac740ffdb95280bb81b3f4b83c

Esse comando baixa o repositório completo, não apenas a Skill. Faça isso em um diretório de teste, confira o commit e copie somente storage-analyzer para o host compatível com Agent Skills. Não execute o servidor de limpeza como parte da instalação. Ler a instrução, rodar o scanner e autorizar uma exclusão são decisões diferentes.

Configuração antes do primeiro uso

Comece com uma regra operacional simples: a primeira execução termina no JSON e não inclui limpeza. Defina onde o resultado será salvo, quem pode lê-lo e quais unidades ou diretórios estão autorizados. Se houver dados de cliente, código proprietário ou perfis compartilhados, obtenha aprovação antes da varredura.

No macOS, a referência de layout distingue caches, contêineres, suporte de aplicações, downloads e aplicações. No Windows, confirme as variáveis USERPROFILE, LOCALAPPDATA, APPDATA, TEMP e SystemDrive. Não presuma que todos os computadores usam os caminhos padrão.

Prepare também um backup válido para dados que possam entrar numa etapa posterior. O fato de um item ir para a Lixeira não garante recuperação em toda situação. Espaço em unidade externa, sincronização incompleta e pastas mantidas por aplicativos podem alterar o comportamento.

Primeiro uso seguro

Execute somente o scanner a partir da pasta da Skill. No macOS:

python3 scripts/scan.py > storage_scan.json

No Windows, use o comando Python disponível:

py -3 scriptsscan.py > storage_scan.json

Abra o JSON como texto e confira system, groups, caminhos negados e tempo de execução. Verifique se o arquivo não está vazio e se o sistema detectado corresponde à máquina. A ausência de um diretório pode significar que ele não existe, ficou abaixo do limite ou não pôde ser lido. Não interprete ausência como espaço zero.

Depois, peça ao agente uma análise sem comandos de exclusão. Exija que cada item traga caminho, tipo provável, evidência observada, incerteza e próximo passo manual. Se quiser um HTML compartilhável, use o gerador estático somente após revisar o JSON de análise que será injetado no template.

Resultado esperado

O primeiro resultado esperado é um inventário, não espaço liberado. Ele deve mostrar capacidade, uso e diretórios relevantes por grupo. A análise pode destacar os cinco maiores consumidores e separar itens que parecem regeneráveis daqueles que contêm dados de usuário ou exigem desinstalação pelo método oficial.

O relatório estático organiza a leitura em visão do disco, maiores consumos, prioridades, níveis verde, amarelo e vermelho e sugestões de longo prazo. As cores são uma classificação produzida pelo agente, não uma garantia técnica. Um cache pode preservar sessão, dados offline ou trabalho ainda não sincronizado. Um aplicativo pode manter arquivos fora da pasta principal.

Qualquer estimativa de espaço recuperável deve permanecer marcada como estimativa. Sistemas de arquivos, snapshots, arquivos esparsos, compressão, deduplicação, hard links e arquivos abertos podem fazer a diferença entre tamanho somado e espaço realmente devolvido ao volume.

Permissões e riscos

A primeira permissão é leitura ampla de diretórios do usuário e, no macOS, de /Applications. Essa leitura pode expor nomes de projetos, arquivos baixados, caches e aplicações instaladas. Use uma conta adequada, limite o compartilhamento do relatório e trate caminhos como dados potencialmente sensíveis. O guia do Bastidores sobre permissões de agentes ajuda a separar leitura, rede, escrita e publicação.

O risco mais sério aparece no servidor local. Ele cria listas permitidas a partir do relatório e oferece três tipos de ação: abrir no gerenciador de arquivos, mover para a Lixeira e apagar diretamente. O código usa token aleatório, bind em 127.0.0.1, validação de Host, realpath e restrição ao diretório do usuário. Esses controles reduzem o alcance, mas não tornam uma classificação errada reversível.

O modo de exclusão direta chama shutil.rmtree para diretórios e os.remove para arquivos. A confirmação no navegador é uma barreira de interface, não um backup. Use primeiro o relatório estático. Se uma remoção for necessária, valide o caminho fora do relatório, feche o aplicativo correspondente, preserve cópia e prefira a Lixeira ou a ferramenta oficial do sistema.

Erros comuns

• Confundir armazenamento com RAM: esta Skill analisa disco, não processos ou memória em uso.
• Tratar verde como autorização: a cor depende da análise do agente e precisa de conferência humana.
• Rodar o servidor primeiro: comece pelo scanner e pelo relatório estático.
• Apagar pasta de perfil do navegador: cache e dados de sessão podem estar próximos, mas não são equivalentes.
• Apagar WinSxS manualmente: a referência oficial manda usar ferramentas do Windows.
• Ignorar caminhos negados: o inventário pode estar incompleto e precisa declarar a lacuna.
• Compartilhar o JSON sem revisão: caminhos podem revelar nomes, clientes e projetos.
• Prometer o total estimado: tamanho listado não garante espaço recuperado.
• Tratar o ZIP como aplicativo: o download local é documental e não executa a varredura.

Versão auditada e download local

A curadoria fixou o commit 7a5c4934be4106ac740ffdb95280bb81b3f4b83c. Em 22/08/2026, o repositório KKKKhazix/khazix-skills tinha 19.955 estrelas e não estava arquivado. Estrelas indicam adoção observável, não revisão de segurança ou qualidade.

A licença MIT permite redistribuição sob suas condições. O ZIP local tem 8.277 bytes, contém somente SKILL.md, LICENSE e ORIGEM.md, e possui SHA-256 dbd65d74ad43433e4e94144b5b999eabdfdc7f5d07cff4a07d387781383b5a46. Os scripts e o template permanecem apenas na fonte oficial.

Resultado esperado e limite final

Storage Analyzer é útil quando transforma “meu disco está cheio” em um mapa verificável de caminhos, tamanhos e decisões. O ganho real está em separar diagnóstico de remoção. Um bom resultado permite que a pessoa explique o que ocupa espaço e por que cada item pode, ou não, ser alterado.

Considere a análise concluída quando o sistema foi detectado corretamente, as lacunas de permissão estão visíveis, os maiores itens têm evidência e nenhuma classificação foi tratada como ordem de exclusão. Considere uma limpeza concluída apenas após backup, confirmação explícita do caminho, uso do método adequado e nova medição do volume.

O download local preserva a instrução e a licença. O botão do repositório oficial leva aos scripts necessários para execução. Mantenha as duas ações separadas: baixar a documentação não instala um limpador, e rodar um scanner não autoriza apagar arquivos.

Fontes primárias

• Repositório oficial KKKKhazix/khazix-skills
• Diretório Storage Analyzer no commit auditado
• SKILL.md oficial fixado
• Scanner somente leitura
• Gerador de relatório estático
• Servidor local com ações de limpeza
• Referência de armazenamento no Windows
• Referência de armazenamento no macOS
• Licença MIT preservada no pacote