Протокол языкового сервера (LSP)

Hermes запускает полноценные языковые серверы — пирайт, гоплс, ржавчин-анализатор, typescript-language-server, clangd и ещё ~20 — как фоновые подпроцессы и передаёт их семантическую коррекцию в пост-записную проверку lint, Используем write_file и patch. Когда агент редактирует файл, он видит именно те ошибки, которые принес этот редактор — не только синтаксические ошибки, но и ошибки типа, неопределенные имена, отсутствующие импорты и семантические проблемы на уровне всего проекта, которые обнаруживают языковой сервер.

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

Когда запускается LSP

LSP включается при обнаружении git-рабочего пространства. Когда каталог агента (или редактируемый файл) находится внутри git-репозитория, LSP работает с этим необходимым пространством. Когда ни то, ни другое не находится в git-репозитории, LSP остается неактивным — полезно для шлюза обмена сообщениями, где текущая рабочая директория — это домашняя директория пользователя и нет проекта для диагностики.

Проверка многоуровневая: сначала внутрипроцессная синтаксическая проверка (микросекунды), затем диагностика LSP, когда синтаксис чист. Неисправный или отсутствующий никогда языковой сервер не может сломать запись — каждый путь отклоняет LSP бесшумно возвращается к результату только синтаксической проверки.

Конкретно, при каждом успешном write_file или patch:

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

Агент видит вывод, ведущий это:

{
  "bytes_written": 42,
  "dirs_created": false,
  "lint": {"status": "ok", "output": ""},
  "lsp_diagnostics": "LSP diagnostics introduced by this edit:\n<diagnostics file=\"/path/to/foo.py\">\nERROR [42:5] Cannot find name 'foo' [reportUndefinedVariable] (Pyright)\nERROR [50:1] Argument of type \"str\" is not assignable to \"int\" [reportArgumentType] (Pyright)\n</diagnostics>"
}

Поле lint несёт результат синтаксической проверки (микросекундный внутрипроцессный разбор через ast.parse, json.loads и т.д.); поле lsp_diagnostics несёт семантическую оценку от реальной языкового сервера. Два канала, независимые сигналы — агент видит синтаксически чистый файл с семантическими проблемами как lint: ok плюс заполненный lsp_diagnostics.

Поддерживаемые языки

Язык	Сервер	Автоустановка
Питон	`pyright-langserver`	НПМ
TypeScript/JavaScript/JSX/TSX	`сервер-языка машинописного текста`	НПМ
Вуэ	`@vue/language-server`	НПМ
Стройная	`svelte-language-server`	НПМ
Астро	`@astrojs/language-server`	НПМ
Перейти	`гоплс`	`иди установи`
Ржавчина	`анализатор ржавчины`	вручную (ржавчина)
Си/С++	`клангд`	вручную (LLVM)
Баш/Зш	`bash-язык-сервер`	НПМ
ЯМЛ	`yaml-язык-сервер`	НПМ
Луа	`lua-язык-сервер`	вручную (выпуски GitHub)
PHP	`интелефенс`	НПМ
OCaml	`ocaml-lsp`	вручную (опам)
Докерфайл	`dockerfile-language-server-nodejs`	НПМ
Терраформировать	`терраформ-лс`	вручную
Дарт	`dart языковой сервер`	вручную (dart SDK)
Хаскелл	`язык-хаскелл-сервер`	вручную (ghcup)
Юлия	`Джулия` + LanguageServer.jl	вручную
Кложур	`clojure-lsp`	вручную
Никс	`никсд`	вручную
Зиг	`злс`	вручную
Блеск	`блеск лсп`	вручную (блеск установить)
Эликсир	`эликсир-ls`	вручную
Призма	`языковой сервер Prisma`	вручную
Котлин	`котлин-язык-сервер`	вручную
Ява	`jdtls`	вручную

Для «вручной» записи установите сервер через соответствующий менеджер инструментов для этого языка (rustup, ghcup, opam, Brew, …). Hermes автоматически обнаруживает бинарник в PATH или в <HERMES_HOME>/lsp/bin/.

Некоторые серверы поддерживаются вместе с зависимостью, которую npm не вытягивает автоматически. Текущий случай — typescript-language-server, который требует, чтобы SDK typescript был импортируемым из того же самого дерево node_modules — Hermes устанавливает оба пакета вместе, когда вы Запустите «hermes lsp install typescript» или автоустановку при первом использовании.

интерфейс командной строки

hermes lsp status          # состояние сервиса + статус установки для каждого сервера
hermes lsp list            # реестр, опционально --installed-only
hermes lsp install <id>    # немедленно установить один сервер
hermes lsp install-all     # попробовать каждый сервер с известным рецептом
hermes lsp restart         # завершить работающие клиенты
hermes lsp which <id>      # вывести разрешённый путь к бинарнику

hermes lsp status — лучшая отправная точка — он показывает, какие языки будут получать семантическую оценку сегодня, а для каких необходимо установить бинарник.

Конфигурация

Настройки по умолчанию работают для типичных конфигураций; ничего задавать не нужно, если бинарники находятся в PATH.

# config.yaml
lsp:
  # Главный переключатель. Отключение пропускает всю подсистему — никакие серверы
  # не запускаются, фоновый цикл событий не работает.
  enabled: true

  # Как долго ждать диагностики после каждой записи.
  wait_mode: document      # "document" или "full"
  wait_timeout: 5.0

  # Как обрабатывать отсутствующие бинарники серверов.
  #   auto    — установить через npm/pip/go install в <HERMES_HOME>/lsp/bin
  #   manual  — использовать только бинарники, уже находящиеся в PATH
  install_strategy: auto

  # Переопределения для каждого сервера (все опциональны).
  servers:
    pyright:
      disabled: false
      command: ["/abs/path/to/pyright-langserver", "--stdio"]
      env: { PYRIGHT_LOG_LEVEL: "info" }
      initialization_options:
        python:
          analysis:
            typeCheckingMode: "strict"
    typescript:
      disabled: true       # пропускать TS, даже если его расширения совпадают

Ключи для каждого сервера

disabled: true — полностью пропустить этот сервер, даже если его расширение произойдет с файлом.
command: [bin,...args] — закрепить пользовательский путь к бинарнику. Обходит автоустановку.
env: {KEY: value} — дополнительные переменные окружения, запущенные технологическим процессом.
initialization_options: {...} — подключается с полезным инструментом LSP initializationOptions, отправляемым в рукопожатии initialize. Специально для сервера; обратитесь к документации языкового сервера.

Места установки

Когда install_strategy: auto, Hermes устанавливает бинарники в <HERMES_HOME>/lsp/bin/. NPM-пакеты рассматриваются в <HERMES_HOME>/lsp/node_modules/ с симлинками в бинарниках на один уровень выше. Го-бинарники ведут из go install с GOBIN, указывающим на промежуточный каталог.

Ничего никогда не настраивается в /usr/local/, ~/.local/ или любом другом общее место — промежуточный каталог полностью принадлежит Hermes и удаляется при сбросе профиля.

Характеристики производительности

Серверы LSP лениво происходят при первом использовании. Редактирование Python-файла в проекте, который никогда не видел трафика .py, запускает пирайт; запуск занимает 1-3 секунды для большинства серверов (анализатор ржавчины может занимать 10+ холодно нам проект). Последующие правки в том же рабочем пространстве снова использовать рабочий сервер.

Слой LSP добавляет несколько миллисекунд к чистым записям, когда диагностика не выполняется. выдаётся. Когда диагностика выдается, бюджет ожидания составляет wait_timeout секунд — обычно сервер отвечает за десять миллисекунд дляpyright/tsserver и за несколько секунд для ржавчина-анализатор во время индексации.

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

Отключение

Установите lsp.enabled: false в config.yaml, чтобы отключить все подсистему. Постзаписная проверка возвращается к внутрипроцессной синтаксической сторону (ast.parse для Python, json.loads для JSON и т.д.), которая увеличение без изменений из-за более осторожного подхода.

Чтобы отключить один язык без отключения всего слоя:

lsp:
  servers:
    rust-analyzer:
      disabled: true

Устранение неполадок

hermes lsp status показывает сервер как "отсутствующий"

Бинарник отсутствует в PATH и не находится в <HERMES_HOME>/lsp/bin/. Запустите hermes lsp install <server_id>, чтобы граждане выполнили автоустановку или установили бинарник вручную через обычный инструментарий языка.

Раздел Backend alerts в hermes lsp status

Некоторые серверы называются тонкими обёртками вокруг внешнего CLI для фактической Диагностика — они проявляют чистоту и принимают указания, но никогда не выдают ошибка, когда вспомогательный бинарник отсутствует. Самый распространённый случай — это bash-language-server, который делегирует проверку shellcheck. Когда hermes lsp status покажет раздел Backend alerts, установите именованный инструмент через пакет менеджера вашей ОС:

apt install shellcheck      # Debian / Ubuntu
brew install shellcheck     # macOS
scoop install shellcheck    # Windows

То же предупреждение регистрируется один раз при запуске сервера в ~/.hermes/logs/agent.log.

Сервер запускается, но никогда не сохраняет результаты

Проверить ~/.hermes/logs/agent.log на наличие записей [agent.lsp.client] — Использование stderr от языкового сервера, а также ошибок протокола. Некоторые серверы (особенно анализатор ржавчины) должны обрабатывать индексацию всего проекта, прежде чем они выполнят проверку для каждого файла; первое изменение после запуска сервера может образоваться без диагностики, а другая правки ее подхватят.

Сервер упал

Упавший сервер включается в набор сломанных и не будет повторно запущен до конца сессия. Запустите hermes lsp restart, чтобы сохранить набор; следующее изменение перезапустить его.

Редактирование файла вне любой git-репозитории

По дизайну LSP работает только внутри git-репозитория. Если проект ещё не Разработано, запустите git init, чтобы включить проверку LSP. В противном случае применять внутрипроцессный запасной вариант только с синтаксической проверкой.