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>
842 lines
48 KiB
Markdown
842 lines
48 KiB
Markdown
# 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).
|