Documentação de desenvolvimento de plugins — CosmosBox

Início rápido

Um plugin é essencialmente uma página web (HTML / CSS / JS). Escreve a página e empacota-a com o empacotador de plugins do CosmosBox num ficheiro .cbplugin — envia-o a qualquer pessoa e instala-se e funciona.

Um caminho mais rápido: geração IA num clique — descreve o que queres no chat IA ("faz um peixe de madeira digital"), e a IA produz um plugin instalável.

Estrutura de diretórios

Um plugin pode ser um ficheiro único ou um diretório de vários ficheiros (.cbplugin é essencialmente um pacote zip):

my-plugin/ — estrutura do pacote de plugin

my-plugin/
├── manifest.json      // manifesto do plugin (obrigatório)
├── index.html         // página de entrada (entry aponta para ela)
├── style.css          // recursos opcionais
└── app.js             // scripts opcionais

Campos de manifest.json

manifest.json — exemplo completo

{
  "pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d",  // ID único UUID v4 (gerado automaticamente pelo empacotador)
  "id": "mobi.reader",            // ID curta antiga (compatibilidade)
  "name": "MOBI Reader",
  "version": "1.2.0",
  "author": "YuzhouHe",
  "description": "Lê e-books MOBI / AZW3",
  "icon": "📖",                    // Emoji / URL de imagem / Base64
  "entry": "index.html",
  "permissions": ["file.read", "storage"],
  "fileTypes": ["mobi", "azw3"]      // encaminhamento de ficheiros: abertura automática por tipo
}

Campo	Obrigatório	Descrição
`pluginId`	✓	ID único UUID v4, proteção contra colisões a nível de sistema; deixa o empacotador gerá-lo
`id`	—	ID curta antiga (ex.: `mobi.reader`); omite-a em plugins novos, só compatibilidade
`name`	✓	Nome visível do plugin
`version`	✓	Versão semântica, ex.: `1.2.0`
`author`	—	Nome do autor
`description`	—	Descrição de uma linha para o mercado de plugins
`icon`	—	Emoji, URL de imagem ou imagem Base64
`entry`	✓	Caminho relativo do ficheiro de entrada (normalmente `index.html`)
`permissions`	✓	Declarações de permissões (ex.: `file.read` / `storage`), concedidas uma a uma no centro de permissões
`fileTypes`	—	Extensões declaradas para o encaminhamento de ficheiros (abertura externa automática)

Fluxo de empacotamento

Escolhe o tipo de plugin: ficheiro único / diretório de vários ficheiros
Preenche o código: cola o HTML ou seleciona uma pasta
Configura o manifest.json: nome / versão / entrada / permissões / tipos de ficheiro
Escolhe a cifragem: plugins públicos → .cbplugin; plugins pagos/privados → .encplugin (cifragem AES + dupla confirmação de palavra-passe)
Gera o pacote: num clique, pronto a partilhar / importar e instalar

🛠️

Empacotamento em lote: o ambiente de desenvolvimento fornece o script pack_plugins.ps1 — executa-o uma vez após editar plugins para regenerar todos os .cbplugin (ignora automaticamente .git / node_modules / build).

Plugins cifrados .encplugin

	`.cbplugin`	`.encplugin`
Uso	Partilha pública	Distribuição paga / privada
Conteúdo	Zip em claro	Cifrado AES
Importação	Instalar diretamente	Inserir palavra-passe (diálogo automático ao abrir externamente)

⚠️ As palavras-passe de plugins cifrados são irrecuperáveis — perder a palavra-passe significa que o plugin nunca poderá ser decifrado. Guarda-a bem.

Sandbox e permissões

Os plugins correm num WebView com sandbox — aberto e seguro ao mesmo tempo:

Mecanismo	Descrição
Injeção de cabeçalhos CSP	Meta tag + cabeçalho HTTP, dupla via; limita o carregamento de scripts externos
eval / Function desativados	Cobertura total com Object.defineProperty, sem execução de código dinâmico
Limite de rede	Pedidos de rede de plugins limitados a 60/min contra abusos
Isolamento de caminhos	Os plugins só leem/escrevem o seu próprio diretório de sandbox (proteção anti path traversal)
Centro de permissões	Declarações permissions + concessão individual, cada ação auditável
Ponte JS	Capacidades nativas via API de ponte (armazenamento / clipboard / ficheiros…), biblioteca base injetada pelo anfitrião

ID único de plugin (UUID v4)

Os IDs de plugin usam UUID v4 (122 bits de entropia aleatória) — colisões são praticamente impossíveis, por isso IDs duplicados do utilizador nunca se sobrescrevem nem se apagam. Recomendado: deixar o empacotador gerá-lo; em especificação manual, usa o formato UUID completo (8-4-4-4-12) — o empacotador valida-o.

Geração de plugins IA num clique

Descreve o que queres diretamente no chat IA do CosmosBox:

Chat IA

Tu → Faz um peixe de madeira digital; ao tocar faz um som com animação
IA → ✅ Plugin "Peixe de madeira digital" gerado — instala e executa num clique

Os plugins gerados por IA recebem a biblioteca base injetada automaticamente (armazenamento / clipboard / adaptação ao modo escuro) e podem ser instalados do centro de plugins de imediato; não gostas? Pede à IA para continuar a editar na página de edição.

📤

Criaste o teu próprio plugin? Envia-o pela submissão de plugins para entrar no mercado (canal em breve).