Univer Workspace : déploiement et mise en pratique des tableurs IA

Si le contenu de tableur généré par l'IA reste confiné à la fenêtre de discussion, les modifications, la collaboration et la révision ultérieures s'interrompent. Univer Workspace réunit documents, tableurs et opérations d'IA dans un même espace de travail, permettant à l'Agent de modifier dans un Worktree isolé, et nous fusionnons après révision. Aujourd'hui, nous allons ensemble effectuer un déploiement local et utiliser un tableau de ventes pour faire fonctionner la génération de synthèses et de formules par l'Agent.

Présentation du projet

Univer Workspace est un espace de travail Office open source, basé sur le SDK Univer Office et déployable de manière autonome. Le problème central qu'il résout est le suivant : le contenu bureautique généré par l'IA doit être transféré manuellement dans l'éditeur, ce qui rend difficile la collaboration et la révision des modifications ultérieures.

Le projet connecte les trois points d'entrée Browser, Agent et CLI au même Workspace Server, permettant aux humains et à l'IA de traiter ensemble Sheet, Doc, Slide, Base et Board. L'Agent travaille dans un Worktree isolé et vérifie les modifications ; seul le contenu que nous avons confirmé est fusionné dans le tronc commun (trunk). Vous pouvez éditer directement dans Workspace Browser, ou laisser Workspace Agent dialoguer à côté des documents, générer du contenu, puis réviser les modifications du tableur comme on révise du code.

Cas d'usage et prérequis

Le cas typique est l'analyse des données de vente. L'équipe place le tableau des détails de vente dans Workspace, laisse l'Agent regrouper par région et générer des formules, et nous révisons les modifications du tableur comme on révise du code.

Avant de commencer, vous devez préparer :

  • Savoir utiliser un terminal et lire la configuration JavaScript/TypeScript
  • Git installé
  • Node.js 24 ou version ultérieure
  • pnpm 11.24.0
  • Une clé API de modèle pour les conversations avec l'Agent
  • Chrome/Chromium pour les captures d'écran ou les contrôles de mise en page

La connexion à Workspace et les identifiants de modèle sont deux choses distinctes : consulter des documents ne nécessite pas de requête de modèle ; seul un dialogue avec l'Agent nécessite des identifiants de modèle.

Dépendances principales et environnement

Le fichier .npmrc du dépôt pointe @univer-cli, @univerjs, @univerjs-pro, @univerjs-labs vers https://insider-npm-registry.univer.work/. Lors de l'installation, vous devez accéder à ce registre privé ainsi qu'au registre npm public.

Le runtime DSH est épinglé à @deepseek-ai/[email protected] via packages/dsh-runtime. Le code source est sous Apache-2.0, mais les conditions d'utilisation du SDK Univer ne sont pas entièrement équivalentes à la licence du code source : les identifiants de développement intégrés au runtime sont renouvelés tous les 90 jours, le SDK Collaboration/Exchange côté serveur nécessite une clé de licence, et en l'absence de l'une ou l'autre valeur, on passe en dégradé vers le quota gratuit.

Arborescence du projet

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 版本与发布工具

Guide pas à pas

1. Cloner la version fixée et installer les dépendances

Commencez par fixer le commit utilisé par le tutoriel afin que les modifications ultérieures n'affectent pas les commandes.

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

Cette étape accède au registre privé et au registre npm public. En cas de restrictions réseau, consultez d'abord les problèmes courants en fin de document.

2. Configurer l'accès au modèle

Avant de démarrer l'Agent, comprenez la répartition entre connexion et identifiants de modèle. La connexion à Workspace n'autorise que l'accès aux données ; lors d'un dialogue avec l'Agent, DSH envoie les requêtes de modèle vers le point de terminaison chat completions que nous avons configuré. Si vous prévoyez de laisser l'Agent analyser le tableau de ventes et générer des formules, préparez d'abord le baseURL, la clé API et le model disponibles pour le modèle.

L'adaptateur deepseek-official de DSH envoie les requêtes à baseURL + /chat/completions ; le baseURL doit donc être renseigné au niveau /v1, sans concaténer à nouveau le chemin.

Pour maîtriser les coûts du modèle, vous pouvez utiliser une passerelle compatible OpenAI comme Defapi. Defapi offre un accès unifié aux modèles, avec une facturation environ moitié prix par rapport à l'officiel ; les modèles et prix exacts font foi sur la console. Le site officiel https://defapi.org fournit une entrée claire ; il est globalement compatible avec les protocoles v1/chat/completions, v1/messages, v1beta/models/. Lors de la configuration, pointez le baseURL vers l'adresse de base chat completions fournie par la console Defapi.

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

L'ID du modèle dépend du catalogue réellement disponible dans la console. Si l'ID de modèle par défaut de DSH ne correspond pas à celui de la console Defapi, vous pouvez le remplacer dans la liste des modèles de la page DSH Models par un ID disponible dans la console. En production, la page Models est masquée par défaut ; il faut définir UWH_MODEL_SETTINGS_ENABLED=true pour l'afficher. En local, si NODE_ENV=production n'est pas défini, la page native DSH Models est directement accessible.

3. Créer la configuration d'environnement Workspace et enregistrer le client OAuth de l'Agent

Workspace n'enregistre pas le client OAuth de l'Agent par défaut ; copier .env.example ne suffit pas.

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

Ensuite, éditez apps/workspace/.env et ajoutez la configuration sur une seule ligne non commentée :

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"]}]}

Si OAUTH_CLIENTS_JSON existe déjà, ajoutez le client ci-dessus au tableau clients, en ne conservant toujours qu'un seul élément de configuration.

4. Démarrer Workspace Server et Browser

Dans le premier terminal, démarrez le Server :

pnpm workspace:dev:server

Dans le second terminal, démarrez le serveur de développement Browser :

pnpm workspace:dev:web

Ouvrez http://127.0.0.1:5173, créez un compte Workspace local ou connectez-vous avec un compte existant. L'inscription locale ne nécessite pas OAuth GitHub/Discord. Laissez les deux processus s'exécuter.

5. Construire le runtime DSH et le profil Agent, puis démarrer l'Agent local

L'Agent est une application Web locale ; il faut d'abord assembler le runtime DSH à partir des sources. Les commandes ci-dessous construisent client-core, trois bundles, et installent le Profile dans un répertoire isolé.

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

La commande restera au premier plan sur start-local.mjs, c'est normal. Attendez qu'une ligne commençant par dsh web: apparaisse sur stderr, puis copiez l'URL complète de cette ligne.

Si le port 3101 est occupé, choisissez un autre port explicite et modifiez en conséquence les redirectUris de l'étape 3.

6. Connecter Workspace et terminer l'OAuth

Ouvrez dans le navigateur l'URL complète imprimée par dsh web:, qui contient un ?token=... à usage unique. DSH définit un cookie HttpOnly et redirige vers l'adresse racine.

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

Ensuite, dans l'interface Agent, allez dans Paramètres → Workspace et saisissez l'adresse du service local :

http://127.0.0.1:5173

Cliquez sur Sign in to Workspace, puis approuvez l'accès sur la page d'autorisation Workspace. Workspace redirige vers le rappel (callback) de l'Agent local, et l'Agent échange le code d'autorisation via PKCE. Une fois revenu, le compte et l'espace personnel (Space) doivent apparaître dans la barre latérale.

Si la page de connexion attend indéfiniment, cliquez sur Check again et gardez start-local.mjs en cours d'exécution.

7. Créer un exemple de tableau de ventes et laisser l'Agent générer synthèses et formules

Dans la barre latérale, ouvrez Fichiers, choisissez un Space personnel ou d'équipe, créez un nouveau tableau et saisissez les détails des ventes :

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

Revenez à Conversations, créez une nouvelle conversation, tapez @ dans le champ de saisie, sélectionnez le tableau que vous venez de créer, puis envoyez :

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

Après l'envoi, l'Agent valide les références à partir du Workspace actuel et écrit les modifications dans le Worktree, sans toucher directement au tronc partagé.

8. Examiner les différences du Worktree, fusionner ou abandonner

Ouvrez l'onglet Worktree et trouvez la tâche en cours. La vue de révision affiche par défaut l'« effet des modifications » ; vous pouvez basculer sur « Différences » pour voir les documents ajoutés, modifiés et supprimés. Confirmez que le résultat est correct, puis cliquez sur « Fusionner » ; si vous n'êtes pas satisfait, vous pouvez le convertir en brouillon ou l'abandonner. Le tronc partagé n'est mis à jour qu'après la fusion.

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

Si l'Agent exécute univer_lint ou univer_screenshot, une page de rendu statique de version correspondante et Chrome/Chromium sont nécessaires. En l'absence de UWH_RENDER_PAGE_ROOT ou de navigateur, l'outil signale clairement une erreur de précondition et ne marque pas la validation visuelle comme réussie.

Dépannage des problèmes courants

1. pnpm install échoue à accéder au registre privé

L'installation exige un accès au registre privé et au registre npm public ; les deux sont indispensables. Si cela bloque ou renvoie une erreur 401, vérifiez d'abord que le réseau peut accéder à https://insider-npm-registry.univer.work/, puis vérifiez les versions de Node et de pnpm. Ne supprimez pas la ligne registry dans .npmrc.

2. L'erreur OAUTH_CLIENT_UNAVAILABLE apparaît

Le serveur Workspace n'a pas chargé le client OAuth de l'Agent. Vérifiez que OAUTH_CLIENTS_JSON dans apps/workspace/.env contient univer-workspace-harness, puis redémarrez le Server après modification. Copier .env.example n'enregistre pas ce client.

3. L'erreur INVALID_REDIRECT_URI apparaît

L'adresse de rappel doit correspondre exactement. localhost et 127.0.0.1 sont des enregistrements distincts. Si vous changez le port de l'Agent, modifiez également les redirectUris et redémarrez le backend Workspace. Cet enregistrement contrôle le rappel OAuth, et non un laissez-passer CORS général pour le port 3101.

4. L'ouverture de l'adresse racine renvoie 401

Si vous n'avez pas d'abord ouvert l'URL complète avec le token, le navigateur ne possède pas de cookie de session. Rouvrez l'adresse dsh web: imprimée par le lanceur pour effectuer l'échange ; ensuite, vous pouvez utiliser l'adresse racine sans paramètres. Ne réutilisez pas le token à usage unique.

5. La connexion Workspace réussit, mais les messages du modèle échouent

L'OAuth Workspace n'autorise que l'accès aux données ; les identifiants du modèle doivent être configurés séparément. Vérifiez DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL et l'ID du modèle. Avec Defapi, renseignez le baseURL fourni par la console pour chat completions, sans concaténer à nouveau /chat/completions.

6. La page de connexion de l'Agent attend indéfiniment

Gardez start-local.mjs en cours d'exécution. Après un changement d'état de connexion, une vérification de disponibilité est effectuée ; si le service de compte échoue à se charger, consultez les journaux du lanceur. Une fois la demande d'autorisation expirée, reconnectez-vous via Paramètres → Workspace. Ce processus utilise l'OAuth du navigateur et ne nécessite pas de saisir de code d'appareil.

7. L'erreur de précondition pour les captures d'écran / contrôles de mise en page

univer_lint et univer_screenshot nécessitent que UWH_RENDER_PAGE_ROOT pointe vers la page de rendu statique, et que UWH_RENDER_BROWSER pointe vers un Chrome/Chromium compatible. S'il n'y a pas de navigateur, assignez le chemin de l'exécutable à UWH_RENDER_BROWSER, puis démarrez l'Agent.

Lectures complémentaires / Pistes d'approfondissement

  • Déploiement Docker : Workspace fournit une application déployable de manière autonome ; vous pouvez construire une image selon le guide officiel de l'application pour placer le Server, le Browser et le stockage sur un serveur.
  • Automatisation CLI : installez univer-workspace-cli, connectez-le à des environnements d'Agent existants comme Claude, Codex, Kimi Work, et utilisez la CLI pour traiter les documents et le Worktree.
  • Intégration MCP : Workspace expose un service MCP distant, prenant en charge Streamable HTTP et OAuth ; des clients comme Cursor, VS Code, Claude Desktop peuvent s'y connecter directement.
  • Documentation officielle et version épinglée : documentation du SDK Web Univer, documentation du SDK Server, documentation de configuration Workspace. Ce tutoriel se base sur c1a5fb3dc9d5951cbf618f76639466feac5da4d7 ; pour les versions ultérieures, faites foi à la documentation officielle.