@@ -23,6 +23,26 @@ MCP-сервер даёт **общие** операции КОМПАС (эски
Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции,
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки.
## Указатель: тип задачи → файл
Этот файл — ядро: применяется в любой задаче. Развёрнутый playbook под конкретный тип работы вынесен
в `reference/*.md` — читай Read'ом ровно тот файл, что подошёл, остальные не трогай.
| Задача | Файл |
|---|---|
| Переменные, параметрическая модель | `reference/parametrization.md` |
| Надпись, логотип, SVG, рельеф, выбор маршрута для внешнего контура | `reference/text-and-relief.md` |
| Переиспользуемый чертёжный блок (*.frw) | `reference/fragments.md` |
| Сборка с нуля (вставка, сопряжения, фиксация) | `reference/assembly-playbook.md` |
| Чертёж по ГОСТ, виды, разрез, размеры | `reference/drawing-playbook.md` |
| Разбор ЧУЖОЙ модели/сборки (импорт, STEP) | `reference/import-playbook.md` |
| Исполнения (типоразмеры, зеркала в одном файле) | `reference/embodiments-playbook.md` |
Ни один файл не подошёл — вопрос, скорее всего, про механику КОНКРЕТНОГО инструмента, а не про
порядок работы: туда — `help(topic="…")` /`help(query="…")` (см. ниже), а не в `reference/` .
Не нашёлся и там — `Grep` по `reference/**` словами задачи: это и есть весь механизм поиска, ничего
специального заводить не пришлось.
## Два правила прежде всего
**1. «Зрение» — структурное, не по картинке. ** «Увидеть» деталь = * * `describe_model` ** — паспорт
@@ -40,7 +60,7 @@ variables | errors | components` (`sections` сужает и ответ, и об
скажет «Документ ТРЕБУЕТ ПЕРЕСТРОЕНИЯ» (`needsRebuild: true` ); увидел — `rebuild` и повтори осмотр,
выводов по непересчитанной модели не делай.
**2. Ответ мутирующей операции — это ТРИ проверки , читай все. ** Любая операция может «пройти»
**2. Ответ мутирующей операции — это НЕСКОЛЬКО проверо ** Любая операция может «пройти»
(`Create()==true` ), оставив деталь в ошибке, поэтому каждая мутирующая операция сама дописывает
к ответу итог проверки построения и сводку состояния «Тел: N, объём V мм³»:
@@ -52,9 +72,27 @@ variables | errors | components` (`sections` сужает и ответ, и об
- **«Тел: 2»** там, где ждёшь одно тело, — деталь распалась: касание объединением не считается
(см. «Надписи»). Смотри на число ТЕЛ, а не граней: объединение сливает компланарные грани,
и счётчик граней законно остаётся прежним.
**Но обратное неверно: «Тел: 1» распад не опровергает. ** Счётчик в сводке ОПАЗДЫВАЕТ. Замер
(журнал операций кейса с хвостом по сечениям): `loft` построил второе тело и отчитался
«Тел: 1», следом `mirror` — снова «Тел: 1», и только третья операция, `chamfer_edge` , напечатала
«Тел: 2», хотя между ними ничего не создавалось. Три операции подряд шли по детали, объём
которой считал пересечение дважды. Поэтому «Тел: 2» — тревога, которой верят сразу, а «Тел: 1» —
не доказательство: там, где важно именно СРАСТАНИЕ (loft/sweep на грань, надпись, примитив
впритык), проверяй `describe_model(sections="bodies")` — у каждого тела там свой габарит — и сверяй
объём с прикидкой.
- **Объём сверяй с прикидкой** «площадь контура × высота». Так ловятся молча не применившаяся
тонкая стенка (прирост как у сплошного сечения), вычитание мимо цели и операция «не туда» —
габарит и снимок этого не покажут.
- **«⚠ Сверка с запросом: …»** — четвёртая, отдельная от первых трёх строка: сервер сравнил
результат с ВХОДНЫМИ параметрами вызова. Сейчас это положение материала у `extrude(mode=boss)`
и покрытие сечений у `loft(mode=boss)` (на базовых и смещённых плоскостях), убыль объёма у
`extrude(mode=cut)` , а у `primitive` — объём против номинала по его же размерам. Сработала —
построено не то, о чём просили, и в тексте сказано что именно. **Молчание успех НЕ доказывает ** :
сверка односторонняя и намеренно молчит там, где улика неоднозначна (прирост меньше
запрошенного, материал целиком внутри габарита, эскиз выдавливания на грани, сечения лофта на
наклонной грани или с одинаковыми именами). Размер-выражение сверке не мешает: и у `primitive` ,
и у `extrude` величина проверяется по уже вычисленному значению. Механика и границы —
`help(topic="build-verification")` .
Отдельный `describe_model(sections=errors,bodies,mass)` после каждого шага не нужен. Он
возвращается, когда авто-проверку выключили (`set_auto_validate(false)` на тяжёлой модели, где
@@ -76,58 +114,12 @@ variables | errors | components` (`sections` сужает и ответ, и об
намеренно не повторяется. Справочник описывает ЭТОТ сервер; справка по 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` — сетка в слайсер).
- *Исполнения:* `embodiment` (`set|add|delete|rename` ; `kind=embodiment|mirror|variant` ) — несколько
геометрий одной модели в одном файле; список с габаритом и массой каждого —
`describe_model(sections=embodiments)` .
- *Сборка:* `assembly_add_component` (положение + поворот `rx/ry/rz` , `embodiment` — какое исполнение
источника вставлять), `assembly_add_mate` (стороной может быть грань ИЛИ вспомогательный объект
`object1/object2` : плоскости и оси СК компонента, а без `componentIndex` — самой сборки)
(семь типов, `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` ; у `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` (что лежит в чертеже/фрагменте).
Три сквозных свойства контракта: **размерный параметр принимает число ИЛИ выражение ** (имя
Пол ный перечень 86 инструментов с параметрами — README плагина §«Инструменты» (единый источник
правды, держать вторую копию здесь не нужно) или `tools/list` самого MCP-сервера. Что известно про
КОНКРЕТНЫЙ инструмент — `help(tool="extrude")` . Три сквозных свойства контракта, которые полезно
держать в голове, а не искать заново на каждом инструменте: **размерный параметр принимает число ИЛИ выражение ** (имя
переменной/формулу — параметр сразу становится ведомым); **объект выбирается индексом ** (надёжно)
или точкой (запасной путь — если выбирал точкой, ответ подскажет, что выбралось); **списковые
параметры** (`entities[]` , `edgeIndices[]` , `points[]` , `faceIndices[]` , `variables[]` , `links[]` ) —
@@ -138,6 +130,14 @@ variables | errors | components` (`sections` сужает и ответ, и об
остаётся — повторяй вызов с оставшимися, а не с начала. Если инструмента под задачу нет — собирай
результат из имеющихся общих операций.
**Оговорка для больших групп рёбер в `fillet_edge`/`chamfer_edge`. ** «Один вызов на весь пакет»
экономит вызовы, но у катета/радиуса есть рабочий диапазон, заданный ВСЕЙ группой рёбер разом, а
не отдельным ребром (измерено: один и тот же контур строится с меньшим катетом и отказывает с
большим). Параметрическая модель может пройти это на одном значении переменной и отказать на
другом — большая группа сама по себе фактор хрупкости при последующей правке размеров. Если пакет
на 15+ рёбер отказывает без диагноза по длине, разбейте его на 2–3 группы — сервер сам подскажет
это в тексте отказа (`help(topic="edge-groups")` ).
## Два пути формообразования — выбирай по форме, а не по привычке
«Эскиз → выдавливание» — не единственный способ. `primitive` строит тело сразу по размерам, и это
@@ -148,7 +148,9 @@ variables | errors | components` (`sections` сужает и ответ, и об
| Плита, брусок, бобышка, штифт, цилиндрическая стойка | `primitive(kind=block\|cylinder)` — один вызов вместо «эскиз + выдавливание» |
| Прямоугольный карман, паз, срез угла | `primitive(..., result=subtract)` — вычитание тела вместо `extrude(mode=cut)` по эскизу |
| Скруглённые углы призмы | `primitive` + `fillet_edge` по рёбрам (скругление после, а не дуги в эскизе) |
| Текст, кривые, произвольный контур, переменное сечение | ТОЛЬКО эскиз: `sketch_create(entities=[…])` + `extrude` /`revolve` / `loft` / `sweep`
| Текст, кривые, произвольный контур | ТОЛЬКО эскиз: `sketch_create(entities=[…])` + `extrude` /`revolve` |
| Переменное сечение: хвост, гребень, переход круга в квадрат | `loft` по сечениям на смещённых плоскостях (`mode=boss` приклеивает к телу) |
| Труба, поручень, кант по кривой | `sweep(profileSketchId, pathSketchId)` — профиль и траектория на разных плоскостях |
| Тонкая стенка, ободок по контуру | эскиз + `extrude(thinThickness, thinSide)` |
Их **сочетают в одной детали ** : корпусные объёмы — примитивами, сложные контуры — эскизами.
@@ -170,8 +172,26 @@ variables | errors | components` (`sections` сужает и ответ, и об
координат — одна операция на все; точки без ребра ошибка перечислит разом.
- **Скругление не построится там, где ребро «съедено» соседним элементом** (угол плашки под каймой
букв). Это нормальный ответ геометрии, а не ошибка вызова: проверь снимком, виден ли угол снаружи.
- **Фаска на почти касательном стыке может ДОСТРОИТЬ объём, а не срезать.** Замер: `chamfer_edge`
0.3 по кромке, где поверхность лофта сходит в плоскость почти по касательной, — «построение
чистое», а объём ВЫРОС на 2.2 мм³. На выпуклом ребре фаска обязана объём УМЕНЬШАТЬ (на вогнутом
легитимно добавляет); сверяй ЗНАК приращения в сводке ответа со своим ожиданием — вырос без
причины, значит фаска выродилась в достройку: убери её `feature_delete` , пологому стыку она
и не нужна.
- **`result=new` даёт ОТДЕЛЬНОЕ тело**, `subtract` мимо цели сервер ловит сам — и то и другое
видно по сводке «Тел/объём» в ответе; при распаде зови `boolean_union` .
- **Сужающуюся или изогнутую форму не набирай лесенкой из примитивов.** `primitive` не умеет
поворота, и «хвост» из десятка блоков со ступеньками — это обход отсутствующего инструмента,
а не решение: он и печатается хуже, и правится только целиком. Бери `loft` по 4–6 сечениям на
смещённых плоскостях — параметричность не теряется, `offset` плоскости принимает выражение.
* * `loft` может отказать молча, и отказ зависит от ПРОЛЁТА, а не от одного сечения** — поиск
виновника перебором пар не работает, ломается СОЧЕТАНИЕ «сечение-выброс + длина набора»; механика
и порядок поиска — `help(topic="loft-and-sweep")` .
- **`loft(mode=boss)` прирастает перекрытием, а не касанием.** Первое сечение ставь на плоскость
ВНУТРИ уже построенного тела (смещение на 1–2 мм вглубь), а не на его грань: касание объединением
не считается — на грани получишь ВТОРОЕ тело вместо приросшего. **Проверять это сводкой «Тел: 1»
НЕЛЬЗЯ** — именно здесь она и соврала (см. правило 2): считай тела
`describe_model(sections="bodies")` , там у каждого свой габарит, и сверь объём с прикидкой.
## Базовый цикл (эскиз → операция → осмотр)
@@ -203,29 +223,16 @@ variables | errors | components` (`sections` сужает и ответ, и об
пересборки. Набор переменных — это план построения числами и паспорт, по которому человек поймёт
модель, не разбирая дерево.
- **Заводи переменной то, что было РЕШЕНИЕМ**: габариты из ТЗ, толщины, зазоры, отступы, кегли,
радиусы. Выводимое задавай формулой (`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 мм³). Это и есть параметрическая модель,
а не комментарий к ней. **До связывания — не перестраивает ** , и `set_variable` говорит об этом
прямо: «⚠ НИЧЕГО НЕ ВЕДЁТ». Такой ответ — не успех: число поменялось, деталь нет.
- **Сверка и уборка в конце:** `describe_model(sections=variables)` помечает «⚠ ничего не ведёт» — это либо забытая
связь, либо мусор; разбери оба. `delete_variable(unused=true)` — только ПОСЛЕ `link_parameter`
на всё, что должно вести геометрию: вычистка не отличает мусор от несвязанного размера из ТЗ.
- **Заводи переменной то, что было РЕШЕНИЕМ** ( габариты из ТЗ, толщины, зазоры) , позиции, подобранные
замером, оставляй числами; **размер передавай выражением прямо в операцию **
(`extrude(depth="badge_T")` ) — переменная должна существовать ДО операции.
- **После связывания правка паспорта перестраивает деталь; до связывания — нет**, и `set_variable`
прямо говорит «⚠ НИЧЕГО НЕ ВЕДЁТ» в этом случае — не успех, хоть число и поменялось.
- **Сверка и уборка в конце:** `describe_model(sections=variables)` помечает «⚠ ничего не ведёт»;
`delete_variable(unused=true)` не трогает справочные (`information` ) и внешние.
Полная методика — обязательные поля ( `note` ), как с ервер ловит промахи в формулах, справочные
переменные `(ТЗ)` и порядок уборки — [reference/parametrization.md ](reference/parametrization.md ).
## Надписи, логотипы и рельеф
@@ -247,301 +254,54 @@ variables | errors | components` (`sections` сужает и ответ, и об
- **Надпись и плашка обязаны ПЕРЕКРЫВАТЬСЯ** — по размерам чертежа блоки обычно только касаются,
а касание объединением не считается. Приём: кайму/полосу плашки сделать выше самой плашки на
1–1.5 мм с той стороны, где стоит надпись. Распад видно по «Тел: 2» в ответе операции — не тяни
проверку до конца построения.
проверку до конца построения. Молчание сводки распад не опровергает (счётчик опаздывает, п. 2):
убедиться, что срослось, можно только `describe_model(sections="bodies")` .
- **Рельеф = разница глубин от одной плоскости** (основание 2 мм + буквы 3 мм = выступ 1 мм);
не строй буквы «на грани основания» — из одного эскиза на базовой плоскости получается и то и
другое, и рельеф не зависит от порядка операций.
- **Надпись читается только с той стороны, куда смотрит нормаль плоскости эскиза** — XOY → +Z,
XOZ → +Y, **YOZ → − ** . Гравировка по эскизу на YOZ, положенная на грань с бОльшим X, выходит
ЗЕРКАЛЬНОЙ, и `angle` этого не исправляет: он вращает, а не отражает (замер — цифра на щеке
X=20.4 зеркальна при любом угле, тот же эскиз на X=0 встаёт верно). Выбирайте грань по нормали,
а поворотом задавайте только, куда смотрит верх глифа. Проверять — снимком С ТОЙ СТОРОНЫ, где
надпись будет видна: `model_snapshot(view=left)` для грани X=0, `right` для X=max.
- **Шрифт должен быть установлен в системе** — неизвестное имя КОМПАС молча подменяет; сервер
предупреждает об этом в ответе `sketch_create` /`measure_text` — не игнорируй.
**Логотип, которого нет в шрифте, приходит готовым вектором (SVG). ** Переводи его в примитивы
эскиза сам — `line` и `arc3points` , а не ломаной: контур из сотен звеньев даёт деталь в сотни
граней, и фаска по такому низу не строится. Кубические Безье режь пополам, пока дуга по трём
точкам не ляжет в допуск. Четыре вещи, каждая из которых стоила захода:
**Логотип (SVG) и выбор маршрута для внешнего контура (вычисляемый / срисованный / CAD-файл) —
в [reference/text-and-relief.md ](reference/text-and-relief.md ).** Там же — точная подгонка (кегль
под заданную ширину, ступени `widthFactor` /`height` , приросты каймы на острых терминалах, разрядка
пробелами, кайма вокруг прямоугольной плашки) и отделка рельефа (скругления/фаски на сотнях рёбер).
Прочитай его, как только контур не сводится к простому вычисляемому эскизу.
- **Ось 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, а
Проверять результат — `list_drawing_objects` : он показывает состав по типам, габарит и все вставки
с их файлами. Вставка, чей файл потерялся, рисуется пустым местом — в списке она помечена
недействительной, и это единственный способ отличить её от удавшейся, не глядя на экран.
Фрагмент (*.frw, с а стоятельный файл переиспользуемого контура/чертежа) —
[reference/fragments.md ](reference/fragments.md ).
## Сборка: собрать своё
Плейбук: **создать → вставить → ЗАФИКСИРОВАТЬ базовую → сопрячь → 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")` .
Сборка с нуля целиком, с адресацией граней, семью типами сопряжений и порядком проверки —
[reference/assembly-playbook.md ](reference/assembly-playbook.md ). Разбор чужой сборки (пришедшей
STEP/импортом) — следующий раздел.
## Чертёж: оформить деталь по ГОСТ
Чертёж строится не так, как деталь: **авто-валидации здесь нет ** . Правило трёх проверок из §«Базовый
цикл» в 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.
Чертёж строится не так, как деталь: **авто-валидации здесь нет ** — верность тут не про геометрию,
а про место на листе, и проверяется только просмотром. Порядок «формат → виды → координаты замером
→ разрез до размеров → простановка → `drawing_export_image` », разрез, три ловушки, на которых
чертёж молча выходит неверным (`viewNumber=0` , ассоциативность размеров, допуск без read-back), и
чего в 2D нет — [reference/drawing-playbook.md ](reference/drawing-playbook.md ).
## Работа с импортом / сборками
Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»:
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` — из −
`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 для печати).
Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт» для ЧУЖОЙ модели —
[reference/import-playbook.md ](reference/import-playbook.md ).
## Исполнения: одна модель — несколько геометрий
Типоразмеры (профиль на 100, 200, 500 мм), правое и левое зеркало часто
живут **в одном файле ** исполнениями. Тогда всё, что ты меришь и экспортируешь, относится к
**текущему ** исполнению — не к «детали вообще» .
- **Признак замечаешь не ты, а ответ.** У модели с несколькими исполнениями `describe_model` сам
пишет, сколько их и какое сейчас текущее. Увидел эту строку — прежде чем считать массу или резать
чертёж, посмотри `describe_model(sections=embodiments)` : там габарит и масса **каждого ** , и это
чтение ничего не переключает.
- **Переключение равно смене документа.** `embodiment(action="set", target="L200")` обнуляет
сессию построения: хендлы `sk_…` /`op_…` после него мертвы. Сохраняй документ до переключения.
- **Индекс живёт до первой правки дерева**: после `delete` индексы смещаются. Адресуй обозначением
(«L500»), а индексом — только сразу после того, как увидел список.
- **Строишь новое исполнение** — `embodiment(action="add", number="02")` ; оно сразу становится
текущим, строй в нём немедленно. `depended=false` нужен, когда правки НЕ должны наследоваться от
родителя, — иначе изменение уедет и в него.
- **В сборку исполнение выбирается явно**: `assembly_add_component(embodiment="L500")` . Без
параметра встанет **базовое ** исполнение, а не то, что сохранено в файле текущим. Обозначение
нужно ПОЛНОЕ («ПРОБА.001-01», а не «-01»); сервер откажет, если КОМПАС подсунет базовое.
- **«Удлинить эти профили с 500 до 600» — это смена исполнения экземпляра, а не новая вставка**:
`embodiment(action="set", target="L600", component=N)` и затем `rebuild` . Сопряжения при этом
**сохраняются ** — пересоздание вставки, наоборот, порвало бы их все. Какие исполнения есть у
конкретного экземпляра, показывает `describe_model(sections="embodiments", component=N)` .
- **Выгнать всю линейку на печать** — `export_model(embodiment="all")` : каждое исполнение в свой
файл с суффиксом обозначения.
- **После смены исполнения в собранном узле проверь сопряжения** (`sections="mates"` ): если у
исполнения нет объекта, на который опиралась связь, она рвётся — «ССЫЛКА ПОТЕРЯНА», `valid: false` ,
компонент недоопределён. Что было потеряно, хранит имя сопряжения; `assembly_delete` сотрёт и его.
Подробности и границы — `help(topic="embodiments")` .
Типоразмеры, зеркала в одном файле — переключение равно смене документа
(хендлы гибнут), индексация и адресация в сборке, порядок «сначала гео мет рия, исполнения последним
шагом» — [ reference/embodiments-playbook.md ]( reference/embodiments-playbook.md ) .
## Эвристики и подводные камни
@@ -550,6 +310,28 @@ variables | errors | components` (`sections` сужает и ответ, и об
- **Направление операции** (`extrude(forward)` , знак `distance` у `move_face` ): на выбранной грани
зависит от ориентации её нормали — реши ДО построения, прочитав нормаль в `list_faces(index=N)`
(или по снимку), а после сверь сводку объёма в ответе.
- **У `forward` смотрит в другую сторону, чем у прилива.** Замерено на плите Z 0..10 с
эскизом на плоскости z=10: `extrude(mode=boss, forward=true)` наращивает ВВЕРХ, а
`extrude(mode=cut, forward=true)` режет ВНИЗ, в тело. То есть у выреза «прямое» — это внутрь
материала. Оба умолчания делают то, чего обычно и хотят, но рассуждение «forward — это плюс
нормали» даст перевёрнутый карман. **Вырез, ушедший в пустоту, КОМПАС считает успехом ** —
дерево чистое, объём не изменился; ловит это только строка сверки в ответе.
- **На YOZ деталь растёт в МИНУС X, и туда же уезжает смещение плоскости.** Нормаль базовой
плоскости смотрит в плюс своей оси не всегда — замерено: XOY → +Z, XOZ → +Y, а **YOZ → − ** .
Значит `extrude(forward=true)` по эскизу на YOZ кладёт материал в отрицательные X, а
`sketch_create(plane="YOZ", offset=30)` ставит плоскость в X = −30, а не +30. Обе вещи следуют
одной нормали, так что путаницы между ними нет — но знак учитывай при компоновке, иначе деталь
уедет зеркально задуманному. Таблица целиком — `help(topic="build-verification")` .
- **`sketch_update` несущего эскиза МОЛЧА теряет часть отделки.** Фаска и скругление, снятые по
точкам, после переиздания базового контура остаются в дереве, ошибок не дают — а построены
оказываются не на всех рёбрах: замерено трижды на одной детали, из четырёх скруглений выживали
то два, то одно. Иногда КОМПАС всё же сознаётся («код 145: операция потеряла опорные объекты»),
но чаще молчит, и единственный признак — объём: он оказывается БОЛЬШЕ ожидаемого ровно на
недоснятый материал. Порядок после каждого переиздания несущего эскиза: сверить объём с прикидкой
либо пересчитать результат отделки (`list_faces(type="cylinder")` для скруглений — их должно быть
ровно столько, сколько рёбер в пакете); недосчитались — снести отделочные узлы
(`feature_delete(featureIndices=[…])` ) и построить заново, уже по новым рёбрам. Пересборка
дешевле поиска виновного, а «построение чистое» здесь не значит ничего.
- **Эскизы и операции адресуются ХЕНДЛАМИ из ответов** — `sk_7c1e5aa3f1_1_2` , `op_7c1e5aa3f1_1_5` .
Не сочиняй их и не передавай числа: числовая адресация не поддерживается, а сервер объяснит формат
отказом. Хендл живёт только в текущей сессии построения: смена активного документа
@@ -588,9 +370,11 @@ variables | errors | components` (`sections` сужает и ответ, и об
## Открытые вопросы / границы
- **Параметрика работает через параметры ОПЕРАЦИЙ, а не размеры эскиза** — сдвинуть контур
переменной нельзя, только пересобрать эскиз. Планируй членение так, чтобы изменяемое задавалось
параметром операции (глубина, радиус, габарит примитива), а не координатами в эскизе.
- **Параметрика работает через параметры ОПЕРАЦИЙ, а не координаты ВНУТРИ эскиза** — сдвинуть
контур переменной нельзя, только пересобрать эскиз ( `sketch_update` ). Но это ограничение уже
границей: **плоскость ** эскиза — обычный узел дерева с параметром «Расстояние», и она
параметризуется как всё остальное. Планируй членение так, чтобы изменяемое задавалось параметром
операции (глубина, радиус, габарит примитива) или положением плоскости, а не координатами точек.
- **2D покрыт вместе с разрезом и сечением.** Есть виды (с выбором набора, ориентации главного и
невидимых линий), разрез/сечение, листы, штамп, размеры с допусками, осевые, обозначения,
техтребования, удаление и сдвиг объекта, вывод в растр — методика в §«Чертёж». Нет выносного
gitea-actions