Awesome OKF

这是什么？适合谁？

Awesome OKF（Albertchamberlain/Awesome-OKF）是 Open Knowledge Format（OKF）生态的精选目录。OKF 是 Google Cloud 提出的开放规范：知识 = 一目录 Markdown 文件 + YAML frontmatter + 少量约定，无运行时、无 SDK。Awesome OKF 在此之上把整个 OKF 生态（工具、插件、skills、提案、文档，当前 29 条目录）收进一份经校验的 YAML catalog，然后由它生成三种消费形态：

catalog.yaml → README.md（人类可读） / CLI 工具（可搜索） / MCP server（Agent 可直查）

外加 OKF Anything 转换链：Markdown、PDF、Obsidian、Notion、飞书、GitHub、JSON、CSV、OCR 等任意可读格式 → 统一中间形状（title/url/description）→ 打包成 myokf 可校验的 OKF 目录。README 有英/中/日/韩四语版本，MIT，Python。仓库 2026-09-07 创建，5 天 102★/2 fork。

适合谁：

• 用 Claude Code / Codex 等 Agent 管理个人或团队知识库，想让 Agent 直接检索 OKF 目录的开发者
• 从 Obsidian / Notion / 飞书向”Agent 友好知识”迁移的重度知识管理者
• 维护 awesome 类清单、想用”改一条 YAML 记录 → 重生成文档 → 随处可查”工作流的目录维护者

不适合：想要重量级知识图谱/RAG 服务平台的团队（OKF 哲学恰好是无运行时纯文件）；不用 YAML/命令行的非技术用户。

使用前提：Python 3；要接 Agent 则需 MCP 客户端（Claude Code / Codex 等）。

准备工作

1. 安装：git clone 仓库（CLI 与 MCP server 由仓库内 scripts/ 提供）
2. 环境：Python 3.x；MCP 宿主可选
3. 准备：一份待检索的 OKF 知识目录，或任意想转成 OKF 的资料（Markdown/PDF/Notion 导出等）
4. 成本：MIT 开源免费
5. 时间：clone 后 10 分钟内可跑通第一次目录检索

快速上手（3 步）

第一步：获取目录

git clone https://github.com/Albertchamberlain/Awesome-OKF.git
cd Awesome-OKF

预期产出：本地得到 catalog.yaml、README、CLI 脚本与 MCP server。

第二步：跑第一次检索

python scripts/search.py "obsidian"   # 以仓库内 CLI 实际入口为准

从 29 条目录记录里检索 OKF 工具/skills，例如找”Obsidian vault 转换插件”。

成功判定：命令返回匹配的 catalog 条目（含 name/url/description）。

第一步任务：把任意文件转成 OKF

python scripts/convert-to-okf.py whatever.txt --format anything -o kb/

--format anything 会依次尝试解析链（列表 → JSON → 键值 → URL → 按行），直到一个能解析为止，输出 myokf 可校验的 OKF 目录 kb/。

成功判定：kb/ 下生成带 YAML frontmatter 的 Markdown 条目；myokf validate kb/ 通过（如已装 myokf）。

初级用法

当一份 awesome 清单读

直接读 README（含中文版 README.zh.md）浏览 29 条 OKF 生态资源，按场景挑工具。

MCP meta-server 检索

把 MCP server 挂到 Claude Code/Codex，Agent 可直接查目录——例如对话中问”找支持飞书导出转换的 OKF 工具”，Agent 调用检索工具拿到结构化结果。

单文件转换

用 convert-to-okf.py 把散落的笔记/导出文件逐个转成 OKF 条目，攒出第一个 Agent 友好知识库。

高级玩法

OKF Anything 管道

平台导出 + 本地引擎（pymupdf、PaddleOCR）承担提取，不经自有模型：Extract → Normalize（title/url/description）→ Bundle（myokf 校验目录）。批量整理 Notion/飞书导出为知识库。

MCP 工具 convert_to_okf

Agent 在对话中直接把任意文本交给 convert_to_okf 工具，拿回 OKF 目录——Agent 边整理知识边入库。

单一数据源维护

目录维护者的工作流：改 catalog.yaml 一条记录 → 重生成 README/CLI/MCP 三端 → 无需手动同步多个展示面。

小技巧

1. 转换不确定格式时直接 --format anything，让解析链自己找路径
2. 目录检索优先走 MCP 让 Agent 拼 query，比人肉关键词更准
3. 生成 OKF 目录后用 myokf 校验，格式错误当场暴露
4. 维护自己的 catalog 时保持”每条记录一个 YAML 对象”，重生成才不乱
5. 中日韩文档齐全，团队内分享直接用对应语言 README

常见踩坑

踩坑 1：以为 OKF 是一个服务/数据库

• 现象：找 API server、找部署方式
• 原因：OKF 是纯文件规范（Markdown + YAML 约定），无运行时无 SDK
• 解决：把它当”带约定的文件夹”用；检索靠 CLI/MCP，不靠服务

踩坑 2：MCP server 连上但查不到东西

• 现象：Agent 调用返回空
• 原因：查询词与 catalog 记录字段（name/description）不匹配
• 解决：先用 CLI 人肉检索确认目标条目存在，再让 Agent 用相近关键词

踩坑 3：转换 PDF/图片失败

• 现象：convert-to-okf 报错或输出空 body
• 原因：本地引擎（pymupdf/PaddleOCR）未安装或版本不符
• 解决：按报错装齐依赖；OCR 质量差的扫描件先人工整理再转换

踩坑 4：catalog 校验不过

• 现象：改完 YAML 后重生成失败
• 原因：字段名/缩进不合 schema
• 解决：对照已有 29 条记录的写法逐字段检查；用仓库自带校验工具

踩坑 5：目录很小期望很高

• 现象：想找的工具不在 29 条里
• 原因：生态早期（OKF 规范 2026 年才起步），目录覆盖必然有限
• 解决：走 contributing 流程补充条目，或自行扩展 catalog

踩坑 6：CLI 入口与文档不符

• 现象：命令参数报错
• 原因：仓库 5 天新，脚本迭代快
• 解决：以仓库 scripts/ 当前版本与 README 为准

常见问题 FAQ

Q1: OKF 和 RAG/vector DB 有什么区别？

A: OKF 是纯文件格式规范：知识就是带 YAML frontmatter 的 Markdown 目录，无嵌入、无服务。Agent 检索靠目录/CLI/MCP 的结构化查询，而不是向量相似度。

Q2: 目录里有多少条目？

A: 当前 29 条（README badge “catalog 29 entries”），覆盖 OKF 生态的工具、插件、skills、提案与文档。

Q3: 支持中文吗？

A: README 有中文（README.zh.md）、日文、韩文版本；catalog 条目内容以英文为主。

Q4: MCP server 怎么接入 Claude Code？

A: 仓库提供 MCP meta-server（catalog 查询 + convert_to_okf 工具），按 README “Connect to your Agent” 节配置宿主的 MCP 连接。

Q5: 免费吗？

A: MIT 开源免费；转换用的本地引擎（pymupdf/PaddleOCR）也均为开源。

Q6: 和其他 awesome 清单有什么区别？

A: 普通 awesome 清单是手写 Markdown；本目录单一 YAML 数据源，自动生成人类可读列表、CLI 与 MCP 三种消费面，且条目经过 schema 校验。

参考链接

• 官方仓库
• 中文 README
• OKF 规范 SPEC.md

本文基于公开资料（GitHub 官方 README）整理，AI 辅助生成，未做本地安装实测；采集日期 2026-09-12。功能与数据以官方仓库最新说明为准。