OKF 是一种开放的、对人和智能体都友好的格式，用来表示 知识——围绕在数据与系统周围的元数据、上下文与经过梳理的洞见。
其设计目标是：可由人撰写、可由智能体生成、可跨组织交换、可被人和智能体共同消费。
这个格式刻意保持极简： 一个目录，里面是带 YAML 头信息的 Markdown 文件。 没有 schema 注册表，没有中央权威，也不要求专门工具链。
1. 动机
面向 AI 智能体的知识表示领域正在飞速演化，并产生大量互不兼容的约定。OKF 主张，知识最好使用通用、可访问、已被广泛接受的格式来表示。
- 对人可读，无需工具；
- 对智能体可解析，无需定制 SDK；
- 可以在版本控制中 diff；
- 可以跨工具、跨组织、跨时间移植。
目标
- 定义一个通用格式，供富化智能体（enrichment agents）写入。
- 指导消费智能体（consumption agents）如何读取与遍历知识。
- 促进知识在系统与组织之间交换。
- 标准化那些为了使知识内容能够被有意义消费而必须存在的少量字段。
非目标
- 定义一套固定的概念类型分类法。
- 规定存储、服务或查询的基础设施。
- 取代领域专用 schema，例如 Avro、Protobuf、OpenAPI 等。
2. 术语
知识包（Knowledge Bundle）： 一个自包含的、层级化的知识文档集合，是分发的基本单位。
概念（Concept）： 包内的一个知识单元，表示为一份 Markdown 文档。
概念 ID（Concept ID）： 概念文件在包内的路径，去掉 `.md` 后缀。
头信息（Frontmatter）： Markdown 文件顶部由 `---` 界定的 YAML 元数据块。
正文（Body）： 头信息之后的全部内容。
链接（Link）： 从一个概念指向另一个概念的标准 Markdown 链接。
引用（Citation）： 从一个概念指向某个外部来源的链接，用来支撑正文中的某个论断。
3. 包结构
一个 OKF 包就是一棵由 Markdown 文件组成的目录树。目录结构与领域无关，生产者按照所捕获知识最合理的方式组织概念。
path/to/bundle/
├── index.md
├── log.md
├── .md
└── /
├── index.md
├── .md
└── /
└── … 一个包可以通过 Git 仓库、tarball / zip 压缩包，或者更大仓库中的子目录进行分发。
3.1 保留文件名
| 文件名 | 用途 |
|---|---|
| index.md | 目录清单 |
| log.md | 更新历史 |
4. Frontmatter 与知识文档
每个普通概念文档通过 YAML Frontmatter 对自身进行描述。Frontmatter 位于 Markdown 文件顶部，是机器解析知识的重要入口。
OKF 允许生产者增加额外字段，同时强调消费者应保持宽容，不应该因为存在未知字段而拒绝整个知识包。
5. 链接
OKF 使用标准 Markdown 链接建立概念之间的关系。链接具体表达的是何种关系，例如父子、引用、关联或依赖，由周围的自然语言表达，而不是由链接本身决定。
OKF 的设计倾向是保持链接简单、通用和可移植，同时把复杂的语义留给消费者解释。
6. 索引文件
index.md 可以出现在任意目录，包括包根目录，用来枚举目录内容，以支持渐进式展开（progressive disclosure）。
7. 日志文件
log.md 可以出现在层级的任意一层，用来记录该范围内的变更历史。日志按日期组织，最新日期在前。
8. 引用
当概念正文做出源自外部材料的论断时，这些来源应当列在文档底部的 Citations 标题下，并编号。
9. 符合性
一个包符合 OKF v0.1，需要满足几项核心硬要求，包括：目录树中每个非保留 `.md` 文件都含有可解析的 YAML 头信息块；每个头信息块都含有非空的 `type` 字段；保留文件名 `index.md` 与 `log.md` 在出现时遵循对应结构。
消费者应该把其他约束视为软性指引，并且不应该因为缺少可选字段、未知的 type、未知的额外键、坏的交叉链接或者缺少 index.md 而拒绝整个知识包。
OKF 的核心原则是：硬要求尽可能少，互操作依靠约定与作品质量，而不是高门槛校验器。
10. 与其他格式的关系
OKF 刻意贴近 LLM“维基”仓库、Obsidian / Notion 等个人知识工具，以及“元数据即代码”的组织方式。
其主要区别在于：OKF 对互操作所需的少量规则进行规范化，同时不对具体工具链发号施令。
11. 版本管理
OKF 当前版本为
0.1。
未来修订采用
<主>.<次>
形式版本化。
次版本可以引入向后兼容的新内容；主版本可能带来破坏性变更。
