RU codex docs compact inspection

Компактная инспекция модели (P0-6)

CADYX сохраняет исходные полные маршруты чтения документа и истории. Внешний агент может сократить объём ответа, исключив длинные строки B-rep, сетки и крупные аргументы команд. Для этого используется доступный только для чтения GET /api/v1/agent/projects/{project_id}/inspection. В MCP тот же маршрут доступен как cadyx_inspect_compact. Не нужны блокировка на запись, дополнительное хранилище состояния или автоматизация браузера.

Обычный MCP cadyx_inspect_project и сводка проекта встроенного AgentRuntime по умолчанию используют компактный формат. Полную геометрию и историю можно явно запросить через cadyx_inspect_project_full. Большую инспекцию читайте страницами, закрепляя все запросы за одной expected_revision, вместо многократной выгрузки полных B-rep.

Параметры запроса

Параметр	Значение	По умолчанию
section	summary, entities, parameters, topology, changes	summary
expected_revision	Текущая ревизия документа, неотрицательное целое	Необязателен; зафиксируйте для последующих страниц
offset / limit	Неотрицательная позиция / от 1 до 100 элементов	0 / 25
kind	Тип объекта для entities; face или edge для topology	Без фильтра / для топологии обязателен
body_id	Сохранённый ID тела; обязателен для topology	Нет
shape	Необязательный дескриптор surface или curve для topology	Все формы
include_metrics	Значение 1 запрашивает нативные метрики выбранных тел	0
since_revision	Начальная ревизия, не включаемая в результат changes	Для changes обязателен

В каждом ответе есть schema_version, project_id, revision и section. Ответы с разбиением на страницы также включают items, total, returned, offset, limit, omitted и has_more. Неизвестные и повторённые параметры считаются ошибкой, их не игнорируют. Если expected_revision устарела, сервер вернёт HTTP 409 REVISION_CONFLICT; нужно запрашивать первую страницу заново, а не смешивать две ревизии.

• summary. Возвращает отсортированное количество сущностей по типам, ограничения, количество тел и параметров, число привязок, единицы параметров, доступность материалов и явный статус доступности метрик геометрии. CADYX не утверждает выведенную догадкой единицу документа или отсутствующий каталог материалов.
• entities. Сортирует объекты по постоянному типизированному ID лексикографически, а не в порядке добавления в документ. Возвращает короткие имена, тип, выбранные скалярные атрибуты, ограниченный список зависимостей и имена параметров. Полные B-rep, сетки и большие параметры намеренно исключены. Для kind=body&include_metrics=1 ядро возвращает запрошенные объём, площадь, границы и метрики топологии тела; это может потребовать больше процессорного времени, чем сводка.
• parameters. Возвращает именованные значения параметров и явно заданные единицы, отсортированные по имени.
• topology. Использует существующий читатель топологии OCCT, ограничивает ответ одним актуальным телом, сортирует по индексам грани/ребра в текущей ревизии и возвращает semantic_key, когда он есть. Например, kind=face&shape=plane перечисляет текущие плоские грани. Индексы не сохраняются при перестроениях. Сложные типизированные предикаты доступны отдельным POST /topology/query.
• changes. Возвращает компактные квитанции команд из существующей сохранённой истории после since_revision, в порядке ревизий. Квитанция перечисляет ID элементов, явно упомянутые в команде/результате, если они доступны. Ответ задаёт feature_change_coverage=explicit_history_references_only и complete_geometry_diff=false. Перестроенная косвенная зависимость может не попасть в список; старые снимки B-rep в истории команд не хранятся. Пустой список элементов не означает, что ничего не менялось.

API не возвращает next_cursor. Пока has_more=true, запрашивайте следующую страницу с offset + limit, неизменно передавая ту же expected_revision. Ответ сообщает, какие поля и элементы пропущены. Полная инспекция доступна по GET /api/v1/agent/projects/{project_id}, через существующие маршруты топологии и viewport.

Производительность и регрессионные доказательства

Тесты tests/test_compact_inspection.py проверяют порядок страниц, фильтры, стабильность ревизии, явные пропуски, безопасные ссылки на элементы, передачу запросов через HTTP/MCP и то, что большие фикстуры геометрии/истории дают заметно меньший JSON-ответ.

Для представительной сохранённой модели можно запустить необязательное измерение в настроенной среде CADYX:

python scripts/benchmark-compact-inspection.py --projects-dir projects --project-id <UUID> --samples 30

Команда выводит размер ответа в UTF-8 байтах, приблизительное количество токенов (байты / 4), медианные p50/p95 задержки и пиковые аллокации для полной и компактной инспекции. Результаты зависят от модели, среды выполнения, ядра и прогретых кешей. Нельзя заявлять преимущество по измерениям, пока они действительно не проведены. Исходный JSON проекта всё равно требуется загрузить и проверить; этот API не обещает независимого снижения расхода памяти слоя хранения. Запуск измерения и всех тестов отложен до среды проверки CI.