Contribuindo

O AISCouncil recebe contribuições em várias áreas: o registro de modelos, traduções, documentação, mini-programas e código principal. Este guia cobre cada caminho de contribuição.

Áreas para Contribuição

Área	Dificuldade	Arquivos	Validação
Registro de Modelos	Fácil	registry/models.json	python3 registry/validate.py
Traduções	Fácil	registry/locale/{lang}.json	python3 registry/locale/validate_locale.py
Documentação	Fácil	doc.aiscouncil.net/site/docs/	Preview local com npm start
Mini-Programas	Médio	manifest.json + index.html	python3 registry/validate.py packages
Correções de Bugs / Funcionalidades	Médio-Difícil	src/*.js, modules/*/index.ts	./build.sh && npm test

Registro de Modelos

O registro de modelos (registry/models.json) é uma lista de provedores e modelos LLM mantida pela comunidade. Adicionar um novo modelo é a maneira mais fácil de contribuir.

Adicionando um Modelo

1. Faça fork do repositório
2. Edite registry/models.json -- adicione seu modelo sob o provedor apropriado
3. Valide:

python3 registry/validate.py

4. Envie um pull request

Formato de Entrada de Modelo

Cada modelo requer estes campos:

{
  "id": "model-id-from-provider",
  "name": "Nome Legível por Humanos",
  "provider": "provider-id",
  "context": 128000,
  "maxOutput": 8192,
  "pricing": { "input": 3.0, "output": 15.0 },
  "capabilities": ["streaming", "vision", "tools"],
  "tier": "paid"
}

O script de validação verifica:

• Estrutura JSON válida
• Todos os campos obrigatórios presentes (id, name, provider, context, maxOutput, pricing, capabilities, tier)
• Nenhum ID de modelo duplicado
• Capabilities do conjunto permitido: vision, tools, streaming, json_mode, reasoning, code
• Tier do conjunto permitido: free, paid, enterprise

dica

Verifique as entradas existentes em models.json para exemplos. Match o estilo de formatação (indentação de 2 espaços, campos na mesma ordem) para diffs limpos.

Traduções

O aplicativo usa arquivos de locale contribuídos pela comunidade para internacionalização. Cada arquivo de locale traduz o wizard e strings da UI.

Adicionando ou Atualizando uma Tradução

1. Copie registry/locale/en.json para registry/locale/{lang}.json (use códigos ISO 639-1: es, zh, ar, fr, etc.)
2. Traduza todos os valores de string (o lado direito de cada par chave-valor)
3. Atualize _meta.lang e _meta.name
4. Valide:

python3 registry/locale/validate_locale.py registry/locale/{lang}.json

5. Envie um pull request

Regras de Tradução

• Traduza: Todos os valores de string e _meta.name
• Não altere: Nomes de chaves, código _meta.lang, _meta.version, variáveis de template dentro de {chaves}

Variáveis de template como {name}, {count} e {error} são substituídas em tempo de execução. Mantenha-as exatamente como aparecem na fonte em inglês.

{
  "_meta": {
    "lang": "es",
    "name": "Espanol",
    "version": 1,
    "module": "wizard"
  },
  "createProfile": "Crear Perfil de IA",
  "operator": "Operador: {name}",
  "modelsSelected": "{count} seleccionados:"
}

informação

Veja registry/locale/TRANSLATING.md para o guia completo de tradução, incluindo regras de codificação de caracteres e idiomas prioritários.

Idiomas Atualmente Necessários

Traduções completas existem para inglês, espanhol, chinês, árabe, francês, português, japonês, coreano, alemão e russo. Traduções ainda são necessárias para: hindi, turco, ucraniano, tailandês, polonês, italiano, holandês, indonésio e vietnamita.

Documentação

A documentação fica no site Docusaurus em doc.aiscouncil.net/site/docs/.

Editando Docs

1. Edite ou crie arquivos Markdown em doc.aiscouncil.net/site/docs/
2. Visualize localmente:

cd doc.aiscouncil.net/site
npm install
npm start

3. Se adicionar uma nova página, registre-a em doc.aiscouncil.net/site/sidebars.ts
4. Envie um pull request

Convenções de Docs

• Use frontmatter com sidebar_position, title e description
• Use admonitions :::tip, :::info, :::warning para callouts
• Use tabelas para comparações estruturadas
• Inclua exemplos de comando onde aplicável
• Mantenha a prosa direta e concisa

Mini-Programas

Mini-programas são web apps sandboxed que rodam dentro da plataforma AISCouncil via iframes.

Criando um Mini-Programa

1. Crie um manifest.json:

{
  "name": "meu-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Meu App",
  "description": "O que meu app faz",
  "entry": "index.html",
  "base_url": "https://seu-cdn.com/meu-app/",
  "permissions": ["storage"]
}

2. Crie index.html usando o SDK window.ais:

<!DOCTYPE html>
<html>
  <body>
    <h1>Meu App</h1>
    <script>
      ais.ready(() => {
        ais.ui.toast("Olá do meu app!");
      });
    </script>
  </body>
</html>

3. Hospede seus arquivos em qualquer CDN (GitHub Pages, Cloudflare Pages, Vercel)

4. Teste localmente instalando via URL do manifest:

AIS.MiniPrograms.install("https://seu-cdn.com/meu-app/manifest.json");

Publicando no Registro

1. Adicione sua entrada de app ao registry/packages.json
2. Valide:

python3 registry/validate.py packages

3. Envie um pull request

Veja a documentação do SDK e sdk/ais.d.ts para a API completa de mini-programas.

dica

O diretório examples/hello-world/ contém um mini-programa completo funcional que você pode usar como ponto de partida.

Contribuições de Código

Configuração de Desenvolvimento

git clone https://github.com/nicholasgasior/bcz.git
cd bcz
npm install
./build.sh
npm test

Ciclo Editar-Build-Testar

1. Edite arquivos fonte em src/ (nunca edite index.html diretamente)
2. Build: ./build.sh
3. Teste: npm test
4. Verifique: ./build.sh --check

Para módulos TypeScript:

1. Edite: modules/{name}/index.ts
2. Verifique tipos: npm run check
3. Build: ./build.sh (auto-compila TypeScript)
4. Teste: npm run test:modules

Estilo de Código

A base de código segue convenções estritas. Revise estas antes de enviar código:

Sem dependências externas. O bundle do navegador contém apenas JS vanilla e WASM opcional. Sem React, sem jQuery, sem lodash, sem pacotes npm em tempo de execução.

HTML semântico. Use <dialog> para modais, <details> para colapsáveis, <output> para regiões dinâmicas, atributo hidden para visibilidade. Alcance um elemento HTML nativo antes de escrever JS.

CSS sem classes. Targetize elementos por ID, tag semântica ou atributo data-*. Use classes apenas para: alternância de estados (.active, .collapsed), componentes JS dinâmicos (.council-member-row) e atalhos utilitários (.f1, .sc).

/* Bom: seletores semânticos */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* Evite: seletores pesados em classes */
.message-container .message--user .message__actions .btn { ... }

Tamanho de fonte mínimo de 14px. Todo texto deve ter pelo menos 14px. Isso garante legibilidade para LLMs de visão que interagem com a UI.

Alvos de clique amigáveis a VLM. Elementos interativos devem ter pelo menos 48px de altura. Switches de toggle são 44x24px. Isso permite modelos de visão de IA clicar em elementos por coordenada.

AIS.lazy() para novos módulos. Todos os módulos não-core devem usar o padrão de hidratação preguiçosa. A função de fábrica roda apenas no primeiro acesso:

if (!AIS.MyModule)
  AIS.lazy("MyModule", function () {
    "use strict";
    // código do módulo
    return { publicMethod };
  });

Delegação de eventos. Anexe um único listener em um elemento container, não listeners individuais em cada filho:

// Bom: listener único com delegação
container.addEventListener("click", (e) => {
  const btn = e.target.closest("[data-action]");
  if (btn) handleAction(btn.dataset.action);
});

// Evite: listeners por item
items.forEach((item) => item.addEventListener("click", handler));

Zero polling. Sem setInterval, sem loops requestAnimationFrame para trabalho não-animação. Use updates orientados a eventos e a API Page Visibility.

Listeners passivos. Todos os handlers de eventos não-canceláveis usam { passive: true }:

window.addEventListener("resize", onResize, { passive: true });

Testes de Worker

Código de worker tem sua própria suíte de testes:

cd worker
npm install
npm test

Ferramentas Python

Python é usado apenas para validação e scripts de build -- nunca enviado ao navegador:

# Validar registro de modelos
python3 registry/validate.py

# Validar registro de pacotes
python3 registry/validate.py packages

# Validar um arquivo de manifest
python3 registry/validate.py manifest caminho/para/manifest.json

# Validar um arquivo de locale
python3 registry/locale/validate_locale.py registry/locale/es.json

Processo de Pull Request

1. Faça fork do repositório
2. Crie uma branch para sua mudança (ex: add-model-deepseek-v3, translate-hindi, fix-streaming-bug)
3. Faça suas mudanças seguindo as convenções acima
4. Execute validação e testes:

# Para mudanças de registro
python3 registry/validate.py

# Para mudanças de código
./build.sh
npm test
./build.sh --check

# Para mudanças de locale
python3 registry/locale/validate_locale.py registry/locale/{lang}.json

5. Envie um PR para a branch main com uma descrição clara do que mudou e por quê

informação

Mudanças apenas de registro (modelos, pacotes, traduções) não requerem build ou execução da suíte completa de testes. Apenas execute o script de validação relevante.

Obtendo Ajuda

• Abra uma issue no GitHub para bugs ou solicitações de funcionalidades
• Verifique a documentação existente em doc.aiscouncil.net
• Revise CLAUDE.md na raiz do repo para a referência arquitetural completa