forgeplan import

forgeplan import считывает JSON-файл, созданный командой forgeplan export, и загружает каждый артефакт, ссылку и запись доказательства обратно в таблицы LanceDB текущего рабочего пространства. Это восстановительная часть пары экспорт/импорт для резервного копирования и единственный поддерживаемый способ восстановления состояния после деструктивной повторной инициализации.

Когда использовать

Восстановление рабочего пространства после rm -rf .forgeplan && forgeplan init -y (вы ведь сначала экспортировали, верно?).
Перемещение рабочего пространства между машинами, когда отслеживаемого git-ом markdown недостаточно (например, для сохранения полной истории оценок).
Откат неудачной forgeplan migrate путём повторной инициализации и импорта резервной копии до миграции.
Клонирование состояния рабочего пространства коллеги для отладки или воспроизведения ошибки.

Когда НЕ использовать

Для слияния двух активных рабочих пространств - import это восстановление, а не слияние. Конфликты требуют --force и могут перезаписать хорошие данные.
Для перестроения индекса LanceDB из markdown - для этого используется forgeplan scan-import, что безопаснее, поскольку markdown является источником истины (ADR-003).
Для импорта данных из другого инструмента - JSON-схема Forgeplan является внутренней. Поддерживаются только файлы, созданные forgeplan export.

Использование

forgeplan import [OPTIONS] <PATH>

Аргументы

  <PATH>  Путь к JSON-файлу экспорта

Опции

      --force    Перезаписать существующие артефакты
  -h, --help     Вывести справку
  -V, --version  Вывести версию

Примеры

Пример 1: Восстановление после повторной инициализации

forgeplan export --output backup.json
cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d)
rm -rf .forgeplan
forgeplan init -y
forgeplan import backup.json
forgeplan health

Канонический цикл аварийного восстановления. import восстанавливает каждый артефакт, ссылку и запись доказательства из JSON-резервной копии.

Пример 2: Принудительная перезапись при конфликте

forgeplan import backup.json --force

Без --force артефакты, которые уже существуют в рабочем пространстве, приводят к безопасному сбою импорта. Используйте --force только тогда, когда вы уверены, что резервная копия является источником истины.

Пример 3: Передача рабочего пространства между машинами

# на машине A
forgeplan export --output workspace.json
scp workspace.json machine-b:/tmp/

# на машине B
forgeplan init -y
forgeplan import /tmp/workspace.json
forgeplan list

Полезно, когда одного markdown недостаточно (например, если вам нужна история оценок, состояние устаревания или ссылки, которые хранятся только в LanceDB).

Как это вписывается в рабочий процесс

import - это инструмент восстановления/миграции, а не часть ежедневного цикла Shape → Validate → Code → Evidence → Activate. Он тесно связан с export:

Перед любой деструктивной операцией: forgeplan export --output backup.json
После повторной инициализации или отката миграции: forgeplan import backup.json
Проверка: forgeplan health должен показывать те же артефакты, ссылки и оценки, что и раньше

Для рутинной перестройки индекса (например, после git clone) предпочтительнее использовать forgeplan scan-import - он читает markdown, который является источником истины.

Примечания по безопасности

Всегда запускайте forgeplan health после импорта. Убедитесь, что количество артефактов, целостность ссылок и оценки R_eff соответствуют состоянию до экспорта.
--force является деструктивным. Он беззвучно перезаписывает существующие артефакты. Если сомневаетесь, импортируйте в свежее рабочее пространство init -y.
Формат JSON является внутренним и версионированным. Импорт резервной копии из гораздо более старой версии бинарного файла в более новое рабочее пространство может потребовать промежуточного шага forgeplan migrate.
Никогда не редактируйте JSON экспорта вручную. Это не файл конфигурации; ручное редактирование нарушит контрольные суммы и связи.
import затрагивает только LanceDB. Он не перезаписывает markdown-файлы в .forgeplan/adrs/, prds/ и т.д. Если markdown и JSON не совпадают, запустите scan-import после этого для согласования.

См. также

forgeplan export - вторая половина пары для резервного копирования
forgeplan init - деструктивный шаг, который обычно предшествует импорту
forgeplan scan-import - перестроение из markdown (предпочтительно для свежих клонов)
forgeplan migrate - недеструктивная альтернатива, когда изменилась только схема
forgeplan health - проверка после импорта