Dokumentacja konfiguracji

Konfiguracja składa się z trzech plików: kancelaria.yaml, sprawy.yaml i cennik.yaml. Edytor zapisuje dokładny tekst pól bez interpretacji przez AI. Obsługiwane pola i wartości opisano poniżej. Nieznane pola są błędem.

Przepływ odpowiedzi

Wiadomość w Inbox → odczyt aktualnej konfiguracji → rozpoznanie sprawy → wybór ważnych informacji i cen → propozycja AI → walidacja → ewentualna redakcja mieszana → szkic do kontroli pracownika.

Konfiguracja jest sprawdzana przed dostępem do poczty. Wykluczenia i reguły obsługi ręcznej mają pierwszeństwo przed dopasowaniem AI. Załączniki pozostają do oceny przez pracownika. Brak pewnego dopasowania lub niepoprawny wynik AI kieruje wiadomość do obsługi ręcznej.

AI dobiera zatwierdzone treści; w trybie mieszanym może redagować dozwolone bloki. Ceny i ich warunki są wstawiane z konfiguracji bez redagowania. Aplikacja nie oblicza indywidualnych sum kosztów.

Aktywacja i historia

Zapis sprawdza składnię, wymagane pola, powiązania i daty całego zestawu. Jeśli walidacja się nie powiedzie, aktywna konfiguracja pozostaje bez zmian. Poprawny zestaw zostaje zapisany jako nowa wersja i aktywowany jednocześnie dla wszystkich trzech plików.

Trwające przetwarzanie kończy się na wcześniej wczytanej konfiguracji; kolejne uruchomienie odczytuje nową. Zmiana konfiguracji nie generuje ponownie odpowiedzi na już obsłużone wiadomości. Przywrócenie wcześniejszej konfiguracji tworzy kolejną wersję, podlegającą tej samej walidacji.

Każde pole może zawierać do 256 KB tekstu UTF-8. Przy jednoczesnej edycji zapis starego formularza jest odrzucany. Panel nie identyfikuje autorów zmian, ponieważ nie wymaga logowania.

Identyfikatory i powiązania

Nazwy spraw i pozycji cenowych są stałymi identyfikatorami. Zaczynają się małą literą i zawierają małe litery a-z, cyfry, _ lub -. Nazwa sekcji cennika musi wskazywać istniejącą sprawę. zastepuje wskazuje inne sprawy; odwołania do siebie, brakujących spraw i cykle są odrzucane.

System tworzy identyfikatory sprawa.<nazwa>.fact, sprawa.<nazwa>.question i cena.<sprawa>.<pozycja>. Nie wpisuj ich ręcznie do plików.

Kancelaria

Poniżej fikcyjny przykład do zastąpienia własnymi danymi:

nazwa: 'Kancelaria Przykładowa — dane fikcyjne'
email: kancelaria@example.invalid
podpis: |-
  Kancelaria Przykładowa — dane fikcyjne
  ul. Wymyślona 10, Miasto Przykładowe
styl: 'Odpowiadaj uprzejmie, krótko i wyłącznie na zadane pytania.'
powitanie: 'Dzień dobry,'
zakonczenie: 'Z poważaniem,'
kontakt:
  adres: 'ul. Wymyślona 10, Miasto Przykładowe — dane fikcyjne'
  www: 'https://example.invalid/'
godziny_pracy: 'PRZYKŁAD FIKCYJNY: Pracujemy od poniedziałku do piątku, 9:00–17:00.'
wykluczenia: [reklamacja, skarga]
obsluga_reczna: [spór, przymus]

Opcjonalne redakcja i brzmienie w kancelaria.yaml ustawiają sposób redagowania odpowiedzi. Szczegóły i wartości: redakcja mieszana. Bez tych ustawień działa dotychczasowy tryb dosłowny.

Opcjonalne dopasowanie: ai włącza semantyczny wybór spraw z obsługą niepewności; domyślne slowa zachowuje dopasowanie słowne. Zobacz dopasowanie AI.

Wymagane są nazwa, email, podpis, styl, powitanie, zakonczenie. Pozostałe pola są opcjonalne:

jezyk: domyślnie pl. Aplikacja nie tłumaczy gotowych tekstów.
strefa_czasowa: domyślnie Europe/Warsaw; określa dzień ważności treści i cen.
kontakt: opcjonalne telefon, adres, www. Dane kontaktowe nie są automatycznie przepisywane do podpisu lub spraw.
godziny_pracy: gotowy tekst odpowiedzi na pytania o godziny. Aplikacja tworzy dla niego sprawę godziny i typowe słowa rozpoznawania. Jeżeli potrzebujesz własnych słów lub dat ważności, pomiń to pole i utwórz sprawę godziny w kolejnym pliku. Nie definiuj obu naraz.
wykluczenia i obsluga_reczna: listy słów kierujących wiadomość do pracownika bez szkicu, z różnymi powodami wewnętrznymi. Domyślnie są puste. Sprawdzane są przed wyborem spraw.

email oznacza nadawcę szkicu, a nie login/hasło IMAP. Ustawienie skrzynki pozostaje zadaniem administratora.

Sprawy

Każda sekcja zaczyna się od krótkiej nazwy sprawy. Przykład redakcyjny do zatwierdzenia:

darowizna:
  rozpoznaj: [darowizna, darowizny, darowiźnie]
  zapytaj: |-
    Prosimy o wskazanie przedmiotu darowizny,
    jeśli nie został jeszcze opisany w wiadomości.

Pole	Zasada
`redakcja`	Opcjonalnie `doslowna` lub `mieszana`; nadpisuje domyślny tryb kancelarii dla odpowiedzi i pytania.
`brzmienie`	Opcjonalne ustawienia tonu, długości i formy; nadpisują wskazane opcje globalne.
`opis`	Opcjonalny opis sprawy dla AI, najwyżej 1000 znaków. W trybie AI wymagany, jeśli brak przykładowych słów.
`rozpoznaj`	W trybie `slowa` obowiązkowa niepusta lista z wariantami odmiany. W trybie `ai` opcjonalne przykłady, jeśli podano opis; model rozpoznaje znaczenie.
`odpowiedz`	Opcjonalny gotowy blok informacji. W trybie dosłownym AI wybiera go bez zmian; w mieszanym może redagować na jego podstawie.
`zapytaj`	Opcjonalny gotowy blok pytania o brakujące informacje.
`od`, `do`	Opcjonalne daty w cudzysłowie `'RRRR-MM-DD'`. Obie granice są wliczane; odnoszą się do odpowiedzi i pytania.
`zastepuje`	Opcjonalna lista innych spraw, które ta szczegółowa sprawa ma wyłączyć po dopasowaniu. Bez cykli i odwołań do siebie.

Możesz mieć odpowiedź, pytanie albo oba bloki. Sprawa z samym rozpoznaj może służyć do wyboru cen. Daty przy sprawie bez tekstów są błędem. Pusty plik spraw zapisuj jako {}.

Jedna sprawa ma najwyżej jedną odpowiedź i jedno pytanie, ale każde może być wielowierszowe. Jeśli treści mają różne warunki rozpoznawania lub okresy ważności, utwórz osobne sprawy. Nie wpisuj kwot i zasad odpłatności do zwykłych odpowiedzi.

zastepuje działa na bezpośrednio wymienione nazwy, nie na cały łańcuch powiązań. Nie wyłączaj ogólnej sprawy koszty, jeśli sprawa szczegółowa nie ma treści odpowiadającej na pytanie o cenę. Używaj tego pola tylko przy rzeczywistym nakładaniu się tematów.

Cennik

Dopóki ceny nie są zatwierdzone, cały plik zawiera:

{}

Aby dodać ceny, zastąp {} sekcją o nazwie istniejącej sprawy. Poniższa kwota, warunki i daty są fikcyjne, nie są propozycją stawki notarialnej:

darowizna:
  przykladowa_usluga:
    kwota: '123.00'
    waluta: PLN
    opis: 'PRZYKŁAD FIKCYJNY: Cena usługi przykładowej: {kwota} {waluta}.'
    warunki: 'PRZYKŁAD FIKCYJNY: Kwota brutto za usługę przykładową, bez opłat zewnętrznych; zakres wymaga potwierdzenia.'
    od: '2026-01-01'
    do: '2026-12-31'

kwota musi być tekstem w cudzysłowie, z kropką i najwyżej dwoma miejscami dziesiętnymi; waluta to trzy wielkie litery.
opis przy kwocie jest opcjonalny; domyślnie: Cena: {kwota} {waluta}.. Własny opis musi zawierać oba znaczniki dokładnie po jednym razie.
warunki, od, do są zawsze obowiązkowe. Wpisz rzeczywisty zakres, warunki i okres obowiązywania, nie datę pobrania informacji ze strony.
Aby przekazać regułę zamiast konkretnej kwoty, wpisz opis, warunki, od, do i pomiń oba pola kwota i waluta.
Każda sprawa może mieć kilka nazwanych pozycji cenowych. Powiązanie wynika z nazwy sekcji; nie podajesz topics.

Warunki będą zawsze dołączone do odpowiedzi. Aplikacja nie oblicza sum ani podatków i nie potwierdza spełnienia warunków przez klienta. Cena jest dostępna tylko wtedy, gdy pasuje sprawa i data. Nieznana nazwa sprawy jest błędem konfiguracji.

Redakcja mieszana

Tryb mieszany pozwala AI redagować wybrane odpowiedzi i pytania na podstawie zatwierdzonych tekstów. Ceny i ich warunki aplikacja wstawia dosłownie po redakcji. Powitanie, zakończenie, podpis oraz nagłówki wiadomości również pozostają pod kontrolą aplikacji.

Stare konfiguracje działają bez zmian: brak ustawienia redakcja oznacza tryb doslowna. Nie ma automatycznego przełączenia wdrożonych profili. Lokalny profil Mania korzysta z trybu mieszanego dla wybranych pytań; informacje kontaktowe, biograficzne, terminy i blok kosztowy oznaczono jako dosłowne.

Ustawienia właściciela

W kancelaria.yaml ustaw wartości domyślne:

redakcja: mieszana
brzmienie:
  formalnosc: neutralna
  dlugosc: standardowa
  zwrot: panstwo
  uklad: automatyczny
  ton: zyczliwy
  slownictwo: proste
  wskazowki: 'Pisz konkretnie. Nie powtarzaj pytań o informacje już podane.'

W sprawy.yaml możesz nadpisać tylko potrzebne pola:

dokumenty:
  rozpoznaj: [dokumenty, dokumentów, przygotować]
  redakcja: mieszana
  brzmienie:
    dlugosc: krotka
    uklad: lista
  zapytaj: |-
    Prosimy o wskazanie rodzaju planowanej czynności i jej przedmiotu,
    w zakresie, którego jeszcze Państwo nie opisali.

Przykład jest propozycją redakcyjną, nie listą wymagań prawnych. Treść wymaga zatwierdzenia przez kancelarię.

Pole	Wartości	Domyślnie / działanie
`redakcja`	`doslowna`, `mieszana`	`doslowna`; AI wybiera bloki bez zmiany tekstu
`formalnosc`	`formalna`, `neutralna`, `swobodna`	`neutralna`; swoboda nadal oznacza uprzejmy język
`dlugosc`	`krotka`, `standardowa`, `szczegolowa`	`standardowa`; szczegółowość może pochodzić tylko z zatwierdzonej treści
`zwrot`	`panstwo`, `bezosobowo`	`panstwo`; forma bezosobowa unika bezpośrednich zwrotów do klienta
`uklad`	`akapity`, `lista`, `automatyczny`	`automatyczny`; lista tam, gdzie ma sens, nie wymuszone wypunktowanie każdego zdania
`ton`	`rzeczowy`, `zyczliwy`, `empatyczny`	`zyczliwy`; empatia nie uprawnia do obietnic ani dopisywania okoliczności
`slownictwo`	`proste`, `specjalistyczne`	`proste`; specjalistyczne zachowuje terminologię źródła, nie dodaje interpretacji prawnych
`wskazowki`	Tekst 1–1000 znaków	Opcjonalne; dodatkowe preferencje językowe, bez nowych faktów i cen

brzmienie w sprawie nadpisuje pojedyncze pola ustawień globalnych, a nie całą sekcję. redakcja sprawy ma pierwszeństwo przed ustawieniem globalnym i dotyczy zarówno odpowiedz, jak i zapytaj. Ustawienia brzmienia mają wpływ na etap redakcji; nie zmieniają treści bloków dosłownych ani podpisu. Długość i ton to wskazówki dla modelu, nie deterministyczne gwarancje stylistyczne.

Ogólne pole styl nadal jest wymagane: trafia do doboru bloków oraz redakcji. Szczegółowe ustawienia ułatwiają spójny opis oczekiwań. Unikaj sprzecznych poleceń między styl i brzmienie.

Treści chronione

Aby cała sprawa zachowała dokładne brzmienie:

termin:
  rozpoznaj: [termin, rezerwacja]
  redakcja: doslowna
  odpowiedz: 'Termin wymaga osobnego potwierdzenia przez pracownika.'

Ceny wraz z warunkami są zawsze chronione, niezależnie od trybu sprawy. cennik.yaml nie przyjmuje redakcja ani brzmienie. Automatyczny blok godziny_pracy z kancelaria.yaml jest również dosłowny.

Ważne zastrzeżenie umieszczone wewnątrz bloku mieszanego podlega redakcji razem z nim. Prompt nakazuje zachować sens, ale walidacja nie jest dowodem jego zachowania. Jeśli brzmienie musi być niezmienne, oznacz całą sprawę jako doslowna. W tej wersji nie ma ochrony pojedynczego zdania wewnątrz mieszanego bloku ani osobnego trybu dla odpowiedzi i pytania tej samej sprawy.

Co robi aplikacja

flowchart TD
    Selection[Wybór aktualnych bloków] --> AI1[AI wybiera i porządkuje identyfikatory]
    AI1 --> Validate[Walidacja propozycji]
    Validate --> Split{Wybrano bloki mieszane?}
    Split -->|Nie| Compose[Składanie odpowiedzi przez aplikację]
    Split -->|Tak| AI2[AI redaguje tylko dopuszczone bloki]
    AI2 --> Checks[Kontrola identyfikatorów, tekstu i ponowna kontrola ważności]
    Checks -->|Poprawny wynik| Compose
    Checks -->|Błąd lub odmowa| Manual[Obsługa ręczna i flaga źródła]
    Protected[Ceny, warunki i bloki dosłowne] --> Compose
    Compose --> MIME[Powitanie, zakończenie, podpis i MIME]
    MIME --> Mode{Tryb dostarczenia}
    Mode -->|Zwykły| Draft[Szkic do przeglądu pracownika]
    Mode -->|Jawny alias i włączony SMTP| Send[Automatyczna wysyłka]
    Mode -->|Dry-run| Preview[Tylko podgląd]

AI zwraca dla każdego dopuszczonego bloku jego ID oraz tekst. Musi zwrócić dokładnie jeden niepusty tekst na blok; nie może dodawać nowych bloków, zmieniać kolejności wybranej w pierwszym etapie ani zastępować ceny. Może upraszczać zdania, poprawiać przejścia, ograniczać powtórzenia i usuwać pojedyncze pytania już wyjaśnione przez klienta. Jeśli cały blok stał się zbędny lub nie może być bezpiecznie zredagowany, powinno wybrać obsługę ręczną. Nie ma samodzielnego generowania całego maila poza tym układem.

Drugi etap otrzymuje najnowszy wyodrębniony tekst maila, dopuszczone bloki i ustawienia stylu. Nie otrzymuje treści bloków chronionych, cen ani podpisu. Nie korzysta z załączników, narzędzi, wyszukiwania ani innych wiadomości. Treść maila jest przekazywana jako niezaufane dane, osobno od instrukcji aplikacji.

Kontrola i jej ograniczenia

Aplikacja odrzuca nieznane, powtórzone, brakujące lub chronione ID; puste teksty; niepoprawny wynik/refusal; typowe znaczniki HTML/kodu i znaki sterujące. Limit wynosi 6000 znaków na redagowany blok i 24000 łącznie. AI ma limit 6000 tokenów odpowiedzi w drugim etapie; przekroczenie limitu/refusal nie prowadzi do zapisania częściowego szkicu.

Dodatkowe kontrole odrzucają nowe wartości liczbowe, których nie było w źródłowym bloku, nowe adresy e-mail/typowe adresy WWW oraz typowe oznaczenia kwot, walut, procentów i bezpłatności. Liczby podane wyłącznie przez klienta nie są dozwolone w redakcji. Ogranicza to możliwość dopisywania kosztów lub danych kontaktowych, ale może też skierować poprawną językowo odpowiedź do ręcznej obsługi.

To nie jest pełna kontrola semantyczna. Nowa informacja może zostać wyrażona słowami, zastrzeżenie może zostać osłabione, a istniejąca liczba użyta w niewłaściwym kontekście. Identyfikator źródła i poprawny JSON nie dowodzą poprawności parafrazy. Pracownik musi przeczytać szkic; treści wymagające bezwzględnej precyzji powinny pozostać dosłowne.

Kontrakt wykorzystuje Structured Outputs oraz osobną obsługę odmowy i niepełnego wyniku zgodnie z dokumentacją OpenAI. Nie zastosowano dodatkowego modelu do oceny semantycznej.

Koszty, błędy i stan

Po wyborze bloków tryb mieszany dodaje kolejne wywołanie tego samego skonfigurowanego modelu tylko wtedy, gdy wybrano co najmniej jeden blok mieszany. Oznacza to dodatkowe zużycie API i czas oczekiwania. Dry-run także wykonuje redakcję, ale nie zapisuje stanu, szkiców ani flag i nie wysyła SMTP. Wywołania API są wyłączone w zwykłych testach automatycznych przez atrapy HTTP/AI.

Nieprawidłowy wynik redakcji zapisuje powód invalid_ai_rewrite; żądanie ręcznej obsługi przez model zapisuje ai_rewrite_requires_staff. Oba przypadki kończą wiadomość jako manualną i zwracają niezerowy kod komendy. Nie ma cichego powrotu do literalnego szkicu, który ukryłby błąd. Znany błąd transportu przed APPEND korzysta z dotychczasowego limitu trzech prób. Uzgadnianie przerwanego APPEND i ponawianie flag nie uruchamiają redakcji ponownie.

W rekordzie pozostają wybrane ID i hash całej konfiguracji, obejmujący ustawienia redakcji. Zwykły powód sukcesu dostaje końcówkę _mixed (np. missing_details_mixed); powód związany z załącznikiem zachowuje pierwszeństwo. Treści źródłowe i zredagowane nie są zapisywane w SQLite. Zmiana trybu nie regeneruje zakończonych szkiców.

Dopasowanie AI

W kancelaria.yaml można włączyć rozpoznawanie znaczenia wiadomości:

dopasowanie: ai

AI otrzymuje temat i najnowszy czytelny tekst wiadomości oraz katalog nazw, opisów i przykładowych słów spraw. Samo wybiera pasujące nazwy. Odmiany i synonimy nie muszą występować dosłownie w rozpoznaj.

Przykład redakcyjny konfiguracji sprawy, nie potwierdzenie wymagań prawnych:

dokumenty:
  opis: 'Pytania o dokumenty i informacje potrzebne przed spotkaniem.'
  zapytaj: 'Prosimy o wskazanie planowanej czynności, jeśli nie została jeszcze opisana.'

W trybie AI rozpoznaj jest opcjonalne, jeśli sprawa ma niepusty opis. Możesz zachować przykładowe słowa jako dodatkowe wskazówki. Każda sprawa musi mieć opis albo co najmniej jedno przykładowe słowo. Opis ma najwyżej 1000 znaków. Opis służy dopasowaniu, nie trafia automatycznie do odpowiedzi i nie zastępuje zatwierdzonych faktów ani cen.

Pytanie „Jakie papiery zabrać na spotkanie?” może zostać zakwalifikowane do sprawy dokumenty, mimo że nie zawiera słowa „dokumenty”. Dla niejednoznacznego „chcę przepisać mieszkanie” model nie powinien sam rozstrzygać, czy chodzi o darowiznę, testament lub inną czynność. Może wybrać odpowiednio opisaną ogólną sprawę zbierającą informacje; gdy katalog nie daje takiej możliwości, powinien wybrać obsługę ręczną.

Kiedy powstaje szkic

Aplikacja sprawdza wykluczenia i reguły ręcznej obsługi, zanim wywoła klasyfikację AI. Trafienie w regułę blokuje dalszą pracę modelu.
Model wybiera najwyżej 10 znanych spraw, obejmujących wszystkie istotne pytania. Cały katalog może zawierać najwyżej 100 spraw.
Wymagany jest wynik matched z oceną high i niepustą listą unikalnych, znanych nazw. Nieznane nazwy, duplikaty, dodatkowe pola lub sprzeczny wynik są odrzucane.
Wynik manual z oceną uncertain i pustą listą oznacza ręczną obsługę. Nie ma powrotu do słów kluczowych po niepewnym wyniku lub odmowie.
Dla wybranych spraw aplikacja nadal stosuje zastepuje, daty ważności, walidację bloków i cen. AI wybiera następnie bloki, a opcjonalny tryb mieszany redaguje dopuszczone teksty.

Ocena high jest deklaracją modelu, nie zmierzoną skutecznością ani gwarancją poprawności. Walidacja sprawdza kontrakt, nie prawidłowość interpretacji. Prompt nakazuje wybrać ręczną obsługę przy niejednoznaczności, brakującym kontekście, sprawach spoza katalogu oraz semantycznych odpowiednikach wykluczeń. Nie ma gwarancji wykrycia wszystkich takich przypadków. Pracownik nadal sprawdza każdy szkic.

Zgodność i koszt

Brak pola dopasowanie oznacza dotychczasowe slowa. Ten tryb wymaga niepustego rozpoznaj i nie odmienia wyrazów ani nie dodaje synonimów. Przełączając profil z AI na słowa, uzupełnij listy w sprawach, które miały tylko opis.

Klasyfikacja AI jest osobnym wywołaniem tego samego skonfigurowanego modelu. Pełny przebieg może mieć trzy wywołania: rozpoznanie spraw, wybór bloków, redakcję mieszaną. --dry-run również wywołuje klasyfikację, lecz nie zapisuje szkiców, flag ani rekordów. Lokalne testy używają atrap — nie są pomiarem trafności rzeczywistego modelu na języku polskim.

Temat i treść maila są niezaufanymi danymi w wiadomości użytkownika, osobno od instrukcji i katalogu. Klasyfikator nie dostaje cen, treści odpowiedzi, podpisu, załączników ani historii korespondencji. Nie ma dostępu do narzędzi ani wyszukiwania. Sama znajomość nazwy sprawy nie uprawnia do dopisywania faktów.

Błędy i ponawianie

Niepewność: terminalny powód topic_match_uncertain, flaga źródła, bez szkicu i bez kolejnych etapów AI. Jest to zwykła decyzja o ręcznej obsłudze; sama nie powoduje niezerowego kodu komendy.
Nieprawidłowy wynik, odmowa lub przerwany wynik: invalid_ai_topic_match, obsługa ręczna i niezerowy kod.
Błąd transportu przed APPEND: dotychczasowe ponawianie, najwyżej trzy próby. Nie stosuje dopasowania słownego jako zastępstwa.
Zakończone rekordy oraz uzgadnianie przerwanego APPEND nie uruchamiają klasyfikacji ponownie.

Po kolejnych wywołaniach AI aplikacja ponownie filtruje ważność treści, używając tej samej zwalidowanej listy spraw. Nie ponawia klasyfikacji tylko dlatego, że minęła północ. Hash konfiguracji obejmuje tryb i opisy; SQLite nie przechowuje tekstu wiadomości ani odpowiedzi klasyfikatora. Wybrane bloki są nadal zapisywane jako identyfikatory.