Univer Workspace: Despliegue y tablas de IA en la práctica
Si el contenido de tablas generado por IA se queda solo en la ventana de chat, la modificación posterior, la colaboración y la revisión se interrumpen. Univer Workspace pone documentos, tablas y operaciones de IA en el mismo espacio de trabajo, de modo que el Agent modifica en un Worktree aislado y nosotros lo fusionamos después de revisarlo. Hoy completaremos juntos el despliegue local y pondremos en funcionamiento la generación de resúmenes y fórmulas por parte del Agent con una tabla de ventas.
Introducción al proyecto
Univer Workspace es un espacio de trabajo ofimático de código abierto, construido sobre Univer Office SDK e implementable de forma independiente. El problema central que resuelve es que el contenido ofimático generado por IA necesita ser trasladado manualmente al editor, y las modificaciones posteriores son difíciles de colaborar y revisar.
El proyecto conecta tres puntos de entrada — Browser, Agent y CLI — al mismo Workspace Server, permitiendo que personas e IA procesen juntas Sheet, Doc, Slide, Base y Board. El Agent trabaja en un Worktree aislado y valida los cambios; solo el contenido que confirmamos se fusiona en el trunk compartido. Puedes editar directamente en Workspace Browser o hacer que Workspace Agent converse junto al documento y genere contenido, para luego revisar los cambios de la tabla como si revisaras código.
Casos de uso y requisitos previos
El caso típico es el análisis de datos de ventas. El equipo coloca la tabla de detalle de ventas en Workspace, hace que el Agent resuma por región y genere fórmulas, y nosotros revisamos los cambios de la tabla como si revisáramos código.
Antes de comenzar, necesitas preparar:
- Poder usar una terminal y saber leer configuración de JavaScript/TypeScript
- Tener Git instalado
- Node.js 24 o superior
- pnpm 11.24.0
- Una API Key de modelo para las conversaciones con el Agent
- Para ejecutar capturas de pantalla o comprobaciones de diseño, prepara Chrome/Chromium
El inicio de sesión de Workspace y las credenciales del modelo son dos cosas distintas: navegar por los documentos no requiere solicitudes al modelo; solo hablar con el Agent requiere credenciales del modelo.
Dependencias principales y entorno
El .npmrc del repositorio apunta @univer-cli, @univerjs, @univerjs-pro y @univerjs-labs a https://insider-npm-registry.univer.work/. Durante la instalación es necesario acceder a este Registry privado y también al Registry público de npm.
DSH Runtime está fijado por packages/dsh-runtime a @deepseek-ai/[email protected]. El código fuente usa Apache-2.0, pero las condiciones de uso del SDK de Univer no equivalen por completo a la licencia del código fuente: las credenciales de desarrollo del runtime integrado rotan cada 90 días, el Collaboration/Exchange SDK del servidor requiere una license key y, si falta cualquiera de estos valores, se degrada a la cuota gratuita.
Árbol de estructura del proyecto
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 版本与发布工具
Instrucciones paso a paso
1. Clona la versión fijada e instala las dependencias
Primero fija el commit usado por el tutorial para evitar que cambios posteriores afecten a los comandos.
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile
Este paso accede al Registry privado y al Registry público de npm. Si tu red está restringida, consulta antes las preguntas frecuentes al final del artículo.
2. Configura el acceso al modelo
Antes de iniciar el Agent, comprende primero la división de tareas entre el inicio de sesión y las credenciales del modelo. El inicio de sesión de Workspace solo autoriza el acceso a los datos; al hablar con el Agent, DSH envía las solicitudes del modelo al endpoint de chat completions que hayamos configurado. Si planeas que el Agent analice la tabla de ventas y genere fórmulas, debes preparar primero un baseURL, una API Key y un model disponibles para el modelo.
El adaptador deepseek-official de DSH envía solicitudes a baseURL + /chat/completions, por lo que debes completar el baseURL hasta el nivel /v1 y no volver a concatenar la ruta.
Si quieres controlar el coste del modelo, puedes conectarte a un gateway compatible con OpenAI como Defapi. Defapi ofrece acceso unificado a modelos, con una facturación de aproximadamente la mitad del precio oficial; los modelos y precios concretos dependen de la consola. El sitio oficial https://defapi.org tiene una entrada clara, y es básicamente compatible con los protocolos v1/chat/completions, v1/messages y v1beta/models/. Al configurarlo, basta con apuntar el baseURL a la base de chat completions que muestra la consola de Defapi.
export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true
El ID del modelo se rige por el catálogo realmente disponible en la consola. Si el ID de modelo predeterminado de DSH no coincide con el de la consola de Defapi, puedes cambiarlo por un ID disponible en la consola desde la lista de modelos de la página DSH Models. En producción, la página Models está oculta por defecto; solo se muestra si configuras UWH_MODEL_SETTINGS_ENABLED=true. En local, si no has establecido NODE_ENV=production, la página nativa de DSH Models se puede abrir directamente.
3. Crea la configuración de entorno de Workspace y registra el cliente OAuth del Agent
Workspace no registra el cliente OAuth del Agent por defecto; solo copiar .env.example no es suficiente.
cp apps/workspace/.env.example apps/workspace/.env
A continuación, edita apps/workspace/.env y añade la siguiente configuración de una sola línea, sin comentar:
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 ya existe OAUTH_CLIENTS_JSON, añade el cliente anterior al array clients; mantén siempre una única entrada de configuración.
4. Inicia Workspace Server y Browser
En la primera terminal, inicia el Server:
pnpm workspace:dev:server
En la segunda terminal, inicia el servidor de desarrollo de Browser:
pnpm workspace:dev:web
Abre http://127.0.0.1:5173, registra una cuenta local de Workspace o inicia sesión con una cuenta existente. El registro local no necesita OAuth de GitHub/Discord. Mantén ambos procesos en ejecución.
5. Compila DSH Runtime y Agent Profile, e inicia el Agent local
El Agent es una aplicación web local; primero hay que ensamblar el runtime de DSH desde el código fuente. Los siguientes comandos compilan client-core, tres bundles e instalan el Profile en un directorio aislado.
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
El comando se quedará en primer plano con start-local.mjs; esto es normal. Espera a que en stderr aparezca una línea que empiece por dsh web: y copia la URL completa de esa línea.
Si el puerto 3101 está ocupado, usa otro puerto explícito y actualiza también los redirectUris del paso 3.
6. Conecta Workspace y completa OAuth
En el navegador, abre la URL completa que imprime dsh web:; contiene un ?token=... de un solo uso. DSH establecerá una cookie HttpOnly y redirigirá a la dirección raíz.
# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>
Luego, en la interfaz del Agent, ve a Configuración → Workspace e introduce la dirección del servicio local:
http://127.0.0.1:5173
Haz clic en Sign in to Workspace y aprueba el acceso en la página de autorización de Workspace. Workspace redirigirá a la devolución de llamada del Agent local, y el Agent usará PKCE para intercambiar el código de autorización. Después de volver, deberían aparecer la cuenta y el Space personal en la barra lateral.
Si la página de conexión sigue esperando, haz clic en Check again y mantén start-local.mjs en ejecución.
7. Crea una tabla de ventas de ejemplo y haz que el Agent genere el resumen y las fórmulas
En la barra lateral, abre Archivos, elige un Space personal o de equipo, crea una nueva tabla e introduce el detalle de ventas:
日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200
Vuelve a Conversaciones, crea una nueva conversación, escribe @ en el campo de entrada para seleccionar la tabla recién creada y luego envía:
@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。
Después de enviarlo, el Agent validará la referencia basándose en el Workspace actual y escribirá los cambios en el Worktree; no modificará directamente el trunk compartido.
8. Revisa las diferencias del Worktree, fusiona o descarta
Abre la pestaña Worktree y encuentra la tarea en curso. La vista de revisión muestra por defecto el 'efecto de los cambios'; puedes cambiar a 'Diferencias' para ver los documentos añadidos, modificados y eliminados. Después de confirmar que el resultado es correcto, haz clic en 'Fusionar'; si no estás satisfecho, puedes convertirlo en borrador o descartarlo. Solo después de fusionar se actualiza el trunk compartido.
创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk
Si el Agent ejecuta univer_lint o univer_screenshot, necesita una página de renderizado estático con versión coincidente y Chrome/Chromium. Si falta UWH_RENDER_PAGE_ROOT o un navegador, la herramienta informará claramente de un error de requisitos previos y no marcará la verificación visual como aprobada.
Solución de problemas comunes
1. pnpm install no puede acceder al Registry privado
Durante la instalación es necesario acceder al Registry privado y también al Registry público de npm; ambos son imprescindibles. Si se queda bloqueado o da 401, primero confirma que la red puede acceder a https://insider-npm-registry.univer.work/ y luego confirma las versiones de Node y pnpm. No elimines la línea registry de .npmrc.
2. Aparece OAUTH_CLIENT_UNAVAILABLE
El servidor de Workspace no ha cargado el cliente OAuth del Agent. Comprueba si OAUTH_CLIENTS_JSON en apps/workspace/.env contiene univer-workspace-harness; después de modificarlo, reinicia el Server. Solo copiar .env.example no registra este cliente.
3. Aparece INVALID_REDIRECT_URI
La dirección de devolución de llamada debe coincidir exactamente. localhost y 127.0.0.1 son registros distintos. Si el Agent cambia de puerto, debes actualizar también redirectUris y reiniciar el backend de Workspace. Este registro controla la devolución de llamada de OAuth, no es un permiso CORS genérico para el puerto 3101.
4. Abrir la dirección raíz devuelve 401
Si no abres primero la URL completa con el token, el navegador no tendrá la cookie de sesión. Vuelve a abrir la dirección dsh web: impresa por el lanzador para completar el canje; después puedes usar la dirección raíz sin parámetros. No reutilices el token de un solo uso.
5. El inicio de sesión en Workspace funciona, pero fallan los mensajes del modelo
El OAuth de Workspace solo autoriza el acceso a los datos; las credenciales del modelo deben configurarse por separado. Revisa DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL y el ID del modelo. Con Defapi, completa el baseURL con la base de chat completions que proporciona la consola y no vuelvas a concatenar /chat/completions.
6. La página de conexión del Agent sigue esperando
Mantén start-local.mjs en ejecución. Cuando cambia el estado de la conexión, se realiza una comprobación de disponibilidad; si el servicio de cuentas no carga correctamente, revisa los registros del lanzador. Si la solicitud de autorización caduca, vuelve a iniciar sesión desde Configuración → Workspace. Este flujo usa OAuth de navegador y no requiere introducir un código de dispositivo.
7. La captura de pantalla o la comprobación de diseño informa de un error de requisitos previos
univer_lint y univer_screenshot requieren que UWH_RENDER_PAGE_ROOT apunte a la página de renderizado estático y que UWH_RENDER_BROWSER apunte a un Chrome/Chromium compatible. Si no hay navegador, asigna la ruta del ejecutable a UWH_RENDER_BROWSER y luego inicia el Agent.
Lecturas adicionales / Direcciones avanzadas
- Despliegue con Docker: Workspace ofrece una aplicación de despliegue independiente; puedes crear una imagen siguiendo la guía oficial de la aplicación y colocar Server, Browser y almacenamiento en el servidor.
- Automatización con CLI: instala
univer-workspace-cli, conéctalo a entornos de Agent existentes como Claude, Codex, Kimi Work, y usa la CLI para procesar documentos y Worktree. - Integración con MCP: Workspace expone un servicio MCP remoto compatible con Streamable HTTP y OAuth; clientes como Cursor, VS Code y Claude Desktop pueden conectarse directamente.
- Documentación oficial y versión fijada: documentación del SDK web de Univer, documentación del SDK del Server y documentación de configuración de Workspace. Este tutorial está escrito con base en
c1a5fb3dc9d5951cbf618f76639466feac5da4d7; para versiones posteriores, consulta la documentación oficial.