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

name, description

name

description

kompas-3d

Методика работы с КОМПАС-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-приёмы импорта/экспорта/обхода).