Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Семантический слой

Статус: действует Область: текущее состояние Последняя проверка: 2026-05-03 Владелец: среда выполнения ax-code

Этот документ описывает семантический слой, который есть в AX Code сегодня. Это контракт текущего состояния, а не дорожная карта.

Источник истины

Эта страница документирует поставляемое семантическое поведение, а не будущие амбиции графа кода. Когда поведение меняется, сверьте его с:

packages/ax-code/src/tool/lsp.ts и связанными модулями LSP для живых семантических операций.
packages/ax-code/src/code-intelligence/ для поведения индексированного графа.
packages/ax-code-reason/ для анализов отладки и рефакторинга на графе (влияние, пути ошибок, гонки, жизненный цикл, дублирование, зашитые значения, находки безопасности и применение рефакторинга за шлюзом).
Проверками воспроизведения, экспорта и аудита, прежде чем заявлять устойчивые гарантии происхождения.

Если возможность запланирована или экспериментальна, держите этот статус явным.

Назначение

AX Code открывает семантические ответы через два явных источника:

lsp: живые запросы языкового сервера
graph: устойчивые запросы разведки кода

Система не направляет один в другой молча. Вызывающий выбирает поверхность по требованиям свежести, задержки и детерминизма.

Текущие семантические поверхности

Поверхность	Источник	Текущая роль
инструмент `lsp`	живые клиенты LSP	самые свежие семантические ответы, явная поверхность живого запроса
инструмент `code_intelligence`	индексированный граф кода SQLite	детерминированные запросы графа по индексированным символам, ссылкам и отношениям вызовов

Инструмент lsp — интерфейс живой семантики. Инструмент code_intelligence — интерфейс индексированной семантики. Ни один не является скрытым запасным путём для другого.

Текущие шлюзы:

code_intelligence включён по умолчанию, но его можно отключить флагами функций
lsp сейчас требует экспериментальный флаг инструмента LSP

Контракт конверта

Семантические ответы несут метаданные происхождения, чтобы нижестоящие потребители могли судить о доверии и свежести.

Общие поля:

source: lsp, graph или cache
completeness: full, partial или empty
timestamp: когда нижележащий ответ был разрешён
degraded: необязательный сигнал, что к ответу следует относиться осторожно

Конверты на LSP могут также включать:

serverIDs: какие языковые серверы внесли вклад
cacheKey: устойчивая ссылка на строку кэша ответа LSP

Аудит и воспроизведение

Текущее поведение:

живые семантические вызовы через инструмент lsp пишут строки audit_semantic_call
воспроизведение инструментов теперь сохраняет tool.result.metadata, поэтому семантические метаданные на графе не теряются при воспроизведении и экспорте
детерминированное воспроизведение сравнивает метаданные пути решений, а не семантическое равенство каждого возвращённого списка символов

Это даёт ответам на LSP и на графе сравнимую видимость аудита, хотя они по-прежнему приходят из разных путей хранения и среды выполнения.

Текущие открытые операции

`lsp`

Живая поверхность lsp включает операции с конвертом для:

определения
ссылок
всплывающей подсказки
символов документа
символов рабочей области
реализаций
иерархии вызовов
сводной диагностики

Это верная поверхность, когда свежесть важнее повторяемости.

`code_intelligence`

Поверхность графа включает:

поиск символа
символы файла
ссылки
вызывающих
вызываемых

Это верная поверхность, когда повторяемость и меньшая задержка важнее немедленной свежести состояния редактора.

Третья, необязательная поверхность знания — собственная семантическая вики репозитория в .ax-wiki/, которую компилирует ax-code wiki. Она не входит в структурный контракт конверта графа и LSP выше.

Поверхность	Роль
`lsp` / `code_intelligence`	Структурная точность (этот документ)
`.ax-wiki/`	Повествование об архитектуре с опорой на исходники для агентов

CLI, маршрутизацию и не-цели см. в AX Wiki. Синтез вики нельзя считать заменой вызывающих, вызываемых и ссылок.

Важные не-цели

Текущий семантический слой этого не делает:

нет скрытой маршрутизации «сначала граф» с автоматическим запасным путём LSP
нет заявления, что свежесть графа равна свежести живого LSP
нет заявления, что каждый внутренний семантический помощник открыт через HTTP или SDK
нет разделения семантической среды выполнения на Rust в текущей реализации
нет заявления, что Markdown AX Wiki — структурный источник истины (см. AX Wiki)

Руководство по интеграции

Когда пишете документацию, привязки SDK или рабочие процессы более высокого уровня:

описывайте lsp и code_intelligence как отдельные семантические поверхности
отличайте публичные операции инструментов от внутренних функций-помощников
описывайте только те гарантии аудита и воспроизведения, которые действительно сохранены в текущих схемах
упоминайте флаги, когда семантическая поверхность включена не всегда
упоминая AX Wiki, явно разделяйте обязанности вики и графа