Zum Artikel springen
HB CodeDocs
App herunterladen

HandbuchMitwirken

Bauen, testen und beitragen

Dieses Kapitel zeigt, wie Sie aus einem Quellcode-Checkout bauen, eine Änderung vornehmen und die Prüfungen für jede Grenze ausführen.

Gegen den Quellcode geprüft am 5. Oktober 2026

Auf dieser Seite

Starten Sie nur die Komponenten, die Ihre Änderung braucht

Verwenden Sie einen Quell-Checkout mit seinen Lockfiles und lesen Sie AGENTS.md für den aktuellen Repository-Vertrag. Der Paketmanager im Stammverzeichnis ist pnpm 10.34.5, und die package.json im Stammverzeichnis pinnt verwundbare transitive Versionen über pnpm-Overrides und gepatchte Abhängigkeiten, weshalb --frozen-lockfile nach einer Abhängigkeitsänderung scheitert, bis das Lockfile neu erzeugt ist. Installieren Sie eine kompatible Node-Laufzeit, stabiles Rust für native Arbeit und die nativen Compiler-Tools der Zielplattform. iOS-Arbeit erfordert macOS und Xcode. Kein Stammbefehl startet alle Komponenten zusammen. Starten Sie nur die Oberflächen, die Ihre Änderung braucht.

JavaScript-Abhängigkeiten aus dem Repository-Root installieren
pnpm install --frozen-lockfile
AufgabeStartbefehl oder Projekt und was es beweist
Websitepnpm dev:website. Dokumentations- und Marketing-UI in einem Browser.
Desktop-Frontendpnpm -C desktop dev. React-Layout und Frontend-Verhalten. Native Aufrufe erfordern eine Tauri-Laufzeitumgebung.
Nativer Desktoppnpm -C desktop tauri:dev. Die eigentliche WebView, Rust-Befehle, Sidecar und lokale Dateien.
Claude-Agent-Hostpnpm -C desktop/agent-host build. Der TypeScript-Host wird nach desktop/agent-host/dist kompiliert. tauri dev führt diesen Build aus, bevor das Frontend startet.
Serverpnpm dev:server nach lokalem Setup. Konfiguriertes HTTP- und Relay-Dienstverhalten.
iOSmobile/ios/HBCode.xcodeproj, HBCode-Scheme. Native Companion-UI und, mit einem konfigurierten Desktop, Fernsteuerung.
Androidmobile/android in Android Studio. Die Compose-Begleit-App und, mit einem konfigurierten Desktop, Fernsteuerung.

Der Claude-Agent-Host ist das pnpm-Workspace-Paket @hbcode/claude-host in desktop/agent-host. Es legt das Claude Agent SDK auf 0.3.283 fest. Ein Debug-Build des Desktops startet node aus dem PATH mit desktop/agent-host/dist/src/entry.js und nimmt die claude-Binärdatei aus dem Plattformpaket des SDK in node_modules. Ohne das installierte Paket schlägt die Claude-Laufzeit mit „Install the Claude host dependencies before running desktop“ fehl. Ein Release-Build führt zuerst pnpm -C agent-host package-runtime aus und liest node, host/entry.mjs und claude aus dem Ordner claude der App-Ressourcen. Fehlt das Host-Skript oder die claude-Binärdatei, lautet der Fehler „The Claude runtime is not packaged“.

Der mitgelieferte Sidecar

tauri:dev baut zuerst den Codex-Kindprozess aus der mitgelieferten Quelle. Dieser Abschnitt erklärt die Schritte und den Prüfbefehl.

Der Claude-Agent-Host

Der Host-Prozess, sein Protokoll mit dem Desktop und die Run-Schleife.

Wo der Desktop-Code liegt

Die gemeinsame Chat-Schicht erreicht einen Agenten nur über agents/dispatch, und die zwei Adapter importieren einander nie
Die gemeinsame Chat-Schicht erreicht einen Agenten nur über agents/dispatch, und die zwei Adapter importieren einander nieEine Karte von desktop/src-tauri/src, einem einzigen Rust-Crate. Die Tauri-Befehle und die RPC-Handler für die Telefone rufen die Chat-Schicht auf. Die Chat-Schicht ruft agents/dispatch auf, und Dispatch ruft den Codex-Adapter oder den Claude-Adapter auf. Jeder Adapter importiert die Verträge der Chat-Schicht und den gemeinsamen Tool-Katalog in services/agent_tools. Zwischen den zwei Adaptern gibt es keinen Import. Unter dem Crate trennt eine Prozessgrenze zwei Kindprogramme ab: den Codex-app-server und den Claude-Agent-Host, ein eigenes Node-Paket in desktop/agent-host.
desktop/src-tauri/src · ein Rust-Crate
commands/Tauri-Befehle für das Desktop-Fenster
remote_api/RPC von den Telefonen
chat/Agentenneutral: Sessions, Outbox, Runs, Timeline-Zeilen, Freigaben, Verträge
agents/dispatchwählt den Adapter für eine Session
agents/codexCodex-Adapter
agents/claudeClaude-Adapter
importiert die Chat-Verträge
importiert die Chat-Verträge
kein Import in beide Richtungen
services/agent_toolsein Tool-Katalog für beide Agenten
Prozessgrenze
codex-app-serverSidecar-Binärdatei, als Kindprozess gestartet
desktop/agent-hostNode-Paket, als Kindprozess gestartet
stdin und stdout
stdin und stdout
  • Gemeinsame Chat-Schichtdesktop/src-tauri/src/chat

    Elf Ordner: approvals, contracts, entrypoints, operation_ledger, outbox, presentation, runs, send, session_messages, sessions und timeline. Ihr einziger Import aus agents ist agents::dispatch.

  • Dispatchdesktop/src-tauri/src/agents/dispatch

    Sechs Module: approvals, conversations, runs, selection, send und timeline. Jede Funktion liest den Agenten der Session und ruft den passenden Adapter auf.

  • Adapteragents/codex · agents/claude

    Jeder Adapter betreibt einen Agenten und bildet ihn auf die Chat-Verträge ab. Konto- und Nutzungsbefehle in commands und remote_api rufen einen Adapter direkt auf, weil sie zu einem Agenten gehören.

  • Tool-Katalogdesktop/src-tauri/src/services/agent_tools

    Beide Adapter rufen ihn auf, um die Tools aufzulisten und einen Tool-Aufruf auszuführen. Er führt den Erklärvideo-Worker auf dem Agenten der Session aus, mit dem Codex-app-server oder dem Claude-Agent-Host, und nutzt chat::session_messages für Nachrichten zwischen Sessions.

  • Claude-Agent-Hostdesktop/agent-host · @hbcode/claude-host

    TypeScript mit dem Claude Agent SDK 0.3.283. Er teilt keinen Code mit dem Crate. Der Claude-Adapter startet ihn als Kindprozess und spricht über stdin und stdout mit ihm.

Die Modulkommentare nennen die Regel. chat/mod.rs bezeichnet die Chat-Schicht als agentenneutral. agents/dispatch/mod.rs sagt, dass die Chat-Schicht agents::codex und agents::claude nur über dieses Modul erreicht. Die Importe halten sich daran: Jeder Verweis von chat auf agents geht an agents::dispatch, und kein Adapter importiert den anderen. Kein Skript in check:quality-boundaries erzwingt diese Regel, daher muss ein Reviewer sie prüfen.

Die ersten sechs Pfade der Tabelle liegen in desktop/src-tauri/src.

PfadWas er besitzt und was er importieren darf
chatSessions, die Outbox, Runs, das Live-Overlay, Timeline-Zeilen und ihre Darstellung, Freigaben, Session-Nachrichten und die Chat-Einstiegspunkte. Darf importieren: agents::dispatch. Nie einen Adapter.
agents/dispatchDie Wahl des Adapters für eine Session: Senden, Runs, Timeline, Freigaben, Unterhaltungen und Modellauswahl. Darf importieren: beide Adapter und chat.
agents/codexDen app-server-Kindprozess, Threads, Turns, Ziele, Verlauf, Codex-Auth-Profile und Nutzungslimits. Darf importieren: chat, services/agent_tools und agents::dispatch für den Session-Eintrag. Nie agents::claude.
agents/claudeDen Host-Prozess, Runs, die Verlaufsprojektion, Berechtigungen, Subagenten und Claude-Konten. Darf importieren: chat, services/agent_tools und agents::dispatch für den Session-Eintrag. Nie agents::codex.
services/agent_toolsDen Tool-Katalog und die Tool-Handler für beide Agenten. Darf importieren: chat, agents::dispatch für den Session-Datensatz und den Run sowie beide Adapter für die zwei Engines des Worker-Kerns.
remote_apiRPC-Handler für die Telefone. Darf importieren: chat und agents::dispatch. Die Handler für Codex-Profile und Nutzungslimits rufen agents::codex auf.
desktop/agent-hostDen Claude-Agent-Host in TypeScript mit eigenen Tests. Er importiert keinen Rust-Code. Das Protokoll steht in src/protocol.ts.
Wie sich Codex und Claude eine Chat-Schicht teilen

Was die Chat-Schicht teilt und was jeder Adapter hinzufügt.

Die nativen Begleit-Apps bauen

  1. iPhone: Öffnen Sie mobile/ios/HBCode.xcodeproj, wählen Sie das Schema HBCode, lösen Sie die lokalen Pakete Core, VibeUI und VibeUIFormatting auf und konfigurieren Sie die Auth0-Werte aus mobile/ios/README.md. Starten Sie auf einem iOS-18-Simulator oder einem Gerät mit Ihrem Signing-Team.
  2. Android: Öffnen Sie mobile/android in Android Studio, lassen Sie Gradle synchronisieren und konfigurieren Sie die Auth0- und Firebase-Werte aus mobile/android/README.md. Die App zielt auf Android 8.0 und neuer.
  3. Für einen Live-Steuerungstest auf einer der Plattformen verbinden Sie sich mit einem konfigurierten Desktop mit demselben Konto und derselben Region und lesen eine bekannte Datei, bevor Sie eine Mutation versuchen.
Lokale Ziele ermitteln und eines davon für Builds und Tests verwenden
xcodebuild -showdestinations \
  -project mobile/ios/HBCode.xcodeproj \
  -scheme "HB Code"

Das Schema „HB Code“ führt VibeUITests über den Testplan mobile/ios/HBCode.xctestplan aus. Der Plan setzt diagnosticCollectionPolicy auf Never, daher sammelt xcodebuild am Ende eines Testlaufs keine Simulator-Diagnosen und wartet nicht auf sie.

Simulatoren und Emulatoren decken Layout, Dekodierung und Zustandsübergänge ab. Sie beweisen nichts über physische Push-Zustellung, Store-Käufe oder die Anbieteranmeldung eines signierten Releases, testen Sie das also mit echten Diensten und einem echten Gerät, bevor Sie ein Release für fertig erklären.

Einer Operation durch den Code folgen

Beispiel: Die Outbox-Übermittlung vom Contract bis zum Speicher nachverfolgen
rg -n "chatOutboxSubmit" rpc-contract.v1.json desktop/src-tauri/src/remote_api server/src mobile/ios
rg -n "submit_outbox_request" desktop/src-tauri/src/chat/outbox
rg -n "save_workspace_chat_outbox_with_operation_identity" desktop/src-tauri/src
  1. Beschreiben Sie die Benutzeraktion, das erwartete Ergebnis und einen Fehlerfall vor der Bearbeitung.
  2. Finden Sie das Transport-DTO und den Domain-Service, der für die Operation zuständig ist. Lesen Sie beides, denn ein Adapter allein definiert kein Verhalten.
  3. Ändern Sie die kleinste zuständige Schicht. Bewahren Sie stabile Identitäten für Operationen, Sessions und Timelines.
  4. Ändern Sie einen gemeinsamen RPC, aktualisieren Sie Manifest, Desktop, Server, iOS und Android zusammen. Das Manifest pinnt, was sie teilen: Seitengrößen 12 und 100, 40 Zeilen für ein Fenster mit Anker, Timeouts von 15, 60, 115, 60 und 20 Sekunden, die Wiederholungsrichtlinie der ersten Timeline und die Mutationen, die einen Idempotenzschlüssel verlangen.
  5. Fügen Sie einen gezielten Regressionstest an der Fehlergrenze hinzu. Untersuchen Sie bei visuellem oder Lebenszyklus-Verhalten auch die laufende Oberfläche.
  6. Aktualisieren Sie das relevante technische Kapitel und seine Quellcode-Referenzen zusammen mit der Codeänderung.

Wählen Sie Prüfungen aus, die zur Änderung passen

Geänderte OberflächeRepository-Befehle
Desktop TypeScriptpnpm -C desktop typecheck, pnpm -C desktop lint, pnpm -C desktop test
Desktop Rustpnpm desktop:check, danach gezielte Rust-Tests für den geänderten Service.
Claude-Agent-Hostpnpm -C desktop/agent-host typecheck, pnpm -C desktop/agent-host test
Server Rustpnpm server:check, danach gezielte cargo-Tests und konfigurierte Service-Tests nach Bedarf.
Shared RPCpnpm check:rpc-contract, plus die betroffenen Client- und Server-Tests.
Codex storage boundarypnpm check:codex-storage-boundary
Websitepnpm -C website typecheck, pnpm -C website lint, pnpm -C website test, pnpm -C website build
Größe von Dateien, Funktionen und Ordnernpnpm check:max-lines, pnpm check:max-function-lines, pnpm check:max-folder-files
Ungenutzter Code im Desktoppnpm check:unused führt knip, cargo machete und clippy mit den Warnungen für toten Code und ungenutzte Elemente aus. Es gehört nicht zu check:all.
Grenz­über­greifendes Reviewpnpm check:quality-boundaries verkettet neun Prüfungen: die drei Größenprüfungen, die Tauri-Befehlsoberfläche, den RPC-Vertrag, die Parität der IntelliJ-Palette, den Skill-Korpus, die Codex-Speichergrenze und einen Duplikat-Scan des geänderten Codes mit mindestens 18 Zeilen.
Allespnpm check:all führt check:quality-boundaries, server:check, desktop:check, Lint und Formatprüfung des Desktops sowie den Typecheck jedes Workspace-Pakets aus.

Eine Typprüfung beweist Typkonsistenz. Sie beweist keine korrekte Zustellung, und ein Relay-Unit-Test beweist keine native Anmeldung. Nennen Sie, welche Prüfungen gelaufen sind, welche externe Dienste brauchen und was Sie im laufenden Produkt geprüft haben.

Machen Sie die Änderung leicht überprüfbar

Behalten Sie einen kanonischen Laufzeitpfad bei. Entfernen Sie veraltete Zweige, statt stilles Kompatibilitätsverhalten hinzuzufügen. Halten Sie Komponenten modular, nutzen Sie die vorhandenen Abhängigkeiten und bewahren Sie fremde Arbeit in einem Checkout mit offenen Änderungen. Das Repository begrenzt Dateien auf 550 Zeilen und Funktionen auf 100 Zeilen. Die Baseline-Dateien .max-lines-baseline und .max-function-lines-baseline halten bestehende Altlasten fest und dürfen nur schrumpfen. AGENTS.md setzt ein Ziel von fünf verfassten Quell- oder Testdateien pro Ordner, und check:max-folder-files schlägt oberhalb von sieben fehl. Teilen Sie einen wachsenden Ordner nach Feature oder Leseraufgabe. Ein Ordner mit Nummer, Buchstabe, part, misc oder more erfüllt die Regel nicht.

Ein Beitrag sollte den Auslöser, das resultierende Verhalten, den betroffenen Vertrag und die Validierungsnachweise erklären, mit einem Screenshot für eine sichtbare Änderung und einer begrenzten Ablaufspur für einen Zustellfehler. Nehmen Sie nie private Session-Transkripte, Auth-Dateien oder maschinenspezifische Pfade auf.