Visão Geral de Mini-Programas

Mini-programas são web apps sandboxed que rodam diretamente dentro da plataforma AISCouncil. Eles estendem a plataforma com funcionalidades customizadas — de ferramentas de sincronização de dispositivos a construtores visuais de páginas — tudo enquanto rodam em um ambiente seguro e controlado por permissões.

O Que São Mini-Programas?

Um mini-programa é um web app padrão HTML/CSS/JS que roda dentro de um iframe sandboxed dentro da plataforma. Em vez de navegar para um site separado, usuários lançam mini-programas da seção Apps na barra lateral. O app substitui a área de chat e tem acesso às APIs da plataforma através do SDK window.ais.

Mini-programas podem:

• Ler e enviar mensagens de chat para interagir com modelos de IA
• Armazenar dados localmente com armazenamento isolado por app
• Acessar configuração do bot para saber qual modelo está ativo
• Mostrar notificações e diálogos através da UI da plataforma
• Ler informações do usuário para personalização
• Registrar hooks para estender comportamento da plataforma

Como Funcionam

+---------------------------+
|   AISCouncil      |
|   (página host)           |
|                           |
|  +---------------------+ |
|  | Sandboxed iframe     | |
|  | (null origin)        | |
|  |                      | |
|  | window.ais SDK       | |
|  |   |                  | |
|  +---|------------------+ |
|      | postMessage          |
|      v                     |
|  Message Bridge            |
|  (verificação de permissão)|
|  (dispatch de métodos)     |
+---------------------------+

1. Injeção do SDK -- Quando um mini-programa é lançado, a plataforma cria um iframe sandboxed e injeta o SDK window.ais (~2 KB) como um preâmbulo <script> antes do código do seu app.

2. Bridge postMessage -- Toda chamada do SDK (ais.storage.get(), ais.chat.send(), etc.) envia um postMessage para a página host. O host valida as permissões do app chamador e despacha a requisição para o módulo apropriado da plataforma.

3. Respostas -- Resultados são enviados de volta ao iframe via postMessage, onde o SDK resolve a Promise correspondente.

Modelo de Segurança

Mini-programas rodam em um sandbox de segurança estrito:

Proteção	Como
Origem nula	sandbox="allow-scripts allow-forms" -- sem allow-same-origin, então o iframe recebe uma origem nula
Sem acesso ao DOM pai	Não pode ler ou modificar o DOM da página host, localStorage ou cookies
Sem acesso de rede à origem host	Não pode fazer requisições same-origin para aiscouncil.net
APIs controladas por permissão	Todo método do SDK além de storage requer uma concessão de permissão explícita do usuário
Isolamento de armazenamento por app	Chaves de armazenamento são prefixadas com mp:{app-name}: -- apps não podem ler dados uns dos outros
Cache endereçado por conteúdo	HTML de entrada é buscado e cacheado no momento da instalação, não carregado da rede a cada lançamento

aviso

Mini-programas ainda podem fazer requisições de rede para origens externas (seu próprio CDN, APIs de terceiros, etc.) já que allow-scripts permite fetch() e XMLHttpRequest. A permissão network:fetch é para futuras requisições proxied através da plataforma, não para restringir acesso de rede outbound.

Diálogo de Permissão

Quando um usuário instala um mini-programa, um diálogo de permissão mostra o nome do app, descrição e a lista de permissões que ele solicita. O usuário deve aprovar antes que a instalação prossiga. Apps que solicitam apenas storage (sempre permitido) ainda mostram o diálogo para transparência.

Comparação com Outras Plataformas

Funcionalidade	Mini-Programas aiscouncil	WeChat Mini Programs	Chrome Extensions	PWAs
Runtime	iframe sandboxed	WebView customizado	Isolated world + service worker	Aba completa do navegador
Tamanho máx	5 MB (HTML) / 50 MB (bundle)	2-20 MB	Sem limite rígido	Sem limite
Requer revisão	Não (Instalação Direta)	Sim (obrigatório)	Sim (Chrome Web Store)	Não
Suporte offline	Sim (cacheado na instalação)	Sim	Sim	Sim (Service Worker)
APIs da plataforma	SDK window.ais	API wx	API chrome	Apenas Web APIs
Modelo de segurança	iframe de origem nula	Sandbox customizado	Content Security Policy	Same-origin
Distribuição	URL, upload de arquivo, registro	Apenas WeChat Store	Chrome Web Store	Apenas URL

Encontrando e Instalando Apps

Pela App Store

1. Clique no ícone Apps na barra lateral esquerda (ou o ícone de grade de apps no header em mobile)
2. Navegue pela seção App Store na parte inferior do painel de apps
3. Clique em Install em qualquer card de app
4. Revise as permissões no diálogo e clique em Allow

Por URL (Sideloading)

1. No painel Apps, encontre a seção Sideload
2. Cole uma URL de manifest no campo de texto
3. Clique em Install
4. Revise as permissões e aprove

Por Upload de Arquivo

1. No painel Apps, clique em Upload App
2. Selecione um arquivo .html (app de arquivo único) ou bundle .ais (arquivo ZIP)
3. Revise as permissões e aprove

Veja Sideloading Apps para detalhes completos sobre todos os métodos de instalação.

Lançando e Fechando Apps

Lançar: Clique no botão Open em qualquer card de app instalado. O app substitui a área de chat e assume o painel de conteúdo principal.

Fechar: Apps podem fechar a si mesmos chamando ais.close(), ou o usuário pode clicar no botão X na barra de título dos apps para retornar à visualização de chat.

Quando um app é fechado:

• O iframe é destruído e seu handler de mensagem é removido
• A área de chat é restaurada
• Qualquer estado não salvo no app é perdido (apps devem usar ais.storage para persistir dados)

Apps Integrados

A plataforma vem com dois mini-programas integrados:

Device Sync

Sincroniza perfis, chaves de API e configurações entre dispositivos. Suporta três métodos de transferência:

• Sync LAN -- Conexão direta entre dispositivos na mesma rede
• Código QR -- Escaneie um código para parear dispositivos
• Relay de internet -- Sinalização WebRTC através da API para dispositivos em redes diferentes

Permissões: storage, config:read, auth:read, ui:toast, secrets:sync

App Builder

Construa páginas web visualmente com geração de conteúdo por IA. Escolha um template, edite seções usando o modelo de IA ativo e exporte como URL ou arquivo HTML. Publique diretamente em bcz.co com um slug customizado.

Permissões: storage, chat:read, chat:write, ui:toast, auth:read, pages:publish

Próximos Passos

• Referência do SDK -- Documentação completa da API para window.ais
• Tutorial: Construa Seu Primeiro App -- Guia passo a passo para criar um mini-programa
• Referência do Manifest -- Documentação do schema para manifest.json
• Sideloading Apps -- Instale apps de URLs, arquivos e bundles
• Publicando no Registro -- Distribua seu app para a comunidade