Agents et automatisation

AI SDK expose les modèles, Facades et services collaboratifs Univer sous forme de capacités TypeScript pour un Agent existant. Il peut comprendre, modifier, vérifier puis soumettre le contenu à une revue. Votre application choisit modèle, protocole des outils et orchestration.

Connecter les capacités à l’Agent

Les capacités renvoient des résultats structurés pour outils, services ou CLI. Les paquets -command facultatifs proposent des commandes Commander natives. L’Agent utilise le modèle de contenu et le système de commandes communs à l’éditeur Web.

Restaurer un état modifiable

Un Collaboration Runtime reste lié à une Unit. Il ouvre le backend de l’application, lit un checkpoint UnitData ou Snapshot, rejoue ses changesets et complète les révisions continues jusqu’à la tête distante. Si le module de formules est installé, il attend aussi l’application du dernier calcul.

fetch() récupère et valide les changements. pull() les réconcilie avec pending/awaiting par OT, puis les applique. baseRevision, knownHeadRevision, pendingMutationCount et awaitingChangeset rendent l’état observable.

Localiser avant d’exécuter une Facade

Commencez par overview puis ciblez des ID stables ou sélecteurs précis, sans envoyer tout le Snapshot au modèle. Inspection couvre plages Sheet, paragraphes Doc, pages Slide, schéma Relational Table et objets Canvases. L’aperçu Relational Table inclut la configuration des champs, mais pas les valeurs ni View projection ; lisez-les via Facade si nécessaire.

prepareContentExecutionProgram() résout la Facade racine par Unit ID sans dépendre de la sélection Web et refuse de redéclarer les variables injectées. Le mode read bloque les actions métier persistantes avant exécution ; write capture les mutations de l’Unit cible. Création et destruction d’Units relèvent d’opérations de cycle de vie distinctes.

Utilisez find() pour découvrir les API et show() pour leurs déclarations et types exacts. L’index fourni fonctionne sans moteur ni documentation en ligne. Voir opérations de contenu et paquets.

Exécution et persistance confirmée

execute({ mode: 'write' }) modifie l’Unit en mémoire et accumule pending. Cela ne confirme pas l’enregistrement côté serveur. commit() envoie un changeset identifié et valide identité, contenu et revision de l’ACK avant confirmation.

Un résultat incertain conserve sid + reqId pour faire confirmer le même changeset de manière idempotente. Le backend doit respecter ce contrat. Une exception peut laisser des mutations déjà effectuées : examinez pending avant de choisir la récupération. execute() ne constitue pas une transaction à annulation automatique.

L’exemple reçoit un Runtime Sheet chargé et renvoie exécution et état de commit. L’appelant traite ces états et ferme le Runtime à la fin de son cycle de propriété.

import { prepareContentExecutionProgram } from '@univer-cli/content-execution'import type { UniverCollaborationRuntime } from '@univer-cli/univer-collaboration-runtime'async function updateSales(runtime: UniverCollaborationRuntime) {  const pulled = await runtime.pull()  if (pulled.status === 'conflict') return pulled  const code = prepareContentExecutionProgram({    unitId: runtime.unitId,    unitType: 'sheet',    code: `      const sheet = workbook.getSheetByName('Data');      if (!sheet) throw new Error('Worksheet Data not found');      sheet.getRange('A2:B2').setValues([        [{ v: 'East', t: 1 }, { v: 128000, t: 2 }]      ]);      return sheet.getRange('A2:B2').getRawValues();    `,  })  const execution = await runtime.execute({ mode: 'write', code })  const commit = await runtime.commit()  return { execution, commit }}

Réutiliser les Runtimes

Le pool prête exclusivement un Worker Runtime par key applicative. La création à froid est single-flight et les leases suivent FIFO ; des keys différentes peuvent utiliser des Workers distincts. release() rend l’instance, TTL/LRU récupère les ressources inactives et invalidate() retire une instance non fiable.

La key doit distinguer backend, Unit et Worktree. Le pool ne vérifie pas la compatibilité sémantique des init. Un daemon conserve le pool entre appels CLI courts, mais synchronisation et confirmation restent nécessaires. Équilibrez démarrage, mémoire résidente et Workers ; voir réutilisation et daemon.

De l’automatisation à la revue humaine

Composez rapports, nettoyage, remplissage de modèles ou génération : localisez, écrivez via Facade, attendez les calculs nécessaires, relisez valeurs, textes et attributs, puis ajoutez une inspection visuelle au besoin.

Pour une approbation, ciblez un Worktree. L’Agent édite et vérifie, marque Ready et une personne décide Merge. Suivez les résultats par Unit : plusieurs Runtimes ne forment pas une transaction atomique entre documents.

L’application gère identité, droits, modèle et tâches. Les restrictions read/write protègent les opérations métier ; l’isolation des processus et les droits fichiers/réseau du JavaScript non fiable restent aussi applicatifs. Essayez le démarrage rapide et l’exemple CLI.

Retour aux fonctionnalités