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

name, description

name

description

kompas-3d

Методика работы с КОМПАС-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, feature_delete (убрать операцию/эскиз из дерева, зависимые уходят каскадом), 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_edges есть отбор type и окно minX…maxZ — им адресуют то, что не выбрать по одному: list_edges(minZ=-0.01, maxZ=0.01) даёт весь нижний контур под фаску), 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). Вписываешь надпись в поле — считай по габариту, не по ячейке.
• Выравнивание — параметрами, а не пересчётом. align: left|center|right и vAlign: baseline|bottom|middle|top трактуют точку вставки как якорь: align="center" кладёт середину глифов ровно в заданный X. Сервер делает это по фактическому габариту (строит, замеряет, сдвигает), поэтому цикл «вставил → прочитал → переставил» агенту больше не нужен. baseline — умолчание и поведение самого КОМПАС: выносные элементы уходят ниже точки.
• Мерить дешевле в черновом документе. Пока деталь пуста, габарит надписи — это габарит всей модели, и подбор кегля идёт без пересборки: document_create part → эскиз с текстом → прочитать метрики → закрыть без сохранения. В собранном теле (сотни граней) выделить рельеф уже нечем. Неудачную пробу теперь не обязательно уносить вместе с документом — feature_delete(id) убирает эскиз или операцию из дерева (зависимые уходят каскадом).
• height — это высота ПРОПИСНОЙ (cap height), а не габарит строки. Замер на Zilla Slab при height=10: «HH» → 9.97 мм, «hd» → 10.71 (восходящие выше прописной), «Hy» → 13.24 мм (нижний выносной уходит на −3.27). Считаешь компоновку — закладывай выносные отдельно.
• widthFactor меняет пропорцию крупно, height — точно. Замер (Lobster «OldMan», h=17): wf 1.00 → 71.84 мм, wf 1.25 → 92.83 (+29 %) — то есть это настоящий масштаб ширины, и без него скриптовый шрифт в вытянутое поле не вписать. Но КОМПАС квантует его ступенями: wf 1.25, 1.26, 1.27, 1.28 дают ячейку 100.64 и ширину 92.83…93.14 (+0.3 %), а на 1.29 ячейка прыгает на 103.34 и ширина сразу 95.49 (+2.5 %). Отсюда правило: пропорцию задаёшь widthFactor, точную ширину добираешь height (он линеен до 0.01 мм) — подгонка через wf топчется на ступени.
• Кайма на острых терминалах шире thinThickness — и по каждой стороне по-своему. Стенка outward обходит контур с миттером: на остром окончании глифа габарит растёт на сторону на t / sin(θ/2), а не на t (Lobster: слева +0.90 при t=0.9, справа +1.70 — терминал «n»). Величина принадлежит не шрифту, а КОНКРЕТНОМУ начертанию: растянув тот же Lobster (widthFactor 1.29), терминал заострился и правый прирост стал +1.99. Поэтому переносить число между вариантами нельзя — перезамеряй габарит после смены widthFactor.
• Кегль под заданный габарит считается за ОДНУ пробу, а не подбирается. При фиксированном widthFactor прирост каймы Δ (сумма по обеим сторонам) от кегля не зависит — фигура подобна. Значит: построил пробу с любым height₀, замерил ширину глифов W₀ и суммарный прирост Δ, дальше height = height₀ · (W_цель − Δ) / W₀ — и целевой габарит получается с первого раза. Замер: проба h=17.06 дала Δ=4.62 (слева 1.50, справа 3.12 — миттер ×2.08) → h=17.00 → 89.98 мм.
• Разрядки (трекинга) у примитива нет — её набирают пробелами. Ширину пробела для конкретного шрифта и кегля вычисляют двумя пробами: «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 делает контур средней линией стенки. Проверяй стенку по объёму: если толщина не применилась, КОМПАС молча строит сплошное сечение — габарит при этом тот же, и по нему подмену не увидеть.
• Кайма вокруг ПРЯМОУГОЛЬНОЙ плашки — вторым примитивом, а не тонкой стенкой. Стенка обходит контуры эскиза, а плашка по playbook'у строится primitive, и каймы у неё не появится. Клади под неё второй блок на 2·t больше и на высоту подложки (85 × 13.5 × 2 под плашкой 82 × 10.5 × 3) — получается тот же кант. Сводить прямоугольник в один эскиз с буквами не надо: контуры пересекутся, и эскиз станет невалидным.
• Рельеф = разница глубин. Основание 2 мм + буквы 3 мм от той же плоскости: буквы выступают на 1 мм. Не строй буквы «на грани основания» — из одного эскиза на базовой плоскости получается и то и другое, и рельеф не зависит от порядка операций.
• Проверяй объёмом, а не габаритом. Буквы дают сотни NURBS-рёбер, и ни снимок, ни габарит не покажут, что операция построила не то: сравнивай ПРИРОСТ объёма (describe_model(sections="mass")) с прикидкой «площадь контура × высота». Именно так ловится молча не применившаяся тонкая стенка.
• Скруглять ВЕРХНИЕ рёбра рельефа пакетом нельзя, а снимать фаску по нижнему контуру — можно. Проверено на Zilla Slab «AB» (203 ребра): одиночное верхнее ребро скругляется R0.1 и R0.2, а fillet_edge сразу по всем отказывает при обоих радиусах — соседние скругления конфликтуют. Зато chamfer_edge(0.3, edgeIndices=[…]) по 59 рёбрам нижнего силуэта надписи (24 прямых, 32 NURBS, 3 дуги, включая огрызки 0.03 мм) строится с первой попытки: фаска против «слоновьей ноги» по всему контуру — это ОДНА операция. Рёбра нижнего контура берутся окном: list_edges(minZ=-0.01, maxZ=0.01).
• primitive(subtract) режет ВСЁ, что попало в его габарит — включая уже построенные буквы. Сверять надо глифы, а не кайму, и только те, что дотягиваются до кармана ПО ВЫСОТЕ: карман обычно вычитается от z основания вверх (например от 2 до 3), а кайма ростом всего 2 мм в этот слой не попадает — она может сколько угодно перекрывать плашку в плане, и именно это перекрытие держит деталь одним телом. Опасны буквы: они идут на всю высоту 3 мм, поэтому их нижняя кромка по Y должна быть выше верхней кромки кармана. Проверка постфактум — точное равенство убыли объёма расчётному (79 × 7.5 × 1.0 = 592.5 против фактических 592.5 мм³): любое касание соседней геометрии сразу ломает равенство, а габарит и снимок его не покажут.
• Углы вокруг надписи — одним 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.