gitea-actions
564 lines
63 KiB
Markdown
564 lines
63 KiB
Markdown
---
|
||
name: kompas-3d
|
||
description: >
|
||
Методика работы с КОМПАС-3D через MCP-сервер плагина: построение и
|
||
модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии
|
||
снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС
|
||
через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать
|
||
сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
|
||
проверенные на практике. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
|
||
«что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели».
|
||
---
|
||
|
||
# kompas-3d — методика управления КОМПАС-3D через MCP
|
||
|
||
MCP-сервер даёт **общие** операции КОМПАС (эскизы, формообразующие, осмотр, обмен), этот навык —
|
||
**методику**: в каком порядке их применять, как выбирать геометрию, чем проверять результат и какие
|
||
подводные камни обходить. Коротко: **MCP = чем делать, навык = как делать.** Подробности вызова —
|
||
варианты операций, обязательные поля, типы примитивов эскиза и их параметры — живут в описаниях
|
||
самих инструментов: контракт сервера подробен, читай его, а не восстанавливай по памяти.
|
||
|
||
## Когда применять
|
||
|
||
Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции,
|
||
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки.
|
||
|
||
## Два правила прежде всего
|
||
|
||
**1. «Зрение» — структурное, не по картинке.** «Увидеть» деталь = **`describe_model`** — паспорт
|
||
одним запросом и ЕДИНСТВЕННЫЙ инструмент осмотра: разделы `box | mass | bodies | topology | tree |
|
||
variables | errors | components` (`sections` сужает и ответ, и объём чтения модели). Углубляться —
|
||
`list_faces(index=N)` / `list_edges` (отбор `type` + координатное окно — им адресуют то, что не
|
||
выбрать по одному: весь нижний контур под фаску) / `measure`. **`model_snapshot`
|
||
бери только** для визуально-пространственных вопросов, на которые паспорт не отвечает (общая
|
||
форма, ориентация, правдоподобность, «куда смотрит грань»): снимок дорог по контексту и менее
|
||
точен, чем числа.
|
||
|
||
**2. Ответ мутирующей операции — это ТРИ проверки, читай все.** Любая операция может «пройти»
|
||
(`Create()==true`), оставив деталь в ошибке, поэтому каждая мутирующая операция сама дописывает
|
||
к ответу итог проверки построения и сводку состояния «Тел: N, объём V мм³»:
|
||
|
||
- **«⚠ N операц. в ошибке»** (напр. `et3dError54`) — деталь невалидна: не продолжай и не
|
||
экспортируй, исправь или переделай другим методом. «Построение чистое» = порядок.
|
||
- **«Тел: 2»** там, где ждёшь одно тело, — деталь распалась: касание объединением не считается
|
||
(см. «Надписи»). Смотри на число ТЕЛ, а не граней: объединение сливает компланарные грани,
|
||
и счётчик граней законно остаётся прежним.
|
||
- **Объём сверяй с прикидкой** «площадь контура × высота». Так ловятся молча не применившаяся
|
||
тонкая стенка (прирост как у сплошного сечения), вычитание мимо цели и операция «не туда» —
|
||
габарит и снимок этого не покажут.
|
||
|
||
Отдельный `describe_model(sections=errors,bodies,mass)` после каждого шага не нужен. Он
|
||
возвращается, когда авто-проверку выключили (`set_auto_validate(false)` на тяжёлой модели, где
|
||
проверка каждого шага тормозит): тогда `describe_model(sections=errors,bodies,mass)` вручную перед выдачей: одного
|
||
`errors` мало — распад детали на два тела показывает только раздел `bodies`.
|
||
|
||
## Справочник сервера: `help`
|
||
|
||
Подробности инструментов — маршруты, порядок вызовов, ловушки — лежат в самом сервере и достаются
|
||
по требованию, а не занимают контекст заранее:
|
||
|
||
- `help()` — оглавление тем (дёшево, одна строка на тему);
|
||
- `help(topic="…")` — статья целиком;
|
||
- `help(query="…")` — поиск словами с цитатами;
|
||
- `help(tool="extrude")` — что известно про конкретный инструмент.
|
||
|
||
**Зови его, когда инструмент повёл себя не так, как ты ожидал, и когда тема названа в тексте
|
||
ошибки.** Ссылки вида `help(topic="…")` по этому файлу — не украшение: там лежит то, что здесь
|
||
намеренно не повторяется. Справочник описывает ЭТОТ сервер; справка по COM API КОМПАС — отдельная
|
||
история и в работе через MCP не нужна.
|
||
|
||
## Инструменты: индекс групп
|
||
|
||
Актуальный перечень с описаниями параметров отдаёт сам MCP-сервер — здесь только карта:
|
||
|
||
- *Система/документы:* `kompas_connect` (shared|private|attach), `kompas_set_visible`,
|
||
`kompas_status`, `set_auto_validate`, `set_operation_log`; `document_create|open|save|close`,
|
||
`document_active` (тип, путь, есть ли несохранённые изменения, «только чтение», материал детали),
|
||
`document_list` (все открытые документы — им проверяют, что имя файла занято другим документом
|
||
и что несохранённого не осталось), `set_part_info`, `set_part_material`.
|
||
- *Эскиз:* `sketch_create` (основание: `plane`+`offset` | `faceIndex` | точка; геометрия — списком
|
||
`entities` **или** файлом `entitiesFile`), `sketch_add`, `sketch_close`; `measure_text` — замер
|
||
надписи без построения; `fragment_create` — тот же список примитивов, но в самостоятельный
|
||
файл-фрагмент (*.frw); `fragment_place` — положить готовый фрагмент в чертёж.
|
||
- *Формообразующие:* `primitive`, `extrude`, `revolve`, `fillet_edge`, `chamfer_edge`, `shell`,
|
||
`rib`, `sweep`, `loft`, `draft`, `hole`, `pattern`, `mirror`, `feature_delete`, `rebuild`.
|
||
- *Прямое редактирование (в т.ч. импортированная B-rep):* `move_face`, `split_solid_by_plane`,
|
||
`move_body`, `boolean_union`.
|
||
- *Переменные:* `set_variable`, `list_parameters`, `link_parameter`, `delete_variable`
|
||
(сами переменные показывает `describe_model(sections=variables)`).
|
||
- *Обмен:* `import_model` (3D: step, iges, sat, xt, stl, c3d, jt, obj + родные форматы чужих САПР),
|
||
`import_drawing` (плоский .dxf/.dwg), `export_model` (`format=auto` по расширению: `.step` —
|
||
точная геометрия в другую САПР, `.stl` — сетка в слайсер).
|
||
- *Сборка:* `assembly_add_component` (положение + поворот `rx/ry/rz`), `assembly_add_mate`
|
||
(семь типов, `orientation`), `assembly_fix_component`, `assembly_delete`,
|
||
`assembly_check_interference` (не налезли ли детали друг на друга — больше это не видно нигде),
|
||
`assembly_transform_point` (`to=world|local` — точка между ЛСК компонента и СК сборки).
|
||
- *2D-чертёж:* `drawing_create_standard_views` (`views[]`, `mainOrientation`, `hiddenLines`),
|
||
`drawing_add_view` / `drawing_move_view` / `drawing_delete_view` / `drawing_get_view_info`
|
||
(компоновка листа и паспорт вида), `drawing_add_section_view` (РАЗРЕЗ или СЕЧЕНИЕ: линия разреза
|
||
на базовом виде и производный вид по ней — одним вызовом), `drawing_add_sheet`,
|
||
`drawing_set_sheet_format`,
|
||
`drawing_fill_title_block`,
|
||
`drawing_add_linear|diametral|radial|angular_dimension` (у всех — `tolerance`/`prefix`/`suffix`/
|
||
`textOverride`; у Ø и R — ещё `objectKind`/`objectIndex`, прямой адрес окружности или дуги),
|
||
`drawing_add_axis`, `drawing_add_rough|text|leader`,
|
||
`drawing_set_unspecified_rough`, `drawing_set_technical_requirements`, `drawing_delete_object`,
|
||
`drawing_move_object` (сдвинуть поставленное), `drawing_project_point` (точка модели → координаты
|
||
вида), `drawing_export_image` (посмотреть
|
||
глазами). Обратное чтение — `drawing_get_title_block` и `drawing_get_technical_requirements`:
|
||
технические требования ПЕРЕЗАПИСЫВАЮТСЯ целиком, поэтому правку одного пункта начинают с чтения
|
||
текущего текста. Методика — §«Чертёж».
|
||
- *Осмотр:* `describe_model` (разделы `box|mass|bodies|topology|tree|variables|errors|components|mates` —
|
||
габарит, МЦХ, тела, топология, дерево построения, переменные, операции в ошибке, состав сборки,
|
||
сопряжения), `measure`, `model_snapshot`; адресация объектов — `list_faces` / `list_edges`.
|
||
Для 2D-документов — свой: `list_drawing_objects` (что лежит в чертеже/фрагменте).
|
||
|
||
Три сквозных свойства контракта: **размерный параметр принимает число ИЛИ выражение** (имя
|
||
переменной/формулу — параметр сразу становится ведомым); **объект выбирается индексом** (надёжно)
|
||
или точкой (запасной путь — если выбирал точкой, ответ подскажет, что выбралось); **списковые
|
||
параметры** (`entities[]`, `edgeIndices[]`, `points[]`, `faceIndices[]`, `variables[]`, `links[]`) —
|
||
весь пакет одним вызовом: прямоугольник с четырьмя отверстиями — ОДИН `sketch_create`, скругление
|
||
восьми рёбер — ОДИН `fillet_edge`, крепёжная картина из шести отверстий — ОДИН `hole(points=[…])`,
|
||
наращивание двух торцов — ОДИН `move_face(faceIndices=[…])`; каждый лишний вызов — лишний шанс
|
||
сбиться. Пакет НЕ транзакционен: отказ называет позицию элемента в списке, а сделанное до него
|
||
остаётся — повторяй вызов с оставшимися, а не с начала. Если инструмента под задачу нет — собирай
|
||
результат из имеющихся общих операций.
|
||
|
||
## Два пути формообразования — выбирай по форме, а не по привычке
|
||
|
||
«Эскиз → выдавливание» — не единственный способ. `primitive` строит тело сразу по размерам, и это
|
||
короче и надёжнее там, где форма призматическая:
|
||
|
||
| Форма | Чем строить |
|
||
|---|---|
|
||
| Плита, брусок, бобышка, штифт, цилиндрическая стойка | `primitive(kind=block\|cylinder)` — один вызов вместо «эскиз + выдавливание» |
|
||
| Прямоугольный карман, паз, срез угла | `primitive(..., result=subtract)` — вычитание тела вместо `extrude(mode=cut)` по эскизу |
|
||
| Скруглённые углы призмы | `primitive` + `fillet_edge` по рёбрам (скругление после, а не дуги в эскизе) |
|
||
| Текст, кривые, произвольный контур, переменное сечение | ТОЛЬКО эскиз: `sketch_create(entities=[…])` + `extrude`/`revolve`/`loft`/`sweep` |
|
||
| Тонкая стенка, ободок по контуру | эскиз + `extrude(thinThickness, thinSide)` |
|
||
|
||
Их **сочетают в одной детали**: корпусные объёмы — примитивами, сложные контуры — эскизами.
|
||
|
||
- **Ось цилиндра и конуса задаётся параметром, а не системой координат детали:**
|
||
`primitive(kind="cylinder", axis="X"|"Y"|"Z")`. Точка `x,y,z` остаётся центром основания в
|
||
мировых координатах, высота растёт вдоль выбранной оси. Не перепроектируй деталь ради того,
|
||
чтобы её ось совпала с Z (у `block` и `sphere` параметра нет: у блока ось задают размеры
|
||
`length/width/height`, у сферы оси нет).
|
||
|
||
- **Тонкую стенку по сложному контуру строй ДО того, как появится тело, которое она пересечёт.**
|
||
`extrude(thinThickness=…)` по многоконтурному эскизу (надпись — десяток замкнутых контуров с
|
||
«дырками») отказывает, если стенка пересекает уже построенное тело; простой прямоугольный контур
|
||
проходит и с пересечением. Ошибка сервера называет причину, но порядок планируй заранее: на
|
||
шильдике «плашка → буквы → кайма» падает, а «буквы → кайма → плашка `primitive(union)` → карман
|
||
`primitive(subtract)`» проходит — примитивам пересечение безразлично.
|
||
- **Скругления делай, пока рёбер мало** — сразу после примитивов их видно в `list_edges` наперечёт.
|
||
Если рёбер уже сотни, бери их ПО ТОЧКАМ: `fillet_edge(radius, points=[…])` по углам известных
|
||
координат — одна операция на все; точки без ребра ошибка перечислит разом.
|
||
- **Скругление не построится там, где ребро «съедено» соседним элементом** (угол плашки под каймой
|
||
букв). Это нормальный ответ геометрии, а не ошибка вызова: проверь снимком, виден ли угол снаружи.
|
||
- **`result=new` даёт ОТДЕЛЬНОЕ тело**, `subtract` мимо цели сервер ловит сам — и то и другое
|
||
видно по сводке «Тел/объём» в ответе; при распаде зови `boolean_union`.
|
||
|
||
## Базовый цикл (эскиз → операция → осмотр)
|
||
|
||
Опорный сценарий построения, проверен end-to-end:
|
||
|
||
1. `kompas_connect` (+ `kompas_set_visible true`). **Работаешь не один — бери свой экземпляр:**
|
||
`kompas_connect(instance="private")` (см. «Когда КОМПАС общий»).
|
||
2. `document_create(type="part", name="…")` — наименование даём сразу, здесь оно ничего не стоит.
|
||
3. **Запиши замысел переменными** до первого эскиза (см. «Параметризация») и связывай каждый
|
||
размер, взятый из паспорта, при построении — иначе переменная останется числом в списке.
|
||
4. `sketch_create(plane="XOY", entities=[…])` — весь контур одним вызовом.
|
||
5. `extrude` / `revolve` → прочитай итог проверки и сводку прямо в ответе (правило 2).
|
||
6. Осмотр — структурно: `describe_model` (нужен кусок — `sections="box,mass"`).
|
||
7. Итерация «на грани»: `list_faces` → `sketch_create(faceIndex=N, entities=[…])` → операция.
|
||
8. **Задай материал, если смотришь на массу** — `set_part_material`: у нового документа стоит
|
||
сталь 7.86, и МЦХ печатной детали завышена вшестеро; плотности ходовых материалов перечислены
|
||
в описании инструмента.
|
||
9. **Проверь, что деталь названа** (шаг 2 или `set_part_info`) — безликая «Деталь» уедет в штамп
|
||
чертежа и спецификацию; имя файла при сохранении этого не заменяет.
|
||
|
||
**Называй каждую операцию** — `name` есть у всех: «Контур плашки», «Рельеф букв OldMan», «Карман
|
||
под площадку». Дерево из «Эскиз:1, Элемент выдавливания:3» нечитаемо ни человеку, ни тебе самому
|
||
через сотню вызовов.
|
||
|
||
## Параметризация: сначала переменные, потом геометрия
|
||
|
||
**В новом документе первым делом опиши будущую модель переменными — до первого эскиза.** Пока
|
||
деталь пуста, компоновка стоит одного вызова на размер; после десятка операций та же мысль стоит
|
||
пересборки. Набор переменных — это план построения числами и паспорт, по которому человек поймёт
|
||
модель, не разбирая дерево.
|
||
|
||
- **Заводи переменной то, что было РЕШЕНИЕМ**: габариты из ТЗ, толщины, зазоры, отступы, кегли,
|
||
радиусы. Выводимое задавай формулой (`plate_L = badge_L - 2*edge_gap`) — правка ведущего размера
|
||
пересчитает зависимые сама. Позиции, подобранные замером, оставляй числами: связь — обещание,
|
||
что правка переменной даст осмысленный результат, а на позиционных числах она чаще ломает деталь.
|
||
- **Размер передавай выражением прямо в операцию** (`extrude(depth="badge_T")`) — параметр сразу
|
||
становится ведомым, внутреннее имя параметра («Расстояние 1») знать не нужно. Переменная должна
|
||
существовать ДО операции — потому паспорт и заводят первым. Задним числом и для параметров,
|
||
которых нет среди аргументов инструмента (углы уклона, второе направление), — `link_parameter`.
|
||
- **Промахи сервер ловит сам:** ссылка на несуществующее имя — отказ с перечнем виновных (и в
|
||
выражениях операций, и в `set_variable`; регистр значим), функции в формулах — предупреждение
|
||
(тригонометрия в радианах, разделитель аргументов «;», непонятая запись = молчаливый 0).
|
||
Твоя часть — **сверить вычисленные значения из ответа со своей прикидкой**.
|
||
- **`note` обязателен** и пишется по-русски, со смыслом и единицей; `(ТЗ)` метит числа,
|
||
зафиксированные пользователем. **Что замерил — верни в переменную** (фактический кегль, прирост
|
||
каймы), иначе паспорт разойдётся с моделью и станет дезинформацией. Переосмысливать можно всё,
|
||
кроме помеченного `(ТЗ)`.
|
||
- **После связывания правка паспорта перестраивает деталь** (проверено: `set_variable(badge_T=4)` →
|
||
габарит по Z 3.00 → 4.00, объём 5154.5 → 5861.5 мм³). Это и есть параметрическая модель,
|
||
а не комментарий к ней.
|
||
- **Сверка и уборка в конце:** `describe_model(sections=variables)` помечает «⚠ ничего не ведёт» — это либо забытая
|
||
связь, либо мусор; разбери оба. `delete_variable(unused=true)` — только ПОСЛЕ `link_parameter`
|
||
на всё, что должно вести геометрию: вычистка не отличает мусор от несвязанного размера из ТЗ.
|
||
|
||
## Надписи, логотипы и рельеф
|
||
|
||
Надпись — примитив `type=text` в эскизе; все поля (шрифт, кегль, `widthFactor`, выравнивание
|
||
`align`/`vAlign`) описаны в схеме `entities`. Она сразу переводится в кривые, поэтому выдавливается
|
||
как обычный контур: гравировка — `extrude(mode="cut")`, выпуклые буквы — `mode="boss"`.
|
||
|
||
- **Ответ даёт габарит ГЛИФОВ и ширину ячейки — позиционируй по глифам.** Ячейка шире на 1–2 % у
|
||
наборных шрифтов (Zilla Slab, Bevan) и на 7–9 % у скриптовых (Lobster, Pacifico).
|
||
- **Кегль калибруй `measure_text`** — он ничего не строит. Пробу, которую всё же пришлось
|
||
построить, убирает `feature_delete`; отдельный черновой документ для этого не нужен.
|
||
- **`height` — высота ПРОПИСНОЙ, а не габарит строки** (Zilla Slab, height=10: «HH» → 9.97 мм,
|
||
«Hy» → 13.24 мм, выносной уходит на −3.27) — закладывай выносные отдельно. Прочие тонкости полей
|
||
(`widthFactor`, `align`, `vAlign`) — `help(topic="sketch-text")`.
|
||
- **Подложка под надпись — тем же эскизом тонкой стенкой:** один хендл эскиза можно передать в
|
||
несколько операций — сплошное выдавливание на высоту подложки + `extrude(thinThickness,
|
||
thinSide="outward")` дают силуэт с равномерной каймой. Стенку проверяй по объёму из сводки:
|
||
не применившаяся толщина молча даёт сплошное сечение при том же габарите.
|
||
- **Надпись и плашка обязаны ПЕРЕКРЫВАТЬСЯ** — по размерам чертежа блоки обычно только касаются,
|
||
а касание объединением не считается. Приём: кайму/полосу плашки сделать выше самой плашки на
|
||
1–1.5 мм с той стороны, где стоит надпись. Распад видно по «Тел: 2» в ответе операции — не тяни
|
||
проверку до конца построения.
|
||
- **Рельеф = разница глубин от одной плоскости** (основание 2 мм + буквы 3 мм = выступ 1 мм);
|
||
не строй буквы «на грани основания» — из одного эскиза на базовой плоскости получается и то и
|
||
другое, и рельеф не зависит от порядка операций.
|
||
- **Шрифт должен быть установлен в системе** — неизвестное имя КОМПАС молча подменяет; сервер
|
||
предупреждает об этом в ответе `sketch_create`/`measure_text` — не игнорируй.
|
||
|
||
**Логотип, которого нет в шрифте, приходит готовым вектором (SVG).** Переводи его в примитивы
|
||
эскиза сам — `line` и `arc3points`, а не ломаной: контур из сотен звеньев даёт деталь в сотни
|
||
граней, и фаска по такому низу не строится. Кубические Безье режь пополам, пока дуга по трём
|
||
точкам не ляжет в допуск. Четыре вещи, каждая из которых стоила захода:
|
||
|
||
- **Ось Y в SVG смотрит вниз** — без инверсии контур встаёт вверх ногами, и это видно только на снимке.
|
||
- **Дуги задавай тремя точками** (`arc3points`): концы заданы явно, соседние примитивы стыкуются
|
||
точно. Перед постройкой проверь цепочку — конец примитива против начала следующего, разрыв 0.
|
||
- **Чисти мелочь под масштаб детали — параметром `minSegment`.** SVG рисуют в своём габарите (сотня
|
||
условных единиц), и его скругления после масштабирования превращаются в дуги по 0.02–0.5 мм;
|
||
замыкающий `z` часто даёт ещё и сегмент нулевой длины. `chamfer_edge` по такому набору отвечает
|
||
«катет больше длины N из M рёбер» — и это правда. Передай `sketch_create(minSegment=катет)` (тот же
|
||
параметр есть у `sketch_update` и `fragment_create`), и та же фаска пройдёт с первой попытки;
|
||
отчёт о выброшенном читай, а не пролистывай — `help(topic="contour-cleanup")`.
|
||
|
||
**Порядок для фаски по контуру логотипа — только такой, и он неочевиден:**
|
||
|
||
1. **чистка** порогом ≈ будущего катета (`minSegment`);
|
||
2. **замер ЧИЩЕНОГО силуэта** — `sketch_measure_thickness(entitiesFile, minSegment=тот же порог)`;
|
||
3. **катет по узкому месту** чищеного силуэта: `c ≤ (узкое_место − 2·w)/2`, где `w` — ширина нити.
|
||
|
||
Менять шаги местами нельзя: **чистка СУЖАЕТ узкое место**. Она заменяет скругление острым углом —
|
||
в выпуклом углу это добавляет материал (габарит подрастает), а в вогнутом срезает его, и именно
|
||
вогнутые углы образуют перемычки между штрихами. Замер обводки логотипа шириной 105 мм:
|
||
узкое место 1.98 → 1.82 мм, порог распада лицевой грани 0.99 → 0.91. Катет, подобранный по
|
||
нечищеному контуру, после чистки перестаёт проходить свой же критерий.
|
||
|
||
- **Ширину штриха и узкое место меряй инструментом, а не глазом** — `sketch_measure_thickness`
|
||
ничего не строит и документа не требует, поэтому зовётся ДО эскиза
|
||
(`help(topic="silhouette-thickness")`). От этих чисел зависит, останется ли что-то от рисунка
|
||
после фаски и напечатается ли он вообще; шаг растра в ответе — точность округления катета.
|
||
|
||
Контур, который переживёт конкретную деталь (логотип, шаблон, профиль), клади во фрагмент —
|
||
`fragment_create(path, entities)` тем же списком примитивов. Активный документ он не подменяет,
|
||
поэтому фрагмент можно снять посреди построения детали; габарит в ответе снят с самого документа —
|
||
сверяй его с задуманным.
|
||
|
||
**Точная подгонка и отделка — в [reference/text-and-relief.md](reference/text-and-relief.md);
|
||
прочитай его, как только доходишь до точной компоновки надписи или отделки рельефа:** подбор кегля
|
||
под заданную ширину за одну пробу, ступени `widthFactor`/`height`, приросты каймы на острых
|
||
терминалах (t/sin(θ/2)) и её роль в стыковке блоков, разрядка пробелами, кайма вокруг прямоугольной
|
||
плашки, карманы `primitive(subtract)` рядом с буквами, скругления и фаски рельефа на сотнях рёбер.
|
||
|
||
## Внешний контур: не диктуй координаты, если фигуру нельзя описать формулой
|
||
|
||
Три маршрута, и выбор между ними механический — не по вкусу, а по происхождению геометрии.
|
||
|
||
| Откуда фигура | Чем строить |
|
||
|---|---|
|
||
| **Вычисляется**: пластины, рёбра, сетка отверстий | `sketch_create(entities[])` — прямо в вызове, размеры вяжи переменными |
|
||
| **Срисована**: логотип, шаблон, кулачок, профиль | внешний вектор → JSON → `sketch_create(entitiesFile=…)` |
|
||
| **Пришла в CAD-формате**: файл от смежника | `import_drawing` (.dxf/.dwg) → фрагмент → `fragment_place` |
|
||
|
||
**Обводка занимает сотни примитивов, и переписывать их в тело вызова незачем.** У `sketch_create`,
|
||
`sketch_add` и `fragment_create` есть `entitiesFile` — путь к JSON того же формата, что `entities`;
|
||
сервер читает файл сам. Замер на эмблеме Volvo: SVG в 1.5 КБ даёт 96 примитивов (50 отрезков +
|
||
46 дуг) и 9.5 КБ JSON; через `entitiesFile` это один вызов на одну строку аргументов, а эскиз
|
||
строится за один заход. Оба параметра можно задать вместе — сначала `entities`, следом файл:
|
||
так к готовому контуру дописывают рамку или ось, не трогая файл.
|
||
|
||
Что проверить **до** постройки, а не после: габарит в ответе (`fragment_create` печатает
|
||
фактический — сверь с задуманным) и вложенные контуры. Правил заливки у эскиза КОМПАС нет: любой
|
||
вложенный контур он режет как отверстие, даже там, где вектор заливал материал. Конвертер такие
|
||
места называет заранее — на них смотри до выдавливания, иначе дыры обнаружатся на снимке.
|
||
|
||
## Фрагмент — переиспользуемый чертёж, а не сечение
|
||
|
||
Эскиз живёт внутри дерева построения и вне его не существует; фрагмент (*.frw) — самостоятельный
|
||
файл, который переживает деталь. `fragment_create` его пишет, `fragment_place` кладёт в активный
|
||
чертёж или другой фрагмент, а `mode` решает, чем он там станет — и это разные объекты, а не
|
||
оттенки одного:
|
||
|
||
- **`reference`** — вставка-ссылка: содержимым владеет файл, правка файла меняет все документы, куда
|
||
он вставлен. Ради этого фрагменты и заводят: одна заготовка на десять чертежей.
|
||
- **`copy`** — копия внутри документа, живёт своей жизнью; файл потом можно удалить.
|
||
- **`local`** — вставка, переиспользуемая только внутри этого документа.
|
||
- **`explode`** — россыпь обычных примитивов: правится по одному, но связи с файлом уже нет.
|
||
|
||
`angle` (градусы), `scale` и `mirror` задают размещение; зеркалить можно только вставку — у россыпи
|
||
отражать нечего. **Зеркало отражает относительно вертикали через точку вставки**, поэтому контур
|
||
уходит в другую сторону от неё: вставка в x=220 после `mirror` занимает 160…220, а не 220…280.
|
||
|
||
Проверять результат — `list_drawing_objects`: он показывает состав по типам, габарит и все вставки
|
||
с их файлами. Вставка, чей файл потерялся, рисуется пустым местом — в списке она помечена
|
||
недействительной, и это единственный способ отличить её от удавшейся, не глядя на экран.
|
||
|
||
## Сборка: собрать своё
|
||
|
||
Плейбук: **создать → вставить → ЗАФИКСИРОВАТЬ базовую → сопрячь → rebuild → проверить.**
|
||
Разбор чужой сборки — следующий раздел, здесь про сборку с нуля.
|
||
|
||
1. **Детали сначала сохрани в файлы.** Компонент вставляется ссылкой на `.m3d`/`.a3d`, поэтому
|
||
несохранённую деталь вставить нельзя.
|
||
2. **`document_create assembly` → `assembly_add_component(filePath, x, y, z, rx, ry, rz)`.** Углы — в
|
||
градусах, вокруг СОБСТВЕННЫХ осей компонента и по очереди X→Y→Z: второй угол считается уже от
|
||
повёрнутого положения. Пока задан один угол, разницы с мировыми осями нет.
|
||
3. **Зафиксируй базовую деталь СРАЗУ: `assembly_fix_component(componentIndex=0, fixedState=true)`.** КОМПАС не закрепляет
|
||
никого сам, включая первый компонент, и решатель двигает того, кого сочтёт нужным — в том числе
|
||
основание, вокруг которого ты собираешь всё остальное. Это самая частая причина «сопряжение
|
||
верное, а сборка расползлась».
|
||
4. **Сопрягай:** `assembly_add_mate(mateType, …)` — семь типов, адресация гранью и смысл
|
||
`orientation` в `help(topic="assembly-mates")`. Что решаешь ты, а не справочник:
|
||
- **Грань адресуй индексом, а не координатами:** `list_faces(component=N)` → пара
|
||
`faceIndex`+`componentIndex`. Точки на бумаге считать не нужно, и сервер сам проверит, что
|
||
грань принадлежит этому компоненту.
|
||
- **Сторону зазора у `distance` задаёт ВЫБОР ПАРЫ ГРАНЕЙ, и от стартового положения она не
|
||
зависит.** «Closest» — не «ближайшее»: при сонаправленных нормалях объект 1 садится со стороны
|
||
−n относительно объекта 2 (замерено двойным прогоном). Практическое правило: бери пару граней,
|
||
которые смотрят ДРУГ НА ДРУГА. Вышло зеркально — меняй грань, а не `orientation`.
|
||
- **Первое сопряжение вешай на зафиксированную деталь.** Пока в цепочке нет ни одного
|
||
закреплённого звена, решатель волен двигать любое; связка «каждый новый компонент — к уже
|
||
стоящему на месте» разваливается вдвое реже, чем связка «все ко всем».
|
||
5. **`rebuild`,** если авто-валидация написала «ℹ Требуется перестроение». Это НЕ ошибка построения:
|
||
так помечает себя свежий компонент или только что наложенная связь. Бросать работу здесь не надо
|
||
— правило «не продолжай при ⚠» касается строки со знаком ⚠, а не этой.
|
||
**Исключение из правила «⚠ = стоп».** После КАЖДОГО сопряжения авто-валидация пишет
|
||
«⚠ N операц. в ошибке: „Сопряжения“ (код 0: ошибки нет)». Это то же «требуется перестроение»,
|
||
только под знаком ⚠: код 0 и имя операции «Сопряжения» означают, что ломаться нечему. Делай
|
||
`rebuild` и иди дальше. Настоящая беда со связью видна не здесь, а в
|
||
`describe_model(sections=mates)` — по пометке `valid:false`.
|
||
6. **Проверь:**
|
||
- `describe_model(sections=components)` — origin, поворот ЧИСЛАМИ (`rx/ry/rz` в градусах, та же
|
||
семантика, что у вставки) и «зафиксирован/свободен» у каждого: этим и видно, КОГО и НА СКОЛЬКО
|
||
подвинул решатель;
|
||
- `describe_model(sections=mates)` — что с чем связано, с каким значением и не выродилось ли.
|
||
Это ключевой детектор: `assembly_add_mate` может ответить успехом, а связь окажется
|
||
вырожденной;
|
||
- `measure(kind1=face, index1=…, componentIndex1=…, kind2=face, index2=…, componentIndex2=…)` —
|
||
зазор между деталями напрямую, без арифметики по габаритам;
|
||
- `assembly_check_interference(componentIndex1, componentIndex2)` — **не налезли ли детали друг
|
||
на друга.** Проверяй все пары, которые должны идти впритирку.
|
||
|
||
**Неудачную связь не нужно пересобирать с нуля:** `assembly_delete(target="mate"|"component", index)`
|
||
снимает сопряжение или компонент вместе с опирающимися на него связями. Индексы после удаления
|
||
сдвигаются — иди от больших к меньшим и перечитывай `describe_model(sections=mates)`.
|
||
|
||
**Пересечение деталей не видно НИГДЕ, кроме `assembly_check_interference`.** Сборка складывается из
|
||
готовых тел, и КОМПАС их не вычитает: две детали могут занимать общий объём, а сопряжения при этом
|
||
останутся `valid`, раздел `errors` — пустым, объём экспорта — простой суммой компонентов. `measure`
|
||
тоже не спасает: нулевой зазор одинаково означает и касание, и взаимопроникновение. Проверяй все
|
||
пары, которые должны идти впритирку.
|
||
|
||
**«Тела: 0» в сборке означает не «пусто», а «спрошено не то»:** тела принадлежат компонентам
|
||
(`describe_model(component=N, …)`), а `box` и `mass` без `component` честно дают габарит и МЦХ сборки
|
||
целиком. Про разные системы координат внутри паспорта компонента —
|
||
`help(topic="model-inspection")`; про локальные координаты граней и `pointOnFace` —
|
||
`help(topic="face-addressing")`.
|
||
|
||
## Чертёж: оформить деталь по ГОСТ
|
||
|
||
Чертёж строится не так, как деталь: **авто-валидации здесь нет**. Правило трёх проверок из §«Базовый
|
||
цикл» в 2D не работает — операция не отчитывается «построилось верно», потому что верность тут не
|
||
про геометрию, а про место на листе. Проверять приходится самому, и способ ровно один: посмотреть.
|
||
|
||
**Порядок, который окупается:**
|
||
|
||
1. **Деталь строится в чертёжной ориентации.** Набор видов задаётся ОТ модели: `mainOrientation`
|
||
выбирает, какую ориентацию модели показывает главный вид, но саму ориентацию модели он не
|
||
вращает. Если самая информативная проекция детали — не одна из шести стандартных, чертежа по
|
||
ГОСТ не выйдет; планируешь чертёж — строй эскизы так, чтобы главный вид попадал на плоскость
|
||
с наибольшей информацией.
|
||
2. **`drawing_set_sheet_format`** (формат до видов — иначе виды придётся двигать), при
|
||
необходимости `drawing_add_sheet` для второго листа.
|
||
3. **`drawing_create_standard_views(views=[…], mainOrientation=…, hiddenLines=…)`** — бери ровно те
|
||
проекции, которые нужны: лишний вид — лишнее место и лишний повод ошибиться видом. **Главный вид
|
||
входит в набор сам**: перечисленные коды — это проекции ОТНОСИТЕЛЬНО него, поэтому `views=["top"]`
|
||
даёт ДВА вида (главный и сверху). Ответ возвращает НОМЕРА видов, и дальше всё адресуется ими.
|
||
4. **Координаты — замером, а не формулой.** `drawing_get_view_info(viewNumber)` отдаёт паспорт вида
|
||
одним вызовом: положение на листе, масштаб, габарит и — главное — локальную СК: куда попадает
|
||
начало координат модели и куда смотрят её оси +X/+Y/+Z в координатах вида (нулевой орт = ось
|
||
проекции, вдоль неё вид смотрит). Этого хватает, чтобы пересчитывать точки модели в вид
|
||
арифметикой; отдельные точки переводит `drawing_project_point(x, y, z, viewNumber)`.
|
||
Выводить оси из головы не надо и вредно: у КОМПАС «спереди» показывает плоскость XY детали, а
|
||
«сверху» — X и **минус Z**, и **знаки инверсии зависят от `mainOrientation`** — формула,
|
||
выведенная на одном чертеже, на соседнем врёт.
|
||
5. **Разрез — до размеров, а не после.** Внутреннюю геометрию (зенковка, ступенчатое отверстие,
|
||
паз, глубокая расточка, полость) показывай разрезом, а не невидимыми линиями: по штриховой линии
|
||
нельзя ни поставить нормальный размер, ни разобрать форму. `drawing_add_section_view` — см.
|
||
§«Разрез» ниже. Размеры внутренней геометрии ставятся УЖЕ НА РАЗРЕЗЕ, поэтому строить его надо
|
||
раньше простановки, иначе размеры придётся переносить.
|
||
6. **Размеры**, `drawing_add_axis` (осевые и центровые), шероховатость, выноски, техтребования,
|
||
штамп. **Осевые сначала посмотри, потом добивай**: ассоциативные виды приходят со СВОИМИ
|
||
центровыми и осевыми, которые КОМПАС ставит сам, и `drawing_add_axis` вслепую даёт дубли поверх
|
||
существующих. Сначала `list_drawing_objects(kind="axis"|"centreMarker", viewNumber=…)`.
|
||
7. **`drawing_export_image`** — посмотреть глазами. Пока картинки не было, чертёж не сдан.
|
||
|
||
### Разрез
|
||
|
||
`drawing_add_section_view` делает всё сразу: проводит линию разреза на базовом виде и строит по ней
|
||
производный вид со штриховкой. Механика, ступенчатый разрез и встроенная проверка честности —
|
||
`help(topic="drawing-sections")`; здесь только решения, которые принимаешь ты:
|
||
|
||
- **Разрез или `hiddenLines`.** Разрез — когда внутреннее нужно ИЗМЕРИТЬ или показать форму:
|
||
зенковка и цековка, ступенчатое или резьбовое отверстие, паз, канавка, глубокая расточка, тонкая
|
||
стенка полой детали. Невидимые линии — только намёк на то, что уже показано где-то ещё; размер к
|
||
штриховой линии не привязывают.
|
||
- **Веди линию с запасом за габарит** (плита 60 мм → от −40 до +40): линия по самому краю режет не
|
||
всю деталь. Координаты — в ЛСК БАЗОВОГО вида, её даёт `drawing_get_view_info`.
|
||
- **Строй разрез, когда модель готова**: после правки детали перестраивается только ПЕРВЫЙ разрез
|
||
базового вида. Модель всё же изменилась — снеси разрезы и построй заново.
|
||
- Сам разрез дальше — обычный вид: размеры и обозначения ставятся на него по его номеру.
|
||
|
||
**Промах простановки лечится, а не остаётся навсегда.** Отката (undo) у чертежа нет, но
|
||
`list_drawing_objects` показывает обозначения с индексами, `drawing_delete_object` убирает одно, а
|
||
`drawing_move_object` его СДВИГАЕТ — слипшиеся тексты соседних размеров лечат именно сдвигом, а не
|
||
заменой размера на выноску. Так же правится и компоновка: `drawing_move_view` переставляет вид со
|
||
всеми обозначениями, `drawing_add_view` доносит недостающую проекцию, `drawing_delete_view` убирает
|
||
лишнюю. Пересоздавать документ ради компоновки не нужно. Подробности адресации и порядок удаления —
|
||
`help(topic="drawing-fixing")`.
|
||
|
||
**Три вещи, на которых чертёж молча выходит неверным** — держи их в голове, детали в справочнике:
|
||
|
||
- `viewNumber=0` — это НЕ главный вид, а координаты ЛИСТА; знак, поставленный «на главном виде» с
|
||
нулём, уезжает за границы формата (`help(topic="drawing-views")`);
|
||
- ассоциативны только диаметральный и радиальный размеры; линейный и угловой меряют координаты, и
|
||
«60» останется, когда деталь станет 70 — после правки модели перепроверяй их сам
|
||
(`help(topic="drawing-dimensions")`);
|
||
- допуск, не легший в размер, виден только по пустому read-back в ответе — техтребования его не
|
||
заменят (`help(topic="drawing-dimension-text")`).
|
||
|
||
Ещё две ловушки, о которых узнаёшь только столкнувшись: штамп частично ведёт МОДЕЛЬ, а не чертёж
|
||
(`help(topic="drawing-title-block")`), и у цилиндрической грани нет «координат оси» — её
|
||
восстанавливают и проверяют сходимостью площадей (`help(topic="cylinder-axis")`).
|
||
|
||
**Чего нет.** Выносного элемента (увеличенный фрагмент), МЕСТНОГО разреза внутри вида, местного
|
||
вида и вида с разрывом. Ассоциативного ЛИНЕЙНОГО размера нет и не будет: в API у него нет привязки к геометрии
|
||
ни под каким именем (проверено QI, поздним связыванием и размером с обрывом). Экспорта в PDF/DXF
|
||
тоже нет — наружу уходит растр (`drawing_export_image`) и STEP.
|
||
|
||
## Работа с импортом / сборками
|
||
|
||
Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»:
|
||
|
||
1. **`import_model`** — `type` задаёт документ: `assembly` (по умолчанию) или `part`.
|
||
Формат берётся из расширения; `.prt` и `.asm` носят несколько САПР сразу — там задавай `format`
|
||
явно. Нужна отдельная деталь файлом — включай `createComponentFiles`: без него импорт не пишет
|
||
на диск ничего, кроме открытого документа.
|
||
Плоский чертёж (.dxf/.dwg) читает не он, а `import_drawing`.
|
||
2. **Разбор:** `describe_model(sections=components)` (у каждого компонента — origin, поворот,
|
||
фиксация) и `describe_model(sections=mates)`, если сборка пришла со связями; грани компонента —
|
||
`list_faces(component=N)`. Извлечённую деталь открывай самостоятельным документом.
|
||
Гашение видимости компонента на снимок **не влияет** — изоляция так не делается.
|
||
3. **Осмотр — структурно** (`describe_model`: какая ось «высота», МЦХ, топология). Снимок
|
||
`model_snapshot(view=…)` — ракурс выбирай по плоскости детали (плоскую смотри сверху или
|
||
спереди, не в изометрии); один и тот же `view` даёт воспроизводимый кадр «до/после».
|
||
**Пары ракурсов противоположны по оси:** `front` смотрит из +Z, `rear` — из −Z, так же
|
||
`top`/`bottom` и `left`/`right`. Следствие, которое нужно чаще всего: деталь, лежащая на столе
|
||
гранью Z=0 (эскиз на XOY, выдавливание вперёд), видна столу как **`rear`**, а `front` покажет
|
||
зеркальную картинку. Читаемость надписи или логотипа доказывают снимком с нужной стороны, а не
|
||
рассуждением.
|
||
4. **Модификация «тупой» B-rep** (итог — в ответе каждой операции): простой случай — `move_face`;
|
||
вставка N мм в призматическую ножку — `split_solid_by_plane` → `move_body` → `move_face` (мост)
|
||
→ `boolean_union` (шаги пронумерованы в описаниях самих инструментов; цепочка проверена
|
||
end-to-end: проставка 39.45 → 41.45 мм, построение чистое).
|
||
5. **Перед выдачей:** последняя операция «Построение чистое» → `export_model` (STEP для обмена,
|
||
STL для печати).
|
||
|
||
## Эвристики и подводные камни
|
||
|
||
- **Правила 1 и 2 действуют всегда:** осмотр структурный; «⚠ N операц. в ошибке» — в STEP/печать
|
||
не брать.
|
||
- **Направление операции** (`extrude(forward)`, знак `distance` у `move_face`): на выбранной грани
|
||
зависит от ориентации её нормали — реши ДО построения, прочитав нормаль в `list_faces(index=N)`
|
||
(или по снимку), а после сверь сводку объёма в ответе.
|
||
- **Эскизы и операции адресуются ХЕНДЛАМИ из ответов** — `sk_7c1e5aa3f1_1_2`, `op_7c1e5aa3f1_1_5`.
|
||
Не сочиняй их и не передавай числа: числовая адресация не поддерживается, а сервер объяснит формат
|
||
отказом. Хендл живёт только в текущей сессии построения: смена активного документа
|
||
(create/open/close) и перезапуск сервера делают прежние хендлы **мёртвыми**, и они отказывают с
|
||
указанием причины — не молча, как раньше делали числовые id. Потерял хендл — читай
|
||
`describe_model(sections=tree)` и строй заново; сохраняйся перед долгими паузами.
|
||
Хендл — это НЕ индекс: `faceIndex`/`edgeIndices` из `list_faces`/`list_edges` и параметр
|
||
`feature` у `link_parameter`/`list_parameters` (имя или индекс узла дерева) остаются числовыми.
|
||
`primitive` и `hole` тоже возвращают хендл (у `hole` — по одному на КАЖДОЕ отверстие серии),
|
||
так что примитив и отверстие можно удалить `feature_delete` и размножить `pattern`/`mirror`.
|
||
Если ответ вместо хендла говорит «выдать не удалось» — операция построена, но адресовать её
|
||
нечем: переставить её потом можно только пересборкой.
|
||
- **Единицы — мм** (геометрия) и **кг** (масса). Локальные координаты эскиза ≠ мировые координаты
|
||
модели.
|
||
- **Одинаковая ошибка у ВСЕХ инструментов — это транспорт, а не КОМПАС.** «Unable to connect…»,
|
||
таймаут или пустой ответ на `kompas_connect`, `kompas_status` и `describe_model` одновременно
|
||
означают, что до MCP-сервера не дошёл ни один байт: перебирать инструменты и «пробовать ещё раз»
|
||
бесполезно. Один-два подтверждающих вызова — и сдавай задачу как заблокированную, назвав, что
|
||
именно не отвечает. Отдельный признак того же — сообщение без имени инструмента и без слова
|
||
«КОМПАС»: наши ошибки всегда называют операцию и причину.
|
||
|
||
## Когда КОМПАС общий
|
||
|
||
По умолчанию (`instance="shared"`) сервер работает в том же экземпляре КОМПАС, что человек и другие
|
||
агенты, а **активный документ там один на всех**. Два симптома, которые легко принять за свою
|
||
ошибку: операция ушла в чужую деталь (кто-то создал документ — активность переехала), либо твой
|
||
документ исчез, потому что сосед вызвал `document_close(all=true)` — тот закрывает ВСЁ и без
|
||
сохранения.
|
||
|
||
- **Строишь параллельно с кем-то — `instance="private"`** при первом `kompas_connect` (потом режим
|
||
не сменить). Свой экземпляр: активный документ только твой, окно скрыто (`kompas_set_visible true`
|
||
покажет).
|
||
- **`shared` оставляй**, когда работа идёт на глазах у человека и ты единственный агент.
|
||
- **Один файл в двух экземплярах не открыть** — второй получит его только на чтение: работу делите
|
||
по файлам, а не по вкладкам.
|
||
|
||
## Открытые вопросы / границы
|
||
|
||
- **Параметрика работает через параметры ОПЕРАЦИЙ, а не размеры эскиза** — сдвинуть контур
|
||
переменной нельзя, только пересобрать эскиз. Планируй членение так, чтобы изменяемое задавалось
|
||
параметром операции (глубина, радиус, габарит примитива), а не координатами в эскизе.
|
||
- **2D покрыт вместе с разрезом и сечением.** Есть виды (с выбором набора, ориентации главного и
|
||
невидимых линий), разрез/сечение, листы, штамп, размеры с допусками, осевые, обозначения,
|
||
техтребования, удаление и сдвиг объекта, вывод в растр — методика в §«Чертёж». Нет выносного
|
||
элемента, местного разреза внутри вида, местного вида и вида с разрывом.
|
||
- **Разрез не переживает правку модели, если он не первый на своём базовом виде.** Замерено:
|
||
обновляется только ПЕРВЫЙ, остальные молча остаются со старой геометрией, и ни одно перестроение
|
||
этого не чинит. Порядок один: сначала модель, потом разрезы.
|
||
- **Вставку фрагмента правят только целиком** (заново `fragment_place`). Экспорт наружу — растр и
|
||
STEP; DXF/DWG и PDF не пишутся.
|
||
- **SVG сервер не читает** — и не будет: разбор путей, деление кривых Безье на дуги и разбор
|
||
вложенности контуров живут во внешнем конвертере, а серверу достаётся готовый список примитивов.
|
||
|
||
## Связанное
|
||
|
||
- Проверка окружения (КОМПАС установлен, сервер запускается, подключение живое): команда **`/kompas:doctor`**.
|
||
- Установка, требования и настройка сервера: README плагина.
|
||
- Правила проектирования под FDM/FFF-печать: навык **`kompas-fdm-design`**.
|