Здесь собраны точные правила команд, библиотек и MCP. Начните с первого запуска, если хотите попробовать OKF; этот раздел нужен для проверки деталей и ограничений.
Контракт документов — зафиксированная спецификация OKF 0.2 (оригинал на английском). Версия Go-модуля, версия плагина и значение okf_version независимы. Версию установленной программы показывает okf version --json; опубликованные версии перечислены в GitHub Releases.
| Входные данные | Как они трактуются |
|---|---|
Поддерживаемое объявление в корневом index.md |
Выбирает контракт документа: 0.2 или поддерживаемый старый 0.1. |
| Объявления нет | Применяется 0.2 с правилами подстановки старых полей из §13. |
okf_version присутствует, но повреждено |
Ошибка структуры индекса. Версия, выбранная для обхода файлов по умолчанию, не делает документ соответствующим формату. |
| Объявлена неизвестная будущая версия | Объявление сохраняется; программа читает знакомые данные, не заявляя соответствия будущей спецификации. |
Явный --spec 0.1 или --spec 0.2 |
Утверждение о версии. Конфликт с объявлением приводит к ошибке, а не к его замене. |
Записывайте okf_version только в корневом index.md. Две зафиксированные редакции исходной спецификации называются 0.2: по умолчанию используется date-3fcbb9f; профиль instant-0b87c52 требует дату и время с часовым смещением в stale_after, sources[].last_modified и usage_window. Его выбирают через --temporal-profile instant-0b87c52 в поддерживающих этот флаг командах. Для превращения даты в момент нужны явно заданные время и часовой пояс. Выбор редакций описан в ADR 0003 (оригинал на английском).
go install github.com/skosovsky/okf/cmd/okf@latest
go install github.com/skosovsky/okf/cmd/okf-mcp@latest
okf version
okf version --json
okf init ./my-knowledge
okf validate --path ./my-knowledge --spec 0.2
init требует отсутствующий каталог с существующим родителем. Команда не перезаписывает существующий файл, каталог или символическую ссылку. См. контракт создания набора (оригинал на английском).
Минимальный набор, соответствующий формату, можно составить и из двух файлов:
index.md:
---
okf_version: "0.2"
---
# Заметки
* [Минимальная заметка](minimal.md) - Простейший пример.
minimal.md:
---
type: Unknown Producer Type
---
Простейший пример.
type — единственное поле, обязательное для каждой заметки. Сведения о происхождении, проверке, состоянии и вычислениях необязательны. Замените учебный текст сведениями из предоставленных материалов; последовательность действий приведена в первом запуске.
| Правило | Что из него следует |
|---|---|
Указывайте generated, только если известен создатель текста |
Автор транзакции, автор коммита, владелец файла и текущий пользователь не считаются создателем документа автоматически. |
Заполняйте sources по реальным материалам |
Связывайте утверждения со сносками по sources[].id. |
Записывайте verified после выполненной проверки |
Авторство, Git, время файла, миграция и проверка формата не создают проверенность, оценку достоверности, состояние или свежесть. |
| Сохраняйте неизвестные ключи, типы и содержимое | Будущие поля остаются доступны без ограничения типизированной моделью библиотеки. |
Выделяйте санкционированное вычисление в отдельную заметку type: Attested Computation |
Границы выполнения описаны в разделе о вычислениях. |
При чтении v0.2 используются generated и sources. Старое timestamp подставляется только при полном отсутствии generated, а # Citations — только при отсутствии sources. Присутствие замещающего поля, даже повреждённого, запрещает подстановку. Это правило одинаково для версии по умолчанию, объявленной и явно выбранной версии, включая v0.1 и будущие версии.
GeneratedPresent/SourcesPresent описывают наличие полей; TimestampAllowed/CitationsAllowed — отсутствие замещающих полей; TimestampActive/CitationsActive дополнительно требуют наличия самой старой формы. Для активных цитат нужен точный заголовок # Citations, распознанный парсером как раздел. Одна запись [1] в обычном тексте старой цитатой не считается: набор без объявления версии и только с таким текстом определяется как v0.2 с переходом target-noop.
Одиночное значение verified и список из одного элемента дают одинаковое типизированное представление без изменения YAML. Проверенность выводится только из verified; проверенность, исходное/эффективное состояние и устаревание отображаются отдельно. При одновременном наличии sources и старых цитат чтение предпочитает sources, сохраняя старые байты. Миграция блокируется с reconcile_sources_and_citations, а не объединяет и не удаляет эти данные.
Канонические примеры перечислены в реестре тестовых данных: минимальный пример, приложение A, проверки, состояние, вычисления, старые, смешанные и будущие версии, а также намеренно сложные случаи. Учебные примеры используют зарезервированные домены вроде example.invalid.
| Уровень | Что проверяется |
|---|---|
| Базовый | UTF-8, разбираемые метаданные YAML заметки, непустая строка type, структура служебных файлов. |
| Строгий | Рекомендательная проверка присутствующих полей v0.2, ссылок на источники, состояния и структуры вычислений. |
| Ссылки | Рекомендательная диагностика внутренних ссылок. |
| Покрытие индексами | Заметки, не перечисленные в индексах; проверяется только по запросу. |
Неизвестные типы, ключи и среды выполнения, отсутствующие необязательные поля, битые ссылки и отсутствующие индексы не становятся базовыми ошибками. Служебный индекс может начинаться с заголовка и вступления перед группами ссылок. Неизвестные ключи рядом с корректным okf_version сохраняются. Перенесённые строки одного элемента плоского списка log.md остаются одной записью. Строгая проверка ссылок на источники игнорирует буквальные сноски внутри фрагментов кода.
Для обработки Markdown, опирающейся на разбор структуры, действуют отдельные ограничения 16 МиБ: на полный документ (bundle.MaxMarkdownDocumentBytes) и на уже отделённый текст документа (bundle.MaxMarkdownBodyBytes). Порядок классификации ошибок: отмена, некорректный UTF-8, bundle.ErrMarkdownResourceLimit, затем ошибки разбора или принадлежности элементов. bundle.MarkdownResourceLimitError содержит вид ресурса, предел и наблюдаемый размер с защитой от переполнения. Методы с контекстом возвращают полностью нулевой результат при отказе. Эти пределы отличаются от суммарных ограничений поиска.
| Команда | Назначение |
|---|---|
init |
Создать черновой набор знаний в новом каталоге. |
setup |
Показать и применить план копирования обычных Markdown в новый управляемый набор. |
search |
Найти разделы, содержащие все слова запроса. |
validate |
Проверить контракт документа и дополнительные диагностические правила. |
info |
Посмотреть представления с учётом версии. |
parse |
Разобрать один документ; при необходимости вывести представления JSON. |
fmt |
Отформатировать документ; -w записывает его. |
index |
Составить навигационные индексы. |
graph |
Построить граф ссылок и, по выбору, типизированных связей. |
view |
Создать автономный HTML-просмотрщик; --lang en|ru задаёт исходный язык интерфейса, по умолчанию en. |
migrate-prepare |
Подготовить заполняемые файлы миграции вне исходного набора. |
migrate |
Показать и применить переход v0.1 → v0.2. |
temporal-upgrade |
Показать и применить явные замены дат на моменты внутри v0.2. |
version |
Показать версию программы и поддерживаемые версии документов. |
help |
Показать справку CLI. |
okf search ./knowledge --query "срок повтора" --limit 5 --json
okf setup --source ./notes --target ./prepared-knowledge --type Note --json
okf validate --path ./knowledge --spec auto --strict --as-of 2026-07-29
okf validate --path ./knowledge --check-links --check-orphans
okf validate --path ./knowledge --spec 0.2 --strict --temporal-profile instant-0b87c52 --as-of 2026-09-23T11:00:00Z
okf info ./knowledge --spec auto --as-of 2026-07-29
okf parse ./knowledge/minimal.md --temporal-profile instant-0b87c52 --as-of 2026-09-23T11:00:00Z --format json
okf fmt ./knowledge/minimal.md
okf fmt ./knowledge/minimal.md -w
okf index ./knowledge --spec auto
okf graph ./knowledge --profile skosovsky/okf-v0.2-instant --format ntriples --as-of 2026-09-23T11:00:00Z
okf view ./knowledge --output ./knowledge.html --lang ru
Для воспроизводимой оценки устаревания явно задавайте --as-of. Разбор, форматирование, индексация и построение графа не мигрируют происхождение данных, не добавляют автора или время, не создают проверки и не повышают okf_version. Неизвестные данные сохраняются без потерь в поддерживаемых изменениях, опирающихся на парсер. Законченные сценарии приведены в руководстве по инструментам.
| Пакет | Ответственность |
|---|---|
bundle |
Загрузка документов и ресурсов; YAML без потерь и типизированные представления v0.2. |
validator |
Базовая и строгая проверка, диагностика ссылок и покрытия индексами. |
graph |
Обычные ссылки, типизированные связи и форматы экспорта. |
retrieval |
Общий поиск по разделам для Go, CLI и MCP. |
setup |
Preview и привязанный к отпечатку плана Apply для обычных Markdown. |
viewer |
Построение представления и автономного HTML; Render использует английский язык, RenderWithOptions позволяет выбрать язык. |
mutation |
Предпросмотр и применение смысловых изменений через желаемое состояние. |
store |
Контракты транзакций, ревизий, проверки ожидаемого состояния и квитанций. |
store/fs |
Файловое хранилище с журналом для восстановления и устойчивой записи. |
backfill |
Извлечение ограниченных свидетельств Git, проверка предложений анализатора и подготовка проверенного восстановления истории. |
upkeep |
Фиксация исходного состояния репозитория, определение затронутых знаний и проверка решений по текущим отпечаткам. |
b, err := bundle.LoadBundle("./knowledge")
if err != nil {
return err
}
report := validator.ValidateBundle(b, &validator.ValidatorConfig{
Strict: true,
CheckLinks: true,
CheckOrphans: true,
})
if !report.IsConformant() {
return errors.New("bundle is not conformant")
}
Этот фрагмент использует импорты errors, github.com/skosovsky/okf/bundle и github.com/skosovsky/okf/validator внутри функции, возвращающей error.
Типизированные методы дают представления поверх YAML без потерь и возвращают защитные копии. Для неизвестных данных доступны Get, узлы YAML и структуры вызывающей программы: подход Bring Your Own Types. Исходные метаданные и текст остаются доступны и не принудительно переводятся в закрытую схему. Файлы источников и вычислений, отличные от Markdown, входят в ревизию как пассивные ресурсы; чтение не запускает их и не загружает содержимое из сети.
Изменение сначала строит временный результат, проверяет итоговый набор, сохраняет оформление нетронутых частей и записывает через проверку ожидаемого состояния (CAS) с журналом. Смысловая миграция отделена от разбора, форматирования, индексации и графа. Авторы транзакций и форматы store.ChangeSet/квитанций независимы от авторов документов. Старые версии обмена и профилей меняются только по собственным контрактам.
search и MCP search_sections требуют наличия всех разных нормализованных слов в Markdown раздела, его заголовке или названии заметки. Применяются приведение регистра Unicode и NFC; склонения, перевод, синонимы и смысловой поиск не поддерживаются. Markdown-код — пассивный текст для поиска, а не инструкция к выполнению; псевдозаголовки внутри блоков кода не делят документ на разделы. Индексы и журналы исключены из поиска.
Результаты содержат исходные фрагменты, включительные номера физических строк, адреса с процентным кодированием пути, SHA-256 всего файла и отпечаток снимка. После изменения файла сравните отпечаток или повторите поиск. Отпечаток не является ревизией хранилища, разрешением на запись или доказательством истинности содержания. Ранжирование использует лексический BM25 (k1=1.2, b=0.75; веса Markdown/заголовка/названия 1/3/2); при равенстве порядок определяется идентификатором заметки и начальной строкой.
| Ограничение поиска | Значение |
|---|---|
| Запрос / разные слова / нормализованное слово | 1–512 символов Unicode / 32 / 4096 символов |
| Число запрошенных результатов | 1–100; по умолчанию 20 |
| Файлы снимка / сумма байтов / один файл | 10 000 / 64 МиБ / 16 МиБ |
| Разделы / индексируемые слова | 100 000 / 1 000 000 |
| Глубина каталогов / байты пути | 64 / 4096 |
| Заголовок и название / фрагмент текста | По 1024 байта UTF-8 / 512 символов Unicode |
| Ответ JSON | 1 МиБ |
total считает подходящие разделы; truncated сообщает о пропущенных результатах. Курсора и постоянного индекса нет. Уточните слова или увеличьте предел до 100. Превышение ограничения, ошибка разбора и отмена завершаются отказом без частичных результатов. Загрузка исключает внутренние символические ссылки и отклоняет корень-ссылку или выход за пределы корня. Полный контракт поиска.
setup сохраняет исходник и показывает план копирования в новый каталог. Просмотрите план и передайте его точный отпечаток для применения; изменения исходника, занятый целевой путь и неподдерживаемые ссылки или ресурсы блокируют запись. Тип заметки задаётся явно; подготовка не выводит источники, автора, проверенность или свежесть. Полный контракт подготовки Markdown.
Сервер не принимает флаг -root. Каждый вызов передаёт доступный абсолютный bundle_path; доступ к файлам определяется разрешениями клиента и процесса. Пошаговое подключение.
{"mcpServers":{"okf":{"command":"okf-mcp","args":[]}}}
| Инструмент | Действие |
|---|---|
list_concepts |
Перечислить документы. |
read_concept |
Прочитать исходные и интерпретированные данные документа. |
validate_bundle |
Проверить набор знаний. |
get_semantic_graph |
Получить представление графа. |
write_concept |
Совместимый интерфейс записи. |
search_concepts |
Ограниченный поиск буквальной подстроки. |
search_sections |
Ранжированные разделы со всеми словами запроса. |
get_neighbors |
Соседи по навигации и типизированным связям; источники происхождения перечисляются отдельно. |
preview_concept_patch |
Показать план изменения через желаемое состояние. |
apply_concept_patch |
Применить правку с проверкой ревизии и отпечатка плана. |
preview_v02_migration |
Показать план миграции старых данных. |
apply_v02_migration |
Применить соответствующий план миграции. |
preview_temporal_upgrade |
Показать план явных замен дат на моменты. |
apply_temporal_upgrade |
Применить соответствующий план замены дат. |
Всего инструментов четырнадцать. Совместимые инструменты сохраняют текстовые ответы для старых клиентов. Структурированные ответы проверяются по схемам. search_concepts и get_neighbors возвращают total/truncated, когда ограниченный ответ пропускает результаты или связи. Курсора нет: уточните входные данные либо запросите весь граф, если он укладывается в ограничения. Превышение resource_limit завершает вызов ошибкой, а не частичной страницей. Некорректные входные данные возвращают стабильные коды и ограниченную по размеру подсказку по полям. Контракт запросов.
search_concepts ставит совпадения идентификатора и метаданных перед совпадениями текста; это буквальный поиск, отдельный от ранжирования разделов.
Для применения правки нужны expected_revision и отпечаток плана из предпросмотра. У миграции другой контракт подтверждения. Метаданные автора не являются аутентификацией. Пути набора проверяются на нахождение внутри корня и обход символических ссылок; значение ресурса не даёт права обращаться к файлам, сети, оболочке или секретам. Границы доверия при изменении данных.
Поля MCP, содержащие автора, имеют ограничение передачи в 256 байт, проверяемое до правил предметной области. При 257 и более байтах возвращается resource_limit, а не ошибка автора. Внутри предела смысловую корректность определяет общий ValidActor. Это ограничение адаптера, а не правило длины автора для документов или хранилища.
В структурированном JSON MCP каждый присутствующий usage_count — каноническая десятичная строка по шаблону ^(0|[1-9][0-9]*)$ либо null, если выходное поле допускает его. Входная правка отклоняет переполнение uint64. Строки защищают от потери точности float64 при декодировании аргументов, включая MaxUint64; прежний текстовый ответ сохраняется.
| Операция | Допустимые формы выбора |
|---|---|
set_usage_window |
Общее окно: нет source_id и source; источник по идентификатору: непустой source_id; точный безымянный источник: есть source, у него отсутствует id. |
remove_source |
По идентификатору или точный безымянный источник по тем же правилам. Общей формы нет. |
Пустой source_id, смешение форм, неизвестные формы и неоднозначное совпадение безымянного источника отклоняются. Метаданные источника не сопоставляются через предполагаемый идентификатор.
В руководстве по миграции есть воспроизводимый пример. Здесь определено подробное поведение.
Каждое переданное поле автора, времени, цитаты, отдельной даты создания, вычисления и ресурса проверяется до определения исходного формата и планирования перехода, даже для набора без корневого индекса или target-noop. Некорректное поле отклоняется, а не игнорируется. Отдельное поле миграции, которое невозможно корректно отобразить, даёт invalid_request.
Старое время не содержит автора. Для превращения его в generated.at вызывающая программа должна передать generated.by. CLI --actor задаёт этого создателя документа, а не store.ChangeSet.Actor; адаптер использует отдельного внутреннего автора транзакции. В предпросмотре автора можно не указать и получить provide_generated_by; запись изменения с generated требует автора. Конфликт timestamp/generated.at требует явной политики. CLI сохраняет старое время и отклоняет конфликты. Набор старых заметок только с типом, без времени, меняет лишь версию корня: автор и время не нужны, generated не создаётся.
Явные пути для цитат, даты создания и вычисления должны указывать на существующие документы набора. Отсутствующий путь блокирует миграцию с migration_document_missing и пустым списком ручных действий; сопоставления не создают отсутствующий документ.
Миграция не выводит названия источников, авторов, использование и дату изменения, привязки утверждений, проверенность и доверие, состояние и срок устаревания, достоверность, квитанции и вердикты, успешную аттестацию или вычисление из повествовательного текста.
CLI --citation-mappings <json-file> и MCP принимают один и тот же закрытый массив; внешнего объекта-обёртки нет:
[{"path":"retries.md","entries":[{"legacy_number":1,"source_id":"requirements","title":"Учебные требования","resource":"https://example.invalid/requirements"}]}]
| Поле | Правило |
|---|---|
path |
Путь Markdown относительно набора, включая корневой index.md, журналы и вложенные файлы; не идентификатор заметки. |
legacy_number |
Ненулевой номер выбирает запись цитаты [n], распознанную парсером. |
legacy_entry |
Точный исходный текст записи, включая ненумерованный пункт или URL. Нужен хотя бы один способ выбора. |
| Оба поля выбора | Оба должны совпадать с одной записью. |
source_id |
Явно заданный устойчивый идентификатор. При повторном использовании метаданные должны совпадать. |
title, resource |
Необязательные явные метаданные. Название или адрес не угадываются. |
legacy_entry должен быть корректным UTF-8 длиной 1–4096 байт, непустым после проверки strings.TrimSpace и без NUL. TAB/LF/CR разрешены; остальные управляющие символы C0 и DEL запрещены. При сопоставлении пробелы не удаляются, регистр не приводится, URL и переводы строк не нормализуются. Точные байты входят в разрешение и отпечаток: LF и CRLF различаются.
Повторные ненулевые номера в одном документе запрещены. Повтор исходного legacy_entry допустим только в разных полных парах номер+текст. Выбор только по тексту пересекается с любым повтором этого текста; два одинаковых выбора только по тексту тоже запрещены. Совпадение выбора только по тексту с дублированными записями неоднозначно. Канонический порядок: путь, номер, точный исходный текст. Неизвестные поля, небезопасные пути, превышенные размеры значений/файлов/массивов, несовпадающие метаданные и неполные сопоставления отклоняются.
Загрузчик CLI ограничивает JSON-файл 16 МиБ, число документов — 10 000, суммарное число записей — 10 000, строки — 4096 байт, legacy_number — 1 000 000, глубину JSON — 16. Это ограничения входного файла, а не общие пределы Markdown. Реализация загрузчика.
Меняются только ссылки на утверждения, принадлежность которых парсер Markdown может доказать. Неоднозначные, дублированные или неразрешённые элементы блокируют миграцию. Строчный и блочный код, а также исходный HTML непрозрачны для этих преобразований: похожий на маркер текст в них не подтверждает и не нарушает проверку повторного применения. Буквальный [^label] в однострочном или многострочном фрагменте кода не учитывается; настоящая краткая ссылка на сноску в обычном тексте учитывается.
При v0.1-to-v0.2 номер выбирает запись в активном старом разделе цитат. При target-noop явное сопоставление проверяет уже мигрированное состояние: должна совпасть именованная сноска, а для заметки — также структурированный идентификатор источника и переданные метаданные. Обычный текст [1] не преобразуется. Активный старый раздел на целевой v0.2 блокирует повторное применение.
Для каждого ненулевого legacy_number выбранный парсером маркер [n] должен исчезнуть, а нормализованная ссылка [^SourceID] — появиться. При выборе только по тексту требование ссылки на утверждение отсутствует. Оставшийся выбранный маркер, отсутствующая или неправильная ссылка дают migration_replay_mismatch с точным диапазоном парсера, без выдуманного ручного действия, подтверждения или разрешения плана.
Совпадение нормализованных идентификаторов источников или меток сносок в одном документе блокируется с normalized_footnote_label_collision и disambiguate_citation_entry, в том числе при target-noop. Для столкновения с существующим документом указывается тот же точный диапазон. Это отличается от отдельного неотображаемого поля (invalid_request). Оба исхода не записывают данные.
Исходный формат определяется ровно один раз перед предпросмотром. Предпросмотр и применение используют один полный expected_source: requested_selector, состояние объявления (declaration_present, declaration_valid, declaration_raw, declared_version), определённую версию и её происхождение, поля перехода, упорядоченные старые признаки и препятствия. Применение отклоняет изменение определения или его оснований. Повреждённая версия корня не считается отсутствующим объявлением или значением по умолчанию; неподдерживаемая корректно объявленная будущая версия остаётся объявленной и блокирует миграцию v0.1.
| Переход | Что нужно для применения |
|---|---|
v0.1-to-v0.2 |
Подтверждение предпросмотра format_version: 2, непустые resolution_digest и expected_plan_digest, полностью тот же expected_source. Старые форматы подтверждения отклоняются. |
Текущий target-noop через MCP |
Тот же зафиксированный expected_source, без подтверждения и отпечатка плана; входные данные целевого состояния всё равно проверяются. |
| Заблокированный предпросмотр | Применение запрещено. |
Отдельного миграционного expected_revision нет: если подтверждение есть, авторитетна proof.base_revision. Успешный предпросмотр перехода с непустым отпечатком плана возвращает подтверждение без содержимого файлов. Оно фиксирует запрос и определение исходной версии, отпечатки ревизий, читаемые пути, записываемые пары путь+отпечаток, удаления, переименования, затронутые и обратные зависимые ссылки, сводки изменённых файлов и ссылок. Массивы не равны null. Байтов файлов, метаданных YAML и текста в подтверждении нет. Предпросмотр MCP без изменений или с блокировкой не возвращает подтверждение.
Применение с подтверждением перехода может вернуть отсутствие изменений только после проверки и повторного построения точного подтверждения и отпечатка плана. Возврат происходит до открытия хранилища; .okf не создаётся.
Перед атомарной записью весь подготовленный набор должен пройти проверку v0.2. Физическая запись или переименование корневого index.md выполняется последним: изменение версии корня — заключительная видимая публикация транзакции. Неизвестные YAML, Markdown и ресурсы сохраняются.
Любой предпросмотр, отказ, блокировка, некорректный запрос, отмена и другой путь без публикации сохраняет полное дерево файлов: те же пути и байты, без .okf и временных артефактов. Публиковать изменения может только разрешённая действительная транзакция. Точный повтор успешного применения возвращает записанный результат без второй публикации.
Поведение target-noop зависит от адаптера:
| Интерфейс | Хранилище и квитанция | Файлы набора |
|---|---|---|
Текущий target-noop MCP |
Без подтверждения; хранилище не открывается; .okf отсутствует. |
Те же пути и байты. |
| CLI без записи | Строит подтверждение, не открывая хранилище. | Те же пути и байты. |
CLI с --write |
Проводит пустую CAS-транзакцию; устойчиво создаёт или воспроизводит квитанцию в .okf. |
Файлы, входящие в ревизию, имеют те же пути и байты. |
Запись через CLI в этом случае действительно публикует квитанцию; правило отсутствия артефактов для путей без публикации к ней не относится. Подтверждение устойчивой записи транзакции (store.CommitReceipt) и квитанция среды выполнения вычисления (executor.receipt) — разные контракты.
| Код | Что нужно разрешить |
|---|---|
provide_citation_mapping |
Нет сопоставления, оно не разрешено либо номер и исходный текст противоречат реальной цитате. |
disambiguate_citation_entry |
Повторное совпадение номера/текста либо столкновение нормализованных источников или меток сносок. |
disambiguate_citation_destination |
Парсер не может однозначно определить адрес ссылки. |
normalize_citations_section |
Дополнительное содержимое старого раздела непрозрачно либо не принадлежит распознанной структуре. |
reconcile_sources_and_citations |
Структурированные источники сосуществуют со старым разделом. Объединение, удаление повторов и удаление данных не выводятся автоматически. |
repair_invalid_utf8 |
Некорректный UTF-8. |
provide_generated_at |
Не указано необходимое время создания. |
provide_generated_by |
Не указан необходимый создатель текста. |
Неоднозначный выбор повторного исходного текста отличается от неоднозначности адреса ссылки. migration_document_missing и migration_replay_mismatch — блокирующие ошибки без придуманного кода ручного действия. См. контракт подготовки миграции с заполняемыми файлами и точными диапазонами байтов и нормативные правила миграции (оригиналы на английском).
Это отдельная операция, не миграция v0.1. Задайте замену для каждой обнаруженной даты в stale_after, usage_window.from/to и sources[].last_modified. Программа не подставляет полночь или конец дня. sources[N] использует позицию с нуля в ревизии предпросмотра. Неразрешённые значения блокируют применение.
{"mappings":[{"concept":"payments/retries","path":"stale_after","from":"2026-09-26","to":"2026-09-26T18:00:00+07:00"}]}
Сохраните полный файл сопоставлений как temporal-mappings.json. Просмотрите план и используйте точные preview.BaseRevision и plan_digest из ответа:
okf temporal-upgrade ./knowledge --id temporal-2026-09 --actor human:reviewer --mappings temporal-mappings.json
okf temporal-upgrade ./knowledge --id temporal-2026-09 --actor human:reviewer --mappings temporal-mappings.json --write --base-revision 'sha256:<preview.BaseRevision hex>' --plan-digest 'sha256:<preview plan_digest hex>'
Применение заново строит план по текущей ревизии и публикует одну транзакцию. Если файлы изменились, повторите предпросмотр и проверьте позиции и отпечаток. Неподдерживаемое оформление YAML, например ссылка-псевдоним или помеченное тегом значение в кавычках, безопасность замены которого нельзя доказать без потерь, приводит к отказу. Перепишите это значение без кавычек, обычным скаляром либо с базовым тегом, и повторите предпросмотр. Для чтения результата выберите instant-0b87c52; профиль дат остаётся исходным. Контракт обновления времени (оригинал на английском).
relations — расширение и правило инструментов skosovsky/okf, а не часть исходного OKF v0.2. Обычные Markdown-ссылки остаются стандартным способом навигации и отношений. Профили графа (skosovsky/okf-v0.2, skosovsky/okf-v0.2-instant, legacy-v0.1) независимы от версии документов. Поддерживаются экспорты dot, mermaid, json-ld и ntriples; дополнительные связи включаются явно через --extension-relations include.
Грамматика ссылки связи — <escaped-concept-id>[#<fragment>]. Только #, входящий в идентификатор, экранируется логическими двумя байтами \#; первый неэкранированный # начинает фрагмент:
| Логическая ссылка | Значение |
|---|---|
source#part |
Заметка source, фрагмент part. |
source\#part |
Заметка с идентификатором source#part, без фрагмента. |
После разделителя обратные косые черты — обычные байты фрагмента. Лишние или неканонические экранирования идентификатора (source\part, source\, source\\#part) отклоняются. Существующие ссылки без экранированного # сохраняют точные байты. YAML допускает 'source\#part'; в JSON это "source\\#part", поскольку обратная косая черта экранируется. Дополнительная каноническая запись не меняет структуру схем графа и MCP. Квитанция хранилища v1 сохраняет ссылки как []string с каноническим лексическим порядком передачи; поддержка экранированного # исправляет нормализацию, а не мигрирует формат.
OKF записывает контракты вычисления и аттестации. computation, executor.resource и attester.resource — пассивные данные. Присутствие этих полей не запускает содержимое. Для выполнения нужны отдельно выбранная доверенная среда и разрешение.
Зафиксированная спецификация разрешает агенту задавать значения только объявленных параметров и запрещает ему создавать или редактировать санкционированное вычисление. OKF v0.2 не определяет обнаружение среды выполнения, реализацию привязки параметров, формат передачи квитанции/вердикта, ABI аттестатора, переносимость, изоляцию и кэш. Инструменты не придумывают эти механизмы. store.CommitReceipt не хранится и не принимается в качестве executor.receipt.
Инструкции внутри текста не могут отменять метаданные YAML, сведения о состоянии и свежести, разрешения или правила доверенной среды выполнения. Текст LLM не является вердиктом аттестации.
| Навык | Назначение и необходимые инструменты |
|---|---|
open-knowledge-format |
Создание, чтение, проверка, экспорт и миграция; установленный okf или подключённый okf-mcp. Привязан к спецификации v0.2. |
okf-maintain |
Проверка знаний репозитория после изменения кода или контрактов; дополнительно нужен okf-upkeep. |
okf-backfill |
Восстановление истории Git с опорой на свидетельства; нужны okf-backfill, backfill/PROTOCOL.md и его схемы. |
Скопируйте выбранный каталог из skills/ в каталог навыков клиента, сохраняя относительные ссылки. Файлы навыка не устанавливают программы и не предоставляют разрешения. Проверьте реальную регистрацию в клиенте и подключение инструментов; руководство по навыку показывает первый вызов.
Если MCP отсутствует, проверьте установленный CLI или запуск Go-команды из исходников. Если недоступны оба пути, отдельно сообщите о ручном просмотре: он не равен выполненной инструментальной проверке. Файл просмотрщика должен быть локальным и находиться вне набора; замена существующего файла требует разрешённого --overwrite.
okf-maintain фиксирует исходное состояние перед изменением репозитория, сравнивает затронутые заметки с кодом и контрактами и записывает обновление либо обоснованное решение об отсутствии влияния, привязанное к итоговому отпечатку. okf-backfill последовательно выполняет извлечение Git, анализ по свидетельствам, проверку плана, разрешённое применение и независимую проверку через конвейер Go.
skills.sh.json, оба манифеста плагинов и skills-lock.json регистрируют три навыка. skill-dependencies.json перечисляет зависимости сценариев по имени и пути без копирования схем. CI сверяет зависимости с каталогом MCP и диспетчером CLI, проверяет ссылки и ресурсы, затем копирует только skills/ в изолированный каталог установки. Проверка пакета использует парсер YAML на Go и разрешает обычные и именованные Markdown-ссылки внутри установленного дерева.
go test ./...
go vet ./...
git diff --check
node scripts/update-skills-lock.mjs --check
node scripts/check-skill-package.mjs
Пересчитайте файл фиксации навыков после завершения изменений содержимого и ссылок. Проверка файлов и пакета подтверждает упаковку, но не активацию навыка или вызов инструментов в Codex, Claude Code или skills.sh. CI не запускает эти клиенты: каждое заявление о поддержке клиента проверяйте настоящим вызовом перед публикацией.
Собственный публичный набор знаний репозитория начинается с knowledge/index.md; описание знаний репозитория объясняет поддержку. Его опубликованный просмотрщик — воспроизводимый снимок, отдельный от двуязычного учебного примера.