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.
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
- 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.
- 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
maine chamaactivate(ctx). As dependências são ativadas primeiro.activatetem 30 segundos. - Execução. Seus handlers respondem às chamadas do app. Tudo o que você registrou está em
ctx.subscriptions. - 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 descartactx.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í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.
gamedev pkg logs acme.level-tools # its last 100 lines
gamedev pkg logs acme.level-tools -f # and every new one until Ctrl+COs 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.tsindica a versão para a qual foi escrito. - O
engines.aigdmais 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.aigdpara 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
dataVersione migre-os emactivate.
Páginas relacionadas
- API de pacotes para as chamadas.
- Pacotes para níveis e atualizações do ponto de vista do usuário.
- Referência da CLI de pacotes para
pkg logs,linkedev.