ckb/.agents/modules/share/README.pl.md
Michał Kopeć b6b592d5d7 Template 2.0.2: share and capture hardening, Crux without Sources
Fixes F6, F12-F16 from the 2.0.0 script review:
- share: plain file/mailbox names and mailbox-bound share_id/version, or
  the message is ignored (no ckb.yaml injection, no writes outside
  raw/inbox/); ledger rejects whitespace/control characters; every
  commit on a message must be by an owner; duplicate members.yaml
  entries unown a mailbox; only verified retractions hide mail; branch,
  url and name validated before git; received copy always untrusted;
  <private> stripped from title/tldr and unclosed tags; no send without
  the secret scan
- capture: frontmatter values quoted unless plainly safe; one-line title
- lint check 13: chat-attributed Crux needs no Sources

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 14:38:18 +01:00

4.3 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 każdy autor commita, który dodał lub zmienił wiadomość, musi być właścicielem jej skrzynki w members.yaml, a skrzynka wpisana tam dwa razy liczy się jako bez właściciela. W przeciwnym razie wiadomość jest oznaczona jako niezweryfikowana i nie jest brana, chyba że nalegasz. Tylko zweryfikowane wycofanie może wycofać wiadomość, której jeszcze nie wzięto. Wiadomość, której from, share_id lub wersja nie pasuje do skrzynki, albo której nazwa pliku nie jest zwykłą nazwą, jest pomijana z ostrzeżeniem.
  • members.yaml jest ufany tak, jak jest zapisany. Każdy członek, który może pushować, może go edytować, także dopisując siebie jako właściciela. Własność skrzynek wymusza dopiero serwer git z chronionymi ścieżkami albo hookiem pre-receive; użyj go w kanale, którego członkom nie ufasz w pełni.
  • Odebrana kopia zawsze ma untrusted: true, a własne pola untrusted i pola przeglądu nadawcy są usuwane.
  • 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