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