Zum Inhalt

Übersicht

Repository

Repository Issues

Allgemeine Informationen

Kurzbeschreibung des Add-ins

Behörden-KlarText ermöglicht es, Texte mithilfe von Large Language Models (LLMs) zu optimieren. Bei diesem Add-In handelt es sich um eine Implementierung, die es ermöglicht, markierten Text durch eine Schnittstelle in besser verständlichen und klareren Text zu überführen.

Welche Probleme löst es?

Viele Dokumente des täglichen Bedarfes (Verträge, Kommunikation mit Behörden usw.) beinhalten oft schwer verständlichen Text. Diese Software ermöglicht die Vereinfachung solcher Textblöcke in verständliche Sprache.

Für welche Office-App ist es gedacht?

Dieses Add-in ist für Windows Installationen von Microsoft 365 entwickelt worden.

Prinzipiell sollte es auch mit Microsoft Office 2016 (und neuer) kompatibel sein. Sie sollten aber davon ausgehen, dass kleinere Anpassungen notwendig sein werden und die Shortcuts eventuell nicht verfügbar sind. Beachten Sie hierbei bitte die Lizenzbestimmungen der Office JavaScript API.

Verfahren

Im Folgenden werden die wichtigsten Schritte im Code dargestellt. Relevant sind vor allem die Dateien index.html und main.js sowie Popup.html und popup.js.

  1. Die Sidebar wird über die Dateien index.html und main.js definiert:

    • Ein Backend-Health-Check wird durchgeführt und gegebenenfalls ein Status als Hinweis angezeigt.
    • Die maximale Zeichenanzahl für die Textauswahl wird aus dem Backend übernommen.
    • Der markierte Text wird an das Optimierungs-Popup weitergereicht.
    • Der optimierte Text wird aus dem Popup in das Dokument eingefügt.

  2. Das Popup wird über die Dateien Popup.html und popup.js definiert:

    • Text zum Optimieren wird empfangen.
    • Text wird zum Optimieren an das Backend gesendet.
    • KI-optimierter Text wird zurück an main.js geschickt.
    • Text aus dem Original-Textfeld wird an main.js geschickt.

  3. Popup-info.html

    • Statische Datei mit Hinweisen zu den Optimierungskriterien.

Bauen

Build & Deployment

Überblick

Das Web-Add-In wird als Container ausgeliefert. Da Microsoft Office Add-Ins zwingend HTTPS voraussetzen, muss für eine Integration in Word eine SSL-gesicherte URL bereitgestellt werden. Im Folgenden wird für Testzwecke das Deployment mit Docker und einem selbst erstellten Zertifikat beschrieben.

1. Container bauen

Erstellen Sie das Docker-Image für das Web-Add-In:

docker build -t vbg-klartext/web-add-in .

2. Zertifikate für lokale Entwicklung (WSL2, Windows)

Schritt A: Zertifikate in WSL2 oder Linux erstellen

Verwenden Sie mkcert, um Zertifikate zu erstellen, und stellen Sie sicher, dass der Key für Docker lesbar ist:

apt install mkcert
mkdir -p certs
mkcert -key-file certs/localhost.key -cert-file certs/localhost.crt localhost 127.0.0.1 ::1
chmod 644 certs/localhost.key

Schritt B: Zertifikat unter Windows vertrauen

Falls das Add-In nicht korrekt geladen wird, müssen Sie möglicherweise das Zertifikat unter Windows als vertrauenswürdig hinzufügen. Dies ist erforderlich, wenn Sie Word unter Windows verwenden (nicht im Webbrowser) und die in WSL2 erstellte "Certification Authority" (CA) noch nicht von Windows akzeptiert wird.

  1. CA-Pfad finden: 
    mkcert -CAROOT
  2. Ordner in Windows öffnen: Navigieren Sie im Windows-Explorer zu dem ausgegebenen Pfad (z. B. \\wsl$\Ubuntu\home\username\.local\share\mkcert).
  3. Zertifikat installieren:
  4. Kopieren Sie rootCA.pem auf Ihren Windows-Desktop und benennen Sie die Datei in rootCA.crt um.
  5. Doppelklick auf rootCA.crt -> Zertifikat installieren...
  6. Wählen Sie Aktueller Benutzer -> Weiter.
  7. Wählen Sie Alle Zertifikate in folgendem Speicher speichern.
  8. Klicken Sie auf Durchsuchen... und wählen Sie Vertrauenswürdige Stammzertifizierungsstellen.
  9. Klicken Sie auf OK -> Weiter -> Fertig stellen.

3. Container starten

Starten Sie den Container mit eingebundenen Zertifikaten und aktivierter SSL-Unterstützung. Der Container benötigt Zugriff auf das Backend (hier über das externe Netzwerk vbg_net).

docker run --rm -p 9999:9999 \
  -e ADDIN_URL=https://localhost:9999 \
  -e USE_SSL=true \
  -v $(pwd)/certs:/etc/nginx/certs:ro \
  --network vbg_net \
  vbg-klartext/web-add-in

4. Konfiguration & Umgebungsvariablen

Das Verhalten des Containers wird über Umgebungsvariablen gesteuert:

Variable Beschreibung Wichtig
ADDIN_URL Die externe Basis-URL des Add-Ins. Muss auf die externe HTTPS-URL zeigen (z.B. https://localhost:9999). Diese URL wird beim Start in die manifest.xml geschrieben.
USE_SSL Aktiviert den SSL-Modus im Nginx. Setzen Sie true, um HTTPS zu aktivieren.

Hinweise:

  • Der nginx im Container erwartet das Backend unter http://backend:8000 (Container-interner Hostname).
  • Das Manifest ist nach dem Start unter <ADDIN_URL>/manifest.xml abrufbar. Laden Sie es für das Test-Deployment herunter.
  • In der aktuellen SSL-Nginx-Konfiguration wird Streaming gepuffert. Dies kann dazu führen, dass Echtzeit-Streaming nicht korrekt funktioniert und der optimierte Text als Ganzes angezeigt wird. Dadurch kann es etwas dauern, bis die Antwort angezeigt wird.

5. Bereitstellung in Microsoft 365

Für den produktiven Einsatz oder weitreichende Tests kann das Add-In im Microsoft 365 Admin Center registriert werden. Das Manifest kann dort:

  • direkt als Datei hochgeladen werden,
  • oder per HTTPS-URL referenziert werden (z. B. https://mein-server.de/manifest.xml).

Sideloading (optional)

Sideloading ist für schnelle lokale Tests gedacht. Microsoft empfiehlt es nicht für produktive Rollouts.

Diese Methode kann direkt in Word im Browser durchgeführt werden. Es wurde mit Microsoft Edge getestet. Weitere Informationen finden Sie unter Microsoft-Dokumentation.

  1. Öffnen Sie Word in ihrem Browser und ein Dokument.
  2. Wählen Sie Start > Add-ins und dann Weitere Einstellungen oder Weitere Add-Ins.
  3. Im Dialogfeld "Office-Add-ins" wählen Sie Mein Add-in hochladen.
  4. Navigieren Sie zur Manifestdatei des Add-ins und wählen Sie Hochladen.
  5. Das Add-In sollte jetzt im Menüband erscheinen.

Das Add-In kann auch in Word auf dem Desktop geladen werden. Dazu muss das manifest.xml in einem freigegebenen Ordner abgelegt werden:

  1. Öffnen Sie Datei > Optionen.
  2. Navigieren Sie zu Trust Center > Einstellungen für das Trust Center.
  3. Wählen Sie Kataloge vertrauenswürdiger Add-Ins.
  4. Fügen Sie den Netzwerkpfad des freigegebenen Ordners hinzu, in dem sich das Manifest befindet, und aktivieren Sie die Option Im Menü anzeigen.
  5. Starten Sie Word neu.
  6. Wählen Sie Add-Ins > Weitere Add-Ins > geteilter Ordner und dann das Add-In Behörden-KlarText aus.
  7. Das Add-In sollte jetzt im Menüband erscheinen.

Hinweis: Tastenkürzel sind bei dieser Methode nicht verfügbar.

pre-commit

Die CI-Pipeline führt bei jedem Push den Job "pre-commit" mit den in .pre-commit-config.yaml hinterlegten Hooks durch. Um ein Failen des Jobs und unnötige Commits zu vermeiden, sollte man pre-commit lokal installieren. So werden etwaige Fehler, die durch Linter und Formatter entdeckt werden, bereits vor dem push offenbart. Dafür muss pip installiert sein. Führen Sie folgende Befehle einmalig in der Konsole aus:

pip install pre-commit
pre-commit install

Wie der Name vermuten lässt, wird der Check vor jedem Commit ausgeführt, bevor Fehler in das Repository gelangen können.

Für das Frontend wird Biome als Linter und Formatter in den pre-commit hooks verwendet. (Hier)[https://biomejs.dev/reference/cli/] sind einige nützliche Befehle zu finden.

Entwicklung

Entwicklungsumgebung unter Windows (VS Code)

Das Add-In kann unter Windows mit VS Code und der Erweiterung Microsoft Office Add-ins Development Kit entwickelt werden.

Voraussetzungen:

  1. Node.js >= 20 Anleitung: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
  2. Microsoft Word (Desktop) ist installiert.

Einrichtung:

  1. Node-Module installieren: 
    npm install
  2. VS-Code-Erweiterung Microsoft Office Add-ins Development Kit installieren.
  3. In VS Code die Erweiterung öffnen und ausführen:
  4. Preview Your Office Add-in
  5. Word Desktop (Edge Chromium)
  6. Add-In in Word testen.

Entwicklung unter Linux (ohne VS-Code-Toolkit)

Diese Methode ist geeignet, wenn kein Windows-Rechner mit dem VS-Code Office Add-ins Development Kit verfügbar ist.

Für Tests können Sie das Add-In lokal hosten und über https://localhost:3000 ausliefern. Word akzeptiert hierfür nur HTTPS, daher werden lokale Zertifikate benötigt.

1) Lokale Zertifikate erzeugen

Verwenden Sie mkcert, um Zertifikate zu erstellen, denen auch der Word-Client vertraut:

mkdir -p certs
mkcert -key-file certs/localhost.key -cert-file certs/localhost.crt localhost 127.0.0.1 ::1

2) webpack.config.js für HTTPS konfigurieren

Passen Sie im Abschnitt devServer die HTTPS-Optionen an, sodass auf die Dateien aus certs/ verwiesen wird:

devServer: {
      headers: {
         "Access-Control-Allow-Origin": "*",
      },
      server: {
         type: "https",
         options:
            {
               key: fs.readFileSync(path.resolve(__dirname, "certs/localhost.key")),
               cert: fs.readFileSync(path.resolve(__dirname, "certs/localhost.crt")),
            },
      },
      port: process.env.npm_package_config_dev_server_port || 3000,
      host: process.env.npm_package_config_dev_server_host || "0.0.0.0",
   },

Stellen Sie außerdem sicher, dass folgende Imports vorhanden sind:

const fs = require("fs");
const path = require("path");

3) Backend-URL setzen

Setzen Sie const urlBackend = "<Ihre-backend_url>" in popup.js und main.js.

4) Dev-Server starten

npm run dev-server
Der Dev-Server ist anschließend unter https://localhost:3000 erreichbar.

Hinweis: Möglicherweise müssen Sie einmalig https://localhost:3000 im Browser öffnen und das Zertifikat akzeptieren, bevor Word die Seite laden kann.

5) Manifest in Word laden

Öffnen Sie Word (z. B. Word 365 im Browser) und laden Sie die manifest.xml über den Add-Ins-Dialog.

Das Manifest finden Sie unter: https://localhost:3000/manifest.xml

Lizenzinformationen

Rechtlicher Hinweis zu Drittanbieter-Komponenten (Microsoft Office.js)

Dieser Quellcode ("Behörden-KlarText") interagiert mit der proprietären Microsoft Office JavaScript API (Office.js).

Technische Einbindung

Das Add-In verweist an mehreren Stellen (insbesondere in HTML-Dateien via <script>-Tags) auf externe Ressourcen der Microsoft Corporation. Die Bibliothek office.js ist nicht physischer Bestandteil dieses Repositories und wird nicht mit diesem Quellcode verteilt oder vervielfältigt.

Die Interaktion erfolgt ausschließlich zur Laufzeit, indem der Client (Browser) des Anwenders die Bibliothek von den Microsoft-Servern (Content Delivery Network - CDN) nachlädt: https://appsforoffice.microsoft.com/lib/1/hosted/office.js

Lizenzbedingungen der Drittkomponente

Die office.js-Bibliothek unterliegt nicht der für dieses Projekt verwendeten Open-Source-Lizenz (Apache License 2.0).

Für die Nutzung, das Laden und die Interaktion mit der office.js-Bibliothek gelten ausschließlich die Microsoft API License Terms. Durch die Nutzung dieses Add-ins akzeptieren Sie neben der Apache-Lizenz für den eigenen Code auch die Bedingungen von Microsoft für die API-Nutzung.

Weitere Informationen: Microsoft API License Terms (Office.js)

Abgrenzung

Wir stellen hiermit klar, dass der in diesem Repository veröffentlichte Code als eigenständiges Werk zu betrachten ist, welches lediglich Schnittstellen zu proprietären Diensten definiert. Es wird kein Eigentum an Microsoft-Code beansprucht oder gewährt.