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 покрыт вместе с разрезом и сечением.** Есть виды (с выбором набора, ориентации главного и
  невидимых линий), разрез/сечение, листы, штамп, размеры с допусками, осевые, обозначения,
  техтребования, удаление и сдвиг объекта, вывод в растр — методика в §«Чертёж». Нет выносного