Mitwirken

Diese Seite ist für Menschen, die OpenBot selbst ändern. Sie zeigt dir, wie du deinen Computer einrichtest, den Server und die Prüfungen startest und dich im Code zurechtfindest.

Einrichten

Du brauchst devenv. devenv gibt dir genau die Werkzeuge für das Projekt: Node.js, pnpm, PostgreSQL, mkcert und mehr. Docker brauchst du nur, um die Images zu bauen und zu prüfen. Siehe Betrieb. Führe jeden Befehl über devenv shell -- <command> aus. So nutzt du immer diese Werkzeuge.

Den Code holen

git clone <repository-url> openbot
cd openbot

Lokale Einstellungen erstellen

devenv shell -- pnpm dev:setup
devenv shell -- mkcert -install

dev:setup erstellt .env.development mit einem neuen, zufälligen geheimen Schlüssel in OPENBOT_SECRET_KEYS. Es erstellt auch ein lokales TLS-Zertifikat in .devenv/dev/. Wenn deine .env.development aus einer älteren Version stammt, lösche sie und führe dev:setup noch einmal aus. Du kannst auch die Entwicklungs-Datenbank zurücksetzen. Siehe Konfiguration. mkcert -install sorgt dafür, dass dein Computer diesem Zertifikat vertraut.

Den Entwicklungsserver starten

devenv shell -- pnpm dev

pnpm dev führt devenv up aus. Das macht diese Schritte:

Es startet PostgreSQL 18 auf 127.0.0.1:5433, mit dem Benutzer openbot_dev. devenv startet es als normalen Prozess. Seine Daten liegen in .devenv/state/postgres.
Es installiert die Pakete mit pnpm install --frozen-lockfile.
Es baut OpenBot und die Pakete, die OpenBot braucht.
Es führt die Datenbank-Migrationen aus.
Es startet den Entwicklungsserver unter https://localhost:8443. Der Server schreibt die Plattform-Einstellungen für diesen Origin selbst. Darum gibt es keinen Einrichtungsschritt.

Wenn du eine Datei in packages/*/src änderst, startet devenv OpenBot neu.

Der Entwicklungsserver nutzt ein lokales Testkonto, Test-Models und eine Test-App. Kein externer Dienst ist nötig. Wie du dich anmeldest und ein User Token erstellst, steht unter Schnellstart.

Prüfungen

Befehl	Was er tut
`devenv shell -- pnpm install`	Installiert alle Pakete.
`devenv shell -- pnpm build`	Baut jedes Paket mit tsdown.
`devenv shell -- pnpm typecheck`	Prüft die Typen jedes Pakets.
`devenv shell -- pnpm -r test`	Führt die Tests jedes Pakets aus.
`devenv shell -- pnpm --filter @openbot-build/core test`	Führt die Tests eines Pakets aus.
`devenv shell -- treefmt`	Formatiert den Code mit Prettier und nixfmt.

Führe pnpm build vor pnpm typecheck aus. Pakete importieren einander aus ihren gebauten Dateien.

Tests nutzen den eingebauten Test-Runner von Node.js. Tests von OpenBot starten ihren eigenen kurzlebigen PostgreSQL-Server mit den Werkzeugen aus devenv. Sie brauchen keine Geheimnisse und keine externen Dienste. GitHub Actions führt dieselben Befehle build, typecheck und test aus. Siehe Betrieb.

Aufbau des Repositorys

Pfad	Was er enthält
`packages/`	Die Pakete des Workspaces. Siehe Pakete.
`packages/docs/`	Diese Doku-Seite.
`packages/template/`	Ein Startpunkt für ein neues Paket. Er gehört nicht zum Workspace.
`protocol-test/`	Der öffentliche Testdienst für das App Protocol. Siehe Protokolltest.
`deploy/`	Dateien, um OpenBot in Betrieb zu nehmen. Jedes Ziel hat einen eigenen Ordner. Siehe Betrieb.
`deploy/docker/`	Das Dockerfile, die Bake-Datei, Compose-Dateien, die Vorlage für die Produktivumgebung und die Image-Prüfungen.
`.env.development.example`	Die Vorlage für `.env.development`.
`patches/`	Korrekturen für genaue Versionen externer Pakete.
`references/`	Quellcode anderer Open-Source-Projekte, als Git-Submodule. Nur zum Lesen.
`devenv.nix`	Die Entwicklungswerkzeuge, Einstellungen und Prozesse.

Der Ordner references/ gehört nicht zum Build. Um diesen Code zu lesen, hole ihn mit git submodule update --init.

Für ein neues Paket kopierst du packages/template/ nach packages/<name>/. Ändere dann seinen Namen, seinen Einstiegspunkt und seine Abhängigkeiten.

Die Doku-Seite

Die Doku-Seite ist eine Astro-Seite, gebaut mit Starlight. Der Build erzeugt nur statische Dateien. Starte sie mit:

devenv shell -- pnpm --filter @openbot-build/docs dev

Öffne dann http://localhost:4321.

Pfad in `packages/docs/`	Was es ist
`content/docs/*.mdx`	Die Seiten. Der Dateiname ist die URL: `deploy.mdx` ist `/docs/deploy`.
`content/docs/<locale>/`	Die Übersetzungen: `zh-cn` für vereinfachtes Chinesisch und `de` für Deutsch.
`astro.config.ts`	Die Einstellungen der Seite und die Reihenfolge der Seiten in der Seitenleiste.
`src/components/`	Die Komponenten, die Seiten ohne Import nutzen können: `Callout`, `Steps` und mehr.
`src/landing/`	Die Startseite. `messages/` enthält ihren Text, mit einer Datei für jede Sprache.
`src/i18n.ts`	Die Sprachen der Doku und der Startseite.
`src/pages/openapi.json.ts`	Liefert `openapi.json` unter `/openapi.json` aus, damit man es herunterladen kann.
`scripts/api.ts`	Erzeugt `openapi.json` aus dem API-Vertrag.

Die API-Referenz unter /docs/api entsteht aus openapi.json, mit dem Plugin starlight-openapi. Schreibe sie nicht von Hand. Das Skript läuft vor jedem dev und build. Wenn du den API-Vertrag in @openbot-build/api änderst, ändert sich auch die Referenz. Wenn du dem Vertrag eine Gruppe hinzufügst, gib ihr in scripts/api.ts einen Titel und eine Beschreibung. Bis du das tust, bricht das Skript mit einem Fehler ab. Der Build erzeugt auch /llms.txt und /llms-full.txt. Sie enthalten die Doku als reinen Text für KI-Werkzeuge. Um zu prüfen, dass jede Seite gebaut wird, führe devenv shell -- pnpm --filter @openbot-build/docs build aus.

Jeder Push auf main veröffentlicht die Seite auf openbot.build. Siehe Die Doku-Seite veröffentlichen.

Projektregeln

Simple English

Schreibe allen Text in Simple English (einfachem Englisch). Das gilt für Doku, Code-Kommentare, Fehlermeldungen, Logs, Prompts und Test-Texte. Nutze kurze Sätze und gängige Wörter. Erkläre jeden Fachbegriff, wenn du ihn zum ersten Mal nutzt.

Englisch ist die Quelle für allen Text. Die Doku gibt es auch auf vereinfachtem Chinesisch und auf Deutsch. Die Startseite gibt es in noch viel mehr Sprachen. Wenn du eine englische Seite änderst, ändere ihre Übersetzungen in derselben Änderung. Eine Übersetzung behält dieselben Überschriften in derselben Reihenfolge. Ihre Links führen zu Seiten in ihrer eigenen Sprache, zum Beispiel /de/docs/deploy. Wenn du Text auf der Startseite änderst, ändere ihn in jeder Datei in src/landing/messages/. Die API-Referenz gibt es nur auf Englisch.

Headless

OpenBot hat keine Benutzeroberfläche. Füge dem Repository keine Seiten, Frontends oder Client-Apps hinzu. Die Doku-Seite ist die einzige Ausnahme. Jede neue Funktion beginnt als Operation im Vertrag @openbot-build/api. Danach behandelt der Server sie. Jede Operation muss mit einem User Token und mit dem Anmelde-Cookie funktionieren. Sie muss auch sagen, welche Berechtigung sie braucht, mit einer Annotation Required oder GroupRequired. Siehe Berechtigungen.

Ein aktuelles Modell

Behalte keine alten Wege für alte Aufrufer, alte Clients oder alte Daten. Wenn sich ein Vertrag oder der Speicher ändern muss, ändere ihn direkt. Die einzige Ausnahme ist eine kleine Korrektur für einen Fehler in einem externen Paket oder Werkzeug.

Zuerst Effect-Daten

Nutze die unveränderlichen Datentypen von Effect, zum Beispiel HashMap, Chunk und Option. Nutze die veränderlichen Typen von JavaScript nur, wenn du sie wirklich brauchst.

Kleine, echte Änderungen

Baue, was echten Nutzen bringt. Halte jede Änderung fokussiert und teste die Teile, die wirklich kaputtgehen können.

Die vollständigen Regeln für Mitwirkende stehen in AGENTS.md im Hauptordner des Repositorys.

Lizenz

OpenBot nutzt die GNU Affero General Public License, nur Version 3 (AGPL-3.0-only). Der vollständige Text steht in der Datei LICENSE im Hauptordner des Repositorys. Wenn du eine Änderung einreichst, stimmst du zu, dass sie dieselbe Lizenz nutzt.