Déploiement pratique d'Univer Workspace : édition collaborative de documents bureautiques assistée par l'IA

Déploiement pratique d'Univer Workspace : édition collaborative de documents bureautiques assistée par l'IA

Présentation du projet

L'édition collaborative de documents bureautiques a toujours été un point douloureux pour le travail d'équipe, surtout lorsque les agents IA commencent à participer à la création de contenu. Comment permettre à l'IA de modifier des documents de manière sûre et contrôlée est devenu un nouveau défi. Univer Workspace a été conçu précisément pour résoudre ce scénario : c'est un espace de travail bureautique open source déployable indépendamment, vous permettant, ainsi qu'à vos agents IA, de traiter ensemble des feuilles de calcul, des documents texte, des présentations, des bases de données et des tableaux blancs sur une même plateforme.

Son principe de conception central mérite d'être souligné. Workspace est composé de quatre parties : Browser, Server, Agent et CLI :

  • Browser fournit l'interface d'édition et de collaboration directe, c'est le point d'entrée pour les humains ;
  • Server est la seule autorité, responsable de l'authentification, de la gestion des permissions et du stockage des documents ;
  • Agent est une application Web locale basée sur DSH, qui regroupe la conversation, l'aperçu des documents et la revue des modifications ;
  • CLI offre aux agents IA une interface d'automatisation structurée, permettant de charger, modifier et valider des documents depuis le terminal.

Le mécanisme le plus remarquable est Worktree. Avant que l'Agent ne modifie quoi que ce soit, le système crée d'abord un arbre de travail isolé. L'Agent y édite et valide librement, puis génère un brouillon prêt à être soumis à la revue humaine. Ce n'est qu'après approbation que les modifications sont fusionnées dans la branche principale. Ainsi, toutes les modifications intermédiaires ne polluent pas le contenu partagé, et les humains gardent toujours le contrôle final.

Dépendances principales et environnement

Avant de commencer, assurez-vous que votre ordinateur dispose de l'environnement de base suivant :

  • Node.js 24+ : le serveur et le frontend de Workspace sont basés sur du JavaScript moderne, nécessitant Node 24 ou une version ultérieure.
  • pnpm 11 : le dépôt utilise pnpm pour gérer les dépendances, version 11.x requise. Il est recommandé d'utiliser directement corepack enable pour l'activer.
  • Docker : si vous optez pour un déploiement en conteneur, vous aurez besoin de Docker pour exécuter la base de données et les services de stockage de fichiers. Pour un essai rapide en local, vous pouvez utiliser SQLite par défaut.
  • Informations d'identification du service de modèle : pour configurer le modèle de langage pour l'agent IA, préparez l'adresse API et la clé du service de modèle, par exemple DEEPSEEK_API_KEY pour DeepSeek.
  • Compte Workspace : l'accès à Workspace nécessite une connexion, l'inscription par mot de passe est activée par défaut.

Arborescence du projet

Après avoir cloné le dépôt, vous verrez la structure de répertoires suivante :

apps/workspace                 Navigateur Workspace, Serveur, contrat HTTP et application de déploiement
apps/cli                       Application d'automatisation Workspace à distance pour les agents
apps/agent                     Application Agent Workspace pour la conversation documentaire et la revue Worktree
packages/client-core           Capacités privées du client Agent Workspace hébergé sur Node
packages/reference-provider    Politique privée de référence-unité pour le navigateur uniquement
packages/dsh-univer-workspace-plugin        Capacités Workspace et interface utilisateur navigateur pour l'Agent Workspace
packages/dsh-univer-workspace-skin-plugin   Habillage visuel Workspace pour l'Agent Workspace
scripts                        Versions SDK et outils de publication locale CLI

apps/workspace est le cœur, contenant le frontend Browser, le backend Server et les contrats API. apps/cli est l'outil en ligne de commande destiné aux agents IA, et apps/agent est l'interface de conversation de niveau bureau.

Guide pas à pas

1. Préparer le code source et l'environnement

Clonez d'abord le dépôt en local, installez les dépendances et copiez les exemples de variables d'environnement :

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

La configuration par défaut utilise SQLite et le stockage de fichiers local, prêt à l'emploi. Si vous déployez en production, modifiez la configuration de la base de données et du stockage dans apps/workspace/.env selon vos besoins.

2. Démarrer le service Workspace

Lancez le serveur backend, qui s'exécutera sur http://127.0.0.1:3020 :

pnpm workspace:dev:server

Dans un autre terminal, démarrez le serveur de développement frontend Browser :

pnpm workspace:dev:web

Ouvrez maintenant http://127.0.0.1:5173; Vite proxy automatiquement le trafic API et WebSocket vers le serveur sur le port 3020. Enregistrez un compte avec un mot de passe, connectez-vous et vous aurez un Workspace éditable.

3. Connecter l'assistant IA et le service de modèle

Pour que l'IA puisse vous aider à traiter des documents, deux connexions indépendantes sont nécessaires : l'une est le connexion Workspace, pour que l'IA puisse accéder à vos documents ; l'autre est le connexion au service de modèle, pour que l'IA ait un "cerveau" pour réfléchir.

D'abord, le service de modèle. La configuration du modèle de l'agent Workspace est un état de la machine locale, non lié à l'utilisateur Workspace. Nous pouvons l'injecter directement via des variables d'environnement. Avant de lancer l'Agent, exécutez :

export DEEPSEEK_API_KEY=<votre-clé-api>

Si vous souhaitez plus de choix ou des prix plus flexibles pour le service de modèle, vous pouvez consulter Defapi. Defapi est une passerelle de modèles agrégés offrant des services de modèles à moitié prix officiels, compatible avec les protocoles courants v1/chat/completions, v1/messages et v1beta/models/. Récupérez l'URL racine de l'API et l'identifiant du modèle depuis la plateforme, puis injectez-les de la même manière via des variables d'environnement. Notez que cela relève de la configuration du client externe, et non d'une fonctionnalité intégrée de Workspace.

Ensuite, enregistrez le rappel OAuth. L'Agent Workspace nécessite une connexion OAuth via navigateur. La documentation officielle recommande de consulter apps/agent/README.md pour les instructions d'installation. Lors de l'installation de l'Agent, le lanceur local affichera l'URL complète du jeton ; vous devrez effectuer l'enregistrement de l'application et la configuration du rappel.

4. Installer et démarrer l'Agent Workspace

L'Agent est une application Web locale basée sur DSH; les étapes d'installation sont décrites dans apps/agent/README.md. Une fois installé, démarrez l'Agent. Il vous guidera pour choisir ou démarrer votre propre service Workspace, enregistrer le rappel OAuth, puis ouvrir la page de connexion.

Après la connexion, dans l'interface de conversation de l'Agent, vous pouvez utiliser @ pour référencer des fichiers dans Workspace. L'Agent lira le contenu et effectuera des modifications.

5. Exécuter une tâche documentaire

Maintenant, demandons à l'Agent de modifier un tableau. Dans la conversation, saisissez :

Veuillez consulter la feuille @Données de vente et résumez les ventes de chaque trimestre de 2024 dans une nouvelle feuille, en indiquant le taux de croissance.

L'Agent créera un nouveau Worktree, dans lequel il effectuera les opérations de lecture, de calcul et d'écriture. Ce processus n'affectera pas les données originales sur la branche principale.

6. Vérifier les résultats et valider la fusion

Une fois les modifications de l'Agent terminées, le Worktree passera à l'état Ready. Revenez à l'interface de revue du Browser ou de l'Agent, vous verrez :

  • Une vue comparative du brouillon de l'Agent et de la branche principale
  • Les cellules modifiées, les nouvelles feuilles ajoutées

Après avoir soigneusement vérifié les données, cliquez sur Fusionner. Ce n'est qu'alors que les modifications seront réellement fusionnées dans la branche principale, et tous les collaborateurs pourront voir les mises à jour. Si vous repérez un problème, vous pouvez marquer Rouvrir pour que l'Agent continue à modifier.

Voici une voie alternative utilisant le CLI. Prenons Claude Code comme exemple. Si vous avez installé univer-workspace-cli dans votre environnement d'exécution d'agent, vous pouvez procéder ainsi :

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          # après confirmation dans le navigateur
uvw auth login --complete
uvw pr list -R <propriétaire>/<slug>

Le CLI traite le Worktree comme une PR. Copiez l'identifiant du Worktree retourné par uvw pr view <n> -R <propriétaire>/<slug> --json id, puis utilisez les commandes de contenu pour l'inspection.

Résolution des problèmes courants

Erreur de version de Node.js au démarrage

Workspace exige Node.js 24+; vérifiez la version avec node -v. Si la version est insuffisante, installez la version LTS avec nvm.

pnpm install bloqué ou en erreur

Le dépôt utilise pnpm 11.24.0; exécutez d'abord corepack enable puis installez. Si un problème réseau provoque l'échec, configurez un miroir et réessayez.

Rien ne s'affiche à l'ouverture du port 5173 dans le navigateur

Assurez-vous que les deux terminaux sont toujours en cours d'exécution : pnpm workspace:dev:server et pnpm workspace:dev:web. Le proxy de Vite nécessite que le serveur démarre avec succès d'abord.

L'URL de rappel ne correspond pas lors de la connexion OAuth

Vérifiez que l'URL de rappel dans la configuration de l'Agent correspond à la liste des rappels autorisés de Workspace. En développement local, le rappel est généralement http://127.0.0.1:<port-agent>/oauth/callback.

L'Agent ne trouve pas les informations d'identification du modèle dans la conversation

Les informations d'identification du modèle sont un état local, non lié à l'utilisateur Workspace. Assurez-vous d'avoir exporté DEEPSEEK_API_KEY avant de démarrer l'Agent, ou configuré le modèle via la page DSH Models. Chaque processus d'Agent doit être configuré séparément.

Erreur de permission lors de la fusion

La fusion du Worktree nécessite des permissions d'édition sur le document. Dans le Browser, vérifiez que le compte actuel a les permissions d'écriture sur le dossier ou le fichier correspondant. Si le document se trouve dans un espace d'équipe, le propriétaire ou l'administrateur doit attribuer les permissions.

Lectures complémentaires / pistes avancées

Si vous souhaitez approfondir l'utilisation d'Univer Workspace, voici quelques pistes à explorer :

  • Utilisation avancée du CLI : consultez apps/cli/README.md pour découvrir uvw execute pour exécuter des scripts personnalisés, uvw inspect pour examiner la structure des documents, et uvw screenshot pour générer des captures d'écran afin de valider la mise en page.
  • Intégration du service MCP : Workspace fournit un service MCP distant. Configurez https://<votre-workspace>/mcp dans Claude, Cursor ou VS Code pour permettre à ces assistants IA de manipuler directement vos documents.
  • Mini-application HTML View : l'Agent peut générer une application Web liée aux données de rapport, avec des indicateurs, des graphiques et des contrôles reliés bidirectionnellement aux cellules, idéale pour les tableaux de bord de décision.
  • Déploiement Docker : passez à PostgreSQL + stockage S3, consultez apps/workspace/README.md pour un déploiement conteneurisé, avec mise à niveau automatisée et migration des données.

Mettez en place un Workspace dès maintenant, laissez l'IA vous aider à traiter votre premier rapport mensuel, et vous ressentirez le contrôle qu'offre le mécanisme de revue Worktree.