Notatki inżynierskie Naly: Codex CLI, JSON w strukturze i pracownicy AI bezpieczni dla crona

Streszczenie

Naly używa Codex CLI jako płaszczyzny sterowania dla zaplanowanej pracy AI: każdy wpis crona uruchamia sprawdzony skrypt, który inicjuje ograniczone zadanie asystenta z wyszukiwaniem w sieci i ścisłym kontraktem wyjścia, po czym zapisuje zweryfikowane artefakty JSON do dalszego publikowania, odtwarzania i ponawiania. Dzięki temu praca modelu zachowuje się jak operacyjny pipeline — to samo polecenie, jawny schemat, jawne artefakty — zamiast elastycznego interakcyjnego workflow. Na dzień 2026-06-25 ta różnica stanowi przewagę niezawodności dla infrastruktury treści krytycznej dla wzrostu.

Gdzie to siedzi w Naly

Naly ma już aktywne priorytety GST wokół procesów odkrywania, retencji i dystrybucji. Ten wzorzec bezpośrednio pasuje do tej warstwy wykonawczej:

Zadania cron wywołują pojedynczy tsx skrypt na przypadek użycia, dzięki czemu każde uruchomienie pozostaje w wersjonowanym kodzie, a nie w ad hoc fragmentach powłoki.
Codex CLI wykonuje rozumowanie i pracę retrieval, podczas gdy Naly odpowiada za orkiestrację: harmonogram, ponawianie, blokowanie i trwałe artefakty.
Wyjście strukturalne zasila systemy downstream oparte na Next.js, React, Drizzle ORM i Neon bez zgadywania schematów po stronie odbiorczej.
Zewnętrzne logi i metadane uruchomienia są zapisywane w NALY_LOG_ROOT, co sprawia, że post-mortemy są odtwarzalne niezależnie od buforowania wyjścia procesu.

Teza brzmi: w produkcyjnym użyciu jakość LLM to tylko połowa systemu; drugą połową są deterministyczne granice wokół tego LLM.

Mechanizm techniczny

1) Punkt wejścia pracownika nastawiony na kontrakt

Każde zadanie startuje z trzech niezmiennych wejść:

Sformalizowany szablon promptu i intencja zadania.
Schemat odpowiedzi, który musi zostać zweryfikowany.
Otoczka uruchomienia (run_id, source_query, attempt, env), utrwalana przed wywołaniem API.

Naly uruchamia Codex CLI w trybie wsadowym z crona, a nie w trybie interaktywnym. Codex jest dokumentowany jako lokalny agent kodowania i dostarczany jako samodzielne CLI o otwartym kodzie źródłowym z aktywnymi wydaniami, i może być uruchamiany w środowisku skryptowym Codex CLI, repozytorium OpenAI Codex.

2) Dlaczego strukturalne wyjście jest nie do negocjacji

Przewodniki OpenAI dotyczące structured-output opisują ekstrakcję schematu wspieraną przez parser i zachowanie trybu ścisłego potrzebne do pipeline'ów maszynowych. W Naly wynik modelu traktowany jest jako artefakt pośredni, a nie ostateczna prawda, więc to na kontrakcie JSON egzekwowana jest niezawodność:

wymagane pola (nagłówek, lista dowodów, pewność, cytowania, powód niepowodzenia)
opcjonalne pola z wartościami domyślnymi
liczbowa pewność i ograniczone wyliczenia (enumy)
jawne błędy parsera ujawniane jako błędy uruchomienia, a nie cicho automatycznie korygowany tekst.

3) Cykl cron→agent z kontrolą współbieżności

Cron wykonuje zaplanowane linie zgodnie ze standardowymi pięciopolowymi polami czasu i uruchamia polecenie, gdy pola się pokrywają crontab. Dla bezpieczeństwa produkcyjnego Naly dodaje:

zabezpieczenie blokadą (pojedyncze aktywne uruchomienie na zadanie)
idempotentny klucz uruchomienia
ograniczona polityka ponawiania z jitterem
zewnętrzny zapis logów dla każdej fazy
aktualizacja stanu po uruchomieniu w tabelach bazy danych zarządzanych przez Drizzle/Neon.

flock zostało zaprojektowane dokładnie pod ten wzorzec zabezpieczenia: pobierz lock, wykonaj sekcję krytyczną, zakończ się czysto, gdy jest już zablokowane flock. Ponieważ stan blokady opiera się na deskryptorach plików, nakładające się okna crona są jawnie odrzucane zamiast uszkadzać stan.

4) Dlaczego MCP ma znaczenie w tym wzorcu

Model Context Protocol formalizuje kontrakty narzędzi host/client/server przy użyciu JSON-RPC, negocjacji możliwości i strukturalnych wywołań narzędzi MCP. W Naly granice w stylu MCP redukują ukryte sprzężenie: wyszukiwanie w sieci można przedstawić jako kontrolowany interfejs narzędzia z jawnymi możliwościami zamiast swobodnego zachowania na poziomie powłoki.

Co mówią badania

Najnowsze badania pokazują, że niezawodność nie jest równoznaczna z surową sprawnością. Paper o niezawodności agentów AI raportuje znaczące luki między trafnością zadania a spójnością pomiędzy uruchomieniami i proponuje jawne wymiary niezawodności (spójność, odporność, przewidywalność, bezpieczeństwo) do oceny operacyjnej Towards a Science of AI Agent Reliability. To wspiera projekt Naly run-state-first: jeśli uruchomienie kończy się powodzeniem, ale nie może zostać powtórzone z jasnymi artefaktami, nie ma jakości produkcyjnej.

W przypadku wyjść strukturalnych ToolPRM argumentuje, że zachowanie strukturalnego wywoływania narzędzi wymaga jawnego nadzoru, a największe poprawy pojawiają się przy modelowaniu wewnętrznego procesu wywołań funkcji, a nie jedynie końcowych rezultatów. ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Calling. To jest spójne z pętlą wykonawczą Naly nastawioną na schemat: bramka jakości jest na granicach interfejsu, nie tylko w płynności treści.

Trzecie opracowanie na tej samej granicy, SLOT, pokazuje praktyczną alternatywną ścieżkę przez dodanie warstwy kształtowania wyjścia niezależnej od modelu na szczycie LLM-ów SLOT: Structuring the Output of Large Language Models. Potwierdza to tę samą zasadę: niezawodność struktury to problem inżynierski, nawet gdy jakość modelu bazowego jest wysoka.

Dylematy projektowe

Sztywny schemat vs. przenośność modelu: rygorystyczne schematy redukują niejednoznaczność downstream, ale mogą czasami zwiększać liczebność błędów parsowania, gdy dostawcy inaczej interpretują ograniczenia.
Prostota crona vs. elastyczność kolejki: cron jest prosty i widoczny, ale przy nagłych skokach obciążenia potrzebny jest mechanizm backoff z uwzględnieniem blokad lub warstwa kolejki, aby uniknąć nakładających się uruchomień i pominiętych okien.
Wyszukiwanie w zadaniu vs. deterministyczne odtwarzanie: świeże wyszukiwanie web poprawia aktualność, ale wprowadza zmienność źródeł; dlatego Naly zapisuje treść zapytania, listę źródeł i surowe referencje w artefaktach uruchomienia.
Zewnętrzne logi vs. logi wyłącznie z bazy danych: logi systemu plików przetrwają restarty procesu i są tanie w ingestowaniu; logi DB ułatwiają ergonomię zapytań, ale przy złym partycjonowaniu mogą otwierać pętle fail-open.

Tryby awarii

Dryf schematu: wyjście dostawcy narusza schemat; środkiem zaradczym jest ścisła walidacja fail-fast, przypięcie wersji schematu i uruchomienia dead-letter.
Nakładające się wykonania crona: podwójne zapisy lub powielone działania zewnętrzne; środkiem zaradczym jest advisory lock + ochrona zakończenia procesu.
Niestabilność wyszukiwania: odpowiedź narzędzia nadrzędnego zmienia się między próbami; środkiem zaradczym są limity ponawiania, wykładnicze opóźnienie i trwałe referencje upstream.
Niespodzianki czasowe: różnice DST i strefy czasowej hosta mogą wpływać na semantykę harmonogramu; środkiem zaradczym jest polityka harmonogramowania w UTC i jawne kontrole środowiska.
Ciche częściowe zapisy: parser przechodzi pomyślnie, ale zapis downstream kończy się błędem; środkiem zaradczym jest transakcyjna kolejność trwałości i idempotentne upserty.
Wycieki bezpieczeństwa/kontekstu: każda ścieżka agenta z uprawnieniami do narzędzi może wykraczać poza zakres, więc niezbędne są granice w stylu MCP z zasadą najmniejszych uprawnień i jawne założenia dotyczące zgody/uwierzytelnienia, zwłaszcza tam, gdzie ścieżki wykonywania narzędzi dotykają zasobów sieciowych Notatki bezpieczeństwa MCP.

Wskazówki wdrożeniowe

Trzymaj jedno polecenie pracownika dla każdego zadania biznesowego w scripts/ i pozwól, aby cron wywoływał wyłącznie ten punkt wejścia.
Zapisuj hash pliku schematu w metadanych uruchomienia, aby oczekiwania parsera były audytowalne po aktualizacji modelu.
Ustaw set -euo pipefailzachowanie w stylu `set -e` w skryptach wrapperów i zawsze dołączaj identyfikatory uruchomień do nazw logów.
Zapisuj trzy punkty kontrolne do logów: started, codex_result_parsed, artifact_persisted.
Używaj NALY_LOG_ROOT tak, aby ślady wykonania nigdy nie zanieczyszczały stanu repozytorium i przetrwały w kontekstach restartu.
Zachowuj attempt, exit_code, retry_reason, i validation_errors aby panele GST i audytu mogły rozdzielić niestabilną infrastrukturę od prawdziwych regresji modelu.