Gdy coś nie działa w Monolynx: objawy, przyczyny i naprawa

Od czego zacząć diagnozę?

Diagnozę zaczynasz od ustalenia warstwy, w której leży problem. Poniższa kolejność prowadzi od rzeczy najtańszych do sprawdzenia do najdroższych.

1. Zapytaj router

   Komenda /monolynx:next czyta stan repozytorium, ticketu, sprintu, sesji i merge requestów, a potem poleca od jednej do trzech komend z uzasadnieniem. Niczego nie zmienia.

2. Sprawdź konfigurację

   Komenda /monolynx:setup pokazuje stan siedmiu punktów: slug, strona toolchain, LLM Wiki, graf, mutacje, flagi i CLI.

3. Przeczytaj ostatnią linię

   Pętla dyspozytora kończy tick linią SPRINT-RUN:, kolejka linią MR-QUEUE:. Zatrzymanie ma własną linię STOP z powodem.

4. Zajrzyj do sesji

   Komenda claude logs <id> pokazuje, na czym stanęła sesja ticketu w tle.

5. Dopiero potem poprawiaj

   Znana przyczyna wskazuje jedną konkretną naprawę z tabel poniżej.

flowchart TD
  A{"Agent widzi narzędzia Monolynx?"} -- nie --> P["Połączenie: MCP albo CLI"]
  A -- tak --> B{"Komendy startują?"}
  B -- nie --> K["Konfiguracja: slug, toolchain, flagi"]
  B -- tak --> C{"Sprint posuwa się?"}
  C -- nie --> S["Sesje: waiting, blokery, sloty"]
  C -- tak --> D{"Merge requesty wchodzą?"}
  D -- nie --> M["Kolejka: CI, konflikt, zatwierdzenie"]
  D -- tak --> OK["Wszystko działa"]

Połączenie: agent nie widzi Monolynx

Problemy tej warstwy widać od razu: agent nie zna narzędzi albo dostaje odmowę przy pierwszej operacji.

Pełną konfigurację połączenia opisuje wpis Jak połączyć agenta AI z Monolynx, a kanał CLI wpis CLI monolynx dla deweloperów i agentów.

Konfiguracja: komenda odmawia startu

W tej warstwie komendy działają, ale zatrzymują się na początku, bo brakuje im wejścia.

Dlaczego sprint-run nie startuje sesji?

Dyspozytor zaczyna każdy tick od kontroli wstępnej. Kontrola zbiera wszystkie problemy naraz, wypisuje je jako linie ERROR: i WARN:, a na końcu podaje wynik.

WARN: MONOLYNX_AUTOMR nie jest ustawiona na true
ERROR: MONOLYNX_AUTOPUSH nie jest ustawiona na true w środowisku procesu
ERROR: MONOLYNX_BASE_BRANCH i MONOLYNX_MR_TARGET wskazują różne branche
PREFLIGHT: failed problems=2

Brzmienie linii w przykładzie jest poglądowe. Prawdziwy wynik zawsze kończy się linią PREFLIGHT: ok albo PREFLIGHT: failed problems=<n>.

Sesja ticketu stoi albo skończyła się bez wyniku

Problemy tej warstwy widać w polu waiting linii statusu i w werdykcie needs_human.

Jak wejść do sesji i odpowiedzieć, opisuje wpis Sesje w tle: jak obserwować pętle sprintu i odpowiadać agentom.

Merge request nie wchodzi

Kolejka mr-queue sprawdza merge request w stałej kolejności: konflikt, CI, zatwierdzenie, merge. Zatrzymuje się na pierwszej przeszkodzie i mówi, czego potrzebuje, w linii raportu zaczynającej się od "Potrzebne:".

Zamknięcie sprintu i wiki

Ostatnia grupa to problemy przy sprint-end i komendach wiki.

Najczęstsze pytania

Słownik i następny krok

Kontrola wstępna

sprawdzenie środowiska na początku ticku, zanim wystartuje jakakolwiek sesja; w komunikatach nazywana preflight

Linia STOP

jedna linia z powodem, którą sesja albo kolejka kończy turę, gdy potrzebuje decyzji człowieka

Werdykt

stan ticketu albo merge requesta policzony przez skrypt, a nie odgadnięty z opisu

Runda poprawek

jedna próba naprawy czerwonego CI przez kolejkę; limit to dwie

Kolizja testów

błędy testów spowodowane współdzieleniem środowiska przez równoległe sesje

Idempotentny

bezpieczny do powtórzenia: drugie uruchomienie nie zmienia wyniku pierwszego

Cały obieg, w którym te problemy mogą się pojawić, opisuje przewodnik Sprint z Monolynx krok po kroku, a pierwszą konfigurację wpis Pierwszy projekt w Monolynx.