Primeros pasos
Crea tu primera aplicación Office con un agente de programación, intégrala y despliégala.
Esta guía presenta tres ejemplos: vinculación con una hoja de cálculo, edición colaborativa y una CLI para agentes. Elige un ejemplo, pasa su prompt a tu agente de programación y sigue los pasos de integración y despliegue.
Decide qué construir primero
Office SDK admite Sheets, Docs, Slides, Relational Tables, Canvases y PDF. Elige una ruta de integración según el objetivo de tu aplicación.
| Tu objetivo | Por dónde empezar | Primer criterio de éxito |
|---|---|---|
| Integrar un editor Office | Instalación Web SDK | Crear contenido, editarlo, guardarlo y volver a abrirlo. |
| Conectar contenido con la interfaz de negocio | API Facade | Sincronizar campos y celdas en ambos sentidos y mostrar los resultados reales del cálculo. |
| Añadir edición colaborativa | Inicio rápido Server SDK | Dos sesiones independientes editan el mismo contenido y reciben los cambios de la otra. |
| Importar, procesar y exportar archivos Office | Conversión de archivos | Importar un archivo real, editarlo, exportarlo e inspeccionar el resultado. |
| Operar contenido desde un agente o CLI | Operaciones AI SDK | Cargar contenido, inspeccionar su estructura, editarlo y verificar la confirmación o salida. |
| Crear un espacio para personas y agentes | Worktree y revisión | Mantener cambios del agente en un borrador aislado para comparar, revisar y fusionar. |
Puedes combinar estas capacidades. Consulta Funciones para comprobar el soporte por producto; los tres ejemplos siguientes permiten probar primero un flujo completo.
Empieza con tu agente
Dale los requisitos y el enlace al índice de documentación llms.txt a tu agente de programación. No necesitas copiar toda la documentación SDK. Adapta la plantilla o pega uno de los tres ejemplos completos.
Una plantilla de requisitos
Sustituye <…> por tus requisitos. Describe un resultado visible antes de planificar todo un sistema de oficina.
Crea una aplicación <nombre> ejecutable en local con Univer Office SDK.Lee primero https://docs.univer.ai/es-ES/llms.txt y los ejemplos completos relevantes.Mantén la misma versión en todos los paquetes SDK.Contenido inicial: <pocos datos o un documento listo para editar>.Experiencia principal: <una acción del usuario y su resultado visible inmediato>.Criterios: <dos o tres comprobaciones concretas mediante interacción>.Implementa solo este flujo con el editor nativo Univer y las funciones reales del SDK.Ejecuta la aplicación, verifícala en el navegador y dame un enlace de vista previa.Indica cualquier configuración obligatoria que falte.Ejemplo 1: una hoja vinculada
Vincula un campo de cantidad con una celda en ambos sentidos y muestra en la página el total calculado por una fórmula.
Crea una página de presupuestos ejecutable en local con Univer Office SDK.Lee https://docs.univer.ai/es-ES/llms.txt y los ejemplos completos relevantes.Mantén la misma versión en todos los paquetes SDK.Usa el preset básico de Sheets para insertar una hoja nativa editable.Prepara 2 monitores a 1200 cada uno, 5 teclados a 300 y 3 auriculares a 200.Calcula importes por línea y total mediante fórmulas de la hoja.Al lado, coloca un campo de cantidad de monitores y una tarjeta de total.Vincula el campo con su celda en ambos sentidos. La tarjeta debe leer el resultadoreal de la fórmula; no vuelvas a calcular el presupuesto en el código de la página.Permite guardar en el navegador y restaurar al recargar.Verifica: total inicial 4500 y total 5700 con cantidad 3; editar la celda tambiénactualiza campo y tarjeta; guardar y recargar restaura los cambios.Implementa solo estas funciones, verifica la aplicación en ejecucióny dame un enlace de vista previa.Pruébalo: Cambia la cantidad de monitores de 2 a 3 y observa el total pasar de 4500 a 5700. Edita después la hoja directamente para comprobar la actualización de la página. Guarda y recarga para confirmar la restauración. Consulta la instalación de Web SDK y las API Facade.
Ejemplo 2: colaboración en documentos
Edita el mismo documento desde dos sesiones independientes y comprueba que los cambios se sincronizan en ambos sentidos.
Crea una demo local de colaboración entre dos personas con Univer Office SDK.Lee https://docs.univer.ai/es-ES/llms.txt y los ejemplos actuales dehttps://github.com/dream-num/univer-collaboration-examples.Usa la misma versión de SDK en frontend y servidor.Coloca los editores nativos de documentos modernos de Alice y Bob en paralelo.Usa entornos y sesiones independientes conectados al servicio real de colaboraciónServer SDK. Sigue el ejemplo oficial para cargar explícitamente el mismo documentocreado en el servidor. Incluye unas frases cortas.Escribir a la izquierda debe aparecer a la derecha, y viceversa, mediante el protocolo SDK.Usa dos usuarios fijos, memoria como almacenamiento y un servicio local para frontend y backend.No añadas inicio de sesión, gestión de archivos ni chat IA. Lee Pro License del entorno;si no existe, conserva el comportamiento y los avisos predeterminados del SDK.Verifica que las ediciones convergen, que el servidor confirma las actualizacionesy que recargar restaura el contenido. Explica que reiniciar el servicio vacía la memoria.Implementa solo estas funciones, verifica la aplicación en ejecucióny dame un enlace de vista previa.Pruébalo: Escribe una frase a la izquierda y continúa a la derecha. Comprueba la sincronización en ambos sentidos y la conservación del texto al recargar. La demo usa memoria y se reinicia con el servicio; conecta una base de datos persistente para desplegarla. Consulta el inicio rápido de colaboración Server SDK.
Ejemplo 3: crea tu propio you-cli
Dale a tu agente actual una herramienta Office propia. Admite Sheet, Doc, Slide, Relational Table y Canvases; empieza con un Doc para generar, previsualizar y revisar mediante la conversación.
Crea un you-cli local al proyecto y una vista previa Web con Univer Office SDK.Lee https://docs.univer.ai/es-ES/llms.txt y los ejemplos completos de contenido enhttps://github.com/dream-num/univer-cli-examples.Alinea versiones de frontend, servidor y AI SDK; comprueba los tipos instalados.Admite Sheet, Doc, Slide, Relational Table, Canvases; empieza con Doc.Proporciona ./you-cli create <type> --name <name>, inspect --unit <id>,execute --unit <id> --file <path>, open --unit <id> y --help.Mantén la herramienta en este proyecto y crea instrucciones o un Skill para el agente actual.Devuelve JSON con el unitId, tipo, resultado de confirmación y URL que correspondan.CLI y Web usan el mismo contenido colaborativo real y el editor nativo ya abierto.Espera la confirmación de escritura, vuelve a leer y guarda contenido y catálogo de forma persistente.open devuelve la URL; el agente la abre en el panel de vista previa si el entorno lo admite.Usa el agente actual para entender el lenguaje y lee licencias desde el entorno.Verifica por conversación: crear un informe semanal y abrir la vista previa;añadir riesgo y responsable al mismo unitId y actualizar la vista previa abierta.Recargar y reiniciar deben restaurar el contenido. Ejecuta estas comprobaciones,entrega el enlace y el uso, e inicia solo el servicio de este ejemplo.Úsalo mediante la conversación
Entrega el prompt anterior a tu agente de programación. Cuando haya creado la herramienta y leído las instrucciones del proyecto, continúa en la misma conversación:
Usa you-cli para crear un informe semanal con avances, riesgos y próximos pasos.Abre su vista previa Web.Después de ver el resultado, continúa:
Añade al mismo informe el riesgo de retraso de entrega y asigna a Alice como responsable.Actualiza la vista previa que ya está abierta.El agente reutiliza el unitId del documento. Los entornos con panel de vista previa pueden mostrarlo junto a la conversación; los demás usan el enlace de navegador devuelto.
Referencia de comandos you-cli
El prompt define estos comandos locales al proyecto. Sustituye UNIT_ID por el unitId que devuelve create. El agente escribe edit.js con las API Facade.
| Acción | Comando | Resultado |
|---|---|---|
| Crear | ./you-cli create doc --name "Informe semanal" | Crea un documento y devuelve unitId; otros tipos: sheet, slide, base, board. |
| Inspeccionar | ./you-cli inspect --unit UNIT_ID | Lee el contenido real y la revisión actual. |
| Editar | ./you-cli execute --unit UNIT_ID --file edit.js | Ejecuta cambios, espera la confirmación y devuelve el resultado. |
| Previsualizar | ./you-cli open --unit UNIT_ID | Devuelve la URL Web del mismo documento para que la abra el agente. |
También puedes usar ./you-cli --help. Consulta Operaciones AI SDK y los CLI SDK Examples completos.
Conecta el primer flujo a tu aplicación
Web SDK proporciona el entorno de contenido común. Añade Server SDK y AI SDK cuando necesites edición compartida u operaciones de agente. Consulta sus funciones en la visión general de Office SDK.
| Paso | Qué conectar en tu aplicación | Más información |
|---|---|---|
| Insertar el editor | Montar un preset, conectar interacciones con Facade, guardar snapshots y liberar instancias. | Integración Web SDK |
| Conectar el backend | Reutilizar identidad y permisos, configurar la base de documentos compartidos y añadir importación/exportación si se necesita. | Colaboración, conversión |
| Conectar un agente existente | Exponer lectura, escritura, cálculo y verificación como herramientas o CLI; añadir Worktree para revisión. | Operaciones AI SDK, Worktree |
Arquitectura de la aplicación
Tu aplicación y tu agente existente pueden compartir contenido Office. La interfaz gestiona las interacciones, el agente llama a herramientas y tu backend mantiene el control de identidad, permisos y almacenamiento.
Los nodos azules los proporcionas y gestionas tú: interfaz, agente existente, API de negocio con identidad y permisos, base de datos y almacenamiento de archivos. Los demás nodos marcados como SDK representan las capacidades Univer integradas.
Un editor integrado puede empezar con snapshots locales; conecta el backend para la edición compartida. Conserva el modelo y la orquestación de tu agente y usa AI SDK para operar contenido. Añade Worktree para aislar, comparar y revisar cambios.
Construye y despliega con Workspace
Univer Workspace muestra los tres SDK en un entorno de oficina completo. Ejecuta los comandos desde la raíz de ese repositorio. Sigue el README para los requisitos.
- Desarrollo local. Instala dependencias y ejecuta
pnpm workspace:dev:serverypnpm workspace:dev:weben dos terminales. Abrehttp://127.0.0.1:5173. El servidor Web de desarrollo reenvía las peticiones API y WebSocket al backend. - Compilar y ejecutar. Compila solo la aplicación Workspace e inicia su entrada de producción:
pnpm --filter @univerjs/univer-workspace buildpnpm workspace:startEl Web se genera en dist/public y el Server en dist/server. Un único proceso Node.js sirve páginas estáticas y API.
- Preparar el despliegue. Configura licencias, identidad y directorios de datos. Haz persistentes los datos de negocio, colaboración y archivos subidos, y comprueba su restauración tras reiniciar. Consulta el despliegue Docker y la arquitectura.
Cuando crezca la aplicación, consulta la guía de despliegue Server SDK para separar servicios.
Explora otros proyectos de código abierto
- Univer CLI: crear, editar e inspeccionar contenido Office en un espacio local desde un agente o terminal, y revisar los cambios en Viewer.
- DeepSeek Harness: añadir herramientas Office, vistas previas en directo y revisión de borradores a una conversación de agente existente.
Consulta todos los ejemplos para ver demostraciones y enlaces a repositorios.
¿Cómo es esta guía?