Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Camada semântica

Status: Ativo Escopo: estado atual Última revisão: 2026-05-03 Responsável: runtime do ax-code

Este documento descreve a camada semântica que existe hoje no AX Code. É um contrato do estado atual, não um roteiro.

Fonte da verdade

Esta página documenta o comportamento semântico já entregue, não ambições futuras de grafo de código. Quando o comportamento mudar, confira contra:

packages/ax-code/src/tool/lsp.ts e módulos LSP relacionados, para operações semânticas ao vivo.
packages/ax-code/src/code-intelligence/ para o comportamento do grafo indexado.
packages/ax-code-reason/ para análises de depuração e refatoração apoiadas no grafo (impacto, caminhos de bug, condições de corrida, ciclo de vida, duplicação, valores fixos no código, achados de segurança e aplicação de refatoração com gate).
Testes de replay, exportação e auditoria antes de afirmar garantias duráveis de proveniência.

Se uma capacidade é planejada ou experimental, mantenha esse status explícito.

Finalidade

O AX Code expõe respostas semânticas por duas fontes explícitas:

lsp: consultas ao vivo ao servidor de linguagem
graph: consultas persistentes de inteligência de código

O sistema não encaminha uma para a outra em silêncio. Quem chama escolhe a superfície segundo atualidade, latência e requisitos de determinismo.

Superfícies semânticas atuais

Superfície	Fonte de apoio	Papel atual
ferramenta `lsp`	clientes LSP ao vivo	respostas semânticas mais recentes, superfície explícita de consulta ao vivo
ferramenta `code_intelligence`	grafo de código SQLite indexado	consultas determinísticas de grafo sobre símbolos, referências e relações de chamada indexados

A ferramenta lsp é a interface semântica ao vivo. A ferramenta code_intelligence é a interface semântica indexada. Nenhuma é contingência oculta da outra.

Gate atual:

code_intelligence fica ativado por padrão, mas pode ser desativado com indicadores de recurso
lsp hoje exige o indicador experimental da ferramenta LSP

Contrato do envelope

Respostas semânticas carregam metadados de proveniência, para que consumidores a jusante possam raciocinar sobre confiança e atualidade.

Campos comuns:

source: lsp, graph ou cache
completeness: full, partial ou empty
timestamp: quando a resposta subjacente foi resolvida
degraded: sinal opcional de que a resposta deve ser tratada com cautela

Envelopes apoiados em LSP também podem incluir:

serverIDs: quais servidores de linguagem contribuíram
cacheKey: referência estável a uma linha do cache de resposta LSP

Auditoria e replay

Comportamento atual:

chamadas semânticas ao vivo pela ferramenta lsp gravam linhas audit_semantic_call
o replay de ferramenta agora preserva tool.result.metadata, o que significa que metadados semânticos apoiados no grafo não se perdem durante replay e exportação
o replay determinístico compara metadados do caminho de decisão, não a igualdade semântica de cada lista de símbolos devolvida

Isso dá às respostas semânticas apoiadas em LSP e apoiadas em grafo uma visibilidade de auditoria comparável, ainda que elas venham de caminhos diferentes de armazenamento e de runtime.

Operações expostas atuais

`lsp`

A superfície ao vivo lsp inclui operações apoiadas em envelope para:

definição
referências
hover
símbolos do documento
símbolos do espaço de trabalho
implementações
hierarquia de chamadas
diagnósticos agregados

Esta é a superfície certa quando a recência importa mais que a repetibilidade.

`code_intelligence`

A superfície de grafo inclui:

busca de símbolo
símbolos de arquivo
referências
chamadores
chamados

Esta é a superfície certa quando a repetibilidade e a menor latência importam mais que a atualidade imediata do estado do editor.

Uma terceira superfície de conhecimento, opcional, é a wiki semântica nativa do repositório em .ax-wiki/, compilada por ax-code wiki. Ela não faz parte do contrato estrutural de envelope de grafo e LSP acima.

Superfície	Papel
`lsp` / `code_intelligence`	Precisão estrutural (este documento)
`.ax-wiki/`	Narrativa de arquitetura apoiada na fonte, para agentes

Veja Compilador AX Wiki para CLI, roteamento e não objetivos. A síntese da wiki não deve ser tratada como substituto de chamadores, chamados e referências.

Não objetivos importantes

A camada semântica atual não faz estas coisas:

sem roteamento oculto com grafo primeiro e contingência automática de LSP
sem afirmação de que a atualidade do grafo equivale à atualidade do LSP ao vivo
sem afirmação de que cada auxiliar semântico interno é exposto por HTTP ou SDK
sem divisão de runtime semântico em Rust na implementação atual
sem afirmação de que o Markdown da AX Wiki é uma fonte estrutural da verdade (veja Compilador AX Wiki)

Orientação de integração

Ao escrever documentação, bindings de SDK ou fluxos de nível mais alto:

descreva lsp e code_intelligence como superfícies semânticas separadas
distinga operações públicas de ferramenta de funções auxiliares internas
descreva apenas garantias de auditoria e de replay que de fato estão preservadas nos esquemas atuais
mencione indicadores quando uma superfície semântica não está sempre ativada
ao mencionar a AX Wiki, mantenha explícitas as responsabilidades da wiki e as do grafo