# Ciclo de vida de pacotes, hosts e permissões — App e CLI do AI Game Dev · AI Game Developer Wiki

Como o AI Game Dev executa um pacote: Extension Host, ativação tardia, desktop vs CLI, níveis, atualizações, erros, logs, permissões e versões de API.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/app/package-lifecycle).

Esta página explica o que acontece com um pacote entre a instalação e a remoção: onde seu código é executado, quando ele inicia e para, o que ele pode fazer, como os erros chegam até você e como a API contra a qual ele foi escrito se mantém compatível. É o contexto que você precisa antes de publicar um pacote que outras pessoas instalam.

## Onde um pacote é executado

O app executa o código do pacote em um **Extension Host**, um processo separado, do mesmo jeito que o VS Code executa extensões. O serviço em segundo plano do app (o Kernel) executa um Extension Host por projeto aberto, compartilhado por toda janela desktop e CLI que tenha esse projeto aberto. Seu código conversa com o app apenas por meio de `ctx.aigd`, através de um canal de mensagens.

|  | App desktop | CLI `gamedev` |
| --- | --- | --- |
| UI que exibe | Tudo: menus, painéis, views, editores personalizados, barra de status, tutoriais, webviews | Comandos slash, linhas de Tools, mensagens, seleções rápidas, caixas de entrada, formulários, linhas de progresso |
| Chamadas exclusivas do desktop | Funcionam | Resolvem para `undefined` ou um objeto inerte, registrado uma vez |
| O processo Extension Host | Compartilhado por projeto | Compartilhado por projeto |

Uma janela sem projeto não executa nenhum host. Um pacote instalado no nível de usuário é executado em todo projeto aberto, a menos que esse projeto o exclua.

## Ativação tardia

1. **Instalação.** O app lê o manifesto e registra de uma vez todas as contribuições declaradas: o comando slash, o interruptor de Tools, os itens de menu e as views aparecem sem executar nenhum código.
2. **Ativação.** Na primeira vez que algo precisa do código (um comando é executado, uma view é aberta, uma capacidade é ativada, um arquivo correspondente é aberto, um projeto de engine é encontrado), o host carrega `main` e chama `activate(ctx)`. As dependências são ativadas primeiro. `activate` tem 30 segundos.
3. **Execução.** Seus handlers respondem às chamadas do app. Tudo o que você registrou está em `ctx.subscriptions`.
4. **Parada.** Na remoção, em um pacote desativado, em uma atualização ou em uma reinicialização do host, o host chama `deactivate()` (opcional) e descarta `ctx.subscriptions`.

Um pacote com `main` e sem nenhum evento inicia após a primeira renderização (`onStartupFinished`). A lista completa de eventos está na [referência do manifesto](https://ai-game.dev/pt-br/docs/wiki/app/package-manifest#activation-events).

O host reinicia quando o conjunto de pacotes ativos muda, e após uma falha (após 1, 5 e 30 segundos). Após três falhas em cinco minutos, ele permanece parado até que o usuário clique em **Reload** na janela Packages.

## Níveis, arquivos de lock e atualizações

Os usuários adicionam um pacote em um de três níveis:

| Nível | Declarado em | Compartilhado |
| --- | --- | --- |
| Usuário | `~/.ai-game-dev/packages.json` | Todos os projetos deste usuário |
| Projeto | `<project>/.ai-game-dev/packages.json` | Versionado: todo membro da equipe recebe |
| Local | `<project>/.ai-game-dev/packages.local.json` | Apenas este computador, nunca versionado |

Local tem precedência sobre projeto, e projeto sobre usuário. Um arquivo de lock ao lado de cada nível fixa a versão exata, o tarball e os hashes, para que um membro da equipe instale exatamente os mesmos bytes. A atualização automática vem ativada por padrão (por pacote, por computador): a cada quatro horas o app leva cada pacote para a versão mais recente dentro do intervalo declarado que o app consegue executar, e mostra uma única notificação para toda a execução. Um link `file:` e uma origem do GitHub fixada em uma tag nunca são atualizados automaticamente.

## Erros e logs

O host atribui cada falha ao seu pacote: um throw em `activate`, `deactivate` ou em um handler, uma exceção não capturada ou uma rejeição não tratada vinda dos seus arquivos, `ctx.reportError(err)` e `ctx.log.error(msg, err)`. A aba **Errors** de cada pacote na janela Packages mostra "N errors · M crashes" e a lista recente com stacks.

```bash
gamedev pkg logs acme.level-tools          # its last 100 lines
gamedev pkg logs acme.level-tools -f       # and every new one until Ctrl+C
```

Os logs ficam em `~/.ai-game-dev/daemon/logs/` em todas as plataformas. Erros de pacotes de terceiros nunca são enviados ao relatório de falhas do AI Game Dev; apenas os pacotes do próprio AI Game Dev reportam lá, e somente com o consentimento do usuário para relatórios de falhas.

## Permissões e confiança

O AI Game Dev segue o modelo do VS Code: **não há sandbox nem prompt de permissão**. O código de um pacote é executado com as permissões do próprio usuário: ele pode ler e gravar arquivos, iniciar processos e usar a rede, como qualquer programa que o usuário instala. O que mantém os usuários informados, em vez disso:

- **Tudo visível antes.** Tudo o que um pacote exibe é declarado em seu manifesto e fica visível antes que o código seja executado.
- **A propriedade é aplicada.** Um pacote só pode registrar ou alterar ids que possui (comandos, views e chaves de contexto `<package id>.<local>`, servidores `<publisher>--<name>`), verificado no carregamento e em cada chamada. Ele pode executar qualquer comando — o seu, o de outro pacote ou um comando do app; uma página webview pode executar apenas os comandos do próprio pacote e os comandos do app.
- **O que ele declara é exibido.** Antes da instalação, a janela Packages mostra o que o índice do registro informa: código nativo, plugins do Claude, dependências. Depois de instalado, ela também mostra se o pacote executa código, inicia servidores de ferramentas ou contribui com uma engine de jogo. Isso é informação, nunca uma barreira.
- **Verificações do registro.** Toda versão no registro da comunidade passou por verificações automáticas de credenciais, injeção de prompt voltada ao agente, malware e truques de arquivo; consulte [Regras e verificações do registro](https://ai-game.dev/pt-br/docs/wiki/app/package-registry).
- **Revogação.** O AI Game Dev pode revogar uma versão maliciosa; cada app a desativa na próxima leitura do índice (em cerca de meia hora).
- **As páginas webview são isoladas.** Uma página é executada em um frame em sandbox sem Node.js; uma janela webview não tem acesso algum à rede.

Como autor: não distribua segredos, deixe claro pelo README e pelo manifesto o que seu pacote faz e pergunte ao usuário antes de qualquer ação destrutiva.

## Versionamento e compatibilidade

Duas numerações versionam a API, e nenhuma delas é a `version` do seu pacote:

- **A versão da API de pacotes** (atualmente 0.4.0) cresce apenas por adições: novos membros e pontos de contribuição. Seu `aigd.d.ts` indica a versão para a qual foi escrito.
- **O `engines.aigd` mais antigo suportado** (atualmente 0.18.0) é o piso mais antigo que o app ainda carrega. Elevá-lo é a única forma de remover um membro estável, após pelo menos duas versões menores de avisos de descontinuação.

Regras para você:

- Defina `engines.aigd` para o app mais antigo com o qual você testou. Um app mais antigo que isso recusa o pacote e avisa o usuário para atualizar.
- Teste por recurso os membros opcionais (`aigd.gameEngines?`, `item.pulse?.()`) quando quiser suportar apps mais antigos que o membro.
- Membros propostos não são cobertos por nada disso. Consulte [API estável e proposta](https://ai-game.dev/pt-br/docs/wiki/app/package-api#stable-vs-proposed).
- Seus dados armazenados são seus: versione-os com `dataVersion` e migre-os em `activate`.

## Páginas relacionadas

- [API de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/package-api) para as chamadas.
- [Pacotes](https://ai-game.dev/pt-br/docs/wiki/app/packages) para níveis e atualizações do ponto de vista do usuário.
- [Referência da CLI de pacotes](https://ai-game.dev/pt-br/docs/wiki/app/package-cli) para `pkg logs`, `link` e `dev`.

---

Source (HTML): https://ai-game.dev/pt-br/docs/wiki/app/package-lifecycle

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/app/package-lifecycle
