Устранение неполадок

Симптомы сгруппированы по тому, где они появляются на пути от установки до экспорта, с самыми частыми сбоями новичков в начале. Каждая запись называет причину и команду исправления.

🚧 Установка и окружение

uv sync завершается с ошибкой

Причина: Python 3.12 или новее отсутствует в PATH, или отсутствует uv. Исправление: Подтвердите версию Python, затем выполните повторно:

uv sync --all-extras --group dev

Если uv отсутствует, установите его согласно официальным инструкциям пакета Astral, откройте новую оболочку и выполните команду повторно.

Установщик сообщает об отсутствующем предварительном условии

Причина: Скрипты установки требуют наличия git и uv в PATH. Исправление: Установите названное предварительное условие, затем выполните повторно ту же команду установки. Задайте DISPATCHATLAS_HOME перед повторным запуском, когда checkout должен находиться вне каталога пользовательских данных по умолчанию.

Обновление сообщает об изменениях, но не применяет их

Причина: Проверки обновлений по умолчанию доступны только для чтения. Исправление: Задайте DISPATCHATLAS_REF равным тегу релиза или полному 40-символьному SHA коммита, затем явно примените обновление через отсоединённый checkout:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

Удаление отклоняет цель

Причина: Скрипты удаления отклоняют пустые пути, корни файловой системы, домашние каталоги и каталоги без сторожевого маркера рабочего пространства DispatchAtlas. Исправление: Задайте DISPATCHATLAS_HOME равным пути установленного checkout и выполните команду удаления повторно.

📦 Импорты

ModuleNotFoundError: No module named 'dispatchatlas'

Причина: Рабочее пространство не синхронизировано, или скрипт выполняется под интерпретатором Python вне окружения проекта. Исправление: Из корня репозитория синхронизируйте и запускайте скрипты через uv, чтобы окружение проекта было активно:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError при создании решателя

Причина: Опциональные тяжёлые бэкенды (точные решатели, обучаемые оценщики) остаются за extras и зондируются во время выполнения, никогда не импортируясь при импорте пакета. Ошибка называет отсутствующий extra, его назначение и любую лицензионную заметку. Исправление: Установите названный extra (например exact, exact-commercial или learning) или выберите решатель, чей бэкенд присутствует. Объявления зависимостей решателей перечислены в системе решателей.

🧪 Конфигурация и выполнение кампаний

CampaignConfigError при валидации кампании

Причина: Поле конфигурации не проходит валидацию — пустой id, неположительное зерно или бюджет, дублирующиеся имена протокола остановки, или пустой список бенчмарков, решателей или целей. Ошибка несёт путь несоответствующего поля. Исправление: Исправьте названное поле. Страница движка кампаний документирует каждый блок конфигурации, а experiments/configs/smoke-pilot.json — это полный рабочий пример:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError при получении задачи бенчмарка

Причина: id задачи отсутствует в каталоге поставщика, или простая строка была передана там, где ожидается ProblemId. Исправление: Оберните id (provider.get_problem(ProblemId("smoke-job-shop-0"))) и сначала перечислите доступные id с помощью provider.list_problem_ids() — см. учебные руководства.

Полная кампания отказывается выполняться

Причина: Кампания на стадии full отказывает в закрытую сторону с full-campaign execution requires statistical design approval, пока это одобрение не записано в конфигурации. Исправление: Выполняйте на стадии smoke или pilot для локальных проверок, или запишите одобрение статистического дизайна согласно готовности релиза перед включением полного выполнения.

Возобновление перепланирует вместо пропуска завершённых прогонов

Причина: Контрольная точка в .checkpoints/{campaign_id}.json защищена хешем конфигурации; любое изменение конфигурации делает её недействительной, а не переиспользует молча. Исправление: Держите конфигурацию неизменной для возобновления, или примите свежий план под изменённой конфигурацией. Контракт рабочего пространства описан в воспроизводимых кампаниях.

📤 Экспорты, отчёты и сайт

Экспорт анализа сообщает об отсутствующей контрольной точке

Причина: Команда dispatchatlas export ожидает завершённый каталог кампании с checkpoint.json, plan.json, environment.json и записями результатов. Исправление: Укажите --campaign-dir на каталог результатов кампании, а не на его родителя, или выполните кампанию повторно:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

Если --target-dir находится вне текущего рабочего каталога, передайте явный --authorized-output-root, содержащий пункт назначения.

Валидация данных портала завершается с ошибкой

Причина: Статические ресурсы сайта не синхронизированы с экспортом результатов портала. Исправление: Регенерируйте статические ресурсы. Команда по умолчанию читает зафиксированный, отфильтрованный по раскрытию экспорт результатов в exports/portal-results.json, поэтому выполняется без аргументов:

uv run python tools/build_site_assets.py

Передайте --result-source, чтобы опубликовать другой отфильтрованный по раскрытию экспорт portal-results.json:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

Если команда сообщает dispatchatlas site-assets: error, проверьте, что --result-source (или exports/portal-results.json по умолчанию) указывает на существующий файл portal-results.json, сгенерированный путём экспорта анализа.

Шлюз редактирования портала завершается с ошибкой

Причина: Токен, которому не место на публичной поверхности, достиг данных портала, поэтому сборка отказывает в закрытую сторону, чтобы публикуемое лицо читалось как универсальный инструментарий оптимизации планирования. Исправление: Ошибка перечисляет каждый нарушающий артефакт, путь поля и токен. Отредактируйте нарушающее поле в сборщике, который выдаёт этот артефакт (под tools/portal_contract.py или его исходным доказательством), чтобы только безопасные для публики производные доказательства достигали данных портала, затем регенерируйте:

uv run python tools/build_site_assets.py

Этот сбой отличается от отсутствующего экспорта портала: передача другого --result-source его не устраняет — нарушающий токен должен быть удалён в его источнике.

Сборка сайта не может найти страницу

Исправление: Запустите контрактные тесты сайта и сборку документации:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

Решатель отсутствует в рекомендациях

Причина: Отбор фильтрует по метаданным. Исправление: Проверьте в метаданных решателя поддержку целей, требуемые теги возможностей, статус опциональных зависимостей и видимость по уровню доказательств в системе решателей.

Всё ещё застряли? См. частые вопросы или откройте задачу в репозитории GitHub.