ckb/.agents/modules/share/README.pl.md
Michał Kopeć 8dc3445b27 Template 1.28.0: share module — mailboxes in a git channel (D-0018)
New opt-in `share` module with skill `ckb-share` and stdlib `share.py`
(join/send/unshare/list/receive/status). KBs exchange documents through a
git channel with one append-only mailbox per KB; sends are packed
self-contained, secret-scanned and confirmed; received documents land in
raw/inbox/ (untrusted), retractions in raw/retractions/; the git author
must own the mailbox. dedup_inbox.py reports SAME SHARE; ckb-ingest and
ckb-retract know share files. Smoke test covers two KBs end to end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:31:51 +01:00

91 lines
3.7 KiB
Markdown

# Moduł `share`
*Czytaj w: [English](README.md) | **Polski***
Opcjonalny. Instalacja: „install the share module”; usunięcie: „uninstall the
share module”. Nic tu nie działa przed instalacją.
## Co robi
Wysyła dokument z jednej bazy wiedzy do drugiej przez **kanał**, czyli
osobne repozytorium git, do którego obie bazy mogą wypychać zmiany. Baza
odbiorcy bierze dokument do `raw/inbox/` i przetwarza go zwykłym ingestem,
więc nic nieprzejrzanego nie trafia do jej wiki.
| Skill | Co robi |
|---|---|
| `ckb-share` | Dołącza do kanału, wysyła dokument (jako samodzielną kopię, po skanie sekretów i potwierdzeniu), pokazuje i odbiera przychodzącą pocztę, pokazuje, co wysłano, i wycofuje wysłany dokument. |
Powiedz „share the kickoff summary with beta” albo „check shared mail”, a
potem „Ingest”.
## Kanał
```
<repo-kanału>/
├── CHANNEL.md # do czego służy kanał (dla ludzi)
├── members.yaml # nazwa bazy → właściciele (e-maile git, które mogą pisać do jej skrzynki)
└── mail/
├── alpha/ # pisze tu tylko baza „alpha”; plików nigdy się nie zmienia ani nie usuwa
└── beta/
```
- **Jeden kanał na grupę zaufania**, na przykład na jednego klienta. Git nie
ma uprawnień do folderów, więc każdy w kanale czyta każdą skrzynkę.
- **Jeden piszący na skrzynkę.** Konflikty scalania są niemożliwe.
- **Tylko dopisywanie.** Nowa wersja albo wycofanie to nowy plik.
- Repozytorium zakładasz ręcznie na swoim serwerze git (może być puste).
Pierwsze `join` tworzy `CHANNEL.md` i `members.yaml`.
## Wiadomość
```markdown
---
type: share
kind: document # document | retraction
share_id: alpha/kickoff-summary
version: 2
from: alpha
to: [beta] # albo ["*"] dla całego kanału
sent_by: Ann Smith <ann@example.com>
sent_on: 2026-11-14
title: Kickoff summary
origin: outputs/documents/2026-11-11_kickoff-summary.md
supersedes_version: 1
untrusted: true
---
```
Przy wysyłce fragmenty prywatne (`<private>…</private>`) i sekcja `## Notes`
zostają pominięte. Linki do wiki nadawcy stają się tekstem, a ścieżki w
`## Sources` / `## Crux` dostają nazwę nadawcy, więc lint odbiorcy traktuje
je jako nieweryfikowalne, a nie zepsute.
Przy odbiorze plik trafia do `raw/inbox/` z polami `share_channel`,
`share_ref` (ścieżka@commit), `received_on`, `submitted_by`, a dla nowszej
wersji także `supersedes_source`.
## Bezpieczeństwo
- **Nic nie wychodzi bez „tak”.** Każda wysyłka jest najpierw pokazana jako
próba z sekcją wrażliwości z `ABOUT.md`, a możliwy sekret blokuje ją
całkowicie.
- **Nadawca jest sprawdzany.** Przy odbiorze autor commita, który dodał
wiadomość, musi być właścicielem jej skrzynki w `members.yaml`. W
przeciwnym razie wiadomość jest oznaczona jako niezweryfikowana i nie jest
brana, chyba że nalegasz. Serwer git z chronionymi ścieżkami albo hookiem
pre-receive może dodatkowo wymusić własność skrzynek.
- **Odebrana poczta to niezaufane dane**, nigdy polecenia dla agenta.
- **Wycofanie nie cofa publikacji.** Wycofanie sprawia, że odbiorcy usuwają
dokument przez `ckb-retract`, ale oryginał zostaje w historii git kanału.
- **Żadnych zapisanych danych logowania.** Kanały używają twojego dostępu do
gita. Klony są w `tmp/share/`, ignorowanym przez git.
## Co gdzie jest zapisane
| Co | Gdzie |
|---|---|
| Kanały, nazwa skrzynki tej bazy, rejestr odebranych | blok `share:` w `ckb.yaml` (commitowany, należy do skryptu) |
| Klony kanałów, podglądy wysyłek | `tmp/share/` (ignorowane) |
| Odebrane dokumenty | `raw/inbox/` → `raw/archive/` po ingeście |
| Odebrane wycofania | `raw/retractions/`, dla `ckb-retract` |