ckb/README.pl.md
Michał Kopeć 03ff809440 Improvement memory: attempts, expected outcomes, lesson context (D-0023)
Schema 1.8, after Google's Self-Improvement Memory paper (arXiv 2611.18856).
- Error book: one entry per recurring problem with every attempt, its
  expected and observed result and context; aliases on merge (ckb-lint §9).
- Decisions: expected_outcome, outcome, outcome_checked, ## Tried,
  append-only ## Outcome, an outcome-review procedure (ckb-decide); lint
  validates outcomes and closes a due review once outcome_checked >= review_on.
- Lessons: Context line, upstream lessons from linked/ in the session
  brief, adopt and merge rules (ckb-profile, session_start.py); ckb-init
  Step 8b carries lessons and problems into a new KB; ckb-upgrade b5.
- Deferred: a self-improvement loop over the template. Rejected: loading
  the whole record into context.
No VERSION change or changelog row: made on the merge from dev (D-0022).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:17:19 +01:00

842 lines
48 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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)
**Co zawiera ta baza wiedzy:** zobacz [ABOUT.pl.md](ABOUT.pl.md) (lub [ABOUT.md](ABOUT.md)) - jej cel,
odbiorców, zakres, właścicieli i poziom poufności, opisane przez osobę, która
ją prowadzi. Reszta tego README opisuje narzędzia Cascade KB, takie same w
każdej bazie.
Warstwowa wiki zarządzana przez agenta, w której lokalna zawartość nadpisuje
źródła nadrzędne (upstream) dostępne tylko do odczytu. 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. Przewodnik zorientowany na
zadania (jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek,
synchronizować się z innymi, z przykładami dla każdego przypadku użycia)
znajdziesz w [docs/MANUAL.pl.md](docs/MANUAL.pl.md) ([English](docs/MANUAL.md)).
Zaczynasz? Przeczytaj jednostronicowy
[docs/QUICKSTART.pl.md](docs/QUICKSTART.pl.md) ([English](docs/QUICKSTART.md)).
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](docs/OPENSPEC.pl.md) ([English](docs/OPENSPEC.md)).
Aby korzystać z bazy w aplikacji webowej Claude lub innym kliencie MCP, opcjonalny
moduł `mcp` udostępnia ją przez MCP: wyszukiwanie i odczyt, zgłoszenia do
`raw/inbox/` i cofanie źle skierowanego zgłoszenia, także przy kilku bazach
podłączonych naraz — zobacz [docs/MCP.pl.md](docs/MCP.pl.md)
([English](docs/MCP.md)). Aby zapisywać strony WWW, PDF-y i transkrypcje filmów
w `raw/inbox/`, opcjonalny moduł `capture` zapisuje każdą jako datowany zrzut
oznaczony jako niezaufany. Aby wysłać dokument do innej bazy, opcjonalny moduł
`share` korzysta ze wspólnego repozytorium git z jedną skrzynką na bazę;
odbiorca bierze dokument do `raw/inbox/` i przetwarza go zwykłym ingestem.
Aby wszystko, co baza wysyła na zewnątrz, brzmiało głosem zespołu, opcjonalny
moduł `voice` przepisuje zachowane odpowiedzi, dokumenty i raporty według
profilu głosu trzymanego jako strona wiki, nie ruszając faktów, cytatów ani
źródeł. Aby oddać dokument jako plik Worda lub PDF, opcjonalny moduł
`convert` uruchamia pandoca ze stylem firmowym trzymanym w
`templates/styles/`, zbudowanym z kilku ustawień albo z firmowego szablonu
Worda.
Każdy moduł ma własne README w obu językach w
`.agents/modules/<nazwa>/`.
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w
[docs/CHANGELOG.pl.md](docs/CHANGELOG.pl.md) ([English](docs/CHANGELOG.md)).
Własne decyzje projektowe szablonu, czyli dlaczego wygląda tak, a nie inaczej,
opisuje [docs/decisions/](docs/decisions/README.md).
### Kanały wydawnicze
Repozytorium szablonu utrzymuje cztery gałęzie wydań oraz `dev`, na którą trafia praca. 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` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Osoby rozwijające sam szablon |
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | KB, które potrzebują PowerShella albo nie mogą jeszcze przejść na 2.0 |
| `dev` | **Integracyjna** — tu najpierw trafia każda zmiana; `VERSION` nigdy się tu nie zmienia | Nikt: to nie jest kanał (upgrade z niej nie znajdzie nic nowszego) |
Wersja zmienia się tylko przy scaleniu `dev` do innej gałęzi, nigdy na samej
`dev`. Zmiany idą `dev` → `experimental` → `test` → `main`,
`dev` → `test` → `main` albo `dev` → `main`; wersja zachowuje swój numer po
drodze. Znaczenie pozycji numeru się nie zmienia: główna dla zmian
łamiących, poboczna dla funkcji, poprawkowa dla poprawek. Zobacz
[D-0022](docs/decisions/0022-dev-branch-and-merge-versioning.md).
Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć
innego kanału, 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`; każda KB sprzed tej konwencji i tak go śledziła.
---
## Struktura katalogów
```
├── ABOUT.md # Co zawiera ta KB: cel, odbiorcy, zakres, właściciele - piszesz go ty
├── ABOUT.pl.md # To samo po polsku - wypełnij plik w języku swojej bazy
├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły, ustawienia rozmów, rutyny
├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu
├── tests/ # Tylko w repo szablonu: baza-fixture + test dymny (tests/smoke.sh); nie kopiowany do KB
├── 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
│ └── documents/ # Dokumenty przygotowane z templates/
├── raw/ # Materiał źródłowy dostarczony przez użytkownika
│ └── inbox/ # Strefa zrzutu: nieprzetworzony materiał
├── templates/ # Twoje szablony dokumentów: nagłówki plus komentarz z instrukcją pod każdą sekcją
├── 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
│ ├── query-gaps.md # Pytania bez odpowiedzi, cele przyszłego ingestu
│ ├── projects/ # Opcjonalne lokalne zakresy zapytań
│ ├── 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_<autor>_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/`, a ona
automatycznie zyska 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 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/`. Potem przypomina o przejrzeniu
wyniku i uruchomieniu „sync changes", żeby wypchnąć zmiany do `origin`, kiedy
wynik będzie Ci odpowiadał. Skill:
`.agents/skills/ckb-ingest/SKILL.md`.
Zanim cokolwiek zapisze, skrypt (`dedup_inbox.py`) zgłasza pliki ze skrzynki,
które już zingestowano: identyczne co do bajtu lub co do tekstu kopie plików z
archiwum, pliki, których skrót strona już cytuje, linki do adresów URL, które
strona już cytuje, oraz duplikaty w samej skrzynce. Potem agent **się
melduje**: dla każdego źródła mówi, jak je rozumie, które strony zmieni i z
czym jest sprzeczne. Nic nie zostaje zapisane, dopóki nie odpowiesz. „Ingest
in batch” pomija meldunek. Tekst owinięty w `<private>…</private>` nigdy nie
jest ingestowany.
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 warto móc znaleźć osobno.
„Wysoka wartość" to jawny test, a nie ocena uznaniowa, bo 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`: ma to być
wyróżniający uchwyt wyszukiwania, a nie słowo obecne już 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.
Jeśli fragment nie spełnia choćby jednego warunku, treść nadal trafia na
stronę, tylko do podsumowania, a nie jako osobna jednostka. Wydzielone
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, agent w ogóle nie ładuje pełnej treści. Ł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 to samo, co przestrzeń robocza
projektu w większym systemie wyszukiwania, ale zakres pozostaje lokalny,
przejrzysty i edytowalny 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
- wyszukiwanie BM25 po sekcjach przez SQLite FTS5 (biblioteka standardowa),
każda sekcja indeksowana z tytułem strony, ścieżką nagłówków i `tldr` jako
kontekstem, więc kandydat wskazuje trafione sekcje i swój koszt w tokenach
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, a nie rozstrzygane wyborem 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.
Wartość 60 jest dostrojona 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 potrzeba serwera, bazy wektorowej ani osobnego klienta.
### 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`. Chodzi o to, żeby agent nie odpowiadał pewnie *z*
nieaktualnej strony, nie przekazując tej informacji dalej.
### Konsolidacja i podsumowania tematów (na żądanie)
„Consolidate” zapisuje raport samych propozycji w `outputs/reports/`: grupy
tematów (i czy każda strona w `wiki/topics/` istnieje i jest aktualna),
kandydatów do scalenia, brakujące linki, strony nieaktualne i stare wpisy
dziennika. Nic w wiki się nie zmienia, dopóki nie zaakceptujesz danej
pozycji. Zaakceptowane strony tematów podsumowują, co KB zawiera o jednym
temacie, i wymieniają strony członkowskie ze skrótami, więc lint oznacza temat,
gdy któryś członek się zmieni. Skill: `.agents/skills/ckb-consolidate/SKILL.md`.
### Profile i lekcje
Każda osoba może mieć profil w `workload/profiles/` (rola, jak z nią
pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej
innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu,
dla całej KB w `wiki/lessons.md`, gdzie czeka na przegląd drugiej osoby.
Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Każda
lekcja zapisuje kontekst, w którym powstała (agent/model, wersja szablonu),
więc po zmianie modelu lub szablonu agent ją sprawdza, zamiast uznawać za
pewnik. Lekcje z baz w `linked/` pojawiają się w podsumowaniu jako
zewnętrzne, poniżej lokalnych, a nowa KB może zacząć od lekcji przeniesionych
z bazy, która ją utworzyła. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Zachowane odpowiedzi
Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w
`outputs/answers/` ze skrótami w `## Sources` i sekcją `## Gaps`. Lint oznacza
zachowaną odpowiedź, której źródła się zmieniły, a to samo pytanie zadane
ponownie aktualizuje ją zamiast tworzyć duplikat. Wprowadzenie odpowiedzi do
wiki odbywa się zwykłym ingestem, nigdy bezpośrednim zapisem. Fragmenty
prywatne (`<private>`) nigdy nie są cytowane.
### 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 postanowiono, 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.
Opcjonalne `expected_outcome`, zapisane w chwili podjęcia decyzji, mówi, co
ma ona zmienić; przy przeglądzie agent zapisuje, co faktycznie się stało
(`outcome: met/partly/missed/unclear`) w dopisywanej sekcji `## Outcome`, a
sekcja `## Tried` zachowuje to, co zbudowano lub przetestowano i porzucono.
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. Dzięki temu na
pytanie „dlaczego jest tak, jak jest?" da się odpowiedzieć po latach, a
„używamy Postgresa" zamienia się 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ę. Nieudane wyszukiwania stają
się wtedy 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
review: draft|reviewed|needs_update # z reviewed_by / reviewed_on (1.6)
tags: retries, billing # tylko tagi z wiki/tags.md (1.6)
---
```
- **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 oznaczane do
przeglądu
- **supersedes / superseded_by** — gdy nowa informacja zastępuje starą,
połącz je
- **freshness_window_days** — strony starsze niż to okno są oznaczane
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*, a lint sprawdza go mechanicznie.
- **review / reviewed_by / reviewed_on** *(1.6)* — czy stronę sprawdził
człowiek: ingest zapisuje `draft`, polecenie „mark X as reviewed” ustawia
`reviewed`, a późniejsza zmiana tego, co strona twierdzi, ustawia
`needs_update`
- **tags** *(1.6)* — płaska lista sprawdzana względem własnego słownika KB
w `wiki/tags.md`; wyszukiwanie może po niej filtrować
#### Zastrzeżone sekcje treści
Trzy 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 |
| `## Rules` | tylko na stronach zakresu projektu: zasady zespołu dla tego projektu, chronione jak `## Notes` |
Gdy dwa źródła się nie zgadzają, a nikt nie zdecydował, które ma rację,
ingest wpisuje na stronę znacznik `> CONTRADICTION: …` zamiast wybierać
zwycięzcę; lint wypisuje go, dopóki człowiek go nie rozstrzygnie.
`## 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.8"`),
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, tylko 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 plik `libs/<name>/source.yaml` pisany przez użytkownika, 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` ustala częstotliwość osobno dla każdego źródła (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 zaległej
o trzy tygodnie.
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.
Do tego dochodzą dwa rozszerzenia:
- 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 czyta to, co już jest, zamiast
budować indeks samodzielnie. Jeśli go tam jeszcze nie ma, to normalny
stan przy pierwszym uruchomieniu, a nie błąd: najbliższe uruchomienie
przez użytkownika z dostępem do zapisu tworzy go tam i publikuje, bez
osobnego kroku „inicjalizacji".
- Odczyt vs. zapis, per użytkownik, per źródło. Czy *ten* użytkownik
może 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. 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.
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)** — oznacza każdą stronę bez poprawnego
frontmatteru lub pola `type`
- **Świeżość** — oznacza 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
- **Sekrety i fragmenty prywatne** — oznacza postaci danych
uwierzytelniających w commitowanym tekście i fragmenty `<private>`, które
trafiły do `wiki/`, zamaskowane, nigdy nie naprawiane automatycznie;
nieszkodliwe dopasowania trafiają do `.secrets-allow` opartego na skrócie
linii
- **Zachowane odpowiedzi** — oznacza odpowiedzi w `outputs/answers/`, których
źródła się zmieniły
- **Budżet kontekstu** — szacuje warstwę ładowaną zawsze (`AGENTS.md` plus
opisy skilli) i oznacza przekroczenie `budget.always_loaded_tokens` w
`ckb.yaml`
- **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 zostaje, oznaczona jako
nieaktualna. Kontrola wersji obejmuje więc wiedzę, a nie tylko pliki.
### 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ą oznaczane 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`, jeden
wpis na powracający problem. Wpis nazywa podejrzewaną przyczynę i zachowuje
każdą wypróbowaną naprawę: co zmieniono, czemu miało to zapobiec (zapisane,
zanim znany był wynik), co faktycznie pokazały kolejne przebiegi lintu oraz
model i wersję szablonu, przy których to działało. Naprawy, które nie
zadziałały, zostają w zapisie, więc ta sama naprawa nie jest próbowana
ponownie na ślepo. 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, musisz dodać ją jako hook Claude Code
albo zaplanowanego agenta.
- **Start sesji** → wybór tytułu rozmowy na podstawie pierwszej wiadomości
i podanie go w jednej linijce (chyba że `conversations.announce_title:
false`); jedno wywołanie `session_start.py` zapisuje tytuł i wypisuje
`git status`, jednolinijkowy wynik `lint_report.py --quick`, zaległe
rutyny i ostatni blok najnowszego podsumowania workload; sugestia
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi; zaległe rutyny wykonywane po pierwszej
prośbie; przy włączonym autozapisie rozmów sprawdza też, czy ta maszyna ma hook
`Stop` w ignorowanym przez gita `.claude/settings.local.json`, i pyta
przed jego zainstalowaniem. Podsumowanie wymienia też otwarte wątki:
nieodhaczone pozycje `- [ ]` pod `### Open threads` w notatkach workload
- **Hook startu sesji (opcjonalny, Claude Code)** → przy
`session.start_hook: true` hook `SessionStart` na tej maszynie wstrzykuje
to samo podsumowanie przed pierwszą wiadomością i ponownie po każdym
kompaktowaniu; agent pyta przed jego zainstalowaniem
- **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia
niezsynchronizowanych zmian; po sesji z realną pracą jednorazowe pytanie,
czy zapisać rozmowę (`ckb-add-conversation`) — zapis tylko po „tak" albo
bez pytania, gdy w `ckb.yaml` ustawiono `conversations.autosave: true`
- **Każda tura dotykająca KB** → notatka w `workload/` (Reguła D)
- **Błędne lub źle skierowane źródło** → `ckb-retract` usuwa je i dokładnie to,
co wniosło (strony, twierdzenia, krawędzie), po pokazaniu planu; prośby z
`raw/retractions/` (np. od serwera MCP) są zgłaszane przy ingestii
- **Pytanie bez odpowiedzi** → wpis w `wiki/query-gaps.md`, jedyny zapis,
który należy do `ckb-retrieve`; odpowiedzi nigdy nie są automatycznie
zapisywane jako strony
- **Lint na żądanie lub przez rutynę** → „Lint" uruchamia pełną kontrolę;
„lint every week" robi z tego rutynę w `ckb.yaml`, która odpala się na
pierwszym starcie sesji po upływie okresu (`ckb-routine`)
### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
Wiki rośnie dzięki rzeczywistym niepowodzeniom agenta, a nie dzięki
doborowi treści z góry:
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 ją uwzględnia
### Podsumowania sesji
Po każdej akcji konwersacyjnej agent dopisuje do
`workload/YYYY-MM-DD_<autor>_summary.md` — jeden plik na osobę na dzień,
nazwany i opisany tożsamością gita, pod którą działa sesja. Daje to
ciągłość między sesjami, przeglądalną historię ewolucji bazy wiedzy, a we
współdzielonym repozytorium zapis, kto co zrobił, bez konfliktów scalania w
`workload/`. Ta sama tożsamość trafia do linii `**Author:**` każdego wpisu
w `wiki/log.md`. Agent czyta ostatnie podsumowanie na starcie sesji,
niezależnie od autora, aby kontynuować od miejsca, w którym skończono.
### 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żna wyeksportować do `outputs/okf/` jako pakiet zgodny z
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
v0.1, który odczyta 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łe przekształcenie (przemapowanie
frontmatteru, przepisanie linków, regenerację 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, a nie
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żna też wyeksportować do formatu dla Astro + Starlight
w `outputs/starlight/`, co daje czytelną dla człowieka stronę dokumentacji,
w odróżnieniu od eksportu OKF, przeznaczonego dla maszyn i narzędzi.
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; agent zadaje
tylko dwa pytania konfiguracyjne (zakres eksportu: pełny uruchamialny
szkielet vs. tylko treść; czy dołączyć strony meta dziennika/księgi błędów)
i przekazuje raport 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ą kolejność czytania w trybie tylko do odczytu:
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", „wprowadź mnie
w bieżący stan projektu"), 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`.
### Dokumenty z szablonów (na żądanie)
Dokumenty, które piszesz regularnie, trzymaj jako szablony w `templates/`:
plik Markdown, w którym nagłówki nadają kształt, a komentarze HTML mówią
agentowi, co ma trafić do każdej sekcji - zapytaj użytkownika, przeczytaj tę
stronę wiki, zmieść się w trzech zdaniach. „Prepare a new document using
template status-report" czyta szablon, zadaje wszystkie pytania naraz, resztę
bierze z wiki i zapisuje wynik w `outputs/documents/`, z frontmatterem
wskazującym szablon i użyte strony. Luki stają się liniami `TODO:`, nie
domysłami. W zestawie jest jeden przykład, `templates/status-report.md`;
format opisuje `templates/README.md`. Zobacz
`.agents/skills/ckb-document/SKILL.md`.
### Synchronizacja gita (na żądanie)
Na żądanie agent uzgadnia historię gita tego repozytorium z jego zdalnym
repozytorium `origin`: commituje lokalne zmiany, pobiera i scala zdalne,
pokazuje Ci konflikty plik po pliku do rozwiązania, a na koniec
automatycznie wypycha wynik (push). Przed stagingiem sprawdza, czy to, co ma
zostać zacommitowane, nie zawiera sekretów, i zatrzymuje się, jeśli coś
znajdzie. 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/mówiłam o Y") i dostać zacytowaną
dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej `.md` do
`raw/inbox/` i powiedz „Ingest". Powiedz „save conversations automatically",
aby przełączyć `conversations.autosave` w `ckb.yaml` - od tej pory każda
sesja jest zapisywana na końcu bez pytania. Każda sesja zaczyna się od
tytułu, który agent nadaje jej na podstawie pierwszej wiadomości i podaje
w pierwszej odpowiedzi; nazywa on zapisany transkrypt, a „stop telling me
the title" wycisza tę linijkę. 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 (woli dodać sesję, niż
upychać materiał) 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`.
### Wyjaśnienia metodą Feynmana (na żądanie)
Powiedz „Feynman me on X” (albo „wyjaśnij mi porządnie X”, „czego nie
rozumiem?”), a agent wyjaśni jedną stronę wiki słowami, które zna
dwunastolatek, pod każdym fragmentem podając link do sekcji, z której
pochodzi, a potem nazwie każde miejsce, w którym wyjaśnienie się rozrzedziło,
i przypisze je do jednej z trzech grup: luka na stronie, luka w jej
źródłach albo luka u wyjaśniającego. Agent nigdy nie łata luki własną
wiedzą. Następnie prosi cię, żebyś sam wyjaśnił jeden fragment, i schodzi
poziom głębiej. Gdy nie podasz pojęcia, proponuje strony robocze (`draft`),
oparte na jednym źródle albo nieaktualne. Sesja trafia do
`outputs/teaching/feynman/`; luka w źródłach trafia do `wiki/query-gaps.md`
tylko po twojej zgodzie. Zobacz `.agents/skills/ckb-feynman/SKILL.md`.
---
## Szybki start
0. **Opcjonalnie: zainstaluj Pythona 3.8+.** Osiem skilli uruchamia skrypt
w Pythonie (tylko biblioteka standardowa); bez niego kontrola na starcie
sesji przechodzi na zapasowy skrypt bash (na Windows: Git Bash), lint i wyszukiwanie
działają w wolniejszym trybie ręcznym, a eksporty są niedostępne. Kroki
dla poszczególnych systemów: [docs/MANUAL.pl.md → Wymagania wstępne](docs/MANUAL.pl.md#wymagania-wstępne).
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/<name>/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/<name>/` 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
oznaczać resztę do przeglądu.
- `tmp/` jest w `.gitignore`. Podobnie większość `libs/`, z jednym
podziałem: kopia git w `libs/<name>/` pozostaje ignorowana, natomiast
konektorowy `libs/<name>/` ma śledzone `source.yaml` oraz generowane
`index.md`/`entities/`/`graph/`/`log.md`. Ten indeks to zsyntetyzowana
wiedza warta udostępnienia przez „sync changes", a nie artefakt budowania.
`libs/<name>/source.local.yaml` to wyjątek w wyjątku: osobisty stan
maszyny, nigdy nie synchronizowany.
- `outputs/` jest śledzony, ale `outputs/okf/` i `outputs/starlight/` nie.
Każdy z nich da się odtworzyć z `wiki/` na żądanie, więc nie ma czego
uzgadniać w historii gita. Ręcznie utrzymywane artefakty w `outputs/`
commituj normalnie.
- `outputs/teaching/` też jest ignorowany. Plany nauki, postęp sesji i sesje
Feynmana są osobiste, nie są współdzieloną treścią KB.
---
## Wersja i licencja
Aktualna wersja szablonu: [VERSION](VERSION). Licencja:
[Apache License 2.0](LICENSE).