tzst

Visão geral da skill tzst

O que a skill tzst ajuda você a fazer

A tzst skill é um guia prático para usar a ferramenta de linha de comando tzst para criar, inspecionar, testar e extrair arquivos .tzst e .tar.zst. Ela é mais útil quando você já sabe com quais caminhos de arquivo quer trabalhar e precisa chegar ao comando certo, às flags adequadas e às escolhas de segurança com mais rapidez do que um prompt genérico normalmente entregaria.

Para quem a tzst é indicada

A tzst skill atende bem desenvolvedores, profissionais de ops e pessoas que montam automações e precisam de fluxos confiáveis para trabalhar com arquivos locais, scripts, jobs de CI ou tarefas pontuais de suporte. Ela é especialmente relevante se você busca saída legível por máquina, comportamento de extração controlado ou um caminho de instalação previsível, sem surpresas.

O trabalho real que ela resolve

A maioria dos usuários não está procurando um tour pelo repositório. O que eles querem responder é: como instalar tzst? Qual comando cria e qual extrai? Como evitar sobrescrever arquivos? Como filtrar o que será extraído? Como usar tzst para File Automation com saída amigável para JSON e flags previsíveis?

Principais diferenciais

Em comparação com um prompt comum, tzst é mais específica e, por isso, mais acionável. O foco está na CLI, não em uma API Python; ela destaca padrões seguros; e direciona o usuário para padrões concretos de comando, como a para criar, x para extração estruturada, e para extração plana, l para listar e t para testar o arquivo.

O que importa antes de instalar

Os maiores bloqueios de adoção normalmente são simples: saber se tzst já está disponível no seu sistema, se você prefere uma instalação baseada em Python ou um binário standalone, e se a sua tarefa realmente envolve tzst em vez de tar ou zip genéricos. Se a sua necessidade é lidar com arquivos via CLI, esta skill é uma ótima opção. Se você precisa de from tzst import ..., ela não é o guia principal certo.

Como usar a skill tzst

Comece pela instalação e pelo preflight

Antes de pedir qualquer coisa mais substancial ao modelo, confirme que tzst existe no seu ambiente:

tzst --version
tzst --help

Se não estiver instalado, a orientação do repositório aponta para estes caminhos de instalação:

uv tool install tzst
pip install tzst

Se você não quiser uma instalação via Python, use os binários standalone publicados em https://github.com/xixu-me/tzst/releases/latest.

Saiba quando acionar a skill tzst

Use a orientação de tzst usage quando o pedido envolver qualquer um destes casos:

• criar um arquivo .tzst
• extrair .tzst ou .tar.zst
• achatar o conteúdo extraído
• listar entradas do arquivo
• testar a integridade do arquivo
• escolher níveis de compressão
• usar modo streaming
• filtrar caminhos extraídos
• definir comportamento em caso de conflito
• gerar saída adequada para scripts

Não comece por esta skill em perguntas sobre formatos de arquivo não relacionados ou sobre biblioteca Python.

O mapa central de comandos

A forma mais rápida de usar tzst bem é mapear seu objetivo para o subcomando certo:

• tzst a archive.tzst files... para criar
• tzst x archive.tzst para extrair preservando os caminhos
• tzst e archive.tzst para extração plana
• tzst l archive.tzst para listar
• tzst t archive.tzst para testar

Isso importa porque muitos problemas surgem ao escolher e quando na verdade você queria x, ou ao extrair sem pensar em conflitos e no diretório de saída.

Prefira extração estruturada à extração plana

Em fluxos normais, tzst x é a opção mais segura por padrão porque preserva a estrutura de diretórios. Use tzst e apenas quando o achatamento for realmente intencional. Essa distinção é importante para tzst for File Automation, já que achatar caminhos pode gerar colisões de nomes ou dificultar correspondências de arquivos nas etapas seguintes.

Quais informações a skill precisa de você

Para gerar um comando de alta qualidade, a skill precisa de detalhes operacionais concretos:

• caminho do arquivo ou nome desejado para o arquivo de saída
• arquivos ou diretórios de origem
• diretório de destino para extração
• se você quer achatamento ou não
• se sobrescrita é permitida
• quais filtros de caminho devem ser aplicados
• se a saída deve ser amigável para scripts
• se você prefere instalação via Python ou binário standalone

Se você omitir essas informações, o modelo ainda pode sugerir a sintaxe, mas não conseguirá fornecer um comando de baixo risco.

Transforme um objetivo vago em um prompt forte para tzst

Prompt fraco:

Help me use tzst.

Prompt melhor:

I need a tzst command to extract archive.tzst into ./out, preserve paths, avoid overwriting existing files, and only extract files under docs/. Assume tzst is already installed.

Por que isso é melhor: ele já entrega, de uma vez, o arquivo, o destino, o modo de extração, a expectativa de conflito e o escopo do filtro.

Padrão de prompt para criação de arquivos

Use um prompt como este ao criar arquivos:

Give me a tzst create command for backup.tzst from ./src and ./docs, use a higher compression level, and explain any safety or performance tradeoffs.

Isso permite que a skill escolha tzst a, destaque -l ou --level e explique quando o padrão costuma bastar e quando compressão extra pode custar tempo.

Padrão de prompt para scripts e automação

Para tzst usage dentro de shell scripts ou CI, peça comandos com expectativas legíveis por máquina:

I need tzst for File Automation in a CI job. Show commands to test an archive, list contents, and return output that is easy to parse in a script.

Isso orienta a skill para caminhos de saída voltados a JSON ou seguros para script, quando houver suporte, e para sequências de comando estáveis em vez de orientações interativas.

Fluxo sugerido para tarefas reais

Um fluxo confiável é:

1. confirmar a instalação com tzst --version
2. testar a disponibilidade com tzst --help
3. escolher o subcomando com base no objetivo real
4. definir destino, filtros e política de conflito
5. testar ou listar antes de uma extração destrutiva quando o risco for alto
6. executar o comando final
7. só então levar isso para a automação

Essa sequência reduz erros evitáveis de extração e facilita a solução de problemas.

Arquivos do repositório que vale ler primeiro

Se você quiser validar a skill antes de adotá-la, comece por aqui:

• skills/tzst/SKILL.md
• skills/tzst/references/cli-reference.md

SKILL.md mostra quando a skill deve ser acionada. references/cli-reference.md é o arquivo mais rápido para encontrar comandos de instalação, mapeamento de comandos e escolha de flags.

Flags práticas que mudam o resultado

Algumas opções afetam materialmente o resultado:

• -l ou --level altera o nível de compressão na criação
• -o controla o destino da extração
• --streaming importa em fluxos grandes ou orientados a pipeline
• --filter limita o que será extraído
• --conflict-resolution ajuda a evitar sobrescritas acidentais
• --no-atomic muda o comportamento de escrita durante a criação

Essas flags não são cosméticas. Elas definem segurança, desempenho e comportamento em scripts.

Erros comuns na instalação e no uso de tzst

Os principais erros são previsíveis:

• tentar usar a skill para imports em Python em vez de tarefas de CLI
• pular o preflight e descobrir que tzst não está instalado só depois de montar o fluxo
• usar extração plana quando a intenção era preservar caminhos
• não especificar tratamento de conflito em diretórios com arquivos existentes
• pedir “um comando” sem informar caminhos, filtros ou saídas

FAQ da skill tzst

A skill tzst é boa para iniciantes?

Sim, desde que a tarefa seja concreta. O tzst guide funciona melhor para iniciantes quando a pessoa já sabe qual arquivo tem em mãos e qual resultado quer obter. Ele ajuda menos em pedidos vagos do tipo “me ensine sobre arquivos compactados”.

Qual é a diferença entre tzst e um prompt genérico de IA?

Um prompt genérico pode fornecer orientações plausíveis sobre arquivos compactados, mas desalinhadas dos subcomandos ou das flags de tzst. A tzst skill restringe o modelo ao fluxo real da CLI, às opções de instalação e ao vocabulário de comandos que o usuário de fato precisa executar.

Quando eu não devo usar tzst?

Não use tzst como guia principal para:

• perguntas genéricas sobre zip ou tar sem envolvimento de tzst
• uso de API Python, como from tzst import ...
• tarefas com arquivos compactados em que outra ferramenta já instalada é a verdadeira necessidade

A skill é deliberadamente específica para CLI.

A tzst é adequada para automação?

Sim. Esse é um dos motivos mais fortes para usá-la. A skill cobre explicitamente listagem, teste, filtragem, controle de conflito e considerações sobre saída legível por máquina, que fazem diferença em shell scripts e CI.

Qual é o melhor caminho de instalação do tzst?

Para muitos usuários, uv tool install tzst é a instalação mais limpa. pip install tzst funciona bem se instalar pacotes Python já faz sentido no seu ambiente. Se você quer o menor overhead possível de dependências, o binário standalone é a melhor escolha.

Preciso ler o repositório inteiro primeiro?

Não. Para decidir sobre a instalação, normalmente basta consultar SKILL.md e references/cli-reference.md. Isso já é suficiente para avaliar aderência, cobertura de comandos e se a skill vai reduzir adivinhação no seu caso de uso.

Como melhorar a skill tzst

Dê à tzst o contexto completo da tarefa

A forma mais rápida de melhorar os resultados com tzst é fornecer os detalhes operacionais logo no início. Inclua nome do arquivo, caminhos de origem, diretório de destino, política de sobrescrita, preferência por achatamento e se o comando precisa ser seguro para script. Entradas melhores produzem comandos que você realmente consegue executar.

Declare explicitamente sua tolerância a risco

Se a tarefa envolve arquivos importantes, diga à skill se ela deve priorizar segurança em vez de brevidade. Isso a empurra para listagem, testes, extração com preservação de caminhos e configurações explícitas de conflito, em vez de comandos mínimos.

Peça o comando junto com a justificativa

Um bom formato de prompt é:

Give me the exact tzst command, explain each important flag briefly, and mention any safer alternative if the destination already contains files.

Isso aumenta a confiança e ajuda você a identificar pressupostos errados antes da execução.

Peça uma segunda iteração depois do primeiro comando

O melhor uso do tzst guide é iterativo. Depois da primeira resposta, refine com detalhes do ambiente:

Now adapt that command for a standalone binary install and a CI environment where the output must be easy to parse.

Isso é mais eficaz do que recomeçar do zero.

Use amostras de arquivos e exemplos de caminho

Se filtragem ou achatamento importam, inclua caminhos representativos. Exemplo:

Archive contains docs/api/index.md, docs/user/intro.md, and src/main.py. I only want docs/ extracted into ./site-content.

Esse nível de detalhe ajuda a skill a escolher o modo de extração e o comportamento de filtro corretos.

Antecipe os modos de falha mais comuns

Peça à skill para verificar estes pontos antes de fechar um comando:

• instalação ausente de tzst
• subcomando errado para a tarefa
• achatamento acidental de caminhos
• conflitos ao sobrescrever arquivo ou ao extrair
• pressupostos não suportados sobre o formato de saída

É aqui que a tzst skill agrega valor real em comparação com uma resposta comum de CLI em uma linha.

Melhore o uso de tzst para File Automation com fluxos estáveis

Ao usar tzst for File Automation, peça uma sequência em vez de um único comando: preflight, listagem ou teste, execução e verificação. Em automação, estabilidade normalmente vem de etapas previsíveis, não da sintaxe mais curta possível.

Valide com o arquivo de referência

Se um comando parecer incerto, compare com references/cli-reference.md. Esse é o arquivo mais rápido para conferir subcomandos, opções de instalação e as flags com maior impacto sobre a correção.

Sugira melhorias de volta para a skill

Se você perceber ambiguidades recorrentes, melhore a skill adicionando mais exemplos orientados à decisão em torno de:

• x vs e
• padrões seguros de --conflict-resolution
• exemplos de filtragem com caminhos realistas
• padrões de saída voltados à automação
• orientação de instalação para Python vs binário standalone

Esses acréscimos tornariam a tzst skill ainda mais útil no momento da decisão, e não apenas na execução.