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

Что-то в AWR ведёт себя не так, как вы ожидаете. Это руководство идёт от симптомов к исправлениям: сначала проверки здоровья, затем проблемы базы данных, затем прерванные изменения исходных файлов. Каждый раздел даёт точную команду для выполнения и объясняет, как читать вывод. О повседневных командах см. Ежедневный рабочий процесс и Справочник CLI.

Шаг первый: выполните проверку здоровья

AWR поставляется со встроенной диагностической командой Doctor на двух уровнях:

awr --json doctor --database-only
awr --json doctor

--database-only проверяет саму базу данных SQLite: целостность, внешние ключи, версию схемы, идентичности миграций и объекты схемы, принадлежащие AWR.
Полный doctor дополнительно инспектирует выбранные исходные файлы и привязки между записями среды выполнения и файлами на диске.

Doctor открывает базу данных только для чтения. Он не мигрирует схему, не переиндексирует источники, не применяет ожидающие мутации, не истекает захваты и не удаляет потерянные файлы — поэтому его всегда безопасно запускать, даже на повреждённом проекте.

Как читать результаты Doctor

Doctor сообщает о проблемах явными находками, а не догадками:

schema_issues — отсутствующие или изменённые таблицы, столбцы, индексы или триггеры, принадлежащие AWR, проверенные по встроенным миграциям. Лишние объекты могут сосуществовать; Doctor не будет чинить определения или печатать их SQL.
foreign_key_check_error — некорректная ссылка помешала SQLite даже запустить проверку внешних ключей. Если вы видите это поле, база данных нездорова, и сообщённый ноль нарушений означает «мы не смогли их сосчитать», а не «всё в порядке».
Активные сессии — только информационно; старая запись не доказывает, что процесс мёртв.
Отсутствующие зависимости, висячие рёбра, недоступные источники, прерванные сохранения и повреждённые или незарегистрированные артефакты сообщаются как находки. Нечитаемые страницы или чужая (не AWR) база данных дают явные ошибки, а не вводящий в заблуждение статус.

Симптом: «AWR отклонил мой исходный файл»

Когда YAML-файл источника содержит синтаксическую ошибку или поле неверного типа, AWR завершается с кодом ошибки InvalidInput и структурированными деталями:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

Как это читать: pointer называет проблемное поле, используя собственный словарь вашего исходного файла (включая настроенные китайские имена полей); line и column отсчитываются от единицы. Чистые синтаксические ошибки могут иметь только координаты парсера, а некоторые поиски (такие как YAML-алиасы) сохраняют указатель с null-координатами — это не отклоняет в остальном корректный файл. rule называет невыполненное ожидание; repair описывает ожидаемую структуру. Команда никогда не редактирует файл и не повторяет отклонённое значение.

Частый случай: вы написали title: [Draft, Review], что YAML разбирает как список, но поле требует строку. Если запятая была задумана буквально:

title: "Draft, Review"

Для многострочных описаний используйте блочный скаляр YAML (|); корректный китайский текст и пути с пробелами полностью поддерживаются.

Симптом: «Мои изменения не появляются в запросах»

Вы отредактировали исходный файл, но AWR по-прежнему показывает старые факты. Выполните переиндексацию:

awr source reindex

Затем проверьте обе части отчёта: успех операции и полноту проекции. Сканирование может пройти успешно, пока проекция остаётся неполной, потому что сканирование наблюдает источники без импорта их изменённых фактов. Тот же отчёт приходит как JSON с --json и через MCP awr_source_reindex. Сравнивайте вывод от эквивалентных начальных снимков; сама переиндексация обновляет состояние источника.

Если свидетельства элемента работы выглядят странно, work show (или MCP awr_work_get) сообщает evidence_groups рядом с плоским списком evidence. У каждой группы один точный указатель места; ссылка на источник и проверенный отчёт по одному и тому же пути остаются раздельными, и группировка никогда не переносит верификацию между записями.

Симптом: «База данных повреждена или потеряна»

Ваши исходные файлы авторитетны для фактов проекта, но база данных SQLite (.awr/state.db) также хранит состояние, которого эти файлы не содержат: сессии, захваты, контрольные точки, события времени выполнения, регистрации артефактов и попытки мутаций. Переиндексация обновляет проекции из источников, но не может восстановить эту историю времени выполнения — как не может и инициализация свежей базы данных из тех же источников.

Правильное резервное копирование

Для восстановимого снимка храните всё это вместе и приостанавливайте пишущих в проект на время сборки (API резервного копирования SQLite даёт согласованный образ базы данных, но не делает снимок окружающих файлов):

Согласованная резервная копия .awr/state.db, сделанная через API резервного копирования SQLite или эквивалентный инструмент, — копирование файла при активных пишущих может пропустить зафиксированные записи, ещё находящиеся в журнале упреждающей записи.
Соответствующие исходные файлы, ревизия Git, .awr/project.toml, конфигурация авторизованного корня и любые явно авторизованные внешние источники.
Управляемые файлы артефактов, зарегистрированные локальные артефакты вне управляемого каталога и журналы восстановления и снимки .awr/mutations, на которые ссылаются ожидающие операции.

Восстановление

Остановите проект.
Восстановите по записанному каноническому корню; сохраните вытесненное состояние вместо его удаления.
Выполните awr --json doctor --database-only, затем полный awr --json doctor.

Восстановление может вернуть регистрацию артефакта, когда его файл всё ещё отсутствует, — восстановите файл или оставьте находку неразрешённой. awr source reindex — это ни восстановление времени выполнения, ни инструмент перемещения базы данных.

Doctor может выполнять именованные починки, но только с текущей ревизией проекта, выбранным объектом и причиной; починки сохраняют источники и несвязанное состояние времени выполнения. Если целостность базы данных нарушена, предлагаемые починки времени выполнения отключены — никакой автоматической реконструкции.

Симптом: «Мутация была прервана посреди записи»

AWR применяет одобренные предложения к вашим исходным файлам с гарантиями долговечности: неизменяемые снимки «до/после» сохраняются до того, как попытка записывается, а успех требует предполагаемых байтов источника, перестроенной проекции и финального события применения. Если процесс умирает посреди записи, попытка остаётся открытой и восстановимой.

Если вы получаете MutationIncomplete с write_outcome: pending_recovery, сначала проинспектируйте:

awr --json doctor
awr --json proposal show PROPOSAL_ID

Прочитайте текущую project_revision из вывода, затем возобновите предложение:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

Что делает восстановление, зависит от того, как далеко зашла попытка:

Состояние после прерывания	Что делает восстановление
Снимки существуют, журнала применения нет	Источник не изменён; может начаться свежее `proposal apply`.
Журнал существует, источник всё ещё совпадает со «до»	Перепроверяет владение, конфигурацию, источник и ревизию, затем устанавливает записанные байты «после».
Источник уже совпадает со «после», проекция неполна	Перестраивает проекцию без перезаписи файла.
Проекция зафиксирована, финальное событие отсутствует	Проверяет проекцию и фиксирует финальное событие — без второй записи файла.
Финальное событие зафиксировано, ответ потерян	Возвращает долговечную квитанцию; повтор восстановления завершается с `InvalidTransition`, без дублирующего события.
Источник или снимки расходятся с записанным планом	Сохраняет источник, сообщает о конфликте, удерживает завершение.

Успешный повтор сообщает recovered, называет исходную попытку и привязывает её resolved_event_id к финальному событию.

Две вещи, которых делать не стоит:

Не редактируйте снимки, чтобы принудить исход. Если текущий источник не совпадает ни с одним снимком, разрешите конфликт источника и подготовьте новое предложение.
Не считайте, что повтор записал файл. source_write_performed описывает только текущий вызов — именно поэтому восстановление сначала перепроверяет.

Конкурентность: пишущие AWR координируются через блокировку ОС на источник и транзакционные проверки expected_revision. Раздельные источники продвигаются независимо, но промежуточная ревизия проекта может потребовать явного повтора восстановления. Внешние редакторы не присоединяются к блокировке; проверки отпечатков обнаруживают их изменения.

Когда остановиться и попросить помощи

Останавливайтесь и эскалируйте вместо импровизации, когда:

Doctor сообщает о нарушенной целостности базы данных (foreign_key_check_error, нечитаемые страницы) — починки времени выполнения отключены, автоматической реконструкции нет.
Восстановление мутации сообщает о конфликте источника/снимков — поддерживаемый путь — новое предложение, а не ручное редактирование снимков или журналов.
Ваш сценарий включает отключение питания машины, распределённых пишущих или другие операционные системы — гарантии восстановления покрывают прерывание локального процесса; за пределами этого ничего не установлено.

Прежде чем просить о помощи или регистрировать проблему, зафиксируйте состояние, пока оно свежее:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

Держите вытесненную базу данных, журналы .awr/mutations и соответствующие исходные файлы нетронутыми — они делают отчёт действенным, и они — ваш запасной вариант, если исправление пойдёт не так.