Praxisleitfaden für die Univer-Workspace-Bereitstellung: Gemeinsame Bearbeitung von Bürodokumenten mit KI

Praxisleitfaden für die Univer-Workspace-Bereitstellung: Gemeinsame Bearbeitung von Bürodokumenten mit KI

Projektübersicht

Die kollaborative Bearbeitung von Bürodokumenten war schon immer ein Schmerzpunkt in der Teamarbeit, insbesondere jetzt, wo KI-Agenten beginnen, sich an der Inhaltserstellung zu beteiligen. Wie KI Dokumente sicher und kontrollierbar ändern kann, ist zu einem neuen Problem geworden. Univer Workspace wurde genau für dieses Szenario entwickelt: Es ist ein unabhängig bereitstellbarer Open-Source-Büroarbeitsbereich, der es dir und KI-Agenten ermöglicht, auf derselben Plattform gemeinsam mit Sheet, Doc, Slide, Base und Board zu arbeiten.

Sein zentrales Designkonzept ist beachtenswert. Der Workspace besteht aus vier Teilen: Browser, Server, Agent und CLI:

  • Browser bietet die direkte Bearbeitungs- und Kollaborationsoberfläche und ist der Bedieneinstieg für Menschen;
  • Server ist die einzige Autorität und verantwortlich für Identitätsauthentifizierung, Berechtigungsverwaltung und Dokumentspeicherung;
  • Agent ist eine lokale Webanwendung basierend auf DSH, die Dialog, Dokumentvorschau und Änderungsprüfung zusammenführt;
  • CLI bietet KI-Agenten einen strukturierten Automatisierungseinstieg, mit dem Dokumente im Terminal geladen, geändert und überprüft werden können.

Das herausragendste Mechanismus ist der Worktree. Bevor der Agent Änderungen vornimmt, erstellt das System zunächst einen isolierten Arbeitsbaum, in dem der Agent frei bearbeitet und überprüft. Sobald der Entwurf fertig ist, wird er einem Menschen zur Prüfung vorgelegt, und erst nach Genehmigung wird er in den Hauptzweig zusammengeführt. So wird sichergestellt, dass zwischenzeitliche Änderungen die freigegebenen Inhalte nicht verschmutzen, und der Mensch behält immer die endgültige Entscheidungsgewalt.

Kernabhängigkeiten und Umgebung

Stelle vor dem Start sicher, dass dein Computer diese Grundumgebung bereitstellt:

  • Node.js 24+: Der Server und die Frontend des Workspace basieren auf modernem JavaScript und benötigen Node 24 oder höher.
  • pnpm 11: Das Repository verwendet pnpm zur Verwaltung der Abhängigkeiten; die Versionsanforderung ist 11.x. Es wird empfohlen, einfach corepack enable auszuführen.
  • Docker: Wenn du den Weg der Container-Bereitstellung gehst, wird Docker benötigt, um Datenbank- und Dateispeicherdienste auszuführen. Für einen schnellen lokalen Test kannst du zuerst das Standard-SQLite verwenden.
  • Modellservice-Anmeldeinformationen: Wenn du das Sprachmodell für den KI-Agenten konfigurierst, musst du die API-Adresse und den Schlüssel des Modellservices bereitstellen, z. B. DEEPSEEK_API_KEY von DeepSeek.
  • Workspace-Konto: Der Zugriff auf den Workspace erfordert eine Anmeldung; die Passwortregistrierung ist standardmäßig aktiviert.

Projektstrukturbaum

Nach dem Klonen des Repositorys siehst du eine Verzeichnisstruktur wie diese:

apps/workspace                 Workspace-Browser, Server, HTTP-Vertrag und Bereitstellungsanwendung
apps/cli                       Remote-Workspace-Automatisierungsanwendung für Agenten
apps/agent                     Workspace-Agent-Anwendung für Dokumentdialoge und Worktree-Überprüfung
packages/client-core           Private, von Node gehostete Fähigkeiten des Workspace-Agent-Clients
packages/reference-provider    Private Referenz-Unit-Policy, die nur im Browser verwendet wird
packages/dsh-univer-workspace-plugin        Workspace-Fähigkeiten und Browser-UI des Workspace-Agents
packages/dsh-univer-workspace-skin-plugin   Visuelles Skin des Workspace-Agents
scripts                        SDK-Version und lokale CLI-Veröffentlichungswerkzeuge

apps/workspace ist der Kern und enthält das Browser-Frontend, das Server-Backend und den API-Vertrag. apps/cli ist das Befehlszeilentool für KI-Agenten, und apps/agent ist die Desktop-Dialogoberfläche.

Schritt-für-Schritt-Anleitung

1. Quellcode und Umgebung vorbereiten

Klonge das Repository zuerst lokal, installiere Abhängigkeiten und kopiere die Beispiel-Umgebungsvariablen:

git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
pnpm install
cp apps/workspace/.env.example apps/workspace/.env

Die Standardkonfiguration verwendet SQLite und lokalen Dateispeicher und ist sofort einsatzbereit. Wenn du in einer Produktionsumgebung bereitstellen möchtest, ändere die Datenbank- und Speicherkonfigurationen in apps/workspace/.env nach Bedarf.

2. Workspace-Dienst starten

Starte den Backend-Server; er wird unter http://127.0.0.1:3020 ausgeführt:

pnpm workspace:dev:server

Starte in einem anderen Terminal den Frontend-Browser-Entwicklungsserver:

pnpm workspace:dev:web

Öffne jetzt http://127.0.0.1:5173. Vite wird API- und WebSocket-Datenverkehr automatisch an den Server auf Port 3020 weiterleiten. Registriere ein Konto mit Passwort, melde dich an und du hast einen bearbeitbaren Workspace.

3. KI-Assistenten und Modellservice verbinden

Damit die KI Dokumente für dich bearbeiten kann, sind zwei separate Verbindungen erforderlich: eine sind die Workspace-Anmeldeinformationen, damit die KI auf deine Dokumente zugreifen kann; die andere sind die Modellservice-Anmeldeinformationen, damit die KI ein „Gehirn“ zum Denken hat.

Zum Modellservice. Die Modelleinstellungen des Workspace-Agents sind lokaler Maschinenzustand und nicht an Workspace-Benutzer gebunden. Du kannst sie direkt über Umgebungsvariablen injizieren. Führe vor dem Start des Agents aus:

export DEEPSEEK_API_KEY=<your-api-key>

Wenn du mehr Auswahl oder flexiblere Preise für Modellservices wünschst, kannst du dich Defapi ansehen. Defapi ist ein aggregierter Modell-Gateway, das Modellservices zum halben offiziellen Preis anbietet und gängige Protokolle wie v1/chat/completions, v1/messages und v1beta/models/ unterstützt. Nachdem du die API-Root-Adresse und die Modell-ID von der Plattform erhalten hast, kannst du sie auf die gleiche Weise über Umgebungsvariablen injizieren. Beachte, dass dies eine externe Client-Konfiguration ist und keine integrierte Workspace-Funktion.

Dann den OAuth-Rückruf registrieren. Der Workspace-Agent verwendet die Browser-OAuth-Anmeldung. Die offizielle Dokumentation empfiehlt, in apps/agent/README.md nach Installationsanweisungen zu suchen. Bei der Installation des Agents gibt der lokale Starter die vollständige Token-URL aus; du musst die Anwendungsregistrierung und Rückrufkonfiguration abschließen.

4. Workspace-Agent installieren und starten

Der Agent ist eine lokale Webanwendung basierend auf DSH; die Installationsschritte findest du in apps/agent/README.md. Nach der Installation starte den Agent. Er führt dich durch die Auswahl oder den Start deines eigenen Workspace-Dienstes, die Registrierung des OAuth-Rückrufs und öffnet dann die Anmeldeseite.

Nach der Anmeldung kannst du in der Dialogoberfläche des Agents mit @ Dateien im Workspace referenzieren. Der Agent liest den Dateiinhalt und nimmt Änderungen vor.

5. Bürodokumentaufgaben ausführen

Jetzt lassen wir den Agent eine Tabelle ändern. Gib im Dialog ein:

Bitte schaue dir das Sheet @Verkaufsdaten an und fasse die Verkaufszahlen für jedes Quartal 2024 in einem neuen Sheet zusammen und kennzeichne die Wachstumsrate.

Der Agent erstellt einen neuen Worktree und führt darin Lese-, Berechnungs- und Schreiboperationen aus. Dieser Prozess beeinflusst die Originaldaten im Hauptzweig nicht.

6. Ergebnisse prüfen und Zusammenführung genehmigen

Nachdem der Agent Änderungen abgeschlossen hat, wechselt der Worktree in den Zustand „Ready“. Kehre zur Prüfoberfläche im Browser oder im Agent zurück, wo du Folgendes siehst:

  • Vergleichsansicht zwischen Agent-Entwurf und Hauptzweig
  • Geänderte Zellen, neu hinzugefügte Sheets

Nach sorgfältiger Prüfung der Daten klicke auf Zusammenführen. Erst dann werden die Änderungen tatsächlich in den Hauptzweig übernommen und alle Mitwirkenden sehen die Aktualisierungen. Wenn Probleme gefunden werden, kannst du Erneut öffnen markieren, damit der Agent die Änderungen fortsetzen kann.

Hier wird ein alternativer Weg über die CLI angeboten. Am Beispiel von Claude Code: Wenn univer-workspace-cli in deiner Agent-Umgebung installiert ist, kannst du so vorgehen:

npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw config set workspace.origin http://127.0.0.1:3020
uvw auth login          # nach Browserbestätigung
uvw auth login --complete
uvw pr list -R <owner>/<slug>

Die CLI verwaltet Worktrees wie PRs. Kopiere die Worktree-ID, die von uvw pr view <n> -R <owner>/<slug> --json id zurückgegeben wird, um die Inhalte mit dem Inhaltbefehl zu überprüfen.

Häufige Probleme beheben

Meldung beim Start: Node.js-Version zu niedrig

Workspace erfordert Node.js 24+; überprüfe die Version mit node -v. Wenn die Version nicht ausreicht, installiere die LTS-Version mit nvm.

pnpm install hängt oder meldet Fehler

Das Repository verwendet fest pnpm 11.24.0. Führe zuerst corepack enable aus und dann die Installation. Wenn Netzwerkprobleme zu Fehlern führen, setze einen Spiegel und versuche es erneut.

Im Browser ist auf Port 5173 kein Inhalt sichtbar

Stelle sicher, dass beide Terminals noch laufen: pnpm workspace:dev:server und pnpm workspace:dev:web. Die Vite-Proxy benötigt einen erfolgreich gestarteten Server.

OAuth-Anmeldung zeigt: Rückrufadresse stimmt nicht überein

Überprüfe, ob die Rückrufadresse in der Agent-Konfiguration mit der Autorisierungs-Rückrufliste des Workspace übereinstimmt. Bei lokaler Entwicklung ist der Rückruf normalerweise http://127.0.0.1:<agent-port>/oauth/callback.

Agent-Dialog meldet: Modellanmeldeinformationen nicht gefunden

Modellanmeldeinformationen sind lokaler Zustand und folgen nicht dem Workspace-Benutzer. Stelle sicher, dass vor dem Start des Agents DEEPSEEK_API_KEY exportiert oder das Modell über die DSH Models-Seite konfiguriert wurde. Verschiedene Agent-Prozesse müssen separat konfiguriert werden.

Meldung beim Zusammenführen: Keine Berechtigung

Das Zusammenführen eines Worktrees erfordert Dokumentbearbeitungsrechte. Überprüfe im Browser, ob das aktuelle Konto Schreibrechte für den entsprechenden Ordner oder die Datei hat. Wenn das Dokument in einem Team-Space liegt, muss der Besitzer oder Administrator Berechtigungen zuweisen.

Weiterführende Lektüre / Fortgeschrittene Richtungen

Wenn du Univer Workspace intensiver nutzen möchtest, sind diese Richtungen eine Erkundung wert:

  • CLI-Fortgeschrittene Nutzung: Lies apps/cli/README.md und erfahre, wie du mit uvw execute eigene Skripte ausführst, mit uvw inspect die Dokumentstruktur überprüfst und mit uvw screenshot Screenshots zur Layout-Verifikation rendert.
  • MCP-Service-Integration: Workspace bietet einen Remote-MCP-Dienst. Konfiguriere https://<dein-workspace>/mcp in Claude, Cursor oder VS Code, damit diese KI-Assistenten direkt auf deine Dokumente zugreifen können.
  • HTML-View-Mini-App: Der Agent kann Webanwendungen erstellen, die an Berichtsdaten gebunden sind. Kennzahlen, Diagramme und Steuerelemente sind bidirektional mit Zellen verknüpft – ideal für Entscheidungs-Dashboards.
  • Docker-Bereitstellung: Wechsle zu PostgreSQL + S3-Speicher, folge apps/workspace/README.md für die Container-Bereitstellung, die automatische Upgrades und Datenmigrationen unterstützt.

Starte mit dem Aufbau eines Workspace und lass die KI deinen ersten Monatsbericht erstellen. Du wirst das Gefühl der Kontrolle durch den Worktree-Überprüfungsmechanismus erleben.