Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Gestire AX Code per il lavoro di lunga durata

Stato: Attivo Ambito: stato attuale Ultima revisione: 2026-09-13 Responsabile: responsabili di AX Code

AX Code limita una singola esecuzione interattiva Super-Long a 72 ore. Per operare su giorni o settimane, esegui un processo ax-code serve supervisionato e dividi il lavoro in occorrenze pianificate durevoli. Il supervisore riavvia il server; il database del progetto conserva le pianificazioni e lo stato della coda.

Workspace interattivo persistente

Per il lavoro locale che deve continuare dopo la chiusura del terminale, aderisci a un runtime di progetto:

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 avvia anche il runtime quando non ne esiste uno. Il runtime è identificato dalla directory canonica del progetto; gli avvii concorrenti riusano un solo processo. La TUI mostra l’host di esecuzione e un’azione Disconnect. Scollegarsi chiude il client e tiene in esecuzione il lavoro accettato. runtime stop spegne il runtime di quel progetto e interrompe il suo lavoro attivo. Un ax-code ordinario conserva il suo ciclo di vita in primo piano esistente.

I seguiti accettati, inviati mentre una sessione è occupata, vengono salvati sul server. Per impostazione predefinita partono dopo la fine del turno in corso, così una richiesta non correlata non fa deragliare il lavoro in corso. Per correggere invece il turno in corso, premi ctrl+s (input_submit_steer in keybinds) con una bozza di solo testo: il testo viene ammesso nella generazione attiva e scritto come messaggio utente al confine del passo successivo del ciclo, dopo che le chiamate di strumenti in corso si assestano e prima della richiesta di modello successiva. Una correzione ammessa mentre il turno sta finendo prolunga l’esecuzione di un’iterazione, invece di essere scartata. Lo sterzo è best-effort: se non c’è più una generazione attiva, la bozza viene inviata dal percorso ordinario; se un hook la vieta, la bozza resta nel compositore con la ragione. Le bozze con allegati e i comandi slash usano sempre la coda dei seguiti. La stessa consegna è disponibile agli altri client tramite l’API di sterzo descritta nei controlli del harness. I seguiti salvati si possono anche sterzare dopo: premere ctrl+s con un compositore vuoto promuove in ordine il prefisso sterzabile della coda e si ferma alla prima riga non sterzabile, e la sezione Follow-ups della barra laterale e la finestra /queue offrono la stessa azione di sterzo immediato per riga. Le righe in pausa sono sterzabili sul posto: interrompere un turno mette in pausa i seguiti in attesa, e sterzarne uno consegna il suo testo senza riprendere il resto della coda. Sono barriere solo le righe che non sono seguiti (comandi slash in coda, comandi di shell), le righe con allegati, il testo vuoto o troppo grande e le righe già in esecuzione o finite. Le righe sterzate vengono annullate con una traccia di audit steeredInto e restano visibili nella cronologia /queue. Quando nessuna generazione è attiva, lo sterzo immediato ripiega sul mettere la riga in testa alla coda: parte comunque solo dopo la fine del turno. Il compositore si svuota solo dopo la conferma. Riagganciati alla stessa sessione e usa /queue per ispezionarli, metterli in pausa, modificarli, riprenderli o annullarli. Modificare prima mette in pausa l’elemento e conserva allegati e selezione del modello; salvare non lo riprende. Le modifiche stantie concorrenti vengono rifiutate. In /queue, Ctrl+R include la cronologia completata e annullata. Anche i terminali stretti mostrano un’intestazione Follow-ups cliccabile. Una vista scollegata è in cache e non può cambiare gli elementi. Interrompere il turno attivo mette in pausa i seguiti in attesa, così non avviano subito un altro turno. Riprendili in modo esplicito quando sei pronto.

Dopo un riavvio del backend, i seguiti accettati e in attesa possono riprendere. Un prompt ordinario in corso, interrotto da quel riavvio, è marcato come fallito e richiede un’ispezione prima del nuovo tentativo; ripristinare i record della coda non ripristina un processo di shell in esecuzione. Una conferma persa si può ritentare dal compositore invariato con la stessa identità di richiesta, durante quella sessione del client. Le bozze non salvate non sono lavori accettati, e questo non garantisce effetti esterni esattamente una volta.

Questa modalità non installa un servizio di accesso, non riavvia in automatico un server andato in crash e non esegue mentre l’host dorme o è spento. Avvia o riaggancia dopo un crash; usa gli esempi di servizio supervisionato sotto per i riavvii non presidiati del server. Gli utenti SSH dovrebbero eseguire il runtime su un host remoto sveglio e agganciarsi lì. Non esporre in pubblico la porta HTTP.

La scoperta del runtime memorizza una capacità privata e un log sotto la cartella runtime/ della directory di stato di AX Code. L’output di stato omette la capacità. Lo spegnimento richiede un’identità di runtime autenticata e corrispondente, non solo un PID salvato. Un processo vivo non disponibile, un record corrotto o una discordanza di versione richiedono un’ispezione; la CLI rifiuta di uccidere un processo non verificato. Ferma un runtime sano prima di aggiornare e riavvialo con il nuovo eseguibile.

Modello di affidabilità

Questo è un recupero sicuro rispetto ai duplicati, non una consegna esattamente una volta per effetti esterni arbitrari. Le integrazioni che scrivono su sistemi esterni dovrebbero usare comunque le proprie chiavi di idempotenza.

Prima di installare un servizio

1. Installa e prova l’eseguibile ax-code come lo stesso utente che eseguirà il servizio.
2. Scegli un percorso assoluto di progetto. Impostalo come AX_CODE_PROJECT così l’avvio del server preriscalda quel progetto e avvia il suo scheduler.
3. Tieni il server su 127.0.0.1; il server di AX Code è solo locale.
4. Metti le credenziali del provider nell’ambiente protetto del supervisore, anziché in un file di servizio committato.
5. Sostituisci ogni segnaposto /absolute/path/... nell’esempio scelto.

Gli esempi usano una porta fissa, così i client Desktop o SDK possono ricollegarsi:

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

Servizio utente systemd

Copia l’esempio systemd in ~/.config/systemd/user/ax-code.service, sostituisci i percorsi assoluti e, in opzione, metti le credenziali in ~/.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

Usa loginctl enable-linger "$USER" solo se la policy operativa consente al servizio utente di girare mentre l’utente è disconnesso.

Agente launchd

Copia l’esempio launchd in ~/Library/LaunchAgents/com.axcode.server.plist, sostituisci i percorsi assoluti, poi validalo e caricalo:

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 non espande le variabili di shell in ProgramArguments. Usa percorsi assoluti e fornisci le credenziali necessarie tramite un meccanismo gestito dall’operatore.

PM2

Copia l’esempio PM2, sostituisci i percorsi e avvialo:

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

Segui le istruzioni di avvio specifiche della piattaforma di PM2 se il processo deve tornare dopo un riavvio dell’host.

Scadenze, recupero del ritardo e ripristino

I compiti pianificati usano per impostazione predefinita catchUpPolicy: "run_once". Dopo un fermo, AX Code esegue una sola occorrenza fusa, invece di creare un arretrato senza limite. Scegli "skip" quando il lavoro in ritardo sarebbe fuorviante o non sicuro.

Ogni compito pianificato può impostare maxRunDurationMs da 1 secondo fino a 72 ore. Altrimenti l’esecuzione della coda dei compiti usa il tetto di 72 ore. Gli elementi attivi aggiornano una marca temporale di heartbeat ogni 30 secondi, e lo stato terminale e i dettagli di errore restano nel database del progetto.

Gli endpoint asincroni di prompt, comando e shell restituiscono l’elemento di coda durevole nella loro risposta HTTP 202. I client dovrebbero conservare il suo id e interrogare GET /task-queue/:id finché completed, failed o cancelled; la sola accettazione non è il completamento.

All’avvio, un backend AX Code persistente riprende gli elementi di coda pianificati e gli elementi asincroni marcati in modo esplicito che erano stati committati ma non erano partiti. I comandi CLI una tantum non prendono possesso di quegli elementi. Il lavoro di prompt già avviato viene fatto fallire con una spiegazione di riavvio, così un operatore può ispezionare gli effetti collaterali prima di ritentare.

Vedere che cosa fanno i compiti pianificati

Ogni occorrenza di un compito pianificato è visibile mentre accade e auditabile dopo:

• Avvio, completamento, fallimento, salto e le pause automatiche per fallimento persistente alzano ciascuna una notifica nell’app che nomina il compito.
• Il comando TUI /schedule elenca ogni compito con stato, pianificazione, orario della prossima esecuzione e ultimo errore, e apre la cronologia recente delle esecuzioni. Da lì puoi mettere in pausa, riprendere, eseguire ora, cancellare (premi ctrl+d due volte per confermare) e saltare alla sessione prodotta da un’esecuzione. Gli strumenti dell’agente list_scheduled_tasks e list_scheduled_task_runs rispondono alle stesse domande in conversazione.
• Ogni esecuzione avviene in una sessione nuova intitolata con il titolo del compito, così i risultati sono a una voce dell’elenco sessioni di distanza, anche se una notifica è stata persa.
• Se un’esecuzione chiede un’autorizzazione o una risposta a una domanda mentre stai guardando una conversazione diversa, un avviso nomina la sessione che ha bisogno di te; /attention elenca le richieste in attesa note e apre la sessione richiedente. Le richieste si possono rispondere in quella sessione o nella vista di un antenato caricato, incluse le sessioni figlie e nipoti. Aprire una richiesta non la approva mai in automatico.
• Un compito una tantum viene disattivato solo dopo un’esecuzione riuscita. Un’occorrenza fallita ritenta con un backoff limitato, e i fallimenti ripetuti mettono in pausa il compito con una notifica: un promemoria non può più sparire in silenzio.

Controlli operativi

• Osserva il conteggio di riavvii del supervisore e i log del server.
• Ispeziona gli elementi falliti della coda dei compiti e gli errori dei compiti pianificati prima di ritentare.
• Conferma che ci sia abbastanza spazio disco per il database SQLite del progetto e i log.
• Esercita un run now manuale dopo aver cambiato credenziali, modelli o percorsi del servizio.
• Ferma tramite il supervisore, così AX Code riceve SIGTERM; gli esempi consentono fino a 90 secondi per uno spegnimento ordinato.

/loop è di proposito locale al processo e non sopravvive a un riavvio. Usa i compiti pianificati per il lavoro non presidiato durevole.

Navigare le sessioni parallele

A 146 colonne di terminale o più, una barra di navigazione a sinistra mostra le sessioni del workspace corrente e i loro agenti figli caricati. Espandi una riga con il suo controllo + e fai clic su un titolo per aprirlo. Le sessioni fissate conservano ordine e numeri di scorciatoia. Le etichette di attività complete distinguono lavoro in corso, tentativi, approvazioni e domande; anche i genitori riflettono le richieste dei discendenti. Queste etichette non significano che un compito abbia superato la verifica. La barra laterale destra esistente tiene il contesto e i controlli della sessione corrente.

L’intestazione Project identifica la directory corrente. Fai clic su di essa o usa /navigation-info per vedere il percorso completo del progetto e il titolo della sessione corrente. Recent mostra le sessioni caricate; Active tiene gli alberi di sessione in lavoro o in attesa e l’albero della sessione corrente. Il filtro è condiviso con il selettore di navigazione e viene ricordato. Usa /navigation-filter per attivarlo o disattivarlo da tastiera. Durante la disconnessione mostra le sessioni in cache, invece di dedurre quali sessioni sono attive. Clear (oppure /navigation-clear) chiede conferma, poi nasconde le righe storiche solo dalla rotaia sinistra e dal selettore di navigazione. Non cancella le sessioni; /sessions le elenca ancora. L’albero della sessione corrente, le sessioni fissate e gli alberi osservati in lavoro o in attesa restano sulla rotaia. Aprire una sessione da /sessions la riporta nell’elenco.

Usa /navigation-width o l’azione Width della navigazione per scegliere 20, 24, 28, 30, 32, 36 o 40 colonne (predefinito 28). La barra laterale destra della sessione ha la stessa azione Width e /sidebar-width (predefinito 32). Entrambe le preferenze vengono ricordate e si restringono da sole quando serve per preservare il contenuto principale. Usa /navigation per nascondere o ripristinare la rotaia di navigazione sinistra sui terminali larghi. /sidebar nasconde o ripristina la barra laterale destra della sessione allo stesso modo. Sui terminali più stretti /navigation apre un selettore di sessioni e agenti. Una barra Sessions visibile fornisce la stessa azione ogni volta che la rotaia di navigazione è assente. La sua azione Pending compare quando richieste note hanno bisogno di input; un asterisco marca un conteggio in cache durante la disconnessione. /sessions continua ad aprire il selettore di sessioni normale. /attention è disponibile a ogni larghezza. Durante la disconnessione, il suo elenco è etichettato come in cache; aprire le voci in cache è ancora possibile, ma le richieste potrebbero essere già state risposte altrove. L’azione Known requests della barra laterale apre le richieste in attesa tra i workspace noti, mentre il suo albero di sessioni resta circoscritto al progetto corrente. Tutte queste viste sono limitate dall’istanza collegata e dai dati di sessione caricati; questo conteggio non è un inventario completo di altri server o di workspace non caricati.

Le bozze non inviate sono isolate per progetto e per sessione dentro la TUI in esecuzione. Cambiare sessione conserva testo, allegati, posizione del cursore e modalità shell; tornare ripristina la bozza corrispondente. Queste bozze sono solo in memoria e non sopravvivono alla chiusura della TUI.

La notifica di completamento facoltativa ora dice Session idle. Segue il lavoro osservato nel sottoalbero della sessione visualizzata e attende che i discendenti attivi osservati diventino inattivi in modo esplicito, senza richieste in attesa. Disconnessioni, risincronizzazioni, stato mancante, errori e annullamento possono sopprimere l’avviso. È una notifica di ciclo di vita, non l’evidenza che i test siano passati o che un obiettivo sia completo.

Compiti nuovi e configurazione

L’avvio normale apre la superficie di lavoro New task, con un compositore in basso e la navigazione delle sessioni. Aprirla o digitare una bozza non crea una sessione salvata; una sessione viene creata quando invii. Usa /sessions o la navigazione sinistra per riprendere il lavoro esistente. Il comportamento esplicito di --session, --continue e --prompt resta disponibile; l’avvio non attiva la ripresa automatica.

La configurazione dei provider non si apre da sola. Usa l’azione visibile /connect nell’area di lavoro quando nessun provider è configurato. Con un provider configurato ma senza un modello valido selezionato, l’azione diventa /models. Una scoperta di provider fallita punta a /status; /connect e /providers restano disponibili per riparare la configurazione. Un modello selezionato è una scelta di configurazione, non un controllo di credenziali o di prontezza del runtime. I suggerimenti compaiono anche per gli utenti di ritorno la cui configurazione ha bisogno di attenzione.