Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Exploiter AX Code pour un travail de longue durée

Statut : actif Portée : état actuel Dernière revue : 2026-09-13 Responsable : mainteneurs d’AX Code

AX Code borne une exécution interactive Super-Long à 72 heures. Pour une exploitation sur des jours ou des semaines, lancez un processus ax-code serve supervisé et divisez le travail en occurrences planifiées durables. Le superviseur redémarre le serveur ; la base du projet conserve les planifications et l’état de la file.

Espace de travail interactif persistant

Pour un travail local qui doit continuer après la fermeture du terminal, activez un runtime de projet :

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

runtime attach démarre aussi le runtime lorsqu’il n’en existe pas. Le runtime est indexé par le répertoire canonique du projet ; des démarrages simultanés réutilisent un seul processus. Le TUI montre son hôte d’exécution et une action Déconnecter. Déconnecter ferme le client et laisse le travail accepté continuer. runtime stop arrête le runtime de ce projet et interrompt son travail actif. Un ax-code ordinaire conserve son cycle de vie au premier plan existant.

Les suites acceptées, soumises pendant qu’une session est occupée, sont enregistrées sur le serveur. Par défaut, elles démarrent après la fin du tour en cours, afin qu’une requête sans lien ne détourne pas le travail en cours. Pour corriger le tour en cours à la place, appuyez sur ctrl+s (input_submit_steer dans keybinds) avec un brouillon seulement texte : le texte est admis dans la génération active et écrit comme message utilisateur à la prochaine frontière d’étape de la boucle, après que les appels d’outils en cours se stabilisent et avant la requête de modèle suivante. Une correction admise pendant que le tour se termine prolonge l’exécution d’une itération au lieu d’être abandonnée. Le pilotage est au mieux : si plus aucune génération n’est active, le brouillon est envoyé par le chemin ordinaire ; si un crochet le refuse, le brouillon reste dans le compositeur avec la raison. Les brouillons avec pièces jointes et commandes slash utilisent toujours la file des suites. La même livraison est offerte aux autres clients par l’API de pilotage décrite dans les contrôles du harnais. Les suites enregistrées peuvent aussi être pilotées après coup : appuyer sur ctrl+s avec un compositeur vide promeut, dans l’ordre, le préfixe pilotable de la file et s’arrête à la première ligne non pilotable. La section Suites de la barre latérale et la boîte /queue offrent la même action de pilotage immédiat par ligne. Les lignes en pause sont pilotables sur place : interrompre un tour met en pause les suites en attente, et en piloter une livre son texte sans reprendre le reste de la file. Seules les lignes qui ne sont pas des suites (commandes slash en file, commandes shell), les lignes avec pièces jointes, le texte vide ou trop long, et les lignes déjà en cours ou terminées sont des barrières. Les lignes pilotées sont annulées avec une piste d’audit steeredInto et restent visibles dans l’historique /queue. Lorsqu’aucune génération n’est active, le pilotage immédiat revient à placer la ligne en tête de file : elle ne démarre encore qu’après la fin du tour. Le compositeur ne se vide qu’après l’accusé de réception. Rattachez-vous à la même session et utilisez /queue pour inspecter, mettre en pause, modifier, reprendre ou annuler ces éléments. Modifier met d’abord l’élément en pause et conserve les pièces jointes et la sélection de modèle ; enregistrer ne le reprend pas. Les modifications périmées simultanées sont rejetées. Dans /queue, Ctrl+R inclut l’historique terminé et annulé. Les terminaux étroits montrent aussi un titre Follow-ups cliquable. Une vue déconnectée est mise en cache et ne peut pas changer les éléments. Interrompre le tour actif met en pause les suites en attente, afin qu’elles ne démarrent pas immédiatement un autre tour. Reprenez-les explicitement lorsque vous êtes prêt.

Après un redémarrage du backend, les suites en attente déjà acceptées peuvent reprendre. Une invite ordinaire en cours, interrompue par ce redémarrage, est marquée en échec et exige une inspection avant un nouvel essai ; restaurer les enregistrements de file ne restaure pas un processus shell en cours d’exécution. Un accusé perdu peut être réessayé depuis le compositeur inchangé, avec la même identité de requête, pendant cette session client. Les brouillons non enregistrés ne sont pas des travaux acceptés, et cela ne garantit pas des effets externes exactement une fois.

Ce mode n’installe pas de service lancé à la connexion, ne redémarre pas automatiquement un serveur planté et n’exécute rien pendant que l’hôte dort ou est éteint. Démarrez ou rattachez de nouveau après un plantage ; utilisez les exemples de service supervisé plus bas pour des redémarrages de serveur sans surveillance. Les utilisateurs SSH doivent exécuter le runtime sur un hôte distant éveillé et s’y attacher. N’exposez pas le port HTTP publiquement.

La découverte du runtime stocke une capacité privée et un journal dans le dossier runtime/ du répertoire d’état d’AX Code. La sortie de statut omet la capacité. L’arrêt exige une identité de runtime authentifiée et correspondante, pas seulement un PID enregistré. Un processus en direct indisponible, un enregistrement corrompu ou un écart de version exige une inspection ; la CLI refuse de tuer un processus non vérifié. Arrêtez un runtime sain avant une mise à niveau, puis redémarrez-le avec le nouvel exécutable.

Modèle de fiabilité

C’est une reprise sûre face aux doublons, pas une livraison exactement une fois pour des effets externes arbitraires. Les intégrations qui écrivent vers des systèmes externes doivent encore utiliser leurs propres clés d’idempotence.

Avant d'installer un service

1. Installez et testez l’exécutable ax-code sous le même utilisateur qui exécutera le service.
2. Choisissez un chemin de projet absolu. Définissez-le comme AX_CODE_PROJECT afin que le démarrage du serveur préchauffe ce projet et démarre son planificateur.
3. Gardez le serveur sur 127.0.0.1 ; le serveur d’AX Code est seulement local.
4. Placez les authentifiants des fournisseurs dans l’environnement protégé du superviseur, plutôt que dans un fichier de service validé dans le dépôt.
5. Remplacez chaque marque de substitution /absolute/path/... de l’exemple choisi.

Les exemples utilisent un port fixe, afin que les clients Desktop ou SDK puissent se reconnecter :

ax-code serve --hostname=127.0.0.1 --port=4096

Service utilisateur systemd

Copiez l’exemple systemd vers ~/.config/systemd/user/ax-code.service, remplacez ses chemins absolus et placez au choix les authentifiants dans ~/.config/ax-code/server.env.

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

N’utilisez loginctl enable-linger "$USER" que si votre politique d’exploitation permet au service utilisateur de tourner lorsque l’utilisateur est déconnecté.

Agent launchd

Copiez l’exemple launchd vers ~/Library/LaunchAgents/com.axcode.server.plist, remplacez ses chemins absolus, puis validez-le et chargez-le :

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd ne développe pas les variables de shell dans ProgramArguments. Utilisez des chemins absolus et fournissez les authentifiants nécessaires par un mécanisme géré par l’opérateur.

Processus PM2

Copiez l’exemple PM2, remplacez ses chemins et démarrez-le :

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

Suivez les instructions de démarrage propres à la plateforme de PM2 si le processus doit revenir après un redémarrage de l’hôte.

Échéances, rattrapage et reprise

Les tâches planifiées ont catchUpPolicy: "run_once" par défaut. Après un arrêt, AX Code exécute une occurrence fusionnée, au lieu de créer un arriéré non borné. Choisissez "skip" lorsqu’un travail en retard serait trompeur ou dangereux.

Chaque tâche planifiée peut définir maxRunDurationMs, de 1 seconde à 72 heures. Sinon, l’exécution de la file de tâches utilise le plafond de 72 heures. Les éléments actifs mettent à jour un horodatage de battement toutes les 30 secondes, et le statut final ainsi que les détails d’erreur restent dans la base du projet.

Les points de terminaison asynchrones d’invite, de commande et de shell renvoient l’élément de file durable dans leur réponse HTTP 202. Les clients doivent conserver son id et interroger GET /task-queue/:id jusqu’à completed, failed ou cancelled ; l’acceptation seule n’est pas l’achèvement.

Au démarrage, un backend AX Code persistant reprend les éléments de file planifiés et les éléments asynchrones explicitement marqués qui ont été validés mais n’avaient pas démarré. Les commandes CLI ponctuelles ne prennent pas possession de ces éléments. Le travail d’invite déjà démarré est marqué en échec, avec une explication de redémarrage, afin qu’un opérateur puisse inspecter les effets de bord avant de réessayer.

Voir ce que font les tâches planifiées

Chaque occurrence de tâche planifiée est visible pendant qu’elle se produit, et auditable ensuite :

• Le démarrage, l’achèvement, l’échec, le saut et les pauses automatiques après échec persistant soulèvent chacun une notification dans l’application, qui nomme la tâche.
• La commande TUI /schedule liste chaque tâche avec son statut, sa planification, l’heure de la prochaine exécution et la dernière erreur, et ouvre son historique d’exécutions récentes. De là, vous pouvez mettre en pause, reprendre, exécuter maintenant, supprimer (appuyez deux fois sur ctrl+d pour confirmer) et aller à la session qu’une exécution a produite. Les outils d’agent list_scheduled_tasks et list_scheduled_task_runs répondent aux mêmes questions en conversation.
• Chaque exécution se fait dans une nouvelle session titrée du titre de la tâche, donc les résultats sont à une entrée de la liste des sessions, même si une notification a été manquée.
• Si une exécution demande une permission ou une réponse pendant que vous regardez une autre conversation, un avertissement nomme la session qui a besoin de vous ; /attention liste les demandes en attente connues et ouvre la session demandeuse. On peut répondre dans cette session ou dans la vue d’un ancêtre chargé, y compris les sessions enfants et petites-enfants. Ouvrir une demande ne l’approuve jamais automatiquement.
• Une tâche ponctuelle n’est désactivée qu’après une exécution réussie. Une occurrence en échec réessaie avec une attente bornée, et les échecs répétés mettent la tâche en pause avec une notification : un rappel ne peut plus disparaître en silence.

Contrôles opérationnels

• Surveillez le compte de redémarrages du superviseur et les journaux du serveur.
• Inspectez les éléments de file en échec et les erreurs des tâches planifiées avant de réessayer.
• Confirmez qu’il y a assez d’espace disque pour la base SQLite du projet et les journaux.
• Lancez un exécuter maintenant manuel après un changement d’authentifiants, de modèles ou de chemins de service.
• Arrêtez par le superviseur, afin qu’AX Code reçoive SIGTERM ; les exemples accordent jusqu’à 90 secondes pour un arrêt gracieux.

/loop est volontairement local au processus et ne survit pas à un redémarrage. Utilisez les tâches planifiées pour un travail durable sans surveillance.

Naviguer entre des sessions parallèles

À partir de 146 colonnes de terminal, une barre de navigation à gauche montre les sessions de l’espace de travail courant et leurs agents enfants chargés. Dépliez une ligne avec son contrôle + et cliquez sur un titre pour l’ouvrir. Les sessions épinglées gardent leur ordre et leurs numéros de raccourci. Les libellés d’activité complets distinguent le travail, le nouvel essai, les approbations et les questions ; les parents reflètent aussi les demandes des descendants. Ces libellés ne signifient pas qu’une tâche a passé la vérification. La barre latérale droite existante conserve le contexte et les contrôles de la session courante.

Le titre Projet identifie le répertoire courant. Cliquez dessus ou utilisez /navigation-info pour voir le chemin complet du projet et le titre de la session courante. Récent montre les sessions chargées ; Actif conserve les arbres de sessions au travail ou en attente, ainsi que l’arbre de la session courante. Le filtre est partagé avec le sélecteur de navigation et mémorisé. Utilisez /navigation-filter pour le basculer au clavier. Pendant une déconnexion, il montre les sessions en cache, plutôt que d’inférer quelles sessions sont actives. Effacer (ou /navigation-clear) demande une confirmation, puis masque les lignes historiques du rail gauche et du sélecteur de navigation seulement. Cela ne supprime pas les sessions ; /sessions les liste encore. L’arbre de la session courante, les sessions épinglées et les arbres observés au travail ou en attente restent sur le rail. Ouvrir une session depuis /sessions la ramène dans la liste.

Utilisez /navigation-width ou l’action Largeur de la navigation pour choisir 20, 24, 28, 30, 32, 36 ou 40 colonnes (28 par défaut). La barre latérale de session de droite a la même action Largeur et /sidebar-width (32 par défaut). Les deux préférences sont mémorisées et se réduisent automatiquement au besoin, afin de préserver le contenu principal. Utilisez /navigation pour masquer ou restaurer le rail de navigation gauche sur les terminaux larges. /sidebar masque ou restaure la barre latérale de session droite de la même façon. Sur les terminaux plus étroits, /navigation ouvre à la place un sélecteur de sessions et d’agents. Une barre Sessions visible fournit la même action chaque fois que le rail de navigation est absent. Son action En attente apparaît lorsque des demandes connues ont besoin d’une saisie ; un astérisque marque un compte en cache pendant la déconnexion. /sessions continue d’ouvrir le sélecteur de sessions normal. /attention est disponible à chaque largeur. Pendant la déconnexion, sa liste est libellée comme mise en cache ; ouvrir les entrées en cache reste possible, mais les demandes peuvent déjà avoir reçu une réponse ailleurs. L’action Demandes connues de la barre latérale ouvre les demandes en attente des espaces de travail connus, tandis que son arbre de sessions reste limité au projet courant. Toutes ces vues sont bornées par l’instance connectée et les données de session chargées ; ce compte n’est pas un inventaire complet des autres serveurs ni des espaces de travail non chargés.

Les brouillons non envoyés sont isolés par projet et par session dans le TUI en cours. Changer de session conserve le texte, les pièces jointes, la position du curseur et le mode shell ; revenir restaure le brouillon correspondant. Ces brouillons ne sont qu’en mémoire et ne survivent pas à la fermeture du TUI.

La notification d’achèvement facultative dit désormais Session idle. Elle suit le travail observé dans le sous-arbre de la session regardée et attend que les descendants actifs observés deviennent explicitement inactifs, sans demande en attente. Les déconnexions, les resynchronisations, un état manquant, les erreurs et l’annulation peuvent supprimer l’avis. C’est une notification de cycle de vie, pas une preuve que les tests ont réussi ou qu’un objectif est atteint.

Nouvelles tâches et configuration

Le démarrage normal ouvre la surface de travail Nouvelle tâche, avec un compositeur en bas et la navigation des sessions. L’ouvrir ou saisir un brouillon ne crée pas de session enregistrée ; une session est créée à l’envoi. Utilisez /sessions ou la navigation gauche pour reprendre un travail existant. Le comportement explicite de --session, --continue et --prompt reste disponible ; le démarrage n’active pas la reprise automatique.

La configuration des fournisseurs ne s’ouvre pas automatiquement. Utilisez l’action visible /connect dans la zone de travail lorsqu’aucun fournisseur n’est configuré. Lorsqu’un fournisseur est configuré mais qu’aucun modèle valide n’est choisi, l’action devient /models. Une découverte de fournisseur en échec pointe vers /status ; /connect et /providers restent disponibles pour réparer la configuration. Un modèle choisi est un choix de configuration, pas un contrôle d’authentifiant ni de préparation du runtime. Les indications apparaissent aussi pour les utilisateurs de retour dont la configuration demande attention.