Despliegue práctico de Univer Workspace: edición colaborativa de documentos de oficina con IA

Despliegue práctico de Univer Workspace: edición colaborativa de documentos de oficina con IA

Introducción al proyecto

La edición colaborativa de documentos de oficina siempre ha sido un punto débil en la colaboración en equipo, especialmente cuando los Agentes de IA comienzan a participar en la creación de contenido, cómo hacer que la IA modifique documentos de manera segura y controlable se convierte en un nuevo problema. Univer Workspace nace precisamente para resolver este escenario: es un espacio de trabajo de oficina de código abierto que se puede implementar de forma independiente, permitiéndote a ti y a los Agentes de IA trabajar juntos en la misma plataforma con Sheet, Doc, Slide, Base y Board.

Su diseño central merece atención. Workspace se compone de cuatro partes: Browser, Server, Agent y CLI:

  • Browser proporciona la interfaz de edición y colaboración directa, es el punto de entrada para los humanos;
  • Server es la única autoridad, responsable de la autenticación de identidad, gestión de permisos y almacenamiento de documentos;
  • Agent es una aplicación web local basada en DSH, que reúne conversación, vista previa de documentos y revisión de cambios;
  • CLI proporciona una entrada de automatización estructurada para Agentes de IA, permitiendo cargar, modificar y validar documentos desde la terminal.

El mecanismo más destacado es Worktree. Antes de que el Agente modifique cualquier contenido, el sistema crea primero un árbol de trabajo aislado, donde el Agente puede editar y validar libremente, y cuando el borrador está listo, se entrega a los humanos para su revisión; solo después de la aprobación se fusiona en la rama principal. De esta manera, cualquier modificación intermedia no contamina el contenido compartido, y los humanos siempre tienen el control final.

Dependencias principales y entorno

Antes de comenzar, asegúrate de que tu computadora tenga listos estos requisitos básicos:

  • Node.js 24+: El servidor y el frontend de Workspace se basan en JavaScript moderno, por lo que se necesita Node 24 o superior.
  • pnpm 11: El repositorio usa pnpm para gestionar las dependencias, la versión requerida es 11.x, se recomienda activarlo con corepack enable.
  • Docker: Si optas por la ruta de implementación en contenedores, necesitas Docker para ejecutar la base de datos y los servicios de almacenamiento de archivos. Para una experiencia rápida local, puedes usar SQLite por defecto.
  • Credenciales del servicio de modelos: Para configurar el modelo de lenguaje para el Agente de IA, necesitas preparar la dirección API y la clave del servicio de modelos, como DEEPSEEK_API_KEY de DeepSeek.
  • Cuenta de Workspace: El acceso a Workspace requiere inicio de sesión, con registro por contraseña habilitado por defecto.

Árbol de estructura del proyecto

Después de clonar el repositorio, verás una estructura de directorios como esta:

apps/workspace                 Browser de Workspace, Server, contrato HTTP y aplicación de implementación
apps/cli                       Aplicación de automatización remota de Workspace orientada a Agentes
apps/agent                     Aplicación Agente de Workspace para conversación de documentos y revisión de Worktree
packages/client-core           Capacidad privada del Cliente Agente de Workspace alojado en Node
packages/reference-provider    Política privada de referenced-Unit policy solo para Browser
packages/dsh-univer-workspace-plugin        Capacidades de Workspace y UI de navegador para Workspace Agent
packages/dsh-univer-workspace-skin-plugin   Skin visual de Workspace para Workspace Agent
scripts                        Herramientas de publicación local y versión SDK

apps/workspace es el núcleo, incluye el frontend Browser, el backend Server y los contratos de API. apps/cli es la herramienta de línea de comandos para Agentes de IA, mientras que apps/agent es la interfaz de conversación de nivel escritorio.

Pasos detallados

1. Preparar el código fuente y el entorno

Primero clona el repositorio localmente, instala las dependencias y copia el ejemplo de variables de entorno:

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

La configuración predeterminada usa SQLite y almacenamiento de archivos local, listo para usar. Si planeas implementar en producción, modifica la configuración de la base de datos y almacenamiento en apps/workspace/.env según sea necesario.

2. Iniciar el servicio de Workspace

Inicia el backend Server, que se ejecutará en http://127.0.0.1:3020:

pnpm workspace:dev:server

En otra terminal, inicia el servidor de desarrollo del frontend Browser:

pnpm workspace:dev:web

Ahora abre http://127.0.0.1:5173, Vite proxyará el tráfico de API y WebSocket automáticamente al Server en el puerto 3020. Regístrate con una contraseña, inicia sesión y tendrás un Workspace editable.

3. Conectar el asistente de IA y el servicio de modelos

Para que la IA te ayude con los documentos, necesitas dos conexiones independientes: una es la credencial de inicio de sesión de Workspace, que permite a la IA acceder a tus documentos; la otra es la credencial del servicio de modelos, que le da a la IA un "cerebro" para pensar.

Hablemos primero del servicio de modelos. La configuración del modelo de Workspace Agent es estado local de la máquina, no está vinculada al usuario de Workspace. Podemos inyectarla directamente a través de variables de entorno; antes de iniciar el Agent, ejecuta:

export DEEPSEEK_API_KEY=<tu-api-key>

Si deseas más opciones o precios más flexibles para el servicio de modelos, puedes consultar Defapi. Defapi es una pasarela de modelos agregada que ofrece servicios de modelos a mitad de precio oficial, compatible con protocolos principales como v1/chat/completions, v1/messages y v1beta/models/. Una vez que obtengas la URL raíz de la API y el ID del modelo de la plataforma, inyéctalo de la misma manera con variables de entorno. Ten en cuenta que esto es configuración externa del cliente, no una función integrada de Workspace.

Luego, registra el callback de OAuth. Workspace Agent requiere inicio de sesión OAuth en el navegador; la documentación oficial sugiere buscar las instrucciones de instalación en apps/agent/README.md. Al instalar el Agent, el instalador local imprimirá la URL completa del token; deberás completar el registro de la aplicación y la configuración del callback.

4. Instalar e iniciar Workspace Agent

Agent es una aplicación web local basada en DSH; los pasos de instalación se encuentran en apps/agent/README.md. Una vez instalado, inicia el Agent, que te guiará para seleccionar o iniciar tu propio servicio de Workspace, registrar el callback de OAuth y luego abrir la página de inicio de sesión.

Después de iniciar sesión, en la interfaz de conversación del Agent, puedes usar @ para hacer referencia a archivos en Workspace; el Agent leerá el contenido del archivo y realizará modificaciones.

5. Ejecutar tareas de documentos de oficina

Ahora hagamos que el Agent modifique una hoja de cálculo. En la conversación, escribe:

Por favor, revisa la hoja @sales data y resume las ventas trimestrales de 2024 en una nueva hoja, indicando la tasa de crecimiento.

El Agent creará un nuevo Worktree, en el que realizará las operaciones de lectura, cálculo y escritura. Este proceso no afecta los datos originales en la rama principal.

6. Revisar los resultados y aprobar la fusión

Después de que el Agent haya modificado, el Worktree pasará al estado Ready. Vuelve a la interfaz de revisión del Browser o del Agent y verás:

  • Una vista comparativa entre el borrador del Agent y la rama principal
  • Las celdas modificadas, la nueva hoja agregada

Después de verificar cuidadosamente que los datos sean correctos, haz clic en Fusionar. Solo entonces los cambios se fusionarán realmente en la rama principal y todos los colaboradores podrán ver las actualizaciones. Si encuentras problemas, puedes marcar Reabrir para que el Agent continúe modificando.

Aquí se proporciona una ruta alternativa usando CLI. Tomando como ejemplo Claude Code, si tu entorno de ejecución del Agent tiene instalado univer-workspace-cli, puedes operar así:

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          # después de confirmar en el navegador
uvw auth login --complete
uvw pr list -R <dueño>/<slug>

El CLI trata los Worktrees como PRs; copia el ID de Worktree devuelto por uvw pr view <n> -R <dueño>/<slug> --json id y úsalo para inspeccionar con comandos de contenido.

Solución de problemas comunes

Al iniciar, advierte sobre versión de Node.js demasiado baja

Workspace requiere Node.js 24+, verifica con node -v. Si la versión es insuficiente, instala la versión LTS con nvm.

pnpm install se atasca o muestra error

El repositorio está fijado a pnpm 11.24.0; primero ejecuta corepack enable y luego la instalación. Si falla por problemas de red, configura un espejo y reintenta.

El navegador abre el puerto 5173 sin contenido

Asegúrate de que ambas terminales sigan ejecutándose: pnpm workspace:dev:server y pnpm workspace:dev:web. El proxy de Vite necesita que el Server se inicie correctamente.

OAuth muestra que la URL de callback no coincide

Verifica que la URL de callback en la configuración del Agent coincida con la lista de callbacks autorizados de Workspace. En desarrollo local, el callback suele ser http://127.0.0.1:<puerto-del-agent>/oauth/callback.

La conversación del Agent indica que no se encuentran credenciales del modelo

Las credenciales del modelo son estado local y no siguen al usuario de Workspace. Confirma que hayas exportado DEEPSEEK_API_KEY antes de iniciar el Agent o que hayas configurado el modelo a través de la página de DSH Models. Diferentes procesos del Agent deben configurarse por separado.

Al fusionar, indica falta de permisos

La fusión de Worktree requiere permisos de edición del documento. En el Browser, verifica si la cuenta actual tiene permisos de escritura en la carpeta o archivo correspondiente. Si el documento está en un Space de equipo, se necesitan permisos asignados por el Owner o Admin.

Lectura adicional / Direcciones avanzadas

Si deseas profundizar en Univer Workspace, estas direcciones merecen exploración:

  • Uso avanzado de CLI: Lee apps/cli/README.md para conocer uvw execute para ejecutar scripts personalizados, uvw inspect para inspeccionar la estructura de documentos, uvw screenshot para renderizar capturas de pantalla y validar el diseño.
  • Integración con servicio MCP: Workspace ofrece un servicio MCP remoto; configura https://<tu-workspace>/mcp en Claude, Cursor o VS Code para que estos asistentes de IA puedan operar directamente tus documentos.
  • Mini aplicación HTML View: El Agent puede generar aplicaciones web vinculadas a datos de informes; métricas, gráficos y controles se vinculan bidireccionalmente con las celdas, ideal para paneles de decisión.
  • Implementación con Docker: Cambia a PostgreSQL + almacenamiento S3, consulta apps/workspace/README.md para la implementación en contenedores, con soporte para actualización automática y migración de datos.

Ponte manos a la obra y monta un Workspace; deja que la IA te ayude a procesar tu primer informe mensual y sentirás el control que brinda el mecanismo de revisión de Worktree.