Plugin-Entwicklungsdoku — CosmosBox · HTML können? Dann können Sie Plugins

Schnellstart

Ein Plugin ist im Kern eine Webseite (HTML / CSS / JS). Schreiben Sie die Seite und packen Sie sie mit dem Plugin-Packager in CosmosBox zu einer .cbplugin-Datei — an jeden gesendet, installiert und läuft sie sofort.

Der schnellere Weg: KI-Erzeugung per Klick — beschreiben Sie den Bedarf im KI-Chat ("baue einen digitalen Holzfisch"), und die KI produziert ein installierbares Plugin.

Verzeichnisstruktur

Ein Plugin kann eine einzelne Datei oder ein Mehrdateien-Verzeichnis sein (.cbplugin ist im Kern ein ZIP-Paket):

my-plugin/ — Plugin-Paketstruktur

my-plugin/
├── manifest.json      // Plugin-Manifest (erforderlich)
├── index.html         // Einstiegsseite (entry zeigt darauf)
├── style.css          // optionale Ressourcen
└── app.js             // optionale Skripte

manifest.json-Felder

manifest.json — vollständiges Beispiel

{
  "pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d",  // UUID-v4-eindeutige ID (vom Packager automatisch erzeugt)
  "id": "mobi.reader",            // alte Kurz-ID (Kompatibilität)
  "name": "MOBI Reader",
  "version": "1.2.0",
  "author": "YuzhouHe",
  "description": "Liest MOBI / AZW3-E-Books",
  "icon": "📖",                    // Emoji / Bild-URL / Base64
  "entry": "index.html",
  "permissions": ["file.read", "storage"],
  "fileTypes": ["mobi", "azw3"]      // Datei-Routing: externe Dateien öffnen automatisch nach Typ
}

Feld	Erforderlich	Beschreibung
`pluginId`	✓	UUID-v4-eindeutige ID, Kollisionsschutz auf Systemebene; vom Packager automatisch erzeugen lassen
`id`	—	Alte Kurz-ID (z. B. `mobi.reader`); bei neuen Plugins weglassen, nur Kompatibilität
`name`	✓	Anzeigename des Plugins
`version`	✓	Semantische Version, z. B. `1.2.0`
`author`	—	Autorenname
`description`	—	Einzeilige Beschreibung für den Plugin-Markt
`icon`	—	Emoji, Bild-URL oder Base64-Bild
`entry`	✓	Relativer Pfad der Einstiegsdatei (üblich `index.html`)
`permissions`	✓	Berechtigungsdeklarationen (z. B. `file.read` / `storage`), einzeln im Berechtigungszentrum gewährt
`fileTypes`	—	Deklarierte Dateiendungen fürs Datei-Routing (Auto-Öffnen von außen)

Paketablauf

Plugin-Typ wählen: Einzeldatei / Mehrdateien-Verzeichnis
Code eintragen: HTML einfügen oder Ordner auswählen
manifest.json konfigurieren: Name / Version / Entry / Berechtigungen / Dateitypen
Verschlüsselung wählen: öffentliche Plugins → .cbplugin; kostenpflichtige/private Plugins → .encplugin (AES-Verschlüsselung + doppelte Passwortbestätigung gegen Tippfehler)
Paket erzeugen: per Klick, sofort teilbar / importierbar & installierbar

🛠️

Stapel-Paketierung: Die Entwicklungsumgebung liefert das Skript pack_plugins.ps1 — nach Plugin-Änderungen einmal ausführen, um alle .cbplugin-Dateien neu zu erzeugen (überspringt automatisch .git / node_modules / build-Verzeichnisse).

Verschlüsselte Plugins .encplugin

	`.cbplugin`	`.encplugin`
Zweck	Öffentliches Teilen	Kostenpflichtig / privat verteilen
Inhalt	Klartext-ZIP	AES-verschlüsselt
Import	Direkt installieren	Passwort eingeben (automatischer Dialog bei externem Öffnen)

⚠️ Passwörter verschlüsselter Plugins können nicht wiederhergestellt werden — ein verlorenes Passwort bedeutet, dass das Plugin nie entschlüsselt werden kann. Bewahren Sie es sicher auf.

Sandbox & Berechtigungen

Plugins laufen in einem Sandbox-WebView — offen und sicher zugleich:

Mechanismus	Beschreibung
CSP-Header-Injektion	Meta-Tag + HTTP-Header, doppelter Pfad; begrenzt externe Skripte
eval / Function deaktiviert	Vollständige Object.defineProperty-Abdeckung, keine dynamische Code-Ausführung
Netzwerk-Drossel	Plugin-Anfragen auf 60/min begrenzt, gegen Missbrauch
Pfad-Isolation	Plugins können nur ihr eigenes Sandbox-Verzeichnis lesen/schreiben (Path-Traversal-Schutz)
Berechtigungszentrum	permissions-Deklarationen + Einzelgewährung, jede Aktion prüfbar
JS-Brücke	Native Fähigkeiten über Brücken-API (Speicher / Zwischenablage / Dateien…), Basisbibliothek vom Host automatisch injiziert

Eindeutige Plugin-ID (UUID v4)

Plugin-IDs nutzen UUID v4 (122 Bit Zufallsentropie) — Kollisionen sind praktisch ausgeschlossen, doppelte Benutzer-IDs überschreiben oder löschen sich also nie. Empfohlen: vom Packager automatisch erzeugen lassen; bei manueller Vergabe das volle UUID-Format (8-4-4-4-12) verwenden — der Packager validiert es.

KI-Plugin-Erzeugung per Klick

Beschreiben Sie den Bedarf direkt im CosmosBox-KI-Chat:

KI-Chat

Du → Baue einen digitalen Holzfisch; beim Tippen ein Geräusch mit Animation
KI → ✅ Plugin „Digitaler Holzfisch“ erzeugt — per Klick installieren und ausführen

KI-erzeugte Plugins erhalten die Basisbibliothek automatisch injiziert (Speicher / Zwischenablage / Dunkelmodus-Anpassung) und sind sofort aus der Plugin-Zentrale installierbar; nicht zufrieden? Lassen Sie die KI im Bearbeitungsfenster einfach weiterarbeiten.

📤

Eigenes Plugin gebaut? Über die Plugin-Einreichung kommt es in den Plugin-Markt (Kanal bald verfügbar).