OKF — Open Knowledge Format

更新日期：2026-09-04

OKF（Open Knowledge Format）是一种面向Markdown知识库的开放约定：纯Markdown文件加上一小段统一的Frontmatter头。本页说明什么是OKF、Plainva自动为它做了什么——以及为什么你并不需要用到它的任何部分。

什么是OKF？

其核心理念是：仓库中的每篇文档都能自我说明它是什么。一个最简单的Frontmatter头就足够了：

---
type: Note
---
# My note

type——说明这份文档是什么类型（例如Note、Daily Note、Project）。这是该约定唯一必填的字段。
okf_version——整个仓库所遵循的约定版本。它只存在一次，在根目录的index.md中（目前是"0.2"），不在每篇笔记里。
index.md——每个文件夹都可以包含一个index.md作为其目录；index.md和log.md这两个名称因此被保留，不应用作普通笔记的文件名。

正在用工具或脚本写入文件？确切的字段契约——允许的值、每种属性类型如何序列化，以及保留名称规则——都在文件格式参考中。

OKF从何而来： OKF是Google Cloud的一项开放规范（GoogleCloudPlatform/knowledge-catalog，Apache-2.0许可）。Plainva遵循OKF 0.2（2026年7月25日发布）。0.2版新增了五个可选字段，笔记借此说明自己的来源、是否有人审阅过，以及是否仍然有效——generated、verified、sources、stale_after和status。Plainva对它们的显示和写入方式，说明见下文”来源、审阅与生命周期”一节。

为什么Plainva使用OKF？

纯Markdown的可移植性令人惊叹——但它本身并没有可靠的结构。OKF恰好添加了足够的结构，而一切依然是带有标准Frontmatter的普通Markdown：

数据库、筛选和模板都能依赖结构。 每篇笔记都带有type，因此建立在纯文本文件之上的.base视图才能保持稳健。
文件夹保持可导航。 每个文件夹一份index.md目录，无论对人还是对工具都同样好用。
脚本和AI助手能够安全地处理你的仓库，因为磁盘上的格式统一且有文档记录。
没有锁定。 OKF是建立在纯Markdown之上的一项开放约定——其他OKF工具同样能理解你的文件，无论是现在还是十年之后。

Plainva自动做了什么

新文件会自动获得OKF头：在Plainva中创建的每一篇笔记，其Frontmatter中都会带有type——自OKF 0.2起，版本标记okf_version只存在一次，位于根目录的index.md中，不再出现在每篇笔记里。你可以按仓库配置这些值：设置 → 仓库 → 内容与结构 → OKF（Open Knowledge Format） → 新笔记的type（默认为Note）和日记的type（默认为Daily Note）。如果模板自带type，模板的值优先生效。

已有文件绝不会被擅自修改。 Plainva只在创建新文件时，或者在你明确启动转换功能时，才会添加OKF字段。

受保护的系统字段： 在属性面板中，type和——在旧笔记仍带有它的情况下——okf_version被标记为OKF系统字段（“OKF系统字段——由Plainva管理”）：type的值可以从已知类型的下拉列表中选择，okf_version仅供查看；重命名、更改类型和删除都被锁定，以免这项约定被意外破坏。

说明界面： 设置中的**什么是OKF？**用三句话给出简要说明，并附带指向本页的链接。它不再会自动弹出；如果仓库中含有不符合OKF格式的文件，Plainva会用一条小提示告知一次，并附带一个按钮，点击即可直接前往转换。

来源、审阅与生命周期（OKF 0.2）

自OKF 0.2起，一篇笔记可以说明自己的来源、谁审阅过它，以及它是否仍然有效。Plainva把这变成了三件事：

Plainva显示什么。

一篇带有status: draft或status: deprecated的笔记，文档标题会带有徽章——草稿或已弃用。stable保持沉默；你自己那一列带有其他值（比如任务数据库中的Open）的status并不是生命周期状态，不会得到徽章。
一旦stale_after已经过去，笔记上方就会出现提示已标记为过期（自 …起），并带有跳转到属性的链接。这个提示仅供显示——Plainva不会改变笔记中的任何内容。
属性面板中的可信度与来源一节（手机上：笔记的上下文操作表中）汇总这些字段，并据此推导出一个可信度等级：未验证、机器确认或已由人工审核——此外还有生成者、verified列表、可点击的来源链接、状态和失效日期。状态、失效日期 和 OKF 版本 三行显示翻译后的标签；写入文件的键（status、stale_after、okf_version）显示在锁图标的提示中，且永不改变。

Plainva写入什么。

generated（以及在来源已知时的sources）恰好由三条机器写入路径设置：导入器（plainva-import/<version>，每次运行一个时刻——导入报告也会带上它）、邮件采集（plainva-mail-capture/<version>，以邮件的Message-ID作为来源）以及任务同步（plainva-task-sync/<version>，仅在它创建笔记时）。
verified只由可信度与来源一节中的标记为已审阅写入：Plainva会把human:<your name>连同当前时刻追加到列表中——第二次审阅绝不会覆盖第一次。你的名字每个仓库只会被询问一次；它保存在这台设备上，可以在设置 → 仓库 → 内容与结构 → 审阅者姓名中更改。
编辑器绝不会自行触碰这些字段中的任何一个，已有的笔记也绝不会被事后补盖印记。status和stale_after由你自己设置，作为属性或直接写在Frontmatter中。

升级bundle版本。 这项约定的版本只存在一次，位于根目录的index.md中。一个仍声明为"0.1"的仓库会照常继续工作——在设置 → 仓库 → 内容与结构 → Bundle 版本（手机上：设置 → Vault → 维护 → Bundle 版本）中，你可以用**升级…**把它提升到0.2。对话框会事先显示将发生哪些变化：根目录index.md中的那一行，以及一个默认勾选的复选框——从仍带有旧okf_version字段的笔记中移除它。每个文件在改变前都会先备份；**清理…**只做第二部分。字段表和详细的写入规则见文件格式参考。

index.md：每个文件夹的目录

index.md是一个文件夹的目录：列出其中包含的笔记和子文件夹，并附有描述和相对链接。

生成——始终由你主动触发，绝不会凭空出现：右键点击文件夹→生成概览 / 更新概览，或通过index.md管理（设置 → 仓库 → 内容与结构）批量处理。
采用而非生成——如果你已经有概览笔记（MOC、Overview、Folder Note、README等），管理器会把它们建议为候选项。采用会把该文件重命名为index.md（链接会在整个仓库范围内更新），并可以选择性地为其做好OKF整理准备。
自动维护——由Plainva生成的目录列表，文件末尾会带有一个不可见的标记（HTML注释）。只有带有这个标记的文件才会在文件夹发生变化时自动保持更新——并且只在OKF仓库中生效（可通过根index.md中的okf_version识别）。
只读且可退出——受管理的index.md文件会以阅读模式打开，并显示横幅：“此index.md由Plainva管理并自动更新。“你可以在那里点击刷新——或选择仍要编辑：这会移除标记，此后该文件完全交由你手动维护（不再自动更新）。
一键批量处理——更新所有index.md文件在仓库根目录的右键菜单和设置中都可以找到；没有标记的文件会被跳过。
填补空白——在index.md管理中，在全部没有 index.md 的文件夹中创建会预先勾选每一个没有 index.md 的文件夹，方便你一次性全部生成。
在手机上 — 同样的事，两个入口：长按文件夹会提供生成概览或更新概览，取决于该文件夹的实际情况。要对整个仓库做一次难得的整理，可打开设置 → 仓库 → 维护 → 概览：没有概览的文件夹排在前面，在全部 N 个没有 index.md 的文件夹中创建可一次性建好。若某个文件夹的 index.md 是你自己写的，它会被列出但不会被改动——采用是那份清单里一个有名字的决定，绝不是点一下的副作用。自动维护现在也在手机上运行：在手机上编辑的仓库不会再一直陈旧到某台桌面端打开它为止。
在阅读模式下，受管理的目录列表会以带有文件/文件夹图标的卡片形式渲染；链接会直接在Plainva内打开。

转换已有仓库（可选加入）

如果仓库中的文件不符合OKF格式（缺少type字段，或把保留名称用作普通笔记），Plainva会提供转换功能——首次打开仓库时会提示一次，此后也可以随时在设置 → 仓库 → 内容与结构中找到（只有在确实存在待处理项时该条目才会出现）。

转换为OKF格式向导分为清晰的几个步骤：

扫描——显示受影响的文件数量（模板和系统文件夹被排除在外；Frontmatter无法读取的文件会被跳过，绝不会被”修复”）。
决策——为没有type的文件设置一个默认type；已有的type值可以保留（推荐——它们已经是有效的OKF类型），也可以重命名到另一个字段。
预览（不做更改）——一次预演，提前展示将会发生哪些变化。
转换——每个文件在被修改前都会先备份到.plainva/backups/；报告会汇总有哪些更改、哪些被跳过，以及备份文件夹的位置。之后你可以选择继续前往index.md管理。

来自向导的一个提示：更改照常会经过同步——对于git仓库，请先提交。

在手机上

手机上也有同样的入口：设置 → Vault → 维护 → 转换为OKF格式。步骤完全相同——扫描、选择、预览、转换——而且在写入任何内容之前，预览会逐一列出受影响的笔记。

另外多了两件事，因为手机随时可能把应用从内存中移除：

暂停与继续。当你点击暂停或应用进入后台时，本次运行会在下一个文件处停下。继续时仍写入同一个备份文件夹——不会出现第二个。
启动时会询问。如果一次运行没有完成，Plainva会在你下次打开仓库时告知，并提供继续或回滚；以后再说也是一个正当的回答。被中断的运行留下的是一个只转换了一部分的仓库，而不是损坏的仓库：只会追加frontmatter字段，每一条笔记仍然是合法的Markdown。

回滚会从备份文件夹恢复文件——桌面端也一样，入口在运行结束后的报告里。备份文件夹之后会保留；它是转换前状态的唯一副本。

我必须使用OKF吗？

不需要。OKF是一项温和的标准：

新文件会自动获得该头部——它从不碍事，也不需要任何代价。
已有的仓库（例如来自Obsidian的仓库）会照常继续工作；转换功能严格来说是可选加入的。
缺少okf_version——或者旧笔记仍然带着它——都不算违反约定；你可以让Plainva和Obsidian长期并存使用，不会受到打扰。
Obsidian和其他任何编辑器仍然可以打开每一个文件：它现在是、将来也仍然是普通的Markdown。

另请参阅

文件格式参考——仓库中每个文件的精确磁盘格式契约
笔记与Markdown——Frontmatter与属性
数据库（.base）——统一的type在实际使用中有什么好处
常见问题与故障排查——备份、只读的index.md等内容