feat(inspection): структурное «зрение» модели — осмотр без снимка

Новый слой «модель как данные» (приоритетный над model_snapshot):
- describe_model — структурный «паспорт» детали одним вызовом (габарит,
  МЦХ, тела, сводка топологии, дерево построения с параметрами, переменные)
- list_features / list_bodies / list_variables
- describe_face / describe_edge (drill-down по индексу)
- measure (расстояние/угол между гранями/рёбрами/вершинами)
- model_snapshot понижен до fallback для визуально-пространственных вопросов

Реализация: ModelInspectionService (COM) + чистый InspectionText (рендер,
группировка, детект «импорт без истории») + record-модели; InspectionTools.
Дерево читается через ksPart.GetFeature()->SubFeatureCollection; точный тип
и параметры операций берутся из GetObject()->GetDefinition() (ksFeature.type
отдаёт лишь coarse o3d_entity).

Снимок дерева также включает слои conversion (STEP), editing (move_face/solid)
и validation, развивавшиеся параллельно. Полный прогон: 61 тест зелёный,
43 MCP-инструмента. Документация (README, ARCHITECTURE, OPEN_QUESTIONS,
CLAUDE.md, presentation.html) синхронизирована.

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

docs/ARCHITECTURE.md

@@ -1,8 +1,7 @@
 # Архитектура MCP-сервера КОМПАС-3D (предлагаемый вариант)
 
-> Статус: **черновик / предлагаемый вариант**, открыт к правкам.
-> Назначение: зафиксировать выбор стека и целевую архитектуру решения до начала
-> реализации. Сопутствующий контекст по COM API КОМПАС — в [`../CLAUDE.md`](../CLAUDE.md).
+> Статус: **реализовано и работает** (v1+v2+STEP/assembly+direct-edit+inspection). Актуализировано по коду.
+> Сопутствующий контекст по COM API КОМПАС — в [`../CLAUDE.md`](../CLAUDE.md).
 > Имена интерфейсов и перечислений сверены со справкой SDK через `.claude/skills/kompas-sdk-research/kdoc.py` (навык `kompas-sdk-research`).
 
 ---
@@ -108,21 +107,21 @@ MCP client ──stdio──> Host (поток-пул, async)
 
 ## 4. Слои решения
 
-В v1 — логические слои (папки/проекты одного solution `KompasMcp.sln`):
+Проекты solution `KompasMcp.slnx` (спайк-проекты ConnectSpike/ReconSpike удалены; их механика покрыта тестами):
 
-| Слой | Ответственность |
+| Проект | Ответственность |
 |---|---|
-| **Kompas.Mcp.Host** | Точка входа. Сборка MCP-сервера (stdio), DI, логи в stderr, старт и владение STA-потоком, graceful shutdown. |
-| **Kompas.Mcp.Tools** | Определения MCP-инструментов по категориям (System / Documents / Sketch / Features / Query). **Тонкий слой**: валидация аргументов → постановка задачи на STA-поток → форматирование результата/ошибки в MCP-ответ. |
-| **Kompas.Mcp.Core** (`KompasSession`) | COM-слой. Менеджер соединения, менеджер документов, построитель эскизов, построитель операций, помощники выборки граней/плоскостей. Безопасные типизированные методы, null-проверки, трансляция ошибок. Здесь живут все паттерны работы с API5/API7. |
-| **Kompas.Mcp.Interop** | Interop-сборки из `.tlb` + маппинг «дружелюбная строка ↔ перечисление» (`DocumentTypeEnum`, `Obj3dType`, `ksEndTypeEnum`, `ksDirectionTypeEnum`). |
+| **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) + интеграционные (требуют КОМПАС). 60 тестов. |
 
-Принцип: **только `Core` и `Interop` знают про COM**. `Tools` оперируют доменными
-DTO и вызывают `Core`; `Host` не содержит бизнес-логики.
+Принцип: **только `Core` знает про COM**. `Host`/Tools оперируют доменными DTO и вызывают `Core`; `Host` не содержит бизнес-логики.
+
+Архитектурный принцип: **MCP транслирует возможности SDK КОМПАС в общие инструменты** (не под конкретную задачу). Методический слой поверх MCP — навык `.claude/skills/kompas-3d/` (playbook'и, эвристики). Полигон отработки подходов — `usecases/` (в .gitignore).
 
 ---
 
-## 5. Карта инструментов v1
+## 5. Карта инструментов (43 инструмента)
 
 Сгруппированы вокруг центрального цикла «эскиз ↔ операция». Имена — `snake_case`.
 
@@ -147,14 +146,37 @@ DTO и вызывают `Core`; `Host` не содержит бизнес-лог
 - `revolve_boss` / `revolve_cut` — угол.
 - `rebuild` — перестроить деталь.
 
-**Selection / Query**
-- `select_face_by_point` — выбрать грань точкой (для следующего эскиза).
-- `list_bodies`, `list_faces_planes` — перечислить тела/грани и плоскости.
-- `get_part_info` — МЦХ/габариты (`IMassInertiaParam7`).
+**Edit** (прямое редактирование)
+- `move_face` — сдвинуть грань по мировой точке (x,y,z, мм) на distance мм вдоль нормали; distance>0 — наружу (добавить материал), <0 — внутрь. Работает на импортированной B-rep. Реализовано через API7 `IPart7.FindObjectsByPoint` + `FaceMover`; контейнеры `ISurfaceContainer`/`IModelContainer` получаются COM-QI от `IPart7` в рантайме. Проверено: top_spacer 39.45→41.45 мм.
 
-**Vision — визуальная обратная связь («зрение агента»)**
+**Selection / Query**
+- `get_part_info` — МЦХ через API5 `ksPart.CalcMassInertiaProperties(ST_MIX_MM|ST_MIX_KG)`.
+- `get_bounding_box` — габарит (`ksPart.GetGabarit`).
+- `list_faces` / `list_edges` — перечислить грани и рёбра детали с классификацией и мерами.
+- `list_components` — перечислить компоненты верхнего уровня сборки (индекс, имя, обозначение, признак детали, габарит) через `TopPart → IParts7`.
+
+**Conversion** (`ConversionTools.cs`, `ConversionService.cs`)
+- `import_step` — импорт .step/.stp в новый документ через встроенный конвертер КОМПАС (код `ksConverterFromSTEP=-3`); параметры `type` (assembly|part), `createComponentFiles`.
+- `export_step` — экспорт активного 3D-документа в STEP; `format` = auto|ap203|ap214|ap242.
+
+**Inspection — структурный осмотр модели (приоритетный над снимком)**
+- `describe_model` — структурный «паспорт» детали одним вызовом: габарит, МЦХ, тела, сводка топологии (грани/рёбра по типам), дерево построения с параметрами, переменные. **Предпочитать перед `model_snapshot`** — не тратит токены изображения.
+- `list_features` — дерево построения с параметрами (глубина/радиус/катеты), имена узлов локализованы КОМПАС.
+- `list_bodies` — тела детали: тип (твёрдое/поверхность) и число граней.
+- `list_variables` — переменные модели (имя/выражение/значение, флаги external/информационная).
+- `describe_face` — drill-down грани по индексу: тип, площадь, нормаль, радиус, число рёбер.
+- `describe_edge` — drill-down ребра по индексу: тип, длина, смежные грани, концевые вершины.
+- `measure` — расстояние и угол между двумя объектами (face|edge|vertex по индексам), единица `ST_MIX_MM`.
+
+Реализовано через `ModelInspectionService` (`src/Kompas.Mcp.Core/Query/ModelInspectionService.cs`),
+рендер текста — `InspectionText` (`InspectionText.cs`, юнит-тестируем без COM).
+Ключевые API-паттерны: `ksPart.GetFeature()` → `ksFeatureCollection` (дерево); `BodyCollection()` → `ksBody`; `VariableCollection()` → `ksVariable`; `GetMeasurer()` → `ksMeasurer`.
+«Импорт STEP без истории» определяется структурно: `bodyCount > 0 && нет формообразующих операций && features.Count <= bodyCount+1`.
+
+**Vision — визуальная обратная связь (fallback)**
 - `model_snapshot` — отрендерить активный 3D-документ в PNG и вернуть **как image-контент MCP**,
-  чтобы мультимодальный агент *увидел* промежуточный результат и контролировал построение пошагово.
+  чтобы мультимодальный агент *увидел* промежуточный результат. Использовать для визуально-пространственных
+  вопросов, когда структурный осмотр (`describe_model`) недостаточен.
 - `set_view` — задать ориентацию вида (`iso` / `front` / `top` / `right` / …), zoom-to-fit и режим
   отображения (`ShadedWireframe`) перед снимком — иначе снимок берётся со случайного текущего ракурса.
 
@@ -282,24 +304,24 @@ dotnet build -c Release -r win-x64        # сборка
 
 ---
 
-## 10. Дорожная карта (после v1)
+## 10. Дорожная карта
 
-1. Операции: `fillet` / `chamfer` / `shell` / `rib` / `loft` / `sweep`; массивы
-   (`ILinearPattern`, `ICircularPattern`).
-2. Параметры и свойства: `IVariable7` / `IVariableTable`, `IPropertyMng` / `IPropertyKeeper`.
-3. Полноценное 2D-черчение: виды, линии/дуги/окружности, размеры (`ILinearDimension`, …),
-   штриховки, тексты.
-4. Спецификации (`ISpecification`), сборки и сопряжения (`IAssemblyDocument`).
-5. Конвертеры/экспорт (STEP и др.) через `IApplication.Converter`.
+**Реализовано (v1+v2+STEP/assembly+direct-edit+inspection):** документы, эскизы, выдавливание/вырез, вращение, скругление/фаска, снимок; `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`; `import_step`, `export_step`, `list_components`; **`move_face`** (прямое редактирование грани, работает на импортированной B-rep); **`describe_model`, `list_features`, `list_bodies`, `list_variables`, `describe_face`, `describe_edge`, `measure`** (структурный осмотр модели).
+
+**Следующие приоритеты:**
+1. Рассечение/перемещение тела как MCP-инструменты (`SplitSolids`/`BodyRepositions`) — механика есть, продуктизация не закончена.
+2. Массивы (`ILinearPattern`, `ICircularPattern`).
+3. Свойства документа: `IPropertyMng` / `IPropertyKeeper`.
+4. Полноценное 2D-черчение: виды, линии/дуги/окружности, размеры (`ILinearDimension`, …), штриховки, тексты.
+5. Спецификации (`ISpecification`), построение сборок и сопряжения.
 6. Транспорт **HTTP/SSE** — как опция для удалённых клиентов.
 
 ---
 
 ## 11. Открытые вопросы
 
-- **Один проект vs solution из 4 проектов** в v1 (склоняемся к одному solution, слои — папками,
-  выделять проекты по мере роста).
-- **Embed Interop Types vs генерируемые interop-сборки** (`tlbimp`) — проверить на реальных
-  `.tlb` v24, выбрать по совместимости типов и размеру.
-- **Стратегия именования инструментов** — подтвердить `snake_case` с группами-префиксами
-  (`document_*`, `sketch_*`, …).
+- **Прямое редактирование B-rep, перемещение грани**: решено — `move_face` (`FaceEditService`) работает через `IPart7.FindObjectsByPoint` + `FaceMover`; проверено на импортированной B-rep. Рассечение/перемещение тела (`SplitSolids`/`BodyRepositions`) — механика есть, инструменты не реализованы (потенциальная следующая опция).
+- **Дерево операций, тела, переменные, геометрические запросы**: решено — `ModelInspectionService` + `InspectionTools` (7 инструментов); юнит-тестируемый рендер через `InspectionText`.
+- **Утечки транзитных RCW** в `PartModeler` (унаследованный паттерн): `EntityCollection`, `GetTopPart()` не освобождаются, накапливаются за длинную сессию.
+- **Насос сообщений / CancellationToken**: `CancellationToken` не прерывает идущий COM-вызов; зависший модальный диалог КОМПАС блокирует всю очередь.
+- **Embed Interop Types vs вендорские interop-сборки**: выбраны вендорские DLL из SDK `Samples/Common`; менять не планируется.