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

3.7 KiB

Moduł share

Czytaj w: English | 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ść

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