Plainva

Automatyzacja i skrypty

Stan na: 2026-10-22

Plainva nie ma systemu wtyczek, który uruchamiałby cudzy kod. Zamiast tego interfejsem rozszerzeń jest sam vault: Twoje notatki to zwykły Markdown, bazy danych to zwykły YAML (.base), a konwencje OKF nadają każdemu plikowi przewidywalną strukturę. Wszystko, co potrafi czytać i zapisywać pliki — skrypt powłoki, program w Pythonie, narzędzie CLI, zaplanowane zadanie czy agent AI — może rozszerzać, generować lub reorganizować Twój vault bez żadnego API specyficznego dla Plainva.

Ta strona wyjaśnia, jak robić to bezpiecznie. Dokładny format każdego pliku na poziomie bajtów jest udokumentowany osobno w Dokumentacji formatu plików; ta strona jest praktycznym uzupełnieniem: zasady, przebieg pracy i to, co przekazać asystentowi AI.

Dlaczego pliki zamiast piaskownicy wtyczek

Jeśli chcesz czegoś, czego Plainva nie robi od razu po wyjęciu z pudełka, nie czekasz na wtyczkę — piszesz mały skrypt działający na plikach.

Bezpieczne odczytywanie vaultu

Wszystko to tekst UTF-8:

Odczyt nigdy nie wymaga ostrożności — plików tekstowych nie da się „uszkodzić” przez samo ich czytanie. Poniższe zasady dotyczą wyłącznie zapisu.

Bezpieczne zapisywanie do vaultu

Trzymaj się tych zasad, a Plainva (i Obsidian) przyjmą Twoje zmiany bez problemów. Plainva obserwuje folder vaultu: zewnętrzny zapis jest wykrywany i automatycznie ponownie indeksowany, zwykle w ciągu sekundy.

  1. Zapisuj UTF-8. Nowemu plikowi daj zakończenia linii LF i nie dawaj BOM — tak zapisuje sama Plainva. Plik, który ma już zakończenia linii CRLF albo BOM, może je zachować: Plainva czyta jedno i drugie i zostawia je bez zmian, także wtedy, gdy notatka jest edytowana lub synchronizowana. Wyjątkiem jest sam znak powrotu karetki (CR) jako zakończenie linii — tak kończą się linie w starych plikach z Maca: Plainva czyta taki plik, ale przy pierwszej zmianie zapisuje go z LF. Nie potrafi natomiast czytać innego kodowania — UTF-16 lub Windows-1252, w których niektóre narzędzia Windows zapisują domyślnie. Takiego pliku Plainva nie otwiera: pokazuje Ten plik nie jest tekstem i proponuje przekazanie go programowi systemu (Otwórz w domyślnej aplikacji, na telefonie Udostępnij), a nic w Plainva nie zapisuje na nim tekstu — ani zapisanie, ani właściwość, ani link przepisywany przy zmianie nazwy. Historia wersji przechowuje go bajt po bajcie, a przywrócenie lub zduplikowanie kopiuje jego bajty. Aby edytować go w Plainva, zapisz go w drugim programie jako UTF-8. Jeśli inny program zapisze plik w innym kodowaniu, gdy masz w nim niezapisane zmiany, Plainva zachowuje Twoje zmiany obok jako plik .CONFLICT; porównanie oferuje wtedy Zastąp bieżący plik kopią konfliktową, Zachowaj oba pliki i Usuń kopię konfliktową. Synchronizacja mimo to przenosi go w nienaruszonym stanie — bajt po bajcie, jak obraz: nie jest scalany, a jeśli dwa urządzenia zmieniły go jednocześnie, Twoja wersja zostaje zachowana jako plik .CONFLICT.
  2. Zapisuj atomowo. Zapisz do pliku tymczasowego w tym samym folderze, a następnie zmień jego nazwę na docelową (rename). Notatka zapisana w połowie (na przykład po awarii) jest gorsza niż brak zmiany. Sama Plainva zapisuje w ten sposób każdą notatkę.
  3. Zachowaj frontmatter OKF i nieznane klucze. Podczas przepisywania notatki zachowaj type i okf_version, a kluczy frontmatter, których nie rozpoznajesz, nigdy nie usuwaj — muszą przetrwać cykl odczytu/zapisu bez zmian. Nie „porządkuj” kluczy, których nie rozumiesz.
  4. Nigdy nie dotykaj .plainva/. Ten folder przechowuje lokalny na urządzeniu indeks Plainva, kopie zapasowe, przypięcia grafu i stan synchronizacji. Nie jest częścią Twojej treści — Twoje skrypty nigdy nie powinny do niego zapisywać, synchronizować go ani dodawać do commitów Git.
  5. Przestrzegaj zasad .base. Plik .base używa tylko czterech kluczy najwyższego poziomu Obsidian (filters, formulas, properties, views); każdy widok potrzebuje name; filtry są jednokorzeniowe. Wszystkie dane specyficzne dla Plainva znajdują się pod zagnieżdżonymi podkluczami plainva:. Pełny kontrakt, wraz z przykładem dwustronnych relacji, znajduje się w Dokumentacji formatu plików.
  6. Nie walcz z edytorem. Jeśli notatka jest otwarta i ma niezapisane zmiany w Plainva, lepiej nie przepisywać jej w tym samym momencie ze skryptu. Plainva ma mechanizm rozwiązywania konfliktów jako siatkę bezpieczeństwa, ale najczystszą drogą jest pozwolić aplikacji zapisać jako pierwszej (albo edytować notatki, które akurat nie są otwarte).

Wzorce

Kilka typowych zadań — wszystkie to zwykłe operacje na plikach:

Tam, gdzie to możliwe, twórz skrypty idempotentne: dwukrotne uruchomienie nie powinno duplikować treści.

Przekazywanie vaultu asystentowi AI

Agent AI z dostępem do odczytu i zapisu folderu vaultu to dokładnie ten przypadek, dla którego powstał ten projekt. Aby działał poprawnie:

  1. Podaj mu Dokumentację formatu plików. Jest napisana z myślą o czytelniku maszynowym: kontrakt frontmatter OKF, serializacja właściwość→YAML, pełny schemat .base wraz z twardymi zasadami Obsidian, kontrakt index.md oraz zasady bezpieczeństwa — wszystko, czego agent potrzebuje, aby edytować pliki bez ich psucia.
  2. Wskaż mu folder vaultu, nie folder .plainva/. Jasno określ, że .plainva/ jest niedostępny.
  3. Proś o atomowe, minimalne edycje. Agent, który przepisuje całą notatkę, aby zmienić jedną właściwość, powinien zachować resztę frontmatter i treści dosłownie bez zmian.

Ponieważ kontrakt jest dokumentem, a nie żywym API, te same instrukcje działają z każdym asystentem, offline czy online.

Podsumowanie zasad bezpieczeństwa

Zobacz też