💻 computer science

Phoenix: Safe GitHub Issue Resolution via Multi-Agent LLMs

Phoenix è un sistema LLM multi-agente che risolve in modo sicuro le issue di GitHub, dal triage alla creazione di pull request, impiegando sette controlli di sicurezza a livelli e una strategia di valutazione consapevole della baseline, raggiungendo un tasso di risoluzione oracle del 75% su un set curato di SWE-bench Lite mantenendo al contempo il 100% di preservazione della correttezza sulle issue reali.

Autori originali: Kipngeno Koech, Muhammad Adam, Baimam Boukar Jean Jacques, Joao Barros

Pubblicato 2026-06-19

📖 5 min di lettura🧠 Approfondimento

CC BY 4.0

Autori originali: Kipngeno Koech, Muhammad Adam, Baimam Boukar Jean Jacques, Joao Barros

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina una biblioteca enorme e frenetica chiamata GitHub, dove milioni di persone lasciano post-it sui libri per chiedere riparazioni, nuove funzionalità o per segnalare refusi. Queste note si chiamano "issue". Di solito, un bibliotecario umano deve leggere la nota, trovare la pagina esatta nel libro, capire cosa c'è che non va, riscrivere il testo e poi chiedere a un bibliotecario senior di controllare prima che venga rimesso sullo scaffale. Questo è un processo lento e faticoso.

Phoenix è un nuovo team di robot IA progettati per fare questo lavoro, ma con una regola molto severa: Non fare danni.

Ecco come funziona Phoenix, suddiviso in concetti semplici:

1. Il Team di Specialisti (I Sei Agenti)

Invece di un unico robot super intelligente che cerca di fare tutto insieme (il che spesso porta a errori), Phoenix utilizza un team di sei lavoratori specializzati, come una catena di montaggio ben oliata:

Il Pianificatore (The Planner): Legge il post-it e disegna una mappa. Decide quali pagine devono essere modificate e come ripararle.
Il Riproduttore (The Reproducer - Il Detective): Prima di riparare qualsiasi cosa, questo robot prova a ricreare il problema. Dice: "Ok, se faccio X, il libro si rompe?". Se può dimostrare che il libro è rotto, procede. Se non può, salta questo passaggio per evitare che il team si blocchi.
Il Programmatore (The Coder): Lo scrittore. Prende la mappa del Pianificatore e riscrive effettivamente il testo sulle pagine.
Il Tester: L'ispettore della qualità. Fa passare il libro attraverso una macchina per vedere se il nuovo testo causa nuovi errori.
L'Analista dei Guasti (The Failure Analyst): Il medico. Se il Tester trova un nuovo errore, questo robot diagnostica perché è accaduto e dice al Programmatore come ripararlo. Hanno due tentativi per risolvere il problema; se falliscono due volte, si fermano e chiedono l'aiuto di un umano.
L'Agente PR (The PR Agent): Il messaggero. Una volta che la riparazione è pronta, confeziona il tutto e lo consegna a un bibliotecario umano per l'approvazione finale.

2. La "Rete di Sicurezza" (Sette Livelli di Protezione)

Il documento sottolinea che l'IA può essere pericolosa se inizia semplicemente a riscrivere libri a caso. Phoenix ha sette "guardie di sicurezza" per prevenire disastri:

La Recinzione (The Fence): Non permette ai robot di scrivere al di fuori delle mura della biblioteca (impedendo loro di cancellare file che non dovrebbero toccare).
Il Tesserino (The ID Badge): Controlla che i robot abbiano chiavi valide (token) in modo che non rimangano chiusi fuori a metà del lavoro.
La Squadra di Pulizia (The Clean-Up Crew): Elimina le parti disordinate e confuse dai post-it prima di mostrarli ai robot, in modo che non si confondano con una formattazione errata.
La Zona Vietata (The "No-Go" Zone): Si rifiuta di toccare i file del sistema di sicurezza della biblioteca (file di workflow) perché manometterli potrebbe bloccare tutti.
Il Pulsante di Arresto (The Stop Button): Se i robot entrano in un loop o continuano a commettere lo stesso errore, il sistema stacca la spina.
Il Lavoratore Solitario (The Solo Worker): Solo un libro alla volta viene lavorato per evitare che i robot si inciampino l'un l'altro.
La Chiave Fresca (The Fresh Key): Aggiorna automaticamente i tesserini identificativi prima che scadano, in modo che il lavoro non si interrompa a causa di un timeout.

3. Il Test "Prima e Dopo" (Consapevolezza del Baseline)

Questo è il trucco più ingegnoso di Phoenix. A volte, un libro della biblioteca è già rotto prima che il robot lo tocchi.

Vecchio Metodo: Un robot corregge un refuso, ma il libro fallisce comunque un test perché era già rotto. Il robot viene incolpato per il fallimento.
Metodo Phoenix: Prima che il robot apporti modifiche, scatta una "istantanea" dello stato attuale del libro. Dopo che il robot ha apportato le modifiche, confronta il nuovo stato con l'istantanea.
- Se il libro era già rotto e rimane rotto (ma non si rompono nuove cose), Phoenix dice: "Successo! Non abbiamo peggiorato la situazione".
- Se il libro funzionava e ora è rotto, Phoenix dice: "Stop! Abbiamo introdotto una regressione".

4. Cosa Mostrano i Risultati

I ricercatori hanno testato Phoenix in due modi:

La Prova Pratica (SWE-bench Lite): Hanno dato a Phoenix 24 problemi specifici e predefiniti. Phoenix ne ha risolti il 75% perfettamente senza rompere nulla che fosse precedentemente funzionante.
Il Test nel Mondo Reale (42 Problemi Reali): Hanno lasciato libero Phoenix su 42 problemi reali provenienti da 14 diversi progetti del mondo reale.
- Sicurezza: Phoenix ha ottenuto il 100% di "Preservazione della Correttezza". Ciò significa che non ha mai rotto un test che precedentemente era passato. Era incredibilmente sicuro.
- Tasso di Successo: Tuttavia, solo circa metà delle riparazioni erano effettivamente la riparazione corretta. L'altra metà erano "allucinazioni" in cui il robot scriveva codice nel posto sbagliato (come scrivere un manuale di riparazione nella sezione di narrativa). Il robot sapeva come ripararlo, ma a volte non riusciva a trovare dove fosse il problema.

In Sintesi

Phoenix è come un apprendista bibliotecario molto prudente e altamente addestrato. È eccellente nel non peggiorare le cose ed è molto bravo a seguire un processo rigoroso. Tuttavia, a volte fatica a trovare l'esatta posizione di un problema se la descrizione non corrisponde perfettamente ai nomi dei file.

Il documento conclude che, affinché l'IA sia utile nel mondo reale, la sicurezza deve venire prima della velocità. Phoenix dimostra che, utilizzando un team di agenti specializzati e rigide guardie di sicurezza, è possibile automatizzare le riparazioni software senza rompere accidentalmente il software stesso. La cosa principale da risolvere è aiutare il robot "Pianificatore" a trovare la pagina giusta nel libro più spesso.

Riepilogo Tecnico: Phoenix – Risoluzione Sicura delle Issue di GitHub tramite Multi-Agent LLM

Problematica

I repository open-source su GitHub accumulano migliaia di issue non risolte, creando un persistente collo di bottiglia per la manutenzione. Sebbene i Large Language Models (LLM) abbiano dimostrato un potenziale nell'automazione dei compiti di ingegneria del software (es. Devin, SWE-Agent, AutoCodeRover), ottimizzare esclusivamente per il tasso di risoluzione delle issue spesso compromette la sicurezza. I sistemi che risolvono una parte delle issue ma introducono regressioni in altre forniscono un valore netto incerto in ambienti di produzione. Inoltre, i benchmark esistenti spesso si concentrano sulle prestazioni offline, trascurando le complessità del deployment in produzione, come il filtraggio dei gateway API, la scadenza dei token e le suite di test preesistenti già rotte.

Metodologia

Phoenix è un sistema multi-agente LLM progettato per risolvere le issue di GitHub, dal triage alla creazione della pull-request (PR), dando priorità alla preservazione della correttezza rispetto ai tassi di risoluzione grezzi. Il sistema opera tramite una pipeline a ciclo chiuso coordinata da un Orchestratore centrale e una macchina a stati basata su label tramite webhook di GitHub.

Architettura del Sistema

La pipeline decompone il flusso di lavoro in sei agenti specializzati, ciascuno corrispondente a una fase di un convenzionale processo di risoluzione delle issue:

Agente Planner: Riceve il testo sanitizzato della issue, l'albero dei file del repository ed estratti rilevanti. Produce un piano strutturato in JSON che dettaglia l'approccio, i file da modificare, i passaggi di implementazione e la strategia di test. Utilizza un punteggio di sovrapposizione di parole chiave per determinare la rilevanza dei file.
Agente Reproducer (Opzionale): Tenta di generare un test sintetico che fallisca sul branch base per dimostrare il bug. Il fallimento in questo passaggio non è bloccante, permettendo alla pipeline di procedere alla codifica anche se un harness di test non può essere generato automaticamente.
Agente Coder: Genera contenuti completi dei file per i file modificati sulla base del piano e di eventuali feedback di errore precedenti. Impone l'auto-verifica e aderisce agli stili di codice esistenti.
Agente Tester: Esegue la suite di test del progetto. Fondamentalmente, impiega una strategia di valutazione dei test consapevole del baseline:
- Nasconde (stash) le modifiche di Phoenix ed esegue la suite sul branch base non modificato per raccogliere i fallimenti del baseline ( $B$ ).
- Ripristina le modifiche ed esegue nuovamente l'esecuzione per raccogliere i fallimenti post-modifica ( $P$ ).
- La correttezza è preservata se $P \setminus B = \emptyset$ (nessun test precedentemente passato fallisce ora). Ciò consente la valutazione su repository con pipeline CI interrotte.
Agente Failure Analyst: Se vengono rilevati nuovi fallimenti, questo agente analizza l'output e fornisce feedback strutturato al Coder per fino a due cicli di riprova.
Agente PR: Compone e apre una pull request facendo riferimento alla issue, transizionando lo stato a ai:review per l'ispezione umana.

Meccanismi di Sicurezza

Sette controlli di sicurezza stratificati sono stati derivati dai modelli di fallimento empirici osservati durante lo sviluppo e il deployment:

Prevenzione del path-traversal: Valida che le scritture dei file non escano dalla root del repository.
Esclusività dello stato delle label: Garantisce transizioni di stato atomiche per evitare l'accumulo di label obsolete.
Guardrail per i file di workflow: Elimina silenziosamente le scritture in .github/workflows/ per prevenire errori di permessi.
Sanificazione del contenuto: Tronca i corpi delle issue e rimuove gli stack trace per evitare risposte 403 dei gateway API (WAF).
Limite dei cicli di riprova: Limita il feedback dell'analista dei fallimenti a due round; un rilevatore di assenza di progressi termina i loop se le modifiche sono identiche.
Serializzazione della concorrenza: Un lock per installazione garantisce che un'issue venga elaborata alla volta su clone condivisi.
Aggiornamento del token di installazione: Aggiorna proattivamente i token dell'App di GitHub prima della scadenza per prevenire fallimenti di autenticazione durante esecuzioni lunghe.

Contributi Chiave

Architettura: Una pipeline a sei agenti con un Reproducer opzionale, una macchina a stati guidata dalle label e una specifica razionale di design per la decomposizione, che permette test isolati e attribuzione dei fallimenti.
Valutazione Consapevole del Baseline: Una strategia di test che distingue i fallimenti preesistenti dalle regressioni introdotte da Phoenix, consentendo la valutazione su repository con CI interrotte.
Lezioni di Deployment: Una caratterizzazione degli hazard del mondo reale (filtraggio WAF, scadenza token, confini di permessi) e i meccanismi specifici sviluppati per affrontare tali problemi.

Risultati

Il documento presenta i risultati di due setting di valutazione:

1. SWE-bench Lite (24 Istanze)

Valutato su un sottoinsieme curato di 24 istanze attraverso 12 repository (3 istanze ciascuno).

Risoluzione Oracle: Phoenix ha raggiunto un tasso di risoluzione oracle del 75% (18/24 istanze).
Sicurezza delle Regressioni: In tutte le esecuzioni oracle-passing, non ci sono state regressioni da pass-to-pass.
Modalità di Fallimento: I fallimenti sono stati principalmente dovuti a stati terminali ai:failed o timeout del valutatore, non a violazioni della sicurezza.
Nota: Gli autori dichiarano esplicitamente che questo sottoinsieme curato non è direttamente confrontabile con i risultati del leaderboard full-split a causa dell'uso del percorso webhook di produzione.

2. Pilota su 42 Issue Reali (14 Repository)

Valutato su 14 repository suddivisi in livelli Easy, Medium e Hard.

Preservazione della Correttezza (CP): Phoenix ha raggiunto il 100% di CP (42/42 issue). Non sono state introdotte nuove falle nei test rispetto al baseline.
Tempo di Risoluzione: Nelle repository di livello "Hard", il tempo medio di risoluzione end-to-end è stato di 122 secondi.
Ispezione Qualitativa: La revisione manuale ha rivelato una dicotomia nella qualità dell'output:
- ~50% delle PR erano correzioni ben mirate che modificavano moduli esistenti.
- ~50% delle PR posizionava il codice in percorsi errati o inventati (es. src/core/config.py). Queste passavano il CP perché non introducevano regressioni, ma non correggevano il bug segnalato. Questo limite è attribuito al ranking lessicale dei file del Planner piuttosto che alle capacità di sintesi del codice.

Significato e Rivendicazioni

Il documento posiziona Phoenix non come un sistema che massimizza il numero di issue risolte, ma come un sistema che dà priorità alla preservazione della correttezza e alla sicurezza negli ambienti di produzione.

La Sicurezza come Requisito di Prima Classe: Gli autori sostengono che la modifica autonoma e affidabile del codice richieda di trattare la sicurezza come un requisito ingegneristico derivato da fallimenti empirici piuttosto che da un design speculativo.
Rivendicazioni Modeste sulla Risoluzione: Il documento riconosce che la preservazione della correttezza al 100% non equivale alla risoluzione del 100% delle issue. Il divario è guidato da limiti di localizzazione (l'incapacità del Planner di mappare il vocabolario della issue ai percorsi dei file senza recupero semantico), non dalla generazione del codice.
Pronto per la Produzione: A differenza di altri lavori focalizzati su benchmark offline, Phoenix è progettato per veri webhook, veri branch e vere PR, con meccanismi specificamente tarati per gestire l'attrito del deployment in produzione (es. scadenza token, gateway API).

Gli autori concludono che, sebbene il recupero semantico sia il passo successivo necessario per affrontare i fallimenti di localizzazione, l'attuale architettura multi-agente dimostra con successo che la risoluzione sicura e end-to-end delle issue è realizzabile con rigorosi controlli di sicurezza e test consapevoli del baseline.