12. Диагностика Windows: найти слой ошибки

← Предыдущий модуль · Оглавление · Следующий модуль →

Если сейчас только читаете: русский разбор ситуации без запуска программ. После него ответьте на вопросы самопроверки модуля; практическое упражнение можно отложить.

Результат модуля: вы умеете собрать короткий диагностический пакет и выбрать узкое исправление. Отсутствующий Python, неверный каталог и запрет sandbox требуют разных действий.

Текущая документация поддерживает нативные Windows-сценарии с PowerShell для приложения, CLI и IDE. WSL — отдельный вариант окружения. Документация sandbox сейчас описывает несколько реализаций, включая MXC на совместимых устройствах. Это не означает, что MXC уже доступен на любом ноутбуке или в установленном старом CLI; проверяйте требования версии и политику организации. Windows sandbox.

Сначала зафиксируйте окружение

$PSVersionTable.PSVersion
Get-Location
Get-Command codex -All -ErrorAction SilentlyContinue |
    Select-Object Name, CommandType, Source
Get-Command git, python, py, node, npm -ErrorAction SilentlyContinue |
    Select-Object Name, CommandType, Source
git --version
codex --version

Команды не устанавливают зависимости и не меняют политики. Путь к исполняемому файлу помогает обнаружить несколько установок. Версия CLI и версия desktop-приложения — разные факты: результат codex --version не устанавливает версию приложения.

Далее проверьте папку и ветку. Если Git отвечает, что текущая папка не является репозиторием, не создавайте новый репозиторий автоматически: сначала найдите правильный каталог. Если есть незакоммиченные изменения, установите их принадлежность до любой очистки или восстановления файлов.

Дерево диагностики

Если команда не найдена, исследуйте установку и PATH. Если команда найдена, но файл заблокирован, смотрите путь, права и текст отказа. Если локальное чтение работает, а запрос в сеть падает, проверьте доступный сетевой маршрут, прокси, авторизацию и ограничения запуска. Недоступность веб-сайта из shell не доказывает недоступность того же источника через подключённый инструмент.

Если skill не появился, проверьте расположение, SKILL.md и метаданные. Для проектных локальных skills текущие документы указывают .agents/skills; изменения обнаруживаются автоматически, а при проблеме можно перезапустить клиент. Не переносите skill в глобальную папку только ради обхода невыясненной ошибки. Build skills.

Если изменённые правила не действуют, проверьте цепочку AGENTS.md и наличие AGENTS.override.md. Более близкие к рабочему каталогу инструкции имеют приоритет; цепочка строится при запуске. Custom instructions with AGENTS.md.

Частые особенности PowerShell

В Windows PowerShell 5.1 нет оператора && из PowerShell 7. Запускайте команды отдельными строками и проверяйте $LASTEXITCODE сразу после внешней программы. У cmdlet ошибки обрабатываются иначе; не считайте старое значение $LASTEXITCODE результатом Get-Content.

Пути с пробелами заключайте в кавычки. Для буквального пути используйте -LiteralPath, а для запуска исполняемого файла по пути — оператор &. Не заменяйте глобальную execution policy ради одного учебного скрипта. Сначала выясните, какой файл запускается и действительно ли нужен скрипт, если ту же проверку можно выполнить обычной командой.

Пример задания Codex

Диагностируй ошибку запуска без установки программ и изменения настроек.
Найди фактически вызываемый executable и версию PowerShell.
Отдели ошибку оболочки от ошибки программы, sandbox и сети.
Не печатай переменные с токенами. Верни минимальное воспроизведение,
подтверждённую причину либо следующий способ её проверить.

Упражнение

В учебной папке выполните заведомо отсутствующую команду, например CodexHowtoMissingCommand. Затем выполните git --codex-howto-invalid-option и сразу посмотрите $LASTEXITCODE. У Git этот неизвестный параметр даёт диагностическую ошибку без изменения репозитория. Сравните её с сообщением PowerShell о ненайденной команде. Запишите, на каком слое произошёл каждый отказ. Не используйте для эксперимента рабочие сервисы или утилиты с неоднозначной семантикой.

Готово, когда: указан точный слой; сохранены версия и минимальное воспроизведение; секреты исключены; исправление соответствует причине; повторение отказа не заменяет диагностику.

Самопроверка:

Почему codex --version не подтверждает версию desktop-приложения?
Что проверять, если программа доступна в одном терминале и не найдена в другом?
Почему отключение sandbox не является обычным первым шагом диагностики?

← Предыдущий модуль · Оглавление · Следующий модуль →