Referência do Manifest

Todo mini-programa, addon e plugin requer um arquivo manifest.json que descreve os metadados, permissões e pontos de entrada da extensão. O manifest segue o schema Manifest v2.

Exemplo Mínimo

O manifest mais simples válido para um mini-programa:

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "entry": "index.html",
  "base_url": "https://cdn.example.com/my-app/"
}

Exemplo Completo

Um manifest completo com todos os campos comumente usados:

{
  "name": "word-counter",
  "version": "1.2.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Word Counter",
  "description": "Conte palavras no seu histórico de chat por papel e visualize tendências",
  "icon": "https://cdn.example.com/word-counter/icon.png",
  "author": {
    "name": "Jane Developer",
    "url": "https://janedev.com"
  },
  "entry": "index.html",
  "base_url": "https://cdn.example.com/word-counter/",
  "permissions": ["storage", "chat:read", "ui:toast"],
  "keywords": ["statistics", "utility", "word-count"],
  "license": "MIT",
  "repository": "https://github.com/janedev/word-counter",
  "min_platform_version": "1.0.0"
}

Referência de Campos

Campos Obrigatórios

`name`

Nome único do pacote. Usado como identificador interno para isolamento de armazenamento, verificações de instalação e lookups de registro.

Propriedade	Valor
Tipo	`string`
Padrão	`^[a-z0-9-]+$` (apenas letras minúsculas, dígitos, hífens)
Comprimento máx	64 caracteres
Obrigatório	Sim

"name": "word-counter"

cuidado

O nome deve ser globalmente único dentro do registro. Escolha um nome descritivo. Você não pode mudá-lo após publicar sem criar uma nova entrada de pacote.

`version`

String de versão semântica. Deve seguir o formato semver.

Propriedade	Valor
Tipo	`string`
Padrão	`^\d+\.\d+\.\d+` (major.minor.patch, prerelease opcional)
Obrigatório	Sim

"version": "1.0.0"

Ao atualizar seu app no registro, incremente a versão tanto no manifest quanto na entrada do registry/packages.json.

Campos Fortemente Recomendados

`abi`

Versão da ABI (Application Binary Interface) que este manifest targetiza. Deve ser 1 para a plataforma atual.

Propriedade	Valor
Tipo	`integer`
Constante	`1`
Obrigatório	Tecnicamente opcional, mas fortemente recomendado

"abi": 1

A plataforma rejeita manifests com valores de abi diferentes de 1. Se omitido, a plataforma assume ABI 1 mas declaração explícita é preferida para compatibilidade futura.

`type`

Tipo de extensão. Determina o ambiente de runtime e capacidades disponíveis.

Propriedade	Valor
Tipo	`string`
Enum	`"plugin"`, `"addon"`, `"mini-program"`
Padrão	`"plugin"`

"type": "mini-program"

Tipo	Runtime	Surface de UI	Requisitos
`plugin`	WASM (kernel slots 4-7)	Nenhum (hooks apenas)	`wasm` + `wasm_sha256`
`addon`	WASM ou JS	Slots de UI nomeados	`wasm` ou `entry`
`mini-program`	iframe sandboxed (origem nula)	Painel completo (substitui chat)	`entry` + `base_url`

`entry`

Caminho para o arquivo HTML de entrada, relativo a base_url.

Propriedade	Valor
Tipo	`string`
Obrigatório	Sim para mini-programas e addons HTML

"entry": "index.html"

A plataforma busca {base_url}{entry} no momento da instalação e cacheia o HTML para uso offline.

`base_url`

URL base para resolver o arquivo de entrada e caminhos de assets relativos (imagens, scripts, stylesheets).

Propriedade	Valor
Tipo	`string` (URI)
Obrigatório	Sim para mini-programas

"base_url": "https://cdn.example.com/word-counter/"

Uma tag <base href="{base_url}"> é injetada no iframe para que caminhos relativos no seu HTML resolvam corretamente.

informação

Para bundles .ais instalados via upload de arquivo, base_url é definido como local:// automaticamente já que todos os assets estão inlineados.

Campos de Metadados Opcionais

`title`

Nome de exibição legível por humanos mostrado na App Store e diálogo de permissão. Se omitido, name é usado.

Propriedade	Valor
Tipo	`string`

"title": "Word Counter"

`description`

Descrição curta para listagem na store e diálogo de permissão.

Propriedade	Valor
Tipo	`string`
Comprimento máx	256 caracteres

"description": "Conte palavras no seu histórico de chat por papel e visualize tendências"

`icon`

URL para uma imagem de ícone quadrada. Tamanho recomendado: 128x128 PNG. Exibido no grid de apps e listagem da store.

Propriedade	Valor
Tipo	`string` (URI)

"icon": "https://cdn.example.com/word-counter/icon.png"

dica

Use um PNG quadrado de 128x128 pixels com fundo transparente ou escuro para combinar com o tema escuro da plataforma. SVG também é aceito.

`author`

Informação do autor.

Propriedade	Valor
Tipo	`object`
Propriedades	`name` (string, máx 100), `url` (string, URI)

"author": {
  "name": "Jane Developer",
  "url": "https://janedev.com"
}

`license`

Identificador de licença SPDX.

Propriedade	Valor
Tipo	`string`

"license": "MIT"

`repository`

URL do repositório de código fonte.

Propriedade	Valor
Tipo	`string` (URI)

"repository": "https://github.com/janedev/word-counter"

`keywords`

Palavras-chave de busca para descoberta na App Store.

Propriedade	Valor
Tipo	`string[]`
Máx itens	10
Máx por keyword	32 caracteres

"keywords": ["statistics", "utility", "word-count"]

`min_platform_version`

Versão mínima da plataforma AISCouncil requerida para rodar esta extensão.

Propriedade	Valor
Tipo	`string` (semver)

"min_platform_version": "1.0.0"

Permissões

`permissions`

Array de strings de permissão que a extensão solicita. O usuário deve aprovar estas no momento da instalação.

Propriedade	Valor
Tipo	`string[]`
Itens únicos	Sim

"permissions": ["storage", "chat:read", "ui:toast"]

Permissões Disponíveis

Permissão	Descrição	Auto-concedida?
`storage`	Armazenamento chave-valor isolado por app	Sim (sempre permitido)
`chat:read`	Ler histórico de chat e subscrever a novas mensagens	Não
`chat:write`	Enviar mensagens como o usuário (dispara respostas de IA)	Não
`config:read`	Ler a configuração do bot ativo (provedor, modelo, prompt de sistema)	Não
`config:write`	Modificar a configuração do bot ativo	Não
`auth:read`	Ler informações do usuário (nome, email, foto de perfil) e nível de assinatura	Não
`ui:toast`	Mostrar notificações toast na UI da plataforma	Não
`ui:modal`	Mostrar diálogos de confirmação	Não
`hooks:action`	Registrar e disparar eventos de hook	Não
`hooks:filter`	Registrar hooks de filtro	Não
`network:fetch`	Fazer requisições de rede proxied através da plataforma (futuro)	Não
`secrets:sync`	Ler e escrever chaves de API para transferência dispositivo-para-dispositivo	Não
`pages:publish`	Publicar páginas web em bcz.co	Não

aviso

Solicite apenas as permissões que seu app realmente precisa. Cada permissão adicional aumenta a barreira para instalação -- usuários são mais propensos a aprovar apps com menos permissões.

Campos Específicos de Plugin

Estes campos são usados por plugins e addons WASM, não por mini-programas.

`wasm`

URL para o binário WASM.

Propriedade	Valor
Tipo	`string` (URI)
Obrigatório	Para plugins

"wasm": "https://cdn.example.com/my-plugin/plugin.wasm"

`wasm_sha256`

Digest hex SHA-256 do binário WASM para verificação de integridade.

Propriedade	Valor
Tipo	`string`
Padrão	`^[0-9a-f]{64}$`
Obrigatório	Para plugins

"wasm_sha256": "a1b2c3d4e5f6..."

`segment_size`

Tamanho do segmento de memória do módulo WASM em bytes.

Propriedade	Valor
Tipo	`integer`
Mínimo	0

"segment_size": 4194304

Campos Avançados

`pages`

Caminhos de páginas adicionais para mini-programas multi-página.

Propriedade	Valor
Tipo	`string[]`

"pages": ["settings.html", "about.html"]

`hooks`

Registros de hooks para plugins e addons. Cada hook tem um nome e prioridade opcional.

Propriedade	Valor
Tipo	`object[]`

"hooks": [
  { "name": "chat:before-send", "priority": 50 },
  { "name": "message:filter", "priority": 100 }
]

Nomes de hooks devem corresponder a ^[a-z][a-z0-9_.:-]*$ e ter no máximo 128 caracteres. Prioridade varia de 0 (mais cedo) a 999 (mais tarde), padrão 100.

`settings`

Configurações configuráveis pelo usuário que aparecem na UI de Configurações da plataforma.

Propriedade	Valor
Tipo	`object` (chaves são nomes de configurações, valores são definições de configuração)

"settings": {
  "theme": {
    "type": "select",
    "label": "Tema de Cores",
    "default": "dark",
    "options": [
      { "value": "dark", "label": "Escuro" },
      { "value": "light", "label": "Claro" }
    ]
  },
  "maxMessages": {
    "type": "number",
    "label": "Máx mensagens para analisar",
    "default": 500,
    "description": "Limita o número de mensagens de chat carregadas"
  },
  "autoRefresh": {
    "type": "boolean",
    "label": "Auto-atualizar ao abrir",
    "default": true
  }
}

Tipos de configuração: string, number, boolean, select.

`mcp_tools`

Declarações de ferramentas MCP (Model Context Protocol) fornecidas por esta extensão.

Propriedade	Valor
Tipo	`object[]`

"mcp_tools": [
  {
    "name": "count-words",
    "description": "Conta palavras no texto fornecido",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": { "type": "string" }
      },
      "required": ["text"]
    }
  }
]

Requisitos Específicos por Tipo

Campo	Plugin	Addon	Mini-Program
`name`	Obrigatório	Obrigatório	Obrigatório
`version`	Obrigatório	Obrigatório	Obrigatório
`type`	`"plugin"`	`"addon"`	`"mini-program"`
`wasm`	Obrigatório	Obrigatório se sem `entry`	Não usado
`wasm_sha256`	Obrigatório	Obrigatório se usar `wasm`	Não usado
`entry`	Não usado	Obrigatório se sem `wasm`	Obrigatório
`base_url`	Não usado	Opcional	Obrigatório

Validação

Use o script de validação integrado para verificar seu manifest antes de publicar:

# Valida um único arquivo de manifest
python3 registry/validate.py manifest caminho/para/manifest.json

O validador verifica:

Campos obrigatórios presentes
name corresponde ao padrão ^[a-z0-9-]+$ e tem no máximo 64 caracteres
version é semver válido
abi é 1 (se presente)
type é um de plugin, addon, mini-program
Permissões são do conjunto permitido
Campos obrigatórios específicos por tipo estão presentes (ex: entry para mini-programas)
Nenhum campo desconhecido (schema é estrito com additionalProperties: false)

dica

O JSON Schema é publicado em registry/manifest-schema.json. Você pode usá-lo com qualquer validador JSON Schema para integração de IDE ou pipelines de CI.

Referência do Schema

O schema do manifest é definido como JSON Schema (Draft 2020-12) e está disponível em:

https://aiscouncil.com/schema/manifest/v2

Referencie-o no seu manifest para autocompletar no editor:

{
  "$schema": "https://aiscouncil.com/schema/manifest/v2",
  "name": "my-app",
  "version": "1.0.0"
}

A maioria dos editores (VS Code, JetBrains, etc.) fornecerá autocompletar e validação quando o campo $schema está presente.

Exemplo Mínimo​

Exemplo Completo​

Referência de Campos​

Campos Obrigatórios​

name​

version​

Campos Fortemente Recomendados​

abi​

type​

entry​

base_url​

Campos de Metadados Opcionais​

title​

description​

icon​

author​

license​

repository​

keywords​

min_platform_version​

Permissões​

permissions​

Permissões Disponíveis​

Campos Específicos de Plugin​

wasm​

wasm_sha256​

segment_size​

Campos Avançados​

pages​

hooks​

settings​

mcp_tools​

Requisitos Específicos por Tipo​

Validação​

Referência do Schema​