docs: спроектировать каталог внешнего CAD-контракта

2026-07-17 01:18:10 +03:00
parent 69d037c875
commit 8e56af61b3
1 changed files with 96 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Каталог внешнего CAD-контракта для агента — дизайн
+
+## Цель
+
+Создать отдельный документ `docs/AGENT_CAD_TOOL_CATALOG.md`, который описывает желаемый внешний MCP-контракт управления CAD с точки зрения автономного агента, показывает все реализованные и необходимые нереализованные методы и позволяет оценить полноту контракта по сквозным CAD-сценариям.
+
+## Границы
+
+- Каталог описывает внешний контракт, а не внутреннюю реализацию.
+- COM-интерфейсы, вызовы API5/API7 и другие детали SDK КОМПАС-3D в итоговую таблицу не включаются.
+- SDK разрешено использовать только для внутренней оценки реалистичности предлагаемых методов и выявления платформенных ограничений.
+- Методы формулируются как общие CAD-операции, а не как инструменты под отдельную пользовательскую задачу.
+- В каталог входят все существующие MCP-инструменты и все выявленные методы, необходимые для полноты агентского контура.
+
+## Структура итогового документа
+
+1. Назначение документа и определение полноты внешнего контракта.
+2. Легенда статусов и приоритетов.
+3. Сводная матрица покрытия сквозных сценариев.
+4. Таблицы методов по функциональным доменам.
+5. Приоритизированный перечень пробелов.
+6. Общий вывод о текущей полноте контракта.
+
+Функциональные домены:
+
+- сессия и документы;
+- 2D-геометрия и эскизы;
+- 3D-моделирование;
+- прямое и историческое редактирование;
+- инспекция, выбор объектов и измерения;
+- сборки;
+- чертежи и оформление;
+- импорт и экспорт;
+- управление состоянием, восстановление и надёжность агентской работы.
+
+## Формат таблиц методов
+
+Каждая строка описывает один метод внешнего контракта. Обязательные столбцы:
+
+| Столбец | Содержание |
+|---|---|
+| Метод | Стабильное имя MCP-метода в `snake_case` |
+| Назначение | Краткое описание результата метода с позиции вызывающего агента |
+| Статус | `✅ реализован`, `🟡 частично`, `⬜ не реализован` или `⛔ ограничен платформой` |
+| Необходимость | `Core`, `Advanced` или `Optional` |
+| Пробел / ограничение | Что отсутствует в контракте или какая часть поведения не покрыта |
+
+SDK-интерфейсы, классы сервисов и другие детали реализации в эти таблицы не добавляются.
+
+## Критерии классификации
+
+### Статус
+
+- `✅ реализован` — метод существует в текущем MCP-каталоге и предоставляет заявленное внешнее поведение.
+- `🟡 частично` — метод существует, но покрывает только часть необходимого внешнего поведения или поддерживает ограниченный набор вариантов.
+- `⬜ не реализован` — метод нужен целевому контракту, но отсутствует как MCP-инструмент.
+- `⛔ ограничен платформой` — желаемое поведение невозможно или ненадёжно в доступном Automation API; ограничение должно быть сформулировано на уровне внешнего результата без SDK-подробностей.
+
+### Необходимость
+
+- `Core` — без метода агент не может надёжно завершить базовый сквозной сценарий либо проверить результат мутации.
+- `Advanced` — метод нужен для промышленно значимого расширенного сценария, но не блокирует минимальный цикл моделирования.
+- `Optional` — повышает удобство, производительность или широту применения, сохраняя работоспособность основного контура без него.
+
+### Приоритет пробела
+
+- `P0` — разрыв базового сквозного сценария или отсутствие необходимой обратной связи/управления состоянием.
+- `P1` — существенное ограничение распространённого профессионального сценария.
+- `P2` — расширение охвата или удобства без разрыва основных сценариев.
+
+## Оценка полноты
+
+Полнота оценивается не числом методов, а способностью агента выполнить замкнутый цикл `обнаружить состояние → изменить модель → проверить результат → сохранить или безопасно откатить`.
+
+Сводная матрица должна проверить минимум следующие сценарии:
+
+1. Создать и сохранить параметрическую 3D-деталь.
+2. Открыть или импортировать модель, локально изменить геометрию и проверить результат.
+3. Создать сборку, разместить компоненты, наложить сопряжения и проверить структуру.
+4. Создать комплект основных видов чертежа, оформить размеры и обозначения, сохранить результат.
+5. Выполнить геометрическую и документную инспекцию без обязательного визуального анализа.
+
+Для каждого сценария фиксируются покрытые этапы, блокирующие пробелы и итоговая оценка: `полный`, `частичный` или `неполный`.
+
+## Проверка реалистичности
+
+Перед включением нереализованного метода в контракт проверяется, что требуемое поведение в принципе доступно в установленной версии КОМПАС-3D либо может быть составлено из надёжных операций. Если реалистичность не подтверждена, метод получает статус `⛔ ограничен платформой` или явную пометку о необходимости технического исследования; детали исследования остаются вне итогового каталога.
+
+## Критерии готовности
+
+- Все текущие MCP-инструменты представлены ровно по одному разу.
+- Для каждого домена перечислены необходимые отсутствующие методы.
+- Частично реализованные методы не ошибочно помечены как полностью реализованные.
+- Сквозные сценарии позволяют увидеть блокирующие пробелы независимо от общего количества методов.
+- Итоговый список `P0–P2` согласован с доменными таблицами и не содержит методов, отсутствующих в основном каталоге.
+- Документ не содержит внутренних COM/SDK-деталей.