docs: assembly_add_component — класс СБОРКИ начат (71 инструмент, 138 тестов)

README/CLAUDE/ARCHITECTURE/OPEN_QUESTIONS/presentation.html: счётчики 70→71,
119→138; новая группа инструментов Assembly; ключевые факты AssemblyService
(workflow API7, эмпирика UpdatePlacement, RequireActiveAssembly, откат).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -39,7 +39,7 @@ src/Kompas.Mcp.Host/bin/Release/net8.0-windows/kompas-mcp.exe
 }
 ```
 
-## Инструменты (70 инструментов)
+## Инструменты (71 инструмент)
 
 | Группа | Инструменты |
 |---|---|
@@ -53,6 +53,7 @@ src/Kompas.Mcp.Host/bin/Release/net8.0-windows/kompas-mcp.exe
 | Query | `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components` |
 | Variables | `create_variable`, `set_variable`, `delete_variable` |
 | Conversion | `import_step`, `export_step` |
+| Assembly | `assembly_add_component` |
 | Validation | `validate_part` |
 
 ### Типовой сценарий
@@ -71,7 +72,7 @@ src/Kompas.Mcp.Host/bin/Release/net8.0-windows/kompas-mcp.exe
 ```
 src/Kompas.Mcp.Core/   COM-слой: STA-диспетчер, подключение, документы, эскизы/операции, конвертация, снимок, инспекция модели
 src/Kompas.Mcp.Host/   MCP-сервер (stdio) + определения инструментов
-tests/Kompas.Mcp.Tests/ 119 тестов: unit + integration (integration требуют КОМПАС)
+tests/Kompas.Mcp.Tests/ 138 тестов: unit + integration (integration требуют КОМПАС)
 libs/kompas-interop/   вендорские interop-сборки КОМПАС (из SDK Samples/Common)
 docs/                  архитектура, план, презентация, MD-база знаний SDK (Kompas3D_SDK/)
 usecases/              полигон обкатки подходов (в .gitignore); приёмы поднимаются в навык kompas-3d
@@ -90,7 +91,7 @@ dotnet test --filter "Category=Integration"   # только integration
 
 - **STA-поток** (`KompasDispatcher`) владеет всеми COM-вызовами — КОМПАС однопоточный STA.
 - Подключение через API5 `KompasObject` (`KOMPAS.Application.5`) → API7 `IApplication` (`ksGetApplication7`).
-- 3D строится через API5 `ksPart` (эскизы, выдавливание, вращение, скругление/фаска); снимок — `ksDocument3D.SaveAsToRasterFormat`. Прямое редактирование импортированной B-rep (`move_face`) — через API7 `IPart7.FindObjectsByPoint` + `FaceMover`. Структурный осмотр (`describe_model` и др.) — через `ModelInspectionService` (дерево операций via `ksPart.GetFeature()`, тела via `BodyCollection()`, переменные via `GetFeature().VariableCollection`, измерения via `ksMeasurer`). Управление переменными (`create_variable`, `set_variable`, `delete_variable`) — через `VariableService` (API5).
+- 3D строится через API5 `ksPart` (эскизы, выдавливание, вращение, скругление/фаска); снимок — `ksDocument3D.SaveAsToRasterFormat`. Прямое редактирование импортированной B-rep (`move_face`) — через API7 `IPart7.FindObjectsByPoint` + `FaceMover`. Структурный осмотр (`describe_model` и др.) — через `ModelInspectionService` (дерево операций via `ksPart.GetFeature()`, тела via `BodyCollection()`, переменные via `GetFeature().VariableCollection`, измерения via `ksMeasurer`). Управление переменными (`create_variable`, `set_variable`, `delete_variable`) — через `VariableService` (API5). Вставка компонента в сборку (`assembly_add_component`) — через `AssemblyService` (API7, `IParts7.AddFromFile` + `IPlacement3D`).
 - STEP импорт/экспорт — `IKompasDocument3D1.ConvertFromAdditionFormat`/`ConvertToAdditionFormat` через встроенный конвертер.
 - MCP — официальный C# SDK `ModelContextProtocol`, транспорт stdio, логи в stderr.
 

docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Архитектура MCP-сервера КОМПАС-3D (предлагаемый вариант)
 
-> Статус: **реализовано и работает** (v1+v2+STEP/assembly+direct-edit+inspection+package-A «богатые эскизы»+package-B «shell+rib+sweep+loft»+package-C «массивы и зеркало»+package-D start «переменные»+package-E «offset plane»+`hole`+`hole_counterbore`+`hole_countersink`+`hole_conic`+`draft`). Актуализировано по коду.
+> Статус: **реализовано и работает** (v1+v2+STEP/assembly+direct-edit+inspection+package-A «богатые эскизы»+package-B «shell+rib+sweep+loft»+package-C «массивы и зеркало»+package-D start «переменные»+package-E «offset plane»+`hole`+`hole_counterbore`+`hole_countersink`+`hole_conic`+`draft`+`assembly_add_component`). Актуализировано по коду.
 > Сопутствующий контекст по COM API КОМПАС — в [`../CLAUDE.md`](../CLAUDE.md).
 > Имена интерфейсов и перечислений сверены со справкой SDK по MD-базе знаний `docs/Kompas3D_SDK/` (навык `kompas-sdk-research`).
 
@@ -112,8 +112,8 @@ MCP client ──stdio──> Host (поток-пул, async)
 | Проект | Ответственность |
 |---|---|
 | **Kompas.Mcp.Host** | Точка входа. Сборка MCP-сервера (stdio), DI (в т.ч. `ConversionService`), логи в stderr, старт и владение STA-потоком, graceful shutdown. Определения инструментов по категориям (System / Documents / Sketch / Features / Query / Conversion). **Тонкий слой**: валидация аргументов → постановка задачи на STA-поток → форматирование результата/ошибки в MCP-ответ. |
-| **Kompas.Mcp.Core** | COM-слой. Менеджер соединения, менеджер документов, построитель эскизов и операций, `ConversionService` (STEP импорт/экспорт), `QueryService` (МЦХ, грани, рёбра, компоненты), `ModelInspectionService` (дерево операций, тела, переменные, drill-down, измерения), снимок. Все паттерны API5/API7 живут здесь. |
-| **Kompas.Mcp.Tests** | Юнит (без COM) + интеграционные (требуют КОМПАС). 119 тестов (69 unit + 50 integration). |
+| **Kompas.Mcp.Core** | COM-слой. Менеджер соединения, менеджер документов, построитель эскизов и операций, `ConversionService` (STEP импорт/экспорт), `QueryService` (МЦХ, грани, рёбра, компоненты), `ModelInspectionService` (дерево операций, тела, переменные, drill-down, измерения), `AssemblyService` (вставка компонентов в сборку, namespace `Kompas.Mcp.Core.Assemblies`), снимок. Все паттерны API5/API7 живут здесь. |
+| **Kompas.Mcp.Tests** | Юнит (без COM) + интеграционные (требуют КОМПАС). 138 тестов (83 unit + 55 integration). |
 
 Принцип: **только `Core` знает про COM**. `Host`/Tools оперируют доменными DTO и вызывают `Core`; `Host` не содержит бизнес-логики.
 
@@ -121,7 +121,7 @@ MCP client ──stdio──> Host (поток-пул, async)
 
 ---
 
-## 5. Карта инструментов (70 инструментов)
+## 5. Карта инструментов (71 инструмент)
 
 Сгруппированы вокруг центрального цикла «эскиз ↔ операция». Имена — `snake_case`.
 
@@ -204,6 +204,9 @@ MCP client ──stdio──> Host (поток-пул, async)
 
 **Ограничение:** переменная управляет геометрией только в параметрической модели, где размеры эскизов привязаны к именам переменных. Наши эскизы строятся литеральными координатами — `set_variable` хранит и вычисляет значение, но геометрию не меняет. Связь размеров эскизов с переменными (параметрические эскизы через API2D) — не реализована (package D продолжение).
 
+**Assembly — построение сборок (`AssemblyService`, `AssemblyTools`, namespace `Kompas.Mcp.Core.Assemblies`)**
+- `assembly_add_component` — вставить компонент (.m3d деталь или .a3d подсборка) из файла в активную сборку; задать положение origin (x,y,z мм, мировая СК сборки). Возвращает индекс и имя вставленного компонента. Реализовано через API7: `IParts7.AddFromFile(path, ExternalFile=true, Redraw=true)` → `IPart7` → `IPlacement3D.SetOrigin(x,y,z)` → `UpdatePlacement(true)` → `RebuildModel(true)`. `RequireActiveAssembly` проверяет `doc.DocumentType == ksDocumentAssembly` до обращения к `TopPart`. Откат при неуспехе через `IFeature7.Delete`. DI: `AddSingleton<AssemblyService>()` в `Program.cs`.
+
 **Vision — визуальная обратная связь (fallback)**
 - `model_snapshot` — отрендерить активный 3D-документ в PNG и вернуть **как image-контент MCP**,
   чтобы мультимодальный агент *увидел* промежуточный результат. Использовать для визуально-пространственных
@@ -337,7 +340,7 @@ dotnet build -c Release -r win-x64        # сборка
 
 ## 10. Дорожная карта
 
-**Реализовано (v1+v2+STEP/assembly+direct-edit+inspection+package-A+package-B+package-C+package-D start+package-E start+hole+hole_counterbore+hole_countersink+hole_conic+draft):** документы, эскизы (полный набор 2D-примитивов: линия, окружность, дуга, дуга по 3 точкам, прямоугольник, эллипс, ломаная, правильный многоугольник, сплайн NURBS, точка), **вспомогательная геометрия (`sketch_create_on_offset_plane`)**, выдавливание/вырез, вращение, скругление/фаска, **оболочка (`shell`)**, **ребро жёсткости (`rib`)**, **кинематическая операция (`sweep`)**, **операция по сечениям (`loft`)**, **линейный/круговой массив и зеркало (`linear_pattern`, `circular_pattern`, `mirror_operation`, `mirror_body`)**, **отверстие (`hole`, API7)**, **цековка (`hole_counterbore`, API7)**, **зенковка (`hole_countersink`, API7)**, **коническое отверстие (`hole_conic`, API7)**, **уклон (`draft`, API5 `ksInclineDefinition`)**, снимок; `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`; `import_step`, `export_step`, `list_components`; **`move_face`**, **`split_solid_by_plane`**, **`move_body`**, **`boolean_union`** (прямое редактирование и булевы операции); **`describe_model`, `list_features`, `list_bodies`, `list_variables`, `describe_face`, `describe_edge`, `measure`** (структурный осмотр модели); **`create_variable`, `set_variable`, `delete_variable`** (управление переменными, package D start).
+**Реализовано (v1+v2+STEP/assembly+direct-edit+inspection+package-A+package-B+package-C+package-D start+package-E start+hole+hole_counterbore+hole_countersink+hole_conic+draft+assembly_add_component):** документы, эскизы (полный набор 2D-примитивов: линия, окружность, дуга, дуга по 3 точкам, прямоугольник, эллипс, ломаная, правильный многоугольник, сплайн NURBS, точка), **вспомогательная геометрия (`sketch_create_on_offset_plane`)**, выдавливание/вырез, вращение, скругление/фаска, **оболочка (`shell`)**, **ребро жёсткости (`rib`)**, **кинематическая операция (`sweep`)**, **операция по сечениям (`loft`)**, **линейный/круговой массив и зеркало (`linear_pattern`, `circular_pattern`, `mirror_operation`, `mirror_body`)**, **отверстие (`hole`, API7)**, **цековка (`hole_counterbore`, API7)**, **зенковка (`hole_countersink`, API7)**, **коническое отверстие (`hole_conic`, API7)**, **уклон (`draft`, API5 `ksInclineDefinition`)**, снимок; `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`; `import_step`, `export_step`, `list_components`; **`move_face`**, **`split_solid_by_plane`**, **`move_body`**, **`boolean_union`** (прямое редактирование и булевы операции); **`describe_model`, `list_features`, `list_bodies`, `list_variables`, `describe_face`, `describe_edge`, `measure`** (структурный осмотр модели); **`create_variable`, `set_variable`, `delete_variable`** (управление переменными, package D start); **`assembly_add_component`** (вставка компонента в сборку, API7, `AssemblyService`).
 
 **Следующие приоритеты:**
 1. Пакет D «параметрика» (продолжение) — связь размеров эскизов с переменными (параметрические эскизы через API2D). ⚠️ **Исследовано**: `ksCDimWithVariable` недоступен из внешней автоматизации — см. `docs/superpowers/specs/2026-05-27-parametric-sketch-findings.md`.
@@ -345,7 +348,7 @@ dotnet build -c Release -r win-x64        # сборка
 3. Рассечение/перемещение тела как MCP-инструменты (`SplitSolids`/`BodyRepositions`) — механика есть, продуктизация не закончена.
 4. Свойства документа: `IPropertyMng` / `IPropertyKeeper`.
 5. Полноценное 2D-черчение: виды, линии/дуги/окружности, размеры (`ILinearDimension`, …), штриховки, тексты.
-6. Спецификации (`ISpecification`), построение сборок и сопряжения.
+6. Сборки — продолжение: сопряжения (`IMates7`), ограничения, авто-позиционирование компонентов; спецификации (`ISpecification`).
 7. Транспорт **HTTP/SSE** — как опция для удалённых клиентов.
 
 ---

docs/OPEN_QUESTIONS.md

@@ -182,3 +182,6 @@ stateful-сессии? Пока полагаемся на последовате
 
 ### ✅ Коническое отверстие — реализовано
 **Решено.** Новый инструмент `hole_conic` — коническое (конусное) отверстие, сужающееся вглубь. Параметры: `x,y,z`, `diameter` (диаметр у основания), `conicAngle` (угол конуса, 0<angle<180), `depth=0`, `throughAll=false`. Реализован через тот же `HoleCore`-паттерн (`configure`-колбэк): `HoleType=ksHTConic` + configure устанавливает `(IConicHoleParameters)hole.HoleParameters` (`ConicType=ksCNAngle`, `ConicAngle`). Завершает набор типов отверстий: простое (`hole`), цековка (`hole_counterbore`), зенковка (`hole_countersink`), коническое (`hole_conic`). Итог: **70 инструментов, 119 тестов (69 unit + 50 integration).**
+
+### ✅ Вставка компонента в сборку — реализована (начало класса «Сборки»)
+**Решено.** Новый инструмент `assembly_add_component(filePath, x, y, z)` — первый инструмент, который *пишет* в сборку (ранее `list_components` только читал). Сервис `AssemblyService` (`src/Kompas.Mcp.Core/Assemblies/`), инструменты — `AssemblyTools`. Паттерн API7: `IParts7.AddFromFile` → `IPlacement3D.SetOrigin` → `UpdatePlacement` → `RebuildModel(true)`. Ключевые тонкости: `UpdatePlacement` возвращает FALSE для вручную позиционируемого компонента — не ошибка; зафиксированный первый компонент двигается через `SetOrigin+RebuildModel` без разфиксации; `RequireActiveAssembly` проверяет тип документа до `TopPart`. Откат при неуспехе через `IFeature7.Delete`. Итог: **71 инструмент, 138 тестов (83 unit + 55 integration).** Следующий шаг: сопряжения (`IMates7`), ограничения.

docs/presentation.html

@@ -128,7 +128,7 @@
 <!-- HERO -->
 <header class="hero">
   <div class="wrap">
-    <span class="badge"><span class="dot" style="background:var(--green);box-shadow:0 0 10px var(--green)"></span> Статус: v3+ работает — эскиз→операции→STEP→сборка→move_face→структурный осмотр→богатые эскизы→shell+rib+sweep+loft+массивы+зеркало+hole+hole_counterbore+hole_countersink+hole_conic+draft+переменные (70 инструментов)</span>
+    <span class="badge"><span class="dot" style="background:var(--green);box-shadow:0 0 10px var(--green)"></span> Статус: v3+ работает — эскиз→операции→STEP→сборка→move_face→структурный осмотр→богатые эскизы→shell+rib+sweep+loft+массивы+зеркало+hole+hole_counterbore+hole_countersink+hole_conic+draft+переменные+assembly_add_component (71 инструмент)</span>
     <h1>КОМПАС-3D <span class="g">MCP-сервер</span><br>управление CAD языком LLM</h1>
     <p class="lead">MCP-сервер, который превращает операции КОМПАС-3D — создание документов,
       эскизы, 3D-операции, параметры — в инструменты для языковой модели. Под капотом —
@@ -261,7 +261,7 @@
       впереди.</p>
 
     <div class="prog">
-      <div class="progrow"><span>Общий прогресс</span><span>v3+: STEP · move_face · структурный осмотр · богатые эскизы (пакет A) · shell+rib+sweep+loft (пакет B) · массивы+зеркало (пакет C) · переменные (пакет D start) · offset-plane (пакет E start) · hole (API7) · hole_counterbore · hole_countersink · hole_conic · draft (API5) · навык kompas-3d · 70 инструментов · 119 тестов</span></div>
+      <div class="progrow"><span>Общий прогресс</span><span>v3+: STEP · move_face · структурный осмотр · богатые эскизы (пакет A) · shell+rib+sweep+loft (пакет B) · массивы+зеркало (пакет C) · переменные (пакет D start) · offset-plane (пакет E start) · hole (API7) · hole_counterbore · hole_countersink · hole_conic · draft (API5) · assembly_add_component · навык kompas-3d · 71 инструмент · 138 тестов</span></div>
       <div class="bar"><i style="width:97%"></i></div>
     </div>
 
@@ -297,7 +297,7 @@
       <!-- TOOLS -->
       <div class="panel">
         <h3>Инструменты v3+ <span class="tag done">ГОТОВО</span></h3>
-        <p class="meta">70 инструментов, отдаются по MCP-протоколу</p>
+        <p class="meta">71 инструмент, отдаются по MCP-протоколу</p>
         <ul class="list">
           <li class="muted"><span class="mark ok">✓</span><span class="t"><code>System</code>: connect · status · set_visible</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Documents</code>: create · open · save · save_as · close · active</span></li>
@@ -309,7 +309,8 @@
           <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Query</code>: get_part_info · get_bounding_box · list_faces · list_edges · list_components</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Variables</code>: <b>create_variable</b> · <b>set_variable</b> · <b>delete_variable</b> (пакет D)</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Conversion</code>: import_step · export_step</span></li>
-          <li><span class="mark wip">→</span><span>пакет E (ось, угловая плоскость) · пакет D параметрика: параметрические эскизы (API2D) — <b>исследовано, недоступно через COM API</b></span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t"><code>Assembly</code>: <b>assembly_add_component</b> (вставка компонента .m3d/.a3d в сборку, API7)</span></li>
+          <li><span class="mark wip">→</span><span>пакет E (ось, угловая плоскость) · пакет D параметрика: параметрические эскизы (API2D) — <b>исследовано, недоступно через COM API</b> · сопряжения в сборках</span></li>
         </ul>
       </div>
 
@@ -320,7 +321,7 @@
         <ul class="list">
           <li class="muted"><span class="mark ok">✓</span><span class="t">Unit-тесты — без COM: диспетчер, enum-маппинг, StepFormat, InspectionText</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Интеграционные тесты с КОМПАС: подключение, документы, снимок, цикл, STEP round-trip, сборка, move_face, инспекция</span></li>
-          <li class="muted"><span class="mark ok">✓</span><span class="t">Итого 119 тестов зелёных (69 unit + 50 integration)</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Итого 138 тестов зелёных (83 unit + 55 integration)</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Сборка <code>kompas-mcp.exe</code>, README с конфигом клиента</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Навык <code>kompas-3d</code> (методика) + полигон <code>usecases/</code></span></li>
           <li><span class="mark todo"></span><span>In-process тест MCP-клиента, релизный publish</span></li>
@@ -347,7 +348,8 @@
       <div class="tl" style="border-color:var(--green)"><div class="ph" style="color:var(--green)">draft · готово ✓</div><h4>Уклон</h4><p><b>draft</b> ✓ (API5 <code>ksInclineDefinition</code>, o3d_incline=42) · 64 инструмента · 115 тестов</p></div>
       <div class="tl" style="border-color:var(--green)"><div class="ph" style="color:var(--green)">пакет D start · готово ✓</div><h4>Переменные модели</h4><p><b>create_variable</b> · <b>set_variable</b> · <b>delete_variable</b> (API5 VariableService) · list_variables исправлен · 67 инструментов</p></div>
       <div class="tl" style="border-color:var(--green)"><div class="ph" style="color:var(--green)">отверстия под крепёж · готово ✓</div><h4>Цековка, зенковка и конус</h4><p><b>hole_counterbore</b> (ksHTCounterbore) · <b>hole_countersink</b> (ksHTCountersinking) · <b>hole_conic</b> (ksHTConic, IConicHoleParameters) · HoleCore рефакторен (configure-колбэк) · 70 инструментов · 119 тестов</p></div>
-      <div class="tl cur"><div class="ph">далее · в работе</div><h4>пакет E продолжение</h4><p>вспомогательная геометрия (ось, угловая плоскость) · пакет D параметрика — параметрические эскизы недоступны через COM API</p></div>
+      <div class="tl" style="border-color:var(--green)"><div class="ph" style="color:var(--green)">сборки start · готово ✓</div><h4>Вставка компонентов</h4><p><b>assembly_add_component</b> (API7 IParts7.AddFromFile + IPlacement3D) · 71 инструмент · 138 тестов</p></div>
+      <div class="tl cur"><div class="ph">далее · в работе</div><h4>пакет E продолжение</h4><p>вспомогательная геометрия (ось, угловая плоскость) · сопряжения в сборках · пакет D параметрика — параметрические эскизы недоступны через COM API</p></div>
     </div>
   </div>
 </section>