Documentation de développement de plugins — CosmosBox · Vous savez faire du HTML, vous savez créer des plugins

Démarrage rapide

Un plugin est essentiellement une page web (HTML / CSS / JS). Écrivez la page, puis empaquetez-la avec l'empaqueteur de plugins de CosmosBox en fichier .cbplugin — envoyez-le à n'importe qui, il s'installe et fonctionne.

Un chemin plus rapide : génération IA en un clic — décrivez le besoin dans le chat IA ("fais un poisson en bois numérique"), et l'IA produit un plugin installable.

Structure des répertoires

Un plugin peut être un fichier unique ou un répertoire multi-fichiers (.cbplugin est essentiellement un zip) :

my-plugin/ — structure du paquet de plugin

my-plugin/
├── manifest.json      // manifeste du plugin (obligatoire)
├── index.html         // page d'entrée (entry y pointe)
├── style.css          // ressources optionnelles
└── app.js             // scripts optionnels

Champs de manifest.json

manifest.json — exemple complet

{
  "pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d",  // ID unique UUID v4 (généré par l'empaqueteur)
  "id": "mobi.reader",            // ancien ID court (compatibilité)
  "name": "MOBI Reader",
  "version": "1.2.0",
  "author": "YuzhouHe",
  "description": "Lit les e-books MOBI / AZW3",
  "icon": "📖",                    // Emoji / URL d'image / Base64
  "entry": "index.html",
  "permissions": ["file.read", "storage"],
  "fileTypes": ["mobi", "azw3"]      // routage de fichiers : ouverture auto par type
}

Champ	Obligatoire	Description
`pluginId`	✓	ID unique UUID v4, protection anti-collision au niveau système ; laissez l'empaqueteur le générer
`id`	—	Ancien ID court (ex. `mobi.reader`) ; à omettre pour les nouveaux plugins, simple compatibilité
`name`	✓	Nom d'affichage du plugin
`version`	✓	Version sémantique, ex. `1.2.0`
`author`	—	Nom de l'auteur
`description`	—	Description en une ligne pour le marché de plugins
`icon`	—	Emoji, URL d'image ou image Base64
`entry`	✓	Chemin relatif du fichier d'entrée (généralement `index.html`)
`permissions`	✓	Déclarations de permissions (ex. `file.read` / `storage`), accordées une à une dans le centre de permissions
`fileTypes`	—	Extensions déclarées pour le routage de fichiers (ouverture externe auto)

Flux d'empaquetage

Choisissez le type de plugin : fichier unique / répertoire multi-fichiers
Renseignez le code : collez le HTML ou sélectionnez un dossier
Configurez manifest.json : nom / version / entrée / permissions / types de fichiers
Choisissez le chiffrement : plugins publics → .cbplugin ; plugins payants/privés → .encplugin (chiffrement AES + double confirmation du mot de passe)
Générez le paquet : en un clic, prêt à partager / importer et installer

🛠️

Empaquetage par lot : l'environnement de développement fournit le script pack_plugins.ps1 — exécutez-le une fois après avoir modifié des plugins pour régénérer tous les .cbplugin (ignore automatiquement .git / node_modules / build).

Plugins chiffrés .encplugin

	`.cbplugin`	`.encplugin`
Usage	Partage public	Distribution payante / privée
Contenu	Zip en clair	Chiffré AES
Import	Installer directement	Saisir le mot de passe (dialogue auto à l'ouverture externe)

⚠️ Les mots de passe de plugins chiffrés sont irrécupérables — perdre le mot de passe signifie que le plugin ne pourra jamais être déchiffré. Gardez-le précieusement.

Sandbox et permissions

Les plugins s'exécutent dans un WebView sandboxé — ouvert et sûr à la fois :

Mécanisme	Description
Injection d'en-têtes CSP	Meta tag + en-tête HTTP, double voie ; limite le chargement de scripts externes
eval / Function désactivés	Couverture totale Object.defineProperty, aucune exécution de code dynamique
Limite réseau	Requêtes réseau des plugins limitées à 60/min contre les abus
Isolation des chemins	Les plugins ne lisent/écrivent que leur propre répertoire sandbox (protection anti path traversal)
Centre de permissions	Déclarations permissions + accords individuels, chaque action auditable
Pont JS	Capacités natives via API de pont (stockage / presse-papiers / fichiers…), bibliothèque de base injectée par l'hôte

ID unique de plugin (UUID v4)

Les IDs de plugin utilisent l'UUID v4 (122 bits d'entropie aléatoire) — les collisions sont pratiquement impossibles, donc des IDs utilisateur dupliqués ne s'écrasent ni ne se suppriment jamais. Recommandé : laisser l'empaqueteur le générer ; en saisie manuelle, utilisez le format UUID complet (8-4-4-4-12) — l'empaqueteur le valide.

Génération de plugins IA en un clic

Décrivez le besoin directement dans le chat IA de CosmosBox :

Chat IA

Vous → Fais un poisson en bois numérique ; taper doit faire un son avec animation
IA → ✅ Plugin « Poisson en bois numérique » généré — installez et lancez en un clic

Les plugins générés par IA reçoivent la bibliothèque de base injectée automatiquement (stockage / presse-papiers / adaptation au mode sombre) et s'installent depuis le centre de plugins immédiatement ; pas satisfait ? Faites continuer l'IA dans la page d'édition.

📤

Vous avez créé votre propre plugin ? Soumettez-le via la soumission de plugins pour entrer dans le marché (canal bientôt disponible).