kompas3d-mcp/plugin/skills/kompas-3d/SKILL.md

---
name: kompas-3d
description: >
  Методика работы с КОМПАС-3D через MCP-сервер плагина: построение и
  модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии
  снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС
  через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать
  сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
  проверенные на практике. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
  «что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели».
---

# kompas-3d — методика управления КОМПАС-3D через MCP

MCP-сервер даёт **общие** операции КОМПАС (эскизы, формообразующие, осмотр, обмен), этот навык —
**методику**: в каком порядке их применять, как выбирать геометрию, чем проверять результат и какие
подводные камни обходить. Коротко: **MCP = чем делать, навык = как делать.**

## Когда применять

Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции,
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки.

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

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

**2. Проверка построения приходит сама — читай её.** Любая операция может «пройти»
(`Create()/Update()==true`), оставив деталь в ошибке, поэтому **каждая мутирующая операция**
(`extrude`/`revolve`/`fillet_edge`/`chamfer_edge`/`hole`/`pattern`/`mirror`/`shell`/`rib`/`sweep`/`loft`/
`draft`/`move_face`/`move_body`/`boolean_union`/`set_variable`/сборочные) **сама дописывает итог проверки
к своему ответу**: «Построение чистое» = порядок, «⚠ Внимание: N операц. в ошибке» (напр. `et3dError54`)
= провал — не продолжай и не экспортируй, исправь или переделай другим методом. Отдельный `validate_part`
после каждого шага **не нужен**; зови его вручную, только если авто-проверку выключили
(`set_auto_validate(false)` или `KOMPAS_MCP_AUTOVALIDATE=0` — так делают на тяжёлой модели, где
проверка после каждого шага заметно тормозит). Перед `export_step`/выдачей результата убедись, что
последняя операция отчиталась чисто.

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

**Реализованы (56 инструментов).** Инструмент назван по СМЫСЛУ операции, а вид задаётся параметром —
не ищи отдельный инструмент под каждый вариант:

- *Система/документы:* `kompas_connect`, `kompas_set_visible`, `kompas_status`, `set_auto_validate`; `document_create|open|save|close|active` (`document_save(path)` — сохранить новый документ или копию, без `path` — на прежнее место); `set_part_info(name, marking)` — наименование и обозначение детали.
- *Эскиз (три инструмента вместо шестнадцати):* `sketch_create` — основание задаётся `plane` (+`offset`) ЛИБО `faceIndex` ЛИБО точкой `x,y,z`, а геометрия сразу списком `entities[{type: line|circle|rectangle|arc|arc3points|ellipse|polyline|polygon|spline|point|axis|text, …}]`; `sketch_add` — дополнить открытый эскиз; `sketch_close`.
- *Формообразующие:* `primitive(kind=block|cylinder|sphere|cone, result=new|union|subtract|intersect)` — тело по размерам БЕЗ эскиза, `extrude(mode=boss|cut)`, `revolve(mode=boss|cut)`, `fillet_edge`/`chamfer_edge` (одной операцией на все рёбра: список `edgeIndices` ЛИБО список `points[{x,y,z}]`, либо одна точка), `shell`, `rib`, `sweep`, `loft`, `draft`, `rebuild`. У всех — `name`: имя операции в дереве построения.
- *Отверстия:* `hole(type=simple|counterbore|countersink|conic)` — грань по `faceIndex` (центр грани) либо точкой.
- *Массивы и зеркало:* `pattern(kind=linear|circular)`, `mirror` (без `featureIds` — всё тело, с ними — только эти операции).
- *Прямое редактирование (без дерева, в т.ч. импортированная B-rep):* `move_face` (сдвинуть грань на N мм по нормали; грань — `faceIndex` или точка), `split_solid_by_plane` (рассечь тело плоскостью), `move_body` (сдвинуть тело на вектор), `boolean_union` (объединить тела).
- *Переменные:* `set_variable` (создаёт, если нет — проверять заранее не нужно), `delete_variable`.
- *Обмен:* `import_step`, `export_step`.
- *Сборка:* `assembly_add_component`, `assembly_add_mate`.
- *2D-чертёж:* `drawing_create_standard_views`, `drawing_fill_title_block`, `drawing_set_sheet_format`, `drawing_add_linear|diametral|radial|angular_dimension`, `drawing_add_rough`, `drawing_add_text`, `drawing_add_leader`, `drawing_set_technical_requirements`.
- *Запрос/осмотр:* `describe_model` (структурный паспорт; `sections=box,mass,bodies,topology,tree,variables` сужает ответ и чтение), `list_faces`/`list_edges` (без `index` — список, с `index` — подробности объекта), `list_components`, `list_bodies`, `list_features`, `list_variables`, `measure`, `model_snapshot`.
- *Проверка:* `validate_part` — нужен, только если авто-проверка выключена (см. правило 2).

Набор растёт от версии к версии — актуальный перечень с описаниями параметров отдаёт сам
MCP-сервер; если инструмента под задачу нет, собирай результат из имеющихся общих операций.

## Два пути формообразования — выбирай по форме, а не по привычке

«Эскиз → выдавливание» — не единственный способ. `primitive` строит тело сразу по размерам, и это
короче и надёжнее там, где форма призматическая:

| Форма | Чем строить |
|---|---|
| Плита, брусок, бобышка, штифт, цилиндрическая стойка | `primitive(kind=block\|cylinder)` — один вызов вместо «эскиз + выдавливание» |
| Прямоугольный карман, паз, срез угла | `primitive(..., result=subtract)` — вычитание тела вместо `extrude(mode=cut)` по эскизу |
| Скруглённые углы призмы | `primitive` + `fillet_edge` по рёбрам (скругление после, а не дуги в эскизе) |
| Текст, кривые, произвольный контур, переменное сечение | ТОЛЬКО эскиз: `sketch_create(entities=[…])` + `extrude`/`revolve`/`loft`/`sweep` |
| Тонкая стенка, ободок по контуру | эскиз + `extrude(thinThickness, thinSide)` |

Их **сочетают в одной детали**: корпусные объёмы — примитивами, сложные контуры — эскизами.
Точка привязки у `block` — **угол** (не центр), у тел вращения — центр основания; размеры идут по
осям X/Y/Z текущей системы координат.

- **Тонкую стенку по сложному контуру строй ДО того, как появится тело, которое она пересечёт.**
  `extrude(thinThickness=…)` по многоконтурному эскизу (надпись — это десяток замкнутых контуров с
  внутренними «дырками») ОТКАЗЫВАЕТ, если стенка пересекает уже построенное тело. Разложено
  экспериментом: в пустой детали — строится; тело есть, но стенка его не задевает — строится;
  стенка пересекает тело — отказ. Ни число тел, ни то, чем тело создано (эскизом или примитивом),
  роли не играют, а простой прямоугольный контур проходит и с пересечением. Поэтому на шильдике
  «плашка → буквы → кайма» падает, а «буквы → кайма → плашка `primitive(union)` → карман
  `primitive(subtract)`» проходит: примитивам пересечение безразлично.
- **Скругления делай, пока рёбер мало** — сразу после примитивов их видно в `list_edges` наперечёт.
  Если момент упущен и рёбер сотни, бери рёбра ПО ТОЧКЕ: `fillet_edge(radius, x, y, z)` на углу
  известных координат — по одному ребру за вызов, зато без перебора индексов.
- **Скругление не построится там, где ребро «съедено» соседним элементом.** У шильдика угол плашки,
  накрытый каймой букв, не скругляется ни R0.5, ни R0.3 — там уже нет ребра. Это нормальный ответ
  геометрии, а не ошибка вызова: проверь снимком, что угол вообще виден снаружи.
- **Вычитание проверяется объёмом.** `primitive(result=subtract)` мимо тела КОМПАС считает удачей;
  инструмент это ловит и сообщает, но привычку сверять `describe_model(sections="mass")` не отменяет.
- **`result=new` даёт ОТДЕЛЬНОЕ тело.** Оно объединится с остальными, только если последующая
  операция их пересечёт; иначе в детали останется несколько тел — проверяй `list_bodies` и при
  необходимости зови `boolean_union`.

## Базовый цикл (эскиз → операция → осмотр)

Опорный сценарий построения, проверен end-to-end:

1. `kompas_connect` (+ `kompas_set_visible true`).
2. `document_create part`.
3. `sketch_create(plane="XOY", entities=[…])` — **весь контур одним вызовом**; эскиз закрывается сам (`autoClose` по умолчанию).
4. `extrude(mode="boss", depth=…)` / `revolve(mode="boss", …)` → читаешь итог проверки прямо в ответе (правило 2).
5. **Осмотр — структурно:** `describe_model` (паспорт: габарит, МЦХ, топология, дерево); нужен кусок — `describe_model(sections="box,mass")`. Снимок — только если нужен визуальный контроль.
6. Итерация «на грани»: `list_faces` (при нужде `list_faces(index=N)` за подробностями) → `sketch_create(faceIndex=N, entities=[…])` → операция.
7. **Назови деталь** — `set_part_info(name=…)` (и `marking`, если известно обозначение). Без этого в дереве
   стоит безликая «Деталь», и она же уедет в штамп чертежа и в спецификацию; `describe_model` специально
   отмечает деталь без наименования. Имя файла при сохранении этого НЕ заменяет — это разные свойства.

**Называй каждую операцию.** У `sketch_create`, `extrude`, `primitive`, `fillet_edge`, `hole`,
`pattern`, `shell` и остальных есть `name` — имя узла в дереве построения. Без него дерево выглядит
как «Эскиз:1, Эскиз:2, Элемент выдавливания:3», и по нему нельзя понять, что чем построено, —
ни человеку, ни тебе самому через сотню вызовов. Имя пиши по смыслу: «Контур плашки», «Рельеф букв
OldMan», «Карман под площадку», «Скругления углов плашки».

**Не разбивай построение на лишние вызовы.** Прямоугольник с четырьмя отверстиями — это ОДИН
`sketch_create` со списком из пяти примитивов, а не шесть вызовов. Скругление восьми рёбер — один
`fillet_edge(radius, edgeIndices=[…])` или `fillet_edge(radius, points=[…])`, а не восемь.
Каждый лишний вызов — лишний шанс сбиться.

## Надписи, логотипы и рельеф

Надпись в эскизе — примитив `type=text` (`points:[{x,y}]` — левый край базовой линии, `text`,
`height` в мм, `fontName` — любой установленный в системе шрифт, плюс `bold`/`italic`,
`widthFactor` — сужение, `angle` — наклон строки). Она **сразу переводится в кривые**, поэтому
выдавливается как обычный контур: гравировка — `extrude(mode="cut")`, выпуклые буквы — `mode="boss"`.

- **Ответ даёт ГАБАРИТ ГЛИФОВ — по нему и позиционируй.** «надпись «OldMan» — глифы X 1.00…87.93,
  Y 12.14…28.94 (86.93 × 16.80 мм), ширина ячейки 94.57 мм». Первые числа — прямоугольник, реально
  занятый буквами (совпадает с тем, что получится после выдавливания); *ширина ячейки* — шаг строки
  с боковыми просветами, она больше на 1–2 % у наборных шрифтов (Zilla Slab, Bevan) и на 7–9 % у
  скриптовых (Lobster, Pacifico). Вписываешь надпись в поле — считай по габариту, не по ячейке.
- **Мерить дешевле в черновом документе.** Пока деталь пуста, габарит надписи — это габарит всей
  модели, и подбор кегля идёт без пересборки: `document_create part` → эскиз с текстом → прочитать
  метрики → закрыть без сохранения. В собранном теле (сотни граней) выделить рельеф уже нечем.
- **`height` — это высота ПРОПИСНОЙ (cap height), а не габарит строки.** Замер на Zilla Slab при
  `height=10`: «HH» → 9.97 мм, «hd» → 10.71 (восходящие выше прописной), «Hy» → 13.24 мм
  (нижний выносной уходит на −3.27). Считаешь компоновку — закладывай выносные отдельно.
- **Ширина линейна по `height`** (проверено до 0.01 мм) — им и подгоняй точный размер.
  **По `widthFactor` линейности НЕТ:** замер даёт +0.55 % коэффициента → +0.07 % ширины
  (КОМПАС квантует кегль). Поэтому `widthFactor` — грубая пропорция начертания, а не масштаб:
  выставил его один раз, дальше набираешь ширину высотой.
- **Толщина каймы на острых терминалах больше, чем `thinThickness`.** Стенка `outward` обходит
  контур с миттером: на остром окончании глифа (скриптовые «n», «l») габарит растёт на
  `t / sin(θ/2)`, а не на `t` — замерено 2.11 мм при `t`=1.0 у Lobster. Считать «глиф + 2t» нельзя,
  габарит после операции надо перечитывать.
- **Разрядки (трекинга) у примитива нет — её набирают пробелами.** Ширину пробела для конкретного
  шрифта и кегля вычисляют двумя пробами: «EDITION» → 38.38 мм, «E D I T I O N» → 47.11 мм,
  значит пробел 1.455 мм (Bevan, cap 5.5).
- **Подложка под надпись — тонкой стенкой, а не вторым эскизом.** `extrude(..., thinThickness=1.2,
  thinSide="outward")` по контуру букв даёт ободок-эквидистанту вокруг них; выдавь ТОТ ЖЕ эскиз
  дважды — сплошным на высоту подложки и стенкой наружу — и получишь силуэт надписи с равномерной
  каймой. `inward` съедает контур внутрь (рамка по периметру плашки), `both` делает контур средней
  линией стенки. **Проверяй стенку по объёму:** если толщина не применилась, КОМПАС молча строит
  сплошное сечение — габарит при этом тот же, и по нему подмену не увидеть.
- **Рельеф = разница глубин.** Основание 2 мм + буквы 3 мм от той же плоскости: буквы выступают
  на 1 мм. Не строй буквы «на грани основания» — из одного эскиза на базовой плоскости получается
  и то и другое, и рельеф не зависит от порядка операций.
- **Проверяй объёмом, а не габаритом.** Буквы дают сотни NURBS-рёбер, и ни снимок, ни габарит не
  покажут, что операция построила не то: сравнивай ПРИРОСТ объёма (`describe_model(sections="mass")`)
  с прикидкой «площадь контура × высота». Именно так ловится молча не применившаяся тонкая стенка.
- **Скруглять рельефный текст можно, но по одному-двум рёбрам, а не пакетом.** Проверено на
  Zilla Slab «AB» (203 ребра): одиночное ребро скругляется R0.1 и R0.2, а `fillet_edge` сразу по
  всем рёбрам отказывает при обоих радиусах (соседние скругления конфликтуют). Адресно выбрать
  «только верхние» рёбра пока нечем — `list_edges` не отдаёт ни координат, ни принадлежности грани.
- **Углы вокруг надписи — одним `fillet_edge(points=[…])`.** На теле с сотнями рёбер список из
  `list_edges` неподъёмен, но точки углов известны из построения: передай их списком, и все рёбра
  уйдут в ОДНУ операцию дерева. Если ребра в части точек нет (типичный случай — угол «съеден»
  каймой букв), ошибка перечислит ВСЕ такие точки сразу: убери их и повтори одним вызовом.
- **Шрифт обязан быть установлен в системе**, где работает КОМПАС: неизвестное имя молча
  подменяется другим шрифтом, и надпись «поедет» по ширине без единого сообщения об ошибке.

## Работа с импортом / сборками

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

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

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

- **Зрение — структурное (правило 1).** Осматривай через `describe_model` / `list_faces(index=…)` /
  `list_edges(index=…)` / `measure`, а не снимком. `model_snapshot` — только для визуально-пространственных
  вопросов; не гоняй картинку зря.
- **Итог проверки — в ответе операции (правило 2).** `Create()/Update()==true` ≠ успех; «⚠ N операц. в ошибке»
  (напр. `et3dError54`) — деталь невалидна, в STEP/печать не брать.
- **Грань/ребро по индексу надёжнее, чем по точке.** Сначала `list_faces`/`list_edges`, затем передавай
  `faceIndex`/`edgeIndices` в `sketch_create`, `hole`, `move_face`, `fillet_edge`, `chamfer_edge`.
  Координаты точки (`SelectByPoint`) — только когда индекс не подходит. Если выбирал точкой, ответ
  подскажет, какой это оказался объект.
- **Направление операции.** `extrude(..., forward)` / `move_face(distance±)` может уйти «не туда» —
  сверяй результат числами (`describe_model(sections="box,mass")`), снимок лишь при необходимости.
- **МЦХ.** Объём/масса меняющейся геометрии — `describe_model(sections="mass")`; перед чтением после правок — `rebuild`.
- **id эскизов/операций** недействительны после смены активного документа (create/open/close).
- **Имя файла занимает открытый документ.** Если та же деталь уже открыта в КОМПАС (например, прошлая
  версия из этой же папки), `document_save(path)` по этому пути не пройдёт — КОМПАС не перезаписывает
  занятый файл. Освободить имя: `document_close(all=true)`. Проверяй, что файл на диске реально
  обновился (время изменения), особенно когда перестраиваешь деталь поверх прежней.
  Несуществующий каталог в пути — не помеха: `document_save` и `export_step` создают его сами.
- **Единицы — мм** (геометрия) и кг (масса). Локальные координаты эскиза ≠ мировые координаты модели.

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

- **Прямое редактирование B-rep — реализовано полностью:** `move_face`, `split_solid_by_plane`,
  `move_body`, `boolean_union`. Цепочка cut→spread→union проверена end-to-end (проставка
  39.45→41.45 мм, построение чистое).
- **Параметрика ограничена.** `set_variable` хранит и пересчитывает значения, но двигает геометрию
  только в параметрической модели (размеры эскиза привязаны к именам переменных). Если эскиз
  построен литеральными координатами, `set_variable` изменит значение, а не форму.
- **2D и сборки покрыты частично.** Чертёж: стандартные виды, штамп, формат листа, размеры,
  шероховатость, текст, выноски, техтребования. Сопряжения: совпадение и расстояние.

## Связанное

- Проверка окружения (КОМПАС установлен, сервер запускается, подключение живое): команда **`/kompas:doctor`**.
- Установка, требования и настройка сервера: README плагина.
- Правила проектирования под FDM/FFF-печать: навык **`kompas-fdm-design`**.