forgeplan_import

Загружает пакет JSON, созданный с помощью forgeplan_export, в текущее рабочее пространство. Каждый артефакт в пакете вставляется в LanceDB, его тело в формате Markdown перепроецируется в .forgeplan/{kind}s/, и каждая связь восстанавливается. Основные варианты использования - восстановление после повторной инициализации, миграция между машинами, заполнение конвейеров CI эталонным рабочим пространством и восстановление после случайного удаления, если существует предыдущий экспорт.

Категория: Рабочее пространство и данные

Когда агент вызывает это

После forgeplan init -y в новом рабочем пространстве - заполните его из резервной копии или общего пакета.
На новой машине разработчика - клонируйте репозиторий, запустите forgeplan init, затем импортируйте общий экспорт команды.
В CI - воспроизведите детерминированный набор артефактов перед запуском интеграционных тестов против сервера MCP.
Аварийное восстановление - рабочее пространство было стёрто, но у вас есть недавний JSON-файл forgeplan_export.

Идемпотентность и поведение при коллизиях

По умолчанию (force=false): существующие артефакты с тем же ID пропускаются. Импортёр логирует количество пропущенных элементов, чтобы агент мог сообщить об изменениях.
force=true: существующие артефакты с тем же ID перезаписываются (метаданные и тело). Связи применяются повторно; дубликаты удаляются по (from, to, type).
ID в пакете сохраняются. Если рабочее пространство пусто, импорт фактически является чистым восстановлением.
Операция не является транзакционной для всего пакета в классическом смысле - она записывает артефакты по одному. Если что-то не удаётся на полпути, уже записанные артефакты остаются. Всегда выполняйте forgeplan_export свежей резервной копии перед импортом с force=true.

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

forgeplan_import изменяет рабочее пространство. Всегда сначала делайте экспорт для безопасности.
Пакет не содержит ключи API - после импорта вам всё равно потребуется перенастроить .forgeplan/config.yaml (провайдер LLM, Hindsight, Orchestra).
Производные индексы (.forgeplan/lance/) перестраиваются на лету по мере записи артефактов; вам не нужно запускать forgeplan scan-import после этого.

Входные параметры

Имя	Тип	Обязательный	Описание
`data`	`string`	yes	Экспорт JSON в виде строки. Передайте полное содержимое пакета, созданного с помощью `forgeplan_export`. Для больших пакетов предпочтительнее использовать CLI, который может читать из файла.
`force`	`bool`	no (по умолчанию: `false`)	Перезаписывать артефакты, которые уже существуют по ID. Используйте с осторожностью.

Источник схемы: crates/forgeplan-mcp/src/server.rs::ImportParams

Возвращает

Количество плюс любые предупреждения, выданные импортёром:

{
  "status": "ok",
  "artifacts_imported": 187,
  "artifacts_skipped": 0,
  "relations_imported": 312,
  "relations_skipped": 4,
  "force": false,
  "warnings": []
}

При force=true ответ различает вставки и перезаписи:

{
  "status": "ok",
  "artifacts_inserted": 14,
  "artifacts_overwritten": 173,
  "relations_imported": 312,
  "force": true
}

Пример вызова

Чистое восстановление в пустое рабочее пространство:

{ "data": "{\"version\":1,\"artifacts\":[…],\"relations\":[…]}" }

Принудительная перезапись во время миграции:

{
  "data": "{\"version\":1,\"artifacts\":[…],\"relations\":[…]}",
  "force": true
}

Типичная последовательность

forgeplan_init                    ← новое рабочее пространство (создаёт таблицы + каталоги)
forgeplan_import (data=bundle)    ← загружает снимок
forgeplan_list                    ← проверяет количество
forgeplan_health                  ← подтверждает форму рабочего пространства

Восстановление после несчастного случая:

forgeplan_export → safety.json     (всегда держите одну копию)
…что-то идёт не так…
rm -rf .forgeplan && forgeplan init -y
forgeplan_import (data=safety.json)

Эквивалент CLI

forgeplan import <file> - читает непосредственно из файла, более эргономично для больших пакетов.

См. также

Обзор MCP
forgeplan_export - создание пакета
forgeplan_init - создание рабочего пространства перед импортом
forgeplan_list - проверка импорта