Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Couche sémantique

Statut : Actif Portée : état actuel Dernière revue : 2026-05-03 Responsable : runtime ax-code

Ce document décrit la couche sémantique qui existe aujourd’hui dans AX Code. C’est un contrat d’état actuel, pas une feuille de route.

Source de vérité

Cette page documente le comportement sémantique livré, pas les ambitions futures de graphe de code. Lorsque le comportement change, vérifiez-le par rapport à :

packages/ax-code/src/tool/lsp.ts et les modules LSP associés pour les opérations sémantiques en direct.
packages/ax-code/src/code-intelligence/ pour le comportement du graphe indexé.
packages/ax-code-reason/ pour les analyses de débogage et de remaniement appuyées sur le graphe (impact, chemins de bogues, courses, cycle de vie, duplication, valeurs codées en dur, constats de sécurité et application de remaniement sous porte).
Les tests de rejeu, d’export et d’audit avant d’affirmer des garanties de provenance durables.

Si une capacité est prévue ou expérimentale, gardez ce statut explicite.

Objet

AX Code expose des réponses sémantiques à travers deux sources explicites :

lsp : requêtes en direct au serveur de langage
graph : requêtes persistantes d’intelligence du code

Le système n’achemine pas silencieusement l’une vers l’autre. Les appelants choisissent la surface selon les exigences de fraîcheur, de latence et de déterminisme.

Surfaces sémantiques actuelles

Surface	Source d’appui	Rôle actuel
outil `lsp`	clients LSP en direct	réponses sémantiques les plus fraîches, surface de requête en direct explicite
outil `code_intelligence`	graphe de code SQLite indexé	requêtes de graphe déterministes sur les symboles indexés, les références et les relations d’appel

L’outil lsp est l’interface sémantique en direct. L’outil code_intelligence est l’interface sémantique indexée. Aucun n’est un repli caché de l’autre.

Portes actuelles :

code_intelligence est activé par défaut, mais peut être désactivé par des drapeaux de fonctionnalité
lsp exige actuellement le drapeau expérimental de l’outil LSP

Contrat d'enveloppe

Les réponses sémantiques portent des métadonnées de provenance afin que les consommateurs en aval puissent raisonner sur la confiance et la fraîcheur.

Champs communs :

source : lsp, graph ou cache
completeness : full, partial ou empty
timestamp : moment où la réponse sous-jacente a été résolue
degraded : signal facultatif indiquant que la réponse doit être traitée avec prudence

Les enveloppes appuyées sur LSP peuvent aussi inclure :

serverIDs : quels serveurs de langage ont contribué
cacheKey : référence stable vers une ligne du cache de réponses LSP

Audit et rejeu

Comportement actuel :

les appels sémantiques en direct à travers l’outil lsp écrivent des lignes audit_semantic_call
le rejeu d’outil préserve désormais tool.result.metadata, ce qui signifie que les métadonnées sémantiques appuyées sur le graphe ne sont pas perdues pendant le rejeu ou l’export
le rejeu déterministe compare les métadonnées du chemin de décision, pas l’égalité sémantique de chaque liste de symboles renvoyée

Cela donne aux réponses sémantiques appuyées sur LSP et sur le graphe une visibilité d’audit comparable, même si elles viennent encore de chemins de stockage et d’exécution différents.

Opérations exposées actuellement

`lsp`

La surface en direct lsp inclut des opérations appuyées sur une enveloppe pour :

la définition
les références
le survol
les symboles de document
les symboles d’espace de travail
les implémentations
la hiérarchie d’appels
les diagnostics agrégés

C’est la bonne surface lorsque la récence compte plus que la répétabilité.

`code_intelligence`

La surface de graphe inclut :

la recherche de symbole
les symboles de fichier
les références
les appelants
les appelés

C’est la bonne surface lorsque la répétabilité et une latence plus faible comptent plus que la fraîcheur immédiate de l’état de l’éditeur.

Une troisième surface de connaissance, facultative, est le wiki sémantique natif du dépôt sous .ax-wiki/, compilé par ax-code wiki. Elle ne fait pas partie du contrat d’enveloppe structurelle graphe/LSP ci-dessus.

Surface	Rôle
`lsp` / `code_intelligence`	Précision structurelle (ce document)
`.ax-wiki/`	Récit d’architecture appuyé sur les sources, pour les agents

Voir AX Wiki natif pour le CLI, le routage et les non-objectifs. La synthèse du wiki ne doit pas être traitée comme un substitut des appelants, des appelés et des références.

Non-objectifs importants

La couche sémantique actuelle ne fait pas ces choses :

pas de routage caché qui privilégie le graphe avec un repli LSP automatique
pas d’affirmation que la fraîcheur du graphe égale la fraîcheur LSP en direct
pas d’affirmation que chaque assistant sémantique interne est exposé via HTTP ou le SDK
pas de séparation du runtime sémantique en Rust dans l’implémentation actuelle
pas d’affirmation que le Markdown d’AX Wiki est une source de vérité structurelle (voir AX Wiki natif)

Conseils d'intégration

Lorsque vous écrivez de la documentation, des liaisons SDK ou des flux de plus haut niveau :

décrivez lsp et code_intelligence comme des surfaces sémantiques distinctes
distinguez les opérations d’outils publics des fonctions d’assistance internes
ne décrivez que les garanties d’audit et de rejeu réellement préservées dans les schémas actuels
mentionnez les drapeaux lorsqu’une surface sémantique n’est pas toujours activée
lorsque vous mentionnez AX Wiki, gardez explicites les responsabilités du wiki et du graphe