Plainva

Automação & Scripts

Última revisão: 2026-10-22

O Plainva não tem um sistema de plugins que execute código de terceiros. Em vez disso, o próprio vault é a interface de extensão: suas notas são Markdown puro, os bancos de dados são YAML puro (.base), e as convenções do OKF dão a cada arquivo uma estrutura previsível. Qualquer coisa capaz de ler e escrever arquivos — um script de shell, um programa em Python, uma ferramenta CLI, uma tarefa agendada ou um agente de IA — pode estender, gerar ou reorganizar seu vault sem uma única API específica do Plainva.

Esta página explica como fazer isso com segurança. O formato exato, byte a byte, de cada arquivo está documentado separadamente na Referência do Formato de Arquivo; esta página é o complemento prático: as regras, o fluxo de trabalho e o que entregar a um assistente de IA.

Por que arquivos em vez de uma sandbox de plugins

Se você quiser algo que o Plainva não faz de fábrica, não é preciso esperar por um plugin — basta escrever um pequeno script que atue sobre os arquivos.

Lendo um vault com segurança

Tudo é texto UTF-8:

A leitura nunca exige cuidado — arquivos de texto não podem ser “corrompidos” ao serem lidos. As regras abaixo são todas sobre escrita.

Escrevendo em um vault com segurança

Siga estas regras e o Plainva (e o Obsidian) aceitarão suas alterações sem problemas. O Plainva observa a pasta do vault: uma escrita externa é detectada e reindexada automaticamente, geralmente em menos de um segundo.

  1. Escreva UTF-8. Dê a um arquivo novo quebras de linha LF e nenhum BOM — é assim que o próprio Plainva escreve. Um arquivo que já tem quebras de linha CRLF ou um BOM pode mantê-los: o Plainva lê os dois e os deixa como estão, também quando a nota é editada ou sincronizada. A exceção é um retorno de carro sozinho como quebra de linha — o que os arquivos antigos de Mac têm: o Plainva lê um arquivo assim, mas o salva com LF na primeira vez que o altera. O que ele não consegue ler é outra codificação — UTF-16 ou Windows-1252, que algumas ferramentas do Windows escrevem por padrão. O Plainva não abre um arquivo assim: mostra Este arquivo não é texto e o oferece ao programa do sistema (Abrir no aplicativo padrão; no telefone, Compartilhar), e nada no Plainva grava um texto por cima dele — nem salvar, nem uma propriedade, nem um link que uma renomeação reescreve. O Histórico de versões o mantém byte a byte, e restaurá-lo ou duplicá-lo copia seus bytes. Para editá-lo no Plainva, salve-o como UTF-8 no outro programa. Se outro programa salvar um arquivo em outra codificação enquanto você tem alterações não salvas nele, o Plainva mantém suas alterações ao lado dele como um arquivo .CONFLICT; a comparação oferece então Substituir arquivo atual pela cópia em conflito, Manter os dois arquivos e Excluir cópia em conflito. A sincronização o transfere intacto mesmo assim — byte a byte, como uma imagem: ele não é mesclado, e se dois dispositivos o alteraram ao mesmo tempo, sua versão é mantida como um arquivo .CONFLICT.
  2. Escreva de forma atômica. Escreva em um arquivo temporário na mesma pasta e depois renomeie-o para o destino. Uma nota escrita pela metade (por exemplo, depois de uma falha) é pior do que nenhuma alteração. O próprio Plainva escreve toda nota dessa maneira.
  3. Preserve o frontmatter do OKF e as chaves desconhecidas. Mantenha type e okf_version ao reescrever uma nota, e nunca descarte chaves de frontmatter que você não reconhece — carregue-as adiante sem alterações. Não “organize” chaves que você não entende.
  4. Nunca toque em .plainva/. Essa pasta guarda o índice local do dispositivo do Plainva, os backups, as fixações do grafo e o estado de sincronização. Ela não faz parte do seu conteúdo, e seus scripts nunca devem escrever nela, sincronizá-la ou incluí-la em um commit do Git.
  5. Respeite as regras de .base. Uma .base usa apenas as quatro chaves de nível superior do Obsidian (filters, formulas, properties, views); toda visualização precisa de um name; os filtros têm raiz única. Todos os dados específicos do Plainva ficam sob subchaves aninhadas plainva:. A Referência do Formato de Arquivo traz o contrato completo, incluindo um exemplo de relação de duas vias.
  6. Não brigue com o editor. Se uma nota está aberta e tem edições não salvas no Plainva, prefira não reescrevê-la a partir de um script no mesmo momento. O Plainva tem um resolvedor de conflitos como rede de segurança, mas o caminho mais limpo é deixar o app salvar primeiro (ou editar notas que não estejam abertas no momento).

Padrões

Algumas tarefas comuns, todas apenas operações de arquivo:

Mantenha os scripts idempotentes sempre que possível: executá-los duas vezes não deve duplicar conteúdo.

Entregando o vault a um assistente de IA

Um agente de IA com acesso de leitura/escrita a uma pasta de vault é exatamente o caso para o qual este design foi feito. Para que ele funcione corretamente:

  1. Entregue a ele a Referência do Formato de Arquivo. Ela é escrita para leitura por máquina: o contrato de frontmatter do OKF, a serialização propriedade→YAML, o esquema completo de .base com suas regras rígidas do Obsidian, o contrato do index.md e as regras de segurança — tudo o que um agente precisa para editar arquivos sem quebrá-los.
  2. Aponte-o para a pasta do vault, não para a pasta .plainva/. Deixe claro que .plainva/ está fora dos limites.
  3. Peça edições atômicas e mínimas. Um agente que reescreve uma nota inteira para alterar uma propriedade deve preservar o restante do frontmatter e do corpo ao pé da letra.

Como o contrato é um documento, não uma API viva, as mesmas instruções funcionam com qualquer assistente, offline ou online.

Recapitulação de segurança

Veja também