KRET LANGUAGE ACADEMY · DOKUMENTACJA ZE ŹRÓDEŁ

Kontrakt narzędzia i negatywne testy

ADVANCED40 min

Postęp nauki 0 / 3

Zaloguj się na konto użytkownika, aby zachować postęp.

Czego się nauczysz

Prześledź źródła i wyjaśnij opisany kontrakt.
W ToolContractErrors znajdź niezgodną sygnaturę. Opracuj korektę deklaracji i oddziel ją od nadal niedostępnego wykonania AI.

Wymagania wstępne

Ukończ Podstawy i wcześniejszy poziom tej ścieżki.

Wyjaśnienie krok po kroku

Typy argumentów oraz wyniku narzędzia muszą pasować do funkcji KretS. Test odmowy jest poprawny, gdy otrzymujesz oczekiwany kod błędu. Nie zmieniaj deklaracji tak, aby przypadkiem uruchomić niezatwierdzone połączenie z modelem.

Praca z kodem źródłowym

Kontrakt narzędzia i polityka danych — błędy

Narzędzie, którego zadeklarowana sygnatura (`amount String`) nie zgadza się z funkcją KretS (`amount: Int`), oraz nieznana polityka danych modelu — obie deklaracje są odrzucane przy kompilacji.

Plik

1kretai "1.0"
2
3// Model lokalny: serwer modeli na tym komputerze (protokół chat/completions — llama.cpp server, Ollama, LM Studio).
4// Polityka „local-only”: brama wymusza, żeby połączenie kończyło się na adresie pętli zwrotnej — dane nie opuszczają komputera.
5model local.small {
6    provider "local"
7    name "qwen2.5:7b"
8    endpoint "http://127.0.0.1:11434"
9    dataPolicy "local-only"
10    maxOutputTokens 1024
11    timeout 2min
12}
13
14tool counter.read {
15    description "Odczytuje wartość licznika o podanej nazwie."
16    handler "Tools.readCounter"
17    parameter name String "Nazwa licznika, np. orders"
18    returns "Int64"
19    permissions {
20        kretdb.open
21        kretdb.read
22    }
23    sideEffects "none"
24}
25
26tool counter.add {
27    description "Zwiększa licznik o podaną wartość i zwraca nowy stan."
28    handler "Tools.addCounter"
29    parameter name String "Nazwa licznika"
30    parameter amount Int64 "O ile zwiększyć"
31    returns "Int64"
32    permissions {
33        kretdb.open
34        kretdb.read
35        kretdb.write
36    }
37    sideEffects "write"
38    requiresConfirmation true
39}
40
41// Agent tylko do odczytu.
42agent reader {
43    model local.small
44    system "Odpowiadasz krótko i tylko na podstawie danych z narzędzi."
45    tools counter.read
46    permissions {
47        kretdb.open
48        kretdb.read
49    }
50    limits {
51        maxSteps 4
52        maxToolCalls 8
53        timeout 2min
54    }
55}
56
57// Agent, który może zmieniać dane — każde wywołanie narzędzia zapisującego wymaga potwierdzenia.
58agent assistant {
59    model local.small
60    system "Pomagasz prowadzić liczniki. Zanim coś zmienisz, sprawdź obecny stan."
61    tools counter.read counter.add
62    delegates reader
63    permissions {
64        kretdb.open
65        kretdb.read
66        kretdb.write
67    }
68    limits {
69        maxSteps 8
70        maxToolCalls 16
71        timeout 5min
72        maxTokens 200000
73    }
74}

Czytanie kodu linia po linii

Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.

kretai "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
Pusta linia oddziela fragmenty źródła.
// Model lokalny: serwer modeli na tym komputerze (protokół chat/completions — llama.cpp server, Ollama, LM Studio).Komentarz autora; nie jest wykonywany.
// Polityka „local-only”: brama wymusza, żeby połączenie kończyło się na adresie pętli zwrotnej — dane nie opuszczają komputera.Komentarz autora; nie jest wykonywany.
model local.small {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
provider "local"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
name "qwen2.5:7b"Pole tożsamości lub wersji w otaczającym bloku; zachowaj jego kontekst.
endpoint "http://127.0.0.1:11434"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
dataPolicy "local-only"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
maxOutputTokens 1024Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
timeout 2minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
Pusta linia oddziela fragmenty źródła.
tool counter.read {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "Odczytuje wartość licznika o podanej nazwie."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
handler "Tools.readCounter"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
parameter name String "Nazwa licznika, np. orders"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns "Int64"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
sideEffects "none"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
Pusta linia oddziela fragmenty źródła.
tool counter.add {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
description "Zwiększa licznik o podaną wartość i zwraca nowy stan."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
handler "Tools.addCounter"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
parameter name String "Nazwa licznika"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
parameter amount Int64 "O ile zwiększyć"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
returns "Int64"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.writeOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
sideEffects "write"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
requiresConfirmation trueOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
Pusta linia oddziela fragmenty źródła.
// Agent tylko do odczytu.Komentarz autora; nie jest wykonywany.
agent reader {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
model local.smallOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
system "Odpowiadasz krótko i tylko na podstawie danych z narzędzi."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
tools counter.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
limits {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
maxSteps 4Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
maxToolCalls 8Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
timeout 2minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
Pusta linia oddziela fragmenty źródła.
// Agent, który może zmieniać dane — każde wywołanie narzędzia zapisującego wymaga potwierdzenia.Komentarz autora; nie jest wykonywany.
agent assistant {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
model local.smallOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
system "Pomagasz prowadzić liczniki. Zanim coś zmienisz, sprawdź obecny stan."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
tools counter.read counter.addOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
delegates readerOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
kretdb.writeOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
limits {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.
maxSteps 8Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
maxToolCalls 16Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
timeout 5minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
maxTokens 200000Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.
}Zamknięcie struktury otwartej we wcześniejszych liniach.
}Zamknięcie struktury otwartej we wcześniejszych liniach.

Oczekiwany wynik: Pierwszy krok — sukces; dwa kolejne — kod 1 z diagnostyką `KCS-KAI-…`.

Typowy błąd: Nadanie agentowi uprawnień szerszych niż przyznał host — agent nigdy nie ma własnych uprawnień, a narzędzie działa z uprawnieniami ze swojej deklaracji.

Instrukcja, wersje i zapisane wyniki →

Materiały źródłowe do tego tematu

Przeczytaj powiązane rozdziały. Kod i kontrakty zachowano z importu; historia źródeł jest dostępna przy każdym rozdziale.

KretAI — zgodność i wersje / compatibility and versions

Polski

KretAI 1.1: model lokalny (test na serwerze modeli, KCS dla kretai.*).
KretAI 1.2: modele zdalne (decyzja FB-05, Vault).
KretAI 1.x: narzędzia w osobnym procesie, strumieniowanie.
Stary walidator JSON Kret.Formats.AiContractValidator (rc.1) — LEGACY.

Otwórz cały rozdział ze źródłem →

KretAI — kody diagnostyczne / diagnostic codes

Kod / code	Polski
`KCS-KAI-0301`	brak lokalnego serwera modeli (po przejściu bramki uprawnień)
`KCS-KAI-0302`	brak przyznania `kretai.use`/`kretai.model.use`
`KCS-KAI-*`	błędy deklaracji: sygnatura narzędzia, uprawnienia, polityka danych, delegacja, limity

Format: kret-diagnostics/1 (kod, plik, wiersz, kolumna, zakres) / (code, file, line, column, range).

Otwórz cały rozdział ze źródłem →

KretAI — bezpieczeństwo / security

Polski

Agent nie ma własnych uprawnień; narzędzie nie rozszerzy uprawnień agenta.
Argumenty od modelu = dane niezaufane.
Model zewnętrzny: 6 warunków naraz; przekierowania HTTP wyłączone.
Audyt bez treści rozmowy i sekretów.
Prawdziwe modele: NOT_RUN bez zgody właściciela.

Otwórz cały rozdział ze źródłem →

KretAI — rozwiązywanie problemów / troubleshooting

Problem (PL)	Rozwiązanie (PL)
`KCS-KAI-0302`	oczekiwane bez `--grant kretai.use,kretai.model.use,…`
`KCS-KAI-0301`	brak lokalnego serwera modeli — oczekiwane w tej rundzie

Otwórz cały rozdział ze źródłem →

KretAI — samouczek ADVANCED

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretai-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Cel: integracja z Core i innymi językami, KretDB, bezpieczny dostęp do API, pluginy, stan, testy, diagnostyka, uprawnienia.

Narzędzia: kret = <SDK>\Compiler\kret.exe (SDK 1.0.0-rc.3+kret.local.3), kretui-host = <SDK>\UiHost\kretui-host.exe. {DATA}/{OUT} = nowe, puste katalogi.

1. Kontrakt narzędzia i polityka danych — błędy (`KRETAI-A01-ToolContractErrors`)

Projekt: ../../Examples/ADVANCED_ToolContractErrors/ · klasyfikacja VALIDATION_ONLY · Playground LOCAL_VALIDATE

Kroki (katalog roboczy: katalog przykładu):

kret check . --json — w wyniku: "succeeded": true
kret check wrong-signature --json — oczekiwany błąd — w wyniku: KCS-KAI
kret check bad-data-policy --json — oczekiwany błąd — w wyniku: "succeeded": false

Wynik tej rundy: PASS — zob. EXPECTED_OUTPUT.txt.

Otwórz cały rozdział ze źródłem →

Ćwiczenie i sprawdzenie wiedzy

W ToolContractErrors znajdź niezgodną sygnaturę. Opracuj korektę deklaracji i oddziel ją od nadal niedostępnego wykonania AI.

Twoje wyjaśnienie lub rozwiązanie — prywatny szkic na tej stronieSzkic nie jest wysyłany na serwer i znika po opuszczeniu lekcji. Przed wyjściem możesz go skopiować.

Podpowiedzi

KretAI (w SDK `KretAi`) deklaruje modele, narzędzia (funkcje KretS) i agentów. Zamrożone są deklaracje, walidacja oraz bramki uprawnień i polityki danych. **Wykonanie z prawdziwym modelem nie należy do kontraktu 1.0** (KretAI 1.1+, NOT_RUN). W Core KretAI jest DISABLED.
Odczytaj ograniczenia i oczekiwane błędy z dostarczonego samouczka; check i run są oddzielnymi krokami.

Omówienie rozwiązania

Odpowiedź oprzyj na pokazanym kodzie i rozdziale źródłowym. Typy argumentów oraz wyniku narzędzia muszą pasować do funkcji KretS. Test odmowy jest poprawny, gdy otrzymujesz oczekiwany kod błędu. Nie zmieniaj deklaracji tak, aby przypadkiem uruchomić niezatwierdzone połączenie z modelem.

Podsumowanie i następny krok

Zaloguj się na konto użytkownika, aby zapisywać postęp i zakładki. Konta obsługi mogą czytać bez zapisu postępu. Logowanie →

Czego się nauczysz

Wyjaśnienie krok po kroku

Praca z kodem źródłowym

Kontrakt narzędzia i polityka danych — błędy

Materiały źródłowe do tego tematu

KretAI — zgodność i wersje / compatibility and versions

Polski

KretAI — kody diagnostyczne / diagnostic codes

KretAI — bezpieczeństwo / security

Polski

KretAI — rozwiązywanie problemów / troubleshooting

KretAI — samouczek ADVANCED

1. Kontrakt narzędzia i polityka danych — błędy (KRETAI-A01-ToolContractErrors)

Ćwiczenie i sprawdzenie wiedzy

Podsumowanie i następny krok

1. Kontrakt narzędzia i polityka danych — błędy (`KRETAI-A01-ToolContractErrors`)