Diagnostyka JSON w Zero: ustrukturyzowane błędy kompilatora dla agentów

Najważniejsza funkcja

Najbardziej charakterystyczna cecha Zero to nie element składni. To sposób, w jaki kompilator rozmawia z tym, kto (lub co) czyta jego wyjście.

Przepuść błędny program przez zero check --json, a dostaniesz dane, które agent może od razu przeczytać:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

To mały, ale treściwy fragment. Omówmy każde pole i decyzje projektowe, które za nim stoją.

Anatomia komunikatu diagnostycznego

Komunikat diagnostyczny to ustrukturyzowany obiekt opisujący jeden problem w kodzie źródłowym. Kanoniczne pola:

• code: stabilny identyfikator (np. NAM003). Zawsze oznacza to samo, niezależnie od wersji kompilatora.
• message: opis czytelny dla człowieka. Jego treść może się zmieniać między wersjami; znaczenie przypina code, a nie komunikat.
• line (i inne pola położenia): gdzie jest problem.
• repair: opcjonalne ustrukturyzowane metadane opisujące poprawkę, która według kompilatora usunie problem. Kształt tego pola sam jest udokumentowany i stabilny.

Kształt najwyższego poziomu zawiera wartość logiczną ok dla całego uruchomienia i tablicę diagnostics; nawet gdy uruchomienie się powiedzie, tablica może zawierać ostrzeżenia lub uwagi.

Stabilne kody błędów

Umowa dotycząca code najpewniej cię zaskoczy. NAM003 oznacza dziś "nieznany identyfikator". NAM003 za miesiąc i za rok też będzie oznaczać "nieznany identyfikator". Agenci (i ludzie) mogą na tym polegać.

To ważne, bo modele językowe i narzędzia mają skłonność do zapamiętywania tego, co widziały. Gdyby znaczenie NAM003 zmieniało się z każdym wydaniem, każde zapamiętane wyszukiwanie byłoby niebezpieczne. Przypięcie kodu sprawia, że:

• Dane treningowe agentów pozostają aktualne między wersjami.
• Dokumentację można indeksować po kodzie.
• Potoki narzędziowe pozostają stabilne.

Czytelny dla człowieka message może się zmieniać, gdy zespół poprawia sformułowania. To code jest identyfikatorem, na którym wszystko się opiera.

Metadane naprawy

Pole repair, jeśli jest obecne, mówi odbiorcy, jaki rodzaj poprawki według kompilatora zadziała:

{
    "code": "NAM003",
    "message": "unknown identifier",
    "line": 3,
    "repair": { "id": "declare-missing-symbol" }
}

declare-missing-symbol to tutaj rodzaj naprawy, czyli ogólny zamiar. Aby dostać konkretne edycje, wywołaj zero fix --plan --json. Zwraca to plan zawierający ścieżkę pliku, zakresy bajtów do zmiany i nowy tekst:

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

(Dokładne nazwy pól i kształt mogą się różnić w twojej wersji toolchaina; zasada brzmi: "ustrukturyzowane dane, nie proza".)

Agent czytający plan ma kilka możliwości:

1. Zastosować edycje bez zmian.
2. Zastosować edycje z modyfikacjami.
3. Odrzucić plan i sięgnąć po inną poprawkę.

W każdym przypadku agent pracuje na ustrukturyzowanych danych, zamiast próbować zinterpretować sugestię po angielsku. Na tym polega różnica między planami naprawy a podpowiedziami "czy chodziło ci o ...?" w typowym kompilatorze.

Jak agent faktycznie z tego korzysta

Uproszczona pętla, którą agent może wykonywać od początku do końca:

1. Wygeneruj lub zmodyfikuj plik Zero.
2. Uruchom na nim zero check --json.
3. Jeśli wynik to { "ok": true, ... }, przejdź dalej.
4. W przeciwnym razie dla każdego komunikatu diagnostycznego:
   • Sprawdź code, aby zrozumieć, co jest nie tak (przez zero explain albo lokalną tabelę).
   • Jeśli zaproponowano repair i wygląda bezpiecznie, wywołaj zero fix --plan --json, aby dostać edycje.
   • Zastosuj (lub zasymuluj) edycje.
5. Wróć do kroku 2.

Porównaj to z pracą na komunikacie tekstowym: agent musi sparsować angielski tekst, wyciągnąć prawdopodobny numer linii, zgadnąć rodzaj poprawki i wywnioskować dokładny tekst do wstawienia lub zamiany. Każdy krok jest niepewny. Ścieżka JSON zastępuje każdy z nich wyszukaniem w udokumentowanym schemacie.

Nie tylko błędy: graf i rozmiar

--json nie służy tylko do diagnostyki. Inne polecenia udostępniają ustrukturyzowane dane w ten sam sposób:

• zero graph --json: zwraca graf zależności pakietu jako ustrukturyzowane dane. Przydaje się do zrozumienia, co od czego zależy, oraz agentom, które chcą przeanalizować miejsca wywołań, zanim cokolwiek zmienią.
• zero size --json: raportuje rozmiar skompilowanych artefaktów na dysku z podziałem na cele. To te same dane, które ludzie widzą w zero size, tylko w formie do parsowania.

Te kształty są częścią projektu: zawsze gdy kompilator ma użyteczne dane, są one dostępne jako JSON, aby narzędzia mogły z nich korzystać bez zeskrobywania ekranu.

Jak wygląda schemat

Nazwy pól i dokładne kształty są udokumentowane w repozytorium Zero i będą ewoluować, dopóki projekt jest przed wersją 1.0. Kategorie, których możesz się spodziewać:

• Metadane uruchomienia: ok, version, czasy.
• Diagnostyka: code, message, położenie (plik/linia/kolumna/zakresy bajtów), poziom ważności (błąd/ostrzeżenie/uwaga), opcjonalne repair.
• Plany naprawy: po pobraniu, ustrukturyzowana lista edycji.

Jeśli budujesz narzędzia na tej powierzchni, bezpieczny wzorzec to czytać znane pola, łagodnie ignorować nieznane i opierać decyzje o zachowaniu na code.

Krótki przykład od początku do końca

Załóżmy, że twój kod używa identyfikatora, który nie został zadeklarowany:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' nie jest nigdzie zdefiniowane
}

Uruchomienie zero check --json daje mniej więcej:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier 'answer'",
            "line": 2,
            "column": 27,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

zero fix --plan --json zwraca edycję:

{
    "diagnostic": { "code": "NAM003", "line": 2 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

zero fix (bez --plan) stosuje edycję w miejscu, po czym zero check zwraca ok: true. Każdy krok to odrębna transakcja, którą można sprawdzić.

Dlaczego to ważne nie tylko dla agentów

Te same właściwości (ustrukturyzowane wyjście, stabilne kody, plany naprawy) ułatwiają też życie:

• Edytorom i IDE. Podkreślenia i żaróweczki działające na identyfikatorach repair zamiast na sparsowanym tekście.
• Potokom CI. Błędy logowane z code, łatwe do wyszukania i pokazania na dashboardach.
• Narzędziom do masowych zmian w kodzie. Hurtowe poprawki celujące w kod błędu, a nie w wyrażenie regularne na komunikatach.

System zaprojektowano z myślą o agentach, ale narzędzia dla ludzi zyskują na nim tak samo.

Dalej: projektowanie z myślą o agentach

System diagnostyki to najbardziej konkretny przykład filozofii Zero, w której agenci są na pierwszym miejscu. Następny artykuł, projektowanie z myślą o agentach, wraca do ogólnych zasad (mała powierzchnia, deterministyczne narzędzia, jawne efekty) i pokazuje, dlaczego każda z nich jest potrzebna.