feat(plugin): команда /kompas:doctor

2026-07-31 02:20:42 +03:00
parent 7c4d7b2c3e
commit 30197b34c7
2 changed files with 69 additions and 0 deletions
@@ -0,0 +1,56 @@
+---
+description: Диагностика установки плагина КОМПАС-3D: версия сервера, кеш, соединение с КОМПАС
+---
+
+Проверь установку плагина `kompas` по шагам и дай отчёт на русском. На каждый неуспешный пункт
+назови конкретное действие, которое пользователь может сделать сам (без доступа к исходникам
+проекта). Не переходи к следующему пункту, если текущий выявил фатальную проблему — сразу
+переходи к отчёту с найденной причиной.
+
+1. **Ожидаемая версия.** Прочитай `${CLAUDE_PLUGIN_ROOT}/server.lock.json` — поле `version`.
+   Если `version` равна `0.0.0`, релиз сервера ещё не публиковался: единственный рабочий вариант —
+   собрать сервер локально (`dotnet build -c Release` в проекте `kompas3d-mcp`) и указать путь к
+   `kompas-mcp.exe` в переменной окружения `KOMPAS_MCP_EXE`. Дальше по этому пункту нечего
+   проверять — переходи к пункту 2.
+
+2. **Локальная сборка вместо релиза.** Проверь переменную окружения `KOMPAS_MCP_EXE`
+   (в PowerShell: `$env:KOMPAS_MCP_EXE`). Если она задана — это режим разработки: используется
+   указанный в ней бинарь, а не установка из `server.lock.json`. Проверь, что файл по этому пути
+   существует. Не существует — попроси пользователя пересобрать проект или поправить переменную.
+   Если `KOMPAS_MCP_EXE` задана и файл на месте, пункты 3–4 (кеш релиза) пропусти — они к этому
+   режиму не относятся, сразу переходи к пункту 5.
+
+3. **Кеш установленного сервера.** Если `KOMPAS_MCP_EXE` не задана, сервер разворачивается в
+   `%LOCALAPPDATA%\kompas-mcp\<version>` (`<version>` — значение из `server.lock.json`). Проверь
+   там файл `install.json` и сверь его поля `version`/`sha256` со значениями `version`/`sha256`
+   из `server.lock.json`.
+   - Файла `install.json` нет или его не удаётся прочитать — установка ещё не выполнялась или
+     повреждена: следующий запуск сервера (например, через любой инструмент `kompas_*`) должен
+     скачать и распаковать её заново. Если и это не помогает — удали каталог
+     `%LOCALAPPDATA%\kompas-mcp\<version>` целиком и повтори запуск.
+   - Поля не совпадают с локом — установка устарела или повреждена: удали каталог
+     `%LOCALAPPDATA%\kompas-mcp\<version>` и дай серверу переустановиться при следующем запуске.
+
+4. **Бинарь на месте и версия совпадает.** Проверь, что `kompas-mcp.exe` лежит рядом с
+   `install.json` в том же каталоге, и его версия (флаг `--version`) совпадает с версией из
+   `server.lock.json`. Расхождение или ошибка запуска — тот же диагноз, что и в пункте 3: удали
+   каталог версии и дай серверу переустановиться.
+
+5. **КОМПАС-3D запущен или доступен для запуска.** Сервер подключается к КОМПАС лениво — не при
+   старте MCP-сервера, а при первом вызове инструмента. Убедись, что КОМПАС-3D установлен на этой
+   машине. Если он уже запущен, сервер присоединится к нему; если нет — попробует запустить новый
+   экземпляр сам. Если КОМПАС не установлен вовсе — это и есть причина сбоя: попроси пользователя
+   установить КОМПАС-3D.
+
+6. **Проверка соединения инструментами MCP.** Вызови инструмент `kompas_connect` — он либо
+   присоединится к уже запущенному КОМПАС, либо запустит новый и покажет окно, и вернёт версию и
+   редакцию. Если вызов упал с ошибкой — приложи её текст к отчёту дословно (обычно это означает,
+   что КОМПАС не установлен, лицензия не активирована, или предыдущий процесс КОМПАС завис —
+   попроси пользователя проверить лицензию и вручную закрыть зависшие процессы КОМПАС через
+   Диспетчер задач). Затем вызови `kompas_status`, чтобы явно зафиксировать итоговое состояние
+   подключения в отчёте — учти, что сам по себе `kompas_status` не пытается подключиться, а
+   только читает текущее состояние сессии, поэтому он осмыслен только после `kompas_connect`.
+
+7. **Итог.** Собери отчёт: ожидаемая версия сервера, источник бинаря (релизный кеш или
+   `KOMPAS_MCP_EXE`), путь до него, результат `kompas_connect`/`kompas_status`, и — если что-то не
+   сошлось — какое из действий выше нужно предпринять пользователю.
@@ -80,4 +80,17 @@ public sealed class PluginManifestTests
        var serverLock = Read("server.lock.json");
        Assert.True(IsReleasedLockValid(serverLock));
    }
+
+    [Fact]
+    public void Doctor_command_exists_and_checks_connection()
+    {
+        var path = Path.Combine(PluginRoot, "commands", "doctor.md");
+        Assert.True(File.Exists(path), $"нет файла {path}");
+
+        var text = File.ReadAllText(path);
+        Assert.StartsWith("---", text, StringComparison.Ordinal);
+        Assert.Contains("description:", text, StringComparison.Ordinal);
+        Assert.Contains("server.lock.json", text, StringComparison.Ordinal);
+        Assert.Contains("kompas_status", text, StringComparison.Ordinal);
+    }
 }