docs(plugin): README и адаптеры под Codex/opencode

2026-07-31 02:28:20 +03:00
parent 30197b34c7
commit 09f17fae16
6 changed files with 122 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Плагин `kompas` — КОМПАС-3D в Claude Code
+
+Даёт Claude Code инструменты управления КОМПАС-3D (детали, сборки, чертежи, STEP) и методику работы
+с ними: навыки `kompas:kompas-3d` и `kompas:kompas-fdm-design`.
+
+## Предпосылки
+
+- Windows x64;
+- установленный **и запущенный** КОМПАС-3D (проверено на v24 Home) — сервер является COM-клиентом,
+  а не автономным CAD-движком, и работает только на той же машине;
+- чекаут репозитория и рабочие файлы — вне синхронизируемых папок OneDrive.
+
+.NET Runtime ставить не нужно: сервер публикуется self-contained.
+
+## Установка
+
+1. `/plugin marketplace add https://git.shahovalov.ru/mikhail/home-repo-cc.git`
+2. `/plugin install kompas@home-repo-cc`
+3. `/kompas:doctor` — проверка. Первый запуск скачивает сервер (~70 МБ) в
+   `%LOCALAPPDATA%\kompas-mcp\<версия>` и сверяет SHA256 с `server.lock.json`.
+
+> На момент написания этого README релиза ещё не существует (`server.lock.json` в состоянии
+> `0.0.0`), а запись плагина `kompas` в каталоге `home-repo-cc` ещё не добавлена — шаги установки
+> выше описывают целевой процесс, но пока не выполнимы буквально. До первого релиза используйте
+> режим разработки (см. ниже).
+
+## Обновление
+
+Три шага, именно в таком порядке:
+
+1. `/plugin marketplace update home-repo-cc`
+2. `/plugin update kompas@home-repo-cc`
+3. при необходимости `/reload-plugins`
+
+Каталог приватный, поэтому на фоновое автообновление полагаться нельзя: фоновая синхронизация
+отключает git-credential-helper и по HTTPS не аутентифицируется. Надёжнее добавить каталог
+по SSH; при HTTPS выставьте `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`, чтобы неудачная
+фоновая синхронизация не сносила локальный клон.
+
+## Разработка сервера
+
+Собрать сервер локально и подсунуть его плагину:
+
+```powershell
+dotnet build -c Release
+$env:KOMPAS_MCP_EXE = "<путь>\src\Kompas.Mcp.Host\bin\x64\Release\net8.0-windows\kompas-mcp.exe"
+```
+
+Тогда лаунчер `scripts/launch-kompas-mcp.ps1` не обращается к релизу.
+
+## Другие харнессы (Codex, opencode)
+
+Тот же лаунчер подключается и к другим агентским харнессам — см. `adapters/codex/` и
+`adapters/opencode/`. Это сниппеты конфигурации и инструкция, а не отдельные дистрибутивы:
+контент (навыки, лаунчер) не размножается, новый харнесс стоит README + сниппета.
+
+## Прочее
+
+Каталог `%LOCALAPPDATA%\kompas-mcp` не очищается при обновлении и удалении плагина — старые версии
+удаляются вручную.
@@ -0,0 +1,19 @@
+# Подключение к Codex
+
+Codex не знает ни маркетплейсов, ни `${CLAUDE_PLUGIN_ROOT}`, поэтому подключение делается по пути
+к клону репозитория.
+
+1. Склонировать `https://git.shahovalov.ru/mikhail/kompas3d-mcp.git`.
+2. Вставить `config.snippet.toml` в `~/.codex/config.toml`, заменив `<PLUGIN>` на абсолютный путь
+   к каталогу `plugin/` клона. Лаунчер `scripts/launch-kompas-mcp.ps1` — тот же, что у плагина
+   Claude Code: он сам скачает сервер по `server.lock.json`.
+3. Навыки: выполнить `pwsh -File tools/sync-agent-assets.ps1` — навыки появятся в `.agents/skills/`.
+
+Формат сниппета (`[mcp_servers.<имя>]` с ключами `command`/`args`) проверен вживую —
+`codex mcp add kompas -- powershell ...` генерирует именно такую секцию (Codex CLI 0.145.0).
+
+Релиза сервера пока не существует (`server.lock.json` в состоянии `0.0.0`) — до первого релиза
+нужен режим разработки: собрать сервер локально и подставить путь к `kompas-mcp.exe` в переменную
+окружения `KOMPAS_MCP_EXE` (см. `../../README.md` §«Разработка сервера»).
+
+Это сниппет и инструкция, а не дистрибутив: полноценный плагин Codex — отдельная веха.
@@ -0,0 +1,5 @@
+# Вставить в ~/.codex/config.toml. <PLUGIN> — путь к каталогу plugin/ этого репозитория.
+[mcp_servers.kompas]
+command = "powershell"
+args = ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+        "-File", "<PLUGIN>/scripts/launch-kompas-mcp.ps1"]
@@ -0,0 +1,16 @@
+# Подключение к opencode
+
+1. Склонировать `https://git.shahovalov.ru/mikhail/kompas3d-mcp.git`.
+2. Слить `opencode.json` со своим конфигом opencode, заменив `<PLUGIN>` на абсолютный путь к
+   каталогу `plugin/` клона. Используется тот же лаунчер `scripts/launch-kompas-mcp.ps1`.
+3. Навыки: `pwsh -File tools/sync-agent-assets.ps1` — раскладывает их в `.agents/skills/`.
+
+Формат `opencode.json` — под MCP-сервер типа `local` команда со всеми аргументами лежит одним
+массивом строк в поле `command` (сверено со схемой `https://opencode.ai/config.json`,
+`$defs.McpLocalConfig`), отдельного поля `args` в этой схеме нет.
+
+Релиза сервера пока не существует (`server.lock.json` в состоянии `0.0.0`) — до первого релиза
+нужен режим разработки: собрать сервер локально и подставить путь к `kompas-mcp.exe` в переменную
+окружения `KOMPAS_MCP_EXE` (см. `../../README.md` §«Разработка сервера»).
+
+Это сниппет и инструкция, а не дистрибутив.
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "kompas": {
+      "type": "local",
+      "command": ["powershell", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                  "-File", "<PLUGIN>/scripts/launch-kompas-mcp.ps1"],
+      "enabled": true
+    }
+  }
+}
@@ -93,4 +93,15 @@ public sealed class PluginManifestTests
        Assert.Contains("server.lock.json", text, StringComparison.Ordinal);
        Assert.Contains("kompas_status", text, StringComparison.Ordinal);
    }
+
+    [Theory]
+    [InlineData("README.md")]
+    [InlineData("adapters/codex/config.snippet.toml")]
+    [InlineData("adapters/opencode/opencode.json")]
+    public void Adapters_reference_the_shared_launcher(string relativePath)
+    {
+        var path = Path.Combine(PluginRoot, relativePath.Replace('/', Path.DirectorySeparatorChar));
+        Assert.True(File.Exists(path), $"нет файла {path}");
+        Assert.Contains("launch-kompas-mcp.ps1", File.ReadAllText(path), StringComparison.Ordinal);
+    }
 }