- New skill ckb-add-conversation: on request, copies the session's Claude Code transcript (JSONL) into raw/saved-conversations/<date>/ with a readable Markdown rendering and an index.md; answers "did we discuss X" from those files. Saved conversations stay outside retrieval and ingest. - AGENTS.md: directory contract, cascade note, routing row, disambiguation, Rule E session-end ask (save only on a yes). - ckb-retrieve, ckb-ingest, ckb-reset (tier 3), ckb-init know the folder. - Docs, both READMEs, CHANGELOG, VERSION; smoke test renders a fixture transcript against a golden file. - .gitignore: ideas/ local scratch folder for template ideas. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
37 KiB
Cascade Knowledge Base
Read this in: English | Polski
Repozytorium źródłowe (zawsze najbardziej aktualna wersja): 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 docs/MANUAL.pl.md (English).
Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł
software dodaje repozytoria w src/ i pracę sterowaną specyfikacją — zobacz
docs/OPENSPEC.pl.md (English).
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w docs/CHANGELOG.pl.md (English). Dlaczego szablon wygląda tak, a nie inaczej — jego własne decyzje projektowe — opisuje docs/decisions/.
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:
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
├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły
├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu
├── tests/ # Baza-fixture + test dymny deterministycznych skryptów (tests/smoke.sh)
├── 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 # Czego dotyczy ta KB — treść, nie schemat
│ ├── 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/<name>/ 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/<name>/
oparty na konektorze (zobacz „Konektory zewnętrznych źródeł i indeksowanie”
poniżej) — agent zarządza jego generowanym indeksem tak samo, jak wiki/.
Funkcje
Każda funkcja poniżej to skill w .agents/skills/. Skill ładuje się do
kontekstu dopiero po wywołaniu; AGENTS.md zawiera tylko routing i reguły
nienegocjowalne, nic więcej.
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 „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. Skill:
.agents/skills/ckb-ingest/SKILL.md.
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. Indeks pozostaje mały; strony, na które wskazuje, nie muszą.
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
rgdla komunikatów błędów, komend, flag, nazw plików, nazw hostów, identyfikatorów zgłoszeń i innych literalnych tokenów — również wraw/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
Zebranie i połączenie tych sygnałów jest mechaniczne, więc wykonuje je
skrypt — .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py — tak
samo jak detekcję w lincie; agent czyta jego ranking i wykonuje osąd
(deduplikacja według twierdzenia, przerankowanie względem dosłownego pytania,
weryfikacja źródła). 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:
---
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 — zamiast tego dostaje
jednolinijkowy wpis POINTER. wiki/decisions/log.md to jedyny dziennik
podkatalogu w bazowym szkielecie, a Reguła B w AGENTS.md wymienia go jako
wyjątek.
Konektory zewnętrznych źródeł i indeksowanie (na żądanie)
Folder libs/<name>/ obsługuje drugi sposób zasilania, obok istniejącej
kopii git: mały, autorski plik libs/<name>/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:
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/<name>/ — 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. 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.yamlmoże dodać opcjonalny blokindex:, 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:
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".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 - 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/<name>/source.local.yaml— domyślnie tylko do odczytu. Ustawienieaccess: writew 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.
Skill: .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/<name>/...
lub libs/<name>/.... 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
confidencedla stron niewzmacnianych nowymi źródłami - Przegląd retencji — archiwizuje strony
retention: lowstarsze 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. Skill: .agents/skills/ckb-lint/SKILL.md.
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
Konwencje sesji
To reguły, których agent przestrzega na podstawie AGENTS.md, a nie haki
wpięte w narzędzie — nic w .claude/ nie uruchamia się samo. Jeśli chcesz,
by któraś była wymuszana mechanicznie, dodajesz ją sam jako hook Claude Code
albo zaplanowanego agenta.
- Start sesji → odczyt
wiki/index.mdi ostatniego podsumowania workload;git statusilint_report.py --quick; sugestiackb-sync-changeslubckb-linttylko wtedy, gdy któreś coś zgłosi - Koniec sesji → dopisanie do
workload/; powtórzenie sprawdzenia niezsynchronizowanych zmian - Każda tura dotykająca KB → notatka w
workload/(Reguła D) - Pytanie bez odpowiedzi → wpis w
wiki/query-gaps.md, jedyny zapis, który należy dockb-retrieve; odpowiedzi nigdy nie są automatycznie zapisywane jako strony - Lint na żądanie → „Lint" uruchamia pełną kontrolę; nie ma wbudowanego harmonogramu
Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
Wiki rośnie na podstawie rzeczywistych niepowodzeń agenta, a nie z góry narzuconej kuracji:
- Agent nie potrafi odpowiedzieć → identyfikuje brakującą wiedzę
- Proponuje minimalną encję/stronę wypełniającą lukę
- Użytkownik zatwierdza lub dostarcza materiał źródłowy
- Kolejny ingest wprowadza ją
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 dokładnie jednym
dzienniku, w kolejności odwrotnie chronologicznej: wiki/decisions/log.md
dla wszystkiego pod wiki/decisions/, wiki/log.md dla reszty, z
jednolinijkowym POINTER w dzienniku głównym, gdy zmianę wchłania dziennik
decyzji. Lint zgłasza zmianę zapisaną w obu.
Eksport OKF (na żądanie)
Wiki może zostać wyeksportowana jako zgodny z
Open Knowledge Format
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. 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. Skill:
.agents/skills/ckb-export-okf/SKILL.md.
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. Skill: .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ć.
Nie ma to nic wspólnego z „Ingest", który zamienia raw/inbox/ na strony
wiki/ i nie dotyka gita. Samo „sync" zawsze oznacza gita. Skill:
.agents/skills/ckb-sync-changes/SKILL.md.
Zapisane rozmowy (na żądanie)
Powiedz „save this conversation", a transkrypt sesji zostanie skopiowany do
raw/saved-conversations/<RRRR-MM-DD>/ - oryginalny plik JSONL, który
przechowuje Claude Code, plus czytelna wersja .md - i wpisany do index.md
w tym folderze. Zapisane rozmowy pozostają poza wyszukiwaniem: na pytania
agent nadal odpowiada wyłącznie z wiki. Możesz natomiast pytać o same
rozmowy („czy rozmawialiśmy o X", „co ci mówiłem o Y") i dostać zacytowaną
dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej .md do
raw/inbox/ i powiedz „Ingest". Skill:
.agents/skills/ckb-add-conversation/SKILL.md.
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/<topic>/. 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
-
Opcjonalnie: zainstaluj Pythona 3.8+. Pięć skilli uruchamia skrypt w Pythonie (tylko biblioteka standardowa); bez niego kontrola na starcie sesji przechodzi na zapasowy skrypt bash/PowerShell, lint i wyszukiwanie działają w wolniejszym trybie ręcznym, a eksporty są niedostępne. Kroki per system: docs/MANUAL.pl.md → Wymagania wstępne.
-
Zamontuj nadrzędne bazy wiedzy:
ln -s /path/to/other-kb ./linked/my-upstream git clone https://github.com/org/external-kb ./libs/external-kbAlbo, dla żywego źródła, którego nie chcesz w pełni kopiować lokalnie, umieść zamiast tego
libs/<name>/source.yaml(zobacz „Konektory zewnętrznych źródeł i indeksowanie" powyżej) i powiedz „index external sources". -
Wrzuć surowy materiał do
raw/inbox/(notatki, linki, artykuły). -
Poleć agentowi „Ingest" — przetworzy skrzynkę odbiorczą, skonsultuje kaskadę, wydobędzie encje i zapisze ustrukturyzowany markdown w
wiki/. -
Zadawaj pytania — agent używa indeksu do routingu, TLDR-ów do szybkich odpowiedzi i grafu do odkrywania relacji.
-
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 wlibs/) nigdy nie są modyfikowane przez agentów. Wyjątkiem jestlibs/<name>/oparty na konektorze (ten zsource.yaml) — agent zarządza jego generowanym indeksem, ale tylko dla użytkownika, który lokalnie ustawił sobieaccess: 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.mdto 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.
tmp/jest w.gitignore. Podobnie większośćlibs/, z jednym podziałem: kopia git wlibs/<name>/pozostaje ignorowana, natomiast konektorowylibs/<name>/ma śledzonesource.yamloraz generowaneindex.md/entities//graph//log.md. Ten indeks to zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie artefakt budowania.libs/<name>/source.local.yamlto wyjątek w wyjątku: osobisty stan maszyny, nigdy nie synchronizowany.outputs/jest śledzony, aleoutputs/okf/ioutputs/starlight/nie. Każdy z nich da się odtworzyć zwiki/na żądanie, więc nie ma czego uzgadniać w historii gita. Ręcznie utrzymywane artefakty woutputs/commituj normalnie.outputs/teaching/też jest ignorowany. Plany nauki i postęp sesji są osobiste, nie są współdzieloną treścią KB.
Wersja i licencja
Aktualna wersja szablonu: VERSION. Licencja: Apache License 2.0.