# Ciclo de vida de los paquetes, hosts y permisos — App y CLI de AI Game Dev · AI Game Developer Wiki

Cómo ejecuta AI Game Dev un paquete: Extension Host, activación diferida, niveles, actualizaciones, errores, permisos y versionado de la API.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/app/package-lifecycle).

Esta página explica qué le ocurre a un paquete entre la instalación y la eliminación: dónde se ejecuta su código, cuándo se inicia y se detiene, qué tiene permitido hacer, cómo te llegan los errores y cómo se mantiene compatible la API con la que está escrito. Es el contexto que necesitas antes de publicar un paquete que otras personas instalarán.

## Dónde se ejecuta un paquete

La aplicación ejecuta el código de los paquetes en un **Extension Host**, un proceso aparte, igual que VS Code ejecuta las extensiones. El servicio en segundo plano de la aplicación (el Kernel) ejecuta un Extension Host por cada proyecto abierto, compartido por todas las ventanas de escritorio y las CLI que tengan ese proyecto abierto. Tu código se comunica con la aplicación solo a través de `ctx.aigd`, mediante un canal de mensajes.

|  | Aplicación de escritorio | CLI `gamedev` |
| --- | --- | --- |
| Interfaz que muestra | Todo: menús, paneles, vistas, editores personalizados, barra de estado, tutoriales, webviews | Comandos de barra, filas de Tools, mensajes, selecciones rápidas, cuadros de entrada, formularios, líneas de progreso |
| Llamadas solo para escritorio | Trabajo | Se resuelven a `undefined` o a un objeto inerte, registrado una vez |
| El proceso Extension Host | Compartido por proyecto | Compartido por proyecto |

Una ventana sin proyecto no ejecuta ningún host. Un paquete instalado a nivel de usuario se ejecuta en todos los proyectos abiertos, a menos que ese proyecto lo excluya.

## Activación diferida

1. **Instalación.** La aplicación lee el manifiesto y registra de una vez todas las contribuciones declaradas: el comando de barra, el conmutador de Tools, los elementos de menú y las vistas aparecen sin ejecutar nada de código.
2. **Activación.** La primera vez que algo necesita el código (se ejecuta un comando, se abre una vista, se activa una capacidad, se abre un archivo coincidente, se encuentra un proyecto de motor) el host carga `main` y llama a `activate(ctx)`. Las dependencias se activan primero. `activate` dispone de 30 segundos.
3. **Ejecución.** Tus controladores responden a las llamadas de la aplicación. Todo lo que registraste está en `ctx.subscriptions`.
4. **Detención.** Al eliminar el paquete, al deshabilitarlo, al actualizarlo o al reiniciar el host, el host llama a `deactivate()` (opcional) y libera `ctx.subscriptions`.

Un paquete con `main` y sin ningún evento arranca tras el primer renderizado (`onStartupFinished`). La lista completa de eventos está en la [referencia del manifiesto](https://ai-game.dev/es/docs/wiki/app/package-manifest#activation-events).

El host se reinicia cuando cambia el conjunto de paquetes activos y tras un fallo (a los 1, 5 y 30 segundos). Después de tres fallos en cinco minutos permanece detenido hasta que el usuario hace clic en **Reload** en la ventana Packages.

## Niveles, bloqueos y actualizaciones

Los usuarios añaden un paquete en uno de tres niveles:

| Nivel | Declarado en | Compartido |
| --- | --- | --- |
| Usuario | `~/.ai-game-dev/packages.json` | Todos los proyectos de este usuario |
| Proyecto | `<project>/.ai-game-dev/packages.json` | Confirmado en el repositorio: lo recibe todo el equipo |
| Local | `<project>/.ai-game-dev/packages.local.json` | Solo este ordenador, nunca se confirma |

Local prevalece sobre proyecto, y proyecto sobre usuario. Un archivo de bloqueo junto a cada nivel fija la versión exacta, el tarball y los hashes, de modo que un compañero de equipo instala exactamente los mismos bytes. La actualización automática está activada por defecto (por paquete y por ordenador): cada cuatro horas la aplicación lleva cada paquete a la versión más reciente dentro de su rango declarado que la aplicación pueda ejecutar y muestra una sola notificación para toda la operación. Un enlace `file:` y una fuente de GitHub fijada a una etiqueta nunca se actualizan automáticamente.

## Errores y registros

El host atribuye cada fallo a su paquete: una excepción lanzada en `activate`, en `deactivate` o en un controlador, una excepción no capturada o un rechazo no gestionado procedente de tus archivos, `ctx.reportError(err)` y `ctx.log.error(msg, err)`. La pestaña **Errors** de cada paquete en la ventana Packages muestra «N errores · M fallos» y la lista reciente con las pilas de llamadas.

```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
```

Los registros están en `~/.ai-game-dev/daemon/logs/` en todas las plataformas. Los errores de paquetes de terceros nunca se envían al informe de fallos de AI Game Dev; solo los propios paquetes de AI Game Dev informan allí, y solo con el consentimiento del usuario para enviar informes de fallos.

## Permisos y confianza

AI Game Dev sigue el modelo de VS Code: **no hay sandbox ni solicitud de permisos**. El código de un paquete se ejecuta con los permisos del propio usuario: puede leer y escribir archivos, iniciar procesos y usar la red, como cualquier programa que el usuario instale. Lo que mantiene informados a los usuarios es lo siguiente:

- **Todo visible de antemano.** Todo lo que muestra un paquete está declarado en su manifiesto y es visible antes de que se ejecute su código.
- **La propiedad se aplica.** Un paquete solo puede registrar o cambiar los ids que posee (comandos, vistas y claves de contexto `<package id>.<local>`, servidores `<publisher>--<name>`), comprobado al cargar y en cada llamada. Puede ejecutar cualquier comando: el suyo, el de otro paquete o un comando de la app; una página webview solo puede ejecutar los comandos de su propio paquete y los comandos de la app.
- **Se muestra lo que declara.** Antes de instalar, la ventana Packages muestra lo que indica el índice del registro: código nativo, plugins de Claude, dependencias. Una vez instalado, también muestra si el paquete ejecuta código, inicia servidores de herramientas o aporta un motor de juego. Esto es información, nunca una barrera.
- **Comprobaciones del registro.** Cada versión del registro comunitario superó comprobaciones automáticas de credenciales, inyección de prompts dirigida al agente, malware y trucos de archivo; consulta [Reglas y comprobaciones del registro](https://ai-game.dev/es/docs/wiki/app/package-registry).
- **Revocación.** AI Game Dev puede revocar una versión maliciosa; cada app la desactiva en su siguiente lectura del índice (en unos treinta minutos).
- **Las páginas webview están aisladas.** Una página se ejecuta en un marco en sandbox sin Node.js; una ventana webview no tiene ningún acceso a la red.

Como autor: no distribuyas secretos, deja claro en tu README y en el manifiesto lo que hace tu paquete, y pregunta al usuario antes de cualquier acción destructiva.

## Versionado y compatibilidad

Dos números versionan la API, y ninguno es la `version` de tu paquete:

- **La versión de la API de paquetes** (ahora 0.4.0) solo crece mediante adiciones: nuevos miembros y puntos de contribución. Tu `aigd.d.ts` indica la versión para la que se escribió.
- **El `engines.aigd` más antiguo admitido** (ahora 0.18.0) es el mínimo más antiguo que la app sigue cargando. Elevarlo es la única forma de eliminar algún día un miembro estable, tras al menos dos versiones menores de avisos de obsolescencia.

Reglas para ti:

- Establece `engines.aigd` en la app más antigua con la que hayas probado. Una app anterior a esa rechaza el paquete y le indica al usuario que actualice.
- Comprueba en tiempo de ejecución los miembros opcionales (`aigd.gameEngines?`, `item.pulse?.()`) cuando quieras dar soporte a apps anteriores a ese miembro.
- Los miembros propuestos no están cubiertos por nada de esto. Consulta [API estable y propuesta](https://ai-game.dev/es/docs/wiki/app/package-api#stable-vs-proposed).
- Tus datos almacenados son tuyos: versiónalos con `dataVersion` y migra en `activate`.

## Páginas relacionadas

- [API de paquetes](https://ai-game.dev/es/docs/wiki/app/package-api) para las llamadas.
- [Paquetes](https://ai-game.dev/es/docs/wiki/app/packages) para los niveles y las actualizaciones desde el punto de vista del usuario.
- [Referencia de la CLI de paquetes](https://ai-game.dev/es/docs/wiki/app/package-cli) para `pkg logs`, `link` y `dev`.

---

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

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