michal/ckb

Michał Kopeć 057a7647cc Sync: local changes as of 2026-07-17T12:45:15Z

2026-07-17 14:45:15 +02:00

19 KiB

Raw Blame History

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 MANUAL.pl.md (English).

Struktura katalogów

├── libs/         # Zewnętrzne bazy wiedzy tylko do odczytu, kopiowane przez git (w .gitignore)
├── 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
│   ├── 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

Agent nigdy nie zapisuje do linked/ ani libs/. Aby poprawić treść nadrzędną, zapisz właściwą wersję w wiki/ — automatycznie zyskuje pierwszeństwo.

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.

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.

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
---

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

Sam wiki/index.md dodatkowo zawiera kb_schema_version (np. "1.1"), 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 (uses, depends_on, caused, contradicts, supersedes) są zapisywane w wiki/graph/edges.json. Zapytania mogą przechodzić po grafie, aby odkrywać powiązane strony (np. „co zależy od Redis?").

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.

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 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
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:

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ą

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 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. 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.

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/cbk-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

Zamontuj nadrzędne bazy wiedzy:

ln -s /path/to/other-kb ./linked/my-upstream
git clone https://github.com/org/external-kb ./libs/external-kb

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 libs/) nigdy nie są modyfikowane przez agentów.
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.
Katalogi tmp/ i libs/ są w .gitignore. 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. Licencja: Apache License 2.0.

19 KiB Raw Blame History Unescape Escape