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

Evidenza di esecuzione

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-08-25 Responsabile: runtime di AX Code

Ogni sessione di AX Code viene registrata mentre è in corso. Questa pagina descrive i comandi che trasformano quella registrazione in qualcosa che puoi rivedere, confrontare, esportare e annullare.

Usala quando un agente ha terminato e devi rispondere: che cosa ha fatto, quanto era rischioso, come si confronta con un altro tentativo e come si torna indietro?

Che cosa viene registrato

Durante un’esecuzione AX Code scrive due cose indipendenti:

• Un log di eventi tipizzato — decisioni di instradamento, attività del modello, confini dei passi, chiamate agli strumenti e risultati degli strumenti. È la sorgente di graph, replay, compare, trace e audit.
• Istantanee dei file — catturate in un object store Git che vive fuori dal repository, sotto la directory dati di AX Code, tramite refs/snapshots/<hash>. L’albero di lavoro e il .git/ del progetto non vengono modificati per conservarle.

Entrambe restano in locale. Nulla viene caricato.

Ricostruire un'esecuzione

ax-code graph <sessionID>

Ricostruisce la sessione come grafo di esecuzione: durata, riepilogo del rischio, conteggi dei token, agenti usati e ogni passo con le relative chiamate agli strumenti e i tempi.

## Session ses_01H8XK

Duration: 9m 54s | Risk: HIGH (53/100) | Tokens: 167,650 in / 18,494 out
Agents: architect

### Step 1 (8s) | tokens: 12263/587

- read: api.ts → ok (5ms)
- grep: rateLimit → ok (12ms)

--format seleziona output alternativi, tra cui Mermaid e una vista della topologia, quando vuoi il grafo in un altro strumento.

Nota: questo è il grafo di esecuzione della sessione — ciò che l’agente ha fatto. Non è il grafo del codice del repository; quello è ax-code index e il livello di code intelligence.

Confrontare due esecuzioni

ax-code session compare <sessionA> <sessionB>
ax-code session compare <sessionA> <sessionB> --deep

Riporta il delta di rischio, i file modificati, i conteggi di fallimento degli strumenti, il percorso decisionale di ogni esecuzione e i conteggi per tipo di evento. --deep aggiunge l’analisi della divergenza a livello di passo tramite il confronto del replay.

Questo confronta le esecuzioni, non il codice sorgente. Risponde alla domanda «il secondo tentativo ha ottenuto un punteggio peggiore: dove ha divergito», non a «mostrami il diff del codice».

Un uso tipico è scegliere tra due strategie per lo stesso compito:

  Risk Comparison
  ----------------------------------------
  Score: 53 → 93 (+40) ↑
  Level: HIGH → CRITICAL
  Files: 8 → 25
  Failures: 0 → 15

Ispezionare il log degli eventi registrato

ax-code session replay <sessionID> --mode summary
ax-code session replay <sessionID> --mode verify
ax-code session replay <sessionID> --mode reconstruct
ax-code session replay <sessionID> --mode export

verify controlla la coerenza del log registrato. reconstruct ricostruisce il flusso dei passi a partire dagli eventi. export scrive un pacchetto di replay portabile.

Il replay ricostruisce; non riesegue. Non rilancia i modelli, non richiama gli strumenti e non riproduce lo stato esterno. La modalità execute prepara un flusso ricostruito per il confronto programmatico con l’originale ed è pensata per i test, non per rieseguire il lavoro.

Leggere i segnali di rischio

ax-code risk <sessionID>
ax-code risk <sessionID> --explain
ax-code risk <sessionID> --json

Il punteggio è un’euristica deterministica ricavata dai segnali registrati, tra cui quanti file sono cambiati, se la modifica attraversa più aree di primo livello, quante chiamate agli strumenti sono fallite, se la validazione è stata eseguita, se esiste un’istantanea del diff, quanta superficie di API è interessata, come si è conclusa l’esecuzione (un gate di completamento bloccato oppure una fine per limite di passi o per stallo aggiungono peso) e se sono stati toccati percorsi sensibili alla sicurezza. Ogni fattore che contribuisce è elencato con il proprio peso, insieme alle mitigazioni suggerite.

È un aiuto alla revisione. Non è una probabilità, una confidenza calibrata né un’affermazione che il codice sia sicuro. Un punteggio LOW su una modifica non verificata significa comunque che la modifica non è verificata.

Annullare con precisione

Le istantanee dei file funzionano nei repository Git e nelle directory di progetto ordinarie quando Git è installato e snapshot è abilitato. AX Code tiene il proprio store Git delle istantanee fuori dal progetto; non crea una directory di progetto .git. Le regole di ignore e le esclusioni dei percorsi non supportati restano in vigore.

Il Revert della TUI annulla i messaggi e le modifiche ai file catturate. Con snapshot: false, oppure per i turni più vecchi che non hanno mai catturato una linea di base, può annullare soltanto i messaggi; le modifiche ai file restano sul disco. Abilitare le istantanee adesso non può ricostruire i contenuti dei file precedenti. Anche un turno catturato senza modifiche ai file non ha nulla da ripristinare.

ax-code session rollback <sessionID> --list      # show recoverable points
ax-code session rollback <sessionID> --dry-run   # show what would change
ax-code session rollback <sessionID> --step 4    # restore one step
ax-code session rollback <sessionID>             # restore the whole session

--list combina gli eventi durevoli dei passi con il dettaglio del grafo di esecuzione, così puoi puntare a un passo specifico invece di annullare l’intera esecuzione. --dry-run usa lo stesso pianificatore di rollback di apply ed elenca le sessioni delegate il cui registro dei file contribuisce al risultato.

Il rollback segue le sessioni figlie annidate quando hanno scritto nella directory di lavoro esatta del genitore. Ripristina le loro modifiche ai file successive al confine e conserva le trascrizioni. I discendenti in esecuzione in un altro worktree o in un’altra directory sono esclusi, e il rollback fallisce in modo chiuso se una sessione inclusa è ancora in esecuzione.

Confini da conoscere prima di farvi affidamento: il rollback ripristina dalle istantanee prese durante l’esecuzione. Un file mai incluso in un’istantanea — perché è stato modificato fuori dalla sessione, oppure non era in uno stato recuperabile — non può essere ripristinato in questo modo. Usa prima --dry-run su qualsiasi cosa rilevante.

Provare una strategia diversa

ax-code session branch <sessionID>
ax-code session branch <sessionID> --from <messageID>

Duplica lo stato memorizzato della sessione, così un secondo tentativo parte da un punto scelto invece che da zero.

Questo duplica lo stato della sessione — messaggi e obiettivi. Non è un branch Git e non è un worktree. Per candidati Git isolati, vedi Modifiche multi-modello verificate.

Diagnosticare

ax-code session trace <sessionID>
ax-code session trace <sessionID> --logs

Diagnostica basata sul replay, con una linea temporale a punteggio di rischio. --logs passa all’analisi legacy dei file di log al posto degli eventi di replay, utile quando si indaga un problema operativo invece di revisionare una modifica.

Esportare l'evidenza

ax-code audit export --all --since 2026-08-01     # JSON Lines
ax-code audit export --all --risk HIGH            # filter by minimum risk
ax-code audit report <sessionID>                  # Markdown report
ax-code audit otlp <sessionID>                    # OpenTelemetry spans
ax-code audit prune --days 90                     # delete old events

JSONL e OTLP rendono il registro dell’esecuzione consumabile dalla tua pipeline di revisione o di osservabilità. Il rapporto Markdown è pensato per le persone che allegano evidenza a una PR o a un registro di modifica.

Sfogliare il rapporto

ax-code run-report                 # latest session
ax-code run-report --index         # session index

Apre il rapporto locale dell’esecuzione in un browser, con il riepilogo dell’esecuzione, la linea temporale, le modifiche, lo stato di validazione, il dettaglio del rischio, le informazioni sul branch e i punti di rollback. Il server si vincola soltanto al loopback.

Correlati

• Garanzia degli obiettivi — controlli di accettazione eseguibili e freschezza delle sorgenti per obiettivi lunghi
• Perché AX Code — a che cosa serve questo livello di evidenza
• Modifiche multi-modello verificate — produrre candidati che vale la pena confrontare
• Livello semantico — buste di provenienza sulle risposte del grafo e di LSP
• Rapporto di esecuzione — la vista a livello di workspace e il rapporto per sessione