Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Ciclo de vida de pacotes, hosts e permissões

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.

Atualizado em 19 de novembro de 2026 Ver como Markdown

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 desktopCLI gamedev
UI que exibeTudo: menus, painéis, views, editores personalizados, barra de status, tutoriais, webviewsComandos slash, linhas de Tools, mensagens, seleções rápidas, caixas de entrada, formulários, linhas de progresso
Chamadas exclusivas do desktopFuncionamResolvem para undefined ou um objeto inerte, registrado uma vez
O processo Extension HostCompartilhado por projetoCompartilhado 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.

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ívelDeclarado emCompartilhado
Usuário~/.ai-game-dev/packages.jsonTodos os projetos deste usuário
Projeto<project>/.ai-game-dev/packages.jsonVersionado: todo membro da equipe recebe
Local<project>/.ai-game-dev/packages.local.jsonApenas 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.

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.
  • 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.
  • Seus dados armazenados são seus: versione-os com dataVersion e migre-os em activate.