From 362fea4d54e1eeb681694b11f25097cec35b68d3 Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Tue, 26 May 2026 21:06:34 +0300 Subject: [PATCH] =?UTF-8?q?docs(spec):=20=D0=B4=D0=B8=D0=B7=D0=B0=D0=B9?= =?UTF-8?q?=D0=BD=20=D0=BF=D0=B0=D0=BA=D0=B5=D1=82=D0=B0=20A=20=E2=80=94?= =?UTF-8?q?=20=D0=B1=D0=BE=D0=B3=D0=B0=D1=87=D0=B5=20=D1=8D=D1=81=D0=BA?= =?UTF-8?q?=D0=B8=D0=B7=D1=8B=20(=D0=BF=D1=80=D0=B8=D0=BC=D0=B8=D1=82?= =?UTF-8?q?=D0=B8=D0=B2=D1=8B=202D)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 7 новых MCP-инструментов эскиза: дуга (3 точки / центр+углы), эллипс, ломаная, правильный многоугольник, сплайн (NURBS), точка. Тонкие обёртки над ksDocument2D; param-структуры через GetParamStruct. Рефакторинг PartModeler в partial class (Sketch/Features). Сигнатуры COM сверены по docs/Kompas3D_SDK/. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-05-26-sketch-primitives-design.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-26-sketch-primitives-design.md diff --git a/docs/superpowers/specs/2026-05-26-sketch-primitives-design.md b/docs/superpowers/specs/2026-05-26-sketch-primitives-design.md new file mode 100644 index 0000000..7503565 --- /dev/null +++ b/docs/superpowers/specs/2026-05-26-sketch-primitives-design.md @@ -0,0 +1,128 @@ +# Дизайн: пакет A — богаче эскизы (примитивы 2D) + +**Дата:** 2026-05-26 +**Статус:** одобрен к реализации +**Контекст:** kompas3d-mcp — MCP-сервер для КОМПАС-3D через COM API (.NET 8, C#). + +## Цель + +Расширить набор примитивов эскиза. Сейчас профиль ограничен отрезком, окружностью, +прямоугольником и осевой линией (`sketch_add_line/circle/rectangle/axis`) — без дуг и +кривых недоступна масса реальных профилей. Добавляем **7 инструментов**: дугу (двумя +способами), эллипс, ломаную, правильный многоугольник, сплайн и точку. + +Это первый из приоритизированных пакетов расширения MCP (см. анализ функций от 2026-05-26: +пакеты A — эскизы, B — формообразующие, C — массивы, D — параметрика). Выбран пакет A. + +## Не входит в объём (YAGNI) + +- Параметрические ограничения и размеры эскиза (отдельный крупный пакет). +- Скругление/фаска углов эскиза (`pCorner` у многоугольника не используем). +- Выставление `degree` сплайна наружу — фиксируем кубический (degree=3). +- Видимые точки-маркеры — точка только вспомогательная (конструктивная). + +## Сигнатуры COM (подтверждены по `docs/Kompas3D_SDK/`) + +Все методы — на интерфейсе `ksDocument2D` (API5), вызываются на редакторе открытого +эскиза (`def.BeginEdit()` → `ksDocument2D`). Углы **в градусах**. Стиль линии `1` = +«основная» (`ksCSNormal`). Каждый метод возвращает `long`: `0` — ошибка. + +``` +long ksArcBy3Points(double x1,y1, x2,y2, x3,y3, long style) +long ksArcByAngle(double xc, yc, rad, f1_град, f2_град, short direction(1=CCW|-1=CW), long style) +long ksEllipse(LPDISPATCH ksEllipseParam) // xc,yc,a,b,angle(град),style +long ksRegularPolygon(LPDISPATCH ksRegularPolygonParam, short centre=0) + // count,xc,yc,ang(град),radius,describe(BOOL),style +long ksNurbs(short degree, BOOL close, long style) // открыть; degree=3 кубический +long ksNurbsPoint(LPDISPATCH ksNurbsPointParam) // x,y,weight=1.0 — на каждый узел +long ksEndObj() // завершить NURBS +long ksPoint(double x, y, long style) // style=0 — вспомогательная +long ksLineSeg(double x1,y1, x2,y2, long style) // уже используется — для polyline +``` + +**Param-структуры** (`ellipse`/`polygon`/`spline`) берутся через +`KompasObject.GetParamStruct(...)` (`_session.Kompas`), заполняются, передаются в метод и +**освобождаются** `ComHelper.Release` — по дисциплине COM-lifetime проекта. Это новый для +`PartModeler` паттерн (раньше — только прямые методы вроде `ksLineSeg`/`ksCircle`). + +Стиль точки: `0` — вспомогательная (конструктивная опора, без маркера). + +## Новые MCP-инструменты (группа Sketch) + +Контракт инструментов (обёртки в `SketchTools`, как существующие `sketch_add_*`; +возвращают строку-подтверждение, id не возвращают): + +| Инструмент | Параметры | COM | +|---|---|---| +| `sketch_add_arc_3points` | `sketchId, x1,y1, x2,y2, x3,y3` | `ksArcBy3Points(..., 1)` | +| `sketch_add_arc` | `sketchId, centerX, centerY, radius, startAngle, endAngle, counterClockwise=true` | `ksArcByAngle(xc,yc,rad,f1,f2,dir,1)` | +| `sketch_add_ellipse` | `sketchId, centerX, centerY, semiMajor, semiMinor, angle=0` | `ksEllipse(param)` | +| `sketch_add_polyline` | `sketchId, points:[{x,y}…], closed=false` | цепочка `ksLineSeg(...,1)` | +| `sketch_add_polygon` | `sketchId, centerX, centerY, vertexCount, radius, inscribed=true, angle=0` | `ksRegularPolygon(param, 0)` | +| `sketch_add_spline` | `sketchId, points:[{x,y}…], closed=false` | `ksNurbs(3,close,1)` → `ksNurbsPoint`×N → `ksEndObj()` | +| `sketch_add_point` | `sketchId, x, y` | `ksPoint(x,y,0)` | + +### Маппинги контракт → COM + +- `counterClockwise=true → direction=1`, `false → direction=-1`. +- `inscribed=true → describe=false` (вершины на окружности `radius`); + `inscribed=false → describe=true` (стороны касаются окружности). +- `closed → ksNurbs(close=TRUE)` / для polyline замыкающий `ksLineSeg` от последней к первой. +- Сплайн: `degree=3`, на каждый узел `ksNurbsPoint` с `weight=1.0`; узловой вектор не + задаём (КОМПАС строит автоматически). + +### Формат списка точек + +`points` — массив объектов `{x, y}` (double). Самодокументируемая JSON-схема, меньше +ошибок у LLM (порядок координат явный). Координаты — в плоскости эскиза, мм. + +## Валидация (до COM-вызова) + +Бросаем `ArgumentException`/`ArgumentOutOfRangeException`: +- `radius > 0`, `semiMajor > 0`, `semiMinor > 0`; +- `vertexCount >= 3`; +- `polyline.points.Length >= 2`; +- `spline.points.Length >= 2`. + +Возврат COM-метода `0` (или `ksEndObj() == 0` для сплайна) → `InvalidOperationException` +с понятным текстом (паттерн `ksLineSeg вернул 0`). + +## Структура кода + +`PartModeler` (сейчас 443 строки) совмещает эскизы и операции; 7 новых методов раздуют +эскизную часть. Разбиваем на **partial class**, сохраняя публичный класс, DI и общий +реестр id: + +- `PartModeler.cs` — поля, реестры `_sketches`/`_features`, helpers (`GetTopPart`, + `RequireSketch`/`RequireOpenSketch`, `SelectEdgeBy*`), `ResetCore`/`Dispose`. +- `PartModeler.Sketch.cs` — создание эскиза (`OpenSketch*`, `CreateSketchOn`), все + примитивы (`AddLine/Circle/Rectangle/Axis` + 7 новых), `CloseSketch*`. +- `PartModeler.Features.cs` — `ExtrudeAsync`/`RevolveAsync`/`CreateFillet`/`CreateChamfer`/ + `RebuildAsync`. + +Операции по-прежнему берут `sketch.Entity` из общего `_sketches` — реестр не делится. +Это targeted-улучшение «по ходу работы», контракт не меняется. + +## Тестирование + +**Unit** (`Category=Unit`, без COM): валидации параметров; маппинги +`counterClockwise→direction` и `inscribed→describe`. (Координат вершин многоугольника +вручную не считаем — метод нативный.) + +**Integration** (`Category=Integration`, `KompasFixture`): для каждого профилирующего +примитива — открыть эскиз → добавить примитив(ы), образующие замкнутый контур → +`extrude_boss` → проверить правдоподобный объём: +- `polygon`: правильный 6-угольник, `radius=10`, `extrude=5` → объём > 0, согласуется с + площадью правильного шестиугольника. +- `ellipse`: `semiMajor=10, semiMinor=5, extrude=4` → V ≈ π·a·b·h. +- `arc_3points` / `arc`: дуга + замыкающий отрезок (хорда) → замкнутый сегмент → V > 0. +- `polyline`: треугольник из 3 точек, `closed=true` → V > 0. +- `spline`: замкнутый сплайн по 4+ точкам → V > 0. +- `point`: вызов не падает, эскиз остаётся валидным (точка контур не образует — без + проверки объёма). + +## Влияние на документацию + +После реализации обновить (через навык `docs-delegate`): счётчики инструментов/тестов и +перечни в `CLAUDE.md`, `README.md`, `docs/ARCHITECTURE.md`; пометить пакет A выполненным в +анализе пробелов. Память `kompas-step-and-assembly-api` не затрагивается.