Como usar o IronZIP com o Google Antigravity
Uma página que entrega documentos de casos a clientes como um ZIP protegido por senha pode compilar sem erros e ainda assim enviar um arquivo com documentos faltando, uma página de erro para um caso comum ou um documento de um caso diferente.
O comando /browser do Google Antigravity inicia um subagente do navegador Chrome que pode controlar a página em execução, assim um único prompt pode digitar uma senha, pressionar Download para cada caso de teste e manter uma captura de tela de cada resultado. O IronZIP constrói o arquivo no servidor com criptografia AES-256 e o extrai novamente, para que a página possa provar que cada documento voltou byte após byte. Este guia constrói aquela página de download em um aplicativo ASP.NET Core MVC, começando a partir do exemplo de proteção por senha do IronZIP, e a verifica em relação a cinco casos cujos documentos e hashes SHA-256 são conhecidos antecipadamente.
Abra a pasta CaseDocs no Antigravity e descreva a página de download.
/plan CaseDocs is an ASP.NET Core MVC project that targets .NET 9.
Add the case document download that docs/case-download-rules.md describes.
The download works like this:
- A user opens /Cases/{id}, ticks documents and types a password.
- The user receives an AES-256 encrypted ZIP that the server builds with IronZIP.
- The NuGet package is IronZIP version 2026.10.2, and its namespace is IronZip.
Program.cs reads IRONZIP_LICENSE_KEY and assigns it once to IronZip.License.LicenseKey.
Confirm only that the variable exists and how many characters it holds.
Never print, log or write its value.
The Implementation Plan must state these answers:
- the entry name each document receives inside the archive
- the path the archive is saved to before the response, and when that file is deleted
- how the saved archive is compared with the ticked documents
Stop once dotnet build succeeds, and tell me the build result.
Leia essas três respostas antes das mudanças no código. Cada uma cobre uma maneira de o arquivo ir errado sem erro do compilador. No agy -p headless ninguém aprova o plano, então leia o plano Artifact ao lado do código que descreve.
Nomeie a variável no prompt e nunca cole o valor. Qualquer coisa digitada na conversa pode alcançar um arquivo de origem, um commit ou uma transcrição de terminal. IronZIP também aceita uma entrada IronZip.LicenseKey em appsettings.json, e um commit inclui esse arquivo com tudo mais. Cada local suportado está no guia de chave de licença.
Fluxo de trabalho mínimo (5 etapas)
- Baixar a biblioteca C# ZIP do NuGet
- Execute um aplicativo ASP.NET Core MVC no localhost antes do primeiro prompt
- Confirme as regras de download e um manifesto com o SHA-256 de cada documento
- Deixe
/browserpressionar Download para cada caso e capture uma captura de tela do resultado - Extraia cada arquivo com sua senha, faça o hash de cada arquivo e confirme os membros do IronZIP na referência de API
O que você deve revisar antes de aceitar as mudanças?
Verifique de onde vem o nome de cada entrada, a pasta para a qual cada arquivo é salvo, a linha que o exclui e o código que lê o arquivo de volta. Depois confirme cada membro do IronZIP no diff contra a referência de API.
O Antigravity salva capturas de tela como Artifacts de imagem que aceitam comentários. Quando um mostra uma página de erro ou a contagem de documentos errada, comente sobre essa captura de tela em vez de escrever um novo prompt sobre isso.
Como você testa cada download em um navegador real?
Peça uma tabela de resultados que somente downloads reais podem preencher.
/browser Start CaseDocs in the background with dotnet run --launch-profile http.
That profile listens on http://localhost:5065.
For each row of TestData/expected.csv, do this:
1. Open /Cases/<case> and leave every checkbox as the page sets it.
2. Type the row's password and press Download.
3. Capture a screenshot of what follows.
4. When the answer is a file, take its name and size from the download or the response headers.
In the Walkthrough and in your reply, give one line per row with these parts:
- the case
- the documents the page listed, against the documents column
- the expected outcome
- what actually happened, as the file name and size or the message shown
- a PASS or FAIL verdict
For any failing row, cite the server log entry or error page text responsible.
Do that before you edit any code.
After every fix, restart the app and go through all six rows again.
Stop the app when you are done.
Uma correção nos nomes de entrada muda cada arquivo, mesmo para casos que já passaram, por isso o prompt reinicia todas as seis linhas.
O que causa downloads incompletos ou com falha?
Na nossa calibração, o código do exemplo de proteção por senha foi movido para uma ação de download. Ele mudou para AES-256 e contou as entradas do arquivo salvo abrindo-o com o construtor. O Chrome headless então pressionou Download para cada caso com IronZIP 2026.10.2. Cada falha abaixo compilou sem um aviso.
| O que aconteceu | Causa | O que pedir |
|---|---|---|
| O caso de seis documentos foi baixado, mas extraí-lo deu 3 arquivos | O IronZIP nomeia cada entrada após o arquivo sozinho, então dois letter.pdf, dois scan.jpg e dois summary.pdf compartilham nomes | Os nomes das entradas são construídos a partir do caminho relativo, com cópias salvas sob esses nomes |
| O caso de um documento retornou uma página de erro | A leitura de retorno do construtor lançou "Senha Inválida!" com a senha correta | Uma leitura de retorno que extrai o arquivo |
| O caso vazio retornou uma página de erro | Salvar um arquivo sem entradas lançou "O arquivo existente está corrompido!" | Uma verificação de seleção antes de o IronZIP ser executado |
| O valor de um checkbox editado para ../C-1001/ledger.csv colocou o arquivo de outro caso no download | A ação confiava nos caminhos postados | Cada caminho postado foi resolvido e mantido dentro da pasta do caso |
| Quatro arquivos ZIP ficaram na pasta temporária | IronZIP salva apenas em um caminho, e nada deletou o arquivo | Uma pasta por solicitação, deletada quando a solicitação termina |
A verificação da contagem de entradas passou para o caso de seis documentos, porque o arquivo continha seis entradas.
Como você configura um projeto no qual Antigravity pode trabalhar?
O agente precisa de um aplicativo que já construa e responda no localhost. dotnet new mvc --framework net9.0 fornece um, e executá-lo uma vez mostra a porta em Properties/launchSettings.json. A porta difere de projeto para projeto, e os prompts /browser devem nomeá-la. A lista de permissões do navegador mantém apenas o localhost inicialmente, então mantenha o endereço na forma http://localhost:<port>.
Confirme as pastas de caso sob CaseFiles, as regras em docs/case-download-rules.md, TestData/expected.csv com o resultado para cada caso e senha, e TestData/manifest.csv com o nome da entrada de cada documento, tamanho e SHA-256. Os cinco casos de teste continham cinco documentos simples, seis documentos com três nomes repetidos em subpastas, uma declaração única, três documentos com nomes acentuados e japoneses, e nenhum documento ao todo. Depois faça o agente auditar o pacote e a chave.
Which IronZIP version does CaseDocs.csproj reference? Quote its PackageReference line.
Then show the line in Program.cs that assigns the license key.
Add either line if it is missing.
IRONZIP_LICENSE_KEY is the only allowed source of that key.
Search these files for an IronZip.LicenseKey entry or a key value, and remove any you find:
- appsettings.json
- appsettings.Development.json
- Properties/launchSettings.json
When the variable is missing at startup, the app logs a single warning.
That warning mentions IRONZIP_LICENSE_KEY and contains no value.
Add it only if it is absent, and leave every other file alone.
Tell me what you found and what you changed.
Repita esse número de versão sempre que um prompt posterior adicionar um projeto ou um pacote, para que cada projeto seja construído contra a mesma versão do IronZIP. Um agente que escreve um nome de pacote de memória pode instalar um pacote malicioso publicado sob um nome alucinado, um ataque chamado slopsquatting. O pacote é IronZIP e o namespace é IronZip.
Com a variável definida e License.LicenseKey nunca atribuída, a página de calibração falhou na chamada de salvamento para todos os quatro casos de arquivo. Cada um lançou uma LicensingException lendo "Licença de Produção Necessária". IronZIP não leu IRONZIP_LICENSE_KEY por conta própria, então o aplicativo tem que atribuir IronZip.License.LicenseKey a si. Para os arquivos de documentação do agente IronZIP e um teste de aceitação de um único prompt, veja o guia de assistentes de codificação de IA.
Como o serviço deve passar documentos para IronZIP?
Add, AddArchiveEntry e FromFiles todos deixaram a pasta em uma sonda, mesmo de um caminho relativo como 2025/letter.pdf, e a extração manteve a última das duas entradas com o mesmo nome. Adicionar um caminho de pasta lançou UnauthorizedAccessException. O serviço, portanto, copia cada documento para uma pasta temporária sob o nome que as regras lhe dão e adiciona as cópias.
A falha do construtor cobre todas as maneiras de abrir um arquivo AES-256 com uma única entrada, já que o fluxo, o byte array e as sobrecargas FromArchive lançaram o mesmo System.Exception. Com duas ou mais entradas AES-256, o construtor as listava mesmo com uma senha errada, enquanto um arquivo Tradicional lançou ZipException no construtor. A extração retornou o arquivo de uma entrada intacto e lançou ArgumentException com "Senha inválida!!" para cada senha errada, vazia ou ausente.
O nível de compressão de ZIP não fez diferença no IronZIP 2026.10.2. Os níveis 0, 1, 6 e 9 produziram o mesmo arquivo de 970.545 bytes de 1.042.684 bytes de documentos sonda, e cada construção levou de 119 a 121 ms.
/plan Draft the Implementation Plan for this change, and wait for review before you edit anything.
Move every IronZIP call out of the controller into Services/CaseArchiveBuilder.cs.
Register it in DI as a singleton.
Given the case folder, the ticked relative paths and the password, it returns the ZIP bytes.
The service works in this order:
1. It copies each document into a new folder under the system temp path.
2. Each copy gets the entry name from the rules.
3. It adds those copies and saves the archive beside that folder.
4. It extracts that archive with the same password into a second folder.
5. It compares the SHA-256 of every extracted file with its source.
6. On any difference, it throws with the document's entry name.
Both folders are removed in a finally block.
The controller keeps the password, selection and path checks.
Afterward, repeat the /browser pass over TestData/expected.csv and report each row.
Compare o serviço do agente com este. Ele é construído contra o IronZIP 2026.10.2, e ele retornou todos os quatro arquivos intactos e não deixou nenhuma pasta temporária para trás.
using System.Security.Cryptography;
using IronZip;
using IronZip.Enum;
public sealed class CaseArchiveBuilder
{
public byte[] Build(string caseFolder, IReadOnlyList<string> relativePaths, string password)
{
var work = Path.Combine(Path.GetTempPath(), "case-" + Guid.NewGuid().ToString("N"));
var staged = Path.Combine(work, "staged");
var check = Path.Combine(work, "check");
Directory.CreateDirectory(staged);
try
{
var sources = new Dictionary<string, string>();
foreach (var relativePath in relativePaths)
{
var entryName = relativePath.Replace('/', '_');
var source = Path.Combine(caseFolder, relativePath);
File.Copy(source, Path.Combine(staged, entryName));
sources.Add(entryName, source);
}
var zipPath = Path.Combine(work, "case.zip");
using (var archive = new IronZipArchive())
{
archive.Encrypt(password, EncryptionMethods.AES256);
foreach (var entryName in sources.Keys)
archive.Add(Path.Combine(staged, entryName));
archive.SaveAs(zipPath);
}
IronZipArchive.ExtractArchiveToDirectory(zipPath, check, password);
if (Directory.GetFiles(check).Length != sources.Count)
throw new InvalidOperationException("The archive does not hold one entry per document.");
foreach (var (entryName, source) in sources)
{
var extracted = Path.Combine(check, entryName);
if (!File.Exists(extracted) ||
!SHA256.HashData(File.ReadAllBytes(extracted)).SequenceEqual(SHA256.HashData(File.ReadAllBytes(source))))
throw new InvalidOperationException($"{entryName} did not come back from the archive intact.");
}
return File.ReadAllBytes(zipPath);
}
finally
{
Directory.Delete(work, recursive: true);
}
}
}
Como você prova que cada arquivo contém os arquivos certos?
O /goal executa até que seu objetivo seja alcançado e não para para pedir confirmação ao longo do caminho.
/goal Every archive the download page produces matches TestData/manifest.csv.
Create a console project at tools/ArchiveAudit that meets these conditions:
- It references IronZIP 2026.10.2.
- The web project's compile items exclude it.
- Its startup copies IRONZIP_LICENSE_KEY into IronZip.License.LicenseKey.
Start CaseDocs with dotnet run --launch-profile http before the first post.
Stop it once the audit passes.
For each expected.csv row with the outcome zip, the audit does this:
1. Post that case page's form with every document ticked and the row's password.
2. Store the response as audit-output/<case>.zip.
3. Extract it with IronZipArchive.ExtractArchiveToDirectory and the password.
4. Confirm that the entry names and SHA-256 values equal that case's manifest rows.
Confirm too that extraction with a wrong password throws.
Keep fixing the app and rerunning the audit until all four archives pass.
Then put the results table in the Walkthrough and in your reply.
O próprio leitor do .NET não pode fazer essa verificação. O System.IO.Compression listou os nomes das entradas dos arquivos de calibração AES-256, mas lançou InvalidDataException, "método de compressão não suportado", para o conteúdo de todas as 15 entradas, então um teste construído sobre ele pode contar entradas sem nunca ler um byte.
Como você aplica as regras de download para tarefas posteriores?
De acordo com a documentação das regras do Antigravity, as regras vêm de AGENTS.md, GEMINI.md e dos arquivos .agents/rules/*.md em cada pasta desde o arquivo editado até a raiz do espaço de trabalho. Os arquivos em .agents/rules devem abrir com cabeçalho YAML nomeando um trigger válido, e um gatilho ausente ou não reconhecido faz o Antigravity descartar a regra sem mensagem. Com model_decision, apenas o caminho e a descrição da regra entram no prompt, e o agente carrega o texto completo quando sua tarefa se encaixa na descrição.
O /learn transforma correções da sessão em uma regra ou uma habilidade. A página de comandos de barra diz que ela pode escrever AGENTS.md, GEMINI.md ou um arquivo em .agents/rules, então nomeie o caminho da regra no prompt.
/learn Turn what this session established about case downloads into a rule.
Write it at .agents/rules/case-archives.md.
Start the file with YAML frontmatter that sets trigger: model_decision.
Add a description saying the rule applies to work on case downloads or IronZIP archives.
The rule covers these points:
- how entry names are formed, and why
- how the saved archive is verified
- which temporary folders each request creates, and when they are deleted
- the messages for a short password and an empty selection
- that no change to the download is finished until two checks succeed
Those two checks are the expected.csv browser pass and the tools/ArchiveAudit run.
Record only what this session verified, and list anything unproven as open.
Depois, leia as primeiras linhas do arquivo e confirme que o cabeçalho soletra o gatilho model_decision, em snake case.
Quando você deve despachar mais de um agente?
Dê os testes automatizados para um agente e as evidências do navegador para um segundo.
Split this work between Agent A and Agent B.
Agent A creates CaseDocs.Tests, an xUnit project that references IronZIP 2026.10.2.
Keep it outside the web project's build.
The tests work like this:
- They start the app with WebApplicationFactory<Program>.
- They post the download form for every expected.csv row and assert the outcome.
- For zip rows, they extract the response with IronZIP into a temporary folder.
- They compare the names and SHA-256 values with manifest.csv.
- One test shows that a path outside the case folder gets a 400 response.
- They assert on extracted files, never on archive bytes.
Agent B starts once Agent A's suite passes:
1. Start the app with dotnet run --launch-profile http (http://localhost:5065).
2. Use /browser to download C-1002 and C-1003 from their case pages, and record each session.
3. Read each file's name and size from what the browser receives or from the response headers.
4. Stop the app.
5. Add the two recordings and one screenshot per finished page to the Walkthrough.
If there is no Walkthrough, save them under audit-output/ instead.
List them with those names and sizes in your reply.
If Agent A's suite does not pass, report the failing tests instead.
Os testes que publicam o formulário através de WebApplicationFactory não precisam de navegador e de porta aberta, então capturam um nome de entrada quebrado em segundos.
O que os prompts produziram em uma execução real?
Todos os sete prompts executados em uma conversa Antigravity CLI, em ordem, sem ninguém no teclado, em um novo aplicativo .NET 9 MVC que continha os cinco casos, as regras e ambos os arquivos CSV. As figuras abaixo vêm de nossas próprias construções de lançamento, downloads do Chrome headless e extração do IronZIP, não das respostas do agente.
- Após o prompt 01 e no aplicativo final, o código correspondia a todas as seis linhas expected.csv na passagem do navegador independente e respondeu ao caminho editado com um 400.
- Em ambos os pontos, a extração do IronZIP de cada download retornou os nomes e valores SHA-256 do manifesto para 5 de 5, 6 de 6, 1 de 1 e 3 de 3 documentos.
- Em ambos os pontos, a extração com uma senha errada lançou "Senha inválida!!".
- Os arquivos finais chegaram a 979.949, 779.422, 3.637 e 154.332 bytes, os mesmos tamanhos que o serviço acima produz.
- A passagem final de download não deixou nenhum arquivo CaseDocs na pasta temporária.
- As construções de lançamento do aplicativo, a ferramenta de auditoria e o projeto de teste reportaram 0 avisos e 0 erros.
- O pacote xUnit passou 7 de 7 em 2 segundos.
- Antes de escrever a leitura de retorno, o prompt 01 testou o IronZIP em um projeto de console de rascunho e atingiu a falha de uma entrada.
- O controlador do prompt 01 abriu o arquivo com o construtor apenas quando mais de um documento foi marcado.
- Para um único documento, esse controlador listou a entrada com System.IO.Compression.
- O prompt 04 substitui essa verificação por extração e uma comparação de SHA-256.
- A auditoria /goal passou na sua primeira execução sem nada para corrigir.
- /learn escreveu uma regra de 68 linhas com o gatilho model_decision.
- No prompt 03 o agente testou o aviso de chave ausente com um -Command powershell aninhado cujas aspas duplas expandiram IRONZIP_LICENSE_KEY.
- A mensagem de erro resultante carregava o valor da chave para o modelo e para os arquivos de transcrição do Antigravity em .gemini/antigravity-cli, enquanto nenhum arquivo de repositório o mantinha.
- Alguns passos foram executados de forma diferente da página. O subagente do /browser não pôde se conectar ao Chrome na máquina de teste ("Não foi possível encontrar DevToolsActivePort"), então o agente dirigiu o Chrome headless com seu próprio script do Playwright para cada passagem do navegador, as capturas de tela e ambas as gravações. Sua resposta ainda creditava o subagente do navegador. Os prompts 01, 04 e 06 cada um disse que estavam aguardando revisão e depois foram editados no mesmo turno. O CLI manteve um plano e um Walkthrough para toda a conversa, e os prompts posteriores sobrescreveram ambos, então apenas as respostas mantiveram as tabelas anteriores. A regra /learn afirmou uma causa tirada da decompilação do IronZIP e nomeou System.IO.Compression como uma forma de extrair esses arquivos. Um agente fez as duas metades do prompt de dois agentes em um único turno da mesma conversa. A ferramenta de auditoria tem como alvo .NET 10. Cada prompt de permissão foi ignorado.
O guia ChatGPT Codex divide um trabalho de admissão de arquivo entre agentes exploradores e trabalhadores, e sua execução gerou quatro threads de agente. O guia Claude Code planeja uma atualização no local de arquivos de casos criptografados no modo de plano, como os prompts /plan fazem aqui. O registro de execução do hub fornece a versão do Antigravity, modelo, durações de prompts e máquina de teste.
Solução de problemas
- Proteção por Senha ZIP para o exemplo de onde esta página começa
- Extração de ZIP Protegido para a chamada de extração em que cada verificação confia
- Visualizar Entradas de Arquivo quando você precisa de nomes de entradas e tamanhos sem extrair
- Chaves de Licença do IronZIP se cada download terminar em uma LicensingException
- Limites de Tamanho de Arquivo e Arquivo do IronZIP antes de servir casos além de 4 GB ou 65.535 documentos
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.