---
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-maintainer`.

## Два правила прежде всего

**1. «Зрение» — структурное, не по картинке.** Чтобы «увидеть» деталь, вызывай **`describe_model`** —
это единый структурный паспорт одним запросом: габарит, МЦХ, тела, топология (грани/рёбра, сгруппированные
по типам), дерево построения с параметрами, переменные. Это **точнее и дешевле по контексту**, чем
`model_snapshot`. Для деталей углубляйся `describe_face` / `describe_edge` / `measure` / `list_faces|edges|bodies|features|variables`.
**`model_snapshot` бери только** для визуально-пространственных вопросов, на которые паспорт не отвечает
(общая форма, ориентация, правдоподобность результата, «куда смотрит грань»). **Не анализируй изображение
там, где достаточно чисел** — снимок дорог по контексту и менее точен.

**2. `validate_part` — после КАЖДОЙ операции.** Любая формообразующая или прямое редактирование
(`extrude_*`/`revolve_*`/`fillet_*`/`chamfer_*`/`move_face`/`split_solid_by_plane`/`move_body`/`boolean_union`)
может «пройти» (`Update()==true`), оставив деталь в ошибке. После каждой операции вызывай `validate_part`:
**пустой результат = чисто; непустой = провал** (напр. `et3dError54`) — не продолжай и не экспортируй,
исправь или переделай другим методом. Перед `export_step` / выдачей результата — обязательно чистый `validate_part`.
(`move_face`/`move_body`/`boolean_union` сами дописывают итог `validate_part` в ответ, но проверяй явно после
формообразующих тоже.)

## Инструменты MCP

**Реализованы (v2+, 46 инструментов):**
- *Система/документы:* `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`.
- *Прямое редактирование (без дерева, в т.ч. импортированная B-rep):* `move_face` (сдвинуть грань на N мм по нормали), `split_solid_by_plane` (рассечь тело плоскостью), `move_body` (сдвинуть тело на вектор), `boolean_union` (объединить тела).
- *Обмен:* `import_step`, `export_step`.
- *Запрос/осмотр:* `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components`, `list_bodies`, `list_features`, `list_variables`, `measure`, `describe_model|face|edge` (структурный осмотр без снимка), `model_snapshot`.
- *Проверка:* `validate_part` (операции в ошибке / требующие перестроения).

**Планируются (трансляция SDK, по мере кейсов):** массивы/паттерны, оболочка/уклон, запись переменных, 2D-чертёж, построение сборок.

> Если нужного инструмента ещё нет — не хардкодь обход под кейс. Заведи кейс в `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`/… → **`validate_part`** (правило 2).
5. **Осмотр — структурно:** `describe_model` (паспорт: габарит, МЦХ, топология, дерево). Снимок — только если нужен визуальный контроль.
6. Итерация «на грани»: `describe_model`/`list_faces` (+`describe_face`) → `sketch_create_on_face_index` → операция → `validate_part`.

## Работа с импортом / сборками (выработано в usecases/0002)

Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»:

1. **Импорт STEP** в новый документ (под капотом: встроенный конвертер по коду формата
   `ksConverterFromSTEP`, затем `ConvertFromAdditionFormat`). Тип документа выбирается по
   содержимому: сборка → `.a3d`, одиночное тело → деталь.
2. **Разбор сборки**: перечислить компоненты (имя, обозначение, габарит, файл) — обход `TopPart → Parts`.
3. **Извлечение отдельной детали**: при импорте включать «создавать файлы компонентов», тогда
   компоненты пишутся как отдельные `.m3d` рядом; открывать деталь самостоятельным документом
   (`OpenSourceDocument`). Гашение видимости компонента на снимок **не влияет** — изоляция так не делается.
4. **Осмотр детали — структурно:** `describe_model` (габарит по осям → какая ось «высота», МЦХ,
   тела, топология). Грани/рёбра под операцию — `list_faces`/`describe_face`, `measure`. `model_snapshot`
   (или стандартные проекции `#Спереди/#Сверху/#Слева/#Справа/#Изометрия`) — **только** если нужен
   визуально-пространственный контроль формы.
5. **Модификация** на «тупой» импортированной B-rep (после каждой операции — `validate_part`):
   - *Простой случай* — `move_face`: сдвинуть плоскую грань на +N мм (наружу) или −N (внутрь).
     ⚠ На сложном торце (с отверстием/пазом) FaceMover может дать `et3dError54`.
   - *Вставка N мм в середину призматической ножки* (надёжно, грани совпадают):
     `split_solid_by_plane(plane, offset)` → `move_body(индекс верхнего тела, dz=N)` →
     `move_face(точка на грани реза, +N)` (мост) → `boolean_union()`.
6. **Проверка перед выдачей:** `validate_part` — чисто; затем **Экспорт STEP** `export_step(path, format=auto|ap203|ap214|ap242)`.

Точные COM-приёмы и сигнатуры — в авто-памяти `kompas-step-and-assembly-api` и в `usecases/0002/case.md`.

## Эвристики и подводные камни

- **Зрение — структурное (правило 1).** Осматривай через `describe_model`/`describe_face`/`describe_edge`/`measure`,
  а не снимком. `model_snapshot` — только для визуально-пространственных вопросов; не гоняй картинку зря.
- **`validate_part` после каждой операции (правило 2).** `Update()==true` ≠ успех; непустой `validate_part`
  (напр. `et3dError54`) — деталь невалидна, в STEP/печать не брать.
- **Грань/ребро по индексу надёжнее, чем по точке.** Сначала `list_faces`/`list_edges` (или `describe_model`),
  затем `*_on_face_index` / `*_edge_index`. По точке (`SelectByPoint`) — только когда индекс не подходит.
- **Направление операции.** `extrude_boss(..., forward)` / `move_face(distance±)` может уйти «не туда» —
  сверяй результат `get_bounding_box`/`describe_model` (числами), снимок лишь при необходимости.
- **МЦХ.** Объём/масса меняющейся геометрии бери через `get_part_info`/`describe_model`; перед чтением после правок — `rebuild`.
- **id эскизов/операций** недействительны после смены активного документа (create/open/close).
- **Единицы — мм** (геометрия) и кг (масса). Локальные координаты эскиза ≠ мировые координаты модели.

## Открытые вопросы / границы

- **Прямое редактирование B-rep — реализовано полностью:** `move_face`, `split_solid_by_plane`,
  `move_body`, `boolean_union`. Цепочка cut→spread→union проверена end-to-end (usecases/0002,
  top_spacer 39.45→41.45 мм, `validate_part` чисто).
- Не реализованы как инструменты: массивы/паттерны, оболочка/уклон, запись переменных, 2D, сборки.

## Связанное

- Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`.
- Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`).
- Поиск по справке SDK: субагент **kompas-sdk-research**.
- Правка документации проекта: субагент **docs-maintainer**.
- Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода).
