Contribuer

AISCouncil accueille les contributions dans plusieurs domaines : le registre de modèles, les traductions, la documentation, les mini-programmes et le code core. Ce guide couvre chaque voie de contribution.

Domaines de Contribution

Domaine	Difficulté	Fichiers	Validation
Registre de Modèles	Facile	registry/models.json	python3 registry/validate.py
Traductions	Facile	registry/locale/{lang}.json	python3 registry/locale/validate_locale.py
Documentation	Facile	doc.aiscouncil.net/site/docs/	Prévisualisation locale avec npm start
Mini-Programmes	Moyen	manifest.json + index.html	python3 registry/validate.py packages
Corrections de Bugs / Fonctionnalités	Moyen-Difficile	src/*.js, modules/*/index.ts	./build.sh && npm test

Registre de Modèles

Le registre de modèles (registry/models.json) est une liste de fournisseurs et modèles LLM maintenue par la communauté. Ajouter un nouveau modèle est le moyen le plus facile de contribuer.

Ajouter un Modèle

1. Forkez le référentiel
2. Éditez registry/models.json — ajoutez votre modèle sous le fournisseur approprié
3. Validez :

python3 registry/validate.py

4. Soumettez une pull request

Format d'Entrée de Modèle

Chaque modèle nécessite ces champs :

{
  "id": "model-id-from-provider",
  "name": "Human-Readable Name",
  "provider": "provider-id",
  "context": 128000,
  "maxOutput": 8192,
  "pricing": { "input": 3.0, "output": 15.0 },
  "capabilities": ["streaming", "vision", "tools"],
  "tier": "paid"
}

Le script de validation vérifie :

• Une structure JSON valide
• Tous les champs requis présents (id, name, provider, context, maxOutput, pricing, capabilities, tier)
• Pas d'IDs de modèle en double
• Capacités dans l'ensemble autorisé : vision, tools, streaming, json_mode, reasoning, code
• Niveau dans l'ensemble autorisé : free, paid, enterprise

astuce

Consultez les entrées existantes dans models.json pour des exemples. Correspondance au style de formatage (indentation 2 espaces, champs dans le même ordre) pour des diffs propres.

Traductions

L'application utilise des fichiers de locale contribués par la communauté pour l'internationalisation. Chaque fichier de locale traduit l'assistant et les chaînes UI.

Ajouter ou Mettre à Jour une Traduction

1. Copiez registry/locale/en.json vers registry/locale/{lang}.json (utilisez les codes ISO 639-1 : es, zh, ar, fr, etc.)
2. Traduisez toutes les valeurs de chaîne (le côté droit de chaque paire clé-valeur)
3. Mettez à jour _meta.lang et _meta.name
4. Validez :

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

5. Soumettez une pull request

Règles de Traduction

• À traduire : Toutes les valeurs de chaîne et _meta.name
• À ne pas changer : Les noms de clés, le code _meta.lang, _meta.version, les variables de template à l'intérieur des {accolades}

Les variables de template comme {name}, {count} et {error} sont remplacées au runtime. Gardez-les exactement comme elles apparaissent dans la source anglaise.

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

info

Voir registry/locale/TRANSLATING.md pour le guide de traduction complet, incluant les règles d'encodage de caractères et les langues prioritaires.

Langues Actuellement Nécessaires

Des traductions complètes existent pour l'anglais, l'espagnol, le chinois, l'arabe, le français, le portugais, le japonais, le coréen, l'allemand et le russe. Des traductions sont encore nécessaires pour : l'hindi, le turc, l'ukrainien, le thaï, le polonais, l'italien, le néerlandais, l'indonésien et le vietnamien.

Documentation

La documentation vit dans le site Docusaurus à doc.aiscouncil.net/site/docs/.

Éditer les Docs

1. Éditez ou créez des fichiers Markdown dans doc.aiscouncil.net/site/docs/
2. Prévisualisez localement :

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

3. Si vous ajoutez une nouvelle page, enregistrez-la dans doc.aiscouncil.net/site/sidebars.ts
4. Soumettez une pull request

Conventions de Doc

• Utilisez du frontmatter avec sidebar_position, title et description
• Utilisez les admonitions :::tip, :::info, :::warning pour les encadrés
• Utilisez des tableaux pour les comparaisons structurées
• Incluez des exemples de commandes le cas échéant
• Gardez la prose directe et concise

Mini-Programmes

Les mini-programmes sont des applications web sandboxées qui s'exécutent à l'intérieur de la plateforme AISCouncil via des iframes.

Créer un Mini-Programme

1. Créez un manifest.json :

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Mon App",
  "description": "Ce que fait mon app",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/my-app/",
  "permissions": ["storage"]
}

2. Créez index.html en utilisant le SDK window.ais :

<!DOCTYPE html>
<html>
  <body>
    <h1>Mon App</h1>
    <script>
      ais.ready(() => {
        ais.ui.toast("Bonjour depuis mon app !");
      });
    </script>
  </body>
</html>

3. Hébergez vos fichiers sur n'importe quel CDN (GitHub Pages, Cloudflare Pages, Vercel)

4. Testez localement en installant via l'URL du manifeste :

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

Publier sur le Registre

1. Ajoutez l'entrée de votre application à registry/packages.json
2. Validez :

python3 registry/validate.py packages

3. Soumettez une pull request

Voir la documentation SDK et sdk/ais.d.ts pour l'API complète des mini-programmes.

astuce

Le répertoire examples/hello-world/ contient un mini-programme complet fonctionnel que vous pouvez utiliser comme point de départ.

Contributions de Code

Configuration de Développement

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

Cycle Éditer-Construire-Tester

1. Éditez les fichiers sources dans src/ (n'éditez jamais index.html directement)
2. Construisez : ./build.sh
3. Testez : npm test
4. Vérifiez : ./build.sh --check

Pour les modules TypeScript :

1. Éditez : modules/{name}/index.ts
2. Vérifiez les types : npm run check
3. Construisez : ./build.sh (compile automatiquement TypeScript)
4. Testez : npm run test:modules

Style de Code

La base de code suit des conventions strictes. Revoyez celles-ci avant de soumettre du code :

Pas de dépendances externes. Le bundle navigateur contient uniquement du JS vanilla et du WASM optionnel. Pas de React, pas de jQuery, pas de lodash, pas de packages npm au runtime.

HTML sémantique. Utilisez <dialog> pour les modales, <details> pour les repliables, <output> pour les régions live, attribut hidden pour la visibilité. Cherchez un élément HTML natif avant d'écrire du JS.

CSS sans classes. Ciblez les éléments par ID, balise sémantique ou attribut data-*. Utilisez des classes uniquement pour : bascules d'état (.active, .collapsed), composants JS dynamiques (.council-member-row) et raccourcis utilitaires (.f1, .sc).

/* Bon : sélecteurs sémantiques */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* À éviter : sélecteurs lourds en classes */
.message-container .message--user .message__actions .btn { ... }

Taille de police minimum 14px. Tout le texte doit faire au moins 14px. Cela assure la lisibilité pour les LLMs de vision qui interagissent avec l'UI.

Cibles de clic adaptées aux VLMs. Les éléments interactifs doivent faire au moins 48px de hauteur. Les interrupteurs sont 44x24px. Cela permet aux modèles de vision IA de cliquer sur les éléments par coordonnées.

AIS.lazy() pour les nouveaux modules. Tous les modules non-core doivent utiliser le pattern d'hydratation différée. La fonction factory ne s'exécute qu'au premier accès :

if (!AIS.MyModule)
  AIS.lazy("MyModule", function () {
    "use strict";
    // code du module
    return { publicMethod };
  });

Délégation d'événements. Attachez un seul listener sur un élément conteneur, pas des listeners individuels sur chaque enfant :

// Bon : listener unique avec délégation
container.addEventListener("click", (e) => {
  const btn = e.target.closest("[data-action]");
  if (btn) handleAction(btn.dataset.action);
});

// À éviter : listeners par élément
items.forEach((item) => item.addEventListener("click", handler));

Zéro polling. Pas de setInterval, pas de boucles requestAnimationFrame pour le travail non-animé. Utilisez des mises à jour pilotées par événements et l'API Page Visibility.

Listeners passifs. Tous les gestionnaires d'événements non-annulables utilisent { passive: true } :

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

Tests Worker

Le code Worker a sa propre suite de tests :

cd worker
npm install
npm test

Outils Python

Python est utilisé pour la validation et les scripts de build uniquement — jamais livré au navigateur :

# Valider le registre de modèles
python3 registry/validate.py

# Valider le registre de packages
python3 registry/validate.py packages

# Valider un fichier manifeste
python3 registry/validate.py manifest path/to/manifest.json

# Valider un fichier de locale
python3 registry/locale/validate_locale.py registry/locale/es.json

Processus de Pull Request

1. Forkez le référentiel
2. Créez une branche pour votre changement (ex., add-model-deepseek-v3, translate-hindi, fix-streaming-bug)
3. Faites vos changements en suivant les conventions ci-dessus
4. Exécutez la validation et les tests :

# Pour les changements de registre
python3 registry/validate.py

# Pour les changements de code
./build.sh
npm test
./build.sh --check

# Pour les changements de locale
python3 registry/locale/validate_locale.py registry/locale/{lang}.json

5. Soumettez une PR vers la branche main avec une description claire de ce qui a changé et pourquoi

info

Les changements de registre uniquement (modèles, packages, traductions) ne nécessitent pas de construction ou d'exécution de la suite de tests complète. Exécutez simplement le script de validation pertinent.

Obtenir de l'Aide

• Ouvrez une issue GitHub pour les bugs ou demandes de fonctionnalités
• Consultez la documentation existante sur doc.aiscouncil.net
• Revoyez CLAUDE.md à la racine du repo pour la référence architecturale complète