Paket-Lebenszyklus, Hosts und Berechtigungen
Wie AI Game Dev Pakete ausführt: Extension Host, Aktivierung, Desktop vs. CLI, Ebenen, Updates, Fehler, Logs, Berechtigungen und API-Versionierung.
Diese Seite erklärt, was mit einem Paket zwischen Installation und Entfernung passiert: wo sein Code läuft, wann er startet und stoppt, was er tun darf, wie Fehler zu dir gelangen und wie die API, gegen die er geschrieben ist, kompatibel bleibt. Das ist der Hintergrund, den du brauchst, bevor du ein Paket auslieferst, das andere installieren.
Wo ein Paket läuft
Die App führt Paketcode in einem Extension Host aus, einem separaten Prozess, so wie VS Code Erweiterungen ausführt. Der Hintergrunddienst der App (der Kernel) betreibt einen Extension Host pro geöffnetem Projekt, gemeinsam genutzt von jedem Desktop-Fenster und jeder CLI, die dieses Projekt geöffnet haben. Dein Code kommuniziert nur über ctx.aigd und einen Nachrichtenkanal mit der App.
| Desktop-App | gamedev CLI | |
|---|---|---|
| Angezeigte UI | Alles: Menüs, Panels, Views, benutzerdefinierte Editoren, Statusleiste, Tutorials, Webviews | Slash-Befehle, Tools-Zeilen, Nachrichten, Quick Picks, Eingabefelder, Formulare, Fortschrittszeilen |
| Nur-Desktop-Aufrufe | Verhalten | Lösen zu undefined oder einem inerten Objekt auf, einmal protokolliert |
| Der Extension-Host-Prozess | Pro Projekt geteilt | Pro Projekt geteilt |
Ein Fenster ohne Projekt betreibt keinen Host. Ein auf Benutzerebene installiertes Paket läuft in jedem geöffneten Projekt, es sei denn, dieses Projekt schließt es aus.
Lazy Activation
- Installieren. Die App liest das Manifest und registriert alle deklarierten Beiträge auf einmal: der Slash-Befehl, der Tools-Schalter, die Menüeinträge und Views erscheinen, ohne dass Code ausgeführt wird.
- Aktivieren. Wenn zum ersten Mal etwas den Code braucht (ein Befehl wird ausgeführt, eine View wird geöffnet, eine Fähigkeit wird eingeschaltet, eine passende Datei wird geöffnet, ein Engine-Projekt wird gefunden), lädt der Host
mainund ruftactivate(ctx)auf. Abhängigkeiten werden zuerst aktiviert.activatehat 30 Sekunden. - Ausführen. Deine Handler beantworten die Aufrufe der App. Alles, was du registriert hast, steht in
ctx.subscriptions. - Stoppen. Bei Entfernung, einem deaktivierten Paket, einem Update oder einem Neustart des Hosts ruft der Host
deactivate()auf (optional) und gibtctx.subscriptionsfrei.
Ein Paket mit main und ohne jedes Ereignis startet nach dem ersten Rendern (onStartupFinished). Die vollständige Liste der Ereignisse steht in der Manifest-Referenz.
Der Host startet neu, wenn sich die Menge der aktiven Pakete ändert, und nach einem Absturz (nach 1, 5 und 30 Sekunden). Nach drei Abstürzen in fünf Minuten bleibt er gestoppt, bis der Benutzer im Fenster Packages auf Reload klickt.
Ebenen, Lock-Dateien und Updates
Benutzer fügen ein Paket auf einer von drei Ebenen hinzu:
| Ebene | Deklariert in | Geteilt |
|---|---|---|
| Benutzer | ~/.ai-game-dev/packages.json | Alle Projekte dieses Benutzers |
| Projekt | <project>/.ai-game-dev/packages.json | Eingecheckt: jedes Teammitglied bekommt es |
| Lokal | <project>/.ai-game-dev/packages.local.json | Nur dieser Computer, nie eingecheckt |
Lokal schlägt Projekt, Projekt schlägt Benutzer. Eine Lock-Datei neben jeder Ebene pinnt die exakte Version, das Tarball und die Hashes fest, sodass ein Teammitglied dieselben Bytes installiert. Auto-Update ist standardmäßig aktiv (pro Paket, pro Computer): Alle vier Stunden bringt die App jedes Paket auf die neueste Version innerhalb seines deklarierten Bereichs, die die App ausführen kann, und zeigt eine Benachrichtigung für den gesamten Lauf. Ein file:-Link und eine auf ein Tag gepinnte GitHub-Quelle werden nie automatisch aktualisiert.
Fehler und Logs
Der Host ordnet jeden Fehler seinem Paket zu: ein Throw in activate, deactivate oder einem Handler, eine unbehandelte Exception oder unhandled rejection aus deinen Dateien, ctx.reportError(err) und ctx.log.error(msg, err). Der Tab Errors jedes Pakets im Fenster Packages zeigt „N Fehler · M Abstürze“ und die aktuelle Liste mit Stacks.
gamedev pkg logs acme.level-tools # its last 100 lines
gamedev pkg logs acme.level-tools -f # and every new one until Ctrl+CLogs liegen auf jeder Plattform in ~/.ai-game-dev/daemon/logs/. Fehler von Drittanbieter-Paketen werden nie an das Crash-Reporting von AI Game Dev gesendet; nur die eigenen Pakete von AI Game Dev melden dorthin, und das nur mit der Zustimmung des Benutzers zum Crash-Reporting.
Berechtigungen und Vertrauen
AI Game Dev folgt dem VS-Code-Modell: Es gibt keine Sandbox und keine Berechtigungsabfrage. Der Code eines Pakets läuft mit den Rechten des Benutzers: Er kann Dateien lesen und schreiben, Prozesse starten und das Netzwerk nutzen, wie jedes Programm, das der Benutzer installiert. Was Benutzer stattdessen informiert:
- Alles zuerst sichtbar. Alles, was ein Paket anzeigt, ist in seinem Manifest deklariert und sichtbar, bevor sein Code ausgeführt wird.
- Eigentümerschaft wird erzwungen. Ein Paket kann nur ids registrieren oder ändern, die ihm gehören (
<package id>.<local>-Befehle, -Ansichten und -Kontextschlüssel,<publisher>--<name>-Server), geprüft beim Laden und bei jedem Aufruf. Es darf jeden Befehl ausführen, eigene, die eines anderen Pakets oder einen App-Befehl; eine Webview-Seite darf nur die Befehle ihres eigenen Pakets und App-Befehle ausführen. - Was es deklariert, wird angezeigt. Vor der Installation zeigt das Packages-Fenster, was der Registry-Index angibt: nativen Code, Claude-Plugins, Abhängigkeiten. Nach der Installation zeigt es außerdem, ob das Paket Code ausführt, Tool-Server startet oder eine Spiel-Engine beiträgt. Das sind Informationen, niemals eine Sperre.
- Registry-Prüfungen. Jede Version in der Community-Registry hat automatische Prüfungen auf Zugangsdaten, auf den Agenten gerichtete Prompt-Injection, Malware und Archiv-Tricks bestanden; siehe Registry-Regeln und -Prüfungen.
- Widerruf. AI Game Dev kann eine bösartige Version widerrufen; jede App deaktiviert sie beim nächsten Lesen des Index (innerhalb von etwa einer halben Stunde).
- Webview-Seiten sind isoliert. Eine Seite läuft in einem Sandbox-Frame ohne Node.js; ein Webview-Fenster hat überhaupt keinen Netzwerkzugriff.
Als Autor: Versende keine Geheimnisse, mache aus README und Manifest klar ersichtlich, was dein Paket tut, und frage den Nutzer, bevor du etwas Destruktives tust.
Versionierung und Kompatibilität
Zwei Nummern versionieren die API, und keine davon ist die version deines Pakets:
- Die Paket-API-Version (derzeit 0.4.0) wächst nur durch Ergänzungen: neue Member und Contribution Points. Deine
aigd.d.tsnennt die Version, für die sie geschrieben wurde. - Die älteste unterstützte
engines.aigd(derzeit 0.18.0) ist die älteste Untergrenze, die die App noch lädt. Sie anzuheben ist der einzige Weg, wie ein stabiles Member jemals entfernt wird – nach mindestens zwei Minor-Releases mit Deprecation-Warnungen.
Regeln für dich:
- Setze
engines.aigdauf die älteste App, mit der du getestet hast. Eine ältere App lehnt das Paket ab und fordert den Nutzer zum Aktualisieren auf. - Teste optionale Member per Feature-Test (
aigd.gameEngines?,item.pulse?.()), wenn du Apps unterstützen willst, die älter als das Member sind. - Vorgeschlagene Member sind von all dem nicht abgedeckt. Siehe stabile und vorgeschlagene API.
- Deine gespeicherten Daten gehören dir: Versioniere sie mit
dataVersionund migriere sie inactivate.
Verwandte Seiten
- Package API für die Aufrufe.
- Packages für Stufen und Updates aus Nutzersicht.
- Package-CLI-Referenz für
pkg logs,linkunddev.