108 lines
9.2 KiB
Markdown
108 lines
9.2 KiB
Markdown
# Velum Raycast Extension
|
|
|
|
Raycast-Extension für PII-sichere Text- und Projekt-Workflows mit Velum: Inhalte werden über die konfigurierte Velum-API pseudonymisiert, bevor sie an externe KI-Modelle oder andere Tools weitergegeben werden. Die Velum-API sollte für vertrauliche Kundendaten in einer dafür geeigneten Umgebung betrieben werden.
|
|
|
|
## Projektdateien
|
|
|
|
`Projektdateien pseudonymisieren` übernimmt einen im Finder ausgewählten Ordner. Ohne Auswahl versucht der Befehl, den geöffneten Finder-Ordner zu übernehmen; andernfalls steht die Ordnerauswahl bereit. Danach werden geeignete Text-, DOCX-, XLSX-, PPTX- und PDF-Dateien ausgewählt. Alle erkannten Treffer einschließlich Datei- und Ordnernamen erscheinen mit Kontext und müssen vor dem Erstellen der Kopien geprüft werden. Personen, Orte und Organisationen sind zunächst abgewählt; explizite Projektbegriffe und strukturierte Treffer sind vorausgewählt. Erst `Kopien erstellen` schreibt Dateien in den Raycast-Support-Bereich außerhalb des Projektordners. PDF wird dabei als DOCX ausgegeben.
|
|
|
|
Projektbegriffe werden zeilenweise als `BEGRIFF: KundenSuite` oder `PERSON: Max Mustermann` eingegeben, nur für dieses Projekt gespeichert und mit `force_masks` pro API-Aufruf übertragen. Die globale Velum-Regelliste bleibt unverändert. Eine neue Projektbearbeitung übernimmt die Zuordnung des letzten Projektstands, sodass Platzhalter konsistent bleiben.
|
|
|
|
`Projektdateien rückübersetzen` wählt einen Projektstand und einzelne Dateien und erstellt Klartext-Kopien unter `~/Downloads/Velum`. Der Quellordner bleibt unverändert. Die neue Projektfunktion benötigt eine Velum-API mit `/api/project-capabilities`, Trefferprüfung für Dokumente, projektbezogenen `force_masks` und `/api/depseudonymize-document`.
|
|
|
|
### Einmalige Übernahme aus KI Datenschutz
|
|
|
|
Velum enthält **keinen** Laufzeit-Zugriff auf die frühere Extension. Das eigenständige Skript `tools/migrate-ki-datenschutz.mjs` wandelt einen bereits anonymisierten KI-Datenschutz-Projektordner samt seiner eingefrorenen Variante-Tabelle in einen Velum-Projektstand um. Es verändert weder den alten Ordner noch die alte Tabelle. Der neue Stand erscheint anschließend unter `Projektdateien rückübersetzen`; Begriffe nur für dieses Projekt werden als Velum-Projektregeln übernommen. Alle Inhalte bleiben während der Migration lokal und werden nicht an eine API gesendet. Das Skript protokolliert nur Zahlen, keine Werte oder Dateinamen.
|
|
|
|
1. In Raycast `Migrationsziel anzeigen` öffnen und den Velum-Datenordner kopieren.
|
|
2. Den alten Projektordner und die zugehörige Datei `projects/<Projekt-ID>.json` aus dem Datenordner von KI Datenschutz angeben. Zuerst ohne `--apply` prüfen:
|
|
|
|
```bash
|
|
node tools/migrate-ki-datenschutz.mjs --project "/Pfad/zum/Projekt" --manifest "/Pfad/zu/projects/abcdef0123456789.json" --target-support "/kopierter/Velum-Datenordner"
|
|
```
|
|
|
|
3. Denselben Befehl mit `--apply` ausführen. Danach den neuen Stand in Velum öffnen und den Klartext-Export mit einem Testdokument prüfen.
|
|
|
|
Das Skript übernimmt Text- und Codedateien. Binäre Dateien und bisher nicht anonymisierte Office/PDF-Dateien werden gezählt und ausgelassen; sie müssen im neuen Projektdateien-Befehl geprüft werden. Platzhalter, die in technischen Bezeichnern kleben, behalten ein eigenes Rückübersetzungsverhalten. Wenn die alte Variante-Tabelle mehrere Klartext-Schreibweisen für denselben Platzhalter enthält, ist die exakte frühere Schreibweise nicht mehr rekonstruierbar; das Skript verwendet dieselbe kontextabhängige Kanonisierung wie der alte Klartext-Export. Die alte Extension kann nach erfolgreicher Prüfung entfernt werden.
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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).
|