From 8e56af61b325d031b3830147cee699bc7ac5c068 Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Fri, 17 Jul 2026 01:18:10 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=BF=D1=80=D0=BE=D0=B5=D0=BA?= =?UTF-8?q?=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D0=BA=D0=B0?= =?UTF-8?q?=D1=82=D0=B0=D0=BB=D0=BE=D0=B3=20=D0=B2=D0=BD=D0=B5=D1=88=D0=BD?= =?UTF-8?q?=D0=B5=D0=B3=D0=BE=20CAD-=D0=BA=D0=BE=D0=BD=D1=82=D1=80=D0=B0?= =?UTF-8?q?=D0=BA=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-agent-cad-tool-contract-catalog-design.md | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-17-agent-cad-tool-contract-catalog-design.md diff --git a/docs/superpowers/specs/2026-07-17-agent-cad-tool-contract-catalog-design.md b/docs/superpowers/specs/2026-07-17-agent-cad-tool-contract-catalog-design.md new file mode 100644 index 0000000..64946cd --- /dev/null +++ b/docs/superpowers/specs/2026-07-17-agent-cad-tool-contract-catalog-design.md @@ -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-деталей.