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

Чему вы научитесь

После изучения этого раздела вы сможете:

Быстро определять источник проблемы (занятость порта, парсинг Hook event, конфигурация Git и т.д.)
Диагностировать ошибки через вывод логов
Применять правильные методы решения для разных типов ошибок
Отлаживать проблемы подключения в удалённом режиме или Devcontainer

Ваша текущая ситуация

Plannotator внезапно перестал работать, браузер не открывается, или Hook выводит сообщения об ошибках. Вы не знаете, как просмотреть логи, и не уверены, на каком этапе возникла проблема. Возможно, вы пробовали перезапустить, но проблема осталась.

Когда использовать этот раздел

Устранение неполадок необходимо в следующих случаях:

Браузер не открывается автоматически
Hook выводит сообщения об ошибках
Порт занят, и запуск невозможен
Страница плана или код-ревью отображается некорректно
Интеграция с Obsidian/Bear не работает
Git diff показывает пустой результат

Основная концепция

Проблемы Plannotator обычно делятся на три категории:

Проблемы окружения: занятость порта, неправильная конфигурация переменных окружения, проблемы с путём к браузеру
Проблемы данных: ошибка парсинга Hook event, пустое содержимое плана, аномальное состояние Git-репозитория
Проблемы интеграции: ошибка сохранения в Obsidian/Bear, проблемы подключения в удалённом режиме

Ключ к отладке — просмотр вывода логов. Plannotator использует console.error для вывода ошибок в stderr и console.log для вывода обычной информации в stdout. Различение этих двух потоков поможет быстро определить тип проблемы.

🎒 Подготовка

✅ Plannotator установлен (плагин Claude Code или OpenCode)
✅ Базовые навыки работы с командной строкой
✅ Знакомство с директорией проекта и состоянием Git-репозитория

Пошаговое руководство

Шаг 1: Проверка вывода логов

Зачем

Все ошибки Plannotator выводятся в stderr. Просмотр логов — первый шаг в диагностике проблемы.

Как это сделать

В Claude Code

Когда Hook запускает Plannotator, сообщения об ошибках отображаются в терминале Claude Code:

bash

# Пример ошибки, которую вы можете увидеть
Error: Port 54321 in use after 5 retries (set PLANNOTATOR_PORT to use different port)

В OpenCode

OpenCode перехватывает stderr CLI и отображает его в интерфейсе:

[stderr] Failed to parse hook event from stdin
[stderr] No plan content in hook event

Ожидаемый результат:

Если ошибок нет, stderr должен быть пустым или содержать только ожидаемые информационные сообщения
При наличии ошибок будет указан тип ошибки (например, EADDRINUSE), сообщение об ошибке и стек вызовов (если есть)

Шаг 2: Решение проблемы занятости порта

Зачем

По умолчанию Plannotator запускает сервер на случайном порту. Если фиксированный порт занят, сервер попытается повторить попытку 5 раз (с задержкой 500 мс каждый раз), после чего выдаст ошибку.

Сообщение об ошибке:

Error: Port 54321 in use after 5 retries (set PLANNOTATOR_PORT to use different port)

Решение

Вариант A: Автоматический выбор порта (рекомендуется)

Не устанавливайте переменную окружения PLANNOTATOR_PORT, и Plannotator автоматически выберет доступный порт.

Вариант B: Использование фиксированного порта с освобождением занятого

Если необходимо использовать фиксированный порт (например, в удалённом режиме), нужно освободить занятый порт:

bash

# macOS/Linux
lsof -ti:54321 | xargs kill -9

# Windows PowerShell
Get-NetTCPConnection -LocalPort 54321 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Затем установите новый порт:

bash

# macOS/Linux/WSL
export PLANNOTATOR_PORT=54322

# Windows PowerShell
$env:PLANNOTATOR_PORT = "54322"

Контрольная точка ✅:

Запустите Plannotator снова — браузер должен открыться нормально
Если ошибка повторяется, попробуйте другой номер порта

Шаг 3: Отладка ошибки парсинга Hook event

Зачем

Hook event — это JSON-данные, считываемые из stdin. Если парсинг не удался, Plannotator не сможет продолжить работу.

Сообщение об ошибке:

Failed to parse hook event from stdin
No plan content in hook event

Возможные причины:

Hook event не является валидным JSON
В Hook event отсутствует поле tool_input.plan
Несовместимая версия Hook

Методы отладки

Просмотр содержимого Hook event

Перед запуском Hook server выведите содержимое stdin:

bash

# Временно измените hook/server/index.ts
# После строки 91 добавьте:
console.error("[DEBUG] Hook event:", eventJson);

Ожидаемый результат:

json

{
  "tool_input": {
    "plan": "# Implementation Plan\n\n## Task 1\n..."
  },
  "permission_mode": "default"
}

Решение:

Если tool_input.plan пуст или отсутствует, проверьте, правильно ли AI Agent сгенерировал план
Если формат JSON некорректен, проверьте правильность конфигурации Hook
Если версия Hook несовместима, обновите Plannotator до последней версии

Шаг 4: Решение проблемы с открытием браузера

Зачем

Plannotator использует функцию openBrowser для автоматического открытия браузера. Если это не удаётся, возможны проблемы кроссплатформенной совместимости или неверный путь к браузеру.

Возможные причины:

Браузер по умолчанию не установлен в системе
Неверный путь к пользовательскому браузеру
Особенности обработки в среде WSL
В удалённом режиме браузер не открывается автоматически (это нормальное поведение)

Методы отладки

Проверка удалённого режима

bash

# Проверка переменной окружения
echo $PLANNOTATOR_REMOTE

# Windows PowerShell
echo $env:PLANNOTATOR_REMOTE

Если вывод 1 или true, это удалённый режим, и браузер не будет открываться автоматически — это ожидаемое поведение.

Ручное тестирование открытия браузера

bash

# macOS
open "http://localhost:54321"

# Linux
xdg-open "http://localhost:54321"

# Windows
start http://localhost:54321

Ожидаемый результат:

Если ручное открытие успешно, сервер Plannotator работает нормально, проблема в логике автоматического открытия
Если ручное открытие не удалось, проверьте правильность URL (порт может отличаться)

Решение:

Вариант A: Установка пользовательского браузера (macOS)

bash

export PLANNOTATOR_BROWSER="Google Chrome"

# Или используйте полный путь
export PLANNOTATOR_BROWSER="/Applications/Google Chrome.app"

Вариант B: Установка пользовательского браузера (Linux)

bash

export PLANNOTATOR_BROWSER="/usr/bin/firefox"

Вариант C: Ручное открытие в удалённом режиме (Devcontainer/SSH)

bash

# Plannotator выведет URL и информацию о порте
# Скопируйте URL и откройте его в локальном браузере
# Или используйте проброс портов:
ssh -L 19432:localhost:19432 user@remote

Шаг 5: Проверка состояния Git-репозитория (код-ревью)

Зачем

Функция код-ревью зависит от команд Git. Если состояние Git-репозитория аномальное (например, нет коммитов, Detached HEAD), diff будет пустым или выдаст ошибку.

Сообщение об ошибке:

Git diff error for uncommitted: Error: Command failed: git diff HEAD

Методы отладки

Проверка Git-репозитория

bash

# Проверка, находитесь ли вы в Git-репозитории
git status

# Проверка текущей ветки
git branch

# Проверка наличия коммитов
git log --oneline -1

Ожидаемый результат:

Если вывод fatal: not a git repository, текущая директория не является Git-репозиторием
Если вывод HEAD detached at <commit>, вы находитесь в состоянии Detached HEAD
Если вывод fatal: your current branch 'main' has no commits yet, коммитов ещё нет

Решение:

Проблема A: Не в Git-репозитории

bash

# Инициализация Git-репозитория
git init
git add .
git commit -m "Initial commit"

Проблема B: Состояние Detached HEAD

bash

# Переключение на ветку
git checkout main
# Или создание новой ветки
git checkout -b feature-branch

Проблема C: Нет коммитов

bash

# Для просмотра diff нужен хотя бы один коммит
git add .
git commit -m "Initial commit"

Проблема D: Пустой diff (нет изменений)

bash

# Создайте какие-нибудь изменения
echo "test" >> test.txt
git add test.txt

# Снова запустите /plannotator-review

Контрольная точка ✅:

Запустите /plannotator-review снова — diff должен отображаться нормально
Если всё ещё пусто, проверьте наличие неиндексированных или незакоммиченных изменений

Шаг 6: Отладка ошибок интеграции с Obsidian/Bear

Зачем

Ошибка интеграции с Obsidian/Bear не блокирует утверждение плана, но приводит к ошибке сохранения. Ошибки выводятся в stderr.

Сообщение об ошибке:

[Obsidian] Save failed: Vault not found
[Bear] Save failed: Failed to open Bear

Методы отладки

Проверка конфигурации Obsidian

macOS:

bash

cat ~/Library/Application\ Support/obsidian/obsidian.json

Windows:

powershell

cat $env:APPDATA\obsidian\obsidian.json

Ожидаемый результат:

json

{
  "vaults": {
    "/path/to/vault": {
      "path": "/path/to/vault",
      "ts": 1234567890
    }
  }
}

Проверка доступности Bear (macOS)

bash

# Тестирование URL scheme Bear
open "bear://x-callback-url/create?title=Test&text=Hello"

Ожидаемый результат:

Приложение Bear откроется и создаст новую заметку
Если ничего не происходит, Bear установлен некорректно

Решение:

Ошибка сохранения в Obsidian

Убедитесь, что Obsidian запущен
Проверьте правильность пути к vault
Попробуйте вручную создать заметку в Obsidian для проверки прав доступа

Ошибка сохранения в Bear

Убедитесь, что Bear правильно установлен
Проверьте доступность bear://x-callback-url
Проверьте, включён ли x-callback-url в настройках Bear

Шаг 7: Просмотр подробных логов ошибок (режим отладки)

Зачем

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

Как это сделать

Включение режима отладки Bun

bash

export DEBUG="*"
plannotator review

# Windows PowerShell
$env:DEBUG = "*"
plannotator review

Просмотр логов сервера Plannotator

Внутренние ошибки сервера выводятся через console.error. Ключевые места логирования:

packages/server/index.ts:260 — логи ошибок интеграции
packages/server/git.ts:141 — логи ошибок Git diff
apps/hook/server/index.ts:100-106 — ошибки парсинга Hook event

Ожидаемый результат:

bash

# Успешное сохранение в Obsidian
[Obsidian] Saved plan to: /path/to/vault/Plan - 2026-01-24.md

# Ошибка сохранения
[Obsidian] Save failed: Cannot write to directory
[Bear] Save failed: Failed to open Bear

# Ошибка Git diff
Git diff error for uncommitted: Error: Command failed: git diff HEAD

Контрольная точка ✅:

Логи ошибок содержат достаточно информации для локализации проблемы
Применяйте соответствующее решение в зависимости от типа ошибки

Типичные ошибки

❌ Игнорирование вывода stderr

Неправильно:

bash

# Смотрим только stdout, игнорируем stderr
plannotator review 2>/dev/null

Правильно:

bash

# Просмотр и stdout, и stderr
plannotator review
# Или разделение логов
plannotator review 2>error.log

❌ Слепой перезапуск сервера

Неправильно:

При возникновении проблемы сразу перезапускать, не выясняя причину ошибки

Правильно:

Сначала просмотреть логи ошибок и определить тип проблемы
Применить соответствующее решение в зависимости от типа ошибки
Перезапуск — только крайняя мера

❌ Ожидание автоматического открытия браузера в удалённом режиме

Неправильно:

bash

export PLANNOTATOR_REMOTE=1
plannotator review
# Ожидание автоматического открытия браузера (не произойдёт)

Правильно:

bash

export PLANNOTATOR_REMOTE=1
plannotator review
# Запишите выведенный URL и откройте его вручную в браузере
# Или используйте проброс портов

Итоги раздела

Plannotator использует console.error для вывода ошибок в stderr и console.log для вывода обычной информации в stdout
Типичные проблемы: занятость порта, ошибка парсинга Hook event, браузер не открывается, аномальное состояние Git-репозитория, ошибки интеграции
Ключ к отладке: просмотр логов → определение типа проблемы → применение соответствующего решения
В удалённом режиме браузер не открывается автоматически — нужно открыть URL вручную или настроить проброс портов

Следующий урок

В следующем уроке мы изучим Часто задаваемые вопросы.
Вы узнаете:
Как решать проблемы установки и конфигурации
Типичные ошибки использования и важные замечания
Рекомендации по оптимизации производительности

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Дата обновления: 2026-01-24

Функция	Путь к файлу	Строки
Механизм повторных попыток порта	`packages/server/index.ts`	79-80
Обработка ошибки EADDRINUSE	`packages/server/index.ts`	320-334
Парсинг Hook event	`apps/hook/server/index.ts`	91-107
Открытие браузера	`packages/server/browser.ts`	45-74
Обработка ошибок Git diff	`packages/server/git.ts`	139-144
Логи сохранения в Obsidian	`packages/server/index.ts`	242-246
Логи сохранения в Bear	`packages/server/index.ts`	252-256

Ключевые константы:

MAX_RETRIES = 5: максимальное количество повторных попыток порта
RETRY_DELAY_MS = 500: задержка между попытками (миллисекунды)

Ключевые функции:

startPlannotatorServer(): запуск сервера ревью планов
startReviewServer(): запуск сервера код-ревью
openBrowser(): кроссплатформенное открытие браузера
runGitDiff(): выполнение команды Git diff
saveToObsidian(): сохранение плана в Obsidian
saveToBear(): сохранение плана в Bear

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

Чему вы научитесь ​

Ваша текущая ситуация ​

Когда использовать этот раздел ​

Основная концепция ​

🎒 Подготовка ​

Пошаговое руководство ​

Шаг 1: Проверка вывода логов ​

В Claude Code ​

В OpenCode ​

Шаг 2: Решение проблемы занятости порта ​

Вариант A: Автоматический выбор порта (рекомендуется) ​

Вариант B: Использование фиксированного порта с освобождением занятого ​

Шаг 3: Отладка ошибки парсинга Hook event ​

Просмотр содержимого Hook event ​

Шаг 4: Решение проблемы с открытием браузера ​

Проверка удалённого режима ​

Ручное тестирование открытия браузера ​

Вариант A: Установка пользовательского браузера (macOS) ​

Вариант B: Установка пользовательского браузера (Linux) ​

Вариант C: Ручное открытие в удалённом режиме (Devcontainer/SSH) ​

Шаг 5: Проверка состояния Git-репозитория (код-ревью) ​

Проверка Git-репозитория ​

Проблема A: Не в Git-репозитории ​

Проблема B: Состояние Detached HEAD ​

Проблема C: Нет коммитов ​

Проблема D: Пустой diff (нет изменений) ​

Шаг 6: Отладка ошибок интеграции с Obsidian/Bear ​

Проверка конфигурации Obsidian ​

Проверка доступности Bear (macOS) ​

Ошибка сохранения в Obsidian ​

Ошибка сохранения в Bear ​

Шаг 7: Просмотр подробных логов ошибок (режим отладки) ​

Включение режима отладки Bun ​

Просмотр логов сервера Plannotator ​

Типичные ошибки ​

❌ Игнорирование вывода stderr ​

❌ Слепой перезапуск сервера ​

❌ Ожидание автоматического открытия браузера в удалённом режиме ​

Итоги раздела ​

Следующий урок ​

Приложение: Справочник по исходному коду ​

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

Чему вы научитесь

Ваша текущая ситуация

Когда использовать этот раздел

Основная концепция

🎒 Подготовка

Пошаговое руководство

Шаг 1: Проверка вывода логов

В Claude Code

В OpenCode

Шаг 2: Решение проблемы занятости порта

Вариант A: Автоматический выбор порта (рекомендуется)

Вариант B: Использование фиксированного порта с освобождением занятого

Шаг 3: Отладка ошибки парсинга Hook event

Просмотр содержимого Hook event

Шаг 4: Решение проблемы с открытием браузера

Проверка удалённого режима

Ручное тестирование открытия браузера

Вариант A: Установка пользовательского браузера (macOS)

Вариант B: Установка пользовательского браузера (Linux)

Вариант C: Ручное открытие в удалённом режиме (Devcontainer/SSH)

Шаг 5: Проверка состояния Git-репозитория (код-ревью)

Проверка Git-репозитория

Проблема A: Не в Git-репозитории

Проблема B: Состояние Detached HEAD

Проблема C: Нет коммитов

Проблема D: Пустой diff (нет изменений)

Шаг 6: Отладка ошибок интеграции с Obsidian/Bear

Проверка конфигурации Obsidian

Проверка доступности Bear (macOS)

Ошибка сохранения в Obsidian

Ошибка сохранения в Bear

Шаг 7: Просмотр подробных логов ошибок (режим отладки)

Включение режима отладки Bun

Просмотр логов сервера Plannotator

Типичные ошибки

❌ Игнорирование вывода stderr

❌ Слепой перезапуск сервера

❌ Ожидание автоматического открытия браузера в удалённом режиме

Итоги раздела

Следующий урок

Приложение: Справочник по исходному коду