Эта глава — наглядное руководство по двум графовым представлениям AITM: Contract Explorer (карта всех Behavioral Contracts проекта) и App Flow (карта того, как один конкретный элемент приложения связан со всем остальным). Здесь объясняется, что показывает каждый граф, как читать узлы, цвета и соединительные линии, что означает легенда и для чего на самом деле нужны оба представления.
Contract Explorer & App Flow
Если вы ещё не знаете, что такое Contract и knowledge graph, сначала прочитайте главу Contracts, Knowledge Graph & Hints. Эта глава опирается на неё и посвящена исключительно навигации по двум визуализациям.
Contract Explorer — карта Contracts проекта
Для чего он нужен: Contract Explorer — это интерактивный граф всех Behavioral Contracts проекта, то есть сохранённых фактов о том, как ведёт себя каждая часть кода. На одном экране видно, сколько знаний о проекте накопил AITM, насколько хорошо они покрыты тестами, какие модули самые крупные и как Contracts связаны с файлами, переменными и документацией. Это самый быстрый способ ответить на вопрос «что AITM знает о моём проекте?» — и найти слабые места (Contracts без тестов или с падающими тестами).
Где найти: в панели проекта нужно нажать подвкладку Contracts (подвкладки проекта: Develop, Testing, Archive, Setting, Optimize, Contracts, Graph и Multi Graph). Соседняя подвкладка Graph рисует граф кода проекта, а Multi Graph — граф сразу для всех проектов вкладки (она показывается, только если во вкладке больше одного проекта).
Что находится на экране
Экран состоит из четырёх основных областей:
- Верхняя панель — вкладки наборов данных, сводная статистика и кнопки действий.
- Левая боковая панель — поиск, фильтры по модулям и список Contracts.
- Основная область графа — интерактивный граф (масштабирование колесом мыши, перемещение перетаскиванием, узлы можно двигать).
- Легенда (накладываемая панель в левом нижнем углу графа) — объясняет цвета узлов и типы линий.
Верхняя панель — вкладки и статистика
| Элемент | Значение |
|---|---|
| Contracts (количество) | Contracts, полученные из кода, — основной набор данных, показываемый в графе. |
| Doc Contracts (количество) | Contracts, извлечённые из документации (результатов Task). На этой вкладке вместо графа показывается список. |
| Doc Pointers (количество) | Ссылки из файлов документации на Contracts — «где в документации об этом написано». |
| Needs Review (количество) | Contracts, ожидающие проверки (например, с низкой достоверностью или после конфликтующего изменения). |
| Total / Passing / Failing / Unknown | Сводка состояния: сколько всего Contracts, у скольких тесты проходят, у скольких падают и у скольких состояние неизвестно. |
| Coverage | Процент Contracts, покрытых тестами. |
| Fix Contracts | Запускает исправление несогласованных Contracts. |
| Reimport | Заново считывает Contracts из исходников проекта (полная пересинхронизация). |
Уровни отображения — Module View и All Contracts
Над графом находится переключатель уровня детализации:
- Module View (по умолчанию для крупных проектов, более 500 Contracts) — каждый узел представляет целый модуль (например, «AI Chat», «Backup Service»). Размер пузыря отражает количество Contracts в модуле; линии между модулями означают, что у них есть общие исходные файлы. Это «вид с высоты птичьего полёта» — идеальная отправная точка.
- Щелчок по модулю переходит к детализации Module Detail — граф показывает отдельные Contracts выбранного модуля.
- All Contracts — полный граф всех Contracts сразу. В крупных проектах для производительности он ограничен 500 узлами (значок показывает количество, а ссылка «Show all» позволяет намеренно снять это ограничение).
В правом верхнем углу графа есть также переключатель средства отрисовки: SVG, Sigma (по умолчанию — WebGL, справляется с большими графами), 3D, Cosmo и deck.gl. Он не меняет функциональность, а только способ отрисовки графа — если граф тормозит на большом проекте, стоит выбрать Sigma.
Как читать граф — узлы
Каждый узел (круг) — это одна сущность. Цвет показывает тип, а для Contracts одновременно и состояние тестов:
| Цвет узла | Тип / состояние | Значение |
|---|---|---|
 зелёный | Contract — Tested (passing) | У Contract есть тесты, и все они проходят. |
 красный | Contract — Failing | У Contract есть падающий тест — смотреть в первую очередь здесь. |
 янтарный | Contract — Untested | У Contract вообще нет тестов — поведение описано, но ничем не защищено. |
 синий | Module | Модуль (группа Contracts) — основные пузыри в Module View. |
 серый | File | Исходный файл, общий для нескольких Contracts. |
 оранжевый | Doc (Doc Pointer) | Файл документации, ссылающийся на Contracts. |
 фиолетовый | Doc Contract / переменная | Contract, полученный из документации, или переменная коммуникационного языка. |
 голубой | Behavior Doc | Сгенерированный документ с описанием поведения. |
Чем больше узел, тем значимее сущность (модуль с большим числом Contracts, Contract из опасной зоны и т. д.).
Как читать граф — линии (связи)
Линии между узлами означают «эти две сущности связаны». Тип связи кодируется стилем линии:
| Стиль линии | Связь | Значение |
|---|---|---|
| сплошная | Module → Contract | Contract принадлежит модулю. В Module View толщина линии отражает количество общих файлов между модулями. |
| сплошная тонкая | Contract → File / Variable / Doc | Contract затрагивает файл, управляет переменной или описан в документе. |
| штриховая фиолетовая | DocContract → Contract | Doc Contract подтверждает или дополняет Contract из кода. |
| штриховая оранжевая | Contract → Doc Pointer | Файл документации ссылается на Contract. |
| штриховая светло-фиолетовая | DocContract ↔ Doc Pointer | Doc Contract и Doc Pointer относятся к одному и тому же Contract — цепочка документации. |
Практическое чтение: сплошные линии — связи в коде, штриховые — связи через документацию. Штриховая линия, отходящая от Contract, означает, что для него существует письменная документация — щёлкните по оранжевому узлу, чтобы открыть её прямо в приложении.
Легенда
Легенда (панель в левом нижнем углу графа) кратко воспроизводит всё описанное выше — цвета узлов и типы связей. Для трёх состояний Contract она дополнительно показывает текущие количества и проценты (например, Tested (passing) 4/2403 (0%)): сколько Contracts из отображаемого в данный момент набора находятся в каждом состоянии. Числа пересчитываются в соответствии с активным фильтром — в Module View они относятся к модулям на экране, а после перехода внутрь модуля — к его Contracts.
Левая боковая панель
- Search — полнотекстовый поиск по идентификаторам Contracts, описаниям поведения, файлам и переменным.
- Filters / Groups — переключение между фильтром по модулям (кнопки с названиями модулей;
Allснимает фильтр) и сгруппированным деревом. - Список Contracts (внизу) — заполняется Contracts выбранного модуля. В каждой строке есть цветная точка с тем же смыслом, что и у узлов графа (зелёный/красный/янтарный), а также значок
для Contracts в опасной зоне (местах, где небольшое изменение исторически приводило к несоразмерно большому ущербу).
Детали Contract
Щелчок по Contract (в графе или в списке) открывает окно с деталями Contract:
| Раздел | Что он сообщает |
|---|---|
| Header + badges | Идентификатор Contract (например, DPL-001), модуль, статус (code-only — получен из кода, без тестов; tested — есть тесты) и значок состояния (unverified, passing, failing). |
| Behavior | Сам Contract — одно-два предложения, точно описывающих поведение («что делает эта часть и что возвращает, когда…»). |
| Tests | Тесты, защищающие это поведение (файл + название теста). |
| Files | Исходные файлы, которые затрагивает Contract — щелчок фильтрует граф. |
| Variables | Переменные коммуникационного языка (BL.*, UI.* …), которыми управляет Contract. |
| Reliability Score | Оценка достоверности Contract (сочетание возраста, тестов и истории изменений). Низкая оценка означает, что к информации стоит относиться с осторожностью. |
| Related Tasks | Tasks, которые создали или изменили Contract. |
| Screenshot | Для UI-Contracts — превью элемента (снятое на шаге E2E Pipeline). |
| Change History | Когда и каким Task был изменён Contract. |
| Related Contracts / Documentation | Соседние Contracts (с общими файлами) и документы, ссылающиеся на этот Contract. |
В верхней части деталей находятся две важные кнопки:
Assembled doc — открывает полный собранный документ по Contract.
Flow — сразу переходит в представление App Flow (см. ниже), центрированное на первой переменной Contract. Это мост между двумя визуализациями: от «что должно выполняться» (Contract) к «как это вписывается в приложение» (поток).
App Flow — карта связей одного элемента
Для чего он нужен: если Contract Explorer показывает проект сверху, то App Flow отвечает на вопрос «как этот конкретный элемент связан с остальной частью приложения?». Видны все переменные коммуникационного языка, соседствующие с элементом, — через его пространство имён, общие Contracts, общие файлы и навигацию по UI. Это идеальный инструмент для оценки влияния изменений («если я это трону, что ещё пострадает?») и для составления точных промптов Task.
Где найти:
- Из Dev Panel — в запущенном приложении нужно щёлкнуть по элементу; откроется окно его деталей с вкладками Graph | Guide & Flow | App Flow.
- Из Contract Explorer — с помощью кнопки Flow в деталях Contract (см. выше).
Что находится на экране
- Левая колонка — данные исследуемого элемента: название, описание, слой и, прежде всего, список Contracts, которые им управляют (с идентификатором, состоянием тестов, состоянием, файлами и оценкой). Это та же информация, что и в Contract Explorer, но с точки зрения одного элемента.
- В центре — граф — интерактивный граф с исследуемым элементом посередине и связанными переменными вокруг него.
- Правая панель — фильтры по типам связей (флажки) и список связанных переменных, отражающий граф в виде удобного для чтения списка.
Как читать граф — узлы
| Вид узла | Значение |
|---|---|
| прямоугольник с подписью | Переменная — подпись представляет собой последний сегмент записи через точки (например, CODEMAP для BL.CODEMAP). |
| узел с синей рамкой | Исследуемый элемент — центр графа, то, по чему вы щёлкнули. |
| штриховая рамка | Ghost node — переменная бизнес-логики, у которой нет собственного элемента на экране (например, чисто серверная переменная BL.*). Щелчок по ghost node загружает её в левую колонку, и её тоже можно закрепить в промпте. |
Как читать граф — цвета рёбер (типы связей)
Каждая линия окрашена в зависимости от того, почему переменные связаны:
| Цвет ребра | Связь | Как возникает |
|---|---|---|
| серый | namespace | Соседи по пространству имён — у них общий префикс до точки (например, UI.PANEL.CHAT и UI.PANEL.BRAINSTORM). Означает «мы из одного семейства». |
| янтарный | contract | Переменные, указанные в одних и тех же Contracts — их поведение подчиняется одним и тем же правилам. Самая ценная связь для анализа влияния. |
 тёмно-серый | file | Переменные других Contracts, затрагивающих те же исходные файлы — связь через код. |
| синий | navigation | Связь в реальном UI: щелчок по этому элементу показывает целевой элемент или переходит к нему (выводится из сопоставленных эффектов в DOM). |
Правая панель — фильтры и список
Вверху расположены четыре флажка — Namespace, Contract, File, Navigation — они фильтруют и граф, и список. По умолчанию отмечены Namespace + Contract (самые полезные и наименее шумные связи); File и Navigation стоит включать, когда нужно проследить связи через код или через поток UI.
В каждой строке списка показаны код переменной, название и значки типов связей. Кнопка 
(вставить в промпт) закрепляет код переменной прямо в промпте Task, который вы пишете, поэтому типичный сценарий такой: найти элемент в приложении → изучить его App Flow → закрепить связанные переменные → описать изменение. AI Agent получает точные адреса мест, которых касается изменение, и ему не нужно их искать.
Легенда и справка
В левом нижнем углу графа находится легенда, кратко описывающая стили узлов и цвета рёбер (в точности как описано выше). В правом верхнем углу расположена кнопка (?), открывающая всплывающую справку о том, что показывает App Flow и как выводится каждый тип связи:
Guide & Flow — поток бизнес-логики
Рядом с App Flow в деталях элемента есть вкладка Guide & Flow. Она объясняет выбранный элемент сверху вниз простыми шагами — сам элемент UI, а затем бизнес-Contracts, описывающие его поведение (каждый с переменными, которых он касается), — а кнопка Copy as Markdown копирует всё объяснение в буфер обмена, готовое для вставки в промпт Task.
AITM Dev Panel
Что это: небольшая плавающая панель инструментов, которую AITM может внедрить в веб-приложение управляемого им проекта. Пока вы работаете с приложением в браузере, панель служит глазами AITM внутри него: она записывает помеченные элементы UI, которые видит (строя карту экранов, кнопок и диалогов проекта, на которой основаны Contract Explorer и App Flow), и перехватывает ошибки JavaScript из консоли браузера, отправляя их в AITM, где они отображаются для проекта и из них можно создавать Tasks по исправлению ошибок.
Как она туда попадает: панель — это один скрипт, который раздаёт сервер AITM и который подключается к странице приложения в режиме разработки. Wizard создания проекта добавляет её автоматически в создаваемые им веб-проекты; в собственном Dashboard AITM она тоже есть.
Что видно: четыре вкладки —
- Elements — элементы, по которым вы щёлкнули или которые закрепили, каждый с кодом переменной, стоящими за ним Contracts и файлами, а также предупреждениями от Contracts из опасных зон. Overlay подсвечивает все помеченные элементы на странице; Pin / One Pin собирают элементы для промпта; значки в каждой строке копируют код, открывают детали элемента (Graph, Guide & Flow, App Flow) и удаляют закрепление. Clear Pins очищает список.
- Records — элементы UI, записанные панелью со страницы.
- Errors — ошибки JavaScript и консоли, перехваченные в этом браузере, с количеством в названии вкладки.
- Settings — собственные параметры панели.
Панель появляется только в режиме разработки и предназначена для вас и AI Agent, а не для конечных пользователей приложения. Её полная документация открывается из меню заголовка: Help → AITM Dev Panel. Размеры шрифтов панели настраиваются в разделе Settings → Font & Style.
Практические сценарии
Найти слабые места модуля: Contracts → Module View → щёлкнуть по модулю → искать в графе янтарные (без тестов) и красные (падающие) узлы. Легенда сразу показывает проценты.
Оценить влияние изменения перед созданием Task: найти элемент в приложении через Dev Panel (или Contract в Contract Explorer и кнопку Flow) → App Flow → включить связи contract и file → всё, что с ним связано, может быть затронуто вашим изменением.
Написать точный промпт: в App Flow закрепить нужные переменные в промпте — тогда Task говорит на языке, понятном и вам, и AI Agent Pipeline (коммуникационном языке).
Проверить, задокументировано ли поведение: в Contract Explorer пройти по штриховым линиям от Contract — они ведут к документам (оранжевые узлы), которые открываются щелчком прямо в приложении.