# Cascade Knowledge Base *Read this in: [English](README.md) | **Polski*** **Repozytorium źródłowe (zawsze najbardziej aktualna wersja):** [git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb) Warstwowa, zarządzana przez agenta wiki, w której lokalna zawartość nadpisuje tylko-do-odczytu źródła nadrzędne (upstream). Zbudowana na wzorcu LLM Wiki Karpathy'ego, rozszerzonym o skalowanie, zarządzanie cyklem życia i wsparcie dla wielu agentów. Ten dokument to techniczny przegląd funkcji. Zorientowany na zadania przewodnik — jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek, synchronizować się z innymi i przykłady dla każdego przypadku użycia — znajdziesz w [MANUAL.pl.md](MANUAL.pl.md) ([English](MANUAL.md)). Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł `software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz [OPENSPEC.pl.md](OPENSPEC.pl.md) ([English](OPENSPEC.md)). Pełny schemat strony oraz historię obu numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)). ### Kanały wydawnicze Repozytorium szablonu utrzymuje trzy gałęzie. Nie są wymienne: | Gałąź | Czym jest | Kto powinien ją śledzić | |---|---|---| | `main` | **Stabilna** — wydany szablon | Wszyscy, domyślnie | | `test` | **Kandydat do wydania** — walidowany przed scaleniem do `main` | Każdy, kto pomaga walidować wydanie albo potrzebuje poprawki, która weszła, ale jeszcze nie została wydana | | `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon | Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć innego kanału, po prostu powiedz którego: *„zainicjuj z gałęzi test"*, *„sprawdź experimental pod kątem aktualizacji"*, *„przełącz tę KB z powrotem na kanał stabilny"*. Śledzona gałąź jest zapisana w `ckb.yaml`: ```yaml template: repo: https://git.wierzbowa.cloud/michal/ckb.git branch: main ``` KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca `main` — czyli dokładnie to, co i tak robiła każda KB sprzed tej konwencji. --- ## Struktura katalogów ``` ├── libs/ # Zewnętrzne źródła tylko do odczytu — kopie git (w .gitignore) LUB │ # konfiguracje konektora (source.yaml) z własnym generowanym indeksem ├── linked/ # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne ├── outputs/ # Wygenerowane artefakty, eksporty, skompilowane pliki ├── raw/ # Materiał źródłowy dostarczony przez użytkownika │ └── inbox/ # Strefa zrzutu: nieprzetworzony materiał ├── tmp/ # Pliki tymczasowe, cache (w .gitignore) ├── wiki/ # Lokalna, ustrukturyzowana wiki w markdown (zarządzana przez agenta) │ ├── index.md # Tabela routingu z wyzwalaczami „Use when" + kb_schema_version │ ├── overview.md # Mapa wysokiego poziomu │ ├── log.md # Główny dziennik zmian (rollup) │ ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia │ ├── decisions/ # Numerowane, tylko-dopisywane zapisy decyzji + własny index.md i log.md │ ├── entities/ # Typowane strony encji (osoby, projekty, koncepcje) + własny index.md │ └── graph/ # Listy krawędzi i dane relacji + własny index.md └── workload/ # Podsumowania sesji i decyzje └── YYYY-MM-DD_summary.md ``` --- ## Priorytet kaskady Podczas wyszukiwania warstwy są sprawdzane w kolejności — pierwsze trafienie wygrywa: ``` wiki/ (najwyższy) ← agent zapisuje tutaj, zawsze wygrywa linked/A/ (średni) ← zamontowane przez symlink wiki nadrzędne linked/B/ (niski) ← zamontowane przez symlink wiki nadrzędne libs/A/ (najniższy) ← kopie zewnętrznych baz wiedzy zarządzane przez git, albo własny generowany indeks konektora ``` Agent nigdy nie zapisuje do `linked/` ani do `libs//` będącego kopią git. Aby poprawić treść nadrzędną, zapisz właściwą wersję w `wiki/` — automatycznie zyskuje pierwszeństwo. Jedynym wyjątkiem jest `libs//` oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie” poniżej) — agent zarządza jego generowanym indeksem tak samo, jak `wiki/`. --- ## Funkcje ### Przepływ oparty na skrzynce odbiorczej (Inbox) Wrzuć dowolny surowy materiał (notatki, artykuły, linki) do `raw/inbox/` bez porządkowania. Po komendzie „Ingest" (lub „Sync the wiki" / „Update the wiki"), agent przetwarza skrzynkę odbiorczą — wydobywa wiedzę, zapisuje ją w `wiki/` i archiwizuje przetworzone elementy do `raw/` — a następnie przypomina o przejrzeniu wyniku i uruchomieniu „sync changes", aby wypchnąć zmiany do `origin`, gdy będziesz z nich zadowolony. Zaimplementowane jako Claude Code Skill — zobacz `.agents/skills/ckb-ingest/SKILL.md` — zamiast być zaszytym w `CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna procedura ładuje się do kontekstu tylko wtedy, gdy jest faktycznie wywoływana. Odrębne od skilla `ckb-sync-changes`, który jest czysto operacją na poziomie gita, bez syntezy wiki. Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną niezróżnicowaną bryłę: wyszukiwalne pytanie, krótkie podsumowanie, rozwiązanie lub decyzja, odniesienia do systemów/kodu, zaangażowane osoby oraz fragmenty o wysokiej wartości, które zasługują na to, by pozostać znajdowalne samodzielnie. „Wysoka wartość" to jawny test, a nie ocena uznaniowa — inaczej każdy fragment wygląda na wart zachowania, a strona staje się drugą kopią transkryptu. Fragment zasługuje na własną wyszukiwalną sekcję tylko wtedy, gdy zawiera termin rzadki w całej wiki (sprawdzane przez `rg -c` — wyróżniający uchwyt wyszukiwania, a nie słowo już obecne na dwudziestu stronach), ma około 200 znaków lub więcej i jest potwierdzony przez coś dalej w materiale, co się z nim zgadza, działa na jego podstawie lub go koryguje. Niespełnienie choćby jednego warunku oznacza, że treść nadal trafia na stronę, tylko wewnątrz podsumowania, a nie jako osobna jednostka. Awansowane fragmenty zabierają ze sobą nagłówek nadrzędny lub pytanie wątku, żeby dały się jednoznacznie czytać samodzielnie. ### Leniwie ładowany indeks z wyzwalaczami „Use When" `wiki/index.md` to tabela routingu. Każdy wpis ma kolumnę **Use when** z listą słów kluczowych wyzwalających. Agent najpierw czyta indeks (pozostaje w kontekście), dopasowuje słowa kluczowe do zadania i ładuje tylko pasujące strony. Zmniejsza to narzut kontekstu z ~12K do ~3.2K tokenów na zadanie. ### Warstwa zapytań oparta na TLDR Każda strona zawiera jednozdaniowe podsumowanie `tldr` we frontmatterze. Podczas zapytania agent najpierw czyta TLDR-y. Jeśli TLDR już odpowiada na pytanie, pełna treść nigdy nie jest ładowana. Łańcuch odwoławczy: TLDR → treść → surowe źródło. ### Lokalne zakresy projektów Dla powracających zespołów, klientów, systemów lub inicjatyw wiki może trzymać zwykłe strony zakresów w formacie Markdown pod `wiki/projects/`. Strona zakresu wymienia strony wiki, encje, źródła z `raw/archive/`, konektorowe `libs/`, wyjścia i obszary grafu, które należy przeszukać najpierw dla danego projektu. Daje to tę samą praktyczną korzyść co przestrzeń robocza projektu w większym systemie wyszukiwania, pozostając lokalnym, przejrzystym i edytowalnym w dowolnym edytorze tekstu. Zakresy zawężają tylko pierwsze przejście. Jeśli wyszukiwanie w zakresie nie odpowiada na pytanie, agent wraca do pełnej kaskady. ### Lokalne wyszukiwanie hybrydowe Gdy routing po indeksie/TLDR nie wystarcza, agent może połączyć kilka lokalnych sygnałów przed odpowiedzią: - dokładne wyszukiwanie tekstu przez `rg` dla komunikatów błędów, komend, flag, nazw plików, nazw hostów, identyfikatorów zgłoszeń i innych literalnych tokenów — również w `raw/inbox/`, więc materiał wrzucony godzinę temu i jeszcze nie zingestowany nadal może odpowiedzieć na pytanie (i sygnalizuje, że ingest jest zaległy) - dopasowania semantyczne/encyjne z tytułów stron, TLDR-ów, zakresów projektów i relacji w grafie - metadane świeżości i pewności, dzięki którym nieaktualne lub słabe strony są traktowane ostrożnie - rozszerzenie kontekstu wokół dopasowanej sekcji, aby odpowiedzi były osadzone w sąsiadujących nagłówkach i akapitach, a nie w samotnym urywku Każdy sygnał tworzy własną listę rankingową, a listy są następnie łączone, zamiast rozstrzygania przez wybór ulubionego sygnału: każdy kandydat zbiera `weight / (k + rank)` zsumowane po listach, na których występuje, więc strona na trzecim miejscu w trzech listach wygrywa ze stroną pierwszą w jednej. `k` wynosi 10, celowo mniej niż zwykle cytowane 60 — 60 jest dostrojone do wyszukiwarek zwracających setki kandydatów i spłaszcza wszystkie wyniki do niemal identycznych wartości przy kilkunastu, które daje lokalna wiki. Zapytania o literalne tokeny podnoszą wagę listy dokładnych dopasowań, ponieważ żadne podobieństwo tytułu nie powinno wyprzedzić trafienia w dokładny ciąg, który ktoś wklejił. Połączeni kandydaci są następnie deduplikowani według twierdzenia — strona wiki, plik z `raw/archive/`, który cytuje, i strona konektora wskazująca na nią to trzy trafienia dla jednego faktu, nie trzy źródła — i przerankowani w skali 0–10 według tego, jak dobrze odpowiadają na dosłownie zadane pytanie, a nie jak dobrze pasują do jego sformułowania. Ten sam agent, świadome drugie przejście, bez osobnego modelu. Wynik jest wewnętrznie normalizowany jako pakiet dowodowy: ścieżka źródła, dopasowane twierdzenie, data/świeżość, pewność/jakość, wskazówki o relacjach lub zakresie oraz informacja, z których sygnałów każdy kandydat został połączony. Nie jest wymagany żaden serwer, baza wektorowa ani dedykowany klient. ### Zastrzeżenia w odpowiedziach Metadane, które wiki już śledzi, są podawane w samej odpowiedzi, a nie tylko sprawdzane przy jej budowaniu. Gdy strona stanowiąca podstawę odpowiedzi przekroczyła `freshness_window_days`, ma niską `confidence`/`quality`, opiera się na niezingestowanym materiale z `raw/inbox/` lub została sprawdzona względem zapisanego w pamięci indeksu konektora, a nie żywego źródła — odpowiedź mówi o tym obok twierdzenia, którego to dotyczy. Konflikty między dwiema aktywnymi stronami są ujawniane tak samo, nawet jeśli żadna nie ma jeszcze `superseded_by`. Zamyka to tryb awarii polegający na pewnej odpowiedzi *z* nieaktualnej strony bez przekazania tej informacji dalej. ### Wyszukiwanie ekspertów i właścicieli „Kto wie o X" i „kto jest właścicielem X" to bezpośrednie zapytania do grafu, a nie zgadywanie po pełnym tekście. Ingest zapisuje krawędzie `has_expertise_in`, gdy ktoś wykazuje się odpowiadaniem na pytania lub wyjaśnianiem decyzji w danym temacie, oraz krawędzie `owns` dla zadeklarowanej odpowiedzialności za system, obszar lub decyzję — oba wyłącznie na podstawie wykazanych dowodów, nigdy wnioskowane z obecności na spotkaniu czy ze stanowiska. Gdy krawędzi jeszcze nie ma, wyszukiwanie wraca do dowodów autorstwa i mówi, które z dwóch stanowiło podstawę odpowiedzi, bo domniemany ekspert to słabsze twierdzenie niż zapisany. ### Zapisy decyzji `wiki/decisions/` zawiera jedną numerowaną stronę na decyzję (`NNNN-slug.md`): co zostało zdecydowane, przez kogo (`decided_by`), kiedy (`decided_on`), dlaczego, jakie alternatywy odpadły i czego decyzja dotyczy (`affects`). Pole `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) mówi, czy decyzja faktycznie obowiązuje, a opcjonalna data `review_on` oznacza ją do przeglądu. Strony decyzji są **tylko do dopisywania**. Gdy wybór się zmienia, *nowa* decyzja zastępuje starą — `supersedes`/`superseded_by` ustawiane są po obu stronach, status starej zmienia się na `superseded` lub `reversed`, a jej pierwotny kontekst i uzasadnienie pozostają nietknięte. To właśnie sprawia, że „dlaczego jest tak, jak jest?" da się odpowiedzieć po latach, i zamienia „używamy Postgresa" w „używamy Postgresa, a wcześniej MySQL-a, zmienione we wrześniu z powodu raportowania". `decided_by` i `affects` stają się też krawędziami grafu, więc „kto zdecydował o X" i „jakie decyzje dotyczą Y" to bezpośrednie wyszukania. Skill `ckb-decide` zapisuje decyzje i odpowiada na pytania o nie; `ckb-lint` sprawdza ich strukturę (słownik statusów, wymagane daty, dwustronne zastępowanie, unikalne numery, zaległe przeglądy). ### Luki w zapytaniach Jeśli kaskada nie potrafi odpowiedzieć na pytanie, agent zapisuje lub proponuje krótki wpis w `wiki/query-gaps.md`: o co pytano, gdzie szukał i jakie najmniejsze źródło lub strona zamknęłaby lukę. Dzięki temu nieudane wyszukiwania stają się użytecznym sygnałem zapotrzebowania dla następnego ingestu, zamiast przepadać w historii czatu. ### Schemat frontmatteru strony Każda strona wiki używa frontmatteru YAML. Pole `type` jest wymagane; reszta jest opcjonalna: ```yaml --- type: concept # WYMAGANE. Otwarty ciąg znaków: person, project, concept, library, decision, playbook, ... resource: https://... # Kanoniczny URI do autorytatywnego zewnętrznego źródła, które opisuje ta strona tldr: Jednozdaniowe podsumowanie zoptymalizowane pod odczyt przez LLM confidence: 0.0–1.0 # Wynik potwierdzenia przez źródła quality: 0.0–1.0 # Samoocena (poniżej 0.7 → oflagowane) supersedes: path/to/old.md superseded_by: path/to/new.md last_updated: YYYY-MM-DD freshness_window_days: 90 # Liczba dni, po których treść uznaje się za nieaktualną retention: high|medium|low source_fingerprint: sha256:3f9a2c1e # skrót źródła, z którego zbudowano tę stronę source_checked: YYYY-MM-DD # kiedy ten skrót był ostatnio zweryfikowany --- ``` - **type** — wymagane; niezarejestrowany ciąg znaków, nowe wartości są zawsze poprawne, czytelnicy tolerują nierozpoznane - **resource** — opcjonalny wskaźnik do żywego/autorytatywnego źródła, oddzielony od własnego komentarza wiki - **confidence** — ustawiane przy zapisie, zanika z czasem, wzmacniane przez nowe źródła - **quality** — samoocena przy zapisie, strony poniżej 0.7 oflagowane do przeglądu - **supersedes / superseded_by** — gdy nowa informacja zastępuje starą, połącz je - **freshness_window_days** — strony starsze niż to okno są oflagowane podczas lintowania - **retention** — strony o niskim priorytecie są archiwizowane po 2× oknie świeżości - **source_fingerprint / source_checked** — skrót materiału, z którego zsyntetyzowano stronę, oraz data ostatniego potwierdzenia. Okno świeżości to przypuszczenie, że źródło *mogło* się zmienić; skrót to fakt, czy *się zmieniło* — i lint sprawdza go mechanicznie. #### Zastrzeżone sekcje treści Cztery nagłówki `##` mają w całej KB ściśle określone znaczenie: | Sekcja | Co zawiera | |---|---| | `## Sources` | po jednym punkcie na źródło, każdy ze skrótem | | `## Crux` | dosłowne cytaty z tych źródeł — dowód, nigdy parafraza | | `## Notes` | pisane przez człowieka i **chronione**: żaden skill ich nie nadpisuje | `## Crux` pozwala odpowiedzieć na pytanie ze strony zamiast z archiwum: streszczenie może po cichu odpłynąć od źródła, cytat albo wciąż się z nim zgadza, albo nie. `## Notes` daje odwrotną gwarancję — na stronach regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce, w którym adnotacja przetrwa kolejną przebudowę. Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.5"`), deklarujący, według której wersji tego schematu wiki została napisana — zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla zmian łamiących kompatybilność. ### Ekstrakcja encji i graf wiedzy Podczas ingestu agent wydobywa typowane encje (osoby, projekty, biblioteki, koncepcje, systemy) i zapisuje je jako strony w `wiki/entities/`. Typowane relacje są zapisywane w `wiki/graph/edges.json` przy użyciu zamkniętego słownika, w którym każdy czasownik jest zdefiniowany przez pytanie, na jakie odpowiada (patrz `wiki/graph/index.md`) — strukturalne (`part_of`, `uses`, `depends_on`, `produces`, `configures`, `validates`, `implements`, `caused`, `contradicts`, `supersedes`) oraz łączące osoby z tematami (`has_expertise_in`, `owns`). Zapytania mogą przechodzić po grafie, aby odkrywać powiązane strony (np. „co zależy od Redis?") albo bezpośrednio odpowiadać na „kto wie o X". ### Rekurencyjna konwencja indeksu i dziennika Każdy podkatalog `wiki/`, który grupuje wiele stron (`entities/`, `graph/`, przyszłe foldery tematyczne), utrzymuje własny `index.md` — zwykłą listę linków, bez frontmatteru — dzięki czemu nawigacja po podkatalogach pozostaje leniwa, zamiast wymagać pełnego skanowania. Podkatalog może też utrzymywać własny `log.md`, gdy ma już wystarczająco dużo niezależnej historii; `wiki/log.md` pozostaje rollupem na poziomie głównym i nigdy nie powtarza zmiany już zapisanej w dzienniku podkatalogu. ### Konektory zewnętrznych źródeł i indeksowanie (na żądanie) Folder `libs//` obsługuje drugi sposób zasilania, obok istniejącej kopii git: mały, autorski plik `libs//source.yaml`, który deklaruje *żywe* zewnętrzne źródło — folder SharePoint, folder Google Drive, zwykły URL albo inny konektor — którego nie chcesz w pełni kopiować lokalnie: ```yaml connector: sharepoint location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports" description: "Wspólny folder raportów zespołu finansowego" refresh_interval_days: 7 # opcjonalne, domyślnie 30 ``` `refresh_interval_days` dostraja częstotliwość per źródło — folder zmieniający się codziennie zasługuje na krótsze okno niż kwartalne archiwum, które prawie nie drgnie — i ustawia `freshness_window_days` nadawane generowanym stronom tego źródła. Zarówno „index external sources", jak i „Lint" raportują źródło zaległe względem tej wartości i mówią o ile, żeby użytkownik z dostępem tylko do odczytu wiedział, kogo zapytać, zamiast po cichu polegać na kopii sprzed trzech tygodni. Powiedz „index external sources", a agent go przeskanuje, dopasowując `connector` do dowolnego żywego narzędzia dostępnego w danej sesji (połączonego narzędzia MCP do Microsoft 365/Google Drive, albo `WebFetch` dla zwykłego adresu URL), i zbuduje samodzielny, generowany indeks wewnątrz tego samego `libs//` — `index.md`/`entities/`/`graph/`/`log.md`, odzwierciedlający strukturę `wiki/` opisaną w Rekurencyjnej konwencji indeksu i dziennika powyżej, ale ograniczony wyłącznie do tego jednego konektora. To celowa decyzja projektowa: ten indeks **nie** jest wmieszany w główne `wiki/entities/`/`wiki/graph/edges.json` — pozostaje oddzielony na warstwie kaskady `libs/`, tak samo jak pliki sklonowanej przez git KB. Sam `source.yaml` pozostaje wyłącznie twój, agent nigdy go nie zapisuje. Dwa rozszerzenia na tym fundamencie: - **Współdzielone, wcześniej zbudowane indeksy.** `source.yaml` może dodać opcjonalny blok `index:`, który deklaruje, *gdzie już zbudowany indeks się znajduje* — repozytorium git albo zasób współdzielony, np. ścieżka sieciowa lub inna lokalizacja dostępna przez konektor: ```yaml index: store: git # git | shared location: "https://github.com/org/finance-index-cache.git" ref: main # opcjonalnie — branch, tag albo podpowiedź co do podścieżki w tym miejscu ``` Każde uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już tam jest, zostaje pobrany — większość osób po prostu czyta to, co już jest, zamiast budować to samodzielnie. Jeśli go tam jeszcze nie ma, to normalny stan przy pierwszym uruchomieniu, a nie błąd: kolejne uruchomienie użytkownika z dostępem do zapisu jest tym, które go tam tworzy i publikuje — bez osobnego kroku „inicjalizacji". - **Odczyt vs. zapis, per użytkownik, per źródło.** Czy *ten* użytkownik może faktycznie przebudować indeks (a nie tylko czytać pobraną/ opublikowaną wersję) to odrębne, lokalne, ignorowane przez git `libs//source.local.yaml` — domyślnie tylko do odczytu. Ustawienie `access: write` w tym pliku włącza dany komputer/użytkownika jako administratora tego źródła, dzięki czemu zespół może wyznaczyć jedną lub dwie osoby do utrzymywania źródła, podczas gdy reszta czyta tylko wynik — bez zbędnego, wielokrotnego przebudowywania i bez potrzeby, żeby każdy użytkownik miał własną autoryzację konektora. Zaimplementowane jako Claude Code Skill — zobacz `.agents/skills/ckb-index-external/SKILL.md`. ### Podwójne linkowanie (Wikilinks + Markdown) Każde odwołanie krzyżowe używa zarówno `[[Wikilinks]]` (kompatybilnych z Obsidian), jak i standardowych linków `[markdown](path.md)`. Działa w widoku grafu Obsidian, renderowaniu GitHub i narzędziach CLI. Odwołania do treści nadrzędnych używają pełnych ścieżek względnych: `linked//...` lub `libs//...`. Odwołania wewnątrz wiki preferują ścieżki bezwzględne względem katalogu głównego projektu (`/wiki/entities/foo.md`) zamiast względnych, dzięki czemu linki przetrwają późniejsze przenoszenie plików. ### Samonaprawiający się lint Okresowo (lub na żądanie) agent sprawdza kondycję wiki: - **Zgodność (conformance)** — oflagowuje każdą stronę bez poprawnego frontmatteru lub pola `type` - **Świeżość** — oflagowuje strony starsze niż ich `freshness_window_days` - **Zanik pewności (confidence decay)** — zmniejsza `confidence` dla stron niewzmacnianych nowymi źródłami - **Przegląd retencji** — archiwizuje strony `retention: low` starsze niż 2× okno świeżości - **Wykrywanie supersesji** — znajduje sprzeczności, łączy stare→nowe - **Wykrywanie sierot** — znajduje strony bez linków przychodzących - **Spójność grafu** — weryfikuje, czy wszystkie krawędzie wskazują na istniejące encje - **Spójność indeksu/dziennika** — weryfikuje, czy każdy podkatalog ma index.md i czy żadna zmiana nie jest podwójnie logowana - **Skróty źródeł** — przelicza skrót każdego cytowanego źródła i oznacza strony, których dowód faktycznie się zmienił, a nie tylko się zestarzał - **Dosłowność sekcji Crux** — oznacza cytat, którego nie ma już w źródle, na które się powołuje - **Częstotliwość konektorów** — oznacza konektorowe źródło, którego generowany indeks jest zaległy względem `refresh_interval_days`, wraz z informacją o ile - **Księga błędów (Error Book)** — zapisuje systemowe problemy wraz z przyczyną i naprawą Automatycznie naprawia to, co może (uszkodzone linki, brakujące odnośniki zwrotne, nieaktualne flagi), i przypomina o przejrzeniu wyniku oraz uruchomieniu „sync changes", aby wypchnąć zmiany do `origin`, gdy będziesz z nich zadowolony. Zaimplementowane jako Claude Code Skill — zobacz `.agents/skills/ckb-lint/SKILL.md` — zamiast być zaszytym w `CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna lista kontrolna ładuje się do kontekstu tylko wtedy, gdy jest faktycznie wywoływana. ### Rozwiązywanie konfliktów (Supersesja) Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki `supersedes` / `superseded_by`. Stara strona jest zachowywana, ale oznaczana jako nieaktualna. Kontrola wersji dla wiedzy, nie tylko dla plików. ### Ocena jakości Każda strona przy zapisie otrzymuje wynik jakości (0.0–1.0), oparty na strukturze, cytowaniu źródeł i spójności z resztą wiki. Strony poniżej 0.7 są oflagowane do przeglądu lub przepisywane podczas kolejnego lintowania. ### Księga błędów (Error Book) Systematyczne błędy (uszkodzone linki, problemy z formatowaniem, sprzeczności między stronami) są zapisywane w `wiki/error-book.md` wraz z przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku zapobiegającym powtórce. Naprawa dwuwarstwowa: - **Warstwa 1** — deterministyczna automatyczna naprawa problemów strukturalnych - **Warstwa 2** — przebieg rozumowania agenta dla problemów semantycznych/między stronami ### Haki automatyzacji (Automation Hooks) - **Nowe źródło** → automatyczny ingest przy kolejnej komendzie „Ingest" - **Start sesji** → ładowanie indeksu + ostatniego podsumowania workload; sprawdzenie niezsynchronizowanych zmian (niezacommitowana praca lub przewaga/zaległość względem `origin`) i zasugerowanie `ckb-sync-changes`, jeśli takie zostaną znalezione - **Koniec sesji** → skompresowanie obserwacji do workload/; ponowne sprawdzenie niezsynchronizowanych zmian (w tym tych, które powstały właśnie w tej sesji) i zasugerowanie `ckb-sync-changes`, jeśli to potrzebne - **Zapytanie** → zapisanie z powrotem wartościowych odpowiedzi jako strony wiki - **Zapis do pamięci** → sprawdzenie sprzeczności, wywołanie supersesji - **Harmonogram** → okresowy lint, konsolidacja, zanik retencji ### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC) Wiki rośnie na podstawie rzeczywistych niepowodzeń agenta, a nie z góry narzuconej kuracji: 1. Agent nie potrafi odpowiedzieć → identyfikuje brakującą wiedzę 2. Proponuje minimalną encję/stronę wypełniającą lukę 3. Użytkownik zatwierdza lub dostarcza materiał źródłowy 4. Kolejny ingest wprowadza ją Zbiega do stabilnej bazy wiedzy po ~20–30 cyklach. ### Podsumowania sesji Po każdej akcji konwersacyjnej agent dopisuje do `workload/YYYY-MM-DD_summary.md`. Zapewnia to ciągłość między sesjami i przeglądalną historię ewolucji bazy wiedzy. Agent czyta ostatnie podsumowanie na starcie sesji, aby kontynuować od miejsca, w którym skończył. ### Dziennik zmian Każda modyfikacja wiki jest natychmiast logowana w `wiki/log.md` w kolejności odwrotnie chronologicznej (najnowsze na górze), z zapisem co się zmieniło, dlaczego i jakie było źródło. ### Eksport OKF (na żądanie) Wiki może zostać wyeksportowana jako zgodny z [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) v0.1 pakiet w `outputs/okf/`, możliwy do skonsumowania przez dowolne ogólne narzędzie OKF (np. referencyjny wizualizator grafu Google) bez naruszania bogatszego wewnętrznego schematu (`confidence`/`quality`/`retention`/`supersedes`/podwójne linkowanie), którego OKF natywnie nie rozumie. Zaimplementowane jako Claude Code Skill — zobacz `.agents/skills/ckb-export-okf/SKILL.md` — zamiast być zaszytym w `CLAUDE.md`/`AGENTS.md`, dzięki czemu zestaw reguł mapowania ładuje się do kontekstu tylko wtedy, gdy jest faktycznie wywoływany. Cały transform — przemapowanie frontmatteru, przepisanie linków, regeneracja indeksów i dzienników oraz sprawdzenie zgodności z OKF na własnym wyjściu — wykonuje deterministyczny skrypt Python (`scripts/export_okf.py`), więc eksport jest odtwarzalny zamiast wyprowadzany na nowo strona po stronie; agent uruchamia skrypt i przekazuje raport. `outputs/okf/` jest w `.gitignore` — to w pełni regenerowalny artefakt budowania, więc każda maszyna/narzędzie regeneruje go na żądanie zamiast przenosić go w historii gita. ### Eksport Starlight (na żądanie) Wiki może też zostać wyeksportowana do formy skonsumowalnej przez Astro + Starlight w `outputs/starlight/`, tworząc czytelną dla człowieka stronę dokumentacji — w odróżnieniu od eksportu OKF, który celuje w konsumpcję maszynową/narzędziową. Deterministyczny skrypt Python (`scripts/export_starlight.py`) obsługuje przemapowanie frontmatteru, zwijanie podwójnych linków, rozwiązywanie wikilinków, kopiowanie zasobów i generowanie paska bocznego; zadaniem agenta jest jedynie zadanie dwóch pytań konfiguracyjnych (zakres eksportu: pełny uruchamialny szkielet vs. tylko treść; czy dołączyć strony meta dziennika/księgi błędów) i przekazanie raportu skryptu. Również na żądanie i tylko jako skill — zobacz `.agents/skills/ckb-export-starlight/SKILL.md`. Podobnie jak `outputs/okf/`, `outputs/starlight/` jest w `.gitignore` jako regenerowalny artefakt budowania. ### Dziennik decyzji (na żądanie) Powiedz „zapisz decyzję: ..." (albo po prostu „zdecydowaliśmy ..."), żeby utworzyć numerowany rekord decyzji; zapytaj „co zdecydowaliśmy w sprawie X", „kto to zdecydował", „które decyzje są wciąż propozycjami" albo „co zastąpiło decyzję 3", żeby dostać ją z powrotem wraz z autorem, datą i statusem. Zapisywanie zbiera brakujące pola w jednej turze zamiast wywiadu, ustawia powiązania zastępowania w obu kierunkach, dodaje krawędzie grafu `decided_by`/`affects` i zapisuje do `wiki/decisions/log.md`. Zobacz `.agents/skills/ckb-decide/SKILL.md`. ### Prowadzone wycieczki wprowadzające (na żądanie) Poproś „oprowadź mnie po X" (lub „od czego zacząć z X", „krótka wycieczka po X") aby otrzymać krótką, tylko-do-odczytu prowadzoną kolejność czytania: akapit wprowadzający plus uporządkowaną listę stron wiki do przeczytania, zbudowaną przez przejście po grafie wiedzy na zewnątrz od najlepiej pasującej strony (najpierw podstawy, potem sam temat, potem to, co się na nim opiera). Nigdy nie zapisuje do `wiki/`. Zobacz `.agents/skills/ckb-onboard-me/SKILL.md`. ### Podsumowanie projektu (na żądanie) Poproś o „podsumowanie projektu" (lub „jak stoją sprawy", „nadrób zaległości w projekcie"), aby zregenerować `PROJECT-OVERVIEW.md` w katalogu głównym repozytorium — jedno- lub dwustronicowy skrót (przegląd, stan projektu, działania i ich status, ryzyka, założenia) zsyntetyzowany w całości z bieżącej zawartości `wiki/` i jej grafu wiedzy. Zawsze nadpisywany w całości przy ponownym uruchomieniu, nigdy nie dopisywany ręcznie. Zobacz `.agents/skills/ckb-project-summary/SKILL.md`. ### Synchronizacja gita (na żądanie) Historia gita tego repozytorium może zostać uzgodniona z jego zdalnym repozytorium `origin` na żądanie: lokalne zmiany są commitowane, zdalne zmiany są pobierane i scalane, wszelkie konflikty są prezentowane użytkownikowi plik po pliku do rozwiązania, a następnie wynik jest automatycznie wypychany (push). Powiedz „sync changes", aby to uruchomić. Również zaimplementowane jako Claude Code Skill — zobacz `.claude/skills/ckb-sync-changes/SKILL.md` — i celowo odrębne od przepływu na poziomie treści „Sync the wiki" / „Ingest", który przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` i nie ma nic wspólnego z gitem. ### Tryb quizu (na żądanie) Poproś o odpytanie z wiki („quiz me on X", „sprawdź moją wiedzę"), aby uzyskać jednorazowy, punktowany sprawdzian wiedzy: agent czyta odpowiednie strony, generuje pytania otwarte lub jednokrotnego wyboru oparte na konkretnych faktach z wiki, przeprowadza je jedno po drugim z natychmiastową informacją zwrotną i bieżącym wynikiem, a na koniec podaje werdykt. Bezstanowy — nic nie jest zapisywane między uruchomieniami. Zobacz `.agents/skills/ckb-quiz/SKILL.md`. ### Prowadzony program nauczania (na żądanie) Poproś o naukę z wiki („teach me the wiki", „naucz mnie o X", „przeprowadź sesję nauki"), aby otrzymać stanowy kurs zamiast jednorazowego quizu. Pierwsze wywołanie go planuje: określa zakres materiału (opcjonalnie uzupełniając cienkie miejsca z internetu, wyraźnie oznaczone jako nieautorytatywne), pyta, czy ma to być jedna sesja, czy rozłożona w czasie seria (czas trwania, częstotliwość, opcjonalne przypomnienia kalendarzowe `.ics`), dzieli treść na porcje wielkości sesji — wolą dodatkową sesję niż upychanie materiału — i zapisuje zaakceptowany plan oraz tracker postępu w `outputs/teaching//`. Kolejne wywołania porównują plan z postępem, uczą kolejnej porcji materiału inną techniką za każdym razem (pytania sokratejskie, analogie, przykłady rozwiązane krok po kroku, „naucz mnie z powrotem", mnemotechniki, ...), sprawdzają utrwalenie wiedzy i powtarzają słabe punkty przed przejściem dalej. Nigdy nie zapisuje do `wiki/`. Zobacz `.agents/skills/ckb-teach-me/SKILL.md`. --- ## Szybki start 1. **Zamontuj nadrzędne bazy wiedzy:** ```bash ln -s /path/to/other-kb ./linked/my-upstream git clone https://github.com/org/external-kb ./libs/external-kb ``` Albo, dla żywego źródła, którego nie chcesz w pełni kopiować lokalnie, umieść zamiast tego `libs//source.yaml` (zobacz „Konektory zewnętrznych źródeł i indeksowanie" powyżej) i powiedz „index external sources". 2. **Wrzuć surowy materiał** do `raw/inbox/` (notatki, linki, artykuły). 3. **Poleć agentowi „Ingest"** — przetworzy skrzynkę odbiorczą, skonsultuje kaskadę, wydobędzie encje i zapisze ustrukturyzowany markdown w `wiki/`. 4. **Zadawaj pytania** — agent używa indeksu do routingu, TLDR-ów do szybkich odpowiedzi i grafu do odkrywania relacji. 5. **Okresowo proś o „Lint"** — agent sprawdzi kondycję wszystkiego, naprawi co może i zgłosi problemy. --- ## Pliki instrukcji dla agenta | Plik | Cel | |------|-----| | `AGENTS.md` | Pełna instrukcja dla dowolnego agenta kodującego AI | | `CLAUDE.md` | Dowiązanie symboliczne do `AGENTS.md`, automatycznie wykrywane przez Claude Code | Skille znajdują się w jednej wspólnej lokalizacji, `.agents/skills/`, dzięki czemu każde narzędzie agentowe respektujące tę konwencję je odnajduje. `.claude/skills` to dowiązanie symboliczne do `.agents/skills` — Claude Code widzi ten sam zestaw skilli bez drugiej kopii do utrzymywania w synchronizacji. --- ## Wskazówki - Nadrzędne bazy wiedzy (`linked/` i kopie git w `libs/`) **nigdy nie są modyfikowane** przez agentów. Wyjątkiem jest `libs//` oparty na konektorze (ten z `source.yaml`) — agent zarządza jego generowanym indeksem, ale tylko dla użytkownika, który lokalnie ustawił sobie `access: write` (zobacz następny punkt); kopia każdego innego użytkownika pozostaje tylko do odczytu. - Aby poprawić treść nadrzędną, zapisz poprawną wersję w `wiki/` — ona wygrywa. - Używaj `raw/inbox/` dla wszystkiego, co nieprzetworzone; agent czyści ją podczas ingestu. - Tabela routingu `wiki/index.md` to najważniejszy plik — utrzymuj go na bieżąco. - Confidence, quality i freshness pozwalają ufać właściwej treści i oflagowywać resztę do przeglądu. - Katalog `tmp/` jest w `.gitignore`, podobnie jak większość `libs/` — ale nie cały: zawartość kopii git w `libs//` pozostaje w `.gitignore` jak dawniej, natomiast `source.yaml` konektora i jego generowany `index.md`/`entities/`/`graph/`/`log.md` są śledzone, ponieważ to zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie jednorazowy artefakt budowania. `libs//source.local.yaml` (osobiste ustawienie odczytu/zapisu) to jedyny wyjątek, który zostaje w `.gitignore` razem z nimi — to osobisty stan komputera, nigdy przeznaczony do synchronizacji. Sam `outputs/` jest śledzony, ale jego regenerowalne podkatalogi budowania, `outputs/okf/` i `outputs/starlight/`, są w `.gitignore` — każdy z nich jest w pełni odtwarzalny z `wiki/` na żądanie, więc nie ma czego uzgadniać, przenosząc go w historii gita. `outputs/teaching/` (osobiste plany nauki i postęp sesji ze skilla do nauczania) jest również w `.gitignore`, ponieważ to osobisty stan sesji, a nie współdzielona treść bazy wiedzy. Commituj inne, ręcznie utrzymywane artefakty w `outputs/` normalnie. --- ## Wersja i licencja Aktualna wersja szablonu: [VERSION](VERSION). Licencja: [Apache License 2.0](LICENSE).