- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every prose file written under apply_to (outputs/answers, documents, reports, PROJECT-OVERVIEW) in a voice whose profile is a wiki page, wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode, profile, writer, apply_to, skip, chat); frozen spans never change, vague claims flagged not cut; `writer:` delegates to an external rewriting skill such as a personal ghost-writer. ckb-module writes a manifest's default_config into the entry's config:. Eval ckb-module/install-voice. - 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a house style in templates/styles/; unit tests and eval ckb-module/install-convert. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1285 lines
77 KiB
Markdown
1285 lines
77 KiB
Markdown
# Podręcznik użytkownika
|
||
|
||
*Read this in: [English](MANUAL.md) | **Polski***
|
||
|
||
Pierwszy raz? Jednostronicowy [Szybki start](QUICKSTART.pl.md) prowadzi od
|
||
pustego folderu do pierwszej odpowiedzi.
|
||
|
||
To jest podręcznik dla *człowieka* korzystającego z Cascade Knowledge Base
|
||
(tego repozytorium) — nie dla agenta. Zasady działania samego agenta
|
||
znajdziesz w [AGENTS.md](../AGENTS.md) / [CLAUDE.md](../CLAUDE.md). Techniczny,
|
||
funkcja-po-funkcji przegląd znajdziesz w [README.md](../README.md) (lub
|
||
[README.pl.md](../README.pl.md)). Pełny schemat strony wraz z historią obu
|
||
numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md). Ten dokument
|
||
jest zorientowany na zadania:
|
||
„chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”
|
||
|
||
Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI,
|
||
z którego korzystasz w tym repozytorium (Claude Code lub inny agent, który
|
||
czyta `AGENTS.md`). Nie musisz używać dokładnych sformułowań — pokazane
|
||
frazy wyzwalające to przykłady, nie magiczne słowa; agent dopasowuje się do
|
||
intencji.
|
||
|
||
---
|
||
|
||
## Spis treści
|
||
|
||
1. [Tworzenie lub inicjalizacja wiki](#1-tworzenie-lub-inicjalizacja-wiki)
|
||
2. [Dodawanie wiedzy](#2-dodawanie-wiedzy)
|
||
3. [Utrzymanie porządku](#3-utrzymanie-porządku)
|
||
4. [Synchronizacja — z samym sobą i z innymi ludźmi](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi)
|
||
5. [Aktualizacja szablonu](#5-aktualizacja-szablonu)
|
||
6. [Przykłady użycia](#6-przykłady-użycia)
|
||
7. [Co jest generowane przez agenta, a co możesz edytować](#7-co-jest-generowane-przez-agenta-a-co-możesz-edytować)
|
||
8. [Szybki przegląd](#8-szybki-przegląd)
|
||
|
||
---
|
||
|
||
## 1. Tworzenie lub inicjalizacja wiki
|
||
|
||
### Wymagania wstępne
|
||
|
||
Agent robi prawie wszystko, czytając i pisząc Markdown. Osiem skilli
|
||
dodatkowo uruchamia mały skrypt w **Pythonie 3.8+** (tylko biblioteka
|
||
standardowa, nic do `pip install`): lint (w tym kontrola uruchamiana na
|
||
początku każdej sesji), ranking przy wyszukiwaniu, wykrywanie duplikatów w
|
||
skrzynce, rutyny, raporty konsolidacji, zapis rozmów oraz dwa eksporty.
|
||
Python jest *zalecany*, nie bezwzględnie wymagany:
|
||
|
||
| Bez Pythona | Co się dzieje |
|
||
|---|---|
|
||
| Kontrola na starcie sesji | Zamiast niej działa zapasowy skrypt bash (na Windows w Git Bash, dołączonym do Git for Windows). Wykrywa strony uszkodzone, przeterminowane, zmienione źródła i najczęstsze postaci sekretów; zaznacza, że cytaty Crux i budżet kontekstu nie zostały sprawdzone. |
|
||
| Sprawdzanie duplikatów przy „Ingest” | Agent ręcznie porównuje skróty `sha256sum` plików ze skrzynki i archiwum, a porównanie adresów URL pomija. |
|
||
| „Lint” | Agent przechodzi ręczną listę kontrolną z `grep` — wolniej, w ograniczonym zakresie, i mówi, co pominął. |
|
||
| Pytania | Agent szereguje kandydatów ręcznie z indeksów i `grep` zamiast skryptu fuzji. |
|
||
| Eksport OKF / Starlight | Niedostępny do czasu zainstalowania Pythona. |
|
||
|
||
Agent raz na sesję mówi, że nie znalazł interpretera, i dalej pracuje
|
||
ścieżkami zapasowymi. Jak zainstalować Pythona:
|
||
|
||
- **Windows** — `winget install Python.Python.3.12` w terminalu, albo
|
||
aplikacja „Python 3.12” z Microsoft Store, albo instalator z
|
||
[python.org](https://www.python.org/downloads/windows/) (zaznacz *Add python.exe
|
||
to PATH*). Potem `python --version` lub `py -3 --version` powinno
|
||
wypisać `Python 3.x`. Jeśli `python` otwiera Store, wyłącz *Aliasy
|
||
wykonywania aplikacji* dla `python.exe` w Ustawieniach Windows albo używaj
|
||
`py -3`.
|
||
- **macOS** — `brew install python` przez [Homebrew](https://brew.sh) albo
|
||
`xcode-select --install` dla `python3` dostarczanego przez Apple.
|
||
- **Linux** — `sudo apt install python3` (Debian/Ubuntu),
|
||
`sudo dnf install python3` (Fedora), `sudo pacman -S python` (Arch).
|
||
Większość dystrybucji już go ma.
|
||
|
||
Dowolne z `python3`, `python` lub `py -3` wystarczy; agent próbuje ich w tej
|
||
kolejności.
|
||
|
||
### Jeśli czytasz to wewnątrz istniejącej Cascade KB
|
||
|
||
Nie musisz nic robić — struktura już istnieje (`wiki/`, `raw/`, `outputs/`
|
||
itd.). Przejdź do [§2](#2-dodawanie-wiedzy).
|
||
|
||
### Zakładanie zupełnie nowej wiki gdzie indziej
|
||
|
||
Powiedz:
|
||
|
||
> „Set up a new wiki like this one in `~/projects/my-notes`.”
|
||
|
||
To sklonuje wyłącznie *schemat* — strukturę katalogów, plik zachowań
|
||
`AGENTS.md`/`CLAUDE.md` oraz pusty szkielet `wiki/` — do docelowego folderu.
|
||
Nigdy nie kopiuje rzeczywistej zawartości tego projektu (żadnych encji,
|
||
danych grafu, notatek). Otrzymujesz świeżą, pustą KB, gotową na pierwszy
|
||
zrzut do `raw/inbox/`. Zobacz `.agents/skills/ckb-init/SKILL.md`.
|
||
|
||
Szablon może pochodzić z dwóch miejsc: z plików tego repozytorium albo ze
|
||
świeżego, płytkiego klona kanonicznego repozytorium szablonu (lub dowolnego
|
||
forka/mirrora, którego URL podasz), pobranego do folderu roboczego.
|
||
Powiedz „pull the latest template and set up a KB in \<folder\>” — albo
|
||
uruchom skilla spoza jakiejkolwiek KB — a agent najpierw sklonuje
|
||
repozytorium, a dopiero potem zbuduje szkielet. Klon jest wyłącznie
|
||
roboczy: nowa KB dostaje własną historię gita (agent pyta przed
|
||
`git init`), a nie historię szablonu.
|
||
|
||
Jeśli docelowy folder wygląda już jak baza wiedzy (ma `wiki/` lub
|
||
`AGENTS.md`), agent zatrzyma się i zapyta, zanim czegokolwiek dotknie — nie
|
||
nadpisze po cichu istniejącej bazy wiedzy.
|
||
|
||
### Budowanie na bazie cudzej wiki
|
||
|
||
Cascade KB może opierać się na jednej lub wielu *nadrzędnych* bazach
|
||
wiedzy, które pozostają tylko do odczytu. Są trzy sposoby ich
|
||
podpięcia:
|
||
|
||
- **Dowiązanie symboliczne** (inna KB na twojej maszynie, lub taka, którą
|
||
utrzymujesz gdzie indziej i chcesz mieć „na żywo”):
|
||
```bash
|
||
ln -s /path/to/other-kb ./linked/other-team
|
||
```
|
||
- **Kopia git** (zewnętrzna KB, której chcesz mieć zamrożoną, wersjonowaną
|
||
kopię):
|
||
```bash
|
||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||
```
|
||
Nie chcesz używać gita? Większość hostingów git oferuje też opcję
|
||
„Download ZIP” na stronie repozytorium — pobierz i rozpakuj zawartość
|
||
bezpośrednio do `./libs/external-kb`. Tak czy inaczej otrzymujesz tę
|
||
samą zamrożoną, tylko-do-odczytu kopię. Różnica polega tylko na tym, że
|
||
nie odświeżysz jej później przez `git pull`; żeby ją zaktualizować,
|
||
pobierz ZIP ponownie i rozpakuj go na starą zawartość.
|
||
- **Konektor** (żywe zewnętrzne źródło, którego *nie* chcesz mieć w pełnej
|
||
lokalnej kopii — folder SharePoint, folder Google Drive albo inne
|
||
podłączone źródło): sam utwórz `libs/<name>/source.yaml`:
|
||
```yaml
|
||
connector: sharepoint
|
||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||
description: "Wspólny folder raportów zespołu finansowego"
|
||
```
|
||
a potem powiedz „index external sources". Agent czyta konfigurację,
|
||
łączy się z tym, co jest dostępne w danej sesji (podłączonym narzędziem
|
||
Microsoft 365/Google Drive albo zwykłym pobraniem URL), i buduje krótki
|
||
indeks tego, co znajdzie — po jednym wpisie na dokument — wewnątrz tego
|
||
samego folderu `libs/<name>/`. Zobacz [§6](#6-przykłady-użycia) po
|
||
omówiony przykład i to, jak wygląda wynik.
|
||
|
||
Zanim oprzesz się na źródle typu konektor:
|
||
- Nie musisz sam budować indeksu. `source.yaml` może dodać blok
|
||
`index:` wskazujący na już zbudowany indeks — repozytorium git albo
|
||
zasób współdzielony — dzięki czemu pobierasz to, co ktoś inny już
|
||
zaindeksował, zamiast samodzielnie skanować żywe źródło. Każde
|
||
uruchomienie najpierw sprawdza tę lokalizację: jeśli indeks już tam
|
||
jest, dostajesz go. Jeśli go tam jeszcze nie ma (normalny stan, zanim
|
||
ktokolwiek z dostępem do zapisu to uruchomił), to nie błąd: najbliższe
|
||
uruchomienie osoby z dostępem do zapisu po raz pierwszy go tam utworzy
|
||
i opublikuje.
|
||
- Budowanie i odświeżanie są opcjonalne, per osoba, per źródło.
|
||
Domyślnie każdy ma do źródła typu konektor dostęp tylko do odczytu —
|
||
niczyj agent nie przeskanuje żywego konektora w imieniu osoby, która
|
||
wyraźnie o to nie poprosiła. Powiedz „make me the admin for
|
||
`<source>`", żeby się na to zapisać (tworzy to lokalny, osobisty plik
|
||
`libs/<name>/source.local.yaml` — nigdy niecommitowany, nigdy
|
||
niewidoczny dla współpracowników). Jedna lub dwie osoby utrzymują
|
||
źródło dla całego zespołu; nikt inny go ponownie nie skanuje.
|
||
- Możesz ustawić, jak często ma być odświeżane. Dodaj opcjonalne
|
||
`refresh_interval_days: 7` do `source.yaml` (domyślnie 30). Folder
|
||
zmieniający się codziennie potrzebuje krótszego okna niż kwartalne
|
||
archiwum, którego nikt nie tyka. Wtedy zarówno „index external
|
||
sources", jak i „Lint" powiedzą ci, kiedy źródło jest zaległe i o ile.
|
||
Ma to największe znaczenie, jeśli masz do niego dostęp tylko do
|
||
odczytu: gdy wiesz, *które* źródło się przedawniło, możesz zapytać
|
||
osobę, która je utrzymuje.
|
||
|
||
Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania.
|
||
Agent sprawdza najpierw twoją lokalną `wiki/`, potem przechodzi przez
|
||
`linked/`, potem `libs/`, i korzysta z tego, co ma odpowiedź. Nigdy nie
|
||
edytujesz plików wewnątrz `linked/` ani kopii git w `libs/<name>/`
|
||
bezpośrednio; jeśli coś tam jest błędne lub nieaktualne, poprawiasz to,
|
||
zapisując poprawioną wersję we własnej lokalnej `wiki/`, która zawsze
|
||
wygrywa. (`libs/<name>/` oparty na konektorze to jedyne miejsce, gdzie
|
||
agent *sam* zapisuje w twoim imieniu — zobacz [§6](#6-przykłady-użycia) —
|
||
ale tylko swój generowany indeks, i tylko część budowania/odświeżania,
|
||
jeśli jesteś administratorem tego źródła; `source.yaml` zawsze pozostaje
|
||
twój do edycji, nigdy agenta.)
|
||
|
||
---
|
||
|
||
## 2. Dodawanie wiedzy
|
||
|
||
To główny sposób, w jaki rośnie wiki. Jest pięć dróg:
|
||
|
||
### A. Wrzuć materiał, potem powiedz „Ingest”
|
||
|
||
Umieść cokolwiek nieprzetworzonego w `raw/inbox/` — wklejone notatki, plik
|
||
`.txt` z transkrypcją, `links.txt` z adresami URL, PDF, chaotyczny plik
|
||
roboczy. Nie musisz go najpierw porządkować. Następnie powiedz:
|
||
|
||
> „Ingest.” (lub „Update the wiki” — to samo; nigdy fraza zawierająca „sync”, to jest git)
|
||
|
||
Przykład:
|
||
|
||
> *Wrzucasz `meeting-2026-07-10.txt` (surowe notatki z rozmowy z klientem)
|
||
> do `raw/inbox/`, potem mówisz „Ingest.”*
|
||
>
|
||
> Agent czyta plik, wydobywa wymienione osoby, decyzje i otwarte pytania,
|
||
> tworzy lub aktualizuje strony encji w `wiki/entities/`, zapisuje relacje
|
||
> w `wiki/graph/edges.json`, dodaje nowe strony do `wiki/index.md`, loguje
|
||
> zmianę w `wiki/log.md` i przenosi oryginalny plik do
|
||
> `raw/archive/2026-07-10/`. Na koniec przypomina o przejrzeniu wyniku i
|
||
> powiedzeniu „sync changes”, gdy wynik będzie ci odpowiadał.
|
||
|
||
Przy długim transkrypcie agent nie poprzestaje na jednej stronie
|
||
podsumowania. Wyciąga wyszukiwalne pytanie, podsumowanie, rozwiązanie oraz
|
||
zaangażowane systemy i osoby — a pojedyncze fragmenty awansuje do własnych
|
||
znajdowalnych sekcji, jeśli inaczej przepadłyby wewnątrz podsumowania. Ta
|
||
ostatnia część ma celowy próg: fragment musi zawierać konkretny
|
||
termin (flagę, komunikat błędu, klauzulę, numer wersji), mieć co najmniej
|
||
kilka zdań i być potwierdzony przez coś dalej w materiale. W przeciwnym razie
|
||
zostaje wtopiony w podsumowanie. Bez tego progu każdy akapit wygląda na wart
|
||
zacytowania, a strona wiki znów staje się transkryptem — co przekreśla sens
|
||
jego zingestowania.
|
||
|
||
Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
|
||
pomijając `raw/archive/`, które zawiera już przetworzoną historię).
|
||
|
||
Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy:
|
||
|
||
- **Duplikaty zostają wyłapane.** Skrypt porównuje każdy plik ze skrzynki z
|
||
`raw/archive/` i ze źródłami, które strony wiki już cytują. Plik już
|
||
zingestowany (co do bajtu albo ten sam tekst zapisany ponownie z innymi
|
||
końcami linii), link do strony, którą wiki już cytuje, albo dwie kopie tego
|
||
samego pliku w skrzynce zostają zgłoszone jako „już zingestowane <data> →
|
||
<strony>”. Agent pyta, zanim którykolwiek pominie.
|
||
- **Agent się melduje.** Dla każdego źródła mówi w trzech–czterech
|
||
linijkach, jak je rozumie, które strony utworzy lub zmieni i z czym jest
|
||
sprzeczne. Potem czeka. Popraw go w tym momencie: to dużo taniej niż
|
||
poprawianie stron później. Powiedz „ingest in batch” (albo „no check-in”),
|
||
żeby to pominąć, np. dla dużej paczki, której ufasz. Ingest uruchomiony
|
||
przez rutynę z `confirm: false` też to pomija.
|
||
- **Fragmenty prywatne zostają poza wiki.** Wszystko, co w źródle owiniesz w
|
||
`<private>` … `</private>`, nigdy nie trafia do wiki: nie jest zapisywane,
|
||
cytowane ani streszczane.
|
||
|
||
Strony tworzone przez agenta zaczynają jako `review: draft`, czyli nikt ich
|
||
jeszcze nie sprawdził. Gdy nowy materiał nie zgadza się ze stroną i nie
|
||
wiadomo, co jest prawdą, agent nie wybiera zwycięzcy. Wpisuje na stronę
|
||
znacznik i mówi ci o tym:
|
||
|
||
```markdown
|
||
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||
```
|
||
|
||
Znacznik zostaje, dopóki go nie rozstrzygniesz (zob. „Przegląd, sprzeczności
|
||
i tagi” w [Utrzymaniu porządku](#3-utrzymanie-porządku)).
|
||
|
||
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
|
||
|
||
### B. Po prostu powiedz agentowi coś w rozmowie
|
||
|
||
Nie zawsze potrzebujesz pliku. Jeśli powiesz agentowi fakt o trwałej
|
||
wartości, np. „właściwie to termin przesunął się na wrzesień”, agent może
|
||
zapisać go bezpośrednio do `wiki/` jako nową stronę lub
|
||
aktualizację istniejącej, tak samo jak z zaingestowanego pliku.
|
||
|
||
### C. Pozwól agentowi powiedzieć, czego brakuje (Demand-Driven Context)
|
||
|
||
Jeśli zapytasz o coś, na co wiki nie potrafi odpowiedzieć, agent nie
|
||
zawiedzie po cichu. Wskaże lukę i zaproponuje minimalną stronę,
|
||
która ją wypełni.
|
||
|
||
Przykład:
|
||
|
||
> **Ty:** „Jaka jest nasza polityka w sprawie X?”
|
||
> **Agent:** „Wiki jeszcze tego nie pokrywa. Chcesz, żebym dodał zalążek
|
||
> strony, czy możesz wkleić/opisać tę politykę, a ja ją spiszę?”
|
||
|
||
Zatwierdzasz, wklejasz źródło albo wrzucasz je do `raw/inbox/` — kolejny
|
||
ingest to wchłonie. Dzięki temu wiki pozostaje napędzana zapotrzebowaniem:
|
||
rośnie wokół tego, o co faktycznie pytasz, a nie wokół wszystkiego, co
|
||
teoretycznie dałoby się spisać.
|
||
|
||
Trwałe braki można też śledzić w `wiki/query-gaps.md`. Dobry wpis o luce jest
|
||
maleńki: pytanie, gdzie agent szukał i jakie najmniejsze źródło lub strona
|
||
sprawiłaby, że odpowiedź będzie dostępna następnym razem.
|
||
|
||
### D. Zapisz decyzję
|
||
|
||
Gdy zapada jakaś decyzja — wybór technologii, zmiana procesu, polityka —
|
||
powiedz:
|
||
|
||
> „Zapisz decyzję: przenosimy billing na Postgresa. Alice i Bob zdecydowali
|
||
> dzisiaj, bo zapytania raportowe zabijały MySQL-a."
|
||
|
||
Agent zapisze numerowany rekord pod `wiki/decisions/` z decyzją, autorami,
|
||
datą, uzasadnieniem, alternatywami i tym, czego dotyczy. Jeśli zastępuje
|
||
wcześniejszą decyzję, połączy obie w obu kierunkach i oznaczy starą jako
|
||
zastąpioną — nie ruszając jej uzasadnienia. O to, czego nie podasz, dopyta w
|
||
jednej turze; jeśli jesteś w środku pracy, powiedz to, a zapisze, co ma, i
|
||
wskaże, które pola zostawił otwarte.
|
||
|
||
Potem pytaj, jak chcesz:
|
||
|
||
> „Co zdecydowaliśmy w sprawie bazy danych billingu?"
|
||
> „Dlaczego używamy Postgresa?"
|
||
> „Kto to zdecydował i kiedy?"
|
||
> „Które decyzje są wciąż tylko propozycjami?"
|
||
> „Co zastąpiło decyzję 3?"
|
||
|
||
Odpowiedź zawsze przychodzi z informacją kto i kiedy, i wprost mówi, gdy
|
||
decyzja jest propozycją, a nie decyzją obowiązującą, albo została już
|
||
zastąpiona — żeby nie opierać się na czymś, co nie obowiązuje. Skill: `ckb-decide`.
|
||
|
||
Dwie zasady:
|
||
|
||
- Decyzje są tylko do dopisywania. „Właściwie zmieniliśmy zdanie" tworzy
|
||
*nową* decyzję zastępującą starą; nigdy nie edytuje uzasadnienia starej.
|
||
Historia jest tu sednem. Zwykłe błędy zapisu („tam miała być Anna,
|
||
nie Alice") agent poprawia w miejscu.
|
||
- Propozycja to nie decyzja. Jeśli sprawa nie została rozstrzygnięta,
|
||
zapisywana jest jako `proposed` bez daty decyzji i pojawia się, gdy pytasz,
|
||
co jest jeszcze otwarte.
|
||
|
||
### E. Utwórz lokalny zakres projektu
|
||
|
||
Gdy jakiś temat, klient, system lub inicjatywa wraca często, poproś:
|
||
|
||
> „Utwórz zakres projektu dla integracji płatności."
|
||
|
||
Agent utworzy lub zaktualizuje zwykłą stronę Markdown pod `wiki/projects/`,
|
||
wymieniającą strony, encje, pliki z `raw/archive/`, indeksy konektorów i
|
||
obszary grafu, które należy przeszukać najpierw dla tego zakresu. Nadal masz
|
||
jedną lokalną wiki; to tylko daje powracającym pytaniom lepszy punkt startowy.
|
||
|
||
Strona zakresu może też zawierać zasady zespołu dla tego projektu, w sekcji
|
||
`## Rules`, którą piszesz sam: „środowiska nazywamy `prod`/`stage`, nigdy
|
||
`production`”, „decyzje tutaj wymagają zgody klienta”. Agent stosuje je
|
||
zawsze, gdy pracuje w tym zakresie, a żaden skill ich nie przepisuje. Nadrzędny
|
||
jest tylko `AGENTS.md`.
|
||
|
||
---
|
||
|
||
## 3. Utrzymanie porządku
|
||
|
||
Powiedz, kiedy chcesz — po dużym ingest lub po prostu okresowo (albo niech
|
||
robi to za ciebie [rutyna](#rutyny-rób-to-za-mnie-co-n-dni)):
|
||
|
||
> „Lint.”
|
||
|
||
To uruchamia przegląd kondycji całej wiki:
|
||
|
||
- strony bez wymaganego frontmatteru (`type`) są oflagowywane
|
||
- strony nietykane od dłuższego czasu są oflagowywane jako nieaktualne
|
||
- wyniki pewności (confidence) zanikają, jeśli nic ostatnio ich nie
|
||
wzmocniło
|
||
- stare, niskopriorytetowe strony są archiwizowane do `wiki/archived/`
|
||
(nigdy usuwane)
|
||
- sprzeczne strony są łączone stare→nowe (supersesja)
|
||
- osierocone strony (nic do nich nie linkuje) dostają odnośniki zwrotne
|
||
albo są archiwizowane
|
||
- uszkodzone krawędzie grafu są naprawiane lub usuwane
|
||
- brakujące/podwójne wpisy w indeksie i dzienniku są poprawiane
|
||
- konektorowe źródła, których indeks jest zaległy do odświeżenia, zostają
|
||
oflagowane wraz z informacją o ile — przydatne nawet jeśli masz do tego
|
||
źródła dostęp tylko do odczytu, bo mówi ci, kogo dopytać
|
||
- strony, których źródło faktycznie się zmieniło, zostają oflagowane —
|
||
patrz niżej
|
||
- cytaty, których nie ma już w źródle, na które się powołują, zostają
|
||
oflagowane
|
||
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
|
||
- przypadkowo zacommitowane dane uwierzytelniające (klucze, tokeny, klucze
|
||
prywatne, hasło w adresie URL) gdziekolwiek w `wiki/`, `outputs/`,
|
||
`workload/` lub `raw/`, a także fragment `<private>`, który trafił na
|
||
stronę wiki, zostają oflagowane — nigdy nie są naprawiane automatycznie,
|
||
patrz niżej
|
||
- zachowane odpowiedzi w `outputs/answers/`, których źródła się zmieniły,
|
||
zostają oflagowane
|
||
- warstwa ładowana zawsze (`AGENTS.md` plus opis każdego skilla) zostaje
|
||
oflagowana, gdy przekroczy budżet z `ckb.yaml`
|
||
|
||
Dwie kontrole źródeł (zmienione skróty i cytaty, które przestały się
|
||
zgadzać) to różnica między „ta strona jest stara"
|
||
a „ta strona jest błędna".
|
||
|
||
Każda strona zapisuje skrót materiału, z którego powstała. Nieaktualność
|
||
liczona datą to przypuszczenie: strona napisana rok temu może być wciąż
|
||
całkowicie poprawna. Skrót nie jest przypuszczeniem — agent przelicza go i
|
||
albo źródło jest co do bajtu tym, przeciwko czemu stronę napisano, albo ktoś
|
||
je zmienił. Gdy źródło się zmienia, strona na nim zbudowana trafia na szczyt
|
||
listy, przed wszystko, co się jedynie zestarzało.
|
||
|
||
Strony cytują też swoje źródła wprost, w sekcji `## Crux` — kilka dosłownych
|
||
linijek niosących właściwe twierdzenie, pod streszczeniem agenta. Wynikają z
|
||
tego dwie rzeczy. Gdy zadajesz pytanie, agent często może odpowiedzieć z
|
||
cytatu zamiast ponownie czytać całe źródło i pokazać ci słowa, a nie swoją
|
||
parafrazę. A gdy cytat przestaje zgadzać się ze źródłem, to strona twierdzi —
|
||
w cudzysłowie — coś, czego jej dowód już nie mówi. To najmocniejsze
|
||
znalezisko lintu i agent nigdy nie „naprawi" go, po cichu dopasowując cytat
|
||
do źródła.
|
||
|
||
Połowa wykrywająca działa jako skrypt Python tylko-do-odczytu
|
||
(`scripts/lint_report.py`; bez Pythona zob.
|
||
[Wymagania wstępne](#wymagania-wstępne), co nadal działa), więc ta sama
|
||
wiki zawsze daje tę samą listę znalezisk. Agent czyta ten raport, a potem
|
||
wykonuje części wymagające osądu (supersesja, niejednoznaczne sieroty,
|
||
wpisy do księgi błędów oraz decyzja, co naprawić, a co oddać tobie).
|
||
Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do
|
||
twojej decyzji. Podobnie jak Ingest, na koniec przypomina o przejrzeniu i
|
||
synchronizacji. Skill: `.agents/skills/ckb-lint/SKILL.md`.
|
||
|
||
**Sekrety.** Klucz znaleziony w repozytorium jest pokazywany tylko w
|
||
pierwszych czterech znakach, nigdy w całości. Naprawa należy do ciebie: usuń
|
||
go i **wymień** (rotate) — zacommitowany sekret zostaje w historii gita nawet
|
||
po usunięciu linii. Nieszkodliwe dopasowanie, np. przykładowy klucz w
|
||
dokumentacji, można dodać do listy dozwolonych: znalezisko podaje linię
|
||
`<ścieżka> <skrót>` do wpisania w `.secrets-allow` w katalogu głównym repo.
|
||
Skrót obejmuje tę jedną linię, więc jej edycja przywraca znalezisko. Ta sama
|
||
kontrola działa przed każdym commitem w „sync changes”.
|
||
|
||
### Przegląd, sprzeczności i tagi
|
||
|
||
**Przegląd.** Strona może mówić, czy sprawdził ją człowiek: `review: draft`
|
||
(napisał ją agent, nikt nie sprawdził), `reviewed` (z `reviewed_by` i
|
||
`reviewed_on`) albo `needs_update` (była przejrzana, potem się zmieniła lub
|
||
pojawiła się sprzeczność). Zapytaj „what needs review?”, żeby zobaczyć
|
||
kolejkę, najpierw `needs_update`. Powiedz „mark X as reviewed”, gdy
|
||
przeczytasz stronę; agent zapisze twoje nazwisko i dzisiejszą datę i nigdy nie
|
||
oznaczy strony, której nie wskazałeś. Jeśli przejrzana strona później się
|
||
zmieni, lint to zauważy. Odpowiedzi oparte na stronach `draft` mówią o tym.
|
||
|
||
**Sprzeczności.** Lint wypisuje każdy otwarty znacznik `> CONTRADICTION:`.
|
||
Rozstrzygasz go, mówiąc, która strona ma rację. Agent wtedy zastępuje błędną
|
||
stronę (supersesja), zapisuje decyzję („record a decision: we retry five
|
||
times”) albo poprawia twierdzenie, i usuwa znacznik.
|
||
|
||
**Tagi.** Strona może mieć `tags: retries, billing`, ale tylko z tagami
|
||
wymienionymi w `wiki/tags.md`. Zanim użyjesz nowego tagu, dodaj tam wiersz;
|
||
lint flaguje każdy tag spoza listy. Pytania można wtedy zawęzić do tagu.
|
||
|
||
**Zimne strony.** Agent zapisuje, które strony faktycznie czyta, w
|
||
`tmp/access.log` na twojej maszynie (nigdy nie jest commitowany). „Which pages
|
||
has nobody read lately?” uruchamia `lint --cold` i proponuje przeniesienie
|
||
takich stron do sekcji `## Archive` ich indeksu, żeby były sprawdzane na
|
||
końcu. To tylko propozycje: nic nie jest przenoszone, zmieniane ani usuwane, a
|
||
strony z `retention: high` nigdy nie są proponowane.
|
||
|
||
**Budżet kontekstu.** Każda sesja zaczyna się od wczytania `AGENTS.md` i
|
||
jednolinijkowego opisu każdego skilla. To kosztuje tokeny, zanim cokolwiek
|
||
powiesz. Lint szacuje ten koszt (znaki ÷ 4) i flaguje go, gdy przekroczy
|
||
`budget: always_loaded_tokens` w `ckb.yaml` (domyślnie 9000). Powiedz „show
|
||
the context budget”, żeby zobaczyć rozbicie.
|
||
|
||
### Start sesji: podsumowanie, otwarte wątki i hook
|
||
|
||
Na początku każdej sesji agent uruchamia jeden skrypt i dostaje krótkie
|
||
podsumowanie: kim jesteś (tożsamość z gita), stan gita, jednolinijkową
|
||
kontrolę kondycji, zaległe rutyny i ostatnią notatkę z `workload/`. Reaguje
|
||
tylko na linie, które tego wymagają.
|
||
|
||
**Otwarte wątki.** Gdy sesja kończy się czymś niedokończonym, agent zapisuje
|
||
to w notatce z danego dnia pod nagłówkiem `### Open threads` jako
|
||
`- [ ] pozycja`. Podsumowanie liczy otwarte wątki we wszystkich notatkach i
|
||
wymienia kilka najstarszych, zaznaczając te starsze niż 30 dni. Żeby zamknąć
|
||
wątek, odhacz go tam, gdzie został otwarty (`- [x]`), albo napisz
|
||
`- [x] dropped: <powód>`. Nic nie jest usuwane, więc notatki pozostają
|
||
zapisem. To jest widok „co jest teraz w toku”: nie ma osobnego pliku
|
||
statusu, który trzeba by aktualizować.
|
||
|
||
**Hook startu sesji (tylko Claude Code).** Domyślnie agent sam uruchamia
|
||
podsumowanie jako pierwszą czynność. Z hookiem robi to Claude Code, zanim
|
||
napiszesz pierwszą wiadomość, i ponownie po kompaktowaniu rozmowy, więc w
|
||
długiej sesji podsumowanie nie wypada z kontekstu. Żeby go włączyć, powiedz
|
||
„turn on the session-start hook”. Agent ustawia `session: start_hook: true`
|
||
w `ckb.yaml` i, po zapytaniu, instaluje hook w `.claude/settings.local.json`.
|
||
Ten plik jest per maszyna i nigdy nie jest commitowany, bo hook w gicie
|
||
uruchamiałby kod przy każdym klonie. Współpracownicy na innych maszynach
|
||
widzą w podsumowaniu linię `start hook:` i są pytani raz. Inni agenci
|
||
ignorują to ustawienie i dalej uruchamiają podsumowanie sami.
|
||
|
||
### Konsolidacja i podsumowania tematów
|
||
|
||
Ingest dodaje wiedzę po jednym źródle; nikt nie patrzy na całość. Powiedz:
|
||
|
||
> „Consolidate.”
|
||
|
||
Agent zapisuje raport w `outputs/reports/<data>_consolidation.md` i niczego w
|
||
wiki nie zmienia. Wymienia w nim:
|
||
|
||
- **tematy**: grupy powiązanych stron (członkowie projektu, strony z
|
||
wspólnym tagiem, połączone grupy), każda oznaczona jako brak, aktualna lub
|
||
nieaktualna;
|
||
- **kandydatów do scalenia**: dwie strony, które zdają się mówić to samo;
|
||
- **brakujące linki**: strony cytujące te same źródła, a nielinkujące do
|
||
siebie;
|
||
- **strony nieaktualne lub zmienione**;
|
||
- **stare wpisy dziennika**, liczone według miesięcy. Sam dziennik nigdy nie
|
||
jest przepisywany.
|
||
|
||
Wybierasz, czym się zająć. „Build the topic summaries” zapisuje
|
||
`wiki/topics/<nazwa>.md`: jedną stronę mówiącą, co KB zawiera ogólnie o danym
|
||
temacie, z listą stron członkowskich i ich skrótami. Gdy członek się zmieni,
|
||
lint oznaczy temat jako nieaktualny. Pytania typu „co ogólnie wiemy o
|
||
płatnościach?” zaczynają się od tych stron, a agent i tak sprawdza strony
|
||
członkowskie przed odpowiedzią. Dobrze pasuje tu rutyna co dwa tygodnie, która
|
||
najpierw pyta: „consolidate every two weeks, ask me first”. Skill:
|
||
`.agents/skills/ckb-consolidate/SKILL.md`.
|
||
|
||
### Rutyny: rób to za mnie co N dni
|
||
|
||
Wszystko, co można powiedzieć agentowi, można zamienić w rutynę:
|
||
|
||
> „Lint co tydzień.”
|
||
> „Indeksuj zewnętrzne źródła co 30 dni, ale najpierw mnie zapytaj.”
|
||
|
||
Agent zapisuje ją w `ckb.yaml` w bloku `routines:` (nazwa, fraza do
|
||
wykonania, okres, czy pytać najpierw i data ostatniego uruchomienia).
|
||
Rutyna liczy czas od ostatniego uruchomienia, nie według kalendarza: na
|
||
starcie każdej sesji agent sprawdza, którym rutynom minął okres, najpierw
|
||
odpowiada na to, o co prosisz, a potem w tej samej turze wykonuje zaległe,
|
||
raportując każdą jedną linijką. Rutyna oznaczona „najpierw zapytaj” jest
|
||
zamiast tego proponowana na końcu odpowiedzi i uruchamia się tylko po
|
||
twojej zgodzie. Rutyna, która się nie powiodła albo została odrzucona, nie
|
||
jest oznaczana jako wykonana, więc wraca w następnej sesji. Ręczne
|
||
wykonanie też się liczy — gdy sam powiesz „Lint”, licznik tygodniowego
|
||
lintu startuje od nowa.
|
||
|
||
Ponieważ data ostatniego uruchomienia jest commitowana z repozytorium,
|
||
rutyna odpala się raz na okres dla wszystkich pracujących w tej KB, a nie
|
||
raz na maszynę. Dwóch akcji nie da się zrobić rutyną: resetu wiki i
|
||
synchronizacji z gitem. „List routines”, „which routines are due”, „run the
|
||
routines now” i „remove the weekly lint” robią to, co mówią. To nie jest
|
||
chmurowy harmonogram Claude Code: nic się nie dzieje, gdy nikt nie ma KB
|
||
otwartej.
|
||
Skill: `.agents/skills/ckb-routine/SKILL.md`.
|
||
|
||
### Zaczynanie od zera: reset do czystego szablonu
|
||
|
||
Czasem chcesz zachować *kształt* bazy wiedzy bez jej zawartości — zwykle
|
||
dlatego, że to repozytorium pełni też rolę szablonu przekazywanego innym, a
|
||
zdążyło zebrać decyzje, podsumowania sesji i strony encji, które nie powinny
|
||
z nim wędrować.
|
||
|
||
> „Zresetuj wiki.” / „Zrób z tego czysty szablon.”
|
||
|
||
To jedyne polecenie w tym repozytorium, które **celowo usuwa wiedzę**, więc
|
||
jest zbudowane tak, żeby trudno było je uruchomić przez przypadek:
|
||
|
||
1. **Najpierw szuka punktu przywracania.** Jeśli drzewo robocze jest
|
||
„brudne”, zatrzymuje się i proponuje commit — po resecie wszystko, co
|
||
zacommitowane, jest o jedno `git checkout` stąd, a wszystko
|
||
niezacommitowane po prostu znika. Może też otagować commit
|
||
(`pre-reset-<data>`), żeby nie trzeba było pamiętać hasha.
|
||
2. **Pyta, jak daleko sięgnąć.** Sześć poziomów wybieranych osobno: wiedza w
|
||
wiki, historia `workload/`, materiał źródłowy w `raw/`, `outputs/`,
|
||
źródła zewnętrzne i zainstalowane moduły. Domyślnie włączony jest tylko
|
||
pierwszy. `libs/`, `linked/` i moduły domyślnie na *nie* — `linked/`
|
||
zawiera dowiązania do cudzych baz wiedzy, więc usuwa dowiązanie, ale
|
||
nigdy nie podąża za nim.
|
||
3. **Liczy, zanim zapyta.** Dostajesz inwentarz — ile stron, ile rekordów
|
||
decyzji (wymienionych z numerem i tytułem), ile krawędzi grafu, plus
|
||
wszystko oznaczone `retention: high` — i jedną linijkę o tym, co
|
||
przetrwa.
|
||
4. **Wymaga wpisania frazy**, nie „tak”. A jeśli w odpowiedzi zmienisz
|
||
zakres, przeliczy wszystko i zapyta ponownie, bo zgoda dotyczyła
|
||
konkretnej liczby, a liczba się zmieniła.
|
||
5. **Weryfikuje po wszystkim**, uruchamiając lint, zanim powie, że się
|
||
udało.
|
||
|
||
Odtwarza dokładnie to, co utworzyłby `ckb-init`: te same katalogi, te same
|
||
pliki szkieletu, ten sam `kb_schema_version`. Opróżnienie treści nie cofa
|
||
wersji schematu.
|
||
|
||
Czego nie rusza nigdy, z potwierdzeniem czy bez: warstwy szablonu
|
||
(`AGENTS.md`, `.agents/`, `LICENSE`, `VERSION`, dokumentacja) oraz `src/`,
|
||
gdzie leżą niezależne repozytoria kodu, do których usuwania to polecenie nie
|
||
ma żadnego tytułu.
|
||
|
||
Jedna celowa osobliwość: w odróżnieniu od każdego innego skilla ten **nie**
|
||
zapisuje notatki sesji w `workload/` — byłby to pierwszy wpis w katalogu,
|
||
który właśnie opróżnił. Informuje o tym w raporcie.
|
||
|
||
Skill: `.agents/skills/ckb-reset/SKILL.md`.
|
||
|
||
---
|
||
|
||
## 4. Synchronizacja — z samym sobą i z innymi ludźmi
|
||
|
||
Są tu dwa różne rodzaje „synchronizacji”. Nie myl ich:
|
||
|
||
| | Ingest / Lint | Sync changes |
|
||
|---|---|---|
|
||
| **Warstwa** | Treść (co wiki wie) | Git (czyj dysk ma jakie pliki) |
|
||
| **Czego dotyczy** | `wiki/`, `raw/` | Historia commitów repo i zdalne repozytorium `origin` |
|
||
| **Powiedz** | „Ingest” / „Lint” | „Sync changes” |
|
||
|
||
### Uzgadnianie z `origin` (synchronizacja na poziomie gita)
|
||
|
||
Powiedz:
|
||
|
||
> „Sync changes.”
|
||
|
||
To commituje wszelkie lokalne zmiany (np. z ostatniego Ingest lub Lint),
|
||
pobiera wszystko nowe z `origin`, scala oba, a jeśli pojawi się konflikt —
|
||
przeprowadza cię przez niego plik po pliku, pytając, czy zachować twoją
|
||
wersję, wersję zdalną, czy podać scaloną treść dla każdego konfliktowego
|
||
fragmentu. Gdy wszystko jest rozwiązane, wypycha zmiany (push).
|
||
|
||
Jeśli to repozytorium nigdy nie było połączone ze zdalnym, agent najpierw
|
||
poprosi cię o wklejenie adresu URL:
|
||
|
||
> **Agent:** „To repozytorium nie ma skonfigurowanego zdalnego `origin`.
|
||
> Wklej adres URL zdalnego repozytorium, a dodam je jako `origin`.”
|
||
>
|
||
> **Ty:** `https://git.wierzbowa.cloud/michal/ckb`
|
||
|
||
Dla *tej* Cascade KB kanoniczną, zawsze aktualną kopią jest repozytorium
|
||
źródłowe
|
||
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb).
|
||
Jeśli nie masz pewności, czy twoja lokalna kopia jest aktualna, porównaj ją
|
||
właśnie z nim.
|
||
|
||
Nie musisz go też klonować przez `git clone`, żeby mieć działającą kopię.
|
||
Jeśli wolisz w ogóle nie używać gita, pobierz go jako ZIP z tej strony i
|
||
rozpakuj lokalnie: dostajesz dokładnie te same pliki i możesz od razu
|
||
skierować swojego agenta na rozpakowany folder. Zabraknie tylko
|
||
skonfigurowanego `origin`, więc „sync changes” i „upgrade the wiki” nie
|
||
będą miały z czym porównywać ani dokąd wypychać zmian. Gdy zechcesz z nich
|
||
korzystać, uruchom `git init` w rozpakowanym folderze i dodaj powyższy
|
||
adres jako `origin` (`git remote
|
||
add origin https://git.wierzbowa.cloud/michal/ckb`).
|
||
|
||
Od tej pory „sync changes” uzgadnia stan właśnie z tym zdalnym
|
||
repozytorium. Tak dzieli się jedną wiki między wieloma osobami: każdy
|
||
robi ingest/edycje lokalnie, a „sync changes” to sposób, w jaki zmiany
|
||
każdej osoby docierają do reszty — i jak zmiany innych docierają do ciebie.
|
||
Przed commitem sprawdza, czy to, co ma zostać zacommitowane, nie zawiera
|
||
sekretów (zob. [Utrzymanie porządku](#3-utrzymanie-porządku)). Jeśli coś
|
||
znajdzie, zatrzymuje się i pyta, a commituje mimo to tylko na wyraźne
|
||
polecenie. Skill: `.agents/skills/ckb-sync-changes/SKILL.md`.
|
||
|
||
Agent przypomina o tym też sam: na początku i na końcu sesji pracy wykonuje
|
||
szybkie, tylko-do-odczytu sprawdzenie, czy jest coś niezacommitowanego lub
|
||
niewypchniętego, i informuje, czy warto uruchomić „sync changes”. Nigdy nie
|
||
wypycha zmian bez twojej prośby. Na końcu sesji, w której wykonano realną
|
||
pracę, pyta też raz, czy zapisać rozmowę (zob. „Zapisywanie rozmowy” w Przykładach użycia) — i
|
||
zapisuje tylko wtedy, gdy się zgodzisz.
|
||
|
||
### Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)
|
||
|
||
Jeśli zamiast *jednej współdzielonej wiki* chcesz mieć *własną wiki, która
|
||
buduje na cudzej* — np. wiki twojego zespołu nadbudowana na
|
||
ogólnofirmowej KB — to w ogóle nie jest synchronizacja gita; to podpięcie
|
||
`linked/`/`libs/` opisane w
|
||
[§1](#budowanie-na-bazie-cudzej-wiki). Każda osoba/zespół utrzymuje własną
|
||
lokalną `wiki/` (która zawsze wygrywa), a nadrzędne bazy wiedzy aktualizują
|
||
się według własnego harmonogramu, niezależnie.
|
||
|
||
---
|
||
|
||
## 5. Aktualizacja szablonu
|
||
|
||
To inny rodzaj „bycia na bieżąco” niż wszystko w
|
||
[§4](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi): tamta sekcja
|
||
dotyczy *zdalnego repozytorium twojej własnej KB* — dzielenia się twoją
|
||
zawartością ze współpracownikami. Ta sekcja dotyczy nadganiania *narzędzi*
|
||
twojej KB względem ulepszeń wprowadzonych w samym kanonicznym szablonie
|
||
Cascade KB, niezależnie skąd twoja KB pierwotnie pochodzi (`ckb-init`,
|
||
klon, fork, albo KB, która istnieje wystarczająco długo, by poprzedzać
|
||
niektóre z tych konwencji).
|
||
|
||
Powiedz:
|
||
|
||
> „Upgrade the wiki.” / „Check for a newer template version.”
|
||
|
||
### Z jakiego kanału pobierasz
|
||
|
||
Repozytorium szablonu utrzymuje cztery gałęzie i domyślnie dostajesz tę
|
||
stabilną:
|
||
|
||
| Gałąź | Czym jest | Kto powinien na niej być |
|
||
|---|---|---|
|
||
| `main` | **Stabilna** — wydany szablon | Ty, o ile nie masz powodu, żeby być gdzie indziej |
|
||
| `test` | **Kandydat do wydania** — walidowany, zanim trafi do `main` | Pomagasz walidować wydanie albo potrzebujesz poprawki, która weszła, ale nie została wydana |
|
||
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Rozwijasz sam szablon |
|
||
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | Potrzebujesz PowerShella albo nie możesz jeszcze przejść na 2.0 |
|
||
|
||
Żeby użyć innej, powiedz której:
|
||
|
||
> „Upgrade from the test branch.” / „Check experimental for updates.” /
|
||
> „Switch this KB back to the stable channel.”
|
||
|
||
To, co wybierzesz, zostaje — jest zapisane w `ckb.yaml`, więc kolejny upgrade
|
||
zostanie na tym samym kanale, zamiast po cichu ściągnąć cię z powrotem na
|
||
`main`. Tak samo przy tworzeniu: *„zainicjuj z gałęzi experimental”*.
|
||
|
||
Na jedno warto uważać. Jeśli śledzisz `test` albo `experimental`, twoja KB
|
||
może mieć wersję, której `main` jeszcze nie wydało. Sprawdzenie względem
|
||
`main` nie znajdzie wtedy nic nowszego — agent powie ci, że **wyprzedzasz**, a
|
||
nie że jesteś aktualny, bo to dwie różne sytuacje. Powrót stamtąd na `main` to
|
||
*downgrade*: może usunąć skille i cofnąć schemat poniżej tego, pod co napisano
|
||
twoje strony. Agent poprosi o wyraźne potwierdzenie, a gdy treść
|
||
przestałaby być zgodna z własnym zadeklarowanym schematem, odmówi wprost.
|
||
|
||
Nowa wersja **główna** (1.x → 2.0) usuwa coś, na czym KB może polegać, więc
|
||
agent nigdy nie przechodzi przez nią po cichu, nawet z rutyny. Podaje, co
|
||
nowa wersja usuwa (z changeloga), i pyta: przejść, czy przełączyć tę KB na
|
||
gałąź utrzymaniową `1.x` (*„przełącz tę KB na gałąź 1.x”*), która dostaje
|
||
poprawki, ale już nie nowe funkcje.
|
||
|
||
### Co jest sprawdzane
|
||
|
||
Sprawdzane są dwie odrębne rzeczy, i każda, obie albo żadna może
|
||
coś wykazać:
|
||
|
||
- **Warstwa szablonu/narzędzi** — `AGENTS.md`/`CLAUDE.md`, każdy skill pod
|
||
`.agents/skills/`, `LICENSE`, `VERSION` oraz dokumenty
|
||
`README`/`MANUAL`. Porównywana z plikiem `VERSION` samego kanonicznego
|
||
repozytorium.
|
||
- **Własna wersja schematu twojej treści wiki** — pole `kb_schema_version`
|
||
w `wiki/index.md`, porównywane z tym, czego obecnie oczekuje szablon. KB
|
||
może być w pełni aktualna pod względem narzędzi, ale nadal nosić treść
|
||
`wiki/` zbudowaną lata temu pod starszym (albo w ogóle brakującym)
|
||
`kb_schema_version` — albo odwrotnie.
|
||
|
||
**Jeśli nic nie jest opóźnione na żadnym froncie**, dostaniesz
|
||
„już aktualne — szablon vX, schemat wiki vY” i nic się nie zmieni.
|
||
|
||
**Jeśli warstwa szablonu jest opóźniona**, zobaczysz podział na to, co
|
||
nowe (nic lokalnego do stracenia) i to, co *zmienione* (plik szablonu,
|
||
którego lokalna kopia różni się — to może być ulepszenie szablonu albo
|
||
twoja celowa zmiana, np. w `AGENTS.md`). Agent zapyta, plik po pliku albo
|
||
wszystko naraz, czy wziąć wersję
|
||
szablonu, zachować swoją, czy najpierw zobaczyć pełną różnicę — nic nie
|
||
zostanie po cichu nadpisane.
|
||
|
||
**Jeśli schemat twojej treści wiki jest opóźniony** (w tym częsty przypadek
|
||
starszej KB bez żadnego `kb_schema_version` — „niewersjonowanej” wiki),
|
||
dostaniesz odrębne, wyraźne pytanie:
|
||
|
||
> **Agent:** „Twoja treść `wiki/` została zbudowana bez
|
||
> `kb_schema_version` (lub ze starszą wersją). Czy mam też zaktualizować
|
||
> wszystkie foldery i dane związane z wiki do nowego standardu?”
|
||
|
||
Jeśli powiesz tak, agent:
|
||
- dodaje wszelkie brakujące elementy szkieletu (np. `wiki/graph/index.md`,
|
||
który nigdy nie istniał, jeśli twoja KB poprzedza funkcję grafu),
|
||
- uzupełnia brakujący frontmatter na istniejących stronach — `tldr`,
|
||
`confidence`, `quality`, `retention` i tak dalej — **bez przepisywania
|
||
czegokolwiek z twojego tekstu**; dodawana jest tylko struktura i
|
||
metadane, nigdy treść merytoryczna strony,
|
||
- potwierdza z tobą, zanim przypisze `type` do jakiejkolwiek strony, gdzie
|
||
nie jest to oczywiste,
|
||
- loguje każdą dotkniętą stronę w `wiki/log.md` jako wpis migracyjny, żeby
|
||
było jasne, że zmiana była strukturalna, a nie nową wiedzą,
|
||
- i podnosi `kb_schema_version`, gdy skończy.
|
||
|
||
Jeśli powiesz nie, agent nie dotknie niczego pod `wiki/` — nawet
|
||
`kb_schema_version` — więc następnym razem, gdy to uruchomisz, nadal
|
||
zostanie to poprawnie oflagowane jako opóźnione, zamiast po cichu uznane
|
||
za załatwione. Te dwie decyzje (warstwa szablonu, treść wiki) są
|
||
niezależne: możesz zaakceptować jedną i odrzucić drugą.
|
||
|
||
Podobnie jak Ingest i Lint, na koniec pojawia się przypomnienie o
|
||
przejrzeniu wyniku i uruchomieniu „sync changes” względem *twojego
|
||
własnego* `origin` — repozytorium szablonu, z którym właśnie porównano,
|
||
jest zwykle osobnym zdalnym repozytorium dla każdej KB innej niż własna
|
||
kopia robocza projektu szablonu. Skill: `.agents/skills/ckb-upgrade/SKILL.md`.
|
||
|
||
---
|
||
|
||
## 6. Przykłady użycia
|
||
|
||
### Zadawanie pytań
|
||
|
||
Zapytaj zwykłym językiem:
|
||
|
||
> „Co wiemy o ryzyku migracji w Q3?”
|
||
|
||
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony. Jeśli
|
||
istnieje pasujący zakres projektu pod `wiki/projects/`, przeszukuje najpierw
|
||
ten zakres. Potem uruchamia `retrieve_candidates.py`, który zbiera sygnały dokładnych
|
||
dopasowań, `tldr`, zakresu projektu, grafu i zaufania w jeden połączony
|
||
ranking, rozszerza kontekst wokół dopasowanych sekcji, przechodzi po grafie
|
||
wiedzy w poszukiwaniu powiązanych faktów i sięga do `linked/`/`libs/`, jeśli
|
||
lokalna wiki nic nie ma.
|
||
Dostajesz odpowiedź opartą na tym, co faktycznie zostało spisane, a nie na
|
||
domysłach.
|
||
|
||
Dwa szczegóły mają znaczenie dla użytkownika:
|
||
|
||
- Przeszukuje też `raw/inbox/`. Materiał wrzucony dziś rano i jeszcze
|
||
niezingestowany nadal może odpowiedzieć na twoje pytanie. Agent powie ci,
|
||
kiedy odpowiedź pochodzi z niezingestowanego materiału, co jednocześnie
|
||
sygnalizuje, że „Ingest" jest zaległy.
|
||
- Odpowiedzi noszą własne zastrzeżenia. Jeśli strona stojąca za odpowiedzią
|
||
przekroczyła okno świeżości, ma niską pewność albo została przeczytana z
|
||
zapisanego indeksu konektora zamiast z żywego źródła, odpowiedź mówi o tym
|
||
obok danego twierdzenia. Jeśli dwie strony są ze sobą sprzeczne, a żadna nie
|
||
została jeszcze oznaczona jako zastąpiona, też o tym usłyszysz. Nie
|
||
trzeba samodzielnie czytać frontmatteru, żeby wiedzieć, na ile ufać
|
||
otrzymanej odpowiedzi.
|
||
- Znajduje sekcję, a nie tylko stronę. Indeks wyszukiwania wszystkich sekcji
|
||
stron (trzymany w `tmp/`, przebudowywany automatycznie) pozwala agentowi
|
||
przeczytać tylko tę sekcję, która odpowiada, i wie, ile kosztowałoby
|
||
przeczytanie całej strony. Gdy odpowiedź jest w istocie tabelą, wykresem,
|
||
prezentacją lub stroną WWW, agent raz to zaproponuje.
|
||
|
||
Gdy odpowiedź wymagała prawdziwej pracy (złożenia kilku stron, ponownego
|
||
przeczytania źródła), agent raz proponuje jej zachowanie. Jeśli się zgodzisz,
|
||
trafia do `outputs/answers/<data>_<pytanie>.md` razem ze źródłami, na których
|
||
się opiera (ze skrótami, więc lint powie ci, gdy się zmienią), i sekcją
|
||
`## Gaps` z tym, na co KB nie umiała odpowiedzieć. Gdy później zadasz to samo
|
||
pytanie, agent zaproponuje aktualizację zachowanej odpowiedzi zamiast
|
||
pisania drugiej. Jeśli odpowiedź zawiera coś, co powinna wiedzieć sama wiki,
|
||
agent proponuje wprowadzenie jej z powrotem. Oznacza to zwykły ingest, z tym
|
||
samym meldunkiem, więc zachowana odpowiedź nigdy sama nie zmienia wiki.
|
||
Fragmenty prywatne (`<private>`) nigdy nie są cytowane w odpowiedzi.
|
||
|
||
Gdy nadal nie ma odpowiedzi, agent powinien powiedzieć, czego brakuje, i albo
|
||
dodać/zaproponować krótki wpis w `wiki/query-gaps.md`, albo zasugerować
|
||
najmniejsze źródło do wrzucenia do `raw/inbox/`.
|
||
|
||
### Pytanie, kto się na czymś zna
|
||
|
||
> „Kto zna się na ścieżce przywracania checkpointów?" / „Kto jest właścicielem
|
||
> usługi billingowej?"
|
||
|
||
Na te pytania odpowiada bezpośrednio graf wiedzy, a nie wyszukiwanie nazwisk po
|
||
słowach kluczowych. Ingest zapisuje krawędź eksperctwa lub własności, gdy
|
||
materiał źródłowy faktycznie pokazuje, że ktoś odpowiada na pytania w danym
|
||
temacie albo ma zadeklarowaną odpowiedzialność za niego — a nie na podstawie
|
||
obecności na spotkaniu czy nazwy stanowiska. Jeśli nikt nie ma jeszcze
|
||
zapisanej krawędzi, agent wraca do tego, kogo zarchiwizowane źródła pokazują
|
||
jako odpowiadającego na tego rodzaju pytania, i mówi ci, że wnioskuje, a nie
|
||
raportuje.
|
||
|
||
### Nauka z wiki
|
||
|
||
**Szybki test tego, co wiesz** — powiedz:
|
||
|
||
> „Quiz me on the onboarding process.”
|
||
|
||
Agent zapyta o liczbę pytań i format (otwarte / jednokrotnego wyboru), a
|
||
następnie przeprowadzi cię przez nie jedno po drugim, z natychmiastową
|
||
informacją zwrotną i bieżącym wynikiem. Potem nic nie zostaje zapisane — to
|
||
jednorazowy sprawdzian. `.agents/skills/ckb-quiz/SKILL.md`.
|
||
|
||
**Prawdziwy kurs, rozłożony w czasie** — powiedz:
|
||
|
||
> „Teach me the wiki.” / „Teach me about the supplier onboarding process.”
|
||
|
||
Pierwsze wywołanie planuje program nauczania: pyta, czy chcesz jedną
|
||
sesję czy serię, jak długa ma być każda sesja i jak często, oraz czy
|
||
potrzebny jest plik kalendarza `.ics` z przypomnieniami. Następnie dzieli
|
||
materiał na porcje wielkości sesji (raczej jedna krótka sesja więcej niż
|
||
upychanie materiału) i pokazuje ci plan, zanim cokolwiek zapisze. Później
|
||
powiedzenie „next lesson” (lub podobnie) wznawia naukę od miejsca, w którym
|
||
się zatrzymała, ucząc za każdym razem inną techniką — pytania sokratejskie,
|
||
analogie, przykłady rozwiązane krok po kroku, „naucz mnie z powrotem”,
|
||
mnemotechniki — i krótko sprawdzając, co zostało w pamięci, zanim przejdzie
|
||
dalej, powtarzając to, co niepewne. Plany i postępy żyją w
|
||
`outputs/teaching/<topic>/`. `.agents/skills/ckb-teach-me/SKILL.md`.
|
||
|
||
**Prowadzona kolejność czytania bez pełnego kursu** — powiedz:
|
||
|
||
> „Onboard me on the payments integration.” / „Where do I start with X?”
|
||
|
||
Dostajesz krótki przegląd plus uporządkowaną listę do przeczytania —
|
||
najpierw podstawy, potem sam temat, potem to, co się na nim opiera —
|
||
zbudowaną przez przejście po grafie wiedzy na zewnątrz. Tylko do odczytu;
|
||
nic nie jest zapisywane. `.agents/skills/ckb-onboard-me/SKILL.md`.
|
||
|
||
**Sprawdź, co ty albo wiki zbywacie ogólnikami** — powiedz:
|
||
|
||
> „Feynman me on the Atlas retry policy.” / „Czego nie rozumiem?”
|
||
|
||
Agent czyta stronę i jej źródła, wyjaśnia ją prostymi słowami na jednym
|
||
konkretnym przykładzie i pod każdym fragmentem podaje link do sekcji, z
|
||
której pochodzi. Potem wypisuje każde miejsce, w którym wyjaśnienie się
|
||
rozrzedziło: strona jest mglista (napraw lintem albo ingestem), źródła tego
|
||
nie omawiały (potrzebne nowe źródło) albo sam agent nie umiał tego uprościć.
|
||
Nie łata luk własną wiedzą. Na koniec prosi, żebyś sam wyjaśnił jeden
|
||
fragment, żeby wyszły też twoje luki, i kończy ponumerowanymi kolejnymi
|
||
krokami. Bez tematu proponuje strony robocze, oparte na jednym źródle albo
|
||
nieaktualne. Sesje są zapisywane w `outputs/teaching/feynman/`; w `wiki/`
|
||
nic się nie zmienia, chyba że zgodzisz się zapisać lukę w
|
||
`wiki/query-gaps.md`. `.agents/skills/ckb-feynman/SKILL.md`.
|
||
|
||
### Generowanie dokumentów / dzielenie się wiedzą poza wiki
|
||
|
||
**Szybki skrót najwyższego poziomu** — powiedz:
|
||
|
||
> „Give me a project summary.” / „Where do things stand?”
|
||
|
||
Regeneruje `PROJECT-OVERVIEW.md` w katalogu głównym repozytorium: jedno-
|
||
lub dwustronicowy przegląd, bieżący stan, otwarte działania ze statusem,
|
||
ryzyka i założenia — w całości zsyntetyzowane z aktualnej wiki. Jest za
|
||
każdym razem nadpisywany w całości, więc zawsze odzwierciedla to, co wiki
|
||
mówi *teraz*. `.agents/skills/ckb-project-summary/SKILL.md`.
|
||
|
||
**Eksport maszynowy dla innych narzędzi** — powiedz:
|
||
|
||
> „Export the wiki as OKF.”
|
||
|
||
Tworzy pakiet [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
|
||
w `outputs/okf/`, możliwy do skonsumowania przez ogólne narzędzia OKF (np.
|
||
wizualizator grafu), bez potrzeby rozumienia bogatszego, własnego schematu
|
||
tej wiki. `.agents/skills/ckb-export-okf/SKILL.md`.
|
||
|
||
**Czytelna dla człowieka strona dokumentacji** — powiedz:
|
||
|
||
> „Export the wiki to Starlight.” / „Build a docs site from the wiki.”
|
||
|
||
Tworzy gotową do uruchomienia stronę Astro + Starlight w
|
||
`outputs/starlight/` — prawdziwe strony, prawdziwą nawigację, coś, co
|
||
możesz hostować i dać komuś, kto nigdy nie widział wiki.
|
||
`.agents/skills/ckb-export-starlight/SKILL.md`.
|
||
|
||
**Dokument, który piszesz regularnie, z szablonu** — powiedz:
|
||
|
||
> „Prepare a new document using template status-report.” / „New status
|
||
> report from the template, for Atlas, last two weeks.”
|
||
|
||
Szablony leżą w `templates/`, każdy w jednym pliku Markdown. Nagłówki
|
||
nadają dokumentowi kształt, a komentarz HTML pod każdym nagłówkiem mówi
|
||
agentowi, co ma tam trafić: „zapytaj użytkownika”, „weź to ze strony
|
||
projektu w wiki”, „trzy zdania, bez punktów”. Agent czyta szablon, zadaje
|
||
ci wszystkie pytania naraz, resztę bierze z wiki i zapisuje gotowy dokument
|
||
w `outputs/documents/`. Czego nie znalazł, zostawia w pliku jako linię
|
||
`TODO:`, nigdy nie zmyśla. W zestawie jest jeden przykład,
|
||
`templates/status-report.md`, a `templates/README.md` opisuje format na
|
||
jednej stronie. Powiedz „make a template for a handover note”, a agent
|
||
przygotuje szkic szablonu do twojej edycji.
|
||
`.agents/skills/ckb-document/SKILL.md`.
|
||
|
||
**Dokument Word, prezentacja lub PDF z zawartości wiki** — nie ma
|
||
dedykowanego skilla do tego, ale to normalna prośba:
|
||
|
||
> „Turn the wiki page on our pricing model into a one-page Word doc I can
|
||
> send to legal.”
|
||
|
||
Agent czyta odpowiednie strony wiki i używa swoich ogólnych umiejętności
|
||
tworzenia dokumentów (`docx`, `pptx`, `pdf`), aby wytworzyć plik — wiki
|
||
pozostaje źródłem prawdy, dokument jest jednorazowym, pochodnym
|
||
artefaktem.
|
||
|
||
### Dodawanie informacji
|
||
|
||
W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał do
|
||
`raw/inbox/` i powiedz „Ingest”, albo powiedz agentowi w
|
||
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
|
||
|
||
### Twój profil i lekcje
|
||
|
||
Powiedz „set up my profile”, a agent zada do trzech pytań: o twoją rolę, o to,
|
||
jak ma z tobą pracować, i o to, czego zawsze lub nigdy nie robić. Odpowiedzi
|
||
trafiają do `workload/profiles/<twoje-imię>.md`. Od tej pory każda sesja, którą
|
||
zaczynasz, wypisuje twój profil w podsumowaniu agenta. Profile innych osób nie
|
||
są dla ciebie wczytywane. Plik jest commitowany, więc trzymaj w nim tylko
|
||
preferencje robocze, którymi podzieliłbyś się z zespołem.
|
||
|
||
Twoje preferencje nigdy nie są ważniejsze od zasad KB. Najpierw `AGENTS.md`,
|
||
potem `## Rules` projektu, a resztę uzupełnia twój profil.
|
||
|
||
Gdy agent się pomyli, możesz utrwalić poprawkę: „remember this: always cite
|
||
the runbook for retry numbers” albo „lesson: …”. Agent pyta, czy lekcja jest
|
||
twoja, czy dla wszystkich:
|
||
|
||
- **Twoja** trafia do twojego profilu.
|
||
- **Dla wszystkich** trafia do `wiki/lessons.md` i czeka na przegląd drugiej
|
||
osoby. Najbliższa sesja każdej innej osoby wymieni ją jako nową.
|
||
|
||
Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze
|
||
obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go
|
||
edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||
|
||
### Zapisywanie rozmowy
|
||
|
||
Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie
|
||
twojej pierwszej wiadomości (albo ten, który w niej podasz: „title: …”).
|
||
Nikt cię nie pyta; pierwsza odpowiedź zaczyna się od jednej
|
||
linijki z tytułem i przypomnieniem, że „rename this conversation to X” go
|
||
zmienia. Tytuł nadaje nazwę zapisanemu transkryptowi i blokowi sesji w
|
||
`workload/`. Jeśli ta linijka ci przeszkadza, powiedz „stop telling me the
|
||
title” — agent przestawi `announce_title: false` w bloku `conversations:`
|
||
w `ckb.yaml`; tytuł nadal jest ustawiany, tylko nie jest ogłaszany.
|
||
|
||
Powiedz „save this conversation”, a agent skopiuje transkrypt sesji do
|
||
`raw/saved-conversations/<RRRR-MM-DD>/` — oryginalny plik JSONL, który
|
||
przechowuje Claude Code, bajt w bajt, plus czytelną wersję `.md` tej samej
|
||
wymiany zdań (twoje wiadomości i odpowiedzi agenta dosłownie, wywołania
|
||
narzędzi jako jednolinijkowe notatki, wyniki narzędzi skrócone, prywatne
|
||
rozumowanie agenta pominięte). `raw/saved-conversations/index.md` wymienia
|
||
wszystko, co zapisano. Wcześniejsze sesje tego samego projektu też można
|
||
zapisać: poproś, a agent wyświetli listę do wyboru.
|
||
|
||
Zapisane rozmowy są celowo **poza** wiki. Na pytania agent nadal odpowiada
|
||
wyłącznie z `wiki/`, `linked/` i `libs/` — transkrypt sam z siebie nigdy
|
||
nie staje się dowodem. Możesz natomiast pytać o same rozmowy: „czy
|
||
rozmawialiśmy o przełączeniu rozliczeń”, „co mówiliśmy o nazewnictwie w
|
||
zeszłym tygodniu”, „jaka była moja prośba w sprawie eksportu”. Agent przeszukuje
|
||
zapisane pliki `.md` i cytuje dokładną wymianę zdań wraz z datą.
|
||
|
||
Jeśli wolisz, żeby agent nie pytał, powiedz „save conversations automatically”:
|
||
agent przestawi `autosave: true` w bloku `conversations:` w `ckb.yaml` i od
|
||
tej pory każda sesja jest zapisywana na końcu bez pytania. „Turn off
|
||
autosave” przestawia z powrotem. Przełącznik jest commitowany z
|
||
repozytorium, więc dotyczy wszystkich pracujących w tej KB. Ponieważ jest to
|
||
reguła, którą agent wykonuje na końcu sesji, sesja przerwana w połowie tury
|
||
zostałaby pominięta — dlatego funkcja ma też połowę per maszyna: hook
|
||
`Stop` Claude Code w `.claude/settings.local.json` (ignorowanym przez gita),
|
||
który ponownie zapisuje transkrypt po każdej turze. Agent nigdy nie
|
||
instaluje go samodzielnie. Przy włączonym autozapisie kontrola na starcie
|
||
sesji zauważa maszynę, na której hooka brakuje (albo taką, na której
|
||
autozapis wyłączono, a hook wciąż jest), i pyta raz, czy zmienić
|
||
konfigurację tej maszyny; zmianę wprowadza tylko po twojej zgodzie. Każda
|
||
maszyna otwierająca repozytorium zostaje zapytana raz.
|
||
|
||
Jeśli rozmowa zawiera wiedzę, która należy do wiki, skopiuj jej `.md` do
|
||
`raw/inbox/` i powiedz „Ingest” — kopię robisz ty, więc nic nie trafia do
|
||
wiki bez twojego wyboru. Pamiętaj, że transkrypt jest dosłowny: zawiera
|
||
wszystko, co agent wypisał w trakcie sesji (zawartość plików, wyniki
|
||
poleceń), i staje się śledzonym plikiem w repozytorium.
|
||
Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
|
||
|
||
### Indeksowanie zewnętrznego źródła
|
||
|
||
Powiedz:
|
||
|
||
> „Index external sources.” (lub „index libs”, „refresh the external
|
||
> index”)
|
||
|
||
To przeszukuje każdy `libs/<name>/`, który ma `source.yaml` (zobacz
|
||
[§1](#budowanie-na-bazie-cudzej-wiki)), i buduje krótki indeks tego, co
|
||
znajdzie — po jednym wpisie na dokument, plus stronę przeglądową — w
|
||
całości wewnątrz tego samego folderu `libs/<name>/`. Niczego pod `wiki/`
|
||
nie dotyka.
|
||
|
||
Przykład:
|
||
|
||
> *Tworzysz `libs/finance-reports/source.yaml`:*
|
||
> ```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
|
||
> ```
|
||
> *potem mówisz „Index external sources.”*
|
||
>
|
||
> Agent łączy się, korzystając z tego, co jest dostępne w danej sesji (w
|
||
> tym przypadku podłączonego narzędzia Microsoft 365), listuje dokumenty w
|
||
> tym folderze, czyta wystarczająco dużo z każdego, aby napisać krótkie
|
||
> podsumowanie, i tworzy `libs/finance-reports/index.md` (przegląd źródła)
|
||
> plus jedną stronę na dokument w `libs/finance-reports/entities/`,
|
||
> połączone krzyżowo przez `libs/finance-reports/graph/edges.json`. Loguje
|
||
> wszystko w `libs/finance-reports/log.md`, dzienniku odrębnym od
|
||
> `wiki/log.md`, ponieważ ten indeks jest ograniczony do jednego
|
||
> konektora, a nie wmieszany w twoją główną wiki. Na koniec przypomina o
|
||
> przejrzeniu wyniku i powiedzeniu „sync changes”, gdy wynik będzie ci
|
||
> odpowiadał.
|
||
|
||
Jeśli konektor wymaga autoryzacji (np. połączenie z SharePoint lub Google
|
||
Drive, które nie jest jeszcze skonfigurowane), agent mówi, który to i gdzie
|
||
go autoryzować, a potem kontynuuje z innymi skonfigurowanymi źródłami,
|
||
zamiast zatrzymywać cały przebieg. Uruchom „index external sources”
|
||
ponownie w każdej chwili, gdy źródło się zmieni — odświeża istniejące
|
||
wpisy w miejscu, zamiast je duplikować, i nigdy nie usuwa strony dla
|
||
dokumentu, który zniknął ze źródła (zamiast tego oflagowuje ją, żeby
|
||
kolejny przebieg „Lint” zarchiwizował ją naturalnie).
|
||
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
|
||
|
||
**Kto może go budować i gdzie jest współdzielony.** Domyślnie nikt nie ma
|
||
dostępu do zapisu w źródle typu konektor, dopóki tego nie zadeklaruje — to
|
||
chroni zespół dziesięciu osób przed redundantnym skanowaniem tego samego
|
||
folderu SharePoint. Powiedz:
|
||
|
||
> „Make me the admin for finance-reports.”
|
||
|
||
To zapisuje osobisty `libs/finance-reports/source.local.yaml` z
|
||
`access: write` — nigdy niecommitowany, nigdy niewidoczny dla
|
||
współpracowników. Każdy bez tego pliku jest tylko-do-odczytu dla tego
|
||
źródła: jeśli powie „index external sources”, agent w jego imieniu w
|
||
ogóle nie dotknie żywego konektora. Zgłosi, co już
|
||
zaindeksowano (albo powie wprost, że nic jeszcze nie zaindeksowano i kogo
|
||
o to zapytać).
|
||
|
||
Jeśli zespół finansowy chce, żeby wszyscy czytali *ten sam* indeks, a nie
|
||
każdy utrzymywał własną lokalną kopię w swojej własnej KB, administrator
|
||
dodaje blok `index:` do współdzielonego `source.yaml`:
|
||
|
||
```yaml
|
||
index:
|
||
store: git
|
||
location: "https://github.com/finance-team/index-cache.git"
|
||
# ref: main — opcjonalnie: przypina branch, tag albo podścieżkę w tym miejscu
|
||
```
|
||
|
||
Za pierwszym razem, gdy ktokolwiek uruchomi „index external sources” po
|
||
dodaniu tego bloku, `https://github.com/finance-team/index-cache.git` jest
|
||
puste. To oczekiwane, nie błąd. Każde uruchomienie sprawdza je najpierw:
|
||
użytkownicy tylko-do-odczytu zobaczą „nic jeszcze nie opublikowano, zapytaj
|
||
administratora”, a uruchomienie administratora je tworzy, bo uruchomienie
|
||
z dostępem do zapisu zawsze przebudowuje indeks z żywego konektora i
|
||
wypycha wynik do tej lokalizacji, niezależnie od tego, czy coś tam
|
||
wcześniej było. Od tego momentu, kiedy *ktokolwiek* powie „index external
|
||
sources”, agent najpierw pobiera to, co już zostało opublikowane.
|
||
Użytkownicy tylko-do-odczytu na tym kończą; administrator dodatkowo
|
||
przebudowuje indeks z żywego konektora i wypycha odświeżoną wersję do tej
|
||
samej lokalizacji, żeby kolejne pobranie innej osoby ją uwzględniło. Pomiń
|
||
blok `index:` (najprostsza konfiguracja, właściwy domyślny wybór dla
|
||
jednego małego zespołu), a indeks leży bezpośrednio wewnątrz
|
||
`libs/finance-reports/` we własnym repozytorium tej KB, współdzielony w
|
||
normalny sposób przez „sync changes”, dokładnie jak w prostym przykładzie
|
||
powyżej.
|
||
|
||
### Dodawanie opcjonalnego modułu
|
||
|
||
Niektóre możliwości mają sens tylko w części baz wiedzy, dlatego są
|
||
dostarczane jako **moduły** w `.agents/modules/`: obecne w każdej kopii,
|
||
nieaktywne, dopóki ich nie zainstalujesz. Powiedz:
|
||
|
||
- **„What modules are available”**: lista modułów z informacją, czy są
|
||
zainstalowane.
|
||
- **„Install the \<name\> module”**: sprawdza, czego moduł potrzebuje, mówi
|
||
ci o tym przed jakimkolwiek zapisem, a potem dodaje jego skille, foldery i
|
||
ustawienia. Instalacja jest zapisana w `ckb.yaml`.
|
||
- **„Uninstall the \<name\> module”**: usuwa jego skille i ustawienia. Twoja
|
||
treść zostaje: strony wiki, które utworzył, klony w `src/`, specyfikacje.
|
||
|
||
| Moduł | Do czego służy | Przewodnik |
|
||
|---|---|---|
|
||
| `software` | Baza dokumentuje tworzone oprogramowanie: repozytoria jako ignorowane klony w `src/`, kod mapowany na encje wiki, specyfikacje z OpenSpec | [OPENSPEC.pl.md](OPENSPEC.pl.md) · [README modułu](../.agents/modules/software/README.pl.md) |
|
||
| `capture` | Zapisywanie linków, artykułów, PDF-ów i transkrypcji filmów w `raw/inbox/` jako datowanych zrzutów, z Wayback w razie niepowodzenia i sprawdzaniem duplikatów | [README modułu](../.agents/modules/capture/README.pl.md) |
|
||
| `share` | Wysyłanie dokumentu do innej bazy przez wspólne repozytorium git (jedna skrzynka na bazę, tylko dopisywanie) i odbieranie tego, co wysłały inne bazy, do `raw/inbox/` — z wersjami, wycofaniami i sprawdzeniem nadawcy | [README modułu](../.agents/modules/share/README.md) |
|
||
| `voice` | Wszystko, co baza wysyła na zewnątrz (zachowane odpowiedzi, dokumenty, raporty, przegląd projektu), pisane głosem zespołu według profilu trzymanego jako strona wiki w `wiki/voice/`. Zmieniają się sformułowania; fakty, cytaty, źródła i kod — nie | [README modułu](../.agents/modules/voice/README.md) |
|
||
| `convert` | Zamiana dowolnego pliku Markdown (dokumentu z szablonu, zachowanej odpowiedzi, raportu) na Word, ODT, PDF lub HTML przez pandoca, w stylu firmowym trzymanym w `templates/styles/`: wystarczy go opisać („Georgia 11pt, granatowe nagłówki, A4”) albo przynieść firmowy szablon Worda | [README modułu](../.agents/modules/convert/README.pl.md) |
|
||
| `mcp` | Korzystanie z bazy w aplikacjach Claude (web/desktop/mobile), Claude Code lub innym agencie przez serwer MCP: wyszukiwanie, odczyt, dodawanie materiału, cofanie źle skierowanego zgłoszenia. Można podłączyć kilka baz naraz | [MCP.pl.md](MCP.pl.md) · [README modułu](../.agents/modules/mcp/README.pl.md) |
|
||
|
||
Skill: `.agents/skills/ckb-module/SKILL.md`.
|
||
|
||
### Praca z agentem innym niż Claude Code
|
||
|
||
KB to zwykłe pliki i `AGENTS.md`, więc może w niej pracować każdy agent, który
|
||
czyta `AGENTS.md`. **Żadna z poniższych konfiguracji nie została jeszcze
|
||
przetestowana**; każda opisuje to, co podaje dokumentacja narzędzia. Jeśli
|
||
którąś potwierdzisz lub poprawisz, zamień „nieprzetestowane” na datę i wersję
|
||
narzędzia.
|
||
|
||
| Agent | Konfiguracja (nieprzetestowana) |
|
||
|---|---|
|
||
| **Codex CLI** | Sam czyta `AGENTS.md` w katalogu głównym repo; uruchom go w folderze KB. Nie wczytuje `.agents/skills/` jako skilli, więc idzie za tabelą routingu i otwiera każdy `SKILL.md`, tak jak każe `AGENTS.md`. |
|
||
| **Cursor** | Czyta `AGENTS.md` w katalogu głównym repo jako regułę projektu. Jeśli twoja wersja tego nie robi, dodaj `.cursor/rules/ckb.mdc`, który każe mu najpierw przeczytać `AGENTS.md`. |
|
||
| **OpenCode** | Czyta `AGENTS.md` w katalogu głównym repo. Skille działają jak w Codex. |
|
||
| **Gemini CLI** | Domyślnie szuka `GEMINI.md`. Wskaż mu `AGENTS.md` przez `{"contextFileName": "AGENTS.md"}` w `.gemini/settings.json` albo zrób z `GEMINI.md` dowiązanie do `AGENTS.md`, tak jak `CLAUDE.md`. |
|
||
|
||
Co dziś robi tylko Claude Code:
|
||
|
||
| Funkcja | Gdzie indziej |
|
||
|---|---|
|
||
| Automatyczne wykrywanie skilli (`.claude/skills` → `.agents/skills`) | Agent czyta pliki `SKILL.md`, gdy `AGENTS.md` go tam kieruje |
|
||
| Hook startu sesji (`start_hook.py`) | Reguła E uruchamiana ręcznie, jak zawsze |
|
||
| Hook autozapisu rozmów i w ogóle zapisywanie rozmów (`ckb-add-conversation` czyta transkrypty Claude Code) | Niedostępne; notatki zapisuj w `workload/` |
|
||
| Tytuły sesji zapisywane dla transkryptów | Niedostępne |
|
||
|
||
Cała reszta (skrypty Pythona, lint, wyszukiwanie, serwer MCP, moduły) działa
|
||
tak samo z każdym agentem.
|
||
|
||
**Zasady dla folderów.** Niektórzy agenci czytają zagnieżdżony `AGENTS.md`,
|
||
gdzie wygrywa ten najbliżej edytowanego pliku. Ten szablon żadnego nie
|
||
dostarcza. Zasady dla jednego projektu zapisuj w sekcji `## Rules` jego strony
|
||
zakresu, którą czyta każdy agent, bo jest częścią wiki.
|
||
|
||
---
|
||
|
||
## 7. Co jest generowane przez agenta, a co możesz edytować
|
||
|
||
Krótka wersja: **lokalna `wiki/` zawsze wygrywa** w kaskadzie, co oznacza,
|
||
że to *twoja* wiki — nic nie blokuje ci jej bezpośredniej edycji. „Zarządzane przez agenta” poniżej oznacza, że agent traktuje się
|
||
jako odpowiedzialnego za utrzymanie tej treści *strukturalnie* poprawną
|
||
(frontmatter, indeks, dziennik, graf) — a nie że nie wolno ci jej dotykać.
|
||
Jeśli ręcznie edytujesz stronę wiki, dobrą praktyką jest uruchomienie
|
||
potem „Lint”, żeby indeks/dziennik/graf pozostały spójne z wprowadzonymi
|
||
zmianami.
|
||
|
||
Jest jeden wyjątek działający w drugą stronę. Na każdej stronie, którą agent
|
||
*regeneruje* — indeks konektora, mapa kodu — wszystko, co napiszesz, zwykle
|
||
ginie przy następnej przebudowie. Dlatego każda taka strona kończy się sekcją
|
||
`## Notes`, której żaden skill nigdy nie tknie:
|
||
|
||
```markdown
|
||
## Notes
|
||
|
||
<!-- Twoje. Żaden skill tego nie nadpisuje. -->
|
||
```
|
||
|
||
Pisz tam, co chcesz — że ten dokument jest nieaktualny, że osoba w nim
|
||
wymieniona już nie pracuje, kogo naprawdę zapytać. Treść jest przenoszona
|
||
przez przebudowy co do bajtu. Wszystko, co napiszesz *powyżej* tego nagłówka
|
||
na stronie generowanej, zostanie nadpisane.
|
||
|
||
| Lokalizacja | Kto zwykle to zapisuje | Uwagi |
|
||
|---|---|---|
|
||
| `raw/inbox/`, luźne pliki w `raw/` | **Tylko ty** | Agent tylko czyta, archiwizuje i przenosi rzeczy tutaj — nigdy nie tworzy treści w `raw/` sam. |
|
||
| `raw/archive/<data>/` | Agent | Automatycznie zarchiwizowana kopia tego, co trafiło do `raw/inbox/`, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne. |
|
||
| `linked/<name>/` | **Ty** (tworzysz dowiązanie symboliczne) | Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane *w tamtym repozytorium* — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz `linked/`. |
|
||
| `libs/<name>/` (kopia git, bez `source.yaml`) | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz niej. |
|
||
| `libs/<name>/source.yaml` (konektor) | **Tylko ty** | Deklaruje konektor, lokalizację, opcjonalnie jak często ma być odświeżany (`refresh_interval_days:`) i opcjonalnie gdzie znajduje się współdzielony/wcześniej zbudowany indeks (`index:`). Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
|
||
| `libs/<name>/source.local.yaml` (konektor) | **Ty** (albo agent, tylko gdy wyraźnie poprosisz o zostanie/przestanie bycia administratorem tego źródła) | Osobiste, per-komputer ustawienie `access: write`/`read` — nigdy niecommitowane, nigdy niewidoczne dla innych. Brak = tylko do odczytu, domyślnie. |
|
||
| `libs/<name>/{index.md,entities/,graph/,log.md}` (konektor) | Generowane przez agenta, **możesz swobodnie edytować** | Własny indeks agenta dla tego jednego źródła konektora, budowany/odświeżany przez „Index external sources” — ale tylko jeśli masz lokalnie `access: write`; użytkownicy tylko-do-odczytu dostają pobraną kopię. Strukturalnie ta sama zasada jak przy wierszu `wiki/` poniżej — śmiało popraw wpis ręcznie, a potem uruchom „Lint” (teraz sprawdza też indeksy oparte na konektorach, respektując ten sam podział odczyt/zapis). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w `wiki/`. **Przebudowę przetrwa tylko `## Notes`** — trzymaj tam wszystko, co chcesz zachować. |
|
||
| `wiki/decisions/` | Generowane przez agenta, **edytuj ostrożnie** | Mechanicznie tak samo jak reszta `wiki/`, ale te strony są z założenia tylko do dopisywania: popraw swobodnie literówkę czy źle przypisane nazwisko, ale nie przepisuj kontekstu ani uzasadnienia decyzji pod późniejszy pogląd — zapisz zamiast tego decyzję zastępującą, żeby historia przetrwała. |
|
||
| `wiki/` (strony, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Generowane przez agenta, **możesz swobodnie edytować** | To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj `last_updated`) i uruchom potem Lint, jeśli zmiana dotyczy czegoś, do czego odwołuje się indeks/graf/dziennik. |
|
||
| `outputs/okf/`, `outputs/starlight/` | Agent, **w pełni regenerowane** | Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie. |
|
||
| `outputs/teaching/<topic>/` | Agent, stan półtrwały | `plan.md`/`progress.md`, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki. |
|
||
| `outputs/teaching/feynman/` | Agent (jeden plik na sesję), **możesz edytować** | Sesje Feynmana: wyjaśnienie, znalezione luki, twoje wyjaśnienie z powrotem i odciski stron, które agent przeczytał. Ignorowane przez gita jak reszta `outputs/teaching/`; kolejna sesja nigdy ich nie nadpisuje. |
|
||
| `PROJECT-OVERVIEW.md` (katalog główny) | Agent, **w pełni regenerowany** | Nadpisywany w całości za każdym razem, gdy poprosisz o podsumowanie projektu. Nie edytuj go ręcznie — edytuj strony wiki, z których jest syntetyzowany, a potem zregeneruj. |
|
||
| `ABOUT.md`, `ABOUT.pl.md` | **Ty** | Ten sam plik po angielsku i po polsku: wypełnij ten w języku swojej bazy, drugi możesz usunąć (jeśli oba są wypełnione, przy rozbieżności wygrywa `ABOUT.md`). Do czego służy ta KB: cel, odbiorcy, zakres, właściciele, poufność, język stron. README do niego linkuje. Agent go czyta, przy ingeście sprawdza nowy materiał względem zakresu i nigdy go nie edytuje bez twojej prośby; aktualizacje i reset go nie ruszają. `wiki/overview.md` to podsumowanie agenta tego, co KB faktycznie zawiera. |
|
||
| `templates/` | **Ty** | Szablony dokumentów: nagłówki plus komentarz pod każdą sekcją mówiący, co ma tam trafić i skąd. Agent je czyta, a nowy zapisuje tylko na twoją prośbę. Nic nie regeneruje ani nie resetuje tego katalogu. Zacznij od `templates/status-report.md`. |
|
||
| `outputs/documents/` | Agent (jeden plik na prośbę), **możesz edytować** | Dokumenty przygotowane z szablonu. Śledzone w gicie i nigdy nie nadpisywane przez kolejne uruchomienie (powtórzona nazwa dostaje `-2`, `-3`). Edytuj je swobodnie; frontmatter zapisuje, z jakiego szablonu i z jakich stron wiki powstały. |
|
||
| `workload/YYYY-MM-DD_<autor>_summary.md` | Agent (dopisywane co sesję) | Bieżący dziennik tego, co działo się każdego dnia, jeden plik na osobę, więc współdzielone repozytorium zapisuje, kto co zrobił, i nigdy nie konfliktuje w tym miejscu. Autor to tożsamość gita sesji. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu. |
|
||
| `workload/ingest-reports/` | Agent (jeden plik na ingest) | Co zmienił każdy ingest: przyjęte pliki z `raw/` i miejsce ich archiwizacji, zapisane decyzje, utworzone lub zaktualizowane encje i inne strony, krawędzie grafu oraz to, co nowy materiał potwierdził, rozszerzył lub z czym był sprzeczny. Zapisywany raz i nigdy nie przepisywany — przeczytaj go, aby przejrzeć ingest bez odtwarzania go z logu i diffa. |
|
||
| `AGENTS.md` / `CLAUDE.md` | **Ty** (rzadko) | To prompt systemowy, który definiuje zachowanie agenta w tym repozytorium. Edytuj go, jeśli chcesz zmienić globalną zasadę — np. schemat frontmatteru, format logowania czy kontrakt katalogów. Zmiany obowiązują od kolejnej sesji. |
|
||
| `.agents/skills/*/SKILL.md` | **Ty** (zaawansowane/opcjonalne) | Każdy plik definiuje jedną możliwość na żądanie. Możesz tworzyć nowe albo edytować istniejące, wzorując się na tych, które już tu są — to nie jest wymagane do normalnego użytku, ale nic ci w tym nie przeszkadza. |
|
||
| `LICENSE`, `VERSION`, `README*`, `docs/`, `ckb.yaml` | Agent, **możesz edytować** | Część tej samej warstwy szablonu co `AGENTS.md` — utrzymywane w synchronizacji przez `ckb-upgrade`, gdy zaakceptujesz aktualizację szablonu. `ckb-upgrade` zawsze zapyta, zanim dotknie linii praw autorskich w `LICENSE` albo któregokolwiek z tych plików, jeśli twoja lokalna kopia różni się od szablonu — dostosowanie tutaj (np. własna nazwa projektu czy posiadacz licencji) jest oczekiwana, nie jest błędem. |
|
||
|
||
---
|
||
|
||
### Gdzie leżą własne decyzje szablonu
|
||
|
||
`docs/decisions/` przechowuje zapisy projektowe szablonu (D-0001, D-0002…) w
|
||
tym samym formacie co `wiki/decisions/`, ale jako część warstwy szablonu:
|
||
skille i dokumentacja się na nie powołują, więc muszą przetrwać `ckb-reset` i
|
||
podróżować z `ckb-upgrade`. Decyzje twojej KB nadal trafiają do
|
||
`wiki/decisions/` przez „record a decision” — nigdy tutaj.
|
||
|
||
### Sprawdzanie wydania szablonu
|
||
|
||
`tests/smoke.sh` uruchamia deterministyczne skrypty (`lint_report.py`,
|
||
`retrieve_candidates.py`, `save_conversation.py`) na fixture'ach w
|
||
`tests/fixtures/` i porównuje wynik z `tests/expected/`. Uruchom go przed
|
||
scaleniem czegokolwiek do `test` lub `main`; z `--update` po zamierzonej
|
||
zmianie wyjścia skryptów. Folder `tests/` istnieje tylko w repo szablonu:
|
||
`ckb-init` go nie kopiuje, a `ckb-upgrade` go nie dostarcza, więc baza
|
||
wiedzy nigdy go nie zawiera.
|
||
|
||
`tests/bench_retrieval.py` mierzy wyszukiwanie (hit@1 i hit@3 na 20
|
||
pytaniach). `tests/run_evals.py` sprawdza, co przebieg agenta zostawił po sobie
|
||
dla każdego przypadku w `tests/evals/`: `prepare` tworzy roboczą KB, agent
|
||
dostaje tam polecenie przypadku, potem `check`. Test dymny sprawdza poprawność
|
||
przypadków, ale nie uruchamia agenta; przypadki uruchom ręcznie przed
|
||
wydaniem.
|
||
|
||
## 8. Szybki przegląd
|
||
|
||
| Powiedz... | Co się dzieje | Skill |
|
||
|---|---|---|
|
||
| „Set up a new wiki like this one in \<folder\>” | Zakłada świeżą, pustą KB z tym schematem | `ckb-init` |
|
||
| „Pull the ckb repo into \<folder\> and set up the wiki” | Klonuje repozytorium szablonu do katalogu roboczego, a potem zakłada z niego pustą KB | `ckb-init` |
|
||
| „Ingest” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
|
||
| „Zapisz decyzję: ...” / „zdecydowaliśmy ...” | Zapisuje numerowany rekord decyzji pod `wiki/decisions/` | `ckb-decide` |
|
||
| „Co zdecydowaliśmy w sprawie X” / „kto zdecydował X” / „co jest otwarte” | Odpowiada z zapisów decyzji, z autorem, datą i statusem | `ckb-decide` |
|
||
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
|
||
| „Zresetuj wiki” / „Zrób z tego czysty szablon” | **Destrukcyjne.** Usuwa zgromadzoną wiedzę i odtwarza pusty szkielet, po inwentarzu i potwierdzeniu wpisaną frazą | `ckb-reset` |
|
||
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
|
||
| „Save this conversation” | Kopiuje transkrypt sesji (JSONL + czytelne `.md`) do `raw/saved-conversations/<data>/`; poza wyszukiwaniem | `ckb-add-conversation` |
|
||
| „Did we discuss X” / „What did I tell you about X” | Przeszukuje zapisane rozmowy i cytuje wymianę zdań | `ckb-add-conversation` |
|
||
| „Save conversations automatically” / „Turn off autosave” | Przestawia `conversations.autosave` w `ckb.yaml`; po włączeniu każda sesja jest zapisywana na końcu bez pytania | `ckb-add-conversation` |
|
||
| „Rename this conversation to X” / „Stop telling me the title” | Ustawia tytuł sesji (używany przez zapisany transkrypt i notatkę workload) / przestawia `conversations.announce_title` | `ckb-add-conversation` |
|
||
| „Retract X” / „Undo the ingest of X” / „This went to the wrong KB” | Pokazuje, co zbudowało źródło (strony, twierdzenia, krawędzie), a po twojej zgodzie usuwa dokładnie to; obsługuje prośby z `raw/retractions/` | `ckb-retract` |
|
||
| „Consolidate” / „Build the topic summaries” | Zapisuje raport samych propozycji / buduje zaakceptowane strony `wiki/topics/` | `ckb-consolidate` |
|
||
| „Set up my profile” / „Remember this: …” / „Lesson: …” | Zapisuje twój profil albo lekcję osobistą lub dla całej KB | `ckb-profile` |
|
||
| „What needs review?” / „Mark X as reviewed” | Wypisuje strony draft i needs_update / zapisuje twój przegląd wskazanych stron | `ckb-lint` |
|
||
| „Keep this answer” | Zapisuje ostatnią odpowiedź w `outputs/answers/` razem ze źródłami i lukami | `ckb-retrieve` |
|
||
| „Ingest in batch” / „Ingest, no check-in” | Ingestuje bez zatrzymywania się, by najpierw pokazać, jak rozumie każde źródło | `ckb-ingest` |
|
||
| „Turn on the session-start hook” / „Show the context budget” | Ustawia `session.start_hook` w `ckb.yaml` i instaluje hook na tej maszynie / pokazuje szacunek tokenów warstwy ładowanej zawsze | `ckb-lint` |
|
||
| „Lint every week” / „Index external sources every 30 days, ask me first” | Dodaje rutynę do `ckb.yaml`; zaległe rutyny wykonują się na starcie sesji, po twojej prośbie | `ckb-routine` |
|
||
| „List routines” / „Which routines are due” / „Remove the weekly lint” | Pokazuje, sprawdza lub usuwa rutyny | `ckb-routine` |
|
||
| „What modules are available” / „Install the mcp module” | Pokazuje lub instaluje opcjonalny moduł; nic w nim nie działa przed instalacją | `ckb-module` |
|
||
| „Deploy the MCP server” / „Connect the KB to Claude web” | Prowadzi przez udostępnienie bazy przez serwer MCP i dodanie jej jako konektora (moduł mcp) | `ckb-mcp` |
|
||
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `ckb-quiz` |
|
||
| „Teach me the wiki” / „Teach me about X” | Planuje i prowadzi rozłożony w czasie kurs ze śledzeniem postępu | `ckb-teach-me` |
|
||
| „Onboard me on X” / „Where do I start with X” | Krótka, prowadzona kolejność czytania po grafie | `ckb-onboard-me` |
|
||
| „Feynman me on X” / „Czego nie rozumiem?” | Proste wyjaśnienie jednej strony, luki, które odsłoniło, i wyjaśnienie z powrotem | `ckb-feynman` |
|
||
| „Give me a project summary” | Regeneruje `PROJECT-OVERVIEW.md` | `ckb-project-summary` |
|
||
| „Prepare a new document using template X” / „List templates” / „Make a template for X” | Wypełnia szablon z `templates/` twoimi odpowiedziami i treścią wiki, zapisuje go w `outputs/documents/`; wypisuje lub przygotowuje szablony | `ckb-document` |
|
||
| „Export the wiki as OKF” | Eksport maszynowy w `outputs/okf/` | `ckb-export-okf` |
|
||
| „Export the wiki to Starlight” | Czytelna dla człowieka strona dokumentacji w `outputs/starlight/` | `ckb-export-starlight` |
|
||
| „Upgrade the wiki” / „Check for a newer template version” | Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz | `ckb-upgrade` |
|
||
| „Index external sources” / „Index libs” | Buduje/odświeża samodzielny indeks dla każdego `libs/<name>/` opartego na konektorze | `ckb-index-external` |
|
||
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf, z zastrzeżeniami gdy źródło jest nieaktualne lub sprzeczne | `ckb-retrieve` |
|
||
| „Kto wie o X" / „Kto jest właścicielem X" | Odpowiedź z krawędzi eksperctwa/własności w grafie | `ckb-retrieve` |
|