Univer Workspace: Bereitstellung und KI-Tabellen in der Praxis

Wenn KI-generierte Tabelleninhalte nur im Chatfenster bleiben, brechen spätere Bearbeitung, Zusammenarbeit und Prüfung ab. Univer Workspace bringt Dokumente, Tabellen und KI-Operationen in denselben Arbeitsbereich, lässt den Agent in einem isolierten Worktree Änderungen vornehmen und führt sie nach unserer Prüfung zusammen. Heute setzen wir gemeinsam die lokale Bereitstellung um und lassen den Agent anhand einer Verkaufstabelle Zusammenfassungen und Formeln erzeugen.

Projektübersicht

Univer Workspace ist ein auf dem Univer Office SDK basierender, eigenständig bereitstellbarer Open-Source-Office-Arbeitsbereich. Das zentrale Problem, das es löst: KI-generierte Office-Inhalte müssen manuell in den Editor übertragen werden, und spätere Änderungen lassen sich nur schwer gemeinsam bearbeiten und prüfen.

Das Projekt verbindet die drei Einstiege Browser, Agent und CLI mit demselben Workspace Server, sodass Mensch und KI gemeinsam Sheet, Doc, Slide, Base und Board bearbeiten können. Der Agent arbeitet in einem isolierten Worktree und validiert Änderungen; nur Inhalte, die wir bestätigen, werden in den gemeinsamen trunk übernommen. Du kannst direkt im Workspace Browser bearbeiten oder den Workspace Agent in einem Gespräch neben dem Dokument Inhalte erzeugen lassen und anschließend Tabellenänderungen wie bei einem Code-Review prüfen.

Anwendungsfälle und Voraussetzungen

Ein typischer Anwendungsfall ist die Analyse von Verkaufsdaten. Das Team legt die Verkaufsdetailtabelle in den Workspace, lässt den Agent nach Region zusammenfassen und Formeln erzeugen, und wir prüfen Tabellenänderungen wie bei einem Code-Review.

Vor dem Start sind folgende Vorbereitungen nötig:

  • Du kannst ein Terminal bedienen und JavaScript/TypeScript-Konfigurationen lesen
  • Git ist installiert
  • Node.js 24 oder höher
  • pnpm 11.24.0
  • Ein Modell-API-Key für Agent-Gespräche
  • Chrome/Chromium, wenn Screenshots oder Layoutprüfungen ausgeführt werden sollen

Workspace-Login und Modellanmeldedaten sind zweierlei: Zum Betrachten von Dokumenten sind keine Modell-Anfragen nötig; erst für Gespräche mit dem Agent benötigt man Modellanmeldedaten.

Kernabhängigkeiten und Umgebung

Die .npmrc des Repositorys verweist @univer-cli, @univerjs, @univerjs-pro und @univerjs-labs auf https://insider-npm-registry.univer.work/. Für die Installation muss sowohl diese private Registry als auch die öffentliche npm-Registry erreichbar sein.

Die DSH Runtime wird von packages/dsh-runtime auf @deepseek-ai/[email protected] gepinnt. Der Quellcode steht unter Apache-2.0, aber die Nutzungsbedingungen des Univer SDK entsprechen nicht vollständig der Quellcode-Lizenz: Die integrierten Runtime-Entwicklungsanmeldedaten werden alle 90 Tage rotiert, und das serverseitige Collaboration/Exchange SDK benötigt einen License-Key. Fehlt einer der Werte, wird auf das kostenlose Kontingent herabgestuft.

Projektstruktur

apps/workspace                 Workspace Browser、Server、HTTP 契约与部署应用
apps/agent                     用于文档对话与 Worktree 审查的 Workspace Agent
apps/cli                       面向 Agent 的远程 Workspace 自动化应用
packages/client-core           私有 Node-hosted Workspace Agent Client 能力
packages/dsh-runtime           固定 DSH 运行时版本与依赖图
scripts                        SDK 版本与发布工具

Schritt-für-Schritt-Anleitung

1. Eine feste Version klonen und Abhängigkeiten installieren

Zuerst auf den im Tutorial verwendeten Commit festlegen, damit spätere Änderungen die Befehle nicht beeinflussen.

git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile

Dieser Schritt greift auf die private Registry und die öffentliche npm-Registry zu. Bei eingeschränktem Netzwerk zuerst die FAQ am Ende des Dokuments lesen.

2. Modellzugang konfigurieren

Bevor du den Agent startest, solltest du die Aufgabenteilung von Login und Modellanmeldedaten verstehen. Der Workspace-Login autorisiert nur den Datenzugriff; bei Gesprächen mit dem Agent sendet DSH die Modellanfragen an den von uns konfigurierten Chat-Completions-Endpunkt. Wenn der Agent die Verkaufstabelle analysieren und Formeln erzeugen soll, müssen baseURL, API-Key und model für das Modell vorbereitet sein.

Der DSH-Adapter deepseek-official sendet Anfragen an baseURL + /chat/completions; daher sollte baseURL bis zur Ebene /v1 gesetzt werden und der Pfad nicht doppelt angehängt werden.

Um die Modellkosten zu kontrollieren, kann ein OpenAI-kompatibles Gateway wie Defapi angebunden werden. Defapi bietet einen einheitlichen Modellzugang mit Abrechnung zu etwa der Hälfte des offiziellen Preises; maßgeblich sind die konkreten Modelle und Preise in der Konsole. Auf der Website https://defapi.org gibt es einen klaren Einstieg; sie ist grundsätzlich mit den Protokollen v1/chat/completions, v1/messages, v1beta/models/ kompatibel. Bei der Konfiguration genügt es, baseURL auf die von der Defapi-Konsole angegebene Chat-Completions-Basisadresse zu setzen.

export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true

Die Modell-ID richtet sich nach dem tatsächlich in der Konsole verfügbaren Modellkatalog. Wenn die Standard-Modell-ID von DSH nicht mit der Defapi-Konsole übereinstimmt, kann sie in der Modellliste der DSH-Models-Seite auf eine in der Konsole verfügbare ID geändert werden. In Produktionsumgebungen ist die Models-Seite standardmäßig ausgeblendet und wird erst mit UWH_MODEL_SETTINGS_ENABLED=true angezeigt. Lokal, ohne NODE_ENV=production, ist die native DSH-Models-Seite direkt erreichbar.

3. Workspace-Umgebungskonfiguration erstellen und Agent-OAuth-Client registrieren

Workspace registriert den Agent-OAuth-Client standardmäßig nicht; nur .env.example zu kopieren reicht nicht.

cp apps/workspace/.env.example apps/workspace/.env

Danach apps/workspace/.env bearbeiten und die unkommentierte einzeilige Konfiguration ergänzen:

OAUTH_CLIENTS_JSON={"clients":[{"clientId":"univer-workspace-harness","clientType":"public","requiresConsent":true,"redirectUris":["http://127.0.0.1:3101/auth/oauth/callback"],"scopes":["identity","session"]}]}

Falls OAUTH_CLIENTS_JSON bereits existiert, den obigen Client zum clients-Array hinzufügen und immer nur einen Konfigurationseintrag behalten.

4. Workspace-Server und Browser starten

Server im ersten Terminal starten:

pnpm workspace:dev:server

Browser-Entwicklungsserver im zweiten Terminal starten:

pnpm workspace:dev:web

Öffne http://127.0.0.1:5173, registriere ein lokales Workspace-Konto oder melde dich mit einem bestehenden Konto an. Für die lokale Registrierung ist kein GitHub/Discord-OAuth nötig. Beide Prozesse laufen lassen.

5. DSH Runtime und Agent-Profil erstellen, lokalen Agent starten

Der Agent ist eine lokale Webanwendung; zuerst muss die DSH-Laufzeit aus dem Quellcode zusammengesetzt werden. Die folgenden Befehle bauen client-core, drei Bundles und installieren das Profil in ein isoliertes Verzeichnis.

export UWH_LOCAL_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/univer-workspace-harness"
export UWH_DSH_BOOTSTRAP="$UWH_LOCAL_ROOT/dsh-cli"
export DSH_HOME="$UWH_LOCAL_ROOT/install"
export UWH_DSH_DATA_HOME="$UWH_LOCAL_ROOT/data"
mkdir -p "$UWH_DSH_BOOTSTRAP" "$DSH_HOME/internal-packages"
export UWA_PACKAGES="$(mktemp -d "$DSH_HOME/internal-packages/build.XXXXXX")"

pnpm --dir packages/dsh-runtime install --frozen-lockfile
pnpm --dir packages/dsh-runtime deploy --legacy \
  --filter @univerjs/univer-workspace-dsh-runtime \
  --prod --config.node-linker=hoisted "$UWH_DSH_BOOTSTRAP"
export DSH_BIN="$UWH_DSH_BOOTSTRAP/node_modules/@deepseek-ai/dsh/lib/bin.js"

pnpm --filter @univerjs/univer-workspace-client-core build
pnpm --filter @univerjs/workspace-agent build
pnpm --filter dsh-univer-workspace-plugin build
pnpm --filter dsh-univer-workspace-skin-plugin build
pnpm --filter @univerjs/workspace-agent pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-plugin pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-skin-plugin pack \
  --pack-destination "$UWA_PACKAGES"

export DSH_PLUGINS="file:$UWA_PACKAGES/univerjs-workspace-agent-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-plugin-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-skin-plugin-0.1.0.tgz"
NPM_CONFIG_USERCONFIG="$PWD/.npmrc" ./apps/agent/scripts/build-profile.sh

export UWH_RENDER_PAGE_ROOT="$PWD/packages/client-core/dist/render-runtime"
export UWH_RENDER_BROWSER="${UWH_RENDER_BROWSER:-$(command -v google-chrome || command -v chromium || true)}"

node apps/agent/scripts/start-local.mjs --port 3101 \
  --no-open --trusted-host 127.0.0.1

Der Befehl bleibt im Vordergrund von start-local.mjs; das ist normal. Warte, bis in stderr eine Zeile erscheint, die mit dsh web: beginnt, und kopiere die gesamte URL.

Falls Port 3101 belegt ist, wähle einen eindeutigen Port und passe die redirectUris aus Schritt 3 entsprechend an.

6. Workspace verbinden und OAuth abschließen

Öffne im Browser die vollständige URL, die dsh web: ausgibt; sie enthält ein Einmal-?token=.... DSH setzt ein HttpOnly-Cookie und leitet auf die Root-Adresse weiter.

# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>

Öffne dann in der Agent-Oberfläche Einstellungen → Workspace und trage die lokale Service-Adresse ein:

http://127.0.0.1:5173

Klicke auf „Sign in to Workspace“ und erlaube den Zugriff auf der Workspace-Autorisierungsseite. Workspace leitet zum lokalen Agent-Callback um; der Agent tauscht den Autorisierungscode per PKCE aus. Nach der Rückkehr sollten in der Seitenleiste das Konto und der persönliche Space erscheinen.

Wenn die Verbindungsseite weiter wartet, klicke auf „Check again“ und lasse start-local.mjs weiterlaufen.

7. Beispiel-Verkaufstabelle erstellen und Agent Zusammenfassung und Formeln erzeugen lassen

Öffne in der Seitenleiste „Dateien“, wähle einen persönlichen oder einen Team-Space, erstelle eine neue Tabelle und trage die Verkaufsdetails ein:

日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200

Wechsle zurück zu „Konversationen“, erstelle eine neue Konversation, tippe @ in das Eingabefeld, wähle die gerade erstellte Tabelle und sende dann:

@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。

Nach dem Senden validiert der Agent die Referenzen auf Basis des aktuellen Workspace und schreibt die Änderungen in den Worktree; der gemeinsame trunk wird nicht direkt verändert.

8. Worktree-Änderungen anzeigen, übernehmen oder verwerfen

Öffne den Tab „Worktree“ und suche die laufende Aufgabe. Die Review-Ansicht zeigt standardmäßig „Änderungseffekt“; du kannst zu „Differenz“ wechseln, um hinzugefügte, geänderte und gelöschte Dokumente zu sehen. Wenn das Ergebnis korrekt ist, klicke auf „Übernehmen“; wenn es nicht passt, kannst du es in einen Entwurf umwandeln oder verwerfen. Erst nach dem Übernehmen wird der gemeinsame trunk aktualisiert.

创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk

Wenn der Agent univer_lint oder univer_screenshot ausführt, werden eine zur Version passende statische Rendering-Seite und Chrome/Chromium benötigt. Fehlen UWH_RENDER_PAGE_ROOT oder ein Browser, meldet das Tool einen eindeutigen Vorbedingungsfehler und markiert die visuelle Prüfung nicht als bestanden.

Problembehandlung

1. pnpm install schlägt beim Zugriff auf die private Registry fehl

Die Installation benötigt Zugriff auf die private Registry und auf die öffentliche npm-Registry; beides ist erforderlich. Wenn sie hängen bleibt oder 401 liefert, zuerst prüfen, ob das Netzwerk https://insider-npm-registry.univer.work/ erreichen kann, und dann die Node- und pnpm-Versionen. Die Registry-Zeile in .npmrc nicht entfernen.

2. OAUTH_CLIENT_UNAVAILABLE tritt auf

Der Workspace-Server hat den Agent-OAuth-Client nicht geladen. Prüfe, ob OAUTH_CLIENTS_JSON in apps/workspace/.env univer-workspace-harness enthält, und starte den Server nach Änderungen neu. Nur .env.example zu kopieren registriert diesen Client nicht.

3. INVALID_REDIRECT_URI tritt auf

Die Callback-Adresse muss exakt übereinstimmen. localhost und 127.0.0.1 sind unterschiedliche Registrierungen. Wenn der Agent den Port gewechselt hat, die redirectUris entsprechend anpassen und das Workspace-Backend neu starten. Diese Registrierung steuert den OAuth-Callback und ist keine allgemeine CORS-Freigabe für Port 3101.

4. Aufruf der Root-Adresse liefert 401

Ohne zuerst die vollständige URL mit Token zu öffnen, hat der Browser kein Sitzungs-Cookie. Öffne die vom Starter ausgegebene dsh web:-Adresse erneut, um den Austausch abzuschließen; danach kannst du die Root-Adresse ohne Parameter verwenden. Das Einmal-Token nicht wiederverwenden.

5. Workspace-Login erfolgreich, aber Modellnachrichten schlagen fehl

Der Workspace-OAuth autorisiert nur den Datenzugriff; die Modellanmeldedaten müssen separat konfiguriert werden. Prüfe DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL und die Modell-ID. Bei Defapi als baseURL die von der Konsole angegebene Chat-Completions-Basisadresse eintragen und /chat/completions nicht erneut anhängen.

6. Die Verbindungsseite des Agents wartet weiterhin

Lasse start-local.mjs weiterlaufen. Nach einer Änderung des Verbindungsstatus wird ein Bereitschaftscheck durchgeführt; falls der Kontodienst nicht geladen werden kann, prüfe die Starter-Logs. Wenn die Autorisierungsanfrage abgelaufen ist, melde dich unter Einstellungen → Workspace neu an. Dieser Ablauf verwendet Browser-OAuth; es muss kein Gerätecode eingegeben werden.

7. Screenshot-/Layoutprüfung meldet Vorbedingungsfehler

univer_lint und univer_screenshot benötigen UWH_RENDER_PAGE_ROOT, das auf statische Rendering-Seiten zeigt, und UWH_RENDER_BROWSER, das auf ein kompatibles Chrome/Chromium zeigt. Ist kein Browser vorhanden, setze UWH_RENDER_BROWSER auf den Pfad zur ausführbaren Datei und starte den Agent.

Weiterführendes / Fortgeschrittene Ansätze

  • Docker-Bereitstellung: Workspace bietet eine eigenständig bereitstellbare Anwendung. Gemäß der offiziellen Anwendungsanleitung kann ein Image erstellt und Server, Browser sowie Speicher auf einem Server abgelegt werden.
  • CLI-Automatisierung: univer-workspace-cli installieren, in bestehende Agent-Umgebungen wie Claude, Codex, Kimi Work einbinden und mit der CLI Dokumente und Worktrees bearbeiten.
  • MCP-Anbindung: Workspace stellt einen entfernten MCP-Dienst bereit, der Streamable HTTP und OAuth unterstützt. Clients wie Cursor, VS Code und Claude Desktop können sich direkt verbinden.
  • Offizielle Dokumentation und fester Versionsstand: Univer Web SDK-Dokumentation, Server-SDK-Dokumentation, Workspace-Konfigurationsdokumentation. Dieses Tutorial basiert auf c1a5fb3dc9d5951cbf618f76639466feac5da4d7; für spätere Versionen ist die offizielle Dokumentation maßgeblich.