--- name: kompas-3d description: > Методика работы с КОМПАС-3D через MCP-сервер этого проекта: построение и модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики, выработанные в usecases/. Триггеры: «построй деталь в КОМПАС», «импортируй STEP», «что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели». НЕ для поиска по справке SDK — это навык kompas-sdk-research. --- # kompas-3d — методика управления КОМПАС-3D через MCP ## Два слоя (важно не смешивать) - **MCP-сервер** (`src/Kompas.Mcp.Host`) — *инструмент*. Он **транслирует возможности COM API/SDK КОМПАС** в MCP-инструменты. Инструменты делаются **общими** (по возможностям SDK), а не под конкретную задачу. Расширяя MCP, добавляй универсальную операцию (например `import_step`, `list_components`, `export_step`, «переместить грань», «рассечь тело»), а не «сделать вот эту деталь». - **Этот навык** — *методика*. Как из общих инструментов собрать решение: порядок шагов, выбор геометрии, проверка результата, обход подводных камней. Подходы вырабатываются в **`usecases/`** и поднимаются сюда. Итог: **MCP = чем делать, навык = как делать.** Новый приём сначала обкатывается кейсом, потом обобщается: инструмент → в MCP, метод → в этот навык. ## Когда применять Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции, импорт/экспорт обменных форматов, разбор сборки, измерения, снимки. Для поиска сигнатур/констант в справке — отдельный навык `kompas-sdk-research`. Для правки документации — `docs-delegate`. ## Инструменты MCP **Реализованы (v2+, 35 инструментов):** `kompas_connect`, `kompas_set_visible`, `kompas_status`; `document_create|open|save|save_as|close|active`; `sketch_create`, `sketch_create_on_face[_index]`, `sketch_add_line|circle|rectangle|axis`, `sketch_close`; `extrude_boss|cut`, `revolve_boss|cut`, `fillet_edge[_index]`, `chamfer_edge[_index]`, `rebuild`; **`move_face`** (прямое редактирование: сдвинуть грань на N мм); `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components`; `import_step`, `export_step`; `model_snapshot`. **Планируются (трансляция SDK, по мере кейсов):** рассечение/перемещение тела как инструменты (`SplitSolids`/`BodyRepositions` — механика есть, продуктизация не закончена), `list_bodies`, массивы/паттерны, переменные/свойства. > Если нужного инструмента ещё нет — не хардкодь обход под кейс. Заведи кейс в `usecases/`, > докажи механику (тест или минимальный прогон в usecases/), затем продуктизируй как > **общий** инструмент MCP (с тестами, TDD) и опиши приём здесь. ## Базовый цикл (эскиз → операция → осмотр) Опорный сценарий построения, проверен end-to-end (см. `usecases/0001`): 1. `kompas_connect` (+ `kompas_set_visible true`, чтобы снимки были осмысленны). 2. `document_create part`. 3. `sketch_create XOY` → `sketch_add_*` → `sketch_close`. 4. `extrude_boss`/`revolve_boss`/… 5. **Осмотр:** `model_snapshot` (увидеть) + `get_part_info`/`get_bounding_box` (сверить числами). 6. Итерация «на грани»: `model_snapshot` → `list_faces` → `sketch_create_on_face_index` → операция. ## Работа с импортом / сборками (выработано в usecases/0002) Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»: 1. **Импорт STEP** в новый документ (под капотом: встроенный конвертер по коду формата `ksConverterFromSTEP`, затем `ConvertFromAdditionFormat`). Тип документа выбирается по содержимому: сборка → `.a3d`, одиночное тело → деталь. 2. **Разбор сборки**: перечислить компоненты (имя, обозначение, габарит, файл) — обход `TopPart → Parts`. 3. **Извлечение отдельной детали**: при импорте включать «создавать файлы компонентов», тогда компоненты пишутся как отдельные `.m3d` рядом; открывать деталь самостоятельным документом (`OpenSourceDocument`). Гашение видимости компонента на снимок **не влияет** — изоляция так не делается. 4. **Осмотр детали**: габарит по осям (какая ось — «высота»), `list_faces`/`list_edges`, стандартные проекции (`#Спереди/#Сверху/#Слева/#Справа/#Изометрия`) + `model_snapshot` для каждой. 5. **Модификация**: на «тупой» импортированной B-rep работает `move_face` — сдвинуть грань на +N мм (наружу, добавить материал) или −N мм (внутрь). Рассечение/раздвижка тела — механика есть, отдельных инструментов пока нет (см. ниже). 6. **Экспорт STEP**: `ConvertToAdditionFormat` (есть AP203/AP214/AP242). Точные COM-приёмы и сигнатуры — в авто-памяти `kompas-step-and-assembly-api` и в `usecases/0002/case.md`. ## Эвристики и подводные камни - **Решай по снимку.** После каждой формообразующей операции делай `model_snapshot` и проверяй визуально; числами — `get_part_info`/`get_bounding_box`. - **Грань/ребро по индексу надёжнее, чем по точке.** Сначала `list_faces`/`list_edges`, затем `*_on_face_index` / `*_edge_index`. По точке (`SelectByPoint`) — только когда индекс не подходит. - **Направление операции.** `extrude_boss(..., forward)` может уйти «не туда» в зависимости от нормали выбранной грани — проверь снимком, при необходимости инвертируй `forward`. - **МЦХ.** Объём/масса меняющейся геометрии бери через `get_part_info` (под капотом API5 `CalcMassInertiaProperties`); перед чтением после правок — `rebuild`. - **id эскизов/операций** недействительны после смены активного документа (create/open/close). - **Единицы — мм** (геометрия) и кг (масса). Локальные координаты эскиза ≠ мировые координаты модели. ## Открытые вопросы / границы - **Перемещение грани (`move_face`) — реализовано.** Работает на импортированной B-rep через `IPart7.FindObjectsByPoint` + `FaceMover`. Проверено: top_spacer 39.45→41.45 мм. - **Рассечение/перемещение тела** (`SplitSolids`/`BodyRepositions`) — механика задокументирована, отдельными MCP-инструментами не оформлена. Возможная следующая опция. - Сборки/паттерны/переменные в MCP пока не реализованы. ## Связанное - Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`. - Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`). - Поиск по справке SDK: навык **kompas-sdk-research**. - Правка документации проекта: навык **docs-delegate**. - Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода).