Спецификация OKF v0.1 на русском: полный разбор

Термины спецификации

Knowledge Bundle (бандл) — самодостаточная иерархическая коллекция документов знаний, единица распространения. Концепт — единица знания внутри бандла, один markdown-документ: осязаемый актив (таблица, API) или абстракция (метрика, бизнес-процесс). Concept ID — путь файла внутри бандла без суффикса .md: файл tables/users.md имеет идентификатор tables/users.

Поля frontmatter

Каждый концепт — UTF-8 markdown-файл из двух частей: YAML-блок между разделителями — и свободное тело. Поля YAML:

Производитель может добавлять собственные ключи — потребители обязаны их не отвергать.

Зарезервированные файлы

index.md — оглавление каталога для «прогрессивного раскрытия»: агент сначала читает индекс и открывает только нужные концепты, экономя контекст. log.md — хронология изменений бандла. Оба имени зарезервированы на любом уровне иерархии и не могут использоваться для концептов. Единственное место, где разрешён frontmatter у index.md — корень бандла, там можно объявить okf_version: «0.1».

Кросс-ссылки и граф знаний

Концепты ссылаются друг на друга обычными markdown-ссылками — относительными путями внутри бандла. Так возникает граф связей, более богатый, чем иерархия каталогов. Цитаты-источники могут быть абсолютными URL, внутренними путями или ссылками в подкаталог references/, где внешние материалы зеркалируются как полноценные концепты.

Конформность

Бандл соответствует v0.1, если каждый незарезервированный .md содержит парсируемый frontmatter с непустым type, а index.md и log.md следуют своим разделам спецификации. Всё остальное — мягкие рекомендации: потребитель не вправе отвергнуть бандл из-за неизвестных типов, лишних ключей, битых ссылок или отсутствия index.md. Версионирование — major.minor: минорные версии добавляют обратно-совместимые поля, мажорные могут менять обязательные.