Plainva

Automazione e script

Ultimo aggiornamento: 2026-10-22

Plainva non ha un sistema di plugin che esegue codice di terze parti. È invece il vault stesso a fare da interfaccia di estensione: le tue note sono semplice Markdown, i database sono puro YAML (.base), e le convenzioni OKF danno a ogni file una struttura prevedibile. Qualsiasi cosa sia in grado di leggere e scrivere file — uno script shell, un programma Python, uno strumento CLI, un job pianificato o un agente IA — può estendere, generare o riorganizzare il tuo vault senza bisogno di un’unica API specifica di Plainva.

Questa pagina spiega come farlo in sicurezza. Il formato esatto di ogni file, a livello di byte, è documentato separatamente nella File Format Reference; questa pagina ne è il compagno pratico: le regole, il flusso di lavoro e cosa consegnare a un assistente IA.

Perché file invece di una sandbox per plugin

Se vuoi qualcosa che Plainva non fa di serie, non aspetti un plugin — scrivi un piccolo script che agisce sui file.

Leggere un vault in sicurezza

Tutto è testo UTF-8:

Leggere non richiede mai particolare attenzione — i file di testo non possono essere “corrotti” leggendoli. Le regole seguenti riguardano tutte la scrittura.

Scrivere un vault in sicurezza

Segui queste regole e Plainva (e Obsidian) accetteranno le tue modifiche senza problemi. Plainva osserva la cartella del vault: una scrittura esterna viene rilevata e re-indicizzata automaticamente, di solito entro un secondo.

  1. Scrivi in UTF-8. Dai a un file nuovo terminatori di riga LF e nessun BOM: è così che scrive Plainva stesso. Un file che ha già terminatori di riga CRLF o un BOM può tenerli: Plainva legge entrambi e li lascia come sono, anche quando la nota viene modificata o sincronizzata. L’eccezione è un ritorno a carrello da solo come terminatore di riga — quello dei vecchi file Mac: Plainva legge un file del genere, ma lo salva con LF la prima volta che lo modifica. Ciò che non sa leggere è un’altra codifica — UTF-16 o Windows-1252, che alcuni strumenti Windows scrivono come impostazione predefinita. Plainva non apre un file così: mostra Questo file non è testo e lo offre al programma di sistema (Apri nell’app predefinita; sul telefono Condividi), e niente in Plainva vi scrive sopra un testo — né un salvataggio, né una proprietà, né un link che una rinomina riscrive. La Cronologia delle versioni lo conserva byte per byte, e ripristinarlo o duplicarlo ne copia i byte. Per modificarlo in Plainva, salvalo in UTF-8 nell’altro programma. Se un altro programma salva un file in un’altra codifica mentre hai modifiche non salvate al suo interno, Plainva conserva le tue modifiche accanto a esso come file .CONFLICT; il confronto offre quindi Sostituisci il file attuale con la copia in conflitto, Conserva entrambi i file ed Elimina la copia in conflitto. La sincronizzazione lo trasferisce comunque intatto — byte per byte, come un’immagine: non viene unito, e se due dispositivi lo hanno modificato contemporaneamente, la tua versione viene conservata come file .CONFLICT.
  2. Scrivi in modo atomico. Scrivi in un file temporaneo nella stessa cartella, poi rinominalo sopra il file di destinazione. Una nota scritta solo a metà (ad esempio dopo un arresto anomalo) è peggio di nessuna modifica. Plainva stesso scrive ogni nota in questo modo.
  3. Conserva il frontmatter OKF e le chiavi sconosciute. Mantieni type e okf_version quando riscrivi una nota, e non scartare mai le chiavi del frontmatter che non riconosci — falle sopravvivere invariate. Non “ripulire” chiavi che non capisci.
  4. Non toccare mai .plainva/. Quella cartella contiene l’indice locale di Plainva, i backup, i fissaggi del grafo e lo stato di sincronizzazione. Non fa parte dei tuoi contenuti e i tuoi script non devono mai scriverla, sincronizzarla o includerla in un commit su Git.
  5. Rispetta le regole della .base. Una .base usa solo le quattro chiavi di primo livello di Obsidian (filters, formulas, properties, views); ogni vista richiede un name; i filtri sono a radice singola. Tutti i dati specifici di Plainva vanno sotto sotto-chiavi annidate plainva:. La File Format Reference contiene il contratto completo, incluso un esempio di relazioni a due vie.
  6. Non entrare in conflitto con l’editor. Se una nota è aperta e ha modifiche non salvate in Plainva, evita di riscriverla da uno script nello stesso momento. Plainva ha un risolutore di conflitti come rete di sicurezza, ma il percorso più pulito è lasciare che l’app salvi per prima (oppure modificare note che al momento non sono aperte).

Casi d’uso

Alcuni compiti comuni, tutti semplici operazioni sui file:

Mantieni gli script idempotenti quando possibile: eseguirli due volte non dovrebbe duplicare i contenuti.

Consegnare il vault a un assistente IA

Un agente IA con accesso in lettura/scrittura a una cartella del vault è esattamente il caso per cui questo design è pensato. Perché funzioni correttamente:

  1. Dagli la File Format Reference. È scritta per un lettore automatico: il contratto del frontmatter OKF, la serializzazione proprietà→YAML, lo schema .base completo con le sue regole rigide di Obsidian, il contratto di index.md e le regole di sicurezza — tutto ciò di cui un agente ha bisogno per modificare i file senza romperli.
  2. Puntalo sulla cartella del vault, non sulla cartella .plainva/. Chiarisci che .plainva/ è vietata.
  3. Chiedi modifiche atomiche e minime. Un agente che riscrive un’intera nota per cambiare una sola proprietà dovrebbe conservare il resto del frontmatter e del corpo del testo invariato.

Poiché il contratto è un documento e non un’API in esecuzione, le stesse istruzioni funzionano con qualsiasi assistente, offline o online.

Sicurezza in breve

Vedi anche