velum-raycast/README.md

Velum Raycast Extension

Raycast-Extension für PII-sichere Text-Workflows mit Velum: Klarnamen werden lokal in Platzhalter überführt, bevor Text an externe KI-Modelle (Raycast AI), Übersetzer oder andere Tools weitergegeben wird. Originalwerte werden anschließend lokal anhand der Velum-Sitzungs-Zuordnung wiederhergestellt.

Konfiguration

Alle Werte sind in den Raycast-Einstellungen pro Extension einstellbar.

Velum & Authentik (Pflicht):

• Velum Basis-URL — z. B. https://velum.example.com
• Authentik Token-URL — z. B. https://auth.example.com/application/o/token/
• OAuth Client-ID
• Dienstkonto-Benutzername
• Dienstkonto App-Passwort (gespeichert als Raycast-Passwort-Preference)
• OAuth Scope — optional, Standard profile

Verhalten:

• Standard-Sitzungsmodus — Aktive Sitzung wiederverwenden (Default), Neue Sitzung pro Anfrage, Tagessitzung
• Ausgabe der Schnellbefehle — In die Zwischenablage kopieren (Default) oder Am Cursor einfügen
• Eigener Name — Default-Signatur für AI-generierte Email-Antworten, im Antwort-Befehl pro Aufruf überschreibbar

Das KI-Modell ist keine Preference: jeder AI-Befehl zeigt ein KI-Modell-Dropdown mit dem aktuellen Modell-Katalog aus src/ai.ts. Die Auswahl wird in LocalStorage (velum.ai.last-model) persistiert und ist beim nächsten Aufruf in jedem AI-Befehl vorausgewählt.

• Maximale Anzahl gespeicherter Sitzungen — älteste werden geprunt (Default 20)
• Raycast nach Kopieren/Einfügen schließen — Auto-Close und Pop-To-Root nach AI-Workflow-Abschluss (Default an)

Access-Tokens und Velum-Sitzungen liegen im Raycast-LocalStorage.

Befehle

AI-Workflows (Pseudonymisieren → Raycast AI → Wiederherstellen)

Jeder AI-Befehl pseudonymisiert die Eingabe via Velum, zeigt einen Confirm-Schritt (pseudonymisierter Text editierbar bevor er an die KI geht), streamt die AI-Antwort und ersetzt zum Schluss lokal alle Platzhalter mit den Originalen. Default-Output ist Rich Text (HTML, via osascript ans System-Pasteboard — siehe Raycast 2.0 Beta unten); zusätzlich gibt es eine Markdown-Copy-Action und eine Paste-Action.

• Email-Konversation zusammenfassen — strukturierte Markdown-Zusammenfassung eines Mailverlaufs (Teilnehmer, Anliegen, Verlauf, Action Items). HTML-Copy für Mail/Outlook.
• Email-Antwort generieren — verfasst eine deutsche Antwort auf einen markierten Mailverlauf, mit anpassbarer Anrede, Schluss, Tonalität und optionalem Hinweis auf den AI-Ursprung. Nutzt OAuth-Personen-Platzhalter aus dem Verlauf.
• Briefing aus Notizen — strukturiertes Briefing (Kontext, Teilnehmer, Entscheidungen, Action Items, Offene Punkte) aus Notizen, Stichpunkten oder Meeting-Transkripten.
• Action Items extrahieren — Markdown-Tabelle (Aufgabe / Verantwortlich / Deadline / Status) aus Transkripten, Threads oder Notizen.
• Strukturierte Daten extrahieren — JSON oder Markdown-Tabelle aus Freitext, gemäß einem frei beschriebenen Schema.
• Projektstatusbericht erstellen — Steering-Update für den Lenkungsausschuss aus Rohnotizen: Status (Ampel), Fortschritt, Top-Risiken, Entscheidung, nächste Schritte, GF-Summary. Triggerphrasen in den zusätzlichen Anweisungen: „Mach mir auch eine GF-Mail dazu.", „Wo sind blinde Flecken?", „Kürzer."

Pseudonymisieren

• Text pseudonymisieren (View) — Text manuell eingeben, Sitzung und Entitätstypen wählen, Mapping inspizieren.
• Markierten Text pseudonymisieren (No-View) — Schnellbefehl: aktuelle Selektion wird pseudonymisiert und je nach Preference kopiert oder eingefügt.
• Zwischenablage pseudonymisieren (No-View) — analog für den Zwischenablage-Inhalt.

Wiederherstellen

• Text wiederherstellen (View) — Platzhalter-Text und Sitzung wählen, Originale per Velum oder lokal einsetzen.
• Markierten Text wiederherstellen (No-View) — Selektion mit der aktiven Sitzung restaurieren.
• Zwischenablage wiederherstellen (No-View) — analog für die Zwischenablage.

Sitzungen

• Sitzungen verwalten — Sitzungen anlegen, aktivieren, ansehen, leeren oder löschen. Zeigt das Mapping je Sitzung als Markdown-Tabelle.

Sitzungen

Eine Sitzung ist eine wachsende Velum-Zuordnung zwischen Platzhaltern (<PERSON_1>, <ORG_2>, …) und Originalwerten. Welche Sitzung ein Schnellbefehl benutzt, regelt der Sitzungsmodus:

• Aktive Sitzung wiederverwenden — Konsistenz über mehrere Anfragen, ideal für längere Korrespondenzen.
• Neue Sitzung pro Anfrage — vollständige Isolation, jede Anfrage bekommt frische Platzhalter.
• Tagessitzung — eine Sitzung pro Tag, ein Kompromiss aus Konsistenz und Isolation.

Die View-Befehle bieten zusätzlich eine explizite Sitzungs-Auswahl plus eine Neue Sitzung-Option.

Raycast 2.0 Beta

Die Extension läuft auf der stabilen Raycast-Version sowie der 2.0 Beta. Für die 2.0 Beta sind drei Workarounds in src/selection.ts und src/ai-views.tsx enthalten:

• Selektion erfassen — getSelectedText() braucht in 2.0 Beta einen vorangestellten Clipboard.clear()-Trigger plus einen readText-Fallback für Outlook und ähnliche Electron-Apps. Der Helper getSelectedTextSafely deckt das ab.
• Rich Text Copy — Clipboard.copy({ html, text }) schreibt in 2.0 Beta nur Plain Text. copyRichText shellt aus zu osascript -l JavaScript und setzt public.html + public.utf8-plain-text direkt am NSPasteboard, sodass beim Einfügen in Word/Outlook eine echte gerenderte Tabelle landet.
• Pop-To-Root nach Abschluss — nach Copy/Paste wird mit closeMainWindow({ popToRootType: PopToRootType.Immediate }) der Navigations-Stack geleert, damit beim nächsten Raycast-Öffnen nicht das alte Result-View wieder hochkommt. Per Preference Raycast nach Kopieren/Einfügen schließen abschaltbar.

Entwicklung

npm install
npm run dev    # ray develop — live reload, lädt die Extension in den lokalen Raycast
npm run lint
npm run build  # ray build -e dist

Voraussetzungen: macOS, Node 22+, Raycast (Pro für die AI-Befehle).