Zum Inhalt springen
covey

Die covey-App

Eine Flutter-App, gebaut aus mobile/, für iPhone und iPad, Android, den Mac und Windows; ein Linux-Build ist angelegt. Sie ist der Ort, an dem ein Mensch mit den Agenten arbeitet, nicht der, von dem aus sie betrieben werden: Sie koppelt sich mit einer Instanz, zeigt die Agenten und was auf diesen Menschen wartet, bringt eine Nachricht zu einem Agenten und eine Antwort zurück und diktiert auf dem Gerät. Agenten, Secrets, Guard-Rails oder die Plattform einrichten bleibt Sache der Weboberfläche — die App hat nichts davon, mit Absicht (spec/27-mobile-app.md).

Stand: ein Prototyp. Sie meldet sich mit einem API-Schlüssel an, den ihr das Koppeln gibt; die gerätegebundene Anmeldung, die die Spezifikation verlangt, gibt es noch nicht. Einem Agenten schreiben setzt voraus, dass die Team-Oberfläche der Organisation eingeschaltet ist (Verwaltung → Administration, Reiter Profil, Karte Team-Oberfläche); ausgeschaltet liest die App mit und sagt, warum sie nicht schreiben kann.

Die App ist für jede Installation dieselbe: Beim ersten Start fragt sie, mit welcher covey sie arbeiten soll.

Die App bekommen

In der Weboberfläche hat das Benutzermenü einen Eintrag covey-App. Er listet die vier Plattformen, verlinkt die Downloads für Mac und Windows und zeigt darunter den Kopplungscode.

Plattform Woher sie kommt
iPhone und iPad Noch nicht im App Store. Jedes Release lädt den Build zu App Store Connect hoch, wo TestFlight ihn den internen Testern des Projekts gibt; zur Prüfung eingereicht wird nichts. iOS 15 oder neuer.
Android Noch nicht bei Google Play, und das Release veröffentlicht keinen Android-Build. Mit Flutter aus mobile/ bauen.
Mac covey-app_<Version>_macos.zip, am GitHub-Release. macOS 12 oder neuer. Sie aktualisiert sich selbst über Sparkle, wenn das Release einen Update-Feed trägt.
Windows covey-app_<Version>_windows.zip, am GitHub-Release. Irgendwohin entpacken und covey_mobile.exe starten; einen Installer gibt es nicht.
Linux Angelegt, kein Paket. Es fehlt die Registrierung von covey:// (eine .desktop-Datei).

Die Download-Links im App-Dialog zeigen auf das Release der eigenen Version der Instanz, damit App und Server zusammenpassen; eine Instanz, die zwischen zwei Tags gebaut ist, verlinkt das neueste Release, und eine, deren Quelle nicht auf GitHub liegt, bekommt keinen Link statt eines falschen.

Mac. Die App ist signiert und notarisiert, wenn das Release mit dem Zertifikat des Projekts gebaut wurde. Ein unsignierter Build sagt das in den Release-Notizen, und Gatekeeper verweigert dann den ersten Start: Rechtsklick auf covey.app → Öffnen, oder xattr -dr com.apple.quarantine covey.app.

Mac App Store. Jedes Release baut außerdem eine zweite Mac-App für den Mac App Store: in der App Sandbox und deshalb ohne „Überall diktieren“ und Aktivitätsprotokoll, die in andere Apps hineinreichen; sie aktualisiert sich auch nicht selbst, das übernimmt der Store. Mit den Store-Zertifikaten des Projekts lädt das Release sie zu App Store Connect hoch, in denselben App-Eintrag wie die iPhone-App; zur Prüfung eingereicht wird nichts, im Mac App Store ist sie also noch nicht. Der direkte Download oben bleibt, wie er ist.

Windows. Die App ist nicht code-signiert, deshalb hält SmartScreen sie beim ersten Start an: Weitere Informationen, dann Trotzdem ausführen. Sie aktualisiert sich nicht selbst; eine neue Version ist ein neuer Download. Bei jedem Start registriert sie covey:// für den aktuellen Benutzer (HKEY_CURRENT_USER\Software\Classes\covey, ohne Administratorrechte) und lässt es auf ihre eigene ausführbare Datei zeigen — nachdem der Ordner verschoben wurde, gewinnt die zuletzt gestartete Kopie. Es gibt ein Fenster: Ein Link oder ein zweiter Start übergibt an das laufende. Wer die Registrierung loswerden will, löscht diesen Schlüssel.

Koppeln

Die App fragt nach keinem Passwort. Gekoppelt wird aus einem angemeldeten Browser:

  1. In der Weboberfläche das Benutzermenü öffnen → covey-App → Mit dieser covey koppeln, oder Profil & Einstellungen → Mobile App → Mobile App koppeln.
  2. Ein QR-Code erscheint. Er gilt einmal und fünf Minuten lang; die Seite zählt herunter und merkt, wenn die App ihn benutzt hat.
  3. In der App auf QR-Code scannen tippen und die Kamera darauf richten.

Die App tauscht den Code gegen einen API-Schlüssel, benannt nach dem Gerät, und legt ihn im Schlüsselbund (Apple) bzw. im Keystore (Android) ab. Der Schlüssel erscheint unter den API-Schlüsseln der Person in Profil & Einstellungen und lässt sich dort widerrufen wie jeder andere (API keys, englisch). Er trägt die Rechte des Platzes dieser Person und nicht mehr.

Der QR-Code trägt einen gewöhnlichen Link zur Instanz, https://<Host>/pair?code=…. Bei einer Instanz, deren Host die App beansprucht (app.covey.work oder eine Installation, die die App unter ihrem eigenen Host ausliefert, siehe App-Links), öffnet die Kamera des Telefons damit direkt die App. Überall sonst öffnet der Link die Seite /pair, die den Code über covey:// an die App weiterreicht.

Auf einem Desktop gibt es keine Kamera zum Scannen. Die Kopplungskarte hat einen Knopf In der App öffnen, einen Link covey://pair?instance=…&code=…, den die Mac- oder Windows-App annimmt.

Nur HTTPS. Die App verbindet sich nur mit HTTPS-Adressen, und die Kopplungsseite warnt, wenn sie nicht über HTTPS ausgeliefert wird. Die eine Ausnahme ist ein Debug-Build gegen http://localhost:8494 (http://10.0.2.2:8494 aus dem Android-Emulator).

Ohne Kamera oder Browser in Reichweite nimmt die App auch die Adresse und einen von Hand eingegebenen API-Schlüssel.

Entscheidungen

Was auf die Entscheidung eines Menschen wartet, wird in der App entschieden, über dieselben Wege und mit denselben Prüfungen wie in der Weboberfläche (#622):

  • Im Gespräch mit einem Agenten stehen seine offenen Freigaben (eine Guard-Rail hat eine Aktion angehalten, spec/06) und die offenen Punkte seiner Reviews (spec/21) als Karten über dem Eingabefeld. Eine Freigabe zeigt die Aktion mit genau den Parametern, die freigegeben werden, mit Freigeben und Ablehnen; steht in den Parametern genau ein Absatz Text, lässt Text korrigieren ihn umschreiben und diese Fassung freigeben. Ein offener Punkt hat Annehmen (oder Erledigt), Ablehnen und eine optionale Notiz.
  • Ein Konfigurationsvorschlag, aus dem Chat entworfen (#491), ist eine Karte im Gespräch, aus dem er kam: was sich ändert und warum, ein Hinweis, wenn er Zugänge erweitert, und Annehmen und Ablehnen für den, der entscheiden darf. Alle anderen lesen, wer entscheidet. Hat sich die Konfiguration seit dem Entwurf geändert, sagt die Karte, dass er neu geschrieben oder verworfen werden muss. Den Diff selbst zeigt weiter die Weboberfläche.
  • Ein Freigabeschritt eines Ablaufs (#564), der den Menschen nennt, steht im Team-Bereich unter Wartet auf Sie, mit einem Knopf je Option.

Welche Knöpfe eine Karte anbietet, folgt der Rolle des Sitzes und den Angaben der Instanz — Freigaben und offene Punkte entscheiden org_admin, agent_owner und security, was ACCESS.md oder EGRESS.md berührt, nehmen nur org_admin und security an, controlling sieht nur die Freigaben. Die Instanz prüft noch einmal; lehnt sie mit 403 ab, sagt die Karte das und bietet nichts mehr an.

Mitteilungen

Stellt ein Agent eine Rückfrage, antwortet er in einem Gespräch oder erledigt er eine Aufgabe, die aus einer Nachricht kam (oder scheitert daran), bekommen die Beteiligten eine Mitteilung — wer diesem Agenten in den letzten zwei Wochen geschrieben hat, wer die Aufgabe gestellt hat und bei einer Rückfrage der Mensch, an den der Agent berichtet. Was jemand schon gelesen hat, wird nicht gemeldet.

Eine wartende Entscheidung wird denen gemeldet, die sie treffen dürfen: eine Freigabe oder ein offener Punkt dem Besitzer des Agenten, wenn seine Rolle entscheiden darf, und den Admins der Organisation (und security, wo ein offener Punkt Zugänge berührt); ein Konfigurationsvorschlag ebenso, neben dem Gespräch, aus dem er entworfen wurde; ein Freigabeschritt eines Ablaufs dem Menschen, den er nennt. Jede hat ihre eigenen Worte („Bea wartet auf eine Freigabe“, „Release wartet auf eine Entscheidung“) und den Ton der Rückfrage.

Plattform Wie
iPhone und iPad Firebase Cloud Messaging, das die Mitteilung an Apple weitergibt
Android Firebase Cloud Messaging
Mac Die App zeigt sie selbst an, solange sie läuft, aus dem Ungelesenen; über einen Push-Dienst geht nichts
Windows, Linux keine

Wie die Instanz Firebase erreicht — direkt mit einem eigenen Dienstkonto, über ein Relay (Vorgabe https://app.covey.work, das das Dienstkonto der App-Builds des Projekts hat) oder aus —, stellt eine Administratorin der Installation unter Verwaltung → Plattform, Reiter Push, ein. Die Einzelheiten, die Umgebungsvariablen und die Einstellungsschlüssel stehen im Betriebshandbuch.

Was die Instanz verlässt. Eine Mitteilung trägt das Token des Geräts, den Namen des Agenten und was er getan hat („Bea hat eine Rückfrage“, in der Sprache des Geräts), die Zahl des Ungelesenen, die ID des Agenten, damit ein Tippen seinen Verlauf öffnet, und den gewählten Ton. Vom Gesagten steht nichts darin. Eine Organisation kann unter Verwaltung → Administration, Reiter Profil, Karte Push-Mitteilungen eine Vorschau einschalten; dann geht die erste Zeile des Gesagten mit. So oder so läuft die Mitteilung über Google und, für ein iPhone, über Apple — und über das Relay, wo eines benutzt wird.

Eine Mitteilung öffnet den Verlauf mit dem Agenten, um den es geht. Die App bietet covey-eigene Mitteilungstöne, den Ton des Systems oder keinen.

Einen Agenten anrufen (Test)

Auf dem Mac hat der Verlauf mit einem Agenten einen Anrufen-Knopf (⌘⇧C). Der Anruf füllt das Fenster mit dem Gesicht des Agenten, das zuhört, nachdenkt und spricht; die Person redet, und der Agent antwortet laut. Es ist ein Test: nur auf dem Mac, geschaltet unter Einstellungen → Anrufe (Test), voreingestellt an, für dieses Gerät allein.

Der Ton bleibt auf dem Mac. Der Sprachdetektor von Silero hört, wo gesprochen wird, und schneidet einen Redebeitrag an einer Pause von etwa 1 s ab (einstellbar in den Anruf-Einstellungen), das Sprachmodell erkennt ihn, und nur der Text geht ins Gespräch — als gewöhnliche Nachricht, markiert als im Anruf gesagt (meta.via = "call"), sodass der eigene Weg des Chats sie beantwortet und das Gespräch sie festhält wie jede andere. Die Antwort spricht der Stimmen-Anbieter der Organisation (Betrieb) mit der gesprochenen Stimme der covey-Stimme des Agenten, gestreamt, während sie entsteht; ohne Anbieter, oder solange er nicht erreichbar ist, spricht sie die Sprachausgabe des Macs, in der Sprache, in der sie geschrieben ist, mit einer Stimme, die je Agent aus den für diese Sprache installierten Stimmen gewählt wird, und der Anruf sagt das; eine lange Antwort wird auf ihre ersten Sätze gekürzt, der Rest steht im Chat. Eine Antwort auf etwas im Anruf Gesagtes trägt neben der geschriebenen eine gesprochene Fassung (#502) — wenige kurze Sätze ohne Kennungen und Links —, und der Anruf spricht diese; hat sie etwas weggelassen, sagt er, dass die Details im Chat stehen. Eine im Anruf eröffnete Aufgabe wird laut bestätigt, und ihr Ergebnis wird gesprochen, wenn es kommt, solange der Anruf noch offen ist. Wer spricht, während der Agent spricht, unterbricht ihn; Stumm hört auf zuzuhören, Auflegen (oder Esc) beendet den Anruf, und danach hört nichts mehr zu.

Ein Anruf geht ohne Kopfhörer (#507). Das Mikrofon läuft über dieselbe Audio-Engine, die die Stimme des Agenten abspielt, mit eingeschalteter Sprachverarbeitung von Apple: Die Echounterdrückung nimmt die Stimme des Agenten, das Tippen, während er nachdenkt, und die Töne des Anrufs aus dem Mikrofon, bevor der Sprachdetektor sie hört; Rauschunterdrückung und automatische Verstärkung glätten den Rest. Damit unterbricht, wer über den Agenten spricht, ihn nach etwa 0,1 s statt nach der eingestellten Unterbrechungszeit — außer in den ersten 3 s nach dem Start der Sprachverarbeitung, solange sich die Echounterdrückung einpendelt: Dann gilt die eingestellte Zeit (#511). Solange die Stimme des Agenten, das Tippen oder die Begrüßung spielt, zählt ein Moment des Mikrofons nur dann als die Person, wenn er mindestens 6 dB lauter ist als das, was gerade spielt (der Ton des Stimmen-Anbieters, dessen Pegel der Anruf kennt): Was von der Stimme des Agenten an der Echounterdrückung vorbeikommt, ist leiser. Die Prüfung, die einen Beitrag verwirft, der wiederholt, was der Agent gerade gesagt hat, bleibt als zweite Sicherung. Anderer Ton auf dem Mac wird so wenig abgesenkt, wie macOS es zulässt (ab macOS 14). Solange der Anruf offen ist, zeigt der Mac das Mikrofon als benutzt an, auch stummgeschaltet — Stumm hört auf zuzuhören, Auflegen gibt das Mikrofon eine Sekunde später frei.

Was nicht unterdrückt wird: Die Sprachausgabe des Macs, die spricht, wenn kein Stimmen-Anbieter spricht, spielt außerhalb dieser Engine — dann gilt wie bisher die eingestellte Unterbrechungszeit. Lässt sich die Sprachverarbeitung nicht einschalten oder startet die Engine des Anrufs nicht, nimmt der Anruf das einfache Mikrofon und verhält sich wie bisher ohne Kopfhörer: Kurze Stöße unterbrechen nicht, Echos werden an ihrem Text verworfen. Das Diagnoseprotokoll sagt je Anruf, was davon gilt — eine Zeile microphone: voice processing, echo cancellation yes|no, input "<Gerät>" 48000 Hz → 16000 Hz, output "<Gerät>" … — und hält einen Gerätewechsel mitten im Anruf fest. Hört der Agent sich trotzdem, oder kommt bei ihm Rauschen oder Abgeschnittenes an — falsch erkannte Beiträge, fehlende erste Wörter, ein pumpender Hintergrund: zuerst diese Zeile ansehen; prüfen, ob Ein- und Ausgabe die gemeinten Geräte sind (ein Bluetooth-Headset schaltet beide um, und AirPods fallen in ihren schlechteren Anrufmodus, solange ihr Mikrofon benutzt wird); ein externes Mikrofon weit weg von den Lautsprechern oder ein externer Lautsprecher, den der Mac nicht als seine eigene Ausgabe kennt, unterdrückt schlechter als das eingebaute Paar; ein lauter externer Verstärker oder eine Lautstärke nahe am Anschlag kann die Unterdrückung übersteuern. Bessere Mac-Stimmen, für den Fall ohne Anbieter, installiert man unter Systemeinstellungen → Bedienungshilfen → Gesprochene Inhalte.

Was wo geht

Die App ist eine Codebasis, aber mehrere Funktionen beruhen auf macOS-Schnittstellen und gibt es nur dort:

iPhone / iPad Android Mac Windows
Koppeln QR-Code QR-Code covey://-Link covey://-Link
Mitteilungen Push Push solange die App läuft —
Freigaben, offene Punkte, Vorschläge und Ablaufschritte entscheiden ja ja ja ja
Diktat in der App ja ja ja ja
Überall diktieren (globales Tastenkürzel) — — ja —
Aktivitätsprotokoll — — ja —
Einen Agenten anrufen (Test) — — ja —
Der eigene Ton des Computers neben dem Mikrofon in einer Notiz — — ja —
Sich selbst aktualisieren TestFlight, für Tester — Sparkle —

Das Diktat wird auf dem Gerät mit sherpa-onnx erkannt; das Sprachmodell kommt von der Instanz, wenn zum ersten Mal jemand diktiert (Sprachmodell).

Weiter

  • mobile/README.md — die App bauen und an ihr arbeiten, die Desktop-Builds, die Firebase-Konfiguration
  • spec/27-mobile-app.md — was die App ist, was sie nicht ist, was sie nie tun darf
  • Betrieb — Push, App-Links, das Sprachmodell

Häufige Fragen

Gibt es die covey-App im App Store oder bei Google Play?

Noch nicht. Der App-Dialog der Weboberfläche sagt das für beide. Jedes Release lädt den iPhone-Build zu App Store Connect hoch, wo TestFlight ihn den internen Testern des Projekts gibt; zur Prüfung eingereicht wird nichts. Einen Android-Build veröffentlicht das Release nicht. Die Mac- und die Windows-App hängen an jedem GitHub-Release.

Wie verbindet sich die App mit meiner Instanz?

Durch Koppeln: Die Weboberfläche zeigt einen QR-Code, der einmal und fünf Minuten lang gilt, die App scannt ihn und tauscht ihn gegen einen API-Schlüssel, benannt nach dem Gerät. Auf einem Desktop öffnet derselbe Code die App über einen covey://-Link. Die Instanz muss über HTTPS erreichbar sein.

Warum zeigt die Windows-App keine Mitteilungen?

Die Mac-App zeigt sie selbst an, solange sie läuft, mit macOS-eigenen Schnittstellen; für Windows gibt es dazu noch kein Gegenstück, und einen Desktop erreicht kein Push-Dienst. Telefone bekommen ihre Mitteilungen über Firebase Cloud Messaging.