Ten rozdział to wizualny przewodnik po dwóch widokach grafowych AITM: Contract Explorer (mapa wszystkich behavioral contracts w projekcie) oraz App Flow (mapa tego, jak jeden konkretny element aplikacji wiąże się ze wszystkim innym). Wyjaśnia, co pokazuje każdy graf, jak czytać węzły, kolory i linie łączące, co oznacza legenda i do czego te dwa widoki faktycznie służą.

Contract Explorer & App Flow

Osoby, które jeszcze nie wiedzą, czym jest Contract i knowledge graph, powinny najpierw przeczytać rozdział Contracts, Knowledge Graph & Hints. Ten rozdział się na nim opiera i skupia się wyłącznie na nawigacji po obu wizualizacjach.

Contract Explorer — mapa Contracts projektu

Do czego służy: Contract Explorer to interaktywny graf wszystkich behavioral contracts w projekcie — zapisanych faktów o tym, jak zachowuje się każda część kodu. Na jednym ekranie widać, ile wiedzy AITM ma o projekcie, jak dobrze jest ona pokryta testami, które moduły są największe oraz jak Contracts łączą się z plikami, zmiennymi i dokumentacją. To najszybszy sposób, by odpowiedzieć na pytanie „co AITM wie o moim projekcie?” — oraz gdzie są słabe punkty (Contracts bez testów lub z testami zakończonymi niepowodzeniem).

Gdzie go znaleźć: w panelu projektu należy kliknąć podzakładkę Contracts (podzakładki projektu to Develop, Testing, Archive, Setting, Optimize, Contracts, Graph i Multi Graph). Sąsiednia podzakładka Graph rysuje graf kodu projektu, a Multi Graph rysuje go dla wszystkich projektów danej zakładki razem (jest widoczna tylko wtedy, gdy zakładka zawiera więcej niż jeden projekt).

Co jest na ekranie

Ekran składa się z czterech głównych obszarów:

• Górny pasek — zakładki zbiorów danych, statystyki zbiorcze i przyciski akcji.
• Lewy panel boczny — wyszukiwanie, filtry modułów i lista Contracts.
• Główny obszar grafu — interaktywny graf (przybliżanie kółkiem myszy, przesuwanie przez przeciąganie, węzły można przeciągać).
• Legenda (panel nakładkowy w lewym dolnym rogu grafu) — wyjaśnia kolory węzłów i typy linii.

Górny pasek — zakładki i statystyki

Poziomy szczegółowości — Module View a All Contracts

Nad grafem znajduje się przełącznik poziomu szczegółowości:

• Module View (domyślny dla dużych projektów, powyżej 500 Contracts) — każdy węzeł to cały moduł (np. „AI Chat”, „Backup Service”). Rozmiar bąbla odzwierciedla liczbę Contracts w module; linie między modułami oznaczają, że współdzielą pliki źródłowe. To „widok z lotu ptaka” — idealny punkt wyjścia.
• Kliknięcie modułu wchodzi głębiej do Module Detail — graf pokazuje wtedy poszczególne Contracts wybranego modułu.
• All Contracts — kompletny graf wszystkich Contracts naraz. W dużych projektach ze względu na wydajność jest ograniczony do 500 węzłów (plakietka pokazuje liczbę, a link „Show all” pozwala świadomie ominąć limit).

W prawym górnym rogu grafu znajduje się także przełącznik renderera: SVG, Sigma (domyślny — WebGL, radzi sobie z dużymi grafami), 3D, Cosmo i deck.gl. Nie zmienia on funkcjonalności, a jedynie sposób rysowania grafu — jeśli graf przycina się w dużym projekcie, warto wybrać Sigma.

Czytanie grafu — węzły

Każdy węzeł (kółko) to jedna encja. Kolor wskazuje jej typ — a w przypadku Contracts jednocześnie status testów:

Większy węzeł = ważniejsza encja (moduł z większą liczbą Contracts, Contract ze strefy ryzyka itp.).

Czytanie grafu — linie (relacje)

Linie między węzłami oznaczają „te dwie rzeczy są ze sobą powiązane”. Typ relacji jest zakodowany w stylu linii:

Praktyczna wskazówka: linie ciągłe = relacje w kodzie, linie przerywane = relacje przez dokumentację. Przerywana linia wychodząca z Contract oznacza, że istnieje dla niego pisemna dokumentacja — kliknięcie pomarańczowego węzła otwiera ją wprost w aplikacji.

Legenda

Legenda (panel w lewym dolnym rogu grafu) podsumowuje dokładnie to, co opisano powyżej — kolory węzłów i typy połączeń. Dla trzech stanów Contract pokazuje dodatkowo bieżące liczby i wartości procentowe (np. Tested (passing) 4/2403 (0%)): ile Contracts z aktualnie wyświetlanego zbioru znajduje się w każdym ze stanów. Liczby przeliczają się zgodnie z aktywnym filtrem — w Module View odnoszą się do modułów widocznych na ekranie, a po wejściu w moduł — do jego Contracts.

Lewy panel boczny

• Search — wyszukiwanie pełnotekstowe po identyfikatorach Contracts, opisach zachowania, plikach i zmiennych.
• Filters / Groups — przełącza między filtrem modułów (przyciski z nazwami modułów; All czyści filtr) a drzewem grupowanym.
• Lista Contracts (na dole) — wypełnia się Contracts wybranego modułu. Każdy wiersz ma kolorową kropkę o takiej samej semantyce jak węzły grafu (zielony/czerwony/bursztynowy) oraz ikonę dla Contracts w danger zone (miejscach, w których niewielka zmiana historycznie powodowała nieproporcjonalnie duże szkody).

Szczegóły Contract

Kliknięcie Contract (w grafie lub na liście) otwiera okno szczegółów Contract:

U góry szczegółów znajdują się dwa ważne przyciski:

• Assembled doc — otwiera kompletny złożony dokument dla Contract.
• Flow — przenosi bezpośrednio do widoku App Flow (patrz niżej), wycentrowanego na pierwszej zmiennej Contract. To most między obiema wizualizacjami: od „co obowiązuje” (Contract) do „jak to się wpisuje w aplikację” (przepływ).

App Flow — mapa relacji jednego elementu

Do czego służy: podczas gdy Contract Explorer pokazuje projekt z góry, App Flow odpowiada na pytanie „jak ten jeden konkretny element wiąże się z resztą aplikacji?”. Widać każdą zmienną języka komunikacji sąsiadującą z elementem — przez jej przestrzeń nazw, przez wspólne Contracts, przez wspólne pliki i przez nawigację w interfejsie. To idealne narzędzie do oszacowania wpływu zmiany („jeśli to ruszę, co jeszcze zostanie dotknięte?”) oraz do pisania precyzyjnych promptów Task.

Gdzie go znaleźć:

1. Z Dev Panel — w działającej aplikacji należy kliknąć element; otworzy się okno jego szczegółów z zakładkami Graph | Guide & Flow | App Flow.
2. Z Contract Explorer — przez przycisk Flow w szczegółach Contract (patrz wyżej).

Co jest na ekranie

• Lewa kolumna — dane badanego elementu: nazwa, opis, warstwa, a przede wszystkim lista Contracts, które nim sterują (z identyfikatorem, statusem testów, kondycją, plikami i wynikiem). To te same informacje co w Contract Explorer, tylko z perspektywy pojedynczego elementu.
• Środek — graf — interaktywny graf z badanym elementem pośrodku i powiązanymi zmiennymi wokół niego.
• Prawy panel — filtry typów relacji (pola wyboru) oraz lista powiązanych zmiennych, odzwierciedlająca graf w czytelnej formie listy.

Czytanie grafu — węzły

Czytanie grafu — kolory krawędzi (typy relacji)

Każda linia jest kolorowana według tego, dlaczego zmienne są ze sobą powiązane:

Prawy panel — filtry i lista

U góry znajdują się cztery pola wyboru — Namespace, Contract, File, Navigation — filtrujące zarówno graf, jak i listę. Domyślnie zaznaczone są Namespace + Contract (najbardziej użyteczne, najmniej szumu); File i Navigation warto włączyć, gdy trzeba prześledzić powiązania przez kod lub przepływ w interfejsie.

Każdy wiersz listy pokazuje kod zmiennej, nazwę i plakietki typów relacji. Przycisk (insert into prompt) przypina kod zmiennej bezpośrednio w pisanym prompcie Task — typowy scenariusz pracy to więc: znaleźć element w aplikacji → sprawdzić jego App Flow → przypiąć powiązane zmienne → opisać zmianę. Agent AI otrzymuje wtedy dokładne adresy miejsc, których zmiana dotyczy, i nie musi ich szukać.

Legenda i pomoc

W lewym dolnym rogu grafu znajduje się legenda podsumowująca style węzłów i kolory krawędzi (dokładnie tak, jak opisano powyżej). W prawym górnym rogu jest przycisk (?), który otwiera okienko pomocy wyjaśniające, co pokazuje App Flow i jak wyprowadzany jest każdy typ relacji:

Guide & Flow — przepływ logiki biznesowej

Obok App Flow szczegóły elementu mają zakładkę Guide & Flow. Wyjaśnia ona wybrany element od góry do dołu, prostymi krokami — najpierw sam element interfejsu, a potem business contracts opisujące jego zachowanie (każdy wraz ze zmiennymi, których dotyczy) — a przycisk Copy as Markdown kopiuje całe wyjaśnienie do schowka, gotowe do wklejenia w prompt Task.

AITM Dev Panel

Czym jest: niewielki pływający pasek narzędzi, który AITM może wstrzyknąć do aplikacji webowej zarządzanego projektu. Podczas korzystania z aplikacji w przeglądarce panel działa jak oczy AITM wewnątrz niej: rejestruje otagowane elementy interfejsu, które widzi (budując mapę ekranów, przycisków i okien dialogowych projektu, z której korzystają Contract Explorer i App Flow), oraz przechwytuje błędy JavaScript z konsoli przeglądarki i wysyła je do AITM, gdzie pojawiają się w projekcie i mogą zostać zamienione w Tasks naprawiające błędy.

Jak się tam znajduje: panel to jeden skrypt serwowany przez serwer AITM i dołączany do strony aplikacji w trybie deweloperskim. Wizard New Project dodaje go automatycznie do tworzonych projektów webowych; własny Dashboard AITM także go zawiera.

Co widać: cztery zakładki —

• Elements — elementy kliknięte lub przypięte, każdy z kodem zmiennej, stojącymi za nim Contracts i plikami oraz ostrzeżeniami z Contracts typu danger zone. Overlay podświetla wszystkie otagowane elementy na stronie; Pin / One Pin zbierają elementy do promptu; ikony w każdym wierszu kopiują kod, otwierają szczegóły elementu (Graph, Guide & Flow, App Flow) i usuwają przypięcie. Clear Pins opróżnia listę.
• Records — elementy interfejsu zarejestrowane przez panel na stronie.
• Errors — błędy JavaScript i konsoli przechwycone w tej przeglądarce, z liczbą w nazwie zakładki.
• Settings — własne opcje panelu.

Panel pojawia się tylko w trybie deweloperskim i jest przeznaczony dla programistów oraz agentów AI, a nie dla użytkowników końcowych aplikacji. Pełna dokumentacja otwiera się z menu w nagłówku: Help → AITM Dev Panel. Rozmiary czcionek panelu można regulować w Settings → Font & Style.

Praktyczne scenariusze pracy

Znalezienie słabych punktów modułu: Contracts → Module View → kliknięcie modułu → wypatrywanie bursztynowych (bez testów) i czerwonych (z niepowodzeniami) węzłów w grafie. Legenda od razu podaje wartości procentowe.

Oszacowanie wpływu zmiany przed zgłoszeniem Task: znaleźć element w aplikacji przez Dev Panel (albo Contract w Contract Explorer i przycisk Flow) → App Flow → włączyć relacje contract i file → wszystko, co jest połączone, może zostać dotknięte zmianą.

Napisanie precyzyjnego promptu: w App Flow należy przypiąć odpowiednie zmienne do promptu — Task zaczyna wtedy mówić językiem zrozumiałym zarówno dla człowieka, jak i dla agentów AI w Pipeline (język komunikacji).

Sprawdzenie, czy zachowanie jest udokumentowane: w Contract Explorer należy podążać za przerywanymi liniami wychodzącymi z Contract — prowadzą one do dokumentów (pomarańczowe węzły), które otwierają się kliknięciem wprost w aplikacji.