kompas 0.4.0 (из f1ecc6ff5a923d524a7aa8dc7b97c538d9cf1bb3)

2026-10-15 03:15:33 +00:00
parent 94e044bd03
commit 0720fd7397
22 changed files with 208 additions and 106 deletions
@@ -5,9 +5,10 @@ description: >
  модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии
  снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС
  через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать
-  сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
+  сборку, померить, раскрасить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
  проверенные на практике. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
-  «что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели».
+  «что в этой сборке», «нарасти/измени деталь», «раскрась модель / выдели надпись цветом», «экспортируй STEP»,
+  «сделай снимок модели».
 ---

 # kompas-3d — методика управления КОМПАС-3D через MCP
@@ -74,7 +75,7 @@ variables | errors | components` (`sections` сужает и ответ, и об
  и счётчик граней законно остаётся прежним.
  **Но обратное неверно: «Тел: 1» распад не опровергает.** Счётчик в сводке ОПАЗДЫВАЕТ. Замер
  (журнал операций кейса с хвостом по сечениям): `loft` построил второе тело и отчитался
-  «Тел: 1», следом `mirror` — снова «Тел: 1», и только третья операция, `chamfer_edge`, напечатала
+  «Тел: 1», следом `pattern(kind=mirror)` — снова «Тел: 1», и только третья операция, `chamfer_edge`, напечатала
  «Тел: 2», хотя между ними ничего не создавалось. Три операции подряд шли по детали, объём
  которой считал пересечение дважды. Поэтому «Тел: 2» — тревога, которой верят сразу, а «Тел: 1» —
  не доказательство: там, где важно именно СРАСТАНИЕ (loft/sweep на грань, надпись, примитив
@@ -95,7 +96,7 @@ variables | errors | components` (`sections` сужает и ответ, и об
  `help(topic="build-verification")`.

 Отдельный `describe_model(sections=errors,bodies,mass)` после каждого шага не нужен. Он
-возвращается, когда авто-проверку выключили (`set_auto_validate(false)` на тяжёлой модели, где
+возвращается, когда авто-проверку выключили (`kompas_connect(autoValidate=false)` на тяжёлой модели, где
 проверка каждого шага тормозит): тогда `describe_model(sections=errors,bodies,mass)` вручную перед выдачей: одного
 `errors` мало — распад детали на два тела показывает только раздел `bodies`.

@@ -116,8 +117,8 @@ variables | errors | components` (`sections` сужает и ответ, и об

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

-Полный перечень 86 инструментов с параметрами — README плагина §«Инструменты» (единый источник
-правды, держать вторую копию здесь не нужно) или `tools/list` самого MCP-сервера. Что известно про
+Полный перечень инструментов с параметрами — `tools/list` самого MCP-сервера (единый источник
+правды, держать вторую копию здесь не нужно). Что известно про
 КОНКРЕТНЫЙ инструмент — `help(tool="extrude")`. Три сквозных свойства контракта, которые полезно
 держать в голове, а не искать заново на каждом инструменте: **размерный параметр принимает число ИЛИ выражение** (имя
 переменной/формулу — параметр сразу становится ведомым); **объект выбирается индексом** (надёжно)
@@ -179,7 +180,7 @@ variables | errors | components` (`sections` сужает и ответ, и об
  причины, значит фаска выродилась в достройку: убери её `feature_delete`, пологому стыку она
  и не нужна.
 - **`result=new` даёт ОТДЕЛЬНОЕ тело**, `subtract` мимо цели сервер ловит сам — и то и другое
-  видно по сводке «Тел/объём» в ответе; при распаде зови `boolean_union`.
+  видно по сводке «Тел/объём» в ответе; при распаде зови `boolean`.
 - **Сужающуюся или изогнутую форму не набирай лесенкой из примитивов.** `primitive` не умеет
  поворота, и «хвост» из десятка блоков со ступеньками — это обход отсутствующего инструмента,
  а не решение: он и печатается хуже, и правится только целиком. Бери `loft` по 4–6 сечениям на
@@ -197,7 +198,7 @@ variables | errors | components` (`sections` сужает и ответ, и об

 Опорный сценарий построения, проверен end-to-end:

-1. `kompas_connect` (+ `kompas_set_visible true`). **Работаешь не один — бери свой экземпляр:**
+1. `kompas_connect` (+ `visible=true`). **Работаешь не один — бери свой экземпляр:**
   `kompas_connect(instance="private")` (см. «Когда КОМПАС общий»).
 2. `document_create(type="part", name="…")` — наименование даём сразу, здесь оно ничего не стоит.
 3. **Запиши замысел переменными** до первого эскиза (см. «Параметризация») и связывай каждый
@@ -206,7 +207,7 @@ variables | errors | components` (`sections` сужает и ответ, и об
 5. `extrude` / `revolve` → прочитай итог проверки и сводку прямо в ответе (правило 2).
 6. Осмотр — структурно: `describe_model` (нужен кусок — `sections="box,mass"`).
 7. Итерация «на грани»: `list_faces` → `sketch_create(faceIndex=N, entities=[…])` → операция.
-8. **Задай материал, если смотришь на массу** — `set_part_material`: у нового документа стоит
+8. **Задай материал, если смотришь на массу** — `set_part_info(material, density)`: у нового документа стоит
   сталь 7.86, и МЦХ печатной детали завышена вшестеро; плотности ходовых материалов перечислены
   в описании инструмента.
 9. **Проверь, что деталь названа** (шаг 2 или `set_part_info`) — безликая «Деталь» уедет в штамп
@@ -230,6 +231,27 @@ variables | errors | components` (`sections` сужает и ответ, и об
  прямо говорит «⚠ НИЧЕГО НЕ ВЕДЁТ» в этом случае — не успех, хоть число и поменялось.
 - **Сверка и уборка в конце:** `describe_model(sections=variables)` помечает «⚠ ничего не ведёт»;
  `delete_variable(unused=true)` не трогает справочные (`information`) и внешние.
+- **Проверь крайние значения переменных ДО прогона.** Размер, зависящий от модуля или шага, но
+  заданный числом, ломает модель на соседнем значении (обод Ø178 при m=4 оказывается шире
+  вершин Ø172 — профиль самопересекается). Веди такие размеры от той же переменной.
+- **Галтель, скругление угла профиля** — примитив `{type:"fillet", between:[i, j], radius}` на
+  острый угол двух отрезков или дуг: точное сопряжение находит решатель КОМПАС, считать точки
+  касания не нужно (`help(topic="sketch-entities")`). Радиус ведёт переменная — `radius` на номер
+  `fillet` в `dimensions`. Если две галтели по данным сходятся в одну (центр уходит за ось
+  симметрии, дуги дна между ними нет) — один `fillet` прямо между двумя боковыми дугами.
+- **Паз со сбегом по дуге** (выход дисковой фрезы): прорежь паз `extrude(cut)` с перебегом за
+  место сбега, затем верни лишнее `revolve(boss)` профиля, ограниченного дугой сбега, вокруг оси
+  вала; либо `revolve(cut)` сечения паза вокруг оси фрезы. У `extrude` нет переменного дна.
+- **Фаски и скругления на кромках зубчатого венца — ДО нарезки зубьев:** одно круговое ребро
+  заготовки вращения вместо десятков рёбер после массива (иначе их перечисляют индексами).
+- **Профиль вала вдоль Z рисуется на XOZ вниз от оси X:** точка (r; −z) — локальная v эскиза
+  смотрит в −Z (`help(topic="sketch-dimensions")`). Адресуя потом рёбра и грани точками, бери
+  мировые z ≥ 0, а не координаты эскиза.
+- **Формулы:** тригонометрия в РАДИАНАХ, константы π нет — заведи `dg = 0.017453292519943295` и
+  пиши `cos(alpha*dg)`; в формуле регистр имени значим, а `spl_d` и `spl_D` — одна переменная.
+- **Связь — в эскизе, а не в калькуляторе** (точную начальную точку дай выражением прямо в координате): точка на кривой (`coincident`, `to.point: "curve"`),
+  касание (`tangent`), расстояние до прямой (`distance`), угол к оси (`angle` с `to.ref`), опоры
+  вне профиля — `construction: true`. Что выражено ограничением, переживает смену переменной.

 Полная методика — обязательные поля (`note`), как сервер ловит промахи в формулах, справочные
 переменные `(ТЗ)` и порядок уборки — [reference/parametrization.md](reference/parametrization.md).
@@ -277,6 +299,51 @@ variables | errors | components` (`sections` сужает и ответ, и об
 Фрагмент (*.frw, самостоятельный файл переиспользуемого контура/чертежа) —
 [reference/fragments.md](reference/fragments.md).

+## Раскраска: умеренно и по смыслу
+
+Цвет — последний шаг, после геометрии: `set_appearance` её не трогает и в дереве узлов не
+плодит. Задача раскраски — чтобы модель читалась с первого взгляда, а не чтобы она была пёстрой.
+
+- **Одна основа, один-два акцента.** Деталь целиком — спокойный нейтральный цвет
+  (`target="part"`), акцент — тому, что должно бросаться в глаза: надпись, логотип, кнопка,
+  посадочная поверхность. Три и больше акцентов уже шумят.
+- **Надпись и логотип красятся ОПЕРАЦИЕЙ**, которая их выдавила
+  (`target="feature", ids=["op_…"]`): так окрашиваются и лицевые грани, и стенки букв. Хендл
+  берётся из ответа `extrude`; если хендлов уже нет — индекс узла из
+  `describe_model(sections=tree)`. Красить только верх букв — `target="face"` пакетом индексов.
+- **Порядок: сначала общее, потом частное.** Своё перекрывает унаследованное в порядке
+  грань > операция > тело > деталь, так что поздний цвет детали акценты не затрёт.
+- **Проба и откат**: объект, который до пробы наследовал вид, возвращают `reset=true`, а не
+  обратным значением — запись даже одной `opacity` закрепляет за ним и цвет («⚠ Цвет закреплён» в
+  ответе). Если вид был свой, откат — прежние значения из «было → стало» ответа.
+- **Сборка — компонент на свой цвет**, близкие по назначению — близкими оттенками; корпус,
+  сквозь который надо видеть внутренности, — `opacity` 0.3–0.5. Цвет компонента живёт в сборке,
+  файл детали не меняется — но он перекрывает ВСЕ акценты детали (надпись станет цвета
+  компонента). Нужны акценты — оставь компоненту наследуемый цвет. Грань или тело ВНУТРИ
+  компонента из сборки не красятся: акценты, общие для всех экземпляров, задают в файле детали.
+- **Передача дальше**: STEP несёт цвета и прозрачность — ответ `export_model` их перечисляет; STL
+  цветов не несёт.
+- **Отделка по материалу**: металл — `finish="metal"` (`silver`, `gold`), пластик — `satin` или
+  `matte`, `glossy` — умолчание КОМПАС.
+- **Текстура — там, где она что-то говорит**: накатка на рукоятке (`texture="diamond knurl"`,
+  `textureSize` 3–10 мм — при умолчании 100 узор не виден), дерево, шлифованный металл, сварной
+  шов. Размер — плитка в мм модели; проверка снимком (текстуры он рисует). Текстура операции
+  ложится на ВСЕ её грани, торец рукоятки тоже — накатку как у эталона ASCON кладут на боковую
+  грань (`target="face"`). Своя картинка — это ссылка на файл: модель её не хранит, предпочитай
+  библиотеку КОМПАС.
+- **Перфорация и сетка — вырезом, а не геометрией**, если отверстия нужны только для вида:
+  `cutout="hexagon"` (или `expanded metal` вместе с одноимённой текстурой) делает окна сквозными
+  на снимке, не трогая массу и топологию. Нужны настоящие отверстия под крепёж или DFM — это
+  `hole`/`pattern`, вырез их не заменяет. Рисунок «не тем боком» — `textureAngle`, сдвиг —
+  `textureOffset` (оба вместе с повтором имён `texture` и `cutout` — повернётся только то, что
+  названо в вызове; поворот 0…180°). Смена рисунка плитку и раскладку сохраняет. В STEP уходят
+  только цвета — текстуры и вырезы остаются в `.m3d`.
+- **Проверка — глазами**: `model_snapshot(view="iso")` после раскраски; что окрашено на самом
+  деле — `describe_model(sections=appearance)`. Прозрачность снимок не рисует — её видно только
+  в разделе `appearance`.
+
+Механизм, имена цветов и измеренные факты — `help(topic="appearance")`.
+
 ## Сборка: собрать своё

 Плейбук: **создать → вставить → ЗАФИКСИРОВАТЬ базовую → сопрячь → rebuild → проверить.**
@@ -315,7 +382,11 @@ STEP/импортом) — следующий раздел.
  `extrude(mode=cut, forward=true)` режет ВНИЗ, в тело. То есть у выреза «прямое» — это внутрь
  материала. Оба умолчания делают то, чего обычно и хотят, но рассуждение «forward — это плюс
  нормали» даст перевёрнутый карман. **Вырез, ушедший в пустоту, КОМПАС считает успехом** —
-  дерево чистое, объём не изменился; ловит это только строка сверки в ответе.
+  дерево чистое, объём не изменился; ловит это только строка сверки в ответе. Поэтому у
+  `extrude`/`revolve(mode=cut)` **не задавай `forward`, если сторона неочевидна**: сервер сам
+  переделает вырез, не убравший материала, в обратную сторону и скажет об этом в ответе.
+  Выбор работает, только если одна сторона пуста: эскиз ВНУТРИ материала (плоскость посреди вала)
+  режет в обе стороны — там `forward` задавай сам и сверяй объём.
 - **На YOZ деталь растёт в МИНУС X, и туда же уезжает смещение плоскости.** Нормаль базовой
  плоскости смотрит в плюс своей оси не всегда — замерено: XOY → +Z, XOZ → +Y, а **YOZ → −X**.
  Значит `extrude(forward=true)` по эскизу на YOZ кладёт материал в отрицательные X, а
@@ -341,7 +412,7 @@ STEP/импортом) — следующий раздел.
  Хендл — это НЕ индекс: `faceIndex`/`edgeIndices` из `list_faces`/`list_edges` и параметр
  `feature` у `link_parameter`/`list_parameters` (имя или индекс узла дерева) остаются числовыми.
  `primitive` и `hole` тоже возвращают хендл (у `hole` — по одному на КАЖДОЕ отверстие серии),
-  так что примитив и отверстие можно удалить `feature_delete` и размножить `pattern`/`mirror`.
+  так что примитив и отверстие можно удалить `feature_delete` и размножить `pattern` (и `kind=mirror`).
  Если ответ вместо хендла говорит «выдать не удалось» — операция построена, но адресовать её
  нечем: переставить её потом можно только пересборкой.
 - **Единицы — мм** (геометрия) и **кг** (масса). Локальные координаты эскиза ≠ мировые координаты
@@ -362,7 +433,7 @@ STEP/импортом) — следующий раздел.
 сохранения.

 - **Строишь параллельно с кем-то — `instance="private"`** при первом `kompas_connect` (потом режим
-  не сменить). Свой экземпляр: активный документ только твой, окно скрыто (`kompas_set_visible true`
+  не сменить). Свой экземпляр: активный документ только твой, окно скрыто (`kompas_connect(visible=true)`
  покажет).
 - **`shared` оставляй**, когда работа идёт на глазах у человека и ты единственный агент.
 - **Один файл в двух экземплярах не открыть** — второй получит его только на чтение: работу делите
@@ -370,11 +441,12 @@ STEP/импортом) — следующий раздел.

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

- **Параметрика работает через параметры ОПЕРАЦИЙ, а не координаты ВНУТРИ эскиза** — сдвинуть
-  контур переменной нельзя, только пересобрать эскиз (`sketch_update`). Но это ограничение уже
-  границей: **плоскость** эскиза — обычный узел дерева с параметром «Расстояние», и она
-  параметризуется как всё остальное. Планируй членение так, чтобы изменяемое задавалось параметром
-  операции (глубина, радиус, габарит примитива) или положением плоскости, а не координатами точек.
+- **Координата в точке — число или выражение (считается один раз), а форму контура ведут `dimensions`** с выражениями
+  (`help(topic="sketch-dimensions")`). Уже наложенный размер перепривязывается без пересборки:
+  `link_parameter(feature=<узел эскиза>, parameter="v15")` — имя `vNN` есть в ответе
+  `sketch_create` и в `list_parameters` (у одноимённых «Линейный размер» — в скобках). Эскиз без
+  размеров переменной не двигается — только пересборкой (`sketch_update`); положение эскиза задаёт
+  **плоскость** — обычный узел с параметром «Расстояние».
 - **2D покрыт вместе с разрезом и сечением.** Есть виды (с выбором набора, ориентации главного и
  невидимых линий), разрез/сечение, листы, штамп, размеры с допусками, осевые, обозначения,
  техтребования, удаление и сдвиг объекта, вывод в растр — методика в §«Чертёж». Нет выносного
@@ -13,12 +13,12 @@
   ГОСТ не выйдет; планируешь чертёж — строй эскизы так, чтобы главный вид попадал на плоскость
   с наибольшей информацией.
 2. **`drawing_set_sheet_format`** (формат до видов — иначе виды придётся двигать), при
-   необходимости `drawing_add_sheet` для второго листа.
+   необходимости `drawing_set_sheet_format(add=true)` для второго листа.
 3. **`drawing_create_standard_views(views=[…], mainOrientation=…, hiddenLines=…)`** — бери ровно те
   проекции, которые нужны: лишний вид — лишнее место и лишний повод ошибиться видом. **Главный вид
   входит в набор сам**: перечисленные коды — это проекции ОТНОСИТЕЛЬНО него, поэтому `views=["top"]`
   даёт ДВА вида (главный и сверху). Ответ возвращает НОМЕРА видов, и дальше всё адресуется ими.
-4. **Координаты — замером, а не формулой.** `drawing_get_view_info(viewNumber)` отдаёт паспорт вида
+4. **Координаты — замером, а не формулой.** `describe_drawing(sections=view, viewNumber)` отдаёт паспорт вида
   одним вызовом: положение на листе, масштаб, габарит и — главное — локальную СК: куда попадает
   начало координат модели и куда смотрят её оси +X/+Y/+Z в координатах вида (нулевой орт = ось
   проекции, вдоль неё вид смотрит). Этого хватает, чтобы пересчитывать точки модели в вид
@@ -34,7 +34,7 @@
 6. **Размеры**, `drawing_add_axis` (осевые и центровые), шероховатость, выноски, техтребования,
   штамп. **Осевые сначала посмотри, потом добивай**: ассоциативные виды приходят со СВОИМИ
   центровыми и осевыми, которые КОМПАС ставит сам, и `drawing_add_axis` вслепую даёт дубли поверх
-   существующих. Сначала `list_drawing_objects(kind="axis"|"centreMarker", viewNumber=…)`.
+   существующих. Сначала `describe_drawing(kind="axis"|"centreMarker", viewNumber=…)`.
 7. **`drawing_export_image`** — посмотреть глазами. Пока картинки не было, чертёж не сдан.

 ## Разрез
@@ -48,16 +48,16 @@
  стенка полой детали. Невидимые линии — только намёк на то, что уже показано где-то ещё; размер к
  штриховой линии не привязывают.
 - **Веди линию с запасом за габарит** (плита 60 мм → от −40 до +40): линия по самому краю режет не
-  всю деталь. Координаты — в ЛСК БАЗОВОГО вида, её даёт `drawing_get_view_info`.
+  всю деталь. Координаты — в ЛСК БАЗОВОГО вида, её даёт `describe_drawing(sections=view)`.
 - **Строй разрез, когда модель готова**: после правки детали перестраивается только ПЕРВЫЙ разрез
  базового вида. Модель всё же изменилась — снеси разрезы и построй заново.
 - Сам разрез дальше — обычный вид: размеры и обозначения ставятся на него по его номеру.

 **Промах простановки лечится, а не остаётся навсегда.** Отката (undo) у чертежа нет, но
-`list_drawing_objects` показывает обозначения с индексами, `drawing_delete_object` убирает одно, а
+`describe_drawing` показывает обозначения с индексами, `drawing_delete(target=object)` убирает одно, а
 `drawing_move_object` его СДВИГАЕТ — слипшиеся тексты соседних размеров лечат именно сдвигом, а не
 заменой размера на выноску. Так же правится и компоновка: `drawing_move_view` переставляет вид со
-всеми обозначениями, `drawing_add_view` доносит недостающую проекцию, `drawing_delete_view` убирает
+всеми обозначениями, `drawing_create_standard_views(views=[])` доносит недостающую проекцию, `drawing_delete(target=view)` убирает
 лишнюю. Пересоздавать документ ради компоновки не нужно. Подробности адресации и порядок удаления —
 `help(topic="drawing-fixing")`.

@@ -27,6 +27,12 @@
  `embodiment(action="set", target="L600", component=N)` и затем `rebuild`. Сопряжения при этом
  **сохраняются** — пересоздание вставки, наоборот, порвало бы их все. Какие исполнения есть у
  конкретного экземпляра, показывает `describe_model(sections="embodiments", component=N)`.
+- **Исполнения, отличающиеся одним размером, — это переменная, а не правка дерева.** Значение
+  переменной каждое исполнение (и вариант) хранит СВОЁ: `set_variable` после `embodiment(add)`
+  меняет только текущее, у наследников выражение становится ссылкой на родителя
+  (`VCM.001|fit_h`). Отсюда приём: построй базу на переменных, затем `add` → `set_variable` в
+  каждом исполнении. Убрать элемент в исполнении часто проще значением, чем `feature_delete`:
+  цековка с `cb_d = hole_d` уходит в уже вырезанное.
 - **Выгнать всю линейку на печать** — `export_model(embodiment="all")`: каждое исполнение в свой
  файл с суффиксом обозначения.
 - **После смены исполнения в собранном узле проверь сопряжения** (`sections="mates"`): если у нового
@@ -11,11 +11,15 @@
 - **`local`** — вставка, переиспользуемая только внутри этого документа.
 - **`explode`** — россыпь обычных примитивов: правится по одному, но связи с файлом уже нет.

+**Имя вставки общее у вставок одного файла одного вида.** Вторая копия того же файла получает имя
+первой, и `name` второго вызова не применяется. Ответ `fragment_place` называет фактическое имя
+и прямо говорит, если запрошенное не легло. Нужны разные имена — кладите разные файлы.
+
 `angle` (градусы), `scale` и `mirror` задают размещение; зеркалить можно только вставку — у россыпи
 отражать нечего. **Зеркало отражает относительно вертикали через точку вставки**, поэтому контур
 уходит в другую сторону от неё: вставка в x=220 после `mirror` занимает 160…220, а не 220…280.

-Проверять результат — `list_drawing_objects`: он показывает состав по типам, габарит и все вставки
+Проверять результат — `describe_drawing`: он показывает состав по типам, габарит и все вставки
 с их файлами. Вставка, чей файл потерялся, рисуется пустым местом — в списке она помечена
 недействительной, и это единственный способ отличить её от удавшейся, не глядя на экран.

@@ -38,7 +38,7 @@
   | «сдвинуть грань на N мм» | `move_face` | это он и есть |
   | «диаметр отверстия (бобышки) должен стать D» | **`resize_face`** | задаётся ДИАМЕТР, ось не двигается; `move_face` сдвинул бы стенку на (D−d)/2, и это пришлось бы считать самому |
   | «грань должна встать НА объект: на плоскость, на грань соседнего тела» | **`replace_face`** | расстояние считает КОМПАС; `move_face` требует вычислить его заранее |
-   | вставка N мм в призматическую ножку | `split_solid_by_plane` → `move_body` → `move_face` (мост) → `boolean_union` | цепочка проверена end-to-end: проставка 39.45 → 41.45 мм |
+   | вставка N мм в призматическую ножку | `split_solid_by_plane` → `move_body` → `move_face` (мост) → `boolean` | цепочка проверена end-to-end: проставка 39.45 → 41.45 мм |

   `resize_face` и `replace_face` требуют КОМПАС v25; на версиях старше они отвечают отказом с
   номером установленной версии, и тогда остаётся `move_face` с арифметикой.
@@ -15,10 +15,39 @@
  становится ведомым, внутреннее имя параметра («Расстояние 1») знать не нужно. Переменная должна
  существовать ДО операции — потому паспорт и заводят первым. Задним числом и для параметров,
  которых нет среди аргументов инструмента (углы уклона, второе направление), — `link_parameter`.
+- **Размер КОНТУРА — тоже выражением**, но не в координатах, а в `dimensions` у
+  `sketch_create`/`sketch_update`: ширина, длина отрезка, Ø/R, а с `to` — расстояние между точками
+  (шаг отверстий, отступ от края) и угол между отрезками. Координаты достаточно нарисовать
+  примерно — контур встанет по значению сразу.
+- **Эскиз определён полностью, только когда привязан к модели.** Форма — размерами, положение —
+  от начала координат и осей: `to:{ref:"origin"}` (расстояние от базовых плоскостей, угол или
+  центр в начало через `coincident`), `coincident` с `ref:"xAxis"|"yAxis"` (точка на оси),
+  `symmetric` с `axis` (деталь симметрична оси — ширина растёт в обе стороны). Порядок для
+  каждого эскиза: **(1) где он стоит** — привязка к началу координат/осям; **(2) форма** — все
+  длины, радиусы, углы; **(3) взаимное положение** элементов — от привязанного контура или от
+  оси. Симметричную деталь строй симметрично оси модели: тогда её плоскости симметрии совпадают с
+  базовыми, и следующие эскизы привязываются к тем же осям. Нужна симметрия на уровне грани —
+  ставь эскиз не на грань, а на базовую плоскость со смещением (`offset`): у грани осей модели нет.
+- **Читай хвост ответа.** «полностью определён» без строки «Закреплено там, где нарисовано» —
+  цель. Строка «Закреплено…» значит, что положение держит закреплённая сервером точка, а не
+  привязка: добавь `ref`. «⚠ НЕДООПРЕДЕЛЁН» — часть контура свободна и сдвинется при смене
+  переменной: допиши размер (чаще всего радиус дуги, угол наклонного отрезка или вторую ось
+  положения). Отказ «размер ЛИШНИЙ» — величина уже следует из других (касание, сшивка, симметрия)
+  — убери один. Поля, правила опоры и пример VESA — `help(topic="sketch-dimensions")`.
 - **Промахи сервер ловит сам:** ссылка на несуществующее имя — отказ с перечнем виновных (и в
-  выражениях операций, и в `set_variable`; регистр значим), функции в формулах — предупреждение
+  выражениях операций, и в `set_variable`), функции в формулах — предупреждение
  (тригонометрия в радианах, разделитель аргументов «;», непонятая запись = молчаливый 0).
-  Твоя часть — **сверить вычисленные значения из ответа со своей прикидкой**.
+  Имена: в ФОРМУЛЕ регистр значим (`aq` не найдёт `Aq`), а две переменные, различающиеся только
+  регистром, не уживаются — `spl_d` перезапишет `spl_D`. Константы π нет: заведи `dg =
+  0.017453292519943295` (градус в радианах) и пиши `sin(a*dg)`.
+- **Связь — ограничением, а не арифметикой.** Центр дуги на окружности — `coincident` с
+  `to.point: "curve"`; опора вне профиля (основная окружность, ось паза) — примитив с
+  `construction: true`; сторона «в 3.5 от оси под 22.5°» — `distance` до `origin` плюс `angle` к
+  оси. Так связь живёт в эскизе и переживает смену переменной; посчитанные числа — нет.
+- **Считает КОМПАС, а не ты:** связь — ограничением в эскизе, скругление — примитивом `fillet`,
+  точная начальная координата — выражением прямо в точке (`{"x": "rb*sin(phi*dg)"}`). Заводить
+  переменные-калькуляторы и переносить их значения в JSON не нужно. Твоя часть — **сверить
+  результат с прикидкой** (`sketch_describe`).
 - **`note` обязателен** и пишется по-русски, со смыслом и единицей; `(ТЗ)` в тексте по-прежнему
  полезен человеку, но для машины число из ТЗ метится ПРИЗНАКОМ:
  `set_variable([{name:"dish_r", expression:"90", note:"по ТЗ", information:true}])`. Комментарий
@@ -17,7 +17,7 @@ Zilla Slab): это порядок величины и форма зависим
 | **Пришла в CAD-формате**: файл от смежника | `import_drawing` (.dxf/.dwg) → фрагмент → `fragment_place` |

 **Обводка занимает сотни примитивов, и переписывать их в тело вызова незачем.** У `sketch_create`,
-`sketch_add` и `fragment_create` есть `entitiesFile` — путь к JSON того же формата, что `entities`;
+`sketch_update(mode=append)` и `fragment_create` есть `entitiesFile` — путь к JSON того же формата, что `entities`;
 сервер читает файл сам. Замер на эмблеме Volvo: SVG в 1.5 КБ даёт 96 примитивов (50 отрезков +
 46 дуг) и 9.5 КБ JSON; через `entitiesFile` это один вызов на одну строку аргументов, а эскиз
 строится за один заход. Оба параметра можно задать вместе — сначала `entities`, следом файл: