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

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

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

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

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

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

## Указатель: тип задачи → файл

Этот файл — ядро: применяется в любой задаче. Развёрнутый 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`** — паспорт
одним запросом и ЕДИНСТВЕННЫЙ инструмент осмотра: разделы `box | mass | bodies | topology | tree |
variables | errors | components` (`sections` сужает и ответ, и объём чтения модели). Углубляться —
`list_faces(index=N)` / `list_edges` (отбор `type` + координатное окно — им адресуют то, что не
выбрать по одному: весь нижний контур под фаску) / `measure`. **`model_snapshot`
бери только** для визуально-пространственных вопросов, на которые паспорт не отвечает (общая
форма, ориентация, правдоподобность, «куда смотрит грань»): снимок дорог по контексту и менее
точен, чем числа.

**1а. Осмотр НЕ перестраивает документ.** Если модель правили снаружи (человек в GUI, соседний
агент) или операция запросила перестроение, `describe_model` покажет числа ДО правки — и ответ
будет выглядеть безупречным: размеры новые, положения старые, сопряжения валидны. Такой ответ сам
скажет «Документ ТРЕБУЕТ ПЕРЕСТРОЕНИЯ» (`needsRebuild: true`); увидел — `rebuild` и повтори осмотр,
выводов по непересчитанной модели не делай.

**2. Ответ мутирующей операции — это НЕСКОЛЬКО проверок, читай все.** Любая операция может «пройти»
(`Create()==true`), оставив деталь в ошибке, поэтому каждая мутирующая операция сама дописывает
к ответу итог проверки построения и сводку состояния «Тел: N, объём V мм³»:

- **«⚠ N операц. в ошибке»** (напр. `et3dError54`) — деталь невалидна: не продолжай и не
  экспортируй, исправь или переделай другим методом. «Построение чистое» = порядок.
  Строки с «ℹ» — не отказы: «требуется перестроение» лечится `rebuild`, а «не определено
  положение (N)» означает, что компоненту не хватает сопряжений или фиксации. Бросать из-за них
  исправную сборку не нужно; в обеих названы имя и индекс компонента.
- **«Тел: 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)` на тяжёлой модели, где
проверка каждого шага тормозит): тогда `describe_model(sections=errors,bodies,mass)` вручную перед выдачей: одного
`errors` мало — распад детали на два тела показывает только раздел `bodies`.

## Справочник сервера: `help`

Подробности инструментов — маршруты, порядок вызовов, ловушки — лежат в самом сервере и достаются
по требованию, а не занимают контекст заранее:

- `help()` — оглавление тем (дёшево, одна строка на тему);
- `help(topic="…")` — статья целиком;
- `help(query="…")` — поиск словами с цитатами;
- `help(tool="extrude")` — что известно про конкретный инструмент.

**Зови его, когда инструмент повёл себя не так, как ты ожидал, и когда тема названа в тексте
ошибки.** Ссылки вида `help(topic="…")` по этому файлу — не украшение: там лежит то, что здесь
намеренно не повторяется. Справочник описывает ЭТОТ сервер; справка по COM API КОМПАС — отдельная
история и в работе через MCP не нужна.

## Инструменты: где искать каталог

Полный перечень 86 инструментов с параметрами — README плагина §«Инструменты» (единый источник
правды, держать вторую копию здесь не нужно) или `tools/list` самого MCP-сервера. Что известно про
КОНКРЕТНЫЙ инструмент — `help(tool="extrude")`. Три сквозных свойства контракта, которые полезно
держать в голове, а не искать заново на каждом инструменте: **размерный параметр принимает число ИЛИ выражение** (имя
переменной/формулу — параметр сразу становится ведомым); **объект выбирается индексом** (надёжно)
или точкой (запасной путь — если выбирал точкой, ответ подскажет, что выбралось); **списковые
параметры** (`entities[]`, `edgeIndices[]`, `points[]`, `faceIndices[]`, `variables[]`, `links[]`) —
весь пакет одним вызовом: прямоугольник с четырьмя отверстиями — ОДИН `sketch_create`, скругление
восьми рёбер — ОДИН `fillet_edge`, крепёжная картина из шести отверстий — ОДИН `hole(points=[…])`,
наращивание двух торцов — ОДИН `move_face(faceIndices=[…])`; каждый лишний вызов — лишний шанс
сбиться. Пакет НЕ транзакционен: отказ называет позицию элемента в списке, а сделанное до него
остаётся — повторяй вызов с оставшимися, а не с начала. Если инструмента под задачу нет — собирай
результат из имеющихся общих операций.

**Оговорка для больших групп рёбер в `fillet_edge`/`chamfer_edge`.** «Один вызов на весь пакет»
экономит вызовы, но у катета/радиуса есть рабочий диапазон, заданный ВСЕЙ группой рёбер разом, а
не отдельным ребром (измерено: один и тот же контур строится с меньшим катетом и отказывает с
большим). Параметрическая модель может пройти это на одном значении переменной и отказать на
другом — большая группа сама по себе фактор хрупкости при последующей правке размеров. Если пакет
на 15+ рёбер отказывает без диагноза по длине, разбейте его на 2–3 группы — сервер сам подскажет
это в тексте отказа (`help(topic="edge-groups")`).

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

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

| Форма | Чем строить |
|---|---|
| Плита, брусок, бобышка, штифт, цилиндрическая стойка | `primitive(kind=block\|cylinder)` — один вызов вместо «эскиз + выдавливание» |
| Прямоугольный карман, паз, срез угла | `primitive(..., result=subtract)` — вычитание тела вместо `extrude(mode=cut)` по эскизу |
| Скруглённые углы призмы | `primitive` + `fillet_edge` по рёбрам (скругление после, а не дуги в эскизе) |
| Текст, кривые, произвольный контур | ТОЛЬКО эскиз: `sketch_create(entities=[…])` + `extrude`/`revolve` |
| Переменное сечение: хвост, гребень, переход круга в квадрат | `loft` по сечениям на смещённых плоскостях (`mode=boss` приклеивает к телу) |
| Труба, поручень, кант по кривой | `sweep(profileSketchId, pathSketchId)` — профиль и траектория на разных плоскостях |
| Тонкая стенка, ободок по контуру | эскиз + `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=[…])` по углам известных
  координат — одна операция на все; точки без ребра ошибка перечислит разом.
- **Скругление не построится там, где ребро «съедено» соседним элементом** (угол плашки под каймой
  букв). Это нормальный ответ геометрии, а не ошибка вызова: проверь снимком, виден ли угол снаружи.
- **Фаска на почти касательном стыке может ДОСТРОИТЬ объём, а не срезать.** Замер: `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")`, там у каждого свой габарит, и сверь объём с прикидкой.

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

Опорный сценарий построения, проверен 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» нечитаемо ни человеку, ни тебе самому
через сотню вызовов.

## Параметризация: сначала переменные, потом геометрия

**В новом документе первым делом опиши будущую модель переменными — до первого эскиза.** Пока
деталь пуста, компоновка стоит одного вызова на размер; после десятка операций та же мысль стоит
пересборки. Набор переменных — это план построения числами и паспорт, по которому человек поймёт
модель, не разбирая дерево.

- **Заводи переменной то, что было РЕШЕНИЕМ** (габариты из ТЗ, толщины, зазоры), позиции, подобранные
  замером, оставляй числами; **размер передавай выражением прямо в операцию**
  (`extrude(depth="badge_T")`) — переменная должна существовать ДО операции.
- **После связывания правка паспорта перестраивает деталь; до связывания — нет**, и `set_variable`
  прямо говорит «⚠ НИЧЕГО НЕ ВЕДЁТ» в этом случае — не успех, хоть число и поменялось.
- **Сверка и уборка в конце:** `describe_model(sections=variables)` помечает «⚠ ничего не ведёт»;
  `delete_variable(unused=true)` не трогает справочные (`information`) и внешние.

Полная методика — обязательные поля (`note`), как сервер ловит промахи в формулах, справочные
переменные `(ТЗ)` и порядок уборки — [reference/parametrization.md](reference/parametrization.md).

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

Надпись — примитив `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):
  убедиться, что срослось, можно только `describe_model(sections="bodies")`.
- **Рельеф = разница глубин от одной плоскости** (основание 2 мм + буквы 3 мм = выступ 1 мм);
  не строй буквы «на грани основания» — из одного эскиза на базовой плоскости получается и то и
  другое, и рельеф не зависит от порядка операций.
- **Надпись читается только с той стороны, куда смотрит нормаль плоскости эскиза** — XOY → +Z,
  XOZ → +Y, **YOZ → −X**. Гравировка по эскизу на YOZ, положенная на грань с бОльшим X, выходит
  ЗЕРКАЛЬНОЙ, и `angle` этого не исправляет: он вращает, а не отражает (замер — цифра на щеке
  X=20.4 зеркальна при любом угле, тот же эскиз на X=0 встаёт верно). Выбирайте грань по нормали,
  а поворотом задавайте только, куда смотрит верх глифа. Проверять — снимком С ТОЙ СТОРОНЫ, где
  надпись будет видна: `model_snapshot(view=left)` для грани X=0, `right` для X=max.
- **Шрифт должен быть установлен в системе** — неизвестное имя КОМПАС молча подменяет; сервер
  предупреждает об этом в ответе `sketch_create`/`measure_text` — не игнорируй.

**Логотип (SVG) и выбор маршрута для внешнего контура (вычисляемый / срисованный / CAD-файл) —
в [reference/text-and-relief.md](reference/text-and-relief.md).** Там же — точная подгонка (кегль
под заданную ширину, ступени `widthFactor`/`height`, приросты каймы на острых терминалах, разрядка
пробелами, кайма вокруг прямоугольной плашки) и отделка рельефа (скругления/фаски на сотнях рёбер).
Прочитай его, как только контур не сводится к простому вычисляемому эскизу.

Фрагмент (*.frw, самостоятельный файл переиспользуемого контура/чертежа) —
[reference/fragments.md](reference/fragments.md).

## Сборка: собрать своё

Плейбук: **создать → вставить → ЗАФИКСИРОВАТЬ базовую → сопрячь → rebuild → проверить.**
Сборка с нуля целиком, с адресацией граней, семью типами сопряжений и порядком проверки —
[reference/assembly-playbook.md](reference/assembly-playbook.md). Разбор чужой сборки (пришедшей
STEP/импортом) — следующий раздел.

## Чертёж: оформить деталь по ГОСТ

Чертёж строится не так, как деталь: **авто-валидации здесь нет** — верность тут не про геометрию,
а про место на листе, и проверяется только просмотром. Порядок «формат → виды → координаты замером
→ разрез до размеров → простановка → `drawing_export_image`», разрез, три ловушки, на которых
чертёж молча выходит неверным (`viewNumber=0`, ассоциативность размеров, допуск без read-back), и
чего в 2D нет — [reference/drawing-playbook.md](reference/drawing-playbook.md).

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

Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт» для ЧУЖОЙ модели —
[reference/import-playbook.md](reference/import-playbook.md).

## Исполнения: одна модель — несколько геометрий

Типоразмеры, зеркала, версии с отверстием и без в одном файле — переключение равно смене документа
(хендлы гибнут), индексация и адресация в сборке, порядок «сначала геометрия, исполнения последним
шагом» — [reference/embodiments-playbook.md](reference/embodiments-playbook.md).

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

- **Правила 1 и 2 действуют всегда:** осмотр структурный; «⚠ N операц. в ошибке» — в STEP/печать
  не брать.
- **Направление операции** (`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 → −X**.
  Значит `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`.
  Не сочиняй их и не передавай числа: числовая адресация не поддерживается, а сервер объяснит формат
  отказом. Хендл живёт только в текущей сессии построения: смена активного документа
  (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` оставляй**, когда работа идёт на глазах у человека и ты единственный агент.
- **Один файл в двух экземплярах не открыть** — второй получит его только на чтение: работу делите
  по файлам, а не по вкладкам.

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

- **Параметрика работает через параметры ОПЕРАЦИЙ, а не координаты ВНУТРИ эскиза** — сдвинуть
  контур переменной нельзя, только пересобрать эскиз (`sketch_update`). Но это ограничение уже
  границей: **плоскость** эскиза — обычный узел дерева с параметром «Расстояние», и она
  параметризуется как всё остальное. Планируй членение так, чтобы изменяемое задавалось параметром
  операции (глубина, радиус, габарит примитива) или положением плоскости, а не координатами точек.
- **2D покрыт вместе с разрезом и сечением.** Есть виды (с выбором набора, ориентации главного и
  невидимых линий), разрез/сечение, листы, штамп, размеры с допусками, осевые, обозначения,
  техтребования, удаление и сдвиг объекта, вывод в растр — методика в §«Чертёж». Нет выносного
  элемента, местного разреза внутри вида, местного вида и вида с разрывом.
- **Разрез не переживает правку модели, если он не первый на своём базовом виде.** Замерено:
  обновляется только ПЕРВЫЙ, остальные молча остаются со старой геометрией, и ни одно перестроение
  этого не чинит. Порядок один: сначала модель, потом разрезы.
- **Вставку фрагмента правят только целиком** (заново `fragment_place`). Экспорт наружу — растр и
  STEP; DXF/DWG и PDF не пишутся.
- **SVG сервер не читает** — и не будет: разбор путей, деление кривых Безье на дуги и разбор
  вложенности контуров живут во внешнем конвертере, а серверу достаётся готовый список примитивов.

## Связанное

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