Okf Creator

OKF Creator

把任意输入整理成符合 OKF v0.2 且正文质量过关的知识包。OKF 的硬要求极低(任何带 type 的 Markdown 就合规),所以本 Skill 的真正价值不在"产出合规文件",而在"产出读了就懂、agent 检索得动的知识"。

何时使用

• 从零创建一个 OKF 知识库;
• 为一个代码库 / 文档站 / 数据表生成知识文档;
• 把零散笔记、Wiki、PDF 抽取文本整理成概念库;
• 校验并修复一个 bundle 的 OKF 符合性。

核心原则(顺序很重要)

1. 先定边界,再动手。 问清楚:知识的来源是什么?消费者是人还是 agent?要覆盖哪些概念?不要一上来就铺目录。
2. 一个概念一个文件。 文件路径即概念身份(concept ID)。按领域而非按文件类型组织。
3. 正文用结构,不用流水账。 偏好标题 / 列表 / 表格 / 代码块。规范只约定 # Schema、# Examples、# Citations 三个标题——适用就用。
4. 链接成图。 概念之间用普通 Markdown 链接互连,推荐包内绝对路径 /path/to/x.md。
5. 质量自检。 每个概念问自己:一个没上下文的人/agent,只读这一篇,能用起来吗?不能就补。

工作流

1. 梳理来源,列出要捕获的概念清单(先列再写)。
2. 用 scripts/scaffold_okf.py 生成骨架(根 index.md + log.md + 目录)。
3. 逐个写概念文档:头信息(type 必填)+ 结构化正文 + 交叉链接 + 必要的 # Citations。
4. 写 / 更新各级 index.md(渐进式展开)与根 log.md。
5. 用 scripts/validate_okf.py <bundle> 校验,修到 0 错误。

头信息规范

---
type: <必填,概念种类>      # 唯一硬要求
title: <显示名>
description: <一句话摘要>   # 强烈建议:索引/搜索靠它
resource: <底层资产 URI>   # 抽象概念可省略
tags: [<标签>, ...]
timestamp: <ISO 8601>
lang: zh                   # 本仓库 i18n 约定(可选扩展)
---

详细字段、保留文件名、链接规则见 references/okf-spec-cheatsheet.md。

处理代码 / PDF / 图片(OKF 原生支持弱,按本约定补)

背景见 docs/code-support-research-zh.md。

• 代码:type 用 Repository|Package|Module|Class|Function|Interface|Config|Script|Notebook;加扩展字段 language、symbol、signature;resource 用 GitHub permalink 带行号锚点 #L10-L40;关系链接用 calls: / depends-on: / deprecated-by: 前缀。正文必写 # Signature 和行为说明,别只贴代码。
• PDF:原件放 assets/,正文承载抽取出的文本/表格,# Source 注明页码。
• 图片:原件放 assets/,正文写图说 / OCR 文本(用多模态模型生成),否则图里的知识 agent 读不到。

反模式(别这么干)

• ❌ 把整本文档塞进一个巨型概念文件;
• ❌ 正文全是散文、没有结构,导致 agent 检索不到要点;
• ❌ 只贴代码不解释行为;
• ❌ 图片直接 ![](...) 嵌入就完事,不写图说;
• ❌ 跳过 validate_okf.py。

配套脚本

• scripts/scaffold_okf.py — 生成空 bundle 骨架。
• scripts/validate_okf.py — OKF v0.2 符合性校验(可独立使用)。

相关 Skill

• awesome-to-okf — 专门把 GitHub awesome 列表转成 OKF。
• book-to-okf — 把长文 / 书稿拆成 OKF 概念库。
• okf-to-book — 把 OKF bundle 发布为可视化文档站。