kompas-plugin/plugin/commands/doctor.md

description

description
Диагностика установки плагина КОМПАС-3D: версия сервера, .NET, interop, соединение с КОМПАС

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

1. Ожидаемая версия. Прочитай ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json — поле version. Это версия, которую Claude Code считает установленной; сервер едет в том же дереве плагина, отдельной установки и кеша у него нет.

2. Локальная сборка вместо поставки. Проверь переменную окружения KOMPAS_MCP_EXE (в PowerShell: $env:KOMPAS_MCP_EXE). Если она задана — это режим разработки: используется указанный в ней бинарь, а не поставленный с плагином. Проверь, что файл по этому пути существует; не существует — попроси пользователя пересобрать проект или снять переменную.

3. Сервер на месте и запускается. Если KOMPAS_MCP_EXE не задана, бинарь лежит в ${CLAUDE_PLUGIN_ROOT}/bin/kompas-mcp.exe. Проверь, что файл есть, и выполни & "<путь>\kompas-mcp.exe" --version — команда печатает версию и сразу выходит, КОМПАС при этом не запускается. Разбирай результат так:

   • файла нет — установка повреждена: /plugin update kompas@kompas-plugin, при необходимости переустановить плагин;
   • команда не запустилась и в ошибке упомянут .NET / hostfxr / «framework» — на машине нет нужного рантайма (см. пункт 4);
   • версия не совпала с plugin.json — обновление применилось наполовину: /plugin update kompas@kompas-plugin, затем /reload-plugins.

4. .NET Runtime. Сервер поставляется framework-dependent, поэтому рантайм нужен на машине: dotnet --list-runtimes должен показать строку Microsoft.NETCore.App 8.<любая> или новее (x64). Ни одной подходящей строки или самой команды dotnet нет — это и есть причина сбоя пункта 3: попроси пользователя поставить .NET Runtime 8 или новее с https://dotnet.microsoft.com/download/dotnet (нужен именно x64; Desktop Runtime не обязателен).

5. КОМПАС-3D установлен и, возможно, уже запущен. Сервер подключается к КОМПАС лениво — не при старте MCP-сервера, а при первом вызове инструмента. Проверь двумя командами: Get-Process KOMPAS* -ErrorAction SilentlyContinue (запущен ли сейчас) и Get-ChildItem 'HKLM:\SOFTWARE\Classes\KOMPAS.Application.5' -ErrorAction SilentlyContinue (зарегистрирован ли COM-класс, то есть установлен ли КОМПАС вообще). Запущен — сервер присоединится к нему; не запущен, но зарегистрирован — попробует запустить новый экземпляр сам; не зарегистрирован — это и есть причина сбоя: попроси пользователя установить КОМПАС-3D.

6. Interop-сборки КОМПАС. Сервер их не поставляет (они принадлежат АСКОН) и берёт из установки КОМПАС: <каталог установки>\SDK\Samples\CSharp.zip, каталог Common внутри архива, распаковка — в %LOCALAPPDATA%\kompas-mcp\interop\<ключ>. Проверь наличие архива: Test-Path ((Get-ItemProperty "HKLM:\SOFTWARE\Classes\CLSID\$((Get-ItemProperty 'HKLM:\SOFTWARE\Classes\KOMPAS.Application.5\CLSID').'(default)')\LocalServer32").'(default)'.Trim('"') | Split-Path | Split-Path | Join-Path -ChildPath 'SDK\Samples\CSharp.zip'). Архива нет — КОМПАС установлен без компонента SDK: попроси пользователя доустановить SDK либо задать переменную окружения KOMPAS_INTEROP_DIR с каталогом, где лежат KompasAPI7.dll, Kompas6API5.dll, Kompas6Constants.dll, Kompas6Constants3D.dll. Если переменная KOMPAS_INTEROP_DIR уже задана — проверь, что эти четыре файла в указанном каталоге есть.

7. Проверка соединения инструментами MCP. Вызови инструмент kompas_connect — он либо присоединится к уже запущенному КОМПАС, либо запустит новый и покажет окно, и вернёт версию и редакцию. Если вызов упал с ошибкой — приложи её текст к отчёту дословно (обычно это означает, что КОМПАС не установлен, лицензия не активирована, или предыдущий процесс КОМПАС завис — попроси пользователя проверить лицензию и вручную закрыть зависшие процессы КОМПАС через Диспетчер задач). Затем вызови kompas_status, чтобы явно зафиксировать итоговое состояние подключения в отчёте — учти, что сам по себе kompas_status не пытается подключиться, а только читает текущее состояние сессии, поэтому он осмыслен только после kompas_connect. Отдельный случай: если kompas_status вернул сообщение про interop-сборки — это диагноз пункта 6, а не проблема соединения.

8. Итог. Собери отчёт: версия плагина, источник бинаря (поставка или KOMPAS_MCP_EXE), путь до него, версия найденного .NET Runtime, результат kompas_connect/kompas_status, и — если что-то не сошлось — какое из действий выше нужно предпринять пользователю.