HMS MediaEngine Agent
362e089be0
Der Nutzer hat recht: Der Ordner war voller Entwicklungs-Muell. Jetzt ist sauber getrennt: ROOT (was der Nutzer sieht und braucht): - run.py = das Programm - hms_app/ = der Anwendungscode - HMS MediaEngine.app = macOS Doppelklick-Starter - HMS-Start.vbs = Windows Doppelklick-Starter - HMS-Install.vbs = Windows Erst-Installation - HMS-Mac-Install.command = macOS Homebrew-Installation - HMS-Portable-Install.command = macOS Portable-Installation (16GB-Fix) - installer_gui.py = grafischer Installer - launcher.pyw + launcher_core.py = interne Start-Logik - LIESMICH.txt = 10-Zeilen-Kurzanleitung - .gitignore _entwicklung/ (alles andere, NICHT benoetigt): - packages/ apps/ native/ plugins/ tools/ schemas/ tests/ docs/ build/ fixture_profiles/ - PLAN.md STATUS.md ERRORS.md TEST_REPORT.md CHANGELOG.md README.md - pyproject.toml uv.lock setup_*.sh/ps1 make_mac_app.py Diese Trennung gilt ab sofort fuer alle Commits. Der Nutzer kann _entwicklung/ loeschen wenn er Platz braucht - die App laeuft ohne. Verifiziert: App startet nach Aufraeumen unveraendert (Health 200).
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# Plugin-Lebenszyklus
|
||
|
||
Dieses Dokument beschreibt den Lebenszyklus eines Plugins. Grundlage sind PLAN.md §14.5 (Plugin-Lebenszyklus), §14.6 (Sicherheitsgrenze), §26.3 (Show-Lock) und die Implementierung `packages/plugin_sdk/hms_plugin_sdk/lifecycle.py`.
|
||
|
||
## Zustände
|
||
|
||
Der Lebenszyklus kennt folgende Zustände:
|
||
|
||
```text
|
||
discovered → validated → installed → enabled → compiled → active
|
||
↘ quarantined / incompatible
|
||
```
|
||
|
||
Zusätzlich existiert der Zustand `disabled` (deaktiviert, aber installiert). Die vollständige Zustandsmenge (`lifecycle.py`):
|
||
|
||
- `discovered`
|
||
- `validated`
|
||
- `installed`
|
||
- `enabled`
|
||
- `compiled`
|
||
- `active`
|
||
- `quarantined`
|
||
- `incompatible`
|
||
- `disabled`
|
||
|
||
## Übergänge
|
||
|
||
Übergänge sind nur entlang definierter Kanten erlaubt; Sprünge sind Fehler (`InvalidTransitionError`). Die erlaubten Übergänge (`lifecycle.py`):
|
||
|
||
| Von | Nach |
|
||
| --- | --- |
|
||
| `discovered` | `validated`, `incompatible`, `quarantined` |
|
||
| `validated` | `installed`, `incompatible`, `quarantined` |
|
||
| `installed` | `enabled`, `disabled`, `quarantined` |
|
||
| `enabled` | `compiled`, `disabled`, `quarantined` |
|
||
| `compiled` | `active`, `quarantined`, `disabled` |
|
||
| `active` | `disabled`, `quarantined` |
|
||
| `disabled` | `enabled`, `quarantined` |
|
||
| `quarantined` | – (manuelle Entfernung/Neuinstallation) |
|
||
| `incompatible` | – |
|
||
|
||
## Discovery und Validierung
|
||
|
||
`discover()` scannt ein Verzeichnis mit Plugin-Ordnern, lädt `plugin.json` und validiert es (inkl. Shader-Existenz). Jedes Plugin wird in `validated` oder `incompatible`/`quarantined` überführt (`lifecycle.py`).
|
||
|
||
Die Validierung umfasst (PLAN.md §14.5):
|
||
|
||
- Manifest-Schema;
|
||
- eindeutige Plugin-ID und semantische Version;
|
||
- API-Kompatibilität;
|
||
- Pfad- und ZIP-Sicherheit;
|
||
- erlaubte Dateitypen und Größenlimits;
|
||
- Shader-Kompilierung;
|
||
- Capability-Prüfung;
|
||
- vollständige, vorab kompilierbare Adaptive-Quality-Varianten und unveränderte Parametersemantik;
|
||
- Lizenzmetadaten;
|
||
- Hash des Pakets.
|
||
|
||
## Quarantäne (§3.5, §14.5)
|
||
|
||
Ein fehlerhaftes Plugin wird **quarantiniert**, ohne ein Projekt unbrauchbar zu machen. Der Effekt wird überbrückt (`bypass_on_error`). Die Quarantäne speichert die Ursache (`last_error`). Aus `quarantined` gibt es keinen automatischen Übergang; das Plugin muss manuell entfernt oder neu installiert werden.
|
||
|
||
## Show-Lock (§26.3)
|
||
|
||
Der Show-Lock sperrt strukturelle Änderungen während einer laufenden Show:
|
||
|
||
- **Installieren/Updaten ist gesperrt.** Übergänge, die Installation/Update bedeuten (`installed` von `discovered`/`validated`), sind im Show-Lock blockiert.
|
||
- **Enable/Disable und Parameter bleiben erlaubt.** Aktivieren bereits installierter Plugins (`enabled`/`compiled`/`active`) bleibt möglich (PLAN.md §17.7 Live-Modus).
|
||
- **Versionswechsel sind gesperrt.** Ein Update startet einen neuen Zyklus; im Show-Lock wird ein Versionswechsel abgelehnt.
|
||
|
||
Der Show-Lock wird über `set_show_lock(enabled)` gesetzt (`lifecycle.py`).
|
||
|
||
## Doppelte Plugin-IDs
|
||
|
||
Doppelte Plugin-IDs sind Fehler, keine stillen Überschreibungen. Ein Versionskonflikt wird erkannt; ohne Show-Lock gewinnt der neue Stand, mit Show-Lock wird der Versionswechsel abgelehnt (`lifecycle.py`).
|
||
|
||
## Sicherheitsgrenze (§14.6)
|
||
|
||
- Shaderplugins erhalten keinen Dateisystem- oder Netzwerkzugriff.
|
||
- Native DLL-Plugins sind vor Version 2 nicht vorgesehen.
|
||
- Python-Control-/Automation-Plugins laufen später in einem separaten Prozess mit freigegebener Command-API.
|
||
- Kein Plugin greift direkt auf SQLite oder interne Python-Objekte zu.
|
||
- Pluginfehler werden einem konkreten Plugin zugeordnet und in der UI angezeigt.
|