156925c689
Szkielet kb-wiki wg docs/kb/modules/05-faza3-plan.md §8.2 (homelab-codex-ws, read-only stąd): typy stron jako katalogi (podmioty/osoby/sprawy/umowy/tematy), _meta/conventions.md (frontmatter z blokiem sources, format przypisów [^envelope_id#chunk_id], zasady flagowania sprzeczności i wersji dokumentów, zasady lintu), README z ostrzeżeniem że treść jest LLM-kompilowana.
151 lines
7.1 KiB
Markdown
151 lines
7.1 KiB
Markdown
---
|
||
title: Konwencje kb-wiki
|
||
type: meta
|
||
status: active
|
||
tags: []
|
||
sources: []
|
||
compiled_by: claude-sonnet-5
|
||
compiled_at: 2026-07-21
|
||
updated_at: 2026-07-21
|
||
---
|
||
|
||
# Konwencje kb-wiki
|
||
|
||
Ten dokument definiuje format stron tej wiki. Rozwinięcie decyzji architektonicznych
|
||
z `homelab-codex-ws`, `docs/kb/modules/05-faza3-plan.md` §8 (szkic operatora, NIE
|
||
zmieniamy stamtąd decyzji — tylko doprecyzowujemy wykonanie). To repo jest read-write
|
||
tylko dla kompilatora (CC/API); baza źródłowa (`kb-postgres@PIHA`) jest zawsze
|
||
read-only z tej strony.
|
||
|
||
## Struktura katalogów
|
||
|
||
Typy stron = katalogi; płasko wewnątrz każdego, graf robią linki `[[...]]`, nie
|
||
hierarchia plików.
|
||
|
||
| Katalog | Zawartość |
|
||
|---|---|
|
||
| `podmioty/` | Firmy i instytucje: ubezpieczyciele, banki, urzędy — encje trwałe, nie procesy |
|
||
| `osoby/` | Tożsamości/aliasy osób fizycznych |
|
||
| `sprawy/` | Procesy w czasie: sezony, remonty, procesy decyzyjne, porównania ofert |
|
||
| `umowy/` | Konkretne, zawarte kontrakty/polisy — jeden dokument prawny lub jego wersje |
|
||
| `tematy/` | Przekrojowe kategorie łączące wiele podmiotów/spraw (np. „ubezpieczenia auto”) |
|
||
| `_meta/` | Ten plik, raporty lintu |
|
||
|
||
Wybór katalogu dla nowej strony: jeśli encja to firma/instytucja → `podmioty/`;
|
||
jeśli to coś co się dzieje/działo w czasie (sezon, spór, zakup) → `sprawy/`; jeśli to
|
||
konkretna umowa prawna → `umowy/`; jeśli łączy wiele podmiotów pod wspólnym parasolem
|
||
tematycznym → `tematy/`.
|
||
|
||
## Frontmatter
|
||
|
||
```yaml
|
||
---
|
||
title: <nazwa strony, czytelna>
|
||
type: podmiot # podmiot | osoba | sprawa | umowa | temat | meta
|
||
status: active # active | archived
|
||
tags: [ubezpieczenie] # słownik wspólny z jobs/documents-ingest/tags-vocab.yaml
|
||
# (homelab-codex-ws) — nie wymyślamy nowego słownika dla wiki
|
||
sources:
|
||
- envelope_id: paperless:119
|
||
chunks: [4211, 4213] # document_chunk.id (klucz PK), NIE chunk_index
|
||
- envelope_id: "CABtrY-...@mail.gmail.com"
|
||
chunks: [] # koperta bez chunków (np. sam manifest)
|
||
compiled_by: claude-sonnet-5 # model/sesja, która skompilowała/ostatnio zmieniła stronę
|
||
compiled_at: 2026-07-20 # data pierwszej kompilacji
|
||
updated_at: 2026-07-20 # data ostatniej zmiany
|
||
---
|
||
```
|
||
|
||
`sources` agreguje **wszystkie** koperty, z których cokolwiek na stronie pochodzi —
|
||
niezależnie od tego, ile razy dana koperta jest cytowana w treści. To jest poziom
|
||
audytu „skąd strona czerpie w ogóle”; poziom „ten konkretny fakt” robią przypisy
|
||
inline (niżej).
|
||
|
||
## Przypisy inline i cytowanie faktów
|
||
|
||
Każdy fakt liczbowy lub identyfikujący (kwota, data, numer polisy/umowy, adres,
|
||
próg punktowy) dostaje przypis w miejscu użycia:
|
||
|
||
```markdown
|
||
składka 1 234 zł/rok [^paperless:119#4212]
|
||
```
|
||
|
||
Format: `[^<envelope_id>#<document_chunk.id>]`. Jeden fakt może mieć więcej niż
|
||
jeden przypis, jeśli potwierdzają go niezależnie różne chunki/koperty — wtedy oba
|
||
się wypisuje: `[^paperless:14#965][^paperless:22#2081]`.
|
||
|
||
Fakty opisowe/narracyjne (np. „PZU oferuje kilka wariantów ubezpieczenia") niosące
|
||
niską specyficzność mogą dzielić jeden przypis na koniec akapitu zamiast przypisu
|
||
po każdym zdaniu — przypis jest obowiązkowy per sekcja, nie per zdanie, ale musi
|
||
dawać się prześledzić do konkretnego chunka.
|
||
|
||
**Zakaz dopowiadania**: jeśli fakt nie występuje w żadnym pobranym chunku/streszczeniu,
|
||
strona pisze wprost „brak danych w KB" zamiast go zgadywać z wiedzy ogólnej modelu.
|
||
|
||
## Sprzeczności między źródłami
|
||
|
||
Gdy dwa dokumenty (typowo: dwie wersje tego samego OWU z różnymi datami
|
||
obowiązywania, albo dwie oferty konkurencyjne) podają różne wartości dla tego
|
||
samego faktu, strona **nie wybiera cicho jednej wersji**. Sprzeczność jest
|
||
flagowana jawnie w tekście, z obiema wartościami i obu przypisami, np.:
|
||
|
||
```markdown
|
||
Udział własny w AC: 300 zł wg OWU obowiązującego od 21.03.2026 [^paperless:14#871],
|
||
ale 500 zł wg wcześniejszej wersji OWU [^paperless:17#XXXX] — **rozbieżność między
|
||
wersjami, nie literówka**; przy sporze o odszkodowanie decyduje wersja obowiązująca
|
||
w dniu zdarzenia.
|
||
```
|
||
|
||
## Wersjonowanie dokumentów źródłowych
|
||
|
||
Ubezpieczenia i regulaminy w korpusie mają wielokrotne wersje z różnymi datami
|
||
„obowiązuje od". Strona encji **nie kompiluje jednej płaskiej prawdy** — jeśli
|
||
źródła mają rozbieżne daty obowiązywania, strona wymienia wersje osobno (np.
|
||
podsekcja per data) zamiast nadpisywać starszą nowszą bez adnotacji. To był
|
||
konkretny finding z pilota dedupa (`docs/kb/eval/retrieval-pilot-2026-07-16.md`,
|
||
`docs/kb/modules/05-faza3-plan.md` §3.2) — dokumenty bywają też **duplikatami
|
||
binarnymi** (`excluded_reason='duplicate'` w bazie), co jest czymś innym niż
|
||
kolejna wersja: duplikat pomijamy w kompilacji (baza już to wyklucza z retrievalu),
|
||
wersję z inną datą obowiązywania — nie.
|
||
|
||
## Linkowanie między stronami
|
||
|
||
`[[nazwa-pliku-bez-rozszerzenia]]` — link do innej strony wiki po nazwie pliku
|
||
(bez katalogu, nazwy plików są unikalne w całym repo). Linkujemy tam, gdzie treść
|
||
się faktycznie styka (wspólny podmiot, wspólna sprawa, przywoływany dokument) —
|
||
nie tworzymy linków na wyrost do stron, które jeszcze nie istnieją, chyba że
|
||
świadomie oznaczamy brakujące pojęcie (patrz niżej), bo taki link psuje inwariant
|
||
lintu „brak stron-sierot i wiszących linków" dopóki strona docelowa nie powstanie.
|
||
|
||
## Brakujące pojęcia (przyszłe strony)
|
||
|
||
Jeśli podczas kompilacji natrafiamy na encję wartą osobnej strony, ale poza
|
||
zakresem bieżącej kompilacji (np. inny ubezpieczyciel wspomniany punktowo, inna
|
||
sprawa), **nie tworzymy linku `[[...]]`** do niej (byłby wiszący). Zamiast tego
|
||
kandydatka trafia do listy „brakujące pojęcia" w najbliższym raporcie lintu
|
||
(`_meta/lint-reports/`), żeby nie zgubić się w wątku.
|
||
|
||
## Zasady lintu
|
||
|
||
Okresowy lint (ręczny w tej fazie, `_meta/lint-reports/YYYY-MM-DD.md`) sprawdza:
|
||
|
||
1. **Strony-sieroty** — strona bez żadnego linku przychodzącego z innej strony
|
||
(poza `INDEX.md`, który z definicji linkuje do wszystkiego).
|
||
2. **Wiszące linki** — `[[cel]]` bez odpowiadającego pliku `cel.md` w repo.
|
||
3. **Brakujące pojęcia** — encje wspomniane w treści (nie w linku) a nieopisane
|
||
osobną stroną; kandydaci na przyszłe strony, nie błąd.
|
||
4. **Spot-check** — dla losowej próbki przypisów `[^envelope_id#chunk_id]`
|
||
weryfikacja, że treść chunka w bazie faktycznie potwierdza przywołany fakt.
|
||
5. **Sprzeczności międzystronicowe** — ten sam fakt o tej samej encji opisany
|
||
różnie na dwóch stronach (nie mylić z rozbieżnością międzywersyjną w obrębie
|
||
jednej strony, która jest już jawnie flagowana w treści per wyżej).
|
||
|
||
## Integracja z retrievalem (poza zakresem tej fazy)
|
||
|
||
Docelowo strony wiki wchodzą do `kb-postgres` jako koperty `source='wiki'`
|
||
(`id='wiki:<katalog>/<plik>'`), embedowane tym samym pipeline'em co chunki
|
||
dokumentów — kaskada retrievalu rozszerza się wtedy o trzeci poziom: wiki →
|
||
streszczenie → chunk. Nie jest to realizowane w tej fazie (proof-of-concept
|
||
ręcznej kompilacji 3–5 stron) — patrz `docs/kb/modules/05-faza3-plan.md` §8.2
|
||
w `homelab-codex-ws` po szczegóły.
|