Documentación de desarrollo de plugins — CosmosBox · ¿Sabes HTML? Puedes crear plugins

Inicio rápido

Un plugin es esencialmente una página web (HTML / CSS / JS). Escribe la página y empaquétala con el empaquetador de plugins dentro de CosmosBox como archivo .cbplugin — envíalo a cualquiera y se instala y funciona.

Un camino más rápido: generación con IA en un clic — describe lo que quieres en el chat IA ("haz un pez de madera digital"), y la IA produce un plugin instalable.

Estructura de directorios

Un plugin puede ser un solo archivo o un directorio de varios archivos (.cbplugin es esencialmente un paquete zip):

my-plugin/ — estructura del paquete de plugin

my-plugin/
├── manifest.json      // manifiesto del plugin (obligatorio)
├── index.html         // página de entrada (entry apunta a ella)
├── style.css          // recursos opcionales
└── app.js             // scripts opcionales

Campos de manifest.json

manifest.json — ejemplo completo

{
  "pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d",  // ID único UUID v4 (generado automáticamente por el empaquetador)
  "id": "mobi.reader",            // ID corta antigua (compatibilidad)
  "name": "MOBI Reader",
  "version": "1.2.0",
  "author": "YuzhouHe",
  "description": "Lee libros electrónicos MOBI / AZW3",
  "icon": "📖",                    // Emoji / URL de imagen / Base64
  "entry": "index.html",
  "permissions": ["file.read", "storage"],
  "fileTypes": ["mobi", "azw3"]      // enrutado de archivos: se abren automáticamente por tipo
}

Campo	Obligatorio	Descripción
`pluginId`	✓	ID único UUID v4, protección contra colisiones a nivel de sistema; deja que el empaquetador lo genere
`id`	—	ID corta antigua (p. ej. `mobi.reader`); omítela en plugins nuevos, solo compatibilidad
`name`	✓	Nombre visible del plugin
`version`	✓	Versión semántica, p. ej. `1.2.0`
`author`	—	Nombre del autor
`description`	—	Descripción de una línea para el mercado de plugins
`icon`	—	Emoji, URL de imagen o imagen Base64
`entry`	✓	Ruta relativa del archivo de entrada (normalmente `index.html`)
`permissions`	✓	Declaraciones de permisos (p. ej. `file.read` / `storage`), concedidos uno a uno en el centro de permisos
`fileTypes`	—	Extensiones declaradas para el enrutado de archivos (apertura automática externa)

Flujo de empaquetado

Elige el tipo de plugin: archivo único / directorio de varios archivos
Rellena el código: pega el HTML o selecciona una carpeta
Configura manifest.json: nombre / versión / entrada / permisos / tipos de archivo
Elige el cifrado: plugins públicos → .cbplugin; plugins de pago/privados → .encplugin (cifrado AES + doble confirmación de contraseña)
Genera el paquete: con un clic, listo para compartir / importar e instalar

🛠️

Empaquetado por lotes: el entorno de desarrollo incluye el script pack_plugins.ps1 — ejecútalo una vez tras editar plugins para regenerar todos los .cbplugin (omite automáticamente .git / node_modules / build).

Plugins cifrados .encplugin

	`.cbplugin`	`.encplugin`
Uso	Compartir en público	Distribución de pago / privada
Contenido	Zip en claro	Cifrado AES
Importación	Instalar directamente	Introducir contraseña (diálogo automático al abrir externamente)

⚠️ Las contraseñas de plugins cifrados no se pueden recuperar — perder la contraseña significa que el plugin nunca podrá descifrarse. Guárdala bien.

Sandbox y permisos

Los plugins se ejecutan en un WebView con sandbox — abierto y seguro a la vez:

Mecanismo	Descripción
Inyección de encabezado CSP	Meta tag + encabezado HTTP, doble vía; limita la carga de scripts externos
eval / Function desactivados	Cobertura total con Object.defineProperty, sin ejecución de código dinámico
Límite de red	Peticiones de red de plugins limitadas a 60/min contra abusos
Aislamiento de rutas	Los plugins solo leen/escriben su propio directorio de sandbox (protección anti path traversal)
Centro de permisos	Declaraciones permissions + concesión individual, cada acción auditable
Puente JS	Capacidades nativas vía API puente (almacenamiento / portapapeles / archivos…), biblioteca base inyectada por el host

ID única de plugin (UUID v4)

Los IDs de plugin usan UUID v4 (122 bits de entropía aleatoria) — las colisiones son prácticamente imposibles, así que IDs duplicados del usuario nunca se sobrescriben ni se borran. Recomendado: dejar que el empaquetador lo genere; al especificarlo a mano, usa el formato UUID completo (8-4-4-4-12) — el empaquetador lo valida.

Generación de plugins con IA en un clic

Describe lo que quieres directamente en el chat IA de CosmosBox:

Chat IA

Tú → Haz un pez de madera digital; al tocar hace un sonido con animación
IA → ✅ Plugin "Pez de madera digital" generado — instálalo y ejecútalo con un clic

Los plugins generados por IA reciben la biblioteca base inyectada automáticamente (almacenamiento / portapapeles / adaptación al modo oscuro) y se pueden instalar desde el centro de plugins al momento; ¿no te convence? Pide a la IA que siga editándolo en la página de edición.

📤

¿Has creado tu propio plugin? Envíalo por la vía de envío de plugins para entrar en el mercado (canal próximamente).