Worktree
Comprenez l’isolation, les révisions de référence, la fusion OT et la connexion d’AI SDK aux agents et à la relecture.
Worktree fournit des brouillons Office isolés et collaboratifs. Un agent peut modifier un budget, des données ou un document pendant que les utilisateurs travaillent sur le document principal (trunk). Les changements sont fusionnés après validation et relecture.
L’isolation concerne le contenu et les changements, pas un répertoire Git. Une tâche peut contenir plusieurs Units, comme un classeur, un document et une présentation.
Isolation : évoluer depuis une référence commune
Pour une Unit existante, la création enregistre sa révision trunk comme baseline. Le brouillon utilise snapshots, changesets, révisions, Presence et Rooms indépendants. Les modifications intermédiaires restent hors du trunk.
| Notion | Rôle |
|---|---|
| Baseline | Révision de départ dans trunk, référence de comparaison et fusion. |
| Draft head | Dernière révision confirmée du brouillon. |
| Ready head | Révision figée qui définit la portée de la relecture et fusion. |
Trunk et brouillon avancent séparément. Leurs numéros décrivent des séquences distinctes et ne suffisent pas à comparer l’actualité du contenu. Synchroniser le brouillon n’y ajoute pas automatiquement les changements trunk ; ils sont réconciliés lors de l’aperçu ou de la fusion.
Comment AI SDK rejoint le même brouillon
Le Collaboration Runtime d’AI SDK traite snapshots, changements et révisions d’une Unit. Le service Worktree de Server SDK gère création, états et fusion, sans exiger un autre moteur d’édition.
L’application résout worktreeID + unitID en URL de snapshot, soumission, WebSocket et Session Ticket du brouillon, puis les transmet au Runtime. Les mêmes outils servent au trunk ou au brouillon.
Un même Unit ID peut exister dans trunk et plusieurs Worktrees. Inspection, exécution, captures et aperçu Web doivent viser la même cible pour éviter de lire le brouillon et écrire dans trunk. Web utilise sa configuration collaborative correspondante.
| Élément | Responsabilité |
|---|---|
| Web SDK | Moteur commun pour Headless et édition navigateur. |
| Server SDK | Isolation, stockage des changements et révisions, états et OT. |
| AI SDK | Runtime, Inspection, recherche API, exécution Facade et contrôles visuels. |
| Votre application | Modèle, cibles, identité, autorisation, tâches et interface de relecture. |
De l’édition à la remise
L’application peut organiser des tâches parallèles avec un Worktree distinct par agent. Chaque agent modifie, vérifie et passe son brouillon à Ready. Une personne les relit individuellement, rouvre le brouillon concerné si nécessaire et fusionne les changements acceptés avec le trunk actuel.
- Créez le brouillon, sélectionnez les Units, connectez la cible Worktree et faites
pull. - Inspectez structure et données, cherchez les API au besoin et modifiez avec Facade.
- Soumettez au brouillon, relisez données et calculs. Ajoutez des captures si nécessaire, Layout Lint pour Slides, et recommencez si besoin.
- Passez à Ready pour figer les révisions et arrêter l’édition durant la relecture.
- Fusionnez après validation ; utilisez Reopen avant toute reprise humaine ou agent, ou Discard pour abandonner.
| Opération | Effet |
|---|---|
runtime.commit() | Soumet seulement au brouillon et avance sa révision. |
markReady() | Fige la version à relire, sans fusion. |
reopenWorktree() | Revient de Ready à Draft et permet l’édition. |
mergeWorktree() | Fusionne les changements figés Unit par Unit. |
Commit, Ready et Merge sont distincts. Un humain comme un agent doit rouvrir un brouillon Ready avant de modifier. Voir le guide AI SDK.
Appliquer les changements au trunk actuel
Pour une Unit issue de trunk, le serveur lit les changesets de la baseline au Ready head, rassemble les mutations et les soumet au Collaboration Service principal. Si trunk a avancé, OT les transforme face aux modifications ultérieures, puis confirme une nouvelle révision.
La fusion applique des changements au lieu de remplacer le document actuel par un ancien snapshot. Une transformation ou application impossible renvoie un conflit à traiter. OT ne tranche pas tous les désaccords métier.
Une Unit créée dans le brouillon n’a pas de baseline trunk. La fusion la crée dans trunk sans recopier tout son historique de changesets.
Relire les changements et leur intégration
- Qu’a-t-on changé ? Comparez les états complets baseline et Ready avec Compare.
- Que donnerait une fusion maintenant ? Après Ready, appelez
evaluateUnitMerge(). Si trunk a avancé, un Runtime isolé applique le candidat transformé par OT au trunk actuel pour produire un aperçu en lecture seule. Aucun changeset n’est soumis et aucun côté n’est modifié.
L’aperçu reflète l’instant de la demande ; Merge utilise l’état au moment de son exécution. Une fusion multi-Unit n’est pas atomique : les réussites restent acquises si une autre Unit échoue. Affichez et traitez les résultats individuellement.
Intégration et périmètre
Assemblez Worktree Client, Service, Endpoint et adaptateurs avec le noyau collaboratif. Séparez les stockages et partagez Session Ticket Store avec trunk. L’application autorise séparément accès au brouillon et écriture trunk : isoler ne donne pas de droits.
Sheet, Doc, Slide, Canvases et Relational Table sont couverts, pas PDF. Consultez l’exemple, les modules et le guide agent.
Que pensez-vous de ce guide ?