Riepilogo Tecnico: DUALVIEW – Ragionamento Strutturale Dual-Mode per la Risoluzione di Problemi tramite Agenti

1. Definizione del Problema

I recenti progressi negli agenti basati su Large Language Model (LLM) hanno migliorato l'automazione della riparazione dei programmi (APR) abilitando l'esplorazione iterativa del repository. Tuttavia, gli approcci esistenti si affidano prevalentemente a una navigazione del codice sequenziale e basata sul testo. Questa interfaccia incentrata sul testo impone due limitazioni fondamentali nella risoluzione di problemi in repository su larga scala e a lungo orizzonte:

1. Osservazioni Frammentate: Gli agenti esplorano i repository attraverso strumenti come grep, cat e comandi shell. Ogni interazione rivela solo un piccolo frammento del codice sorgente, costringendo l'agente a ricostruire mentalmente le relazioni strutturali (ad es., accoppiamento tra moduli, catene di chiamate) da prove testuali sparse. Ciò porta alla "deriva dell'esplorazione" (exploration drift) e a una localizzazione incompleta man mano che lo spazio di ricerca cresce.
2. Linearizzazione delle Strutture a Grafo: Sebbene le dipendenze di un repository siano intrinsecamente strutturate a grafo, i sistemi esistenti serializzano queste relazioni (ad es., Abstract Syntax Trees, grafi di chiamata) in descrizioni testuali lineari o liste di archi prima di presentarle all'agente. Questa linearizzazione oscura la topologia, rendendo difficili la percezione e il ragionamento su percorsi multi-hop, strutture di branching e regioni di dipendenza dense.

La sfida centrale è il disallineamento tra la natura strutturata a grafo dei repository e l'interazione incentrata sul testo degli attuali agenti, che ostacola un'esplorazione efficiente a lungo orizzonte e l'analisi delle dipendenze.

2. Metodologia: Framework DUALVIEW

Gli autori propongono DUALVIEW, un framework di scaffolding strutturale dual-mode che equipaggia i sistemi agentici con viste strutturali multi-grana di un repository. Invece di ricostruire la struttura dal testo, DUALVIEW esternalizza le relazioni del repository come rappresentazioni grafiche visive e testuali sincronizzate.

A. Viste Strutturali Multi-Grana

DUALVIEW decompone la struttura del repository in quattro viste grafiche complementari, organizzate come una gerarchia di esplorazione da grossolana a fine:

1. Modulo Coupling Graph (MCG): Una vista dell'intero repository che cattura l'accoppiamento tra sottosistemi e moduli. Aiuta gli agenti a orientarsi all'interno del codice e a identificare i candidati sottosistemi responsabili di un problema.
2. Function Call Graph (FCG): Una vista cross-funzione che espone i percorsi di propagazione chiamante-chiamato. Permette agli agenti di tracciare il comportamento attraverso file e funzioni per comprendere i confini di impatto.
3. Class Hierarchy Graph (CHG): Una vista cross-classe che dettaglia le relazioni di ereditarietà e overriding. Colma il divario tra indizi API astratti (interfacce/classi base) e implementazioni concrete.
4. Program Dependence Graph (PDG): Una vista intra-funzione che cattura le dipendenze di dati e controllo a livello di istruzione. Aiuta nell'identificazione di specifici flussi di valori o decisioni di controllo che causano difetti.

Queste viste sono esposte tramite un'interfaccia di query parametrizzata $V(t, s, \theta)$, dove $t$ è il tipo di vista, $s$ è l'entità seme e $\theta$ controlla l'ambito (raggio di hop, direzione, budget di nodi).

B. Osservazioni Strutturali Dual-Mode

Per ogni query al grafo, DUALVIEW restituisce una risposta sincronizzata contenente:

• Rappresentazione Visiva: Un diagramma nodo-link (renderizzato tramite Graphviz) che preserva topologia, connettività e pattern di dipendenza. Enfatizza l'organizzazione globale, i pattern di fan-in/fan-out e le alternative strutturali senza appesantire la vista con dettagli semantici completi.
• Rappresentazione Testuale: Una serializzazione strutturata della stessa porzione di grafo, che fornisce il preciso radicamento semantico (percorsi dei file, numeri di riga, identità delle entità e semantica delle relazioni) necessario per l'ispezione a livello di sorgente.

C. Ragionamento Strutturale Adattivo

DUALVIEW si integra nei loop degli agenti esistenti come uno strato di ragionamento adattivo. L'agente valuta il proprio stato di ragionamento attuale per decidere quando invocare le viste strutturali:

• Orientamento al Sottosistema: Utilizza MCG quando l'organizzazione modulare non è chiara.
• Propagazione delle Funzioni: Utilizza FCG quando il ruolo upstream/downstream di una funzione è ambiguo.
• Risoluzione Gerarchica: Utilizza CHG quando si gestiscono classi astratte o interfacce.
• Dipendenze Locali: Utilizza PDG quando si restringe il campo a un'implementazione specifica per analizzare il flusso di controllo/dati.

Ciò consente agli agenti di alternare naturalmente tra ragionamento strutturale (navigazione del grafo) e ispezione del codice sorgente (editing del codice).

3. Contributi Chiave

1. Scaffolding Strutturale Dual-Mode: La proposta di DUALVIEW, che esternalizza la struttura del repository in rappresentazioni grafiche visive e testuali sincronizzate, consentendo agli agenti di ragionare sia sull'organizzazione a livello di repository che sulle dipendenze a grana fine.
2. Valutazione Esaustiva: Valutazione su molteplici framework di agenti (mini-SWE-agent, OpenCode), modelli di fondazione (Claude 4.5 Sonnet, Kimi K2.5, Gemini 3 Flash) e benchmark (SWE-bench Pro, SWE-bench Verified).
3. Implementazione Open-Source: Rilascio dell'implementazione di DUALVIEW, confezionata come strumenti riutilizzabili e servizi Model Context Protocol (MCP) per facilitare la ricerca futura.

4. Risultati Sperimentali

Gli autori hanno valutato DUALVIEW su SWE-bench Pro (731 istanze) e SWE-bench Verified (500 istanze).

• Efficacia Complessiva: DUALVIEW ha migliorato costantemente le prestazioni di risoluzione dei problemi attraverso diverse architetture di agenti e famiglie di modelli.
  • Su SWE-bench Pro, utilizzando OpenCode con Kimi K2.5, DUALVIEW ha risolto 388 istanze (53,1%), un miglioramento di 46 istanze (+13,5%) rispetto al baseline (342 istanze).
  • Utilizzando mini-SWE-agent con Claude 4.5 Sonnet, ha risolto 375 istanze (51,3%), rispetto a 355 (+5,6%).
  • Su SWE-bench Verified, l'integrazione di DUALVIEW con mini-SWE-agent e Gemini 3 Flash ha raggiunto un tasso di risoluzione del 79,8% (399/500), superando il baseline (75,8%) e riducendo il costo medio per istanza da $0,36 a$0,18.
• Efficienza dei Costi: Nonostante l'overhead della generazione di grafi visivi, DUALVIEW ha ridotto il numero medio di step LLM e il costo totale di inferenza per istanza. Ciò è attribuito alla prevenzione di esplorazioni non valide e all'accumulo non necessario di contesto.
• Studi di Ablazione:
  • Dual-Mode vs. Solo-Testo: Le rappresentazioni grafiche visive da sole hanno superato le serializzazioni testuali dei grafi (78 contro 71 istanze risolte). La combinazione di entrambe le modalità ha prodotto la performance più forte (81 istanze risolte), confermando che la topologia visiva aiuta la navigazione mentre i dettagli testuali consentono un editing preciso.
  • Viste Multi-Grana: Ogni singola vista del grafo (MCG, FCG, CHG, PDG) ha migliorato le prestazioni rispetto al baseline. La combinazione di tutte le viste ha costantemente superato qualsiasi variante a singola vista, dimostrando la necessità di informazioni strutturali a diverse granularità.
• Confronto con i Baseline: DUALVIEW ha superato gli agenti esistenti incentrati sul testo (SWE-agent, Live-SWE-agent) e altri approcci basati su grafi (RepoGraph, CodeGraph) che si affidano alla serializzazione testuale dei grafi.

5. Significato e Rivendicazioni

L'articolo sostiene che DUALVIEW dimostri che il ragionamento strutturale dual-mode funge da potenziamento generale per la risoluzione di problemi agentici, piuttosto che da un'ottimizzazione specifica per un modello.

• Cambio di Paradigma: Il lavoro sostiene un passaggio dall'esplorazione incentrata sul testo al ragionamento strutturale visivo. Postula che i grafi del repository debbano servire come artefatti di ragionamento (strutture direttamente osservabili) piuttosto che solo come artefatti di recupero (testo serializzato).
• Mitigazione delle Limitazioni: Rendendo la connettività e le relazioni multi-hop immediatamente percepibili, DUALVIEW mitiga la "deriva dell'esplorazione" causata dalle osservazioni testuali frammentate e dalla difficoltà di percepire topologie complesse in un testo lineare.
• Complementarità: I risultati suggeriscono che le modalità visiva e testuale siano complementari: la modalità visiva fornisce la "mappa" (topologia e struttura) per una navigazione efficiente, mentre la modalità testuale fornisce le "coordinate" (percorsi dei file e numeri di riga) per un'azione precisa.

Gli autori concludono che esporre la struttura del repository attraverso rappresentazioni grafiche visive e testuali complementari migliora significativamente la capacità di risolvere problemi a lungo orizzonte in codebase complesse.