Миграция переносит старое время timestamp в generated.at и старые цитаты из # Citations в sources с именованными сносками. Она нужна владельцу уже существующего набора v0.1. Для обычных Markdown без OKF используйте подготовку документов. Чтение или форматирование старого файла само по себе его не мигрирует.
Выполните сборку из исходников по инструкции первого запуска в той же оболочке, затем сделайте собранную программу доступной для команд ниже:
export PATH="$demo_dir:$PATH"
okf version
Сохраните копию настоящего набора и выясните создателя текста и материалы каждой цитаты. Время миграции нельзя подставлять вместо исторического времени создания.
Ниже используются вымышленные учебные требования: доставка повторяется 24 часа, затем подключается оператор. Пример выполняется в новом временном каталоге; создаваемые файлы — предоставленные учебные материалы, а не сведения о реальном продукте.
migration_demo=$(mktemp -d)
cd "$migration_demo"
mkdir old-knowledge
cat > old-knowledge/index.md <<'EOF'
---
okf_version: "0.1"
---
# Заметки
* [Повторы доставки](retries.md)
* [Учебные требования](requirements.md)
EOF
cat > old-knowledge/requirements.md <<'EOF'
---
type: Note
title: Учебные требования
timestamp: 2026-06-01T10:00:00Z
---
# Учебные требования
Повторять доставку не дольше 24 часов; затем передать задачу оператору.
EOF
cat > old-knowledge/retries.md <<'EOF'
---
type: Note
title: Повторы доставки
timestamp: 2026-06-01T10:00:00Z
---
# Повторы доставки
Повторять доставку не дольше 24 часов; затем передать задачу оператору.[1]
# Citations
[1] [Учебные требования](requirements.md)
EOF
okf validate --path old-knowledge --spec 0.1
Утверждение заканчивается [1]. Свяжите этот номер в retries.md с устойчивым идентификатором источника requirements. path — относительный путь файла, а не идентификатор заметки. Верхний уровень JSON — массив.
cat > citation-mappings.json <<'EOF'
[
{"path":"retries.md","entries":[
{"legacy_number":1,"source_id":"requirements","title":"Учебные требования","resource":"requirements.md"}
]}
]
EOF
human:trainer — известный создатель этого учебного текста. Для настоящего набора укажите реального создателя; автор транзакции задаётся отдельно. Предпросмотр без автора вернёт ручное действие, если преобразованию нужен автор.
Следующая команда сохраняет отпечаток исходника вне набора, не изменяя его. Скопируйте source_sha256 из migration-inputs/preparation-report.json в приглашение ввода и выполните предпросмотр с заполненным сопоставлением. Для больших миграций помощник также создаёт пустые шаблоны; идентичность источника он за вас не подтверждает.
okf migrate-prepare old-knowledge --output-dir migration-inputs --format json
cat migration-inputs/preparation-report.json
printf 'Вставьте source_sha256 из отчёта: '
read -r source_sha256
okf migrate old-knowledge --to 0.2 --actor human:trainer \
--citation-mappings citation-mappings.json \
--prepared-source-sha256 "$source_sha256" --format json
Проверьте, что план меняет только ожидаемые документы: версия корня станет 0.2, старое время получит известного автора, цитата №1 станет источником requirements и сноской [^requirements]. Старое время сохраняется согласно политике CLI. При блокировке разрешите перечисленные ручные действия и повторите предпросмотр.
Между проверкой и применением сохраните входные файлы и исходный набор неизменными. CLI заново строит и проверяет план внутри команды; --prepared-source-sha256 дополнительно отклоняет изменённый исходник. После изменения исходника подготовьте новый каталог и заново проверьте план.
okf migrate old-knowledge --to 0.2 --actor human:trainer \
--citation-mappings citation-mappings.json \
--prepared-source-sha256 "$source_sha256" --write --format json
okf validate --path old-knowledge --spec 0.2 --strict
cat old-knowledge/retries.md
okf view old-knowledge --output migrated.html --lang ru
Ожидаемый результат: корневой index.md объявляет 0.2, у заметки есть generated.by: human:trainer, источник requirements указывает на requirements.md, а утверждение использует именованную сноску. Неизвестные поля и нетронутый текст сохраняются. Проверка формата подтверждает структуру, а содержание следует сверить с предоставленными требованиями.
| Ситуация | Следующее действие |
|---|---|
| Неизвестен создатель или время создания | Найдите реальные записи; не угадывайте. Переход только по типам без времени не требует ни автора, ни времени. |
| Повторную или ненумерованную цитату нельзя однозначно выбрать | Изучите отчёт подготовки, разрешите неоднозначность в исходнике и подготовьте заново. |
Одновременно есть sources и старый # Citations |
Явно согласуйте две формы; программа их не объединяет. |
| Изменился подготовленный исходник | Используйте новый каталог подготовки и проверьте новый план. |
| Путь документа неправильный или отсутствует | Исправьте путь; сопоставление не создаёт отсутствующий документ. |
Предпросмотр и отказ не записывают набор и не создают .okf. Настоящий CLI --write может создать там квитанцию транзакции, в том числе для уже преобразованного набора. См. точные правила миграции, правила выбора цитат и запись и отсутствие изменений.
Отдельная операция переводит календарные даты старой редакции v0.2 в дату и время с часовым смещением. Для каждого обнаруженного значения укажите реальное время и часовой пояс; программа не подставляет полночь. Используйте справочник обновления времени, сохраняя ревизию и отпечаток предпросмотра. Это не меняет okf_version на новый номер.