# AI SDK

> Aprende cómo AI SDK añade una CLI Node.js y un punto de entrada para AI Agent a una aplicación Univer.

- Human documentation: [https://docs.univer.ai/es-ES/ai](https://docs.univer.ai/es-ES/ai)

- Agent Markdown: [https://docs.univer.ai/es-ES/ai.md](https://docs.univer.ai/es-ES/ai.md)

- Requested language: `es-ES`

- Content language: `es-ES`

- Documentation version: `1.2.0`

- Source: [index.es-ES.mdx](https://github.com/dream-num/documentation/blob/dev/content/ai/index.es-ES.mdx)

---

Univer Office SDK incluye [Web SDK](https://docs.univer.ai/es-ES/guides/sheets.md) para editores integrados y procesamiento de contenido sin interfaz, [Server SDK](https://docs.univer.ai/es-ES/server.md) para colaboración e importación y exportación de archivos, y [AI SDK](https://docs.univer.ai/es-ES/ai.md) para flujos de trabajo de agentes.

**AI SDK** es un SDK TypeScript para crear CLI de Office. Ofrece a AI Agents y automatizaciones un punto de entrada Node.js para cargar, comprender, modificar y comprobar Units[^document-unit] de Univer.

AI SDK es un conjunto de capacidades combinables, no una CLI de producto fija. La aplicación de negocio decide nombres de comandos, argumentos, destinos, identidad y autorización, salida y despliegue.

## Estructura recomendada

Esta guía sigue una aplicación `CLI + Web + Server`:

```mermaid
flowchart LR
    Agent(["AI Agent / usuario CLI"]) --> CLI["<b>AI SDK</b><br/>CLI de negocio"]
    Human(["Usuario humano"]) --> Web["<b>Web SDK</b><br/>Web"]
    CLI --> Server["<b>Server SDK</b><br/>Colaboración · Conversión de archivos"]
    Web --> Server
    Server --> Storage["Almacenamiento"]
    classDef default rx:8,ry:8,stroke-width:1px
    classDef actor fill:transparent,stroke:none
    class Agent,Human actor
```

* CLI es la entrada para que un AI Agent o usuario opere una Unit.
* Web presenta la página real para editar de forma interactiva y revisar como persona.
* Server almacena Units, revisiones y estado de colaboración compartidos por CLI y Web.

Pueden desplegarse por separado o ejecutarse totalmente en local. Construir primero Web + Server con Collaboration SDK y añadir después la CLI es una ruta de aprendizaje recomendada, no una restricción de despliegue.

> [!NOTE: También se admiten aplicaciones solo CLI]
> AI SDK puede procesar Units locales directamente. Los resultados se examinan mediante salida estructurada, comprobaciones visuales del AI Agent o archivos Office exportados. Las páginas Web en vivo, revisiones compartidas, History y Worktree requieren las capacidades Web y de colaboración correspondientes.

## Organizar la CLI con Commander

Los paquetes base exponen API TypeScript estructuradas. Los presets convierten capacidades comunes en objetos nativos Commander `Command`. La aplicación de negocio siempre controla el programa raíz:

```ts
import { Command } from "commander";

const program = new Command("my-cli");

program.addCommand(presetCommand);
program.addCommand(applicationCommand);

await program.parseAsync();
```

* Un **preset de comandos** aporta argumentos, ayuda y salida de texto o JSON predeterminados.
* Un **comando de aplicación** compone Runtime[^live-runtime], destinos de negocio, identidad y políticas de commit o archivos.
* Ambos son objetos Commander `Command` normales y pueden mezclarse en un programa raíz.

Cada tema presenta primero la capacidad base y después cómo conectarla con Commander.

## Construir capacidades progresivamente

La guía empieza por operaciones esenciales de contenido y añade archivos, inspección visual, colaboración y procesos:

```text
cargar y editar una Unit
→ importar y exportar archivos Office
→ inspección visual
→ edición y revisión aisladas con Worktree
→ reutilización del Runtime y Daemon
```

### 1. Cargar y editar una Unit

Establece el ciclo mínimo del AI Agent: carga con Collaboration Runtime, comprende mediante Inspection, ejecuta código Univer Facade y descubre las API Facade cuando sea necesario.

### 2. Conectar el límite de archivos Office

Usa Exchange para convertir archivos Office y UnitData. Las Units importadas permanecen en Collaboration Server; la exportación obtiene primero las UnitData más recientes mediante Collaboration Runtime.

### 3. Añadir inspección visual

La salida estructurada no describe completamente el diseño. Screenshot proporciona imágenes renderizadas al AI Agent y Layout Lint ofrece diagnósticos estructurados de diseño.

### 4. Aislar cambios con Worktree

Un AI Agent puede editar y comprobar un borrador Worktree en varias rondas. Cuando está listo, una persona lo revisa en Web y elige Merge o Reopen.

### 5. Reutilizar runtimes costosos

Empieza por runtimes de corta duración. Añade un pool, workers o daemon solo cuando importen el coste de inicio, la concurrencia o la reutilización entre procesos CLI.

## Orden de lectura recomendado

1. [Carga y operaciones de contenido](https://docs.univer.ai/es-ES/ai/content-operations.md)
2. [Importación y exportación de archivos Office](https://docs.univer.ai/es-ES/server/import-export/node.md)
3. [Inspección visual](https://docs.univer.ai/es-ES/ai/visual-inspection.md)
4. [Worktree: edición por AI Agent y revisión humana](https://docs.univer.ai/es-ES/ai/worktree.md)
5. [Reutilización del Runtime y Daemon](https://docs.univer.ai/es-ES/ai/runtime-architecture.md)
6. [Catálogo de paquetes](https://docs.univer.ai/es-ES/ai/packages.md)
7. [Ejemplos](https://docs.univer.ai/es-ES/ai/examples.md)

[^document-unit]: Una Unit es una instancia de documento, como un libro de cálculo o un documento de texto. Una hoja forma parte de un libro y no es una Unit independiente.

[^live-runtime]: Aquí, Runtime es la instancia activa de Univer y los recursos necesarios para operar sobre una Unit cargada, no el ejecutable de Node.js ni una instantánea guardada.