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

Controlli dell'harness e valutazione verificata

Stato: attivo

Ambito: stato attuale

Ultima revisione: 2026-09-14

Responsabile: runtime di ax-code

Per lo sforzo specifico del modello, gli interruttori di pensiero e la riproduzione del ragionamento, vedi controlli di ragionamento del modello corrente.

Controlli facoltativi di contesto e strumenti

Abilita ogni esperimento in modo indipendente nella configurazione di AX Code:

{
  "experimental": {
    "context_recovery": true,
    "mcp_tool_discovery": true,
    "tail_reminders": true,
    "read_only_recipes": true
  }
}

Tutte e quattro le opzioni sono disattivate per impostazione predefinita. Misura il successo del compito e il tempo trascorso con il tuo modello prima di adottarle insieme. Conservano i permessi degli strumenti e le impostazioni di isolamento esistenti. Vedi diagnostica delle prestazioni.

context_recovery espone context_recover e aggiunge puntatori al sorgente nei riepiloghi di compattazione riusciti. Lo strumento accetta una parola chiave, un ID di messaggio, un ID di parte facoltativo e un limite di risultati. Legge solo la sessione corrente, inclusa la cronologia precedente alla compattazione, ed esclude materiale ripristinato, ragionamento nascosto e testo ignorato o sintetico. Restituisce gli ID originali di messaggio e parte e estratti limitati. La ricerca esamina al massimo 100 parti per pagina e i primi 16.000 caratteri di ogni parte; before prosegue nelle parti più vecchie. Una corrispondenza mancante non prova che l’intera cronologia non contenga quel testo. I fork usano la cronologia copiata e ID nuovi. Le assegnazioni di credenziali vengono redatte dagli estratti.

mcp_tool_discovery mantiene disponibili gli strumenti integrati e introduce tool_search per gli strumenti MCP connessi. Una ricerca restituisce fino a cinque schemi corrispondenti e rende quegli strumenti disponibili alla richiesta successiva del modello. Non li esegue. Le selezioni sono limitate alla sessione, al massimo 32 strumenti, e vengono intersecate con l’ammissione corrente a ogni richiesta. Gli schemi grandi possono essere omessi dal risultato della ricerca e caricati alla richiesta successiva. Se tool_search è negato, il catalogo MCP ammesso ordinario resta disponibile. Uno strumento esistente in conflitto chiamato tool_search produce un errore.

tail_reminders sposta solo i promemoria dinamici di turno generati da AX Code alla fine della richiesta al provider. I messaggi utente memorizzati, il ragionamento dell’assistente, la cronologia degli strumenti e le istruzioni statiche restano invariati. Questo può cambiare il comportamento del modello e l’uso della cache; non dimostra da solo un miglioramento di velocità.

read_only_recipes espone read_recipe. Esegue fino a otto chiamate dipendenti read, glob o grep tramite il dispatcher normale degli strumenti. Ogni figlio ha i propri controlli di permesso, hook, annullamento e prove di sessione. Una ricetta non può valutare codice, eseguire comandi di shell, scrivere file, chiamare strumenti MCP o annidare un’altra ricetta.

{
  "steps": [
    { "id": "files", "tool": "glob", "parameters": { "pattern": "src/**/*.ts" } },
    {
      "id": "source",
      "tool": "read",
      "parameters": { "filePath": { "$ref": { "step": "files", "path": ["paths", 0] } } }
    }
  ],
  "select": [{ "step": "source", "path": ["text"] }]
}

I risultati glob canonici contengono paths e truncated; i risultati grep contengono matches con path, line, text; i risultati read contengono kind, text reso e truncated. Seleziona un risultato precedente tramite il suo passo e il percorso della proprietà propria. Le selezioni di array supportano un filtro letterale contains e limit. Controlla lo stato restituito e il troncamento. La ricetta ha una scadenza di annullamento di 60 secondi, un budget di argomenti di 32KB, un budget intermedio di 192KB e un output finale limitato. L’annullamento attende che lo strumento posseduto si stabilizzi. Nuove istruzioni del repository o media mettono in pausa l’esecuzione e conservano l’output normale del figlio, così il modello li vede prima di continuare. Le selezioni riuscite sostituiscono gli output intermedi solo nella richiesta al modello; i record originali dei figli restano nella cronologia. I genitori interrotti conservano l’output dei figli.

Correggere una generazione in corso

GET /session/{sessionID}/steering restituisce l’UUID della generazione attiva e le ricevute recenti. Includi il parametro di query esistente directory quando selezioni un progetto tramite il server HTTP.

Invia POST /session/{sessionID}/steering con:

{
  "expectedGeneration": "00000000-0000-4000-8000-000000000001",
  "clientID": "correction_1",
  "text": "Preserve the existing public function signature."
}

Usa l’UUID ottenuto da GET, non l’UUID di esempio. accepted significa che la correzione è in attesa. applied significa che è stata scritta come messaggio utente a un confine del ciclo e include il proprio ID di messaggio; non garantisce il completamento da parte del provider. rejected significa che non è stata applicata. Gli hook del ciclo di vita possono porre il veto all’ammissione. Una correzione accettata prolunga di un’altra iterazione una generazione che stava per completarsi, quindi una correzione inviata al traguardo viene applicata invece di essere rifiutata; annullamento ed errori rifiutano comunque le correzioni in attesa, e una generazione vecchia non può ammettere testo nel proprio successore. I tentativi identici restituiscono la stessa ricevuta conservata; un contenuto diverso sotto un ID client esistente restituisce HTTP 409. Il gesto di invio immediato della TUI ctrl+s usa questo endpoint.

Chiamate di strumenti in parallelo in un passo

Quando il modello emette più chiamate di strumenti in un solo messaggio dell’assistente, il runtime le esegue in contemporanea attraverso un cancello lettore/scrittore limitato alla sessione. Gli strumenti di sola lettura condividono la corsia e si sovrappongono; le modifiche ai file, bash, bash_input, le modifiche ai notebook, ops_apply, gli strumenti MCP e qualsiasi batch che contiene un figlio non sicuro per la concorrenza prendono la corsia esclusiva e girano da soli in ordine di arrivo. Una chiamata interrotta durante l’attesa non viene mai eseguita. Il batch mantiene una propria barriera di ordinamento per le chiamate che invia, e le sessioni figlie hanno un proprio cancello.

Le ricevute sono locali al processo, al massimo 256 per sessione e 32 richieste in attesa. Le ricevute terminali e le voci di sessione inattive possono essere rimosse. Dopo un riavvio, ottieni la nuova generazione e riconcilia i messaggi salvati; questa API non promette una ricerca durevole delle ricevute attraverso i riavvii. L’SDK generato espone session.steering e session.steer.

Instrada un seguito salvato nel turno in corso

POST /task-queue/{taskID}/steer ammette il testo di un seguito in coda nella generazione in corso della sessione al confine del passo successivo — lo stesso punto di consegna di POST /session/{sessionID}/steering — e annulla la riga di coda nella stessa richiesta, registrando steeredInto (l’UUID della generazione) e steeredAt nel payload della riga per l’audit. I seguiti di solo testo fino a 16.000 caratteri sono instradabili; il testo instradato applica agente, modello e strumenti del turno in corso. Allegati, tipi che non sono follow-up, righe già chiuse e testo troppo grande vengono rifiutati con HTTP 400, e una riga che passa a un altro stato a metà richiesta restituisce HTTP 409.

La risposta porta l’elemento di coda più recente e una ricevuta che può essere nulla. Quando nessuna generazione è attiva, la riga resta intatta e la risposta segnala generation_not_active con ricevuta nulla; i chiamanti possono allora ripiegare su POST /task-queue/{taskID}/send-now, che sposta solo la riga in testa alla coda e attende comunque la fine del turno. Una riga instradata non è annullabile, ma resta visibile come cancelled nella cronologia /queue con i propri campi di audit.

Nella TUI, l’associazione di tasti input_submit_steer (predefinita ctrl+s) instrada la bozza digitata quando esiste; con un compositore vuoto su una sessione occupata promuove invece il prefisso instradabile della coda salvata in ordine FIFO, fermandosi alla prima riga non instradabile così i seguiti successivi non le passano mai davanti. La sezione Seguiti della barra laterale e la finestra /queue offrono la stessa azione di instradamento immediato per riga, e un suggerimento vicino ai seguiti in coda mostra il tasto associato. L’SDK generato espone taskQueue.steer.

Proponi una skill a partire da lavoro verificato

I candidati di skill sono record espliciti nell’archivio locale esistente di AX Code. Non entrano nella scoperta delle skill finché non li promuovi, e non innescano mai una chiamata automatica al modello né una riscrittura delle istruzioni.

Crea un file JSON di proposta con name, description, applicability, procedure e evidence che contiene sessionID, messageID e partID. Le prove devono identificare un risultato originale riuscito di verify_project con buste di test o type-check eseguite rispetto alla revisione Git pulita corrente. Una frase di successo o un’uscita arbitraria della shell non bastano. La validazione deve citare la verifica riuscita di un’altra sessione alla stessa revisione.

ax-code skill candidate propose --proposal proposal.json
ax-code skill candidate show verified-procedure
ax-code skill candidate validate verified-procedure --proposal independent-evidence.json
ax-code skill candidate promote verified-procedure
ax-code skill candidate retire verified-procedure

Tieni il JSON di input fuori dal worktree oppure in una directory locale ignorata, così il controllo della revisione pulita resta significativo. La promozione crea .ax-code/skill/{name}/SKILL.md senza sovrascrivere una skill esistente. Le prove di sorgente vengono ricontrollate prima della promozione. Le directory symlink vengono rifiutate. Il ritiro rimuove solo il file invariato del candidato; le modifiche manuali causano un conflitto. Riavvia un’istanza di runtime esistente per aggiornare la scoperta delle skill in cache. I controlli superati costituiscono prova per quei controlli; rivedi l’applicabilità della procedura prima della promozione.

Acquisisci un esperimento abbinato

Da un checkout del sorgente, usa:

pnpm --dir packages/ax-code exec tsx script/harness-eval.ts run /path/to/manifest.json > /path/to/runs.ndjson
pnpm --dir packages/ax-code exec tsx script/harness-eval.ts compare /path/to/runs.ndjson baseline candidate

Il manifesto fidato dell’operatore contiene un provider/model esplicito, runtimeRevision, argv CLI facoltativo command, repetitions, timeoutMs, esattamente due arms nominati e tasks. Ogni braccio ha features facoltativo (i flag sperimentali sopra) e toolProfile. Ogni compito fornisce id, prompt, files in linea (path/content) e un oracle. L’oracolo è JavaScript fidato eseguito da Node.js dopo l’uscita del processo di programmazione; process.argv[1] identifica la fixture temporanea. Il suo codice resta fuori dallo spazio di lavoro dell’agente e non proviene mai dalla risposta del modello.

Ogni tentativo ottiene una fixture Git nuova. L’oracolo deve fallire con uscita 1 sulla fixture iniziale. L’esecutore usa un’invocazione fissa della CLI headless, alterna l’ordine dei bracci tra le ripetizioni, applica un timeout ed esegue di nuovo l’oracolo dopo un tentativo completato. elapsedMs include il processo di programmazione e la verifica dopo l’esecuzione; verificationMs identifica quest’ultima separatamente. La preparazione della fixture e il controllo iniziale in fallimento sono esclusi. Il flusso registra ogni tentativo completato, fallito, scaduto o annullato man mano che finisce. Prompt grezzi, output dei sottoprocessi e credenziali non vengono emessi nei record di valutazione. Una coorte interrotta resta incompleta e non può produrre un confronto abbinato.

Il confronto rifiuta i duplicati e le coppie compito/modello/coorte/ripetizione mancanti o non corrispondenti. I tentativi falliti e non verificati restano nei denominatori del tasso di successo. Le mediane di latenza e i rapporti appaiati sono condizionati esplicitamente al successo verificato. P95 richiede 20 osservazioni riuscite dentro una cella compito/modello/coorte/braccio; gli aggregati di celle miste lo omettono. La coorte calcola l’hash del manifesto, ma la revisione del runtime e le condizioni esterne di provider, configurazione e cache richiedono comunque il controllo dell’operatore. Una piccola esecuzione di fumo non può stabilire una superiorità generale di velocità né giustificare il cambiamento dei predefiniti.

Selezione delle capacità e diagnostica di recupero

Le richieste autonome possono includere un pacchetto di contesto per agente lungo quando il modello ha almeno 64.000 token di contesto, supporto al ragionamento e supporto agli strumenti. Per i modelli senza una voce di registro, tutti e tre devono essere dichiarati nei metadati risolti del modello. Il pacchetto supplementare ha un tetto di stima di 2.048 token in caratteri; non è la finestra di conversazione. Le dichiarazioni negative esplicite e le restrizioni registrate impediscono l’ammissione. Questa ottimizzazione del testo del prompt non stabilisce la compatibilità con la cache o con il pensiero conservato, né cambia le scadenze e il ritmo automatici di Super-Long. Questi conservano le regole esistenti di qualificazione e di override.

Due fallimenti strutturati consecutivi di strumenti dopo l’ultimo messaggio utente (contati prima dei promemoria sintetici di coda) richiedono un ragionamento più profondo alla chiamata successiva del modello, quando esiste una variante di sforzo utilizzabile. Un risultato di strumento riuscito azzera il conteggio. Lo sforzo esplicito dell’utente e le opzioni di ragionamento configurate hanno la precedenza. Questo cambia la selezione dello sforzo, non i limiti di retry né i permessi degli strumenti.

Gli eventi locali di replay llm.request includono capabilityResolution: protocollo, finestra di contesto, se è stato selezionato un pacchetto di contesto o la modalità Super-Long, fallimenti consecutivi di strumenti e selezione del ragionamento oppure un motivo di non applicazione. boundary: "policy-selection" descrive la decisione di AX Code; plugin e SDK dei provider possono ancora alterare la richiesta finale. I valori espliciti di sforzo di GPT-6 vengono conservati; l’API richiede low o superiore, non none o minimal. L’evento conserva gli hash della richiesta, non i corpi del prompt o delle credenziali. L’assenza di una variante di sforzo non implica che il pensiero predefinito del provider sia disattivato.

L’acquisizione abbinata dell’harness legge gli eventi JSON della CLI step_finish e tool_use per i token di input, output, ragionamento e lettura di cache, le chiamate di strumenti completate e gli errori degli strumenti. Gli ID di parte duplicati contano una sola volta. metricsStatus è observed, partial o unavailable; i flussi troncati o malformati e i tentativi interrotti trattengono i totali. I confronti riportano, per ogni metrica, i conteggi di esecuzioni osservate e mancanti e la mediana, inclusi i tentativi falliti dove esistono osservazioni. I valori mancanti restano mancanti. Questi contatori descrivono eventi di runtime emessi, non la fatturazione del provider, l’uso delle sessioni figlie o gli strumenti interni nativi della CLI. Un flusso osservato completo senza eventi terminali di strumenti riporta zero chiamate di strumenti. La verifica dell’oracolo resta la fonte del successo del compito; l’uso da solo non stabilisce un recupero riuscito né una qualità migliore.