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

Livello semantico

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-05-03 Responsabile: runtime di ax-code

Questo documento descrive il livello semantico presente oggi in AX Code. È un contratto sullo stato attuale, non una roadmap.

Sorgente di verità

Questa pagina documenta il comportamento semantico già distribuito, non le ambizioni future sul grafo del codice. Quando il comportamento cambia, verificalo rispetto a:

packages/ax-code/src/tool/lsp.ts e i moduli LSP correlati, per le operazioni semantiche in tempo reale.
packages/ax-code/src/code-intelligence/ per il comportamento del grafo indicizzato.
packages/ax-code-reason/ per le analisi di debug e refactoring appoggiate al grafo (impatto, percorsi di bug, race, ciclo di vita, duplicazione, valori hardcoded, rilievi di sicurezza e applicazione controllata del refactoring).
Test di replay, di export e di audit prima di affermare garanzie durevoli di provenienza.

Se una capacità è pianificata o sperimentale, mantieni quello stato esplicito.

Scopo

AX Code espone le risposte semantiche attraverso due sorgenti esplicite:

lsp: query al language server in tempo reale
graph: query persistenti di code intelligence

Il sistema non instrada in silenzio una sorgente nell’altra. Chi chiama sceglie la superficie in base a freschezza, latenza e requisiti di determinismo.

Superfici semantiche attuali

Superficie	Sorgente di supporto	Ruolo attuale
strumento `lsp`	client LSP in tempo reale	risposte semantiche più fresche, superficie esplicita di query in tempo reale
strumento `code_intelligence`	grafo del codice SQLite indicizzato	query deterministiche sul grafo, su simboli indicizzati, riferimenti e relazioni di chiamata

Lo strumento lsp è l’interfaccia semantica in tempo reale. Lo strumento code_intelligence è l’interfaccia semantica indicizzata. Nessuno dei due è un fallback nascosto dell’altro.

Gating attuale:

code_intelligence è abilitato per impostazione predefinita, ma può essere disabilitato con i feature flag
lsp richiede oggi il flag sperimentale dello strumento LSP

Contratto della busta

Le risposte semantiche portano metadati di provenienza, così i consumatori a valle possono ragionare su fiducia e freschezza.

Campi comuni:

source: lsp, graph oppure cache
completeness: full, partial oppure empty
timestamp: momento in cui la risposta sottostante è stata risolta
degraded: segnale facoltativo che la risposta va trattata con cautela

Le buste appoggiate a LSP possono includere anche:

serverIDs: quali language server hanno contribuito
cacheKey: riferimento stabile a una riga della cache delle risposte LSP

Audit e replay

Comportamento attuale:

le chiamate semantiche in tempo reale attraverso lo strumento lsp scrivono righe audit_semantic_call
il replay degli strumenti ora conserva tool.result.metadata, quindi i metadati semantici appoggiati al grafo non si perdono durante replay ed export
il replay deterministico confronta i metadati del percorso decisionale, non l’uguaglianza semantica di ogni elenco di simboli restituito

Questo dà alle risposte semantiche appoggiate a LSP e a quelle appoggiate al grafo una visibilità di audit confrontabile, anche se provengono ancora da percorsi di storage e di runtime diversi.

Operazioni esposte oggi

`lsp`

La superficie in tempo reale lsp include operazioni con busta per:

definizione
riferimenti
hover
simboli del documento
simboli del workspace
implementazioni
gerarchia delle chiamate
diagnostica aggregata

È la superficie giusta quando la recenza conta più della ripetibilità.

`code_intelligence`

La superficie del grafo include:

ricerca dei simboli
simboli del file
riferimenti
chiamanti
chiamati

È la superficie giusta quando la ripetibilità e una latenza più bassa contano più della freschezza immediata dello stato dell’editor.

Una terza superficie di conoscenza, facoltativa, è il wiki semantico nativo del repository sotto .ax-wiki/, compilato da ax-code wiki. Non fa parte del contratto strutturale di busta grafo/LSP descritto sopra.

Superficie	Ruolo
`lsp` / `code_intelligence`	Precisione strutturale (questo documento)
`.ax-wiki/`	Narrazione di architettura ancorata alle sorgenti, per gli agenti

Vedi AX Wiki per CLI, instradamento e non-obiettivi. La sintesi del wiki non va trattata come sostituto di chiamanti, chiamati e riferimenti.

Non-obiettivi importanti

Il livello semantico attuale non fa queste cose:

nessun instradamento nascosto che privilegi il grafo, con fallback automatico a LSP
nessuna affermazione che la freschezza del grafo equivalga alla freschezza di LSP in tempo reale
nessuna affermazione che ogni helper semantico interno sia esposto tramite HTTP o SDK
nessuna separazione del runtime semantico in Rust nell’implementazione attuale
nessuna affermazione che il markdown di AX Wiki sia una sorgente di verità strutturale (vedi AX Wiki)

Guida all'integrazione

Quando scrivi documentazione, binding SDK o workflow di livello più alto:

descrivi lsp e code_intelligence come superfici semantiche separate
distingui le operazioni pubbliche degli strumenti dalle funzioni helper interne
descrivi soltanto le garanzie di audit e di replay che sono davvero conservate negli schemi attuali
cita i flag quando una superficie semantica non è sempre abilitata
quando citi AX Wiki, tieni esplicite le responsabilità del wiki rispetto a quelle del grafo