Если CodeGraph не запускается, проект не виден или анализ возвращает ошибку,
doctor помогает определить область сбоя: конфигурацию, проект, CPG или сервисы.
Соберите отчёт, выберите проверку по симптому и выполните предложенное действие
для нужного проекта. Перед восстановлением проверьте целевые данные, резервную
копию и способ отката.
1. Соберите общую диагностику
Установите CLI по руководству. Откройте PowerShell в корне исходного репозитория установленной версии. Для сервисных проверок нужны доступные сервисы CodeGraph.
$env:CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI = '1'
python -m src.cli doctor --json > 'doctor-report.json'
$doctorExit = $LASTEXITCODE
$diagnostics = Get-Content -Raw 'doctor-report.json' | ConvertFrom-Json
Файл сохраняется в текущем каталоге и перезаписывает прежний отчёт. Для обычных проверок
doctor код 0 означает успех, 1 — предупреждение, 2 — ошибку. Проверяйте $doctorExit
вместе с результатами отдельных проверок. Поле overall_status показывает общий результат,
primary_issue — основную проблему, а checks — результаты по областям.
Каждая проверка содержит id, status, summary и предложенное действие suggested_action.
Разберите статус каждой проверки:
status |
Следующий шаг |
|---|---|
pass |
Перейдите к другим проверкам отчёта. |
warn |
Прочитайте summary и выполните предложенное suggested_action. |
fail |
Начните восстановление с указанной причины и проверьте результат повторной диагностикой. |
skip |
Изучите причину пропуска и подготовьте условия для нужной проверки. |
Сохраните ревизию CodeGraph, время, окружение, проект и наблюдаемый симптом. Перед передачей удалите токены, пароли, пользовательские исходники и персональные данные.
2. Выберите проверку по симптому
python -m src.cli doctor config
python -m src.cli doctor project --help
python -m src.cli doctor cpg --help
python -m src.cli doctor openviking --help
python -m src.cli doctor temporal --help
Запустите нужную подкоманду с явным --project 'имя-проекта', если проверка относится к проекту.
Справка перечисляет параметры выбранной проверки. Например, если граф проекта устарел,
выберите doctor cpg, укажите имя проекта и разберите причины в отчёте. Команда doctor openviking принимает подкоманду
employee-memory и идентификатор сотрудника --employee; без неё результат содержит
unsupported_openviking_doctor_command. Проверка оценивает доступность памяти выбранного сотрудника. Её код 0 означает ready, 1 — иной статус.
3. Проверьте локальные сервисы разработки
Только для локального окружения из исходников:
python scripts/run_app_stack.py status --local --with-mcp
$stackExit = $LASTEXITCODE
python scripts/run_app_stack.py logs --local --with-mcp
$logsExit = $LASTEXITCODE
status выводит состояние процессов и результаты проверок готовности.
Для локального стека $stackExit равен 0, когда проверки готовности пройдены
и необходимые процессы работают; 1 требует разбора выведенных причин.
logs выводит пути к stdout/stderr журналам сервисов. Откройте нужный файл
и найдите сообщения за время ошибки. $logsExit относится к получению этого
списка путей; сохраните его вместе с $stackExit.
На Ubuntu-развёртывании заказчика используйте
systemctl, Compose и команды проверки готовности из
руководства по установке.
4. Проверьте план восстановления
Некоторые проверки поддерживают восстановление. Сначала изучите план без записи изменений:
python -m src.cli doctor config --repair --dry-run
Перед применением проверьте целевой файл, резервную копию, ожидаемый результат и способ отката.
--dry-run выводит план действий. Для повреждённого YAML восстановление создаёт минимальную
конфигурацию; прежние настройки перенесите из проверенной резервной копии.
Что проверить при каждом симптоме
| Симптом | Что проверить сначала |
|---|---|
| Ошибка запуска или конфигурации | doctor config, состояние сервисов и готовность компонентов |
| Проект не виден | projects list, projects resolve-scope, учётная запись доступа |
| Граф отсутствует или устарел | задание импорта, doctor project, doctor cpg |
| MCP недоступен | готовность API/MCP, /status, привязка проекта |
| Контекст неполон | doctor openviking employee-memory, сотрудник, состояние синхронизации |
| Задание выполняется дольше ожидаемого | doctor temporal, идентификатор задачи или сессии |
Начните с отчёта выбранной проверки. Изменение данных, процессов и настроек сервисов выполните по согласованному плану восстановления.
Что передать поддержке
Передайте поддержке:
- точный симптом и ожидаемое поведение;
- время, окружение, версию выпуска и точный коммит;
- организацию, группу, проект и идентификатор сессии или задания;
- очищенные отчёты диагностики и готовности;
- выполненные действия и внесённые изменения.
Справочные материалы
Параметры диагностических команд и способы проверки проекта описаны в руководстве CLI.
См. также: Установка · Конфигурация