Compagno mobile

Piattaforma e capacità

apps/mobile è un'applicazione Expo SDK 57 che utilizza React Native 0.86.3, React 19.2, Expo Router, NativeWind, Reanimated e Gesture Handler. Il trasporto di rete bloccato supportato è implementato in Swift dal locale companion-net modulo. L'identificatore del bundle iOS è com.cadcamfun.mobile.

Il telefono legge progetti, esamina la cronologia e le richieste pull, invia flussi di lavoro, riceve attività e interagisce con le sessioni dell'assistente in esecuzione sul desktop associato. Il desktop continua a possedere il database, il calcolo della geometria, le credenziali del fornitore di intelligenza artificiale e l'esecuzione del flusso di lavoro. Per tali operazioni è necessario un desktop raggiungibile e funzionante.

Struttura dell'applicazione

Expo Router separa le schermate di connessione dalle schede delle applicazioni autenticate. app/connect.tsx gestisce l'input di abbinamento, app/pair.tsx accetta collegamenti diretti e app/(app) contiene Progetti, Assistente, Attività e Impostazioni. Le schermate del progetto includono pannelli di panoramica/cronologia/pull/flusso di lavoro, dettagli di commit e revisione delle richieste pull.

• components/: controlli riutilizzabili, pannelli di progetto, trascrizione dell'assistente e interfaccia utente di connessione.
• lib/client.ts: client digitato su un trasporto iniettato; I tipi API vengono importati senza il runtime del server.
• lib/pairing.ts, native.ts, e storage.ts: convalida dell'accoppiamento, selezione del trasporto e credenziali persistenti.
• lib/sse.ts, live-events.ts, e chat-log.ts: analisi dello streaming, abbonamenti live e stato della trascrizione.
• modules/companion-net/: Modulo Expo e implementazione HTTPS bloccata da Swift.

Ambito di trasporto e gateway

Il gateway complementare è separato dal listener di loopback del sidecar. È disattivato per impostazione predefinita. Abilitandolo si avvia un server HTTPS 0.0.0.0, utilizzando la porta 8443 a meno che non venga selezionata un'altra porta valida. Il servizio mantiene il suo stato abilitato e lo riprende dopo l'avvio del sidecar. Il firewall del desktop e il percorso di rete devono consentire al telefono di raggiungere questo ascoltatore.

Il telefono invia un token del dispositivo revocabile. Il gateway archivia il proprio hash SHA-256, controlla il metodo/percorso della richiesta rispetto a un elenco consentito e inoltra le richieste accettate all'API di loopback utilizzando il token desktop. Il telefono non riceve il token di avvio. L'autenticazione non valida restituisce 401, le rotte negate restituiscono 403, l'autenticazione ripetuta non riuscita può restituire 429 e un upstream non disponibile restituisce 502.

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.

Il gateway limita i tentativi di autenticazione non riusciti: dopo dieci tentativi di portante falliti da un indirizzo IP entro 60 secondi, ulteriori richieste da quell'indirizzo ricevono HTTP 429 fino alla scadenza della finestra (apps/sidecar/src/services/companion-gateway.ts).

Sessioni dell'assistente e messaggi offline

Il compagno invia richieste di chat a POST /api/ai/chat/stream e analizza gli eventi inviati dal server. Un identificatore di sessione consente la continuazione della conversazione sul desktop. Il client può dirigere o accodare messaggi, interrompere una svolta, rispondere a domande e rispondere alle richieste di autorizzazione. Configurare il provider del modello sul desktop; il telefono interroga lo stato dell'AI prima dell'uso.

Se uno stream termina senza un terminale done o error frame e non è stato annullato, il client segnala una connessione incompleta. Il trasporto nativo chiude l'handle del flusso in caso di annullamento e completamento. La decodifica nativa preserva gli scalari UTF-8 incompleti tra i blocchi di byte.

I messaggi dell'assistente che non possono essere inviati possono entrare in una coda permanente. Conserva al massimo 50 voci, eliminando quelle più vecchie quando sono piene e riprova in primo piano e nel ripristino della connettività. Le voci non riuscite rimangono in coda. Questa coda memorizza i messaggi per l'esecuzione successiva; non è una copia offline della geometria del progetto o un runtime AI offline.

Costruisci e corri

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

Il comando build esporta il bundle JavaScript iOS in apps/mobile/dist; non produce un IPA. I comandi di esecuzione iOS richiedono macOS, Xcode e CocoaPods. L'installazione del dispositivo richiede inoltre un dispositivo attendibile, la modalità sviluppatore e un team di firma Apple configurato per il progetto Xcode generato. native:generate esegue Expo prebuild per iOS senza installare pod. Per il lavoro quotidiano, start (alias dev) esegue il bundler del client di sviluppo di Expo, ios:dev lo avvia su localhost e apre il simulatore iOS, ios:build compila l'app di debug senza avviare un bundler e web avvia il web target di Expo. IL test viene eseguito lo script bun test test dentro apps/mobile.

.github/workflows/ci.yml definisce il controllo del tipo associato, i test logici e l'esportazione JavaScript. .github/workflows/ios.yml genera il progetto Xcode, crea un'app di simulazione di rilascio non firmata, la associa a un sidecar live, controlla l'elenco dei progetti autenticati e acquisisce uno screenshot. Questi controlli configurati non stabiliscono l'accettazione del dispositivo fisico, della firma, di TestFlight o del fornitore reale.

Archiviazione e sicurezza dei dispositivi

Su iOS nativo, le credenziali di abbinamento vengono archiviate con Expo SecureStore. La voce di abbinamento utilizza WHEN_UNLOCKED_THIS_DEVICE_ONLY. Anche le voci della coda offline e gli indicatori di sessione visualizzati utilizzano SecureStore. Il fallback del browser utilizza l'archiviazione locale per lo sviluppo.

L'app interroga la capacità e gli usi biometrici expo-local-authentication per l'autenticazione locale, con fallback del passcode di sistema abilitato. L'interfaccia utente biometrica non modifica le autorizzazioni del percorso lato server del gateway. La revoca del dispositivo è controllata dal desktop associato.

Il desktop conserva il certificato del gateway e la chiave privata nella directory complementare dei dati dell'applicazione; la chiave viene scritta con autorizzazioni di solo proprietario. La sostituzione del certificato modifica l'impronta digitale bloccata e richiede un nuovo accoppiamento attendibile.

Flusso di lavoro di revisione del progetto

1. Apri Progetti e scegli un progetto desktop.
2. Ispeziona lo stato di funzionamento, i rami, i commit, le richieste pull o le esecuzioni del flusso di lavoro.
3. Apri un commit per esaminarne le differenze o apri una richiesta pull per esaminare le modifiche e inviare un verdetto.
4. Utilizza le azioni di unione/chiusura o di invio del flusso di lavoro disponibili quando appropriato per il progetto.
5. Apri l'Assistente con il contesto del progetto selezionato per continuare o avviare una sessione AI.

Tutte le modifiche vengono eseguite sul desktop. L'interruzione della rete, l'autorizzazione revocata o un desktop arrestato impediscono il nuovo funzionamento del server; I messaggi dell'assistente in coda locale vengono ritentati in seguito.

Interfaccia cliente

CompanionClient accetta 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.

Gli errori JSON diventano CompanionError con uno stato e un messaggio. La chat in streaming e gli eventi live utilizzano il parser SSE condiviso in modo che i limiti arbitrari dei blocchi di rete non diventino limiti degli eventi dell'applicazione. I test inseriscono trasporti senza importare moduli nativi o eseguire un simulatore.

Accoppia un telefono

1. Sul desktop, apri Impostazioni e il relativo pannello Mobile, oppure /settings/companione accendere il gateway.
2. Crea un accoppiamento con nome del dispositivo e visualizza il codice QR. Il collegamento contiene i candidati host HTTPS, un token del dispositivo e l'impronta digitale del certificato.
3. Su iOS, scansiona il codice QR o incolla il file cadcamfun://pair collegamento. Consenti l'accesso alla rete locale quando richiesto.
4. L'app convalida il collegamento, gareggia con i candidati host pubblicizzati e mantiene la prima connessione sanitaria riuscita.
5. Verifica che il dispositivo venga visualizzato nelle impostazioni del desktop. Utilizza l'azione di revoca del desktop per rimuoverne l'accesso.

I candidati host includono IPv privati4 e indirizzi di rete overlay adeguati; il gateway pubblicizza al massimo sei indirizzi scoperti. Il listener corrente è IPv4, quindi gli indirizzi IPv6 rilevati non vengono pubblicizzati. Una rete VPN o overlay deve già fornire il routing da utilizzare lontano dalla rete locale; l'accoppiamento non crea un relè o una VPN.

Blocco del certificato

L'implementazione Swift utilizza effimero URLSession istanze con un delegato di fiducia. Accetta un certificato foglia solo quando l'hash SHA-256 dei suoi byte DER equivale all'impronta digitale dell'accoppiamento. Le richieste richiedono HTTPS, i reindirizzamenti vengono rifiutati e i chiamanti nativi non eseguono mai il downgrade silenzioso al trasporto del browser.

L'attendibilità del certificato deriva quindi dal collegamento di accoppiamento. Considera il codice QR e il collegamento incollato come credenziali. Un collegamento con un'origine o un'impronta digitale imprevista deve essere sostituito tramite il flusso di accoppiamento del desktop anziché ignorare la convalida TLS.

Diagnosticare una connessione

• Nessun trasporto nativo: installare uno sviluppo iOS o una build di rilascio contenente il modulo locale.
• Nessun host raggiungibile: controlla l'autorizzazione della rete locale, il firewall desktop, l'indirizzo pubblicizzato, la porta del gateway e il routing della rete.
• 401: il token del dispositivo non è valido o è stato revocato; creare un nuovo abbinamento.
• 403: l'endpoint è esterno all'elenco consentito associato.
• Mancata corrispondenza del certificato: associarlo nuovamente al certificato desktop corrente.
• Assistente non disponibile: controlla la configurazione del provider desktop e se il sidecar è in esecuzione.

Impostazioni del telefono e stato locale

Le preferenze dell'interfaccia utente si trovano in AsyncStorage sotto cadcamfun.ui.v1; le credenziali di associazione, i messaggi in coda e gli indicatori di sessione vista utilizzano SecureStore. L'archivio dell'interfaccia utente ricorda il progetto selezionato e l'ultima sessione per progetto per un desktop abbinato. La modifica dell'identità del desktop cancella la mappatura del progetto/sessione ricordata in modo che non venga riutilizzata su un server non correlato.

Il coordinatore del blocco salta le schermate di avvio e connessione e mostra una sovrapposizione di sblocco a schermo intero per un'app abbinata. Non sospende le sessioni lato server né revoca un token. L'annullamento dell'abbinamento rimuove l'abbinamento salvato del telefono e ritorna a Connetti; la revoca del desktop è l'azione separata che impedisce la nuova autenticazione del token.

Esempio di amministrazione del gateway

Queste richieste vengono eseguite sull'API di loopback del desktop con il relativo token di avvio, non sul gateway del telefono. Utilizza un'istanza di sviluppo isolata. Sostituisci la porta di esempio con la porta del suo evento ready e fornisci il token di quel processo.

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}'

La risposta sullo stato contiene enabled, un nullable port, un nullable fingerprint, il suggerito host, e devices. Il servizio accetta porte esplicite da 1024 a 65535. Una porta già in uso non riesce ad avviare il listener; scegli un'altra porta e rigenera l'indirizzo di accoppiamento.

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"}'

Sostituisci l'host di esempio con un indirizzo a cui il telefono può instradare. La creazione dell'associazione riuscita restituisce HTTP 201 con un dispositivo id e un portatore di credenziali link. Il nome troncato deve contenere 1–60 caratteri. Scansiona/incolla il link in privato; non copiarlo in una segnalazione di bug. La creazione del token non attiva automaticamente il gateway.

Per rimuovere l'accesso, invia DELETE /api/companion/devices/<id> utilizzando l'autorizzazione desktop. Per interrompere tutto il nuovo traffico gateway, invia POST /api/companion/disable. Gli hash del dispositivo vengono controllati a ogni richiesta, quindi i token revocati vengono rifiutati nelle richieste successive.

Recupero senza perdere il contesto

1. Tocca la riga della connessione desktop in Impostazioni per riprovare l'integrità con gli host pubblicizzati.
2. Se solo un percorso di rete fallisce, verifica il percorso Wi-Fi/hotspot/VPN corretto e rigenera un codice QR dopo la modifica dell'indirizzo del desktop.
3. Se l'autorizzazione fallisce, revoca il dispositivo obsoleto sul desktop e crea un nuovo abbinamento.
4. Se solo un flusso dell'assistente ha avuto esito negativo, riapri la sessione del progetto e controllane lo stato prima di inviare nuovamente la stessa istruzione.
5. Controllare il conteggio dei messaggi in coda prima di inviare una richiesta duplicata; le operazioni in coda riprovano più tardi.

La coda offline ha una conservazione limitata e riproduce ogni operazione in sospeso tramite una nuova richiesta di chat che trasporta l'identificatore di sessione memorizzato quando disponibile. Non è una garanzia di consegna esatta. Un'interruzione della rete dopo l'esecuzione del server può lasciare il client incerto sul completamento; ispezionare lo stato risultante del progetto/sessione prima di ripetere una modifica.

Ancore di implementazione: app/(app)/settings.tsx, components/layout/AppLockCoordinator.tsx, lib/store.ts, lib/server.tsx, e lib/offline-queue.ts.

Elenco consentiti del gateway

Il telefono comunica con il desktop solo tramite il gateway complementare, che ammette questo insieme fisso di percorsi e li inoltra all'API di loopback:

Poiché l'elenco è fisso nel sidecar, una funzionalità che richiede un altro percorso (ad esempio il caricamento di file o il push di GitHub) è una funzionalità solo desktop finché l'elenco non cambia.

Cosa memorizza il telefono

In una build di sviluppo del browser, gli stessi dati ricadono nell'archiviazione locale, che non è crittografata. Usatelo solo con abbinamenti usa e getta.

Schermi

I percorsi utilizzano le convenzioni dei file Expo Router: (app) è un gruppo che condivide un layout senza aggiungere un segmento URL e [id] è un parametro.

Coda dell'assistente offline

Quando il desktop non è raggiungibile, un messaggio digitato nell'assistente viene accodato sul telefono invece di essere perso:

Solo gli errori di connettività accodano un messaggio. Un invio viene considerato offline quando il client segnala lo stato 0 o il testo dell'errore menziona un errore di rete, timeout, connessione rifiutata o simili; Gli errori HTTP e aziendali ("richiesta a... non riuscita con...") vengono visualizzati anziché messi in coda.

Nel 3D