okf-knowledge-base

开放知识格式（OKF）

OKF v0.2 是一种便于 Agent 读取知识的可移植格式：Markdown 文件、YAML frontmatter 和标准链接。/open-knowledge 技能规定工具的使用方式；本技能介绍 OKF 语义。

核心规则

• 一个知识包是由 .md 文件组成的目录树。每个非保留文件表示一个概念；其去掉 .md 的路径就是该概念的 ID。
• 每个概念都需要可解析的 frontmatter，其中包含非空字符串 type。没有其他字段是必需的。
• 类型采用开放词表。使用者必须接受不熟悉的类型和元数据。
• 使用标准 Markdown 链接表示可移植关系。允许存在失效链接，也允许缺少索引。
• index.md 和 log.md 在每一层都是保留文件。文件名使用小写。
• index.md 通常没有 frontmatter；只有根索引可以声明 okf_version: "0.2"。
• log.md 按时间从新到旧排列；条目标题以 ISO 日期开头——## YYYY-MM-DD: Summary（日期之后的摘要可选；仅写 ## YYYY-MM-DD 同样符合规范）。
• OKF 使用者读取 .md，而非 .mdx。

编写判断

• 将每个概念设为最小且实用的链接或引用目标。选择稳定且有描述性的类型；只有在没有更合适的类型时才使用通用类型 Document。
• 不要编造事实、关系、资源、来源、核验信息或历史记录。缺少知识也好过错误的结构。
• 仅在确实能增加信息时使用 title、description、resource 和 tags。
• 在 sources 中记录来源信息。将针对具体声明的引用与相匹配的 sources[].id 和 Markdown 脚注关联起来。
• 将作者信息与核验信息分开：generated 表示由谁生成内容；verified 表示由谁确认内容。适用时使用精确的小写前缀 human: 和 process:。
• 所有来源时间戳都写成带明确 UTC 偏移量的 ISO 8601 日期时间（stale_after: 2026-12-31T00:00:00Z），不得只写日期，也不得省略时区偏移量。这适用于 generated.at、verified[].at、stale_after、sources[].last_modified 以及 usage_window 的两个边界值。log.md 条目标题则不同：仍使用纯 YYYY-MM-DD 日期。
• 将 status: deprecated 和已过期的 stale_after 值视为信任信号，而非验证错误。
• 对于 type: Attested Computation，请遵循声明的运行时和参数。不要改写经批准的计算过程。

读取和维护知识包

• 从最近的 index.md 开始，检查 frontmatter，然后只跟进相关链接。
• 优先采用当前且已核验的来源，但也要容忍未知类型和不完整链接。
• 如果知识包与某项假设冲突，以知识包为准；如果知识包缺失或内容不一致，请如实说明。
• 将可长期保留的发现写回相关概念和已编写的枚举内容中。
• 如果知识包使用日志，在持久性变更后添加如实的、带日期的 log.md 条目。
• 读取旧版 timestamp 和正文引用，但更新概念时优先使用 v0.2 的 generated.at 和 sources。迁移时绝不编造来源信息。

OpenKnowledge 的 okf 插件

这个可选的项目插件会持续提供可移植性反馈，但不会阻止写入：

• 写入时警告和项目审计会检查结构、frontmatter、保留文件、链接以及 .mdx 的使用情况。
• .ok/okf/*.schema.json 包含精确的字段约定。请读取这些生成文件，不要猜测；也不要编辑它们。
• 确定性的 lint 结果可以判定是否符合规范。元数据是否真实且有用，仍须由 Agent 判断。
• 可选的索引生成会维护 index.md 文件。生成的索引归机器管理：绝不要编辑，因为 OpenKnowledge 会替换其内容。
• log.md 由作者编写，不会自动生成。

该插件默认关闭，每条规则都可以禁用。它的价值在于及早发现 OpenKnowledge 原生内容可能会被其他 OKF 使用者误读的情况。