Mobiler Begleiter

Plattform und Funktionen

apps/mobile ist eine Expo SDK 57-Anwendung, die React Native 0.86.3, React 19.2, Expo Router, NativeWind, Reanimated und Gesture Handler verwendet. Der unterstützte angeheftete Netzwerktransport wird lokal in Swift implementiert companion-net modul. Die iOS-Bundle-ID lautet com.cadcamfun.mobile.

Das Telefon liest Projekte, überprüft den Verlauf und Pull-Anfragen, leitet Workflows weiter, empfängt Aktivitäten und interagiert mit Assistentensitzungen, die auf dem gekoppelten Desktop ausgeführt werden. Der Desktop ist weiterhin Eigentümer der Datenbank, der Geometrieberechnung, der Anmeldeinformationen des KI-Anbieters und der Workflow-Ausführung. Für diese Vorgänge ist ein erreichbarer, laufender Desktop erforderlich.

Anwendungsstruktur

Expo Router trennt Verbindungsbildschirme von authentifizierten Anwendungsregisterkarten. app/connect.tsx verarbeitet die Pairing-Eingabe, app/pair.tsx akzeptiert Deep Links und app/(app) enthält Projekte, Assistent, Aktivität und Einstellungen. Zu den Projektbildschirmen gehören Übersichts-/Verlaufs-/Pull-/Workflow-Panels, Commit-Details und Pull-Request-Überprüfung.

• components/: wiederverwendbare Steuerelemente, Projektfenster, Assistententranskript und Verbindungs-Benutzeroberfläche.
• lib/client.ts: typisierter Client über einen injizierten Transport; API-Typen werden ohne die Serverlaufzeit importiert.
• lib/pairing.ts, native.ts, und storage.ts: paarungsvalidierung, Transportauswahl und persistente Anmeldeinformationen.
• lib/sse.ts, live-events.ts, und chat-log.ts: stream-Analyse, Live-Abonnements und Transkriptstatus.
• modules/companion-net/: Expo-Modul und Swift-Pin-HTTPS-Implementierung.

Transport- und Gateway-Bereich

Das Companion-Gateway ist vom Loopback-Listener des Sidecars getrennt. Es ist standardmäßig deaktiviert. Durch die Aktivierung wird ein HTTPS-Server gestartet 0.0.0.0, unter Verwendung von Port 8443, sofern kein anderer gültiger Port ausgewählt ist. Der Dienst behält seinen aktivierten Zustand bei und nimmt ihn nach dem Start des Sidecars wieder auf. Die Desktop-Firewall und die Netzwerkroute müssen es dem Telefon ermöglichen, diesen Listener zu erreichen.

Das Telefon sendet ein widerrufliches Geräte-Token. Das Gateway speichert seinen SHA-256-Hash, prüft die Anforderungsmethode/den Anforderungspfad anhand einer Zulassungsliste und leitet akzeptierte Anforderungen mithilfe des Desktop-Tokens an die Loopback-API weiter. Das Telefon erhält dieses Starttoken nicht. Eine ungültige Authentifizierung gibt 401 zurück, verweigerte Routen geben 403 zurück, wiederholte fehlgeschlagene Authentifizierung kann 429 zurückgeben und ein nicht verfügbarer Upstream gibt 502 zurück.

Allowed families include project reads; version-control, pull-request, and workflow endpoints; project events; notifications; assistant status/models/agents; streaming chat; queue/abort; permissions; and session state/control. Files, credentials, plugins, billing, gateway administration, and GitHub remote/push/pull endpoints are excluded.

Das Gateway begrenzt fehlgeschlagene Authentifizierungsversuche: Nach zehn fehlgeschlagenen Trägerversuchen von einer IP-Adresse innerhalb von 60 Sekunden empfangen weitere Anfragen von dieser Adresse HTTP 429, bis das Fenster abläuft (apps/sidecar/src/services/companion-gateway.ts).

Assistentensitzungen und Offline-Nachrichten

Der Begleiter sendet Chatanfragen an POST /api/ai/chat/stream und analysiert vom Server gesendete Ereignisse. Eine Sitzungskennung ermöglicht die Fortsetzung der Desktop-Konversation. Der Client kann Nachrichten steuern oder in die Warteschlange stellen, eine Runde abbrechen, Fragen beantworten und auf Erlaubnisanfragen antworten. Konfigurieren Sie den Modellanbieter auf dem Desktop. Das Telefon fragt vor der Verwendung den AI-Status ab.

Wenn ein Stream ohne Terminal endet done oder error frame ausgeführt und nicht abgebrochen wurde, meldet der Client eine unvollständige Verbindung. Der native Transport schließt sein Stream-Handle bei Abbruch und Abschluss. Bei der nativen Dekodierung bleiben unvollständige UTF-8-Skalare zwischen Byteblöcken erhalten.

Assistentennachrichten, die nicht gesendet werden können, können in eine dauerhafte Warteschlange gelangen. Es behält höchstens 50 Einträge bei, löscht die ältesten, wenn sie voll sind, und versucht es bei der Vordergrund- und Konnektivitätswiederherstellung erneut. Fehlgeschlagene Einträge bleiben in der Warteschlange. In dieser Warteschlange werden Nachrichten zur späteren Ausführung gespeichert. Es handelt sich nicht um eine Offline-Kopie der Projektgeometrie oder eine Offline-KI-Laufzeitumgebung.

Erstellen und ausführen

bun install
bun run --cwd apps/mobile test
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile build
bun run --cwd apps/mobile ios
bun run --cwd apps/mobile ios:release --device

Der Build-Befehl exportiert das iOS-JavaScript-Bundle nach apps/mobile/dist; es wird kein IPA erstellt. Für die iOS-Ausführungsbefehle sind macOS, Xcode und CocoaPods erforderlich. Für die Geräteinstallation sind außerdem ein vertrauenswürdiges Gerät, der Entwicklermodus und ein Apple-Signaturteam erforderlich, das für das generierte Xcode-Projekt konfiguriert ist. native:generate führt Expo Prebuild für iOS aus, ohne Pods zu installieren. Für die tägliche Arbeit, start (alias dev) führt den Expo-Entwicklungs-Client-Bundler aus, ios:dev startet es auf localhost und öffnet den iOS-Simulator, ios:build kompiliert die Debug-App, ohne einen Bundler zu starten, und web startet das Expo-Webziel. Der test skript läuft bun test test innen apps/mobile.

.github/workflows/ci.yml definiert Companion-Typprüfung, Logiktests und JavaScript-Export. .github/workflows/ios.yml generiert das Xcode-Projekt, erstellt eine nicht signierte Release-Simulator-App, koppelt sie mit einem Live-Sidecar, überprüft die authentifizierte Projektliste und erfasst einen Screenshot. Diese konfigurierten Prüfungen stellen keine Akzeptanz für physische Geräte, Signaturen, TestFlight oder echte Anbieter her.

Speicher- und Gerätesicherheit

Unter nativem iOS werden die Anmeldeinformationen für die Kopplung mit Expo SecureStore gespeichert. Der Pairing-Eintrag verwendet WHEN_UNLOCKED_THIS_DEVICE_ONLY. Offline-Warteschlangeneinträge und in der Sitzung angezeigte Markierungen verwenden ebenfalls SecureStore. Der Browser-Fallback nutzt lokalen Speicher für die Entwicklung.

Die App fragt biometrische Fähigkeiten und Verwendungen ab expo-local-authentication für die lokale Authentifizierung mit aktiviertem System-Passcode-Fallback. Die biometrische Benutzeroberfläche ändert nicht die serverseitigen Routenberechtigungen des Gateways. Der Gerätewiderruf wird vom gekoppelten Desktop gesteuert.

Der Desktop behält sein Gateway-Zertifikat und seinen privaten Schlüssel in seinem Anwendungsdaten-Begleitverzeichnis; Der Schlüssel wird nur mit Eigentümerberechtigungen geschrieben. Das Ersetzen dieses Zertifikats ändert den angehefteten Fingerabdruck und erfordert eine neue vertrauenswürdige Kopplung.

Workflow für die Projektüberprüfung

1. Öffnen Sie Projekte und wählen Sie ein Desktop-Projekt aus.
2. Überprüfen Sie den Arbeitsstatus, die Branches, Commits, Pull Requests oder Workflow-Ausführungen.
3. Öffnen Sie einen Commit, um dessen Diff zu überprüfen, oder öffnen Sie eine Pull-Anfrage, um Änderungen zu überprüfen und ein Urteil abzugeben.
4. Verwenden Sie die verfügbaren Zusammenführungs-/Schließungs- oder Workflow-Versandaktionen, wenn dies für das Projekt angemessen ist.
5. Öffnen Sie den Assistenten mit dem ausgewählten Projektkontext, um eine KI-Sitzung fortzusetzen oder zu starten.

Alle Änderungen werden auf dem Desktop ausgeführt. Eine Netzwerkunterbrechung, ein Widerruf der Autorisierung oder ein angehaltener Desktop verhindern die Arbeit eines neuen Servers. Lokal in der Warteschlange befindliche Assistentennachrichten werden später erneut versucht.

Client-Schnittstelle

CompanionClient akzeptiert a Transport with JSON request and text-stream methods. It exposes project reads; VCS status, history, diff, commit, branch, checkout, and restore; pull requests and reviews; workflow runs and dispatch; AI status/models/agents; session control; notifications; and project event streams.

JSON-Fehler werden CompanionError mit Status und Meldung. Streaming-Chat und Live-Ereignisse nutzen den gemeinsam genutzten SSE-Parser, sodass willkürliche Netzwerk-Chunk-Grenzen nicht zu Anwendungsereignisgrenzen werden. Tests injizieren Transporte, ohne native Module zu importieren oder einen Simulator auszuführen.

Koppeln Sie ein Telefon

1. Öffnen Sie auf dem Desktop die Einstellungen und das zugehörige Mobile-Begleitfenster, oder /settings/companion, und schalten Sie das Gateway ein.
2. Erstellen Sie eine benannte Gerätekopplung und zeigen Sie den QR-Code an. Der Link enthält HTTPS-Hostkandidaten, ein Gerätetoken und den Zertifikatsfingerabdruck.
3. Scannen Sie unter iOS den QR-Code oder fügen Sie ihn ein cadcamfun://pair link. Erlauben Sie den Zugriff auf das lokale Netzwerk, wenn Sie dazu aufgefordert werden.
4. Die App validiert den Link, testet die angekündigten Host-Kandidaten und behält die erste erfolgreiche Gesundheitsverbindung bei.
5. Bestätigen Sie, dass das Gerät in den Desktop-Einstellungen angezeigt wird. Verwenden Sie die Widerrufsaktion des Desktops, um dessen Zugriff zu entfernen.

Zu den Hostkandidaten gehören geeignete private IPv4- und Overlay-Netzwerkadressen; Das Gateway gibt höchstens sechs erkannte Adressen bekannt. Der aktuelle Listener ist IPv4, daher werden erkannte IPv6-Adressen nicht angekündigt. Ein VPN- oder Overlay-Netzwerk muss bereits Routing für die Verwendung außerhalb des lokalen Netzwerks bereitstellen; Beim Pairing wird weder ein Relay noch ein VPN erstellt.

Anheften von Zertifikaten

Die Swift-Implementierung verwendet Ephemeral URLSession instanzen mit einem Vertrauensdelegierten. Es akzeptiert ein Blattzertifikat nur, wenn der SHA-256-Hash seiner DER-Bytes dem Fingerabdruck aus der Paarung entspricht. Anfragen erfordern HTTPS, Weiterleitungen werden abgelehnt und native Aufrufer führen niemals stillschweigend ein Downgrade auf den Browser-Transport durch.

Die Vertrauenswürdigkeit des Zertifikats ergibt sich daher aus dem Pairing-Link. Behandeln Sie den QR-Code und den eingefügten Link als Anmeldeinformationen. Ein Link mit einem unerwarteten Ursprung oder Fingerabdruck sollte durch den Desktop-Pairing-Ablauf ersetzt werden, anstatt die TLS-Validierung zu umgehen.

Diagnostizieren Sie eine Verbindung

• Kein einheimischer Transport: installieren Sie einen iOS-Entwicklungs- oder Release-Build, der das lokale Modul enthält.
• Kein erreichbarer Host: überprüfen Sie die Berechtigung für das lokale Netzwerk, die Desktop-Firewall, die angekündigte Adresse, den Gateway-Port und das Netzwerk-Routing.
• 401: das Geräte-Token ist ungültig oder widerrufen; Erstellen Sie eine neue Paarung.
• 403: der Endpunkt liegt außerhalb der Companion-Zulassungsliste.
• Nicht übereinstimmendes Zertifikat: erneut mit dem aktuellen Desktop-Zertifikat koppeln.
• Assistent nicht verfügbar: überprüfen Sie die Konfiguration des Desktop-Anbieters und ob der Sidecar ausgeführt wird.

Telefoneinstellungen und lokaler Status

UI-Einstellungen befinden sich in AsyncStorage unten cadcamfun.ui.v1; beim Pairing von Anmeldeinformationen, Nachrichten in der Warteschlange und Markierungen für gesehene Sitzungen wird SecureStore verwendet. Der UI-Store merkt sich das ausgewählte Projekt und die letzte Sitzung pro Projekt für einen gekoppelten Desktop. Durch das Ändern der Desktop-Identität wird die gespeicherte Projekt-/Sitzungszuordnung gelöscht, sodass sie nicht für einen nicht zugehörigen Server wiederverwendet wird.

Der Sperrkoordinator überspringt Start- und Verbindungsbildschirme und zeigt ein Entsperr-Overlay im Vollbildmodus für eine gekoppelte App an. Serverseitige Sitzungen werden nicht angehalten oder ein Token widerrufen. Durch das Aufheben der Kopplung wird die gespeicherte Kopplung des Telefons entfernt und es kehrt zu „Verbinden“ zurück. Der Desktop-Sperrvorgang ist die separate Aktion, die verhindert, dass sich das Token erneut authentifiziert.

Beispiel für die Gateway-Verwaltung

Diese Anfragen werden an die Desktop-Loopback-API mit ihrem Starttoken ausgeführt, nicht an das Telefon-Gateway. Verwenden Sie eine isolierte Entwicklungsinstanz. Ersetzen Sie den Beispielport durch den Port aus seinem Ready-Ereignis und stellen Sie das Token dieses Prozesses bereit.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/enable"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"port":18443}'

Die Statusantwort enthält enabled, eine Nullable port, eine Nullable fingerprint, das vorgeschlagene host, und devices. Der Dienst akzeptiert explizite Ports von 1024 bis 65535. Ein bereits verwendeter Port kann den Listener nicht starten. Wählen Sie einen anderen Port und generieren Sie die Pairing-Adresse neu.

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/pair"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Development iPhone","host":"192.168.1.20"}'

Ersetzen Sie den Beispielhost durch eine Adresse, an die das Telefon weiterleiten kann. Bei erfolgreicher Kopplungserstellung wird HTTP 201 mit einem Gerät zurückgegeben id und ein Berechtigungsnachweis link. Der gekürzte Name muss 1–60 Zeichen enthalten. Scannen Sie diesen Link und fügen Sie ihn privat ein. Kopieren Sie es nicht in einen Fehlerbericht. Durch das Erstellen des Tokens wird das Gateway nicht automatisch aktiviert.

Um den Zugriff zu entfernen, senden Sie DELETE /api/companion/devices/<id> mithilfe der Desktop-Autorisierung. Um den gesamten neuen Gateway-Verkehr zu stoppen, senden Sie POST /api/companion/disable. Geräte-Hashes werden bei jeder Anfrage überprüft, sodass widerrufene Token bei nachfolgenden Anfragen abgelehnt werden.

Wiederherstellung, ohne den Kontext zu verlieren

1. Tippen Sie in den Einstellungen auf die Zeile der Desktop-Verbindung, um den Zustand der angekündigten Hosts erneut zu testen.
2. Wenn nur ein Netzwerkpfad ausfällt, überprüfen Sie die korrekte WLAN-/Hotspot-/VPN-Route und generieren Sie nach Änderungen der Desktop-Adresse einen QR-Code neu.
3. Wenn die Autorisierung fehlschlägt, widerrufen Sie das veraltete Gerät auf dem Desktop und erstellen Sie eine neue Kopplung.
4. Wenn nur ein Assistenten-Stream fehlgeschlagen ist, öffnen Sie die Projektsitzung erneut und überprüfen Sie ihren Status, bevor Sie dieselbe Anweisung erneut senden.
5. Überprüfen Sie die Anzahl der in der Warteschlange befindlichen Nachrichten, bevor Sie eine doppelte Eingabeaufforderung senden. Vorgänge in der Warteschlange werden später wiederholt.

Die Offline-Warteschlange verfügt über eine begrenzte Aufbewahrung und spielt jeden ausstehenden Vorgang über eine neue Chat-Anfrage mit der gespeicherten Sitzungskennung ab, sofern verfügbar. Es handelt sich nicht um eine Garantie für eine exakt einmalige Lieferung. Ein Netzwerkabbruch nach der Serverausführung kann dazu führen, dass der Client unsicher ist, ob die Ausführung abgeschlossen ist. Überprüfen Sie den resultierenden Projekt-/Sitzungsstatus, bevor Sie eine Änderung wiederholen.

Umsetzungsanker: app/(app)/settings.tsx, components/layout/AppLockCoordinator.tsx, lib/store.ts, lib/server.tsx, und lib/offline-queue.ts.

Gateway-Zulassungsliste

Das Telefon kommuniziert mit dem Desktop nur über das Companion-Gateway, das diesen festen Satz von Routen zulässt und sie an die Loopback-API weiterleitet:

Da die Liste im Sidecar festgelegt ist, ist eine Funktion, die eine andere Route benötigt (z. B. Datei-Upload oder GitHub-Push), eine reine Desktop-Funktion, bis sich die Liste ändert.

Was das Telefon speichert

Bei einem Browser-Entwicklungs-Build fallen dieselben Daten in den lokalen Speicher zurück, der nicht verschlüsselt ist. Verwenden Sie es nur mit Wegwerfpaarungen.

Bildschirme

Routen verwenden Expo-Router-Dateikonventionen: (app) ist eine Gruppe, die ein Layout teilt, ohne ein URL-Segment hinzuzufügen, und [id] ist ein Parameter.

Offline-Assistentenwarteschlange

Wenn der Desktop nicht erreichbar ist, wird eine im Assistenten eingegebene Nachricht auf dem Telefon in die Warteschlange gestellt und geht nicht verloren:

Nur Verbindungsfehler stellen eine Nachricht in die Warteschlange. Ein Versand gilt als offline, wenn der Client den Status 0 meldet oder der Fehlertext einen Netzwerkfehler, eine Zeitüberschreitung, eine verweigerte Verbindung oder ähnliches erwähnt; HTTP- und Geschäftsfehler („Anfrage an … fehlgeschlagen mit …“) werden angezeigt und nicht in die Warteschlange gestellt.

In 3D