Instrukcja użytkownika

1. Czym jest Loonar Compass

Loonar Compass to samodzielna aplikacja okienkowa dla Windows: asystent AI do pracy z modelem Enterprise Architect (Sparx Systems). Piszesz do niego zwykłym językiem, a on:

• czyta model (pakiety, elementy, diagramy, połączenia, atrybuty i operacje) i opisuje, co w nim jest,
• analizuje model: wpływ zmiany elementu na resztę modelu, miejsca użycia operacji, elementy bez połączeń,
• zmienia model: tworzy pakiety, diagramy, elementy i połączenia, dodaje atrybuty i operacje, ustawia wartości tagów i słowa kluczowe, rozmieszcza elementy na diagramach, przenosi je, zdejmuje z diagramu, usuwa, koloruje, dodaje legendy, kopiuje pakiety i robi ich baseline,
• prowadzi słownik projektu EA (pojęcia z definicją i typem) oraz scenariusze elementów (kroki aktora i systemu),
• rysuje diagramy z opisu, ze zdjęcia, ze szkicu albo z załączonego pliku,
• pokazuje diagramy jako obrazki na czacie, tak jak rysuje je Enterprise Architect,
• przygotowuje dokumenty z treści modelu: Word, Excel, PowerPoint, PDF, obrazki PNG i strony Confluence, także według szablonów,
• czyta dokumenty: PDF, Word, PowerPoint, Visio i Excel, z Twojego dysku albo z biblioteki SharePoint zespołu,
• stosuje instrukcje modelowania zespołu zapisane w samym repozytorium EA, więc każdy, kto pracuje z repozytorium, korzysta z tych samych reguł,
• pamięta ustalenia między rozmowami (konwencje modelowania, preferencje, poprawki).

Aplikacja korzysta przez Internet z modelu językowego AI, z Twoim kluczem API: domyślnie z Claude Haiku 5.5 (Anthropic), a w ustawieniach możesz wybrać inny model Claude albo model OpenAI (rozdział 5). Z modelem EA łączy się na dwa sposoby: czyta go wprost (z bazy PostgreSQL, SQL Server, MySQL/MariaDB albo Oracle albo z pliku .qea/.qeax), a zapisuje przez Enterprise Architect, na koncie użytkownika modelu podanym w ustawieniach, jeśli model ma takie konto. Gdy plik modelu masz otwarty w EA, zmiany idą przez Twoje okno EA; w pozostałych przypadkach EA działa w tle. Zmiany w modelu możesz przed zapisem zatwierdzić albo odrzucić (rozdział 16).

Loonar Compass działa jako osobne okno, uruchamiane z menu Start, albo jako okno zadokowane w samym Enterprise Architect, które pracuje na projekcie otwartym w tym oknie EA (rozdział 10).

Interfejs i odpowiedzi asystenta są dostępne w czterech językach: polskim, angielskim, niemieckim i francuskim (rozdział 5). Aplikacja jest bezpłatna, także do użytku komercyjnego (rozdział 24).

Bez okna Compass sprawdza też model w potokach CI (rozdział 23), a osobny program Compass Hub udostępnia modele zespołu ludziom i narzędziom (rozdział 22).

4. Okno aplikacji i nawigacja

Po lewej stronie okna jest granatowy pasek nawigacji z ikonami. Po najechaniu myszą na ikonę pojawia się jej nazwa. Kliknięcie przełącza widok. Na dole okna jest pasek z nazwą i wersją aplikacji oraz danymi właściciela.

Pomarańczowy znak „!” na ikonach Ustawienia, Pamięć asystenta i Szablony dokumentów oznacza, że po zmianie języka tłumaczenie jeszcze się nie zakończyło (rozdział 5).

Wesprzyj projekt. Loonar Compass jest bezpłatny, także do użytku komercyjnego, i taki pozostanie. Przycisk Wesprzyj na suppi.pl otwiera stronę https://suppi.pl/loonar, na której możesz dobrowolnie wesprzeć rozwój aplikacji; wpłaty pokrywają między innymi certyfikat do podpisywania kodu, dzięki któremu Windows rozpozna aplikację jako pochodzącą od zweryfikowanego wydawcy. W części „Inne sposoby wsparcia” są linki do kodu źródłowego na GitHubie i do loonar.eu: możesz zgłaszać błędy i pomysły, polecić aplikację innym użytkownikom Enterprise Architect albo dać projektowi gwiazdkę na GitHubie.

Widok czatu

• Lista rozmów po lewej jest pogrupowana na „Dzisiaj”, „Wczoraj”, „Ostatnie 7 dni” i „Wcześniej”. Nową rozmowę zaczynasz przyciskiem +. Wybrana rozmowa jest podświetlona. Rozmowę usuniesz prawym przyciskiem myszy (rozdział 17).
• Nagłówek rozmowy pokazuje jej tytuł, przycisk Model: … z modelem tej rozmowy (rozdział 17), a w trakcie pracy asystenta znacznik „Asystent pracuje”.
• Wiadomości: Twoje są w beżowym dymku, odpowiedzi asystenta mają ikonę aplikacji. Przy każdej wiadomości jest godzina (przy starszych także data).
• Ekran nowej rozmowy pokazuje logo, podpowiedź, co możesz zrobić, oraz model EA, z którym rozmowa będzie pracować, z przyciskami Wybierz inny model… i Zatwierdź model i rozpocznij (rozdział 17).
• Karta wiadomości na dole: pole tekstu, przycisk wklejania, przycisk ⌖ (wybór z modelu), przy Claude także przełączniki 💭 (rozumowanie) i ∑ (kod w piaskownicy), model i tryb zatwierdzania (na przykład „claude-haiku-5-5 · tryb ask”) oraz okrągłe przyciski wysyłania i przerwania (rozdział 6).
• Przypomnienie pod kartą wiadomości: „Odpowiedzi i zmiany przygotowuje model AI i mogą zawierać błędy. Sprawdzaj je przed zatwierdzeniem.”

5. Ustawienia i język

Widok Ustawienia ma dwanaście kart: Model AI i Język i zatwierdzanie zmian w lewej kolumnie, Model i Enterprise Architect w prawej, a pod nimi Confluence, Jira, SharePoint, Agenci zdarzeń (Compass w EA), Serwery MCP, Zespół (Compass Hub), Miro i Nowe wydania (newsletter). W Compass otwartym w Enterprise Architect nie ma kart Model i Enterprise Architect, bo modelem jest projekt otwarty w tym oknie EA (rozdział 10). Każdą kartę zapisujesz osobno przyciskiem pod nią, a aplikacja od razu sprawdza, czy dane działają. Wynik pojawia się pod przyciskiem: zielony z opisem albo czerwony z przyczyną błędu.

Puste pole hasła, klucza lub tokena oznacza „bez zmian”. Napis zapisano obok pola mówi, że wartość jest już zapamiętana w Menedżerze poświadczeń, a BRAK, że jeszcze jej nie ma. Hasło do bazy nie może zawierać średnika (;), bo Enterprise Architect nie przekaże go w swoim ciągu połączenia. Adres Confluence musi zaczynać się od https://; adres http:// jest dopuszczalny tylko dla serwera na tym samym komputerze.

Wartości domyślne. Gdy nie ma jeszcze ustawień, pola serwera, nazwy bazy, konta użytkownika EA i haseł są puste (przy serwerze szara podpowiedź „np. 127.0.0.1”), port to 5432, konto bazy to postgres, ścieżka do EA to C:\Program Files\Sparx Systems\EA\EA.exe, tryb zatwierdzania to ask, dostawca to Anthropic (Claude), model to claude-haiku-5-5, poziom wysiłku to „domyślny dla modelu”, a Max tokenów to 10000. Jeśli brakuje ustawień albo któregoś z haseł lub klucza, aplikacja otwiera się w widoku Ustawienia i podaje, co trzeba uzupełnić.

Max tokenów. Jeśli asystent przerywa pracę komunikatem o uciętej odpowiedzi, zwiększ tę wartość (na przykład do 20000). Sam limit nic nie kosztuje: płacisz za faktycznie wygenerowany tekst.

Blokowanie pakietów i elementów przy zapisie zależy od opcji „Model wymaga blokady do edycji (Require User Lock to Edit)” w karcie Model: zaznacz ją, gdy model ma w EA włączone „Require User Lock to Edit”.

Model AI: dostawca, model i poziom wysiłku

Karta Model AI decyduje, który model językowy odpowiada w rozmowach:

Zapisz i sprawdź klucz sprawdza klucz krótkim zapytaniem do wybranego modelu. Dane potrzebne do odpowiedzi trafiają wyłącznie do wybranego dostawcy: do api.anthropic.com albo do api.openai.com (rozdział 18). Jeśli niczego w tej karcie nie zmienisz, aplikacja działa tak jak wcześniej: z Claude Haiku 5.5 i poziomem wysiłku domyślnym dla modelu. Większe modele i wyższy poziom wysiłku kosztują więcej; ceny podają Anthropic i OpenAI.

Zmiana języka

Aplikacja działa w czterech językach: polskim, angielskim, niemieckim i francuskim. Język wybierasz w instalatorze, a zmieniasz w karcie „Język i zatwierdzanie zmian”:

1. Wybierz język z listy Język.
2. Kliknij Zapisz. Interfejs od razu przełącza się na nowy język, a asystent odpowiada w nim od kolejnej wiadomości (jeśli napiszesz do niego w innym języku, odpowie w Twoim).
3. Aplikacja przenosi Twoje treści na nowy język: pamięć asystenta i Twoje szablony tłumaczy model AI.

Tłumaczone są tylko pamięć asystenta i szablony. Historia rozmów nigdy nie jest tłumaczona: rozmowy zostają w języku, w którym je prowadziłeś.

Po zapisaniu języka Compass przełącza też korektę pisowni samego EA na ten język, jeśli EA ma dla niego słownik. EA ma tylko słowniki angielskie, więc dla pozostałych języków teksty sprawdza Compass (rozdział 7, „Pisownia w języku Compassa”).

Szyfrowanie połączenia z bazą

Pole Szyfrowanie połączenia w karcie „Model” (opcja „Baza PostgreSQL”) decyduje, czy odczyt modelu przez asystenta idzie przez TLS:

• Test połączenia mówi, czy połączenie jest szyfrowane: „Połączenie jest szyfrowane (TLS).” albo „Połączenie NIE jest szyfrowane: serwer nie oferuje TLS.”.
• Przy weryfikacji certyfikatu nazwa w polu Serwer musi się zgadzać z nazwą w certyfikacie serwera.
• Administrator bazy może wymusić TLS dla wszystkich klientów wpisami hostssl w pliku pg_hba.conf.
• Ustawienie dotyczy odczytu modelu przez asystenta. Połączenie samego Enterprise Architect z bazą (przy zapisie) zależy od ustawień EA.
• Przy SQL Server ustawienie trafia do sterownika ODBC („Wymagane”: szyfrowanie bez sprawdzania certyfikatu; „Wymagane, z weryfikacją certyfikatu”: szyfrowanie i sprawdzenie certyfikatu). Przy MySQL i Oracle szyfrowanie ustawiasz w sterowniku albo w db.odbc (niżej).

SQL Server, MySQL i Oracle

Oprócz PostgreSQL i plików EA Compass czyta repozytoria EA w SQL Server, MySQL/MariaDB i Oracle: w osobnym oknie, w hubie zespołu (rozdział 22) i w trybie sprawdzania (rozdział 23). W karcie Model wybierz SQL Server, MySQL albo Oracle i wypełnij te same pola co dla PostgreSQL; port zmienia się na zwykły port tej bazy (1433, 3306, 1521), chyba że zmieniłeś go sam. Taką bazą może być też model rozmowy (rozdział 17).

• Sterownik ODBC. Compass łączy się przez 64-bitowy sterownik ODBC producenta bazy i sam go znajduje. Dla SQL Server bierze „ODBC Driver 18 for SQL Server”, potem 17, a na końcu własny sterownik Windows „SQL Server”. Dla MySQL sterownik MySQL albo MariaDB, dla Oracle sterownik klienta Oracle („Oracle in …”). Gdy żadnego nie ma, test podaje zainstalowane sterowniki.
• Własny ciąg połączenia. Gdy połączenie wymaga czegoś, czego nie ma w karcie (na przykład nazwy TNS Oracle albo opcji sterownika), wpisz w app.properties pełny ciąg połączenia ODBC jako db.odbc, bez hasła: Compass dodaje hasło z Menedżera poświadczeń. Przykład: db.odbc=Driver={ODBC Driver 18 for SQL Server};Server=sql01,1433;Database=ea;UID=compass;Encrypt=yes.
• Tylko odczyt. Odczyt idzie w transakcji, która zawsze jest wycofywana, więc sam Compass niczego w bazie nie zmienia. Do odczytu wystarczy konto z prawem SELECT na tabelach EA (t_*); gdy Enterprise Architect zapisuje tym samym kontem (SQL Server, niżej), potrzebuje też INSERT, UPDATE i DELETE na tych tabelach.

Zapis. Zmiany takiego modelu zapisuje Enterprise Architect, tak jak przy PostgreSQL. Twoja edycja EA musi obsługiwać repozytoria DBMS.

• SQL Server: Compass sam buduje połączenie EA (dostawca OLE DB SQLOLEDB) z pól karty Model. Sprawdź je przyciskiem „Zapisz i sprawdź dostęp do EA”.
• MySQL i Oracle: EA łączy się z nimi przez źródło danych ODBC. Wpisz połączenie EA do app.properties jako ea.conn: tekst skrótu połączenia EA, na przykład ea_lab --- DBType=0;Connect=Provider=MSDASQL.1;Data Source=<DSN ODBC>;…. Bez ea.conn zmiany wprowadzaj przez Compassa w Enterprise Architect (rozdział 10): zapisuje on przez Twoje okno EA, które działa z każdym otwartym w nim repozytorium.

W app.properties wybór to model.source=sqlserver, mysql albo oracle (postgres i file jak dotąd), z db.host, db.port, db.name, db.user i db.sslmode.

Logowanie do usługi AI: OAuth2 i inne adresy

Niektóre firmy dają dostęp do modelu AI przez własną bramkę albo przez Microsoft Azure zamiast klucza API. Karta Model AI ma do tego pola:

Pola są zapisywane w app.properties jako claude.url, ai.oauth.token_url, ai.oauth.client_id i ai.oauth.scope. Sprawdź je przyciskiem Zapisz i sprawdź klucz.

6. Rozmowa z asystentem

Pisanie

Wiadomość wpisujesz w karcie wiadomości na dole okna. Karta zawiera pole tekstu, przycisk wklejania, przycisk ⌖ (Wybierz z modelu, opis niżej), przy Claude także przełączniki 💭 i ∑ („Rozumowanie i obliczenia” niżej), nazwę modelu i bieżący tryb zatwierdzania oraz okrągłe przyciski: Wyślij, a w trakcie pracy asystenta Przerwij. Pod kartą jest przypomnienie, że odpowiedzi i zmiany przygotowuje model AI i trzeba je sprawdzać przed zatwierdzeniem.

Pole wiadomości rośnie razem z tekstem. Błędy pisowni są podkreślane na czerwono słownikiem systemu Windows, w języku z ustawień systemu. Kliknij podkreślone słowo prawym przyciskiem myszy i wybierz Dodaj „…” do słownika: słowo trafia do słownika Windows, a polskie wyrażenie we wszystkich formach odmiany (w liczbie pojedynczej i mnogiej, od mianownika do wołacza). W tym samym menu Dodaj „…” do słownika projektu EA prosi asystenta o dodanie pojęcia do słownika projektu (rozdział 7).

Wybierz z modelu

Przycisk ⌖ obok przycisku wklejania otwiera Wybierz z modelu. Wpisz część nazwy elementu, pakietu albo diagramu w polu „Nazwa elementu, pakietu albo diagramu”; przy pustym polu widzisz „Główne pakiety modelu:”. Kliknij wynik, a trafi do wiadomości jako odwołanie, na przykład «Element: Zamówienie (Class, id 26)». To takie samo odwołanie jak z menu EA pod prawym przyciskiem myszy Dodaj do rozmowy w Compass (rozdział 10), więc asystent wie dokładnie, o który obiekt chodzi.

Załączniki

Do wiadomości możesz dołączyć do 5 plików, każdy do 10 MB. Sposoby: przeciągnij pliki do okna (z Eksploratora albo z przeglądarki), wklej je ze schowka (Ctrl + V) albo użyj przycisku wklejania w karcie wiadomości.

W trakcie pracy asystenta

• Pod wiadomościami widać kartę kroków: co asystent właśnie robi, ile to trwa i jaki był wynik każdego kroku. W trakcie pracy karta jest rozwinięta, a po zakończeniu zwija się do jednej linii; kliknięcie nagłówka karty rozwija ją ponownie.
• W polskiej wersji interfejsu wynik kroku to krótkie podsumowanie, na przykład „wiersze: 12”, „zapisano w modelu EA” albo „plik gotowy”. Pełną treść wyniku (po angielsku) lista pokazuje tylko w angielskiej wersji interfejsu.
• Możesz pisać dalej: kolejna wiadomość trafia do kolejki i asystent uwzględni ją przy najbliższym kroku, bez przerywania pracy.
• Przycisk Przerwij zatrzymuje pracę po bieżącym kroku. Krok, który już trwa (na przykład zapis do EA), dobiega końca.
• Jedna odpowiedź może mieć najwyżej 24 kroki. Jeśli asystent nie zdąży w tym limicie, przerywa pracę z komunikatem, że wykonał maksymalną liczbę kroków; poproś go wtedy w nowej wiadomości, żeby kontynuował.

Ocena odpowiedzi i zgłoszenia z czatu

Pod każdą odpowiedzią asystenta są przyciski 👍 i 👎. Po kliknięciu 👎 wybierz powód: „Błędna lub niedokładna odpowiedź”, „Nie o to prosiłem”, „Za wolno” albo „Błąd w modelu”. W tym samym menu jest „Zgłoś problem z tą odpowiedzią”: otwiera formularz zgłoszenia (rozdział 20) z gotowym tematem i z dołączoną zgłaszaną odpowiedzią. Oceny trafiają tylko do statystyk użycia, jeśli są włączone, i pomagają ustalić, co poprawić najpierw.

Gdy prosisz o coś, czego asystent nie potrafi (na przykład nieobsługiwany format pliku albo integrację), mówi o tym wprost i proponuje, co może zrobić zamiast tego. Pod taką odpowiedzią pojawia się przycisk „💡 Zgłoś zapotrzebowanie”: otwiera formularz zgłoszenia z tematem „Zapotrzebowanie: …”, w którym opisujesz, czego potrzebujesz. Zgłoszenie trafia na GitHub jako pomysł.

Pytania, plan i podagenci

• Pytania doprecyzowujące. Gdy przed większą zmianą coś ważnego jest niejasne (który pakiet, jaka notacja, nazewnictwo, zakres), asystent nie zgaduje: pokazuje na czacie mały formularz „Pytania do Ciebie”, z wyborem odpowiedzi albo polem na krótką odpowiedź. Zamiast wyboru możesz wpisać własny tekst w polu „Coś innego…”. Wyślij odpowiedzi wysyła je jako Twoją kolejną wiadomość, zaczynającą się od „Moje odpowiedzi:”, a asystent pracuje dalej.
• Plan większej pracy. Przy pracy z trzema lub więcej krokami asystent pokazuje w karcie kroków swój plan, na przykład „📋 Plan: 1 z 4 zrobione”, z zadaniami oznaczonymi ✓ (zrobione), ▶ (w toku) i ○ (czeka). Plan aktualizuje się w trakcie pracy; w Compass w EA widać go też w System Output (rozdział 10).
• Podagenci. Przy większej analizie asystent może przekazać wąskie zadanie podagentowi: impact (na co wpływa planowana zmiana), review (przegląd pakietu, szkicu albo planowanych zmian według dobrych praktyk i instrukcji zespołu) albo document (szkic tekstu sekcji dokumentu). Podagent tylko czyta model, we własnym kontekście, i zwraca zwięzły wynik, dzięki czemu rozmowa zostaje krótka. Krok pokazuje „Podagent (impact): …”.

Rozumowanie i obliczenia

Dwa przełączniki w karcie wiadomości działają tylko z Claude (przy OpenAI ich nie ma); ustawienie jest zapamiętywane.

• 💭 Pokazuj rozumowanie asystenta w krokach. Streszczenie tego, jak model rozumuje, pojawia się w krokach jako „💭 Rozumowanie asystenta”. Model rozumuje tak czy inaczej; przełącznik tylko to pokazuje. Ile rozumuje, nadal decyduje poziom wysiłku w karcie Model AI (rozdział 5).
• ∑ Kod w piaskownicy (domyślnie wyłączony). Asystent może uruchamiać kod w piaskownicy Anthropic do obliczeń i analizy danych, na przykład sum wyceny albo statystyk eksportu modelu. Wynik widać jako krok „Kod w piaskownicy”. Dane, które asystent tam przekazuje, trafiają do Anthropic, tak jak rozmowa (rozdział 18).
• 🌐 Internet (domyślnie wyłączony). Asystent może szukać w internecie i czytać strony, np. dokumentację produktu albo artykuł, którego adres podajesz. Z Claude wyszukiwanie i czytanie stron wykonuje Anthropic. Z OpenAI Compass sam czyta tylko strony, których adresy podałeś w rozmowie (bez wyszukiwania); nie czyta adresów tego komputera ani sieci firmowej. Klucz claude.web_domains w ustawieniach (domeny po przecinku) zawęża dozwolone strony. Administrator huba może wyłączyć tę funkcję wszystkim ("web_access": false w polityce zespołu) albo ograniczyć domeny ("web_allowed_domains"). Każde wyszukiwanie i każda strona są widoczne w krokach odpowiedzi.

Co potrafi asystent? Asystent zna funkcje aplikacji z changelogu. Zapytaj go: „Co potrafisz w tej aplikacji?”.

7. Praca z modelem Enterprise Architect

Pisz tak, jak do współpracownika, który zna EA. Wskazuj pakiety i diagramy po nazwie. Asystent wskazuje obiekty modelu nazwą, pakietem i GUID. Poniżej przykłady poleceń; przykłady uporządkowane według celu są w rozdziale 8.

Odczyt

Pokazany diagram pojawia się na czacie jako obrazek. Pod nim są przyciski Zapisz jako… i Otwórz w pełnym rozmiarze.

Analiza wpływu zmiany

Asystent idzie od wskazanego elementu po relacjach w głąb modelu (do 6 poziomów, w jedną albo obie strony, opcjonalnie tylko po wybranych typach relacji). Dla każdego dotkniętego elementu podaje relację, przez którą dochodzi wpływ, ścieżkę od elementu startowego i diagramy, na których element leży. Wynik możesz dostać jako opis, obrazek, dokument Word albo arkusz Excel.

Gdzie użyte są operacje

Dla klasy, komponentu albo interfejsu asystent znajduje, gdzie są wywoływane operacje (usługi) tego elementu: na diagramach sekwencji (komunikaty do elementu albo jego linii życia) i aktywności (akcje wywołujące operację), z pakietem i wywołującym. Podaje też operacje nieużywane na żadnym diagramie.

Rysowanie

Podprocesy BPMN

• Osadzony (embedded): kroki podprocesu są jego elementami podrzędnymi i są narysowane w jego prostokącie na tym samym diagramie.
• Zwinięty (collapsed): kroki są na osobnym diagramie, a dwukrotne kliknięcie podprocesu otwiera ten diagram. Asystent może też powiązać podproces (albo inny element) z istniejącym diagramem jako diagramem złożonym.
• Do istniejącego podprocesu asystent dodaje nowe kroki.

Zmiany w istniejącym modelu

Asystent zmienia też położenie i rozmiar elementu na diagramie bez zdejmowania go (połączenia zostają), wartości tagów elementów oraz nazwę, opis i stereotyp istniejącego diagramu.

Słowa kluczowe i legendy

Asystent ustawia słowa kluczowe elementów (pole Keywords w EA) i tworzy legendę diagramu z automatycznym kolorowaniem, jak w EA: elementy (według słowa kluczowego, stereotypu, statusu albo typu) i połączenia (na przykład według stereotypu) dostają kolor z legendy, a legenda pokazuje wartość, kolor i podpis.

Linie połączeń

• Styl linii (jak Line Style w EA): prosta, automatyczna, łamana, prostokątna, prostokątna zaokrąglona, drzewo i boczna; dla wybranych połączeń albo wszystkich na diagramie.
• Trasa połączenia: asystent prowadzi linię przez wskazane punkty załamania i miejsca styku z bokami elementów, na przykład według szkicu na zrzucie ekranu.
• Ukrywanie połączeń na jednym diagramie (i ponowne pokazywanie): relacja zostaje w modelu i na innych diagramach, więc gęsty diagram odciążysz bez usuwania relacji.

Kopia pakietu i baseline

• Kopia pakietu tworzy duplikat pakietu z całą zawartością.
• Baseline to zapisana wersja pakietu w EA. Asystent ma polecenie robić baseline przed usuwaniem albo większą przebudową istniejącego pakietu, ale aplikacja tego nie wymusza. Przy ważnych pakietach poproś o baseline wprost i pracuj w trybie ask.
• Przywracanie wykonujesz w Enterprise Architect: kliknij pakiet prawym przyciskiem myszy, wybierz Manage Baselines, zaznacz baseline i użyj Compare/Restore. Asystent nie przywraca baseline'ów sam, bo przywracanie przez automatyzację zawiesza EA.

Słownik projektu EA

Asystent dodaje pojęcia do słownika projektu EA (Project Glossary): pojęcie z definicją i typem, domyślnie typ Glossary. Polskie pojęcie trafia do słownika we wszystkich formach odmiany (w liczbie pojedynczej i mnogiej, od mianownika do wołacza), więc EA podświetla w notatkach każdą jego formę. Pojęcie dodasz prośbą w rozmowie albo z pola wiadomości: kliknij słowo prawym przyciskiem myszy i wybierz Dodaj „…” do słownika projektu EA. Jeśli asystent nie zna definicji albo typu pojęcia, zapyta Cię o nie.

Scenariusze elementów

Asystent tworzy, zmienia i usuwa scenariusze elementów, na przykład przypadków użycia. Są to scenariusze strukturalne, widoczne w EA w zakładce Scenarios elementu, z krokami wykonywanymi przez aktora albo przez system.

Instrukcje modelowania zespołu

Zasady zespołu dla repozytorium (nazewnictwo, typy elementów i stereotypy, struktura pakietów, diagramy, wymagane wartości tagów, kontrole jakości) mogą być zapisane w samym repozytorium EA: w notatkach elementu Artifact ze stereotypem «CompassInstructions» o nazwie „Loonar Compass – modelling instructions”. Każdy, kto otwiera repozytorium w Compassie, pracuje według tych samych zasad, a historię zmian prowadzi sam EA (audyt, baseline, kontrola wersji).

• Asystent dostaje instrukcje w każdej odpowiedzi i stosuje je jako konwencje repozytorium.
• Kreator na start: gdy repozytorium nie ma jeszcze instrukcji, asystent je analizuje (typy elementów i stereotypy, relacje, diagramy, pakiety, wartości tagów, statusy, przykładowe nazwy) i pokazuje szkic zasad. Zapisuje je dopiero po Twojej zgodzie.
• Zmiany: asystent zastępuje instrukcje albo dopisuje do nich jedną zasadę, na przykład Twoją poprawkę. Każdy zapis jest zmianą modelu i przechodzi zwykłe zatwierdzanie (rozdział 16). Element powstaje w pierwszym pakiecie pod korzeniem modelu, chyba że wskażesz inny pakiet.
• Instrukcje mają najwyżej 20 000 znaków. Notatki elementu możesz też edytować sam w EA.

Instrukcje repozytorium obowiązują wszystkich, którzy z nim pracują; pamięć asystenta (rozdział 15) przechowuje Twoje własne ustalenia na tym komputerze.

Kontrola jakości modelu

Jednym poleceniem asystent sprawdza pakiet razem z podpakietami. Sprawdzenie wykonuje program, a nie model AI, więc nic nie jest zgadywane. Wbudowane kontrole:

• domyślne i puste nazwy (na przykład Class1, Activity 2),
• elementy bez opisu,
• osierocone elementy (bez relacji i na żadnym diagramie),
• powtórzone nazwy w pakiecie i powtórzone relacje,
• relacje elementu do samego siebie oraz do nieistniejących elementów,
• relacje niedozwolone w ArchiMate 3.2 (opis niżej),
• puste pakiety i puste diagramy.

Każde ustalenie ma wagę: błąd, ostrzeżenie albo informacja. Poprawki asystent wprowadza dopiero po Twojej zgodzie.

Reguły organizacji. Własne reguły wpisujesz w pliku governance.json, który leży obok app.properties (pliku ustawień w folderze danych użytkownika). Gdy takiego pliku nie ma, a Compass jest połączony z hubem zespołu, reguły pochodzą z polityki zespołu (rozdział 22). Przykład:

{"naming":[{"applies_to":"Component","pattern":"*Service","message":"Nazwa komponentu kończy się na Service"}],
 "required_tags":[{"applies_to":"«ArchiMate_ApplicationComponent»","tag":"Owner"}],
 "allowed_relations":[{"connector_type":"Realisation","source":"Component","target":"Interface"}]}

• naming: nazwy elementów danego typu muszą pasować do wzorca (pattern); message to treść ustalenia.
• required_tags: element danego typu musi mieć wskazany tagged value.
• allowed_relations: typ relacji wpisany na tej liście jest dozwolony tylko między wymienionymi końcami; typy relacji, których na liście nie ma, nie są ograniczane.

W applies_to podajesz typ elementu albo «stereotyp»; działają symbole wieloznaczne * i ?.

Relacje ArchiMate 3.2. Gdy relacja i oba jej końce mają stereotypy ArchiMate (na przykład «ArchiMate_ApplicationComponent», «ArchiMate_DataObject»), kontrola stosuje też reguły relacji ArchiMate 3.2, bez żadnej konfiguracji. Zgłasza tylko pewne naruszenia, jako błędy; połączeń, które mogłaby uzasadnić relacja wyprowadzona, nie zgłasza. Na przykład:

• relacja access musi kończyć się na elemencie struktury pasywnej (obiekt biznesowy, obiekt danych, artefakt…) i zaczynać od elementu zachowania lub struktury aktywnej,
• relacja influence musi kończyć się na elemencie motywacji,
• relacje triggering, flow i serving nie łączą elementów struktury pasywnej ani elementów motywacji,
• assignment prowadzi od struktury aktywnej do zachowania (albo od węzła do artefaktu),
• specialization łączy dwa elementy tego samego typu,
• element motywacji realizuje (realization) tylko inny element motywacji.

Węzły połączeń (junction) i grupowania (grouping) nie są sprawdzane. Kontrola na bieżąco w Compass w EA (rozdział 10) stosuje te same reguły. Reguły ArchiMate wyłączysz wpisem "archimate": false w governance.json.

Analiza luk as-is / to-be

Asystent porównuje dwa pakiety, na przykład stan obecny i docelowy, i podaje, co jest nowe, co jest do wycofania i co się zmieniło (stereotyp, opis, relacje). Wynik możesz zapisać do Excela.

Łańcuch wymagań: model, kod, testy, zgłoszenia

Gdy zestawiasz wymagania z modelem (podrozdział 8.5) i podasz też folder z kodem, asystent (narzędzie trace_requirements) prowadzi każde wymaganie dalej: wymaganie → element modelu → kod → test → klucze zgłoszeń. Folder czyta tylko do odczytu.

• Kod: pliki, które deklarują typ nazwany tak jak powiązany element modelu, oraz pliki źródłowe, które wymieniają identyfikator wymagania.
• Testy: pliki testów (w folderze testów albo o nazwach w rodzaju OrderTest.java, order.spec.ts, test_order.py), które wymieniają identyfikator wymagania albo dotyczą typu z tego kodu.
• Zgłoszenia: klucze w rodzaju ARCH-123 w treści wymagania i w powiązanych elementach (nazwa, alias, notatki, tagged values).

Każde wymaganie dostaje status: kompletny albo przerwany: brak w modelu, brak kodu lub brak testów.

CMDB a model

Asystent porównuje pozycje konfiguracji (CI) z bazy CMDB z modelem (narzędzie cmdb_compare). Tylko czyta: niczego nie zapisuje ani w modelu, ani w CMDB.

• Dane: eksport CSV albo JSON, na przykład eksport listy z ServiceNow albo JSON z jego Table API ({"result": [...]}), podany jako ścieżka albo załącznik, albo dane, które w rozmowie zwrócił serwer MCP bazy CMDB. Kolumny takie jak nazwa (name), sys_id, klasa (class), właściciel (owned_by) i status (install_status) są rozpoznawane po nagłówkach.
• Dopasowanie: po identyfikatorze CMDB zapisanym w tagged value elementu (sys_id albo CMDB id), a gdy go nie ma, po nazwie.
• Elementy: domyślnie komponenty, węzły, urządzenia, środowiska wykonawcze oraz komponenty aplikacji, węzły, oprogramowanie systemowe i usługi ArchiMate. Możesz wskazać inne typy albo stereotypy i zawęzić porównanie do pakietu.
• Raport: tylko w CMDB, tylko w modelu oraz inny właściciel (tagged value Owner) albo status.

Drugie polecenie wymaga serwera MCP ServiceNow w karcie Serwery MCP (zobacz „Własne serwery MCP” niżej). Na życzenie asystent dopisuje do modelu brakujące elementy, właścicieli albo identyfikatory (po Twojej zgodzie) albo zapisuje raport do Excela. W potoku CI to samo porównanie robi opcja --cmdb (rozdział 23).

Czytanie dokumentów

Asystent czyta dokumenty na Twoim komputerze, które wskażesz w rozmowie (narzędzie read_document), w tych samych formatach co załączniki (rozdział 6): PDF (każda strona), PowerPoint .pptx (slajdy z notatkami), Visio .vsdx (strony, kształty z tekstem i połączenia A → B), Excel .xlsx (arkusze i komórki), Word .docx, HTML i pliki tekstowe. O plik, który nie jest załącznikiem rozmowy, najpierw pyta. PDF bez warstwy tekstu (skanu) nie da się tak przeczytać: dołącz go do rozmowy, a model przeczyta jego strony jako obrazy. Stare formaty (.doc, .ppt, .xls, .vsd) trzeba najpierw zapisać w nowym formacie. Tak samo czytane są dokumenty z biblioteki SharePoint zespołu (rozdział 13).

Wymagania do porównania z modelem (punkt 8.5) i do łańcucha wymagań mogą też pochodzić z plików PDF, PowerPoint, Visio i Excel, w rozmowie i w trybie sprawdzania (--requirements, rozdział 23).

Zgłoszenia Jira

Po uzupełnieniu karty Jira (rozdział 5) asystent czyta zgłoszenia po kluczu albo wyszukiwaniem JQL i używa ich jako kontekstu: rysuje diagramy na podstawie opisu zgłoszenia (story) albo sprawdza, czy model pokrywa jego wymagania. Zawsze po Twojej zgodzie w panelu zatwierdzania tworzy zgłoszenia, dodaje komentarze i linki do elementów modelu.

Asystent zmienia też istniejące zgłoszenia: tytuł, opis i etykiety (dodaje i usuwa), np. poprawia kryteria akceptacji w kilku zgłoszeniach naraz. Story albo przypadek użycia z epikiem jako rodzicem zakłada w Jira Cloud przez pole rodzica, a w Jira Server i Data Center przez pole Epic Link, które sam odnajduje. Przy serii zgłoszeń kliknij w panelu zgody Zatwierdź wszystkie zgłoszenia Jira do zamknięcia Compassa: kolejne zgłoszenia i zmiany idą bez pytania.

Sprawdzenie zapisu

Po każdym zapisie Compass czyta model jeszcze raz i porównuje go z prośbą: czy utworzone obiekty istnieją, czy nowe relacje mają wskazane końce, czy nowe elementy są we wskazanym pakiecie, czy zmienione nazwy, opisy, stereotypy i tagged values mają nowe wartości oraz czy usunięte obiekty zniknęły. Różnice trafiają do asystenta, który ma o nich powiedzieć, a nie napisać „gotowe”.

Zapis jest wszystko albo nic: jeśli nie uda się w połowie, obiekty, które już powstały, są usuwane. Usunięcie elementu, który ma relacje, zawsze wymaga Twojej zgody (także w trybie auto), a lista tych relacji jest pokazana w panelu zgody.

Zawsze z pytaniem i pełnymi danymi. Zapis plików (eksport XMI, dokumenty z szablonów dokumentów EA) i import XMI zawsze wymagają Twojej zgody, także w trybie auto, a panel pokazuje pełną ścieżkę. Przyjmowane są tylko pełne ścieżki na dysku lokalnym: udziały sieciowe oraz foldery systemowe, programów i danych aplikacji są odrzucane. Identyfikator musi być liczbą. Zapis ustalenia w pamięci asystenta, zapis szablonu dokumentu oraz zapis i uruchomienie skryptu EA też zawsze wymagają zgody, a panel pokazuje cały tekst albo kod (teksty dłuższe niż 20 000 znaków są odrzucane); skrypt działa dokładnie tak, jak go pokazano, razem z dołączeniami !INC. Akcje kontroli wersji pakietu i wysyłanie plików do SharePoint też zawsze wymagają zgody. Gdy asystent chce przeczytać plik, który nie jest załącznikiem rozmowy (dokument wymagań, folder z kodem), najpierw pyta.

Własne serwery MCP

Własne serwery MCP dają asystentowi dodatkowe narzędzia, na przykład system zgłoszeń, repozytorium albo firmową bazę wiedzy. Serwery wpisujesz w pliku mcp_servers.json obok pliku ustawień, a sprawdzasz w karcie Serwery MCP. Serwer może być programem lokalnym (command i args, komunikacja przez stdio) albo usługą HTTP (url i headers, Streamable HTTP):

{"servers":[{"name":"hub","url":"http://127.0.0.1:8730/mcp","headers":{"Authorization":"Bearer ${secret:hub_token}"}},
 {"name":"files","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","C:/docs"]}]}

• ${secret:nazwa} to wpis w Menedżerze poświadczeń Windows, a ${env:NAZWA} to zmienna środowiska; dzięki temu tokeny nie leżą w pliku.
• Każde wywołanie narzędzia pyta o Twoją zgodę, chyba że serwer ma "trusted": true. Ustawiaj to tylko dla serwerów, którym ufasz: to, że serwer sam deklaruje narzędzie jako tylko do odczytu, nie wystarcza.
• Własnych kluczy i haseł Compassa (klucze dostawców AI, hasła i tokeny bazy, EA, Confluence, Jiry i Miro) nie można użyć w ${secret:…}. Jedyny wyjątek to ${secret:hub_token} w nagłówkach własnego punktu MCP huba zespołu (adres huba z Ustawień ze ścieżką /mcp), jak w przykładzie powyżej. Tokeny innych serwerów zapisz pod ich własnymi nazwami w Menedżerze poświadczeń Windows.
• Program lokalny (command) dostaje tylko podstawowe zmienne środowiska Windows (PATH, TEMP, foldery profilu użytkownika, ustawienia proxy…) i zmienne wymienione w jego "env".
• "command": "npx" działa: Compass uruchamia npx.cmd (tak samo npm, pnpm i yarn). Serwery uruchamiane przez npx wymagają Node.js na komputerze.
• Logowanie inne niż nagłówek. Serwer HTTP może mieć "auth" zamiast nagłówka Authorization: {"type": "basic", "user": …, "password": …} dla nazwy użytkownika i hasła albo {"type": "oauth2", "token_url": …, "client_id": …, "client_secret": …, "scope": …} dla poświadczeń klienta OAuth2: Compass pobiera token z token_url i wysyła go jako Bearer. Hasła i klucze tajne trzymaj w Menedżerze poświadczeń jako ${secret:mcp_…}.
• Przycisk Zapisz i sprawdź serwery MCP łączy się z każdym serwerem i pokazuje liczbę jego narzędzi.

Gotowe serwery. W karcie Serwery MCP wybierz serwer z listy Dodaj gotowy serwer i kliknij Dodaj: jego wpis trafia do tekstu mcp_servers.json, gdzie go uzupełniasz i zapisujesz kartę. Nazwa, która już jest użyta, dostaje numer.

Token serwera MCP. Wpisz nazwę zaczynającą się od mcp_ (litery, cyfry i _, na przykład mcp_github) i token, a potem kliknij Zapisz i sprawdź serwery MCP. Token trafia do Menedżera poświadczeń Windows; w mcp_servers.json używasz go jako ${secret:mcp_github}. To samo pole zapisuje hasło albo klucz tajny klienta serwera z "auth", na przykład:

{"servers":[{"name":"wiki","url":"https://mcp.example.com/mcp",
  "auth":{"type":"oauth2","token_url":"https://login.example.com/oauth2/token",
          "client_id":"compass","client_secret":"${secret:mcp_wiki}","scope":"mcp.read"}}]}

Skrypty EA

Asystent pokazuje grupy skryptów i skrypty modelu, czyta skrypt, zapisuje skrypt (JScript, VBScript albo JavaScript; brakująca grupa powstaje sama) i go uruchamia. Zapis i uruchomienie skryptu wymagają zgody, także w trybie auto, bo skrypt może zmienić w modelu wszystko. Po Twojej zgodzie kolejne skrypty tej samej budowy (ten sam kod z innymi danymi) nie pytają ponownie, a przycisk Zatwierdź wszystkie skrypty do zamknięcia Compassa wyłącza pytania o skrypty do zamknięcia aplikacji; panel zgody pokazuje cały kod. Skrypt działa w otwartym oknie EA albo, gdy go nie ma, w osobnej sesji EA działającej w tle. Repository i Session.Output działają jak w EA, a dołączenia !INC Grupa.Skrypt są rozwiązywane z modelu. Jeśli w EA jest otwarty inny model, uruchomienie kończy się komunikatem.

Technologie MDG i API EA

• Technologie MDG (narzędzie mdg_technologies): które profile model faktycznie wykorzystuje i ile razy; pliki technologii EA i Twoje własne; technologie zaimportowane do modelu. Dla technologii (na przykład ArchiMate3, BPMN2.0, SysML1.5) asystent podaje jej stereotypy z metatypem i tym, do czego się stosują, a dla stereotypu jego wartości tagów z typem, dozwolonymi wartościami i wartością domyślną. Korzysta z tego, zanim utworzy elementy ze stereotypami technologii i zanim wypełni wartości tagów.
• API EA (narzędzie ea_api): interfejs automatyzacji EA odczytany z biblioteki typów EA.tlb EA zainstalowanego na tym komputerze (ścieżka do EA.exe w Ustawieniach): klasy, właściwości (tylko do odczytu albo do odczytu i zapisu), metody z parametrami i wyliczenia. Asystent sprawdza je przed napisaniem skryptu EA, żeby nazwy właściwości i metod pasowały do Twojej wersji EA.

Kontrola wersji pakietów

Gdy pakiety modelu są w EA pod kontrolą wersji (SVN, Git, TFS albo udział plików), asystent czyta ich stan (narzędzie version_control_status): konfigurację, plik, kto ma który pakiet pobrany do edycji (checked out), ostatni zapis i wczytanie. Na Twoją prośbę wykonuje dla pakietu check out, check in (z komentarzem), get latest, put latest albo resync. Każda z tych akcji zawsze wymaga Twojej zgody, w każdym trybie. Pakiet musi już być pod kontrolą wersji w EA (Package → Version Control → Add Package to Version Control); asystent nie konfiguruje kontroli wersji.

Dalsze operacje na modelu

• Automatyczny układ diagramu: kierunek w dół, w prawo, w górę albo w lewo i odstęp.
• XMI: eksport pakietu do pliku XMI i import pakietu z pliku (import zastępuje identyfikatory GUID, chyba że poprosisz o ich zachowanie).
• Dokumenty powiązane elementów (linked documents), tworzone z tekstu.
• Pasy (swimlanes) diagramu.
• Odwrócenie relacji (zamiana końców).
• Edycja pakietu: nazwa, opis, wersja, status i stereotyp.
• Dokument z szablonu dokumentów EA (DOCX, PDF albo RTF), na przykład szablon „Model Report”, jak w EA: Publish → Report Builder.

Pisownia w języku Compassa

Narzędzie asystenta spell_check sprawdza notatki elementów i diagramów, kroki scenariuszy oraz słownik projektu słownikiem pisowni Windows w języku Compassa (korekta pisowni samego EA ma tylko słowniki angielskie). Nazwy elementów i pojęcia ze słownika projektu są uznawane za znane słowa. Asystent podaje podpowiedzi, a poprawia dopiero po Twojej zgodzie. Jeśli Windows nie ma słownika dla tego języka, dodaj język w Ustawieniach Windows → Czas i język → Język. W Compass w EA notatki zmienionego elementu są sprawdzane na bieżąco (linie „✎ Pisownia: …” w System Output, rozdział 10).

O czym warto wiedzieć

• Pierwsze wywołanie EA trwa od kilku do kilkunastu sekund, bo aplikacja uruchamia Enterprise Architect w tle i otwiera model. Kolejne zapisy i pobrania diagramów trwają już krócej niż sekundę. Po 10 minutach bez wywołań EA w tle zamyka się i zwalnia licencję. Zamknięcie aplikacji też zamyka jej sesję EA. Compass w EA (rozdział 10) nie uruchamia EA w tle: zapisuje przez Twoje okno EA.
• Blokady. Gdy w karcie Model jest włączona opcja „Model wymaga blokady do edycji”, asystent blokuje obiekt na swoje konto na czas zapisu i po zapisie blokadę zdejmuje. Obiektu zablokowanego przez innego użytkownika nie zmieni; komunikat podaje, kto blokuje element (konto lub grupa, od kiedy), jego pakiet i diagram.
• Usuwanie jest trwałe. Usunięcie pakietu usuwa całą jego zawartość. W trybach ask i plan usuwanie zawsze wymaga osobnej zgody, a panel zgody podaje nazwy usuwanych obiektów (rozdział 16). Przy ważnych modelach używaj trybu ask, proś o baseline i rób kopie zapasowe bazy.
• Zapis „wszystko albo nic”. Gdy jedna z operacji zapisu się nie uda, obiekty utworzone wcześniej w tym zapisie są usuwane, więc w modelu nie zostaje nic niedokończonego; komunikat podaje przyczynę.
• Sprawdzaj wynik. Asystent może się pomylić: źle odczytać zdjęcie, wybrać inny typ elementu albo ułożyć diagram nieczytelnie. Poproś o pokazanie diagramu po zmianach i o poprawki.
• Duże diagramy asystent zapisuje w kilku krokach. To normalne.

8. Przykłady użycia

Ten rozdział zbiera przykładowe polecenia według celu. Wypróbowano je na modelu przykładowym z pakietem „Shop domain”, procesem „Order process” i diagramem „Domain model”; w swoim modelu wstaw nazwy własnych pakietów, diagramów i elementów. Asystent nie wymaga dokładnych sformułowań: ważne są nazwy obiektów i to, czego oczekujesz. Szczegóły funkcji są w rozdziale 7, a zasady zatwierdzania zmian w rozdziale 16.

8.1 Pytanie o model

Odczyt modelu niczego nie zmienia i nie wymaga zgody. Compass czyta model przez bazę albo plik EA, a asystent odpowiada na tej podstawie i wskazuje obiekty nazwą, pakietem i GUID. Analiza wpływu idzie po relacjach w głąb modelu i podaje też diagramy, na których leżą dotknięte elementy.

Co zobaczysz: kartę kroków z odczytami modelu, a potem odpowiedź na czacie. Przy pytaniu o wpływ każdy element ma relację, przez którą dochodzi wpływ, ścieżkę od elementu startowego i listę diagramów. Okno zgody się nie pojawia.

Wskazówka: dopisz „wynik daj w Excelu”, jeśli lista jest długa: dostaniesz arkusz zamiast tekstu na czacie.

8.2 Tworzenie i zmiana modelu

Asystent tworzy pakiety, diagramy, elementy i relacje oraz zmienia istniejące: nazwy, opisy, tagged values, położenie na diagramie. Zmiany zapisuje do EA dopiero po Twojej zgodzie (w trybie ask przed każdym zapisem, w trybie plan przed pierwszym zapisem odpowiedzi; rozdział 16).

Co zobaczysz: nad polem wiadomości panel „Asystent chce zapisać zmiany w modelu” z opisem zmian i częścią „Przed → po:”: co powstaje, co zmienia się z jakiej wartości na jaką (pole: stara → nowa wartość) i co jest usuwane. Przy trzecim poleceniu zobaczysz tam zmianę dla każdej klasy. Przycisk Zatwierdź zapisuje zmiany, a Odrzuć niczego nie zmienia i pozwala opisać asystentowi, co ma zrobić inaczej.

• Sprawdzenie po każdym zapisie. Compass czyta model jeszcze raz i porównuje go z prośbą (czy obiekty istnieją, czy relacje mają wskazane końce, czy nowe wartości są zapisane). Asystent mówi tylko to, co model potwierdził, a różnice zgłasza zamiast pisać „gotowe”.
• Wszystko albo nic. Jeśli zapis nie uda się w połowie, obiekty, które już powstały, są usuwane.
• Usuwanie elementu z relacjami zawsze pyta o zgodę, także w trybie auto, a panel wymienia te relacje.

Wskazówka: przy zmianie masowej, jak w trzecim poleceniu, przeczytaj „Przed → po” przed zatwierdzeniem: tam widać każdą zmianę.

8.3 Cofanie zmian

Każdy zapis asystenta trafia do dziennika cofania („wehikuł czasu”) razem z operacjami odwrotnymi. Cofnięcie usuwa utworzone obiekty, a zmienionym polom, tagged values, położeniom i przeniesieniom przywraca poprzednie wartości. Dotyczy to zapisów asystenta w tym modelu; zmian wykonanych ręcznie w EA nie obejmuje.

Co zobaczysz: przy historii listę zapisów od najnowszego, z informacją, co da się cofnąć. Przy cofaniu panel zgody „Cofnąć ostatnie zapisy asystenta (…)” z listą zapisów (pojawia się w każdym trybie); po zatwierdzeniu Compass cofa zapisy i sprawdza wynik w modelu. Gdy nic nie ma do cofnięcia, asystent mówi, że w tym modelu nie ma nic do cofnięcia.

Usunięcia, importy i automatyczny układ diagramu nie dają się cofnąć operacjami. Przed takim zapisem Compass robi w EA baseline pakietu, którego dotyczy zmiana. Przywracasz go w Enterprise Architect: kliknij pakiet prawym przyciskiem myszy, wybierz Manage Baselines, zaznacz baseline i użyj Compare/Restore.

Wskazówka: możesz cofnąć kilka zapisów naraz („Cofnij trzy ostatnie zmiany”); najpierw poproś o historię, żeby zobaczyć, co wejdzie w cofnięcie.

8.4 Jakość modelu i reguły zespołu

Kontrolę jakości wykonuje program, nie model AI, więc nic nie jest zgadywane: domyślne i puste nazwy, elementy bez opisu, osierocone elementy, powtórzenia, relacje do nieistniejących elementów, relacje niedozwolone w ArchiMate 3.2, puste pakiety i diagramy oraz reguły z pliku governance.json (albo z polityki zespołu w hubie). Pisownię notatek sprawdza słownik Windows w języku Compassa.

Przykład krótkiego pliku governance.json (leży obok app.properties), który wymaga tagged value Owner na każdej klasie:

{"required_tags":[{"applies_to":"Class","tag":"Owner"}]}

Co zobaczysz: podsumowanie sprawdzenia i ustalenia z wagą: błąd, ostrzeżenie albo informacja. Przy pisowni: liczbę sprawdzonych tekstów i słów oraz listę możliwych błędów z podpowiedziami. Okno zgody pojawia się dopiero, gdy poprosisz o poprawki. Jeśli Windows nie ma słownika dla języka Compassa, dodaj język w Ustawieniach Windows → Czas i język → Język.

Wskazówka: po sprawdzeniu poproś o poprawienie jednej grupy ustaleń naraz, na przykład „Uzupełnij brakujące opisy klas w pakiecie Shop domain”. Zapis przejdzie przez zwykłe zatwierdzanie i sprawdzenie po zapisie.

8.5 Dokument wymagań a model

Asystent czyta wymagania z dokumentu (Word .docx, PDF, PowerPoint .pptx, Visio .vsdx, Excel .xlsx, .txt, .md, załącznik rozmowy, strona Confluence po ID albo wklejony tekst) i zestawia je z modelem. Wymaganie to wiersz albo wiersz tabeli zaczynający się od identyfikatora, na przykład W1, R.1.2, REQ-12, FR-01. Dopasowanie robi program: szuka elementów z tym identyfikatorem (w nazwie, aliasie, notatkach, tagged values), relacji śledzenia i podobnych słów. Kandydatów ocenia asystent.

Co zobaczysz: przy pliku, który nie jest załącznikiem rozmowy, najpierw pytanie, czy asystent może go przeczytać; potem podsumowanie „Śledzenie wymagań: … wymagań – pokryte …, tylko kandydaci …, NIEPOKRYTE …, zgodne ID przy innej treści …” i listę wymagań z jednym z czterech statusów: pokryte, kandydaci, NIEPOKRYTE albo ZGODNE ID, INNA TREŚĆ. Osobna lista to „Elementy modelu, do których nie odnosi się żadne wymaganie”. Asystent wskazuje też wymagania sprzeczne z modelem. Macierz w Excelu dostajesz jako kartę pliku z przyciskami Otwórz i Zapisz jako…. Relacje śledzenia (Realisation albo Dependency «trace») powstają dopiero po Twojej zgodzie, w zwykłym panelu zatwierdzania.

Wskazówka: stronę Confluence można czytać po uzupełnieniu karty Confluence w Ustawieniach (rozdział 5). Dopasowanie jest najpewniejsze, gdy identyfikator wymagania wpisano w nazwę, alias, notatkę albo tagged value elementu; bez niego zostają tylko kandydaci. Zakres możesz zawęzić do pakietu: „…z pakietem Shop domain”. Dodaj folder z kodem, żeby prześledzić wymagania dalej, do kodu, testów i zgłoszeń (rozdział 7, „Łańcuch wymagań”).

8.6 Model a kod

Asystent czyta folder z kodem (na przykład lokalny klon repozytorium) tylko do odczytu i porównuje go z modelem: klasy, interfejsy, enumy i rekordy z polami (Java, Kotlin, C#, TypeScript, Rust, Python), tabele i kolumny z SQL (CREATE TABLE) oraz operacje API (operationId z OpenAPI) z klasami, atrybutami, tabelami i operacjami w modelu.

Co zobaczysz: najpierw pytanie, czy asystent może przeczytać folder, potem podsumowanie „Model ↔ kod: plików źródłowych …” i sekcje: W kodzie, brak w modelu, W modelu, brak w kodzie, Różne pola (kod vs atrybuty modelu), Tabele bazy danych oraz Operacje API (OpenAPI operationId) bez odpowiednika w modelu. Zgoda na zapis nie jest potrzebna, bo nic nie jest zapisywane: ani w kodzie, ani w modelu.

Wskazówka: ogranicz porównanie do jednego pakietu („…z pakietem Shop domain”), jeśli folder zawiera wiele usług, i poproś o raport w Excelu. Uzupełnienie modelu o brakujące klasy to osobna prośba, która przejdzie przez zwykłe zatwierdzanie.

8.7 Wycena zmiany

Z wpływu zmiany w modelu asystent buduje wstępną wycenę: elementy do zmiany, powiązane elementy do dostosowania, dalsze do sprawdzenia i diagramy do aktualizacji dostają wiersze WBS w prostym języku funkcjonalnym, z godzinami zależnymi od typu elementu. Do tego dochodzą testy, analiza i dokumentacja oraz bufor ryzyka.

Co zobaczysz: tabelę WBS z wierszami w rodzaju „Zmiana: Product”, „Dostosowanie: …”, „Sprawdzenie wpływu na: …”, „Aktualizacja diagramu: …”, „Testy zmiany”, „Analiza i dokumentacja” i „Bufor ryzyka”, podsumowanie w godzinach i osobodniach, „Godziny według typu” oraz „Ryzyka” (na przykład element z wieloma relacjami, bez opisu albo zmiana dotykająca wielu pakietów). Excel to karta pliku z przyciskami Otwórz i Zapisz jako….

Wskazówka: to punkt wyjścia z modelu, a nie oferta: skoryguj godziny wiedzą zespołu. Normy godzinowe są w pliku estimate.json obok pliku ustawień; gdy go nie ma, działają normy domyślne.

8.8 Dokumenty i eksporty

Asystent przygotowuje dokumenty Word z treści modelu i diagramów (rozdział 13). Enterprise Architect generuje też raport z własnego szablonu dokumentów EA (DOCX, PDF albo RTF) i eksportuje pakiety do XMI. Raport i eksport XMI zawsze wymagają Twojej zgody, także w trybie auto.

Co zobaczysz: dla dokumentu Word kartę pliku z przyciskami Otwórz i Zapisz jako…. Dla raportu i XMI panel zgody z opisem („dokumenty z szablonów EA”, „pakiety wyeksportowane do XMI”) i pełną ścieżką pliku, a po zapisie komunikat „zapisano raport: …” albo „zapisano XMI: …” ze ścieżką; Compass sprawdza, czy plik powstał.

Wskazówka: raport musi mieć rozszerzenie .docx, .pdf albo .rtf, a plik XMI .xml albo .xmi. Podaj pełną ścieżkę na dysku lokalnym: udziały sieciowe oraz foldery systemowe, programów i danych aplikacji są odrzucane. Szablon o podanej nazwie musi istnieć w EA; gdy go nie ma, EA nie utworzy raportu i asystent to zgłosi.

8.9 Diagramy

Poza rysowaniem nowych diagramów asystent poprawia istniejące: układa je automatycznie (w dół, w prawo, w górę albo w lewo, z podanym odstępem), dodaje tory (swimlanes) i tworzy dokumenty powiązane (linked documents) elementów z podanego tekstu.

Co zobaczysz: zwykły panel zgody z opisem zmiany, a po zapisie sprawdzenie modelu. Jeśli masz otwarty ten sam model w EA, zmieniony diagram odświeża się w Twoim oknie sam (rozdział 9).

Wskazówka: po zmianie poproś „Pokaż diagram Domain model”: zobaczysz go jako obrazek na czacie i ocenisz, czy układ jest czytelny. Automatycznego układu nie da się cofnąć operacjami, więc Compass robi wcześniej baseline pakietu (podrozdział 8.3).

8.10 Skrypty EA

Asystent pisze skrypty EA (JScript, VBScript albo JavaScript) i uruchamia je w modelu: wypisują dane, sprawdzają coś albo zmieniają wiele obiektów naraz. Brakująca grupa skryptów powstaje sama. Skrypt działa w otwartym oknie EA, a gdy go nie ma, w osobnej sesji EA w tle.

Co zobaczysz: najpierw panel zgody na zapis skryptu (grupa, nazwa, język i cały kod), potem osobne pytanie o zgodę na uruchomienie: oba pojawiają się za każdym razem, także w trybie auto, bo skrypt może zmienić w modelu wszystko. Skrypt działa dokładnie tak, jak go pokazano, razem z dołączeniami !INC. Wynik (to, co skrypt wypisał przez Session.Output) trafia na czat jako „Wynik skryptu …”. Jeśli w EA jest otwarty inny model, uruchomienie kończy się komunikatem.

Wskazówka: zanim zatwierdzisz uruchomienie, przeczytaj kod skryptu w oknie zgody, zwłaszcza gdy skrypt ma coś zmieniać. Na początek pisz skrypty tylko do odczytu.

8.11 Jira i Confluence

Po uzupełnieniu kart Jira i Confluence w Ustawieniach (rozdział 5) asystent czyta zgłoszenia i strony jako kontekst: sprawdza, których elementów modelu dotyczy zgłoszenie, rysuje diagramy z jego opisu albo zestawia wymagania ze strony z modelem (podrozdział 8.5).

Co zobaczysz: przy czytaniu odczyt zgłoszenia w karcie kroków i odpowiedź z listą elementów. Tworzenie zgłoszeń, komentarzy i linków do elementów modelu zawsze wymaga Twojej zgody w panelu zatwierdzania, w każdym trybie. Publikacja strony w Confluence też zawsze pyta i mówi wprost, gdy zastąpi istniejącą stronę (rozdział 13).

Wskazówka: podawaj klucz zgłoszenia i nazwę pakietu. Gdy nie wskażesz projektu, nowe zgłoszenie powstaje w projekcie domyślnym z karty Jira.

8.12 Praca zespołowa (Compass Hub)

Z hubem zespołu (rozdział 22; karta Zespół (Compass Hub) w Ustawieniach) zmianę w modelu możesz najpierw zaproponować zespołowi: asystent niczego nie zapisuje w modelu, tylko wysyła do huba zestaw zmian z opisem i podglądem „przed → po”. Zespół komentuje go w widoku webowym, a architekt albo administrator zatwierdza lub odrzuca. Nikt, nawet administrator, nie może zatwierdzić własnego zestawu zmian. Zatwierdzony zestaw wprowadzasz w Compassie.

Co zobaczysz: po propozycji komunikat „Zestaw zmian dla zespołu: …” z numerem (CH-…), a w widoku webowym huba nowy wiersz w zakładce Change sets. Przy wprowadzaniu: zwykły panel zatwierdzania i sprawdzenie po zapisie; hub oznacza zestaw jako wprowadzony. Wprowadzić można tylko zestaw zatwierdzony i dotyczący tego modelu, i tylko raz: Compass najpierw rezerwuje go w hubie, a po zapisie zgłasza wynik.

Widok webowy. Osoby bez Enterprise Architect logują się w nim nazwą użytkownika i hasłem od administratora huba (adres https://<hub>/; http:// tylko na tym samym komputerze). Zakładki mają angielskie nazwy: Ask (pytania do modelu), Search (wyszukiwanie elementów), Model check (kontrola modelu według reguł zespołu), Gaps (luki as-is / to-be), Audit trail (zespołowy dziennik zmian), Team notes (wspólne notatki) i Change sets (propozycje zmian z komentarzami i decyzją). W zakładce Ask wpisujesz pytanie własnymi słowami, na przykład „Które systemy korzystają z bramki płatności?”. Asystent w tym miejscu tylko czyta model: nie ma dostępu do plików, Jiry, Confluence ani serwerów MCP i nie może niczego zaproponować ani zapisać. Odpowiada na jedno pytanie naraz (pytanie ma najwyżej 2000 znaków), a pytania trafiają do dziennika huba.

Wskazówka: nadaj propozycji tytuł, z którego recenzent pozna zakres zmiany bez otwierania szczegółów. Zestaw zmian jest przypisany do modelu: wprowadzisz go tylko w Compassie połączonym z tym samym modelem huba.

8.13 Dodatkowe narzędzia z serwerów MCP

Własne serwery MCP dają asystentowi dodatkowe narzędzia: system zgłoszeń, repozytorium, bazę wiedzy albo serwer MCP samego huba. Serwery wpisujesz w pliku mcp_servers.json (rozdział 7) albo dodajesz gotowe (Azure DevOps, GitHub, ServiceNow / CMDB, Files, Compass Hub) i sprawdzasz w Ustawieniach, w karcie Serwery MCP, przyciskiem Zapisz i sprawdź serwery MCP.

Co zobaczysz: w karcie kroków wywołanie narzędzia serwera, a potem jego wynik w odpowiedzi. Każde wywołanie narzędzia pyta o Twoją zgodę, chyba że serwer ma "trusted": true; ustawiaj to tylko dla serwerów, którym ufasz.

Wskazówka: w poleceniu podaj nazwę serwera z pliku mcp_servers.json („przez serwer MCP hub…”), żeby asystent wiedział, którego użyć. Tokeny trzymaj w Menedżerze poświadczeń Windows pod ich własnymi nazwami (${secret:nazwa}), nie w pliku; własnych kluczy i haseł Compassa nie można tam użyć (rozdział 7).

8.14 Compass w Enterprise Architect

Gdy Compass jest zadokowany w EA (rozdział 10), pilnuje modelu w trakcie Twojej pracy i nie wymaga żadnego polecenia. Wyniki trafiają do zakładki Loonar Compass okna System Output:

• Kontrola na bieżąco: po narysowaniu relacji i po edycji elementu (nazwy, stereotypu, tagged values) pojawia się „⚠ Kontrola modelu: …”, według tych samych reguł co w podrozdziale 8.4.
• Pisownia: notatki zmienionego elementu są sprawdzane w języku Compassa i dają „✎ Pisownia: …”.
• Agenci zdarzeń: własne reguły w pliku event_agents.json (karta Agenci zdarzeń (Compass w EA)) uruchamiają asystenta po zdarzeniu w EA. Jego uwagi zaczynają się od 🤖.

Przykładowa reguła, która po utworzeniu komponentu sprawdza właściciela i opis:

{"agents":[{"name":"Component owner","event":"element_created","applies_to":"Component",
  "prompt":"Check that the new component has an owner and a description; suggest what to fill in."}]}

Co zobaczysz: w System Output linię w rodzaju „🤖 Component owner: …” z uwagami asystenta. Agent tylko czyta model: nie ma dostępu do plików, Jiry, Confluence ani serwerów MCP i nie może niczego zaproponować ani zapisać. Ten sam agent reaguje na ten sam obiekt najwyżej raz na minutę. Nowy element jest sprawdzany dopiero po pierwszej edycji, bo EA nadaje mu najpierw nazwę Class1.

Wskazówka: pisz krótkie, konkretne polecenia agentów i zawężaj je przez applies_to (typ, «stereotyp» albo *). Po zmianie pliku kliknij Zapisz agentów zdarzeń. Agent może też pilnować usuwania i je zatrzymywać (punkt 8.22).

8.15 Sprawdzanie modelu w potoku CI

Tryb sprawdzania wykonuje kontrolę modelu, porównanie z kodem i z CMDB oraz łańcuch wymagań bez okna i bez modelu AI, a kończy się kodem wyjścia, który rozumie potok (rozdział 23).

LoonarCompass.exe --check --model model\shop.qea --rules governance.json --code src --requirements docs\wymagania.md --junit junit.xml --fail-on error --lang pl | Out-Host

Co zobaczysz: raport Markdown na standardowym wyjściu, który zaczyna się od wyniku, PASSED albo FAILED, a dalej ma sekcje kontroli modelu, modelu a kodu i wymagań. W potoku plik JUnit pokazuje każdą grupę ustaleń jako test, nieudany, gdy jej waga jest na progu --fail-on albo wyżej. Kod wyjścia to 0, gdy sprawdzenie przeszło, 1, gdy są takie ustalenia, i 2 przy błędnych argumentach albo modelu, którego nie da się odczytać.

Wskazówka: zacznij od --fail-on error i trzymaj ostrzeżenia w raporcie; przejdź na warning, gdy model będzie czysty. Trzymaj governance.json w repozytorium i podawaj go opcją --rules, żeby potok i ludzie stosowali te same reguły.

8.16 CMDB a model

Asystent porównuje pozycje konfiguracji z CMDB (eksport albo dane z serwera MCP) z komponentami modelu i pokazuje, czego brakuje po każdej stronie oraz gdzie różni się właściciel albo status (rozdział 7, „CMDB a model”).

Co zobaczysz: przy pliku, który nie jest załącznikiem rozmowy, najpierw pytanie, czy asystent może go przeczytać; przy serwerze MCP ServiceNow wywołanie jego narzędzia (z pytaniem o zgodę, chyba że serwer jest zaufany). Potem podsumowanie „CMDB ↔ model: pozycje CMDB: …, elementy modelu: …, dopasowane: …” i sekcje W CMDB, brak w modelu, W modelu, brak w CMDB oraz Inny właściciel lub status. Bez Twojej zgody nic nie jest zapisywane.

Wskazówka: trzymaj identyfikator CMDB (sys_id) w tagged value elementów: wtedy pozycje dopasują się także po zmianie nazwy. Zawęź porównanie do pakietu albo wskaż typy elementów, gdy model zawiera więcej niż CMDB.

8.17 Zgłoszenia Jira i strony Confluence z huba

Gdy administrator ustawi integrations w hub.json (rozdział 22), architekci i administratorzy tworzą zgłoszenia Jira i strony Confluence wprost z widoku webowego huba, bez Compassa i bez EA. Hub używa własnego konta technicznego.

• Search → kliknij element → Create Jira issue: wpisz podsumowanie; zgłoszenie dostaje szczegóły elementu.
• Change sets → otwórz zestaw zmian → Create Jira issue for this change set: jedno zgłoszenie na zestaw zmian.
• Wybierz pakiet w drzewie → Model check → Publish this package to Confluence: wpisz tytuł (pusty: nazwa pakietu i modelu).

Co zobaczysz: „Created ARCH-…” z linkiem do zgłoszenia; w zestawie zmian wiersz „Jira: ARCH-…”; przy Confluence „Created:” albo „Updated:” z linkiem do strony. Każda akcja trafia do zakładki Audit trail z Twoją nazwą.

Wskazówka: strona Confluence to tekstowe podsumowanie pakietu (elementy z opisami i relacje, bez diagramów), zastępowane przy każdej publikacji: zmieniaj model, nie stronę. Stronę z diagramami publikuj z Compassa (rozdział 13).

8.18 Instrukcje modelowania zespołu

Zasady zespołu dla repozytorium są zapisane w samym repozytorium, jako notatki elementu Artifact «CompassInstructions» (rozdział 7, „Instrukcje modelowania zespołu”). Asystent stosuje je w każdej odpowiedzi, u każdego, kto otwiera repozytorium.

Co zobaczysz: przy pierwszym poleceniu analizę repozytorium w krokach („Instrukcje modelowania: …”), potem szkic zasad pod nagłówkami (nazewnictwo, typy elementów i stereotypy, struktura pakietów, diagramy, relacje, wartości tagów, kontrole jakości) i pytanie, czy go zapisać. Zapis, a także dopisana zasada z drugiego polecenia, przechodzą przez zwykły panel zgody jako zmiana elementu „Loonar Compass – modelling instructions”.

Wskazówka: po poprawce, którą podałeś w rozmowie, poproś asystenta o dopisanie jej do instrukcji: wtedy obowiązuje cały zespół, nie tylko Ciebie. Osobiste preferencje należą do pamięci asystenta (rozdział 15).

8.19 Dokumenty: PDF, PowerPoint, Visio, Excel

Asystent czyta dokumenty, które dołączysz albo wskażesz: PDF, Word, PowerPoint z notatkami, Visio z kształtami i połączeniami, Excel z arkuszami (rozdział 7, „Czytanie dokumentów”).

Co zobaczysz: przy pliku, który nie jest załącznikiem, najpierw pytanie, czy asystent może go przeczytać, potem krok „Czytanie dokumentu …”. Przy rysunku Visio asystent proponuje elementy i przepływy na podstawie kształtów i połączeń; zapis przechodzi zwykłe zatwierdzanie.

Wskazówka: zeskanowany PDF nie ma tekstu: dołącz go do rozmowy zamiast podawać ścieżkę, a model przeczyta strony jako obrazy. Stare pliki .doc, .ppt, .xls i .vsd najpierw zapisz w nowym formacie.

8.20 Prezentacje i PDF

Asystent przygotowuje z modelu prezentacje PowerPoint (slajd tytułowy, slajdy z punktami i diagramami) oraz dokumenty Word także jako PDF (rozdział 13).

Co zobaczysz: krok „Przygotowanie prezentacji …” i kartę pliku z przyciskami Otwórz i Zapisz jako…; przy PDF drugą kartę z plikiem PDF. PDF tworzy Microsoft PowerPoint albo Word na tym komputerze.

Wskazówka: bez Microsoft Office prezentacja i dokument i tak powstają jako PPTX i DOCX; brakuje tylko PDF, a asystent o tym mówi.

8.21 Większe zadania: pytania, plan, podagenci

Przed większą zmianą asystent pyta o to, co niejasne, pokazuje plan i może przekazać analizy podagentom (rozdział 6, „Pytania, plan i podagenci”).

Co zobaczysz: formularz „Pytania do Ciebie” (na przykład który pakiet, jaka notacja), z wyborem odpowiedzi i polem „Coś innego…”. Po Wyślij odpowiedzi w krokach plan „📋 Plan: 0 z 4 zrobione”, aktualizowany znakami ✓ ▶ ○ w trakcie pracy. Pracę podagenta widać jako krok „Podagent (impact): …”, a po nim jego zwięzły wynik.

Wskazówka: jeśli znasz już odpowiedzi, wpisz je w polecenie („w pakiecie Returns, BPMN 2.0”): asystent zapyta wtedy o mniej.

8.22 Strażnik, który zatrzymuje usunięcie

Agenta zdarzeń z "mode": "guard" EA pyta, zanim coś usunie, a on może usunięcie zatrzymać (rozdział 10, „Agenci zdarzeń”).

{"agents":[{"name":"Zatwierdzone zostają","event":"element_deleting","mode":"guard","applies_to":"Requirement",
  "prompt":"Zablokuj usunięcie wymagania, którego status to Approved."}]}

Co zobaczysz: gdy w EA usuwasz zatwierdzone wymaganie, komunikat „Loonar Compass zatrzymał to usunięcie:” z przyczyną, a wymaganie zostaje. W System Output wiersze „🛡 Zatwierdzone zostają: zablokowane - …” albo „🛡 Zatwierdzone zostają: dozwolone”.

Wskazówka: strażnik odpowiada w kilka sekund; jeśli nie zdecyduje w ciągu 40 sekund (albo nie może, np. bez AI), usunięcie zostaje wstrzymane, żeby chroniony obiekt nie zniknął przypadkiem. Pisz polecenia strażników tak, żeby jasno mówiły, kiedy blokować.

8.23 Kontrola wersji pakietów

Dla pakietów pod kontrolą wersji w EA asystent pokazuje, kto co ma pobrane do edycji, i wykonuje check out oraz check in (rozdział 7, „Kontrola wersji pakietów”).

Co zobaczysz: przy pierwszym poleceniu listę pakietów pod kontrolą wersji z konfiguracją, plikiem i stanem („checked out to …” albo „checked in”). Przy drugim panel zgody „Kontrola wersji: check_in – pakiet Orders”, który pojawia się w każdym trybie.

Wskazówka: najpierw dodaj pakiet do kontroli wersji w EA; asystent pracuje tylko z pakietami, które już tam są.

8.24 SharePoint

Gdy karta SharePoint jest wypełniona (rozdział 13), asystent czyta dokumenty z biblioteki zespołu i wysyła tam przygotowane przez siebie dokumenty i prezentacje.

Co zobaczysz: listę folderu, potem tekst dokumentu przeczytany jak w punkcie 8.19. Przy wysyłaniu panel zgody „Wysłać … do SharePoint: …” z witryną, biblioteką i folderem; pojawia się w każdym trybie.

Wskazówka: wysłać można tylko pliki, które asystent przygotował w rozmowie (z jego folderu załączników), a nie dowolny plik z dysku.

8.25 Power BI i GraphQL z huba

Hub zespołu udostępnia modele jako płaskie tabele i przez API GraphQL tylko do odczytu, dla Power BI, Excela i innych narzędzi (rozdział 22, „GraphQL i tabele dla Power BI”).

POST https://hub.example.com/api/sources/shop-db/graphql
{"query":"{ elements(type: \"Component\", limit: 20) { name stereotype connectors { type target { name } } } }"}

Co zobaczysz: odpowiedź JSON z komponentami i ich relacjami. W Power BI: Pobierz dane (Get Data) → Sieć Web (Web) → Zaawansowane (Advanced), adres https://<hub>/api/sources/<id>/table/elements i nagłówek Authorization z wartością Bearer <token API>.

Wskazówka: poproś administratora huba o własny token API (zakładka Users); czytać może każda rola.

Wskazówki do dobrych poleceń

• Nazywaj pakiety i diagramy dokładnie, tak jak w modelu (najlepiej w cudzysłowie). Przy dwóch obiektach o tej samej nazwie dodaj pakiet.
• Powiedz, czy zmieniać, czy tylko zaproponować. „Zaproponuj, ale jeszcze nie zapisuj” daje opis zmian bez zapisu.
• Przy większej zmianie poproś najpierw o podgląd i pracuj w trybie plan: panel zgody pokaże całość „Przed → po” przed pierwszym zapisem.
• Poproś o zapis wyniku do Excela albo Worda, gdy ma żyć poza czatem: listy, macierze i wyceny.
• Przy ryzykownych zmianach użyj trybu ask (Ustawienia → „Język i zatwierdzanie zmian”), poproś o baseline pakietu i sprawdź diagram po zmianach.

9. Współpraca z otwartym oknem EA

Jeśli masz otwarty w Enterprise Architect ten sam model, asystent współpracuje z Twoim oknem EA:

• wie, co masz otwarte i zaznaczone: jaki diagram jest otwarty i które elementy są zaznaczone na diagramie albo w przeglądarce projektu. Możesz więc pisać „ten element” albo „zaznaczone zadania”,
• otwiera diagramy w Twoim oknie EA i wskazuje elementy w przeglądarce projektu,
• po zapisie sam odświeża zmienione diagramy i pakiety w Twoim oknie, bez naciskania F5.

Klawisz F5 jest potrzebny tylko wtedy, gdy okno EA nie jest otwarte albo pokazuje inny model: asystent działa wtedy jak zwykle, a zmiany zobaczysz po odświeżeniu pakietu w EA. Jeśli w oknie EA jest otwarte okno dialogowe, EA nie odpowiada asystentowi; zamknij je i ponów prośbę.

Opisana tu współpraca dotyczy osobnej aplikacji. Compass uruchomiony w samym Enterprise Architect zawsze pracuje na projekcie otwartym w swoim oknie EA (rozdział 10).

Odczyty pliku EA, który jest otwarty w oknie EA, idą przez to okno, bo plik na dysku może jeszcze nie mieć Twoich ostatnich zmian.

10. Compass w Enterprise Architect

Loonar Compass działa też wewnątrz Enterprise Architect, jako okno zadokowane obok przeglądarki projektu i diagramów. Pracujesz w nim tak samo jak w osobnej aplikacji: rozmowa, załączniki, zatwierdzanie zmian, pamięć, szablony i dokumenty działają bez zmian. Osobna aplikacja, uruchamiana z menu Start, też działa jak dotąd.

Instalacja i uruchomienie

1. W instalatorze, na stronie „Folder docelowy”, zaznacz „Dodaj Loonar Compass do Enterprise Architect”. Działa to z każdą instalacją Enterprise Architect, także z wersją próbną. Po instalacji uruchom EA ponownie.
2. Otwórz projekt w Enterprise Architect: plik albo bazę danych.
3. Na wstążce Start, w grupie Add-Ins, kliknij Loonar Compass (przycisk znajdziesz też w Specialize). Przycisk działa tylko przy otwartym projekcie.
4. Compass otwiera się jako okno zadokowane w EA, w tym samym miejscu co okno Properties. Możesz je przeciągnąć w inne miejsce, odpiąć albo dołączyć do grupy zakładek; EA zapamiętuje, gdzie je umieściłeś.

Projekt i rozmowy

• W EA Compass zawsze pracuje na projekcie otwartym w tym oknie EA: pliku albo dowolnej bazie danych. Czyta model przez sam Enterprise Architect, więc nie potrzebuje ustawień modelu, haseł ani wyboru modelu rozmowy. Otwarcie w EA innego projektu przełącza Compass na ten projekt; bez otwartego projektu Compass nie działa.
• Rozmowy wybierasz z listy rozwijanej u góry okna. Lista pokazuje tylko rozmowy z tym projektem. Przycisk + zaczyna nową rozmowę, a ołówek zmienia nazwę wybranej.
• Ikony widoków są na dole okna, a w wąskim oknie strony przewijają się w poziomie i w pionie.
• Ctrl + V wkleja obrazy, pliki i tekst, tak jak w osobnej aplikacji.
• Ustawienia w EA nie mają kart Model i Enterprise Architect. Karty Model AI, Język i zatwierdzanie zmian, Confluence, Miro, Jira, SharePoint i Zespół (Compass Hub) działają tak samo jak w osobnej aplikacji (rozdział 5).

Zmiany, diagramy i odwołania do obiektów

• Zapisy idą przez to samo okno EA, więc zmiany widać od razu w przeglądarce projektu i na diagramach. Zatwierdzanie zmian działa jak w osobnej aplikacji (rozdział 16).
• Pokaż diagram i Edytuj diagram otwierają diagram w samym EA, zamiast pokazywać obrazek na czacie.
• Kliknij element, pakiet albo diagram prawym przyciskiem myszy (w przeglądarce projektu albo na diagramie) i wybierz Specialize → Dodaj do rozmowy w Compass. Do wiadomości trafia odwołanie do obiektu, na przykład «Pakiet: Sklep (id 5)», a asystent wie, o który obiekt chodzi. Przycisk ⌖ w karcie wiadomości dodaje takie same odwołania przez wyszukanie w modelu (rozdział 6, „Wybierz z modelu”).

Kontrola na bieżąco

Gdy Compass jest zadokowany w EA, sprawdza zmiany w trakcie Twojej pracy według tych samych reguł co kontrola modelu (wbudowanych i z governance.json albo z huba). Kontrola rusza po narysowaniu relacji i po edycji elementu (nazwy, stereotypu, tagged values). Ustalenia pojawiają się w zakładce Loonar Compass okna System Output, każde tylko raz, jako „⚠ Kontrola modelu: …”. Nowy element jest sprawdzany dopiero po pierwszej edycji, bo EA nadaje mu najpierw nazwę Class1.

Lista rozmów w zakładce pokazuje tylko rozmowy z projektem otwartym w tym oknie. Menu ⋯ obok kosza ma pozycje Rozmowy z innych modeli… (np. po przeniesieniu projektu z bazy do pliku: Kontynuuj tutaj robi kopię rozmowy przypiętą do tego projektu; oryginał zostaje przy swoim modelu, a notatki pamięci poprzedniego modelu można przypiąć do nowego), Eksportuj rozmowę… i Importuj rozmowę… (plik .lcchat, rozdział 17).

Agenci zdarzeń

Karta Agenci zdarzeń (Compass w EA) zawiera reguły, według których asystent reaguje na to, co dzieje się w EA. Reguły są w pliku event_agents.json:

{"agents":[{"name":"Component owner","event":"element_created","applies_to":"Component",
  "prompt":"Check that the new component has an owner and a description; suggest what to fill in."}]}

• Zdarzenia (event), łącznie 18:
  • elementy: element_created, element_changed, element_deleting;
  • połączenia: connector_created, connector_changed, connector_deleting;
  • diagramy: diagram_created, diagram_changed, diagram_deleting;
  • pakiety: package_created, package_changed, package_deleting;
  • atrybuty i metody: attribute_created, attribute_deleting, method_created, method_deleting;
  • słownik projektu: glossary_term_created, glossary_term_deleting.
  W applies_to podajesz typ elementu, «stereotyp» albo * (działają symbole * i ?).
• Agenci działają, gdy Compass jest otwarty w swojej zakładce w EA. Asystent czyta model i odpowiada w zakładce Loonar Compass okna System Output (linie zaczynają się od 🤖). Tylko czyta model: nie ma dostępu do plików, Jiry, Confluence ani serwerów MCP i nie może niczego zaproponować ani zapisać.
• Ten sam agent reaguje na ten sam obiekt najwyżej raz na minutę.
• Przycisk Zapisz agentów zdarzeń zapisuje reguły i podaje liczbę agentów.

Strażnicy. Domyślnie agent doradza po zdarzeniu ("mode": "advise"). Z "mode": "guard", dozwolonym tylko dla zdarzeń *_deleting, EA pyta Compass, zanim usunie obiekt. Strażnik odpowiada ALLOW albo BLOCK z przyczyną. Przy BLOCK EA pokazuje „Loonar Compass zatrzymał to usunięcie:” z przyczyną i anuluje usunięcie. Jeśli strażnik nie zdecyduje w ciągu 40 sekund albo nie może zdecydować, usunięcie zostaje wstrzymane z komunikatem. System Output pokazuje „🛡 …: dozwolone” albo „🛡 …: zablokowane - …”.

{"agents":[{"name":"Zatwierdzone zostają","event":"element_deleting","mode":"guard","applies_to":"Requirement",
  "prompt":"Zablokuj usunięcie wymagania, którego status to Approved."}]}

Agenci zespołu. Z hubem zespołu (rozdział 22) agenci z polityki zespołu (event_agents) działają w Compassie w EA u każdego, obok agentów tego komputera. Ich nazwy mają dopisek „(team)”.

Pisownia na bieżąco. Notatki zmienionego elementu są sprawdzane w języku Compassa; uwagi pojawiają się w System Output jako „✎ Pisownia: …”.

Kroki asystenta w System Output

Okno System Output w EA ma zakładkę Loonar Compass: Twoje wiadomości i każdy krok asystenta (odczyty modelu, zapisy do EA, wyniki, plan „📋 Plan: …” większej pracy) z godziną. Czat w oknie Compass pokazuje w tym czasie tylko ostatni krok, w jednej linii.

Zamykanie. Compass zamyka się razem z Enterprise Architect i zapisuje rozmowę. Po zamknięciu projektu w EA Compass prosi o otwarcie projektu.

11. Edytor diagramów

Każdy diagram z EA pokazany w rozmowie ma przycisk Edytuj diagram. Otwiera on diagram w oknie edytora, w którym zmieniasz go myszą. Edytor działa na modelu, nie na obrazku: to, co zapiszesz, trafia do EA przez te same operacje, których używa asystent, z panelem zatwierdzania i dziennikiem zmian (rozdział 16). Edytor potrzebuje WebView2, który jest częścią Windows 10 i 11. W Compass w EA przycisk Edytuj diagram otwiera diagram w samym Enterprise Architect (rozdział 10).

Rysowanie

• Przesuwanie, zmiana rozmiaru i wyrównywanie elementów myszą i przyciskami wyrównania; Ctrl+Z i Ctrl+Y cofają i ponawiają.
• Dodaj: przyciski zależą od rodzaju diagramu (klas, komponentów, przypadków użycia, aktywności, BPMN, maszyny stanów, wdrożenia, pakietów, sekwencji). Nowy element trafia w wolne miejsce blisko środka widoku; od razu wpisz jego nazwę.
• Łączenie: przeciągnij od jednego elementu do drugiego. Rodzaj relacji wybierasz na liście Połączenie.
• Z modelu… wstawia na diagram element, który już jest w modelu (wyszukiwanie po nazwie, typie lub pakiecie). Jego relacje z elementami diagramu pojawią się po zapisie.
• Dwuklik na elemencie lub relacji zmienia nazwę.

Właściwości

Panel Właściwości pokazuje zaznaczony element lub relację. Każde pole ma znaczek model (zmiana obowiązuje wszędzie, gdzie obiekt jest pokazany) albo diagram (tylko ten diagram).

• Ogólne: nazwa, alias, stereotyp, słowa kluczowe, status, wersja, autor, faza, złożoność, abstrakcyjny i notatki; pakiet, GUID i daty tylko do odczytu. Dla relacji: nazwa, stereotyp, kierunek, krotności i role obu końców, notatki.
• Atrybuty i operacje (klasy, interfejsy, komponenty): dodawanie, zmiana (widoczność, nazwa, typ) i usuwanie; nowa operacja przyjmuje parametry w postaci nazwa: Typ, inna: Typ.
• Tagi: zmiana, dodawanie i usuwanie; gdy profil podaje dozwolone wartości (na przykład typy zadań BPMN), wybierasz z listy.
• Wygląd: kolor wypełnienia na tym diagramie albo domyślny kolor elementu oraz styl linii relacji na tym diagramie.

Usuwanie

Klawisz Delete usuwa bez pytania to, co dodałeś w edytorze. Przy obiekcie, który już jest w modelu, edytor pyta: Usuń z tego diagramu (zostaje w modelu i na innych diagramach) albo Usuń z modelu (trwale, razem z relacjami, ze wszystkich diagramów). Pokazuje, na jakich innych diagramach jest element i ile ma relacji.

Diagramy sekwencji

Linie życia mają nagłówek i przerywaną linię; przesuwają się tylko w poziomie. Komunikaty idą od góry w swojej kolejności, z numerami, tak jak rysuje je EA. Kolejność zaznaczonego komunikatu zmieniasz przyciskami ▲ ▼ w panelu albo Alt+↑ / Alt+↓. Nowy komunikat (przeciągnij od jednej linii życia do drugiej) trafia zaraz po zaznaczonym. W panelu ustawiasz rodzaj (synchroniczny albo asynchroniczny), czy to odpowiedź, i możesz nazwać go operacją odbiorcy.

Zapis

• Zapisz do EA zapisuje zmiany i zamyka edytor; wynik pojawia się w rozmowie. Anuluj zamyka go bez zapisu.
• Uporządkuj z AI zapisuje zmiany i prosi asystenta w rozmowie o takie rozmieszczenie diagramu, żeby dobrze się czytał, bez dodawania, usuwania i zmiany nazw.

12. Wysyłanie diagramów do Miro

Diagram z EA może trafić na tablicę Miro jako edytowalne kształty i połączenia w ramce z nazwą diagramu. Tylko z EA do Miro: to, co ktoś zmieni na tablicy, nie wraca do modelu.

Konfiguracja, jednorazowo:

1. W Miro otwórz ustawienia profilu → Your apps → Create new app. Miro najpierw prosi o założenie Developer team (darmowej piaskownicy na Twoje aplikacje): zaakceptuj warunki i utwórz go. W organizacji na planie Enterprise zakłada go administrator organizacji.
2. Nadaj aplikacji nazwę (na przykład Loonar Compass) i nie zaznaczaj „Expire user authorization token”: wygasający token przestaje działać po godzinie.
3. W sekcji Permissions zaznacz boards:read i boards:write.
4. Kliknij Install app and get OAuth token i wybierz organizację oraz zespół, których tablic aplikacja może używać (na pierwszy test: Developer team). Skopiuj token.
5. Wklej go w Ustawieniach, karta „Miro”, i kliknij Zapisz i sprawdź połączenie z Miro. Token jest przechowywany w Menedżerze poświadczeń Windows.

Diagramy trafiają tylko na tablice zespołu, w którym aplikacja jest zainstalowana; żeby wysyłać do innej organizacji, zainstaluj aplikację także tam (tym samym przyciskiem).

Wysyłanie:

1. Kliknij Wyślij do Miro pod diagramem w rozmowie.
2. Wybierz tablicę (pierwsza jest ta użyta ostatnio; pole wyszukiwania filtruje po nazwie).
3. Miniatura pokazuje, co już jest na tablicy (szare), i gdzie trafi diagram (niebieska ramka, czerwona, gdy coś by zasłoniła). Aplikacja sama znajduje wolne miejsce; przeciągnij ramkę, żeby wybrać inne.
4. Kliknij Wyślij do Miro. Po wysłaniu w rozmowie pojawia się wiadomość z linkiem, który otwiera tablicę na nowej ramce.

Diagramy sekwencji trafiają jako linie życia z ponumerowanymi komunikatami w kolejności z EA (odpowiedzi przerywaną linią). Ponowne wysłanie tego samego diagramu stawia nową ramkę obok poprzedniej, więc nic, co zmieniono na tablicy, nie zostaje nadpisane.

13. Dokumenty: Word, Excel, PowerPoint, PDF, obrazki PNG, Confluence, SharePoint

Asystent przygotowuje dokumenty z treści modelu i rozmowy. Gotowy plik pojawia się na czacie jako karta z przyciskami, a sam plik zostaje w folderze attachments w folderze danych (rozdział 18).

Prezentacje i PDF

• PowerPoint: asystent buduje prezentację (16:9) z modelu i rozmowy: slajd tytułowy z podtytułem, a potem slajdy z tytułem, najwyżej około sześcioma punktami na dwóch poziomach i/lub obrazkiem: diagramem z EA albo obrazkiem narysowanym w rozmowie. Przy punktach obrazek trafia na prawą stronę.
• PDF: na życzenie prezentację zapisuje też jako PDF Microsoft PowerPoint, a dokument Word Microsoft Word (tylko jako PDF albo jako DOCX i PDF). Office działa niewidocznie w tle. Bez Office plik PPTX albo DOCX i tak powstaje, a asystent mówi, że PDF się nie udał.

SharePoint

Asystent pracuje z biblioteką dokumentów witryny SharePoint zespołu (narzędzie sharepoint): pokazuje zawartość folderu, czyta tekst dokumentu (PDF, Word, PowerPoint, Visio, Excel) i wysyła plik, który przygotował w tej rozmowie (dokument, skoroszyt, prezentację). Każde wysłanie wymaga Twojej zgody, w każdym trybie; plików z innych miejsc dysku nie da się wysłać.

Rejestracja aplikacji. Poproś administratora Microsoft 365 o rejestrację aplikacji w Microsoft Entra ID z kluczem tajnym klienta i uprawnieniem aplikacji Microsoft Graph Sites.Selected, nadanym dla tej witryny (zalecane), albo Sites.ReadWrite.All. Compass loguje się jako ta aplikacja (poświadczenia klienta OAuth2) w login.microsoftonline.com i pracuje przez Microsoft Graph (graph.microsoft.com). Zapisz kartę przyciskiem Zapisz i sprawdź połączenie z SharePoint: pokaże „Zapisano. Połączono z SharePoint: … pozycji w bibliotece.”

Strony Confluence

Asystent przygotowuje stronę w formacie edytora kodu źródłowego Confluence (storage XHTML): nagłówki, tabele, listy, spis treści, panele (informacja, uwaga, ostrzeżenie, wskazówka, sekcja rozwijana), statusy, zgłoszenia Jira, wzmianki o osobach i bloki kodu. Diagramy z EA i obrazki są dołączane jako załączniki.

Wklejanie ręczne (bez ustawień Confluence):

1. Kliknij Kopiuj kod strony na karcie strony.
2. W Confluence otwórz edycję strony i edytor kodu źródłowego (Source Editor), wklej kod i zatwierdź.
3. Kliknij Otwórz folder z obrazkami i dodaj obrazki do strony jako załączniki.

Publikacja przez asystenta. Po uzupełnieniu karty „Confluence” asystent na Twoją prośbę publikuje stronę przez REST API, wyłącznie przez HTTPS: tworzy nową stronę pod stroną nadrzędną albo aktualizuje istniejącą (wskazaną po ID albo tytule). Obrazki trafiają jako załączniki; istniejące dostają nową wersję. Diagramy są przy każdej publikacji eksportowane z EA na nowo, więc ponowna publikacja odświeża stronę po zmianach w modelu. Asystent pamięta strony, które opublikował.

Confluence Cloud: skąd wziąć dane.

1. Token: tworzy się go na koncie Atlassian, nie w Confluence. Otwórz https://id.atlassian.com/manage-profile/security/api-tokens (konto Atlassian → Security → API tokens). Atlassian może najpierw poprosić o potwierdzenie tożsamości kodem wysłanym e-mailem.
2. Kliknij Create API token (zwykły, nie Create API token with scopes), nadaj nazwę, na przykład Loonar Compass, i wybierz ważność: domyślnie tydzień, najwyżej rok. Kliknij Create i skopiuj token: Atlassian pokazuje go tylko raz. Gdy wygaśnie, utwórz nowy i wklej go w karcie „Confluence”.
3. E-mail: adres konta Atlassian, do którego należy token.
4. Adres: Twoja witryna z /wiki, na przykład https://twoja-witryna.atlassian.net/wiki.
5. Przestrzeń (klucz): jest w adresie każdej strony przestrzeni, po /spaces/ (na przykład …/wiki/spaces/PM/… daje PM), oraz w Ustawieniach przestrzeni.
6. Strona nadrzędna (ID) (opcjonalnie): liczba w adresie strony, po /pages/ (na przykład …/pages/65818/… daje 65818).

Zapisz kartę przyciskiem Zapisz i sprawdź połączenie z Confluence.

14. Szablony dokumentów

Szablon mówi asystentowi, jak ma wyglądać dokument: jakie ma sekcje, co w nich umieścić, wskazówki i przykłady. Asystent wypełnia go treścią z modelu, rozmowy, Jiry, Confluence i kodu, a potem przygotowuje stronę Confluence, dokument Word albo opis zgłoszenia Jira. Szablonów może być dowolnie wiele - jeden, kilka albo setka - i każdy użytkownik ma własne. Compass nie dostarcza gotowych szablonów: dodajesz te, których używa Twój zespół.

Dodawanie szablonów

• ➕ Dodaj z plików… - wybierz jeden lub kilka plików: Markdown (.md), tekst, Word (.docx), HTML, PDF, PowerPoint albo Excel. Z Worda i HTML zostają nagłówki, listy i tabele; z PDF, PowerPointa i Excela sam tekst. Przy jednym pliku otwiera się formularz szablonu, przy kilku szablony zapisują się od razu, a narzędzie i grupę ustawiasz potem przyciskiem Właściwości.
• ➕ Dodaj z Confluence - wklej adres strony (z /pages/ID albo pageId=ID) albo jej id. Strona-wzór staje się szablonem dla Confluence.
• ➕ Nowy szablon - pusty formularz, treść piszesz w Markdown.
• Możesz też poprosić asystenta o zrobienie szablonu z przykładowego dokumentu (patrz niżej).

Właściwości szablonu

Szablon to plik Markdown w folderze templates. Właściwości są zapisane w jego pierwszych wierszach, więc pliki możesz też przygotować sam i wrzucić do folderu:

Widok „Szablony dokumentów”

• Użyj wstawia do rozmowy prośbę o dokument według szablonu (stronę Confluence, dokument Word albo zgłoszenie Jira - zależnie od narzędzia szablonu). Uzupełnij ją i wyślij.
• Właściwości otwiera formularz z nazwą, opisem, narzędziem, grupą, modelem i treścią.
• Edytuj otwiera plik szablonu w Notatniku.
• Usuń (dwa kliknięcia) przenosi szablon do folderu bin w folderze szablonów - stamtąd możesz go przywrócić.
• Otwórz folder szablonów otwiera folder templates w Eksploratorze.

Szablony dostarczane przez wcześniejsze wersje (BRD, opis procesu i inne), których nie zmieniałeś, po aktualizacji trafiają do folderu bin; zmienione przez Ciebie zostają.

Jak asystent pisze dokument

W rozmowie podaj nazwę szablonu albo grupy:

• Asystent najpierw spisuje listę Twoich próśb o dokument z całej rozmowy (sekcje, każde wymienione wymaganie, źródła, obrazy, format) i czyta wszystkie wskazane źródła, także obrazy załączone w zgłoszeniach Jira.
• Trzyma się nagłówków szablonu w jego kolejności; każde wymaganie dostaje osobny wpis z numerem i treścią ze źródła; czego nie wie - oznacza „do uzupełnienia”.
• Compass nie utworzy dokumentu, w którym brakuje sekcji z szablonu albo któraś prośba nie ma swojego miejsca - asystent musi go najpierw uzupełnić. W odpowiedzi pokazuje listę: prośba → sekcja.

Szablon z przykładowego dokumentu

Asystent zawsze prosi o zgodę przed zapisaniem szablonu, także w trybie auto, i pokazuje cały tekst.

15. Pamięć asystenta

Asystent pamięta ustalenia między rozmowami: konwencje modelowania, Twoje preferencje i poprawki oraz fakty o projektach i modelu. Zna je w każdej nowej rozmowie. Ustalenie na ten sam temat aktualizuje, zamiast dublować, a nieaktualne usuwa. Haseł, kluczy ani innych sekretów nie zapamiętuje.

Ustalenia asystent zapisuje sam, gdy uzna, że przydadzą się w kolejnych rozmowach, i mówi o tym jednym zdaniem. Możesz też poprosić o to wprost, zaczynając od „zapamiętaj…”:

Ustalenia są wspólne dla wszystkich modeli. Jeśli chcesz, żeby ustalenie dotyczyło tylko jednego modelu, powiedz to wprost, na przykład „zapamiętaj to tylko dla tego modelu”: wtedy asystent korzysta z niego wyłącznie w rozmowach z tym modelem, a widok „Pamięć asystenta” oznacza je znacznikiem „Tylko dla modelu …”.

Zapis ustalenia w pamięci (i jego usunięcie przez asystenta) zawsze wymaga Twojej zgody, w każdym trybie, a panel zgody pokazuje nazwę i całą treść notatki (rozdział 16). Zapis ustalenia nie przerywa pracy asystenta nad bieżącym zadaniem. Ustalenia dotyczące modelu mogą być nieaktualne, dlatego przed zapisem do modelu asystent sprawdza je w bazie. Pełna treść pamięci trafia do modelu AI w każdym zapytaniu (rozdział 18).

Widok „Pamięć asystenta”

• Lista ustaleń z datą.
• Usuń od razu kasuje wybrane ustalenie.
• Otwórz folder pamięci otwiera folder memory w Eksploratorze. Ustalenia są w nim plikami Markdown, a spis jest w pliku MEMORY.md.

16. Zatwierdzanie zmian i dziennik zmian

Tryb ustawiasz w widoku Ustawienia, w karcie „Język i zatwierdzanie zmian”. Decyduje on, czy i kiedy aplikacja zapyta o zgodę przed zapisem do EA (zapis do pamięci asystenta i zapis szablonu zawsze wymagają zgody). Odczyt modelu i pokazywanie diagramów nigdy nie wymagają zgody. Bieżący tryb widać też w karcie wiadomości.

Gdy potrzebna jest zgoda, nad kartą wiadomości pojawia się panel „Asystent chce zapisać zmiany w modelu” z opisem zmian i przyciskami Zatwierdź oraz Odrzuć. Opis podaje, ile pakietów, diagramów, elementów i połączeń powstanie albo się zmieni, nazwy nowych pakietów i diagramów, a przy usuwaniu, przenoszeniu i kopiowaniu także osobne wiersze z nazwami tych obiektów (USUNIĘCIE, PRZENIESIENIE, KOPIOWANIE). Ten sam panel pyta o zgodę na zapis ustalenia w pamięci, nadpisanie szablonu i publikację w Confluence. Odrzucony zapis niczego nie zmienia, a asystent dostaje informację o odrzuceniu i może zaproponować coś innego.

Opis zmian w panelu zgody ma część „Przed → po:”: co powstaje (utworzone obiekty), co zmienia się z jakiej wartości na jaką (pole: stara → nowa wartość) i co jest usuwane. Dzięki temu widzisz skutek zapisu, zanim klikniesz Zatwierdź.

Usuwanie elementu z relacjami. Usunięcie elementu, który ma relacje, zawsze wymaga Twojej zgody, także w trybie auto. Panel zgody wymienia te relacje.

Zawsze, w każdym trybie, Compass pyta też przed: publikacją w Confluence, cofnięciem zapisów, utworzeniem zgłoszeń, komentarzy i linków w Jirze, zapisem plików (eksport XMI, dokumenty z szablonów EA) i importem XMI, zapisem ustalenia w pamięci albo szablonu dokumentu, zapisem lub uruchomieniem skryptu EA, check out, check in i innymi akcjami kontroli wersji pakietu, wysłaniem pliku do SharePoint, wywołaniem narzędzia serwera MCP, który nie jest zaufany, oraz przeczytaniem pliku, który nie jest załącznikiem rozmowy (rozdział 7).

Seria tych samych działań: przy zgodzie na zgłoszenie Jira, publikację w Confluence, notatkę pamięci, wywołanie narzędzia MCP, wysyłkę pliku albo skrypt EA panel ma też przycisk Zatwierdź wszystkie … do zamknięcia Compassa. Po jego kliknięciu kolejne działania tego rodzaju idą bez pytania, aż zamkniesz aplikację; pozostałe zmiany nadal zależą od trybu zatwierdzania.

Dziennik zmian

Każdy zapis asystenta do modelu EA, także nieudany, trafia do dziennika zmian (plik audit_log.jsonl w folderze danych). Nie ma w nim zapisów odrzuconych przez Ciebie ani operacji, których aplikacja nie dopuściła do zapisu; dziennik nie obejmuje też pamięci, szablonów ani publikacji w Confluence.

Widok Dziennik zmian (ikona „Dziennik zmian w modelu”) pokazuje 200 ostatnich zapisów, od najnowszych: wynik (OK albo BŁĄD), czas, konto EA i bazę, opis zmian oraz treść błędu. Przycisk Eksportuj do Excela zapisuje cały dziennik jako arkusz XLSX (kolumny: Czas, Wynik, Konto EA, Baza, Tryb, Zmiany, Utworzone, Błąd), na przykład do przeglądu zmian w zespole. Przycisk Otwórz plik dziennika otwiera plik dziennika w Notatniku.

17. Rozmowy: historia, wyszukiwanie, praca w tle

• Nowa rozmowa: przycisk + nad listą rozmów. Każda rozmowa jest zapisywana i wraca po ponownym uruchomieniu aplikacji.
• Grupy: rozmowy są pogrupowane na „Dzisiaj”, „Wczoraj”, „Ostatnie 7 dni” i „Wcześniej”.
• Wyszukiwanie: pole „Szukaj w rozmowach…” filtruje listę po tytule i po treści wiadomości.
• Zmiana nazwy: kliknij ołówek przy wybranej rozmowie, wpisz nazwę, Enter zapisuje, Esc anuluje.
• Kilka rozmów naraz: w trakcie pracy asystenta możesz zacząć nową rozmowę albo przejść do innej. Rozpoczęta praca toczy się w tle.
• Usuwanie: kliknij rozmowę na liście prawym przyciskiem myszy i wybierz Usuń rozmowę. Jej plik trafia do folderu history\bin (rozdział 18), więc rozmowę przywrócisz, przenosząc plik z powrotem do history, gdy aplikacja jest zamknięta. Rozmowy, w której asystent pracuje, nie da się usunąć, dopóki nie skończy.
• Długie rozmowy: zanim zapytanie zbliży się do 100 000 tokenów (Claude Haiku 5.5 liczy dłuższe zapytanie w całości 5× drożej), wcześniejsza część rozmowy jest dla asystenta zastępowana streszczeniem napisanym przez model, a 8 najnowszych wiadomości zostaje słowo w słowo. Streszczenie jest zapisywane w rozmowie i używane w kolejnych odpowiedziach; w czacie miejsce, od którego zaczyna się pełna treść, oznacza linia „Asystent widzi rozmowę powyżej jako streszczenie”. Historia, którą widzisz na czacie, zostaje pełna. Przy bardzo długiej pracy na narzędziach (np. dziesiątki przeczytanych plików) serwer Anthropic sam usuwa z widoku modelu najstarsze wyniki narzędzi; 6 najnowszych zostaje, a asystent w razie potrzeby czyta plik ponownie.
• Model rozmowy: każda rozmowa pracuje z własnym modelem EA, a nowa rozmowa zaczyna się od zatwierdzenia tego modelu. Ekran nowej rozmowy pokazuje model domyślny z ustawień. Przycisk Wybierz inny model… otwiera okno „Model tej rozmowy”, w którym wybierasz Domyślny z ustawień albo Inny model: Baza PostgreSQL (serwer, port, nazwa bazy, użytkownik, hasło, szyfrowanie połączenia) albo Plik EA (.qea, .qeax), z kontem EA i opcjami zabezpieczeń jak w karcie Model. Sprawdź połączenie otwiera model, liczy pakiety, elementy i diagramy oraz zapisuje w nim pakiet próbny, który sprawdza i od razu usuwa. Przycisk Zatwierdź model i rozpocznij ustala model rozmowy: potem nie można go już zmienić, a przycisk Model: … w nagłówku pokazuje go tylko do podglądu. Aby pracować na innym modelu, zacznij nową rozmowę. Zmiana modelu domyślnego w ustawieniach nie zmienia trwających rozmów. Hasła połączenia innego niż w ustawieniach trafiają do Menedżera poświadczeń Windows. W Compass w EA modelem rozmowy jest zawsze projekt otwarty w EA (rozdział 10).
• Plik EA upuszczony na okno: plik .qea lub .qeax upuszczony na czat staje się modelem rozmowy, a nie załącznikiem. Jeśli rozmowa ma już wiadomości, z tym plikiem zaczyna się nowa rozmowa.
• Rozmowy z wcześniejszych wersji przy pierwszym uruchomieniu wersji 0.5 lub nowszej dostają kopię modelu z ustawień, więc pracują z nim dalej, nawet gdy później zmienisz ustawienia. Po najechaniu myszą na rozmowę na liście widać jej model.
• Kontynuacja w innym modelu: w osobnym oknie model rozmowy zmieniasz przyciskiem „Model: …” w nagłówku; od tego miejsca w czacie widać linię „Od tego miejsca: model …”, a asystent wie, że wcześniejsze wiadomości dotyczyły innego modelu. W zakładce EA służy do tego „Rozmowy z innych modeli…” (rozdział 10).
• Eksport i import: prawy przycisk na rozmowie → Eksportuj rozmowę… zapisuje ją z załącznikami do pliku .lcchat (bez kont i haseł: tylko ścieżka pliku albo nazwa bazy i serwera); ikona importu obok + wczytuje taki plik jako nową rozmowę z modelem otwartym w danym oknie.
• Koszt odpowiedzi: ostatni krok każdej odpowiedzi, „💲 Koszt tej odpowiedzi”, pokazuje liczbę wywołań modelu, tokeny wejścia (z udziałem odczytów z cache) i wyjścia oraz koszt w USD według cennika modelu. Każde wywołanie trafia też do dziennika usage\<dzień>.jsonl w folderze danych (same liczby, bez treści).

Zapisy do EA z różnych rozmów wykonują się po kolei, nie jednocześnie. EA w tle ma otwarty jeden model naraz: przejście między rozmowami z różnymi modelami otwiera go ponownie, co trwa od kilku do około 25 sekund. Gdy czat jest przewinięty wyżej, kółko ze strzałką nad polem wiadomości przenosi na koniec rozmowy.

18. Dane, bezpieczeństwo i prywatność

Gdzie są Twoje dane

Historia rozmów to zwykłe pliki w Twoim profilu Windows, chronione Twoim kontem Windows; aplikacja ich nie szyfruje. Chroń dostęp do swojego konta i nie udostępniaj folderu danych.

Co trafia do dostawcy modelu AI

Żeby asystent mógł odpowiadać, w każdym zapytaniu do wybranego dostawcy modelu AI (Anthropic albo OpenAI, karta Model AI) aplikacja wysyła: treść rozmowy, załączone pliki, pełną treść pamięci asystenta, instrukcje modelowania repozytorium, listę szablonów z opisami oraz to, co asystent odczytał z modelu w danej rozmowie, czyli wyniki jego zapytań do bazy (na przykład nazwy i opisy pakietów, elementów i diagramów) i obrazki diagramów. Nie jest wysyłana cała baza, tylko to, o co asystent zapytał. Treść szablonu trafia do modelu, gdy asystent go użyje, a po zmianie języka trafiają też pamięć i szablony do przetłumaczenia.

Dane trafiają bezpośrednio do wybranego dostawcy (api.anthropic.com albo api.openai.com) z użyciem Twojego klucza API; drugi dostawca nie dostaje niczego. Loonar ich nie otrzymuje, a aplikacja nie zbiera żadnych danych o korzystaniu (brak telemetrii). Z claude.url (rozdział 5) zapytania idą zamiast tego pod ten adres, na przykład do Twojego zasobu Azure AI Foundry albo firmowej bramki.

Inne miejsca, do których mogą trafić Twoje dane, tylko gdy je skonfigurujesz albo włączysz:

Uprawnienia asystenta

• Bazę asystent czyta w sesji tylko do odczytu, a plik modelu otwiera tylko do odczytu: wyłącznie zapytaniami SELECT i WITH, z limitem czasu zapytania i bez funkcji serwera, które czytają pliki albo wpływają na inne sesje. Wszystkie zmiany idą przez Enterprise Architect, na koncie EA modelu (z karty Model albo z modelu rozmowy), więc obowiązują je uprawnienia i blokady tego konta. Compass w EA czyta i zapisuje model przez okno EA, w którym jest otwarty, na koncie, na którym zalogowałeś się w EA.
• Ochrona przed ukrytymi instrukcjami (prompt injection). Dokument, zgłoszenie, strona albo notatka w modelu mogą zawierać tekst napisany po to, żeby sterować asystentem. Asystent dostaje zasady bezpieczeństwa w każdym zapytaniu; wyniki z dokumentów, Jiry, Confluence, serwerów MCP, CMDB i kodu są oznaczone jako dane, a nie polecenia; a odpowiedź, która powtarza słowo w słowo wewnętrzne instrukcje asystenta, jest wstrzymywana („Odpowiedź powtarzała wewnętrzne instrukcje asystenta i została wstrzymana.”). Asystent nie wykonuje znalezionych tam instrukcji i nie wysyła danych w miejsca, które ta treść wskazuje, a zapisy nadal wymagają Twojej zgody (rozdział 16).
• W Confluence asystent działa z uprawnieniami tokena z karty „Confluence” i publikuje tylko po Twoim zatwierdzeniu.
• Asystent nie ma dostępu do plików na dysku poza tymi, które sam mu załączysz, oraz poza swoimi folderami pamięci i szablonów; każdy inny plik (dokument wymagań, folder z kodem) czyta dopiero po zapytaniu Cię o zgodę. Obrazki rysowane przez asystenta nie mogą wczytać plików z dysku ani z sieci.
• Login i hasło z ciągu połączenia otwartego okna EA nigdy nie trafiają do modelu językowego.

Statystyki użycia

Jeśli ich nie wyłączysz, Loonar Compass wysyła anonimowe statystyki: przy każdym uruchomieniu losowy identyfikator instalacji (utworzony na tym komputerze, niewyliczany z komputera ani z Ciebie) z wersją aplikacji, wersją Windows i językiem, a co godzinę podsumowanie dnia: rodzaje zadań i jak się skończyły, jak często użyto każdej funkcji asystenta i jak często kończyła się błędem, oceny odpowiedzi, czego asystent nie umiał zrobić, zgody, otwierane widoki, tokeny i rodzaj konfiguracji. Nigdy nie są wysyłane treści rozmów, nazwy ani identyfikatory z modelu, ścieżki plików, adresy serwerów, treści błędów ani nazwy użytkowników. Usługa odbierająca dane nie zapisuje adresów IP; dane widzi tylko autor, a publikowane są wyłącznie podsumowania wszystkich instalacji łącznie (link „Opublikowane statystyki”). Dane są przechowywane 13 miesięcy.

Przy pierwszym uruchomieniu aplikacja pokazuje informację z przyciskami Zostaw włączone, Wyłącz i Pokaż szczegóły. W widoku „Statystyki użycia” (pasek nawigacji) widzisz dokładnie, co zostało policzone dziś („Dziś do tej pory”) i co zostało wysłane w ostatnich 30 dniach, w postaci JSON z przyciskiem Kopiuj. Tam też odznaczasz „Wysyłaj anonimowe statystyki użycia (co godzinę)” (dni jeszcze niewysłane są wtedy usuwane) albo przyciskiem Nowy identyfikator nadajesz instalacji nowy identyfikator, po którym późniejszych dni nie da się połączyć z wcześniejszymi.

Organizacja może wyłączyć statystyki dla wszystkich: zmienną środowiskową LOONAR_TELEMETRY=0, zasadą w rejestrze (szablon ADMX w pakiecie dla administratorów) albo polityką huba zespołu ("telemetry": false). Wtedy nic nie jest liczone ani wysyłane.

Połączenia i szyfrowanie

• API modelu AI (Anthropic albo OpenAI albo adres z claude.url), Confluence, Jira, SharePoint, Miro i adresy tokenów OAuth2: wyłącznie HTTPS (http:// jest dopuszczalny tylko dla serwera na tym samym komputerze).
• Baza modelu: połączenie może być szyfrowane TLS, zależnie od ustawienia w karcie Model (rozdział 5). Administrator bazy może wymusić TLS dla wszystkich klientów wpisami hostssl w pg_hba.conf. Połączenie samego Enterprise Architect z bazą zależy od ustawień EA.
• Proxy: aplikacja korzysta z proxy z ustawień internetowych Windows oraz ze zmiennych środowiskowych HTTPS_PROXY i ALL_PROXY. Skrypty PAC i uwierzytelnianie NTLM/Kerberos na proxy nie są obsługiwane.
• Chwilowe błędy API modelu AI (przeciążenie 529 i inne błędy 5xx, limit zapytań 429) aplikacja ponawia automatycznie.

19. Rozwiązywanie problemów

20. Zgłaszanie błędów i nowe wydania

Zgłoś błąd

1. Kliknij ikonę Zgłoś błąd w pasku nawigacji albo, przy konkretnej odpowiedzi, 👎 → „Zgłoś problem z tą odpowiedzią” (rozdział 6).
2. Wybierz, jak wysłać zgłoszenie: „Publiczne zgłoszenie na GitHubie (zalecane)” albo „E-mail do autora (prywatnie)”.
3. Wpisz temat i opis: co robiłeś, co się stało, czego się spodziewałeś. Opis jest wymagany; możesz w nim wkleić treść błędu z czatu. Przy zgłoszeniu na GitHubie temat i opis są publiczne: nie wpisuj w nich informacji poufnych.
4. Dodaj zdjęcia, najlepiej zrzuty ekranu z zaznaczonym miejscem błędu: przeciągnij je do okna, wklej ze schowka (Ctrl + V) albo wybierz z dysku przyciskiem + Dodaj zdjęcie.
5. Opcje: „Dołącz informacje techniczne (publicznie)” dodaje wersję, Windows, model AI, tryb zatwierdzania, liczbę kroków i identyfikator instalacji, bez haseł i kluczy. Przy zgłoszeniu z odpowiedzi „Dołącz zgłaszaną odpowiedź” dodaje Twoje pytanie, odpowiedź i kroki asystenta; widzi je tylko autor. „Pokaż, co jest dołączone” pokazuje dokładnie, co zostanie wysłane. E-mail do odpowiedzi jest opcjonalny.
6. Kliknij Wyślij zgłoszenie. Zgłoszenie na GitHubie powstaje od razu, a aplikacja pokazuje link do niego, pod którym śledzisz, co się z nim dzieje. Przy e-mailu otwiera się gotowa wiadomość w programie pocztowym ze zdjęciami jako załącznikami; sprawdź ją i wyślij.

W zgłoszeniu na GitHubie (repozytorium github.com/loonar-eu/loonar-compass) publiczne są tytuł, opis i, jeśli zostawisz opcję, informacje techniczne. Zrzuty ekranu, zgłaszana odpowiedź i Twój adres e-mail trafiają do prywatnego repozytorium, które czyta tylko autor. Zgłoszenie wysłane e-mailem nie jest publikowane. Zgłoszenia służą wyłącznie do odpowiedzi i poprawy aplikacji i są przechowywane do 2 lat po zamknięciu sprawy. Przed wysłaniem usuń ze zrzutów dane osobowe i informacje poufne. Szczegóły są w polityce prywatności, do której link jest w formularzu; link „Zgłoszenia i pomysły” prowadzi do listy wszystkich zgłoszeń.

Nowe wydania (newsletter)

W karcie „Nowe wydania (newsletter)” w ustawieniach wpisz adres e-mail, zaznacz „Chcę dostawać informacje o nowych wydaniach” i kliknij Zapisz. Dostaniesz krótki e-mail, gdy wyjdzie nowa wersja: co nowego i skąd ją pobrać, bez reklam. Zapis i rezygnacja trafiają do autora wiadomością z programu pocztowego. Adres jest wykorzystywany wyłącznie do informacji o nowych wersjach, na podstawie Twojej zgody, do czasu jej wycofania; administratorem danych jest Loonar Mariusz Głowacki. Zgodę wycofasz w każdej chwili, odznaczając opcję i zapisując kartę albo pisząc e-mail. Pod informacją w karcie jest link do polityki prywatności.

22. Compass Hub (usługa zespołowa)

Compass Hub to opcjonalna usługa dla zespołu, uruchamiana na komputerze lub serwerze zespołu. Daje wspólną politykę (reguły kontroli modelu i minimalny tryb zatwierdzania), centralny dziennik zmian ze wszystkich stanowisk, wspólne notatki, zestawy zmian do przeglądu, widok webowy modeli dla osób bez Enterprise Architect, zgłoszenia Jira i strony Confluence tworzone z widoku webowego, raporty pakietów w Word i Excel, logowanie kontem firmowym (OpenID Connect), agentów zdarzeń dla całego zespołu, API GraphQL tylko do odczytu i tabele dla Power BI oraz serwer MCP (tylko odczyt) dla innych narzędzi AI. Bez huba Compass działa samodzielnie, jak dotąd.

Dla użytkownika

Adres huba i swój token API dostajesz od administratora (zakładka Users widoku webowego). Wpisz je w karcie „Zespół (Compass Hub)” w widoku Ustawienia: Adres huba (musi zaczynać się od https://; http:// tylko na tym komputerze), Token i opcjonalnie Ten model w hubie (identyfikator źródła, czyli modelu huba odpowiadającego Twojemu), a potem kliknij Zapisz i sprawdź połączenie z hubem. Test pokazuje Twoje konto, rolę i politykę zespołu. Z hubem:

• polityka zespołu min_approval może tylko zaostrzyć lokalny tryb zatwierdzania (od najluźniejszego: auto, plan, ask);
• reguły kontroli modelu z huba obowiązują, gdy nie ma lokalnego pliku governance.json (rozdział 7);
• każda zapisana zmiana trafia do zespołowego dziennika zmian; wysyłanie odbywa się w tle, więc niedostępny hub nie zatrzymuje pracy, a ostatni problem widać na karcie.

Instalacja huba

Hub to osobny program, compass-hub, dla Windows i Linuksa. Czyta modele wprost (baza PostgreSQL, SQL Server, MySQL/MariaDB albo Oracle albo pliki .qea/.qeax), więc na serwerze nie jest potrzebny Enterprise Architect. Do pobrania:

• Windows: CompassHub-0.9.0-windows-x64.zip z plikiem compass-hub.exe, przykładowym hub.json i plikiem README.
• Docker: obraz ghcr.io/loonar-eu/compass-hub:0.9.0 albo własna kompilacja w głównym folderze repozytorium: docker build -f hub/Dockerfile -t compass-hub .

W konsoli (Windows albo Linux). Hub działa, dopóki nie zamkniesz konsoli:

compass-hub hub.json

Jako usługa Windows, w konsoli uruchomionej jako administrator. Usługa „CompassHub” startuje od razu i razem z Windows; zatrzymujesz ją w Usługach albo poleceniem sc stop CompassHub, a usuwasz opcją --service-uninstall:

compass-hub --service-install C:\Hub\hub.json
compass-hub --service-uninstall

W Dockerze. Plik hub.json z "listen": "0.0.0.0:8730" umieść w folderze danych, który kontener widzi jako /data:

docker run -d --name compass-hub -p 8730:8730 -v /srv/compass-hub:/data \
  -e LOONAR_SECRET_CLAUDE_API_KEY=... ghcr.io/loonar-eu/compass-hub:0.9.0

• Kontener działa jako użytkownik o identyfikatorze 10001: folder danych musi być dla niego zapisywalny, bo hub zapisuje tam hub.json, dziennik zmian, notatki, zestawy zmian i hub.log.
• Modele: pliki .qea/.qeax w folderze danych, ze ścieżkami widzianymi z wnętrza kontenera (na przykład model.file=/data/models/shop.qea w app.properties źródła), albo baza danych. Obraz ma unixODBC dla SQL Server, MySQL i Oracle; linuksowy sterownik ODBC producenta (na przykład pakiet msodbcsql18 Microsoftu) trzeba dodać w obrazie zbudowanym na tym obrazie. PostgreSQL i pliki EA niczego więcej nie potrzebują.

Polecenie LoonarCompass.exe --hub C:\Hub\hub.json nadal działa: aplikacja desktopowa uruchamia wtedy hub bez okna. Hub zapisuje dziennik pracy w pliku hub.log obok hub.json. compass-hub --version wypisuje wersję.

Sekrety huba

Klucze, tokeny i hasła nie leżą w hub.json. compass-hub bierze każdy z nich ze zmiennej środowiska LOONAR_SECRET_<NAZWA> albo z pliku wskazanego w LOONAR_SECRET_<NAZWA>_FILE (na przykład sekretu Dockera); w Windows także z Menedżera poświadczeń konta, na którym działa hub. Dla usługi Windows ustaw je jako systemowe zmienne środowiska.

Konta i logowanie

Do widoku webowego (https://<hub>/; http:// tylko na tym samym komputerze) ludzie logują się nazwą użytkownika i hasłem. Compass i klienci MCP używają tokenu API.

• Hasło ma co najmniej 10 znaków i nie może być hasłem domyślnym ani nazwą użytkownika. Hub przechowuje hasła tylko jako skróty PBKDF2.
• Zalogowanie trwa 12 godzin; Sign out kończy je od razu.
• Po 20 błędnych hasłach albo tokenach z jednego adresu ten adres jest odrzucany przez 10 minut.
• Link Sign in with a token instead na stronie logowania pozwala zalogować się tokenem API.

Zakładka Users (tylko dla administratorów):

• Add a user (dodaj użytkownika): nazwa, rola i pierwsze hasło, które użytkownik musi zmienić przy pierwszym logowaniu.
• Role: zmienia rolę (viewer, architect albo admin).
• Reset password: ustawia nowe hasło, które użytkownik musi zmienić przy następnym logowaniu.
• New API token: token dla Compassa (Ustawienia → Zespół (Compass Hub)) i dla klientów MCP. Jest pokazywany tylko raz, a poprzedni token użytkownika przestaje działać.
• Remove: usuwa użytkownika. Hub zawsze zachowuje co najmniej jednego administratora, a siebie usunąć nie możesz.

Zmiana albo usunięcie użytkownika kończy jego zalogowania. Każda zmiana użytkowników trafia do dziennika zmian.

Logowanie kontem firmowym (OpenID Connect)

Ludzie mogą logować się do widoku webowego kontem firmowym: AD FS, Microsoft Entra ID, Keycloak, Okta i inni dostawcy OpenID Connect. Strona logowania pokazuje wtedy przycisk Sign in with your company account. Dopisz do hub.json:

"oidc": {
  "issuer": "https://adfs.example.com/adfs",
  "client_id": "<identyfikator klienta od dostawcy>",
  "redirect_uri": "https://hub.example.com/auth/callback",
  "groups_claim": "groups",
  "roles": { "admin": ["Compass-Admins"], "architect": ["Compass-Architects"], "viewer": ["Compass-Viewers"] },
  "password_login": true
}

• U dostawcy: zarejestruj hub jako poufną aplikację webową z przepływem authorization code, z powyższym adresem przekierowania (adres huba z /auth/callback), zakresami openid profile email (AD FS: allatclaims hub dodaje sam; zmienia je klucz scopes) i oświadczeniem groups z nazwami grup w tokenie ID. Klucz tajny klienta to sekret huba OIDC_CLIENT_SECRET (LOONAR_SECRET_OIDC_CLIENT_SECRET).
• Kontrole: logowanie korzysta z PKCE i jednorazowego parametru state; hub sam sprawdza token ID: podpis RS256 kluczami dostawcy, wystawcę, odbiorcę, ważność i nonce.
• Role z grup: roles podaje grupy, które dają każdą rolę (domyślnie Compass-Admins, Compass-Architects i Compass-Viewers); groups_claim wskazuje oświadczenie z grupami (domyślnie groups). Rola jest ustalana od nowa przy każdym logowaniu, a wygrywa najwyższa. Osoba spoza wszystkich grup nie dostaje dostępu.
• Nazwa użytkownika: name_claim wybiera oświadczenie (domyślnie upn, potem preferred_username, email). Jeśli lokalny użytkownik huba ma tę samą nazwę, logowanie kontem firmowym jest odrzucane, dopóki administrator nie zmieni nazwy tego użytkownika albo go nie usunie.
• Tylko logowanie firmowe: "password_login": false wyłącza logowanie nazwą i hasłem. Tokeny API dla Compassa i klientów MCP działają dalej. button zmienia tekst przycisku.
• Każde logowanie kontem firmowym trafia do dziennika zmian.

Konfiguracja (hub.json)

{"listen":"127.0.0.1:8730",
 "sources":[
  {"id":"shop-db","name":"Shop (PostgreSQL)","properties":"shop-db/app.properties"},
  {"id":"shop-file","name":"Shop (file)","properties":"shop-file/app.properties"}],
 "users":[
  {"name":"anna","role":"admin","password_pbkdf2":"pbkdf2-sha256$210000$..."},
  {"name":"bob","role":"architect","token_sha256":"<SHA-256 tokenu>"}],
 "integrations":{
  "jira":{"url":"https://firma.atlassian.net","user":"<service account>","project":"ARCH","issue_type":"Task"},
  "confluence":{"url":"https://firma.atlassian.net/wiki","user":"<service account>","space":"ARCH","parent":"65818"}},
 "policy":{"min_approval":"ask","ask_min_role":"viewer","ask_per_hour":20,
  "governance":{ ... governance.json ... },
  "event_agents":[{"name":"Zatwierdzone zostają","event":"element_deleting","mode":"guard","applies_to":"Requirement",
    "prompt":"Zablokuj usunięcie wymagania, którego status to Approved."}]}}

• listen: adres i port; domyślnie 127.0.0.1:8730, w Dockerze 0.0.0.0:8730. Poza jednym komputerem postaw hub za HTTPS (zobacz „Bezpieczeństwo huba”).
• sources: modele zespołu. properties to plik app.properties danego modelu (w tym samym formacie co plik ustawień Compassa), ścieżka względem hub.json. Model w SQL Server, MySQL albo Oracle ma tam model.source=sqlserver, mysql albo oracle (rozdział 5), z hasłem z sekretu DB_PASSWORD; serwer potrzebuje sterownika ODBC producenta.
• users: nie musisz ich wpisywać. Pomiń users, żeby dostać domyślnego administratora, a użytkownikami zarządzaj w zakładce Users: hub zapisuje ich z powrotem w hub.json tylko jako skróty (password_pbkdf2, token_sha256). Wpis ze zwykłym "token" (co najmniej 16 losowych znaków) jest nadal przyjmowany i zamieniany na token_sha256, gdy hub zapisuje użytkowników. compass-hub --hub-token (albo LoonarCompass.exe --hub-token) wypisuje nowy losowy token i jego skrót. Nazwy i tokeny muszą być unikalne.
• integrations: Jira i Confluence zespołu (opis niżej); tokeny pochodzą z sekretów huba.
• policy: min_approval (ask, plan lub auto), ask_min_role (kto może korzystać z Ask w widoku webowym; domyślnie viewer), ask_per_hour (pytania na użytkownika i godzinę; domyślnie 20), governance w formacie governance.json oraz event_agents: agenci zdarzeń zespołu, w formacie listy "agents" z event_agents.json, także strażnicy (rozdział 10). Działają w Compassie w EA u każdego, z dopiskiem „(team)”. Administratorzy edytują politykę w zakładce Team policy widoku webowego.
• oidc: logowanie kontem firmowym (opis wyżej).

Nikt, nawet admin, nie zatwierdza własnego zestawu zmian. Zestaw zmian jest wprowadzany w dwóch krokach: jeden Compass go rezerwuje, a po zapisie zgłasza wynik, więc nie da się go wprowadzić dwa razy.

Jira i Confluence z huba

Z integrations w hub.json architekci i administratorzy dostają przyciski w widoku webowym. Hub działa na własnym koncie technicznym: user (e-mail dla Cloud; puste dla Data Center z osobistym tokenem dostępu) i tokeny z sekretów JIRA_TOKEN i CONFLUENCE_TOKEN.

• Create Jira issue przy elemencie (Search → element): zgłoszenie w projekcie project, typu issue_type (domyślnie Task), ze szczegółami elementu w opisie.
• Create Jira issue for this change set w zestawie zmian: jedno zgłoszenie na zestaw zmian, z jego opisem i podglądem; link do zgłoszenia widać w zestawie zmian.
• Publish this package to Confluence w kontroli modelu (Model check) pakietu: strona tekstowa w przestrzeni space (pod stroną parent, jeśli ją podano) z elementami, ich opisami i relacjami. Nie ma na niej obrazków diagramów, bo hub nie ma EA. Kolejna publikacja pakietu zastępuje stronę.

Każda taka akcja trafia do dziennika zmian. Asystent w Ask nadal tylko czyta: nie może tworzyć zgłoszeń ani stron.

Raporty Word i Excel

Wybierz pakiet w drzewie i otwórz Model check: przyciski Word report of the package i Excel report of the package pobierają raport pakietu z podpakietami: opis, elementy i relacje. Raporty nie mają obrazków diagramów, bo hub nie ma EA. Każde pobranie trafia do dziennika zmian.

Widok webowy

Pod adresem https://<hub>/ (http:// tylko na tym samym komputerze) logujesz się nazwą użytkownika i hasłem albo przyciskiem Sign in with your company account, gdy logowanie firmowe jest skonfigurowane. Widok pokazuje drzewo pakietów, wyszukiwanie, szczegóły elementu z analizą wpływu, kontrolę modelu według reguł zespołu, luki, dziennik zmian, notatki zespołu i zestawy zmian, a administratorom także użytkowników i zakładkę Team policy: edytor JSON polityki (min_approval, governance, event_agents, ask_min_role, ask_per_hour), zapisywanej w hub.json. W zakładce Ask asystent odpowiada na pytania o model. Tylko czyta model: nie ma dostępu do plików, Jiry, Confluence ani serwerów MCP i nie może niczego zaproponować ani zapisać; odpowiada na jedno pytanie naraz.

Bezpieczeństwo huba

Hub komunikuje się zwykłym HTTP. Do dostępu z innych komputerów postaw go za reverse proxy z HTTPS (na przykład IIS albo nginx) i podawaj ludziom adres https://. Od razu zmień hasło konta domyślnego. Chroń plik hub.json i folder danych uprawnieniami do plików. Zapytania mają ograniczony rozmiar i czas. Po 20 błędnych hasłach albo tokenach z jednego adresu ten adres jest odrzucany przez 10 minut; poprawny token nadal działa. Błędy wewnętrzne są pokazywane tylko jako identyfikator, a szczegóły są w hub.log. Widok webowy trzyma zalogowanie tylko na czas sesji przeglądarki i ma przycisk Sign out (wyloguj).

IIS z ARR przed hubem: hub nasłuchuje tylko na tym komputerze ("listen": "127.0.0.1:8730"), a witryna IIS z certyfikatem przekazuje ruch na http://127.0.0.1:8730/ (URL Rewrite + Application Request Routing). W ustawieniach proxy ARR wyłącz przepisywanie nagłówków odpowiedzi: reverseRewriteHostInResponseHeaders="false" (Menedżer IIS → serwer → Application Request Routing Cache → Server Proxy Settings → odznacz „Reverse rewrite host in response headers”). Inaczej ARR podmienia adres przekierowania do AD FS lub Entra ID na adres huba i logowanie firmowe się nie udaje. Nagłówek Authorization musi przechodzić bez zmian (domyślnie przechodzi). Hub ufa nagłówkowi X-Forwarded-For tylko od proxy na tym samym komputerze: blokada po błędnych hasłach dotyczy wtedy adresu klienta, a nie wszystkich naraz. Nieudane i odrzucone logowania (hasłem i kontem firmowym) są w zakładce Audit trail z wynikiem ✗ i adresem klienta, a zakładka Users pokazuje też konta firmowe z rolą i czasem ostatniego logowania (tylko do odczytu: rolę zmienia się w grupach u dostawcy).

Serwer MCP

Serwer MCP (tylko odczyt) działa jako JSON-RPC przez HTTP POST pod adresem /mcp, z nagłówkiem Authorization: Bearer <token>. Narzędzia: list_sources, list_packages, search_elements, element_details, impact_analysis, model_lint, gap_analysis.

GraphQL i tabele dla Power BI

Inne narzędzia czytają modele huba z tokenem API (zakładka Users, nagłówek Authorization: Bearer <token>); czytać może każda rola, a niczego nie da się zmienić.

• GraphQL: POST /api/sources/{sourceId}/graphql z {"query": "…"}. Zapytania: packages, package, elements(name, type, stereotype, package, limit), element, diagrams, diagram. Elementy mają attributes, operations, taggedValues, connectors (z source i target) oraz package. Schemat w SDL jest pod GET /api/graphql/schema.
• Tabele: GET /api/sources/{sourceId}/table/{table} zwraca płaską tabelę jako JSON, dla elements, connectors, packages, diagrams, attributes albo tagged_values.
• Power BI: Pobierz dane (Get Data) → Sieć Web (Web) → Zaawansowane (Advanced); adres tabeli, a w nagłówkach żądania HTTP Authorization z wartością Bearer <token API>. Excel i inne narzędzia działają tak samo.

{ elements(type: "Component", limit: 20) { name stereotype taggedValues { name value } connectors { type target { name } } } }

Klucze AI, Jira i Confluence na hubie

Hub może trzymać klucze Claude i konta Jira oraz Confluence zespołu, tak żeby ludzie nie mieli ich na swoich komputerach. Klucze są sekretami huba (zmienne LOONAR_SECRET_<NAZWA> albo pliki LOONAR_SECRET_<NAZWA>_FILE), a w hub.json wskazuje się, kto którego używa:

"ai": {
  "keys": [
    {"for": "anna.architekt@lab.local", "secret": "claude_key_anna"},
    {"for": "role:architect", "secret": "claude_key_team"},
    {"for": "*", "secret": "claude_key_team"}
  ],
  "limits": [
    {"for": "role:viewer", "tokens_per_day": 50000},
    {"for": "*", "tokens_per_day": 300000, "tokens_per_month": 5000000}
  ],
  "models": ["claude-haiku-5-5", "claude-sonnet-5-5"]
},
"policy": {"ai_via_hub": true, "jira_via_hub": true, "confluence_via_hub": true, "web_access": false}

• keys – klucz dla osoby (nazwa z huba albo UPN konta firmowego), dla roli (role:viewer, role:architect, role:admin) albo dla wszystkich (*); wygrywa pierwszy pasujący wpis dla osoby, potem dla roli, potem *. Kto nie ma klucza, dostaje odmowę.
• limits – tokeny (wejście + wyjście) na dzień i na miesiąc, w tej samej kolejności. Zużycie każdej osoby widać w zakładce Users (dziś i w tym miesiącu); szczegóły są w ai_usage.jsonl.
• models – opcjonalnie: tylko te modele.
• Polityka: "ai_via_hub": true – Compass pyta Claude przez hub (bez własnego klucza); "jira_via_hub" i "confluence_via_hub" – Compass korzysta z Jiry i Confluence przez hub, kontem z sekcji integrations (viewer tylko czyta, każda zmiana trafia do audytu z nazwą osoby), a projekt i przestrzeń zespołu są domyślne.

Zasady komputera: wymuszenie huba (GPO, Intune)

Polityka zespołu w hubie działa u tych, którzy są do niego podłączeni. Żeby obowiązywała wszystkich, dział IT ustawia zasady komputera w kluczu HKLM\SOFTWARE\Policies\Loonar\Compass (dla komputera) albo HKCU\SOFTWARE\Policies\Loonar\Compass (dla użytkownika), przez zasady grupy (GPO) albo Intune. Zwykły użytkownik nie może ich zmienić. Zasady tylko zaostrzają ustawienia:

• HubUrl – adres huba zespołu; pole w ustawieniach jest zablokowane.
• RequireHub = 1 – asystent działa tylko po zalogowaniu do huba i z jego polityką. Gdy hub chwilowo nie odpowiada, Compass używa ostatniej otrzymanej polityki (najwyżej sprzed tygodnia); bez niej asystent nie działa.
• WebAccess = 0 – bez internetu (przycisk 🌐 zablokowany).
• UpdateCheck = 0 – bez codziennego sprawdzania nowej wersji.
• MinApproval = ask, plan albo auto – najmniej surowy tryb zatwierdzania.
• AllowedProviders – dozwoleni dostawcy AI, np. anthropic albo anthropic,openai.

Logowanie kontem firmowym: w Ustawienia → Zespół (Compass Hub) przycisk Zaloguj się kontem firmowym otwiera logowanie huba w przeglądarce (AD FS, Entra ID, Keycloak…); po zalogowaniu hub oddaje sesję jednorazowym adresem na tym komputerze (127.0.0.1) i Compass zapisuje ją w Menedżerze poświadczeń zamiast tokenu. Sesja trwa 12 godzin; potem wystarczy zalogować się ponownie. Szablony zasad grupy (LoonarCompass.admx i pliki językowe .adml) są w folderze deploy\policies repozytorium: skopiuj je do C:\Windows\PolicyDefinitions albo do magazynu centralnego domeny. Kto ma na komputerze uprawnienia administratora, może zasady obejść, tak jak w każdej aplikacji.

23. Tryb sprawdzania w potokach CI

Z opcją --check Loonar Compass sprawdza model bez okna i bez modelu AI, na przykład w potoku CI po każdej zmianie modelu albo kodu. Sprawdzenia wykonuje program, więc ten sam model zawsze daje ten sam wynik, a w modelu nic nie jest zapisywane.

LoonarCompass.exe --check --model <plik.qea|app.properties>
  [--package <id|nazwa>] [--rules governance.json] [--code <folder>]
  [--requirements <dokument>] [--cmdb <eksport.csv|json>] [--report raport.md]
  [--junit junit.xml] [--fail-on error|warning|info|never] [--lang en|pl|de|fr]

Co jest sprawdzane

Wynik

• Raport: Markdown na standardowym wyjściu. Zaczyna się od wyniku, PASSED albo FAILED, i liczby grup błędów i ostrzeżeń, a dalej ma sekcję dla każdej części.
• JUnit: zestaw testów (test suite) dla każdej części i przypadek testowy dla każdej grupy ustaleń. Grupy z wagą na progu --fail-on albo wyżej są niepowodzeniami, więc potok pokazuje je jako nieudane testy.
• Kod wyjścia: 0 sprawdzenie przeszło; 1 ustalenia na progu --fail-on albo wyżej; 2 błędne argumenty, model, którego nie da się odczytać, albo plik, którego nie da się zapisać (przyczyna trafia na wyjście błędów).

GitLab CI

Zadanie na runnerze Windows (PowerShell) z Loonar Compass zainstalowanym dla wszystkich użytkowników. Zadanie uruchamia sprawdzenie i publikuje junit.xml jako raport testów:

compass-check:
  tags: [windows]
  script:
    - '& "C:\Program Files\Loonar Compass\LoonarCompass.exe" --check --model model\shop.qea --rules governance.json --code src --junit junit.xml --report report.md | Out-Host'
    - 'if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }'
  artifacts:
    when: always
    paths: [report.md]
    reports:
      junit: junit.xml

GitHub Actions

Zadanie na własnym runnerze Windows (self-hosted) z Loonar Compass zainstalowanym dla wszystkich użytkowników. Zadanie uruchamia sprawdzenie i przesyła junit.xml oraz raport jako artefakt, który wybrany krok raportu JUnit może pokazać jako wyniki testów:

jobs:
  compass-check:
    runs-on: [self-hosted, windows]
    steps:
      - uses: actions/checkout@v4
      - name: Model check
        shell: pwsh
        run: |
          & "C:\Program Files\Loonar Compass\LoonarCompass.exe" --check --model model\shop.qea --rules governance.json --code src --junit junit.xml --report report.md | Out-Host
          exit $LASTEXITCODE
      - name: Publish the results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: compass-check
          path: |
            junit.xml
            report.md

Dla modelu w PostgreSQL podaj w --model plik app.properties bez haseł i ustaw LOONAR_DB_PASSWORD: w GitLabie jako maskowaną zmienną CI/CD, w GitHubie z sekretu (env: LOONAR_DB_PASSWORD: ${{ secrets.EA_DB_PASSWORD }}).

24. Licencja, znaki towarowe i kontakt

Licencja. Loonar Compass jest oprogramowaniem typu freeware. W skrócie:

• korzystanie jest bezpłatne, także zawodowe i komercyjne, na dowolnej liczbie komputerów, bez ograniczeń czasu i terytorium,
• aplikację wolno kopiować i przekazywać innym wyłącznie bezpłatnie, w całości i bez zmian, razem z plikami LICENSE i THIRD-PARTY-NOTICES,
• bez pisemnej zgody właściciela nie wolno jej zmieniać, dekompilować, sprzedawać ani wynajmować (z wyjątkiem uprawnień, których nie można wyłączyć umową),
• odpowiedzi, zmiany w modelu i dokumenty przygotowuje model AI: sprawdzaj je przed zatwierdzeniem, tryb auto włączasz na własne ryzyko, a przed pracą rób kopie zapasowe modelu,
• aplikacja nie zbiera danych (brak telemetrii); treść potrzebna do odpowiedzi trafia bezpośrednio do wybranego dostawcy modelu AI (Anthropic albo OpenAI) na podstawie Twojej umowy z tym dostawcą,
• Enterprise Architect, Claude API, OpenAI API, Confluence, Miro i inne usługi wymagają odrębnych licencji i kont ich dostawców; opłaty za nie ponosisz Ty.

Wiążąca jest polska wersja licencji; wersje angielska, niemiecka i francuska są tłumaczeniami. Pełna treść jest w widoku Informacje oraz w pliku LICENSE.txt w folderze programu. Lista zmian i znanych ograniczeń tej wersji jest w widoku Changelog.

Prywatność i nota prawna. Polityka prywatności: https://loonar.eu/pl/privacy/. Nota prawna: https://loonar.eu/pl/legal/. Link do polityki prywatności jest też w widoku Informacje, w formularzu zgłoszenia błędu i w karcie newslettera.

Kod źródłowy i komponenty open source. Kod źródłowy aplikacji jest publiczny: https://github.com/loonar-eu/loonar-compass. Aplikacja zawiera biblioteki i czcionki open source; każda z nich ma własną licencję. Ich lista jest w pliku THIRD-PARTY-NOTICES.txt w folderze programu, a w widoku Informacje otwiera ją przycisk Pokaż licencje komponentów w części „Komponenty open source”.

Znaki towarowe. Sparx Systems i Enterprise Architect są zarejestrowanymi znakami towarowymi Sparx Systems Pty Ltd. Claude i Anthropic są znakami towarowymi Anthropic, PBC. OpenAI i GPT są znakami towarowymi OpenAI. Atlassian, Confluence i Jira są znakami towarowymi Atlassian. Microsoft, Windows, Word, Excel, PowerPoint, Visio, SharePoint, SQL Server, Entra ID, Power BI, Azure, Azure DevOps i GitHub są znakami towarowymi grupy Microsoft. Oracle i MySQL są zastrzeżonymi znakami towarowymi Oracle i/lub podmiotów powiązanych; MariaDB jest znakiem towarowym MariaDB plc; Okta jest znakiem towarowym Okta, Inc. GitLab jest znakiem towarowym GitLab Inc., ServiceNow – ServiceNow, Inc., a Docker – Docker, Inc. PostgreSQL jest zarejestrowanym znakiem towarowym PostgreSQL Community Association. Loonar Compass jest niezależnym produktem, niepowiązanym z tymi firmami, nieautoryzowanym ani niesponsorowanym przez nie.

Właściciel i kontakt. Loonar Mariusz Głowacki, ul. Gombrowicza 12, 73-110 Stargard.
E-mail: mariusz@loonar.eu, strona: https://loonar.eu (z pytaniami i odpowiedziami). Błędy najwygodniej zgłaszać przez widok Zgłoś błąd (rozdział 20). Problemy z bezpieczeństwem zgłaszaj prywatnie e-mailem na mariusz@loonar.eu, z tematem „Security: Loonar Compass”, a nie w publicznym zgłoszeniu na GitHubie.

Wsparcie projektu. Rozwój aplikacji możesz dobrowolnie wesprzeć na https://suppi.pl/loonar (widok Wesprzyj projekt, rozdział 4).

Loonar Compass 0.9.2 · © 2026 Loonar Mariusz Głowacki. Wszelkie prawa zastrzeżone.