自动化与脚本

更新日期：2026-10-22

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。 新文件请使用LF换行符且不带BOM——Plainva自己就是这样写的。已经使用CRLF换行符或带有BOM的文件可以保留它们：Plainva两者都能读取，并且原样保留，在笔记被编辑或同步时也是如此。例外是仅由回车符（CR）构成的换行符——旧版Mac文件使用的形式：Plainva能读取这样的文件，但会在第一次修改它时用LF保存。它无法读取的是其他编码——一些Windows工具默认写入的UTF-16或Windows-1252。Plainva不会打开这样的文件：它会显示此文件不是文本，并提供交给系统程序打开的方式（在默认应用中打开；在手机上为分享），Plainva中的任何功能都不会向其写入文本——无论是保存、属性，还是重命名时改写的链接。版本历史会逐字节保存它，恢复或复制它时会复制其字节。若要在Plainva中编辑它，请在另一个程序中将其另存为UTF-8。如果你在某个文件中有未保存的更改时，另一个程序以其他编码保存了该文件，Plainva会把你的更改作为.CONFLICT文件保留在它旁边；随后比较界面会提供用冲突副本替换当前文件、保留两个文件和删除冲突副本。不过同步仍会将它原样传送——逐字节传送，就像图片一样：它不会被合并，如果两台设备同时修改了它，你的版本会被保留为一个.CONFLICT文件。
原子写入。 先把内容写入同一文件夹中的一个临时文件，再将其重命名覆盖目标文件。一篇写了一半的笔记（比如崩溃之后留下的）比完全不改还要糟糕。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，最好还带上generated: { by: <your-tool>/<version>, at: … }，以及你自己的属性）和Markdown正文的.md文件。自OKF 0.2起，okf_version只属于根目录的index.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视图的工作原理