Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Capa semántica

Estado: Activo Alcance: estado actual Última revisión: 2026-05-03 Responsable: entorno de ejecución de ax-code

Este documento describe la capa semántica que existe hoy en AX Code. Es un contrato del estado actual, no una hoja de ruta.

Fuente de verdad

Esta página documenta el comportamiento semántico publicado, no ambiciones futuras de grafo de código. Cuando el comportamiento cambie, verifícalo contra:

packages/ax-code/src/tool/lsp.ts y los módulos LSP relacionados para las operaciones semánticas en vivo.
packages/ax-code/src/code-intelligence/ para el comportamiento del grafo indexado.
packages/ax-code-reason/ para los análisis de depuración y refactorización respaldados por el grafo (impacto, rutas de errores, carreras, ciclo de vida, duplicación, valores fijos en el código, hallazgos de seguridad y aplicación condicionada de refactorizaciones).
Pruebas de reproducción, exportación y auditoría antes de afirmar garantías durables de procedencia.

Si una capacidad está planificada o es experimental, mantén ese estado explícito.

Propósito

AX Code expone respuestas semánticas a través de dos fuentes explícitas:

lsp: consultas en vivo al servidor de lenguaje
graph: consultas persistentes de inteligencia de código

El sistema no enruta una hacia la otra en silencio. Quien llama elige la superficie según los requisitos de frescura, latencia y determinismo.

Superficies semánticas actuales

Superficie	Fuente de respaldo	Papel actual
Herramienta `lsp`	clientes LSP en vivo	respuestas semánticas más frescas, superficie explícita de consulta en vivo
Herramienta `code_intelligence`	grafo de código SQLite indexado	consultas deterministas de grafo sobre símbolos, referencias y relaciones de llamada indexados

La herramienta lsp es la interfaz semántica en vivo. La herramienta code_intelligence es la interfaz semántica indexada. Ninguna es un respaldo oculto de la otra.

Condicionamiento actual:

code_intelligence está activado de forma predeterminada, pero se puede desactivar con marcas de función
lsp exige ahora la marca experimental de la herramienta LSP

Contrato del sobre

Las respuestas semánticas llevan metadatos de procedencia para que los consumidores posteriores puedan razonar sobre la confianza y la frescura.

Campos habituales:

source: lsp, graph o cache
completeness: full, partial o empty
timestamp: cuándo se resolvió la respuesta subyacente
degraded: señal opcional de que la respuesta debe tratarse con cautela

Los sobres respaldados por LSP también pueden incluir:

serverIDs: qué servidores de lenguaje contribuyeron
cacheKey: referencia estable a una fila de la caché de respuestas LSP

Auditoría y reproducción

Comportamiento actual:

las llamadas semánticas en vivo a través de la herramienta lsp escriben filas audit_semantic_call
la reproducción de herramientas conserva ahora tool.result.metadata, lo que significa que los metadatos semánticos respaldados por el grafo no se pierden durante la reproducción o la exportación
la reproducción determinista compara metadatos de la ruta de decisión, no la igualdad semántica de cada lista de símbolos devuelta

Esto da a las respuestas semánticas respaldadas por LSP y por el grafo una visibilidad de auditoría comparable, aunque sigan viniendo de rutas distintas de almacenamiento y de entorno de ejecución.

Operaciones expuestas actuales

`lsp`

La superficie en vivo lsp incluye operaciones respaldadas por sobres para:

definición
referencias
hover
símbolos del documento
símbolos del espacio de trabajo
implementaciones
jerarquía de llamadas
diagnósticos agregados

Es la superficie adecuada cuando la actualidad importa más que la repetibilidad.

`code_intelligence`

La superficie de grafo incluye:

búsqueda de símbolos
símbolos de archivo
referencias
llamadores
llamados

Es la superficie adecuada cuando la repetibilidad y una menor latencia importan más que la frescura inmediata del estado del editor.

Una tercera superficie de conocimiento, opcional, es la wiki semántica nativa del repositorio bajo .ax-wiki/, compilada por ax-code wiki. No forma parte del contrato de sobre estructural de grafo y LSP de arriba.

Superficie	Papel
`lsp` / `code_intelligence`	Precisión estructural (este documento)
`.ax-wiki/`	Narrativa de arquitectura respaldada por el código fuente, para agentes

Consulta AX Wiki para la CLI, el enrutado y lo que no es un objetivo. La síntesis de la wiki no debe tratarse como sustituto de llamadores, llamados y referencias.

Lo que no es un objetivo

La capa semántica actual no hace estas cosas:

no hay enrutado oculto que priorice el grafo con respaldo automático de LSP
no se afirma que la frescura del grafo equivalga a la frescura del LSP en vivo
no se afirma que cada ayuda semántica interna se exponga por HTTP o por el SDK
no hay una división del entorno de ejecución semántico en Rust en la implementación actual
no se afirma que el Markdown de AX Wiki sea una fuente estructural de verdad (consulta AX Wiki)

Orientación de integración

Al escribir documentación, enlaces del SDK o flujos de nivel superior:

describe lsp y code_intelligence como superficies semánticas distintas
distingue las operaciones públicas de herramientas de las funciones de ayuda internas
describe solo las garantías de auditoría y reproducción que de verdad se conservan en los esquemas actuales
menciona las marcas cuando una superficie semántica no está siempre activada
al mencionar AX Wiki, mantén explícitas las responsabilidades de la wiki frente a las del grafo