OKF — Open Knowledge Format

更新日期：2026-07-11

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

什么是OKF？

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

---
type: Note
okf_version: "0.1"
---
# My note

type——说明这份文档是什么类型（例如Note、Daily Note、Project）。这是该约定唯一必填的字段。
okf_version——写入该文件时所依据的约定版本号。
index.md——每个文件夹都可以包含一个index.md作为其目录；index.md和log.md这两个名称因此被保留，不应用作普通笔记的文件名。

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

为什么Plainva使用OKF？

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

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

Plainva自动做了什么

新文件会自动获得OKF头：在Plainva中创建的每一篇笔记，其Frontmatter中都会带有type和okf_version。你可以按仓库配置这些值：设置 → 仓库 → 内容与结构 → OKF（Open Knowledge Format） → 新笔记的type（默认为Note）和日记的type（默认为Daily Note）。如果模板自带type，模板的值优先生效。

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

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

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

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

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 的文件夹，方便你一次性全部生成。
在阅读模式下，受管理的目录列表会以带有文件/文件夹图标的卡片形式渲染；链接会直接在Plainva内打开。

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

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

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

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

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

我必须使用OKF吗？

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

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

另请参阅

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