自动化与脚本

更新日期：2026-07-15

Plainva没有运行第三方代码的插件系统。取而代之，仓库本身就是扩展接口：你的笔记是纯Markdown，数据库是纯YAML（.base），OKF约定让每个文件都拥有可预测的结构。任何能够读写文件的东西，都可以扩展、生成或重新组织你的仓库，而不需要任何Plainva专属的API——不管是Shell脚本、Python程序、CLI工具、定时任务，还是AI助手。

本页说明如何安全地做到这一点。每个文件精确到字节级别的格式，另行记录在文件格式参考中；本页则是配套的实践说明——规则、工作流程，以及该交给AI助手哪些内容。

为什么用文件而不是插件沙盒

安全性。 代码插件系统会在你的编辑器内运行别人编写的程序，并让它访问你的笔记。纯文件不需要这样的信任：脚本只会触碰你指向它的文件夹，且只拥有你操作系统赋予的普通权限。
长久性。 格式比应用本身活得更久。五年前用脚本生成的一个Markdown文件，今天依然可以打开——无论是在Plainva中、在Obsidian中，还是在任何文本编辑器中。没有需要被废弃的插件API。
格式即契约。 由于磁盘上的格式开放且有文档记录，这个”API”是稳定且可检视的：你可以比较它的版本差异、用Git进行版本控制，并对它进行推理分析。

如果你想要某个Plainva本身不具备的功能，你不必等待插件出现——直接针对这些文件写一个小脚本即可。

安全地读取仓库

一切都是UTF-8文本：

笔记（.md）——一个可选的YAML Frontmatter块（位于文件最顶端两行---之间）保存着属性；随后是Markdown正文。用任意YAML库解析Frontmatter即可。
数据库（.base）——纯YAML，描述笔记之上的视图。值从不存放在.base中；它们存放在笔记的Frontmatter里。
结构——标签在正文中写作#tag，或在Frontmatter中写作tags:；链接是[[Note]]（Wiki链接）或[text](path.md)。任务是- [ ] / - [x]列表项。

读取从不需要小心——文本文件不会因为被读取而”损坏”。下面的规则说的全都是写入。

安全地写入仓库

遵循以下规则，Plainva（以及Obsidian）就会干净利落地接受你的更改。Plainva会监视仓库文件夹：外部写入通常会在一秒内被自动检测到并重新编制索引。

写入UTF-8无BOM，使用LF换行符。 默认使用UTF-16或CRLF的Windows工具产生的文件，会被Plainva在每次同步时都视为已更改。
原子写入。 先把内容写入同一文件夹中的一个临时文件，再将其重命名覆盖目标文件。一篇写了一半的笔记（比如崩溃之后留下的）比完全不改还要糟糕。Plainva自身对每一篇笔记都是这样写入的。
保留OKF Frontmatter与未知的键。 重写一篇笔记时保留type和okf_version，并且绝不要丢弃你不认识的Frontmatter键——让它们原样经受住一次往返读写。不要去”整理”你看不懂的键。
绝不要碰.plainva/。 这个文件夹保存着Plainva的设备本地索引、备份、关系图固定信息和同步状态。它不属于你的内容，绝不能被你的脚本写入、同步或提交到Git。
遵守.base的规则。 一个.base只使用Obsidian的四个顶层键（filters、formulas、properties、views）；每个视图都需要一个name；筛选条件是单根的。所有Plainva专有的数据都放在嵌套的plainva:子键之下。文件格式参考中有完整的契约，包括一个双向关联的示例。
不要与编辑器抢占文件。 如果一篇笔记正在Plainva中打开并且有未保存的修改，最好不要在同一时刻用脚本重写它。Plainva有冲突解决机制作为安全网，但最干净的做法是先让应用完成保存（或者去编辑那些当前没有打开的笔记）。

模式

几个常见的用途，全部都只是文件操作：

批量创建笔记——生成带有OKF Frontmatter块（type、okf_version，以及你自己的属性）和Markdown正文的.md文件。这些文件一出现，Plainva就会为它们编制索引。
日记或报告生成器——一个定时脚本，把带日期的笔记写入你的日记文件夹，内容取自其他数据源。
属性巡检——读取每篇笔记的Frontmatter，转换某个字段，再把它写回去（原子写入，并保留未知的键）。
导出／发布——读取仓库，把它渲染成HTML、静态网站或PDF。只是读取——无需担心任何规则。
链接维护——重新扫描[[Note]]链接和tags:，生成一份报告，或者直接原地修复它们。

尽量让脚本保持幂等：运行两次不应该产生重复的内容。

把仓库交给AI助手

一个对仓库文件夹拥有读写权限的AI助手，正是这套设计所要应对的典型场景。要让它正确工作：

把文件格式参考交给它。 这份文档正是为机器读者而写的：OKF Frontmatter契约、属性→YAML的序列化方式、完整的.base模式（schema）及其硬性的Obsidian规则、index.md契约，以及安全规则——AI助手编辑文件而不破坏它们所需要的一切都在这里。
把它指向仓库文件夹，而不是.plainva/文件夹。 明确告诉它.plainva/是禁区。
要求它进行原子化的最小改动。 如果某个AI助手要为了修改一个属性而重写整篇笔记，它应该原样保留Frontmatter和正文中的其余部分。

因为这份契约是一份文档，而不是一个实时API，所以同样的说明适用于任何AI助手——无论离线还是在线。

安全要点回顾

UTF-8，无BOM，LF换行符。
原子写入（临时文件 + 重命名）。
保留type、okf_version以及未知的键。
绝不要写入.plainva/。
.base：四个顶层键、命名视图、单根筛选条件，其余一切都放在plainva:子键下。
仓库处于被监视状态——外部更改会自动出现在Plainva中。

另请参阅

文件格式参考——每个文件在磁盘上的精确格式
OKF——让文件拥有可预测结构的Open Knowledge Format
数据库（.base）——.base视图的工作原理