Zum Hauptinhalt springen

Mitwirken

AISCouncil freut sich über Beiträge in mehreren Bereichen: der Modell-Registry, Übersetzungen, Dokumentation, Mini-Programmen und Kern-Code. Dieser Guide behandelt jeden Beitragspfad.

Bereiche für Beiträge​

BereichSchwierigkeitDateienValidierung
Modell-RegistryEinfachregistry/models.jsonpython3 registry/validate.py
ÜbersetzungenEinfachregistry/locale/{lang}.jsonpython3 registry/locale/validate_locale.py
DokumentationEinfachdoc.aiscouncil.net/site/docs/Lokale Vorschau mit npm start
Mini-ProgrammeMittelmanifest.json + index.htmlpython3 registry/validate.py packages
Bugfixes / FeaturesMittel-Schwersrc/*.js, modules/*/index.ts./build.sh && npm test

Modell-Registry​

Die Modell-Registry (registry/models.json) ist eine community-gepflegte Liste von LLM-Anbietern und Modellen. Ein neues Modell hinzuzufügen ist der einfachste Weg, beizutragen.

Ein Modell hinzufügen​

  1. Forken Sie das Repository
  2. Bearbeiten Sie registry/models.json – fügen Sie Ihr Modell unter dem entsprechenden Anbieter hinzu
  3. Validieren Sie:
python3 registry/validate.py
  1. Reichen Sie einen Pull Request ein

Modell-Eintrag-Format​

Jedes Modell erfordert diese Felder:

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

Das Validierungsskript prüft:

  • Gültige JSON-Struktur
  • Alle erforderlichen Felder vorhanden (id, name, provider, context, maxOutput, pricing, capabilities, tier)
  • Keine doppelten Modell-IDs
  • Capabilities aus der erlaubten Menge: vision, tools, streaming, json_mode, reasoning, code
  • Tier aus der erlaubten Menge: free, paid, enterprise
Tipp

Prüfen Sie die existierenden Einträge in models.json für Beispiele. Passen Sie den Formatierungsstil an (2-Space-Einrückung, Felder in derselben Reihenfolge) für saubere Diffs.

Übersetzungen​

Die App verwendet community-beigesteuerte Locale-Dateien für Internationalisierung. Jede Locale-Datei übersetzt die Wizard- und UI-Strings.

Eine Übersetzung hinzufügen oder aktualisieren​

  1. Kopieren Sie registry/locale/en.json zu registry/locale/{lang}.json (verwenden Sie ISO 639-1-Codes: es, zh, ar, fr, etc.)
  2. Übersetzen Sie alle String-Werte (die rechte Seite jedes Schlüssel-Wert-Paars)
  3. Aktualisieren Sie _meta.lang und _meta.name
  4. Validieren Sie:
python3 registry/locale/validate_locale.py registry/locale/{lang}.json
  1. Reichen Sie einen Pull Request ein

Übersetzungsregeln​

  • Übersetzen: Alle String-Werte und _meta.name
  • Nicht ändern: Schlüsselnamen, _meta.lang-Code, _meta.version, Template-Variablen in {geschweiften Klammern}

Template-Variablen wie {name}, {count} und {error} werden zur Laufzeit ersetzt. Behalten Sie sie genau so, wie sie in der englischen Quelle erscheinen.

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

Siehe registry/locale/TRANSLATING.md für den vollständigen Übersetzungs-Guide, einschließlich Zeichenkodierungsregeln und Prioritäts-Sprachen.

Aktuell benötigte Sprachen​

Vollständige Übersetzungen existieren für Englisch, Spanisch, Chinesisch, Arabisch, Französisch, Portugiesisch, Japanisch, Koreanisch, Deutsch und Russisch. Übersetzungen werden noch benötigt für: Hindi, Türkisch, Ukrainisch, Thai, Polnisch, Italienisch, Niederländisch, Indonesisch und Vietnamesisch.

Dokumentation​

Die Dokumentation lebt in der Docusaurus-Site unter doc.aiscouncil.net/site/docs/.

Docs bearbeiten​

  1. Bearbeiten oder erstellen Sie Markdown-Dateien in doc.aiscouncil.net/site/docs/
  2. Vorschau lokal:
cd doc.aiscouncil.net/site
npm install
npm start
  1. Wenn Sie eine neue Seite hinzufügen, registrieren Sie sie in doc.aiscouncil.net/site/sidebars.ts
  2. Reichen Sie einen Pull Request ein

Doc-Konventionen​

  • Verwenden Sie Frontmatter mit sidebar_position, title und description
  • Verwenden Sie :::tip, :::info, :::warning Admonitions für Callouts
  • Verwenden Sie Tabellen für strukturierte Vergleiche
  • Fügen Sie Befehlsbeispiele ein, wo anwendbar
  • Halten Sie den Text direkt und prägnant

Mini-Programme​

Mini-Programme sind gesandboxte Web-Apps, die über iframes innerhalb der AISCouncil-Plattform laufen.

Ein Mini-Programm erstellen​

  1. Erstellen Sie ein manifest.json:
{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Meine App",
  "description": "Was meine App macht",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/my-app/",
  "permissions": ["storage"]
}
  1. Erstellen Sie index.html mit dem window.ais SDK:
<!DOCTYPE html>
<html>
  <body>
    <h1>Meine App</h1>
    <script>
      ais.ready(() => {
        ais.ui.toast("Hallo von meiner App!");
      });
    </script>
  </body>
</html>

  1. Hosten Sie Ihre Dateien auf einem beliebigen CDN (GitHub Pages, Cloudflare Pages, Vercel)

  2. Testen Sie lokal durch Installation über Manifest-URL:

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

In der Registry veröffentlichen​

  1. Fügen Sie Ihren App-Eintrag zu registry/packages.json hinzu
  2. Validieren Sie:
python3 registry/validate.py packages
  1. Reichen Sie einen Pull Request ein

Siehe die SDK-Dokumentation und sdk/ais.d.ts für die vollständige Mini-Programm-API.

Tipp

Das examples/hello-world/-Verzeichnis enthält ein vollständiges funktionierendes Mini-Programm, das Sie als Ausgangspunkt verwenden können.

Code-Beiträge​

Entwicklungs-Setup​

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

Edit-Build-Test-Zyklus​

  1. Quelldateien bearbeiten in src/ (index.html niemals direkt bearbeiten)
  2. Builden: ./build.sh
  3. Testen: npm test
  4. Verifizieren: ./build.sh --check

Für TypeScript-Module:

  1. Bearbeiten: modules/{name}/index.ts
  2. Type-Check: npm run check
  3. Builden: ./build.sh (kompiliert TypeScript automatisch)
  4. Testen: npm run test:modules

Code-Stil​

Die Codebasis folgt strengen Konventionen. Überprüfen Sie diese vor dem Einreichen von Code:

Keine externen Abhängigkeiten. Das Browser-Bundle enthält nur Vanilla JS und optionales WASM. Kein React, kein jQuery, kein lodash, keine npm-Pakete zur Laufzeit.

Semantisches HTML. Verwenden Sie <dialog> für Modals, <details> für Ausklappbares, <output> für Live-Regionen, hidden-Attribut für Sichtbarkeit. Greifen Sie nach einem nativen HTML-Element, bevor Sie JS schreiben.

Klassenloses CSS. Zielen Sie auf Elemente per ID, semantischem Tag oder data-*-Attribut. Verwenden Sie Klassen nur für: State-Toggles (.active, .collapsed), dynamische JS-Komponenten (.council-member-row) und Utility-Shorthands (.f1, .sc).

/* Gut: semantische Selektoren */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* Vermeiden: klassenlastige Selektoren */
.message-container .message--user .message__actions .btn { ... }

14px minimale Schriftgröße. Der gesamte Text muss mindestens 14px sein. Dies stellt die Lesbarkeit für Vision-LLMs sicher, die mit der UI interagieren.

VLM-freundliche Click-Targets. Interaktive Elemente müssen mindestens 48px hoch sein. Toggle-Schalter sind 44x24px. Dies ermöglicht KI-Vision-Modellen, Elemente per Koordinate zu klicken.

AIS.lazy() für neue Module. Alle Nicht-Core-Module müssen das Lazy-Hydration-Muster verwenden. Die Factory-Funktion läuft nur beim ersten Zugriff:

if (!AIS.MyModule)
  AIS.lazy("MyModule", function () {
    "use strict";
    // Modul-Code
    return { publicMethod };
  });

Event-Delegation. Hängen Sie einen einzelnen Listener an ein Container-Element an, keine einzelnen Listener an jedem Kind:

// Gut: einzelner Listener mit Delegation
container.addEventListener("click", (e) => {
  const btn = e.target.closest("[data-action]");
  if (btn) handleAction(btn.dataset.action);
});

// Vermeiden: Per-Item-Listener
items.forEach((item) => item.addEventListener("click", handler));

Kein Polling. Kein setInterval, keine requestAnimationFrame-Loops für Nicht-Animations-Arbeit. Verwenden Sie Event-gesteuerte Updates und die Page Visibility API.

Passive Listener. Alle nicht-abbrechbaren Event-Handler verwenden { passive: true }:

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

Worker-Tests​

Worker-Code hat seine eigene Test-Suite:

cd worker
npm install
npm test

Python-Tooling​

Python wird nur für Validierungs- und Build-Skripte verwendet – niemals an den Browser ausgeliefert:

# Modell-Registry validieren
python3 registry/validate.py

# Paket-Registry validieren
python3 registry/validate.py packages

# Eine Manifest-Datei validieren
python3 registry/validate.py manifest path/to/manifest.json

# Eine Locale-Datei validieren
python3 registry/locale/validate_locale.py registry/locale/es.json

Pull-Request-Prozess​

  1. Forken Sie das Repository
  2. Erstellen Sie einen Branch für Ihre Änderung (z.B. add-model-deepseek-v3, translate-hindi, fix-streaming-bug)
  3. Machen Sie Ihre Änderungen nach den oben genannten Konventionen
  4. Führen Sie Validierung und Tests aus:
# Für Registry-Änderungen
python3 registry/validate.py

# Für Code-Änderungen
./build.sh
npm test
./build.sh --check

# Für Locale-Änderungen
python3 registry/locale/validate_locale.py registry/locale/{lang}.json
  1. Reichen Sie einen PR in den main-Branch ein mit einer klaren Beschreibung, was sich geändert hat und warum
Info

Nur-Registry-Änderungen (Modelle, Pakete, Übersetzungen) erfordern kein Builden oder Ausführen der vollständigen Test-Suite. Führen Sie einfach das relevante Validierungsskript aus.

Hilfe bekommen​

  • Eröffnen Sie ein GitHub-Issue für Bugs oder Feature-Requests
  • Prüfen Sie die existierenden Docs unter doc.aiscouncil.net
  • Überprüfen Sie CLAUDE.md im Repo-Root für die vollständige architektonische Referenz