# AI SDK

> Comprendre comment AI SDK ajoute une CLI Node.js et un point d’entrée pour AI Agent à une application Univer.

- Human documentation: [https://docs.univer.ai/fr-FR/ai](https://docs.univer.ai/fr-FR/ai)

- Agent Markdown: [https://docs.univer.ai/fr-FR/ai.md](https://docs.univer.ai/fr-FR/ai.md)

- Requested language: `fr-FR`

- Content language: `fr-FR`

- Documentation version: `1.2.0`

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

---

Univer Office SDK comprend [Web SDK](https://docs.univer.ai/fr-FR/guides/sheets.md) pour les éditeurs intégrés et le traitement de contenu headless, [Server SDK](https://docs.univer.ai/fr-FR/server.md) pour la collaboration et l’import/export de fichiers, et [AI SDK](https://docs.univer.ai/fr-FR/ai.md) pour les workflows des agents.

**AI SDK** est un SDK TypeScript pour créer des CLI Office. Il fournit aux AI Agents et à l’automatisation un accès Node.js pour charger, comprendre, modifier et vérifier les Units[^document-unit] Univer.

AI SDK est un ensemble de capacités composables, pas une CLI de produit figée. L’application métier possède les noms de commandes, arguments, cibles, identité et autorisations, sorties et déploiement.

## Structure d’application recommandée

Ce guide utilise une application `CLI + Web + Server` :

```mermaid
flowchart LR
    Agent(["AI Agent / utilisateur CLI"]) --> CLI["<b>AI SDK</b><br/>CLI métier"]
    Human(["Utilisateur humain"]) --> Web["<b>Web SDK</b><br/>Web"]
    CLI --> Server["<b>Server SDK</b><br/>Collaboration · Conversion de fichiers"]
    Web --> Server
    Server --> Storage["Stockage"]
    classDef default rx:8,ry:8,stroke-width:1px
    classDef actor fill:transparent,stroke:none
    class Agent,Human actor
```

* CLI est le point d’entrée d’un AI Agent ou d’un utilisateur pour manipuler une Unit.
* Web présente la vraie page pour l’édition interactive et la revue humaine.
* Server conserve les Units, révisions et états collaboratifs partagés par CLI et Web.

Ces trois composants peuvent être déployés séparément ou fonctionner entièrement en local. Construire Web + Server avec Collaboration SDK avant la CLI est un parcours pédagogique recommandé, pas une contrainte de déploiement.

> [!NOTE: Les applications uniquement CLI sont aussi prises en charge]
> AI SDK peut traiter directement des Units locales. Les résultats se vérifient par sortie structurée, inspection visuelle par AI Agent ou fichiers Office exportés. Les pages Web en direct, révisions partagées, History et Worktree nécessitent les capacités Web et collaboratives correspondantes.

## Organiser la CLI avec Commander

Les paquets de base exposent des API TypeScript structurées. Les préréglages transforment les capacités courantes en objets Commander `Command` natifs. L’application métier possède toujours le programme racine :

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

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

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

await program.parseAsync();
```

* Un **préréglage de commande** fournit arguments, aide et sortie texte ou JSON par défaut.
* Une **commande applicative** compose Runtime[^live-runtime], cibles métier, identité, politique de commit ou de fichiers.
* Les deux sont des objets Commander `Command` ordinaires et peuvent cohabiter dans un même programme racine.

Chaque thème commence par la capacité de base, puis explique sa connexion à Commander.

## Construire progressivement les capacités

Le guide part des opérations essentielles sur les Units, puis ajoute fichiers, inspection visuelle, collaboration et processus :

```text
charger et modifier une Unit
→ importer et exporter des fichiers Office
→ inspection visuelle
→ édition et revue isolées avec Worktree
→ réutilisation du Runtime et Daemon
```

### 1. Charger et modifier une Unit

Établissez la boucle minimale d’un AI Agent : charger avec Collaboration Runtime, comprendre le contenu avec Inspection, exécuter du code Univer Facade et découvrir les API Facade au besoin.

### 2. Connecter la frontière des fichiers Office

Utilisez Exchange pour convertir fichiers Office et UnitData. Les Units importées restent sur Collaboration Server ; l’export récupère d’abord les dernières UnitData via Collaboration Runtime.

### 3. Ajouter l’inspection visuelle

Une sortie structurée ne décrit pas toute la mise en page. Screenshot fournit les images rendues à l’AI Agent, tandis que Layout Lint fournit des diagnostics structurés de disposition.

### 4. Isoler les changements avec Worktree

Un AI Agent peut modifier et vérifier un brouillon Worktree pendant plusieurs cycles. Une fois prêt, une personne le révise dans Web et choisit Merge ou Reopen.

### 5. Réutiliser les runtimes coûteux

Commencez par des runtimes éphémères. Ajoutez pool, workers ou daemon seulement lorsque le coût de démarrage, la concurrence ou la réutilisation entre processus CLI devient important.

## Ordre de lecture recommandé

1. [Chargement et opérations de contenu](https://docs.univer.ai/fr-FR/ai/content-operations.md)
2. [Import-export de fichiers Office](https://docs.univer.ai/fr-FR/server/import-export/node.md)
3. [Inspection visuelle](https://docs.univer.ai/fr-FR/ai/visual-inspection.md)
4. [Worktree : édition par AI Agent et revue humaine](https://docs.univer.ai/fr-FR/ai/worktree.md)
5. [Réutilisation du Runtime et Daemon](https://docs.univer.ai/fr-FR/ai/runtime-architecture.md)
6. [Catalogue des paquets](https://docs.univer.ai/fr-FR/ai/packages.md)
7. [Exemples](https://docs.univer.ai/fr-FR/ai/examples.md)

[^document-unit]: Une Unit est une instance de document, par exemple un classeur ou un document texte. Une feuille appartient à un classeur et ne constitue pas une Unit distincte.

[^live-runtime]: Ici, Runtime désigne l’instance Univer active et les ressources nécessaires pour manipuler une Unit chargée, et non l’exécutable Node.js ou un instantané enregistré.