Частые проблемы

Что вы научитесь делать

✅ Быстро диагностировать и решать проблемы с занятым портом
✅ Понимать, почему браузер не открылся автоматически, и знать, как получить доступ
✅ Устранять проблемы с отображением плана или код-ревью
✅ Обрабатывать ситуации с ошибками выполнения Git-команд
✅ Решать ошибки, связанные с загрузкой изображений
✅ Диагностировать причины сбоя интеграции с Obsidian/Bear
✅ Правильно получать доступ к Plannotator в удалённой среде

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

При использовании Plannotator вы можете столкнуться со следующими проблемами:

Проблема 1: При запуске появляется сообщение о занятом порте, сервер не запускается
Проблема 2: Браузер не открылся автоматически, непонятно, как получить доступ к интерфейсу ревью
Проблема 3: Страница плана или код-ревью пустая, контент не загружается
Проблема 4: При выполнении /plannotator-review появляется ошибка Git
Проблема 5: Загрузка изображения не удалась или изображение не отображается
Проблема 6: Интеграция с Obsidian/Bear настроена, но план не сохраняется автоматически
Проблема 7: В удалённой среде невозможно получить доступ к локальному серверу

Эти проблемы прерывают ваш рабочий процесс и влияют на удобство использования.

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

Механизм обработки ошибок

Сервер Plannotator реализует механизм автоматического повтора:

Максимальное количество попыток: 5 раз
Задержка между попытками: 500 миллисекунд
Применимые сценарии: Занятый порт (ошибка EADDRINUSE)

При конфликте портов система автоматически пробует другие порты. Ошибка выдаётся только после 5 неудачных попыток.

Обработка ошибок в Plannotator следует следующим принципам:

Приоритет локального вывода: Все сообщения об ошибках выводятся в терминал или консоль
Плавная деградация: Сбой интеграции (например, сохранение в Obsidian) не блокирует основной процесс
Чёткие подсказки: Предоставляются конкретные сообщения об ошибках и рекомендуемые решения

Частые проблемы и решения

Проблема 1: Занятый порт

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

Port 19432 in use after 5 retries

Анализ причин:

Порт уже занят другим процессом
В удалённом режиме настроен фиксированный порт, но возник конфликт
Предыдущий процесс Plannotator не завершился корректно

Решения:

Способ 1: Дождаться автоматического повтора (только для локального режима)

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

Все 5 случайных портов заняты (крайне редко)
Настроен фиксированный порт (PLANNOTATOR_PORT), но он конфликтует

Вы должны увидеть: В терминале отображается "Port X in use after 5 retries"

Способ 2: Использовать фиксированный порт (удалённый режим)

В удалённой среде необходимо настроить PLANNOTATOR_PORT:

macOS/LinuxWindows PowerShell

bash

export PLANNOTATOR_PORT=9999
plannotator start

powershell

$env:PLANNOTATOR_PORT = "9999"
plannotator start

Рекомендации по выбору порта

Выбирайте порт в диапазоне 1024-49151 (пользовательские порты)
Избегайте портов распространённых сервисов (80, 443, 3000, 5000 и т.д.)
Убедитесь, что порт не заблокирован файрволом

Способ 3: Завершить процесс, занимающий порт

bash

# Найти процесс, занимающий порт (замените 19432 на ваш порт)
lsof -i :19432  # macOS/Linux
netstat -ano | findstr :19432  # Windows

# Завершить процесс (замените PID на фактический ID процесса)
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

Внимание

Перед завершением процесса убедитесь, что это не важное приложение. Plannotator автоматически закрывает сервер после получения решения, обычно ручное завершение не требуется.

Проблема 2: Браузер не открылся автоматически

Симптом: В терминале отображается, что сервер запущен, но браузер не открылся.

Анализ причин:

Сценарий	Причина
Удалённая среда	Plannotator обнаружил удалённый режим и пропустил автоматическое открытие браузера
Неверная настройка `PLANNOTATOR_BROWSER`	Неправильный путь или имя браузера
Браузер не установлен	Браузер по умолчанию отсутствует в системе

Решения:

Сценарий 1: Удалённая среда (SSH, Devcontainer, WSL)

Проверьте, является ли среда удалённой:

bash

echo $PLANNOTATOR_REMOTE
# Вывод "1" или "true" означает удалённый режим

В удалённой среде:

В терминале отображается URL для доступа:

Plannotator running at: http://localhost:9999
Press Ctrl+C to stop

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

Вы должны увидеть: В терминале вывод типа "Plannotator running at: http://localhost:19432"

Сценарий 2: Локальный режим, но браузер не открылся

Проверьте настройку PLANNOTATOR_BROWSER:

macOS/LinuxWindows PowerShell

bash

echo $PLANNOTATOR_BROWSER
# Должно вывести имя или путь браузера

powershell

echo $env:PLANNOTATOR_BROWSER

Сбросьте пользовательскую настройку браузера:

macOS/LinuxWindows PowerShell

bash

unset PLANNOTATOR_BROWSER
plannotator start

powershell

$env:PLANNOTATOR_BROWSER = ""
plannotator start

Настройте правильный браузер (если требуется кастомизация):

bash

# macOS: используйте имя приложения
export PLANNOTATOR_BROWSER="Google Chrome"

# Linux: используйте путь к исполняемому файлу
export PLANNOTATOR_BROWSER="/usr/bin/google-chrome"

# Windows: используйте путь к исполняемому файлу
set PLANNOTATOR_BROWSER="C:\Program Files\Google\Chrome\Application\chrome.exe"

Проблема 3: План или код-ревью не отображается

Симптом: Браузер открылся, но страница пустая или не загружается.

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

Причина	Ревью плана	Код-ревью
Параметр Plan пустой	✅ Часто	❌ Не применимо
Проблема с Git-репозиторием	❌ Не применимо	✅ Часто
Нет diff для отображения	❌ Не применимо	✅ Часто
Сервер не запустился	✅ Возможно	✅ Возможно

Решения:

Случай 1: Ревью плана не отображается

Проверьте вывод терминала:

bash

# Найти сообщения об ошибках
plannotator start 2>&1 | grep -i error

Частая ошибка 1: Параметр Plan пустой

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

400 Bad Request - Missing plan or plan is empty

Причина: Claude Code или OpenCode передали пустую строку в качестве plan.

Решение:

Убедитесь, что AI Agent сгенерировал валидное содержимое плана
Проверьте правильность настройки Hook или Plugin
Просмотрите логи Claude Code/OpenCode для получения дополнительной информации

Частая ошибка 2: Сервер не запустился корректно

Решение:

Проверьте, отображается ли в терминале сообщение "Plannotator running at"
Если нет, обратитесь к разделу "Проблема 1: Занятый порт"
Просмотрите Настройка переменных окружения для проверки конфигурации

Случай 2: Код-ревью не отображается

Проверьте вывод терминала:

bash

/plannotator-review 2>&1 | grep -i error

Частая ошибка 1: Нет Git-репозитория

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

fatal: not a git repository

Решение:

bash

# Инициализировать Git-репозиторий
git init

# Добавить файлы и закоммитить (если есть незакоммиченные изменения)
git add .
git commit -m "Initial commit"

# Запустить снова
/plannotator-review

Вы должны увидеть: В браузере отображается diff viewer

Частая ошибка 2: Нет diff для отображения

Симптом: На странице отображается "No changes" или подобное сообщение.

Решение:

bash

# Проверить наличие незакоммиченных изменений
git status

# Проверить наличие staged изменений
git diff --staged

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

# Переключить тип diff для просмотра разных диапазонов
# В интерфейсе код-ревью нажмите на выпадающее меню:
# - Uncommitted changes
# - Staged changes
# - Last commit
# - vs main (если на ветке)

Вы должны увидеть: diff viewer показывает изменения кода или сообщение "No changes"

Частая ошибка 3: Ошибка выполнения Git-команды

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

Git diff error for uncommitted: [конкретное сообщение об ошибке]

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

Git не установлен
Устаревшая версия Git
Проблема с конфигурацией Git

Решение:

bash

# Проверить версию Git
git --version

# Протестировать команду Git diff
git diff HEAD

# Если Git работает нормально, проблема может быть внутренней ошибкой Plannotator
# Просмотрите полное сообщение об ошибке и сообщите о баге

Проблема 4: Ошибка загрузки изображения

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

400 Bad Request - No file provided
500 Internal Server Error - Upload failed

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

Причина	Решение
Файл не выбран	Нажмите кнопку загрузки и выберите изображение
Формат файла не поддерживается	Используйте формат png/jpeg/webp
Файл слишком большой	Сожмите изображение перед загрузкой
Проблема с правами на временную директорию	Проверьте права на директорию /tmp/plannotator

Решения:

Проверьте загружаемый файл

Поддерживаемые форматы:

✅ PNG (.png)
✅ JPEG (.jpg, .jpeg)
✅ WebP (.webp)

Неподдерживаемые форматы:

❌ BMP (.bmp)
❌ GIF (.gif)
❌ SVG (.svg)

Вы должны увидеть: После успешной загрузки изображение отображается в интерфейсе ревью

Проверьте права на временную директорию

Plannotator автоматически создаёт директорию /tmp/plannotator. Если загрузка всё равно не удаётся, проверьте права на системную временную директорию.

Если требуется ручная проверка:

bash

# Проверить права на директорию
ls -la /tmp/plannotator

# Проверка в Windows
dir %TEMP%\plannotator

Вы должны увидеть: drwxr-xr-x (или аналогичные права) означает, что директория доступна для записи

Просмотрите инструменты разработчика браузера

Нажмите F12, чтобы открыть инструменты разработчика
Перейдите на вкладку "Network"
Нажмите кнопку загрузки
Найдите запрос /api/upload
Проверьте статус запроса и ответ

Вы должны увидеть:

Код статуса: 200 OK (успех)
Ответ: {"path": "/tmp/plannotator/xxx.png"}

Проблема 5: Сбой интеграции с Obsidian/Bear

Симптом: После одобрения плана в приложении для заметок нет сохранённого плана.

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

Причина	Obsidian	Bear
Интеграция не включена	✅	✅
Vault/App не обнаружен	✅	N/A
Неверная настройка пути	✅	✅
Конфликт имён файлов	✅	✅
Сбой x-callback-url	N/A	✅

Решения:

Проблемы интеграции с Obsidian

Шаг 1: Проверьте, включена ли интеграция

В интерфейсе Plannotator нажмите на настройки (значок шестерёнки)
Найдите раздел "Obsidian Integration"
Убедитесь, что переключатель включён

Вы должны увидеть: Переключатель отображается синим цветом (включён)

Шаг 2: Проверьте обнаружение Vault

Автоматическое обнаружение:

Plannotator автоматически читает файл конфигурации Obsidian
Расположение файла конфигурации:
- macOS: ~/Library/Application Support/obsidian/obsidian.json
- Windows: %APPDATA%\obsidian\obsidian.json
- Linux: ~/.config/obsidian/obsidian.json

Ручная проверка:

macOSWindows PowerShellLinux

bash

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

powershell

cat $env:APPDATA\obsidian\obsidian.json

bash

cat ~/.config/obsidian/obsidian.json

Вы должны увидеть: JSON-файл, содержащий поле vaults

Шаг 3: Настройте путь к Vault вручную

Если автоматическое обнаружение не сработало:

В настройках Plannotator
Нажмите "Manually enter vault path"
Введите полный путь к Vault

Примеры путей:

macOS: /Users/yourname/Documents/ObsidianVault
Windows: C:\Users\yourname\Documents\ObsidianVault
Linux: /home/yourname/Documents/ObsidianVault

Вы должны увидеть: В выпадающем меню отображается введённое вами имя Vault

Шаг 4: Проверьте вывод терминала

Результат сохранения в Obsidian выводится в терминал:

bash

[Obsidian] Saved plan to: /path/to/vault/plannotator/Title - Jan 24, 2026 2-30pm.md

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

[Obsidian] Save failed: [конкретное сообщение об ошибке]

Частые ошибки:

Недостаточно прав → Проверьте права на директорию Vault
Недостаточно места на диске → Освободите место
Неверный путь → Убедитесь в правильности написания пути

Проблемы интеграции с Bear

Проверьте приложение Bear

Убедитесь, что Bear установлен на macOS
Убедитесь, что приложение Bear запущено

Протестируйте x-callback-url:

bash

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

Вы должны увидеть: Bear открывается и создаёт новую заметку

Проверьте вывод терминала:

bash

[Bear] Saved plan to Bear

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

[Bear] Save failed: [конкретное сообщение об ошибке]

Решение:

Перезапустите приложение Bear
Убедитесь, что Bear обновлён до последней версии
Проверьте настройки прав macOS (разрешите Bear доступ к файлам)

Проблема 6: Проблемы доступа в удалённой среде

Симптом: В SSH, Devcontainer или WSL невозможно получить доступ к серверу из локального браузера.

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

Что такое удалённая среда

Удалённая среда — это удалённая вычислительная среда, доступ к которой осуществляется через SSH, Devcontainer или WSL. В такой среде необходимо использовать проброс портов для отображения удалённого порта на локальный, чтобы получить доступ к удалённому серверу из локального браузера.

Решения:

Шаг 1: Настройте удалённый режим

Установите переменные окружения в удалённой среде:

macOS/Linux/WSLWindows

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

powershell

$env:PLANNOTATOR_REMOTE = "1"
$env:PLANNOTATOR_PORT = "9999"

Вы должны увидеть: В терминале вывод "Using remote mode with fixed port: 9999"

Шаг 2: Настройте проброс портов

Сценарий 1: Удалённый SSH-сервер

Отредактируйте ~/.ssh/config:

Host your-server
    HostName server.example.com
    User yourname
    LocalForward 9999 localhost:9999

Подключитесь к серверу:

bash

ssh your-server

Вы должны увидеть: После установки SSH-соединения локальный порт 9999 пробрасывается на удалённый порт 9999

Сценарий 2: VS Code Devcontainer

VS Code Devcontainer обычно автоматически пробрасывает порты.

Как проверить:

В VS Code откройте вкладку "Ports"
Найдите порт 9999
Убедитесь, что статус порта "Forwarded"

Вы должны увидеть: Вкладка Ports показывает "Local Address: localhost:9999"

Сценарий 3: WSL (Windows Subsystem for Linux)

WSL по умолчанию использует проброс через localhost.

Способ доступа:

В браузере Windows напрямую перейдите по адресу:

http://localhost:9999

Вы должны увидеть: Интерфейс Plannotator отображается нормально

Шаг 3: Проверьте доступ

Запустите Plannotator в удалённой среде
В локальном браузере перейдите по адресу http://localhost:9999
Убедитесь, что страница отображается нормально

Вы должны увидеть: Интерфейс ревью плана или код-ревью загружается нормально

Проблема 7: План/аннотации не сохраняются корректно

Симптом: После одобрения или отклонения плана аннотации не сохраняются или сохраняются в неправильном месте.

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

Причина	Решение
Сохранение плана отключено	Проверьте опцию "Plan Save" в настройках
Неверный пользовательский путь	Проверьте, доступен ли путь для записи
Содержимое аннотации пустое	Это нормальное поведение (сохраняется только при наличии аннотаций)
Проблема с правами сервера	Проверьте права на директорию сохранения

Решения:

Проверьте настройки сохранения плана

В интерфейсе Plannotator нажмите на настройки (значок шестерёнки)
Просмотрите раздел "Plan Save"
Убедитесь, что переключатель включён

Вы должны увидеть: Переключатель "Save plans and annotations" синего цвета (включён)

Проверьте путь сохранения

Расположение по умолчанию:

bash

~/.plannotator/plans/  # Планы и аннотации сохраняются в этой директории

Пользовательский путь:

В настройках можно указать пользовательский путь сохранения.

Проверьте доступность пути для записи:

macOS/LinuxWindows PowerShell

bash

ls -la ~/.plannotator
mkdir -p ~/.plannotator/plans
touch ~/.plannotator/plans/test.txt
rm ~/.plannotator/plans/test.txt

powershell

dir $env:USERPROFILE\.plannotator
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.plannotator\plans"

Вы должны увидеть: Команды выполняются успешно, без ошибок прав доступа

Просмотрите вывод терминала

Результат сохранения выводится в терминал:

bash

[Plan] Saved annotations to: ~/.plannotator/annotations/slug.json
[Plan] Saved snapshot to: ~/.plannotator/plans/slug-approved.md

Вы должны увидеть: Подобные сообщения об успехе

Итоги урока

В этом уроке вы научились:

Диагностировать проблемы с занятым портом: Использовать фиксированный порт или завершать занимающий процесс
Обрабатывать ситуацию, когда браузер не открылся: Определять удалённый режим, получать доступ вручную или настраивать браузер
Устранять проблемы с отображением контента: Проверять параметр Plan, Git-репозиторий, статус diff
Решать проблемы с загрузкой изображений: Проверять формат файла, права на директорию, инструменты разработчика
Исправлять сбои интеграции: Проверять конфигурацию, пути, права и вывод терминала
Настраивать удалённый доступ: Использовать PLANNOTATOR_REMOTE и проброс портов
Сохранять планы и аннотации: Включать сохранение планов и проверять права на путь

Запомните:

Вывод терминала — лучший источник отладочной информации
Удалённая среда требует проброса портов
Сбой интеграции не блокирует основной процесс
Используйте инструменты разработчика для просмотра деталей сетевых запросов

Следующие шаги

Если ваша проблема не описана в этом уроке, обратитесь к:

Устранение неполадок - Углублённые методы отладки и анализа логов
Справочник API - Все API-эндпоинты и коды ошибок
Модели данных - Структуры данных Plannotator

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

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

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

Функция	Путь к файлу	Строки
Логика запуска сервера и повторных попыток	`packages/server/index.ts`	79-335
Обработка ошибки занятого порта (ревью плана)	`packages/server/index.ts`	319-334
Обработка ошибки занятого порта (код-ревью)	`packages/server/review.ts`	252-267
Определение удалённого режима	`packages/server/remote.ts`	Весь файл
Логика открытия браузера	`packages/server/browser.ts`	Весь файл
Выполнение Git-команд и обработка ошибок	`packages/server/git.ts`	36-147
Обработка загрузки изображений (ревью плана)	`packages/server/index.ts`	153-174
Обработка загрузки изображений (код-ревью)	`packages/server/review.ts`	181-201
Интеграция с Obsidian	`packages/server/integrations.ts`	Весь файл
Сохранение плана	`packages/server/storage.ts`	Весь файл

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

Константа	Значение	Описание
`MAX_RETRIES`	5	Максимальное количество попыток запуска сервера
`RETRY_DELAY_MS`	500	Задержка между попытками (миллисекунды)

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

startPlannotatorServer() - Запуск сервера ревью плана
startReviewServer() - Запуск сервера код-ревью
isRemoteSession() - Определение удалённой среды
getServerPort() - Получение порта сервера
openBrowser() - Открытие браузера
runGitDiff() - Выполнение команды Git diff
detectObsidianVaults() - Обнаружение Obsidian vaults
saveToObsidian() - Сохранение плана в Obsidian
saveToBear() - Сохранение плана в Bear

Частые проблемы ​

Что вы научитесь делать ​

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

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

Частые проблемы и решения ​

Проблема 1: Занятый порт ​

Способ 1: Дождаться автоматического повтора (только для локального режима) ​

Способ 2: Использовать фиксированный порт (удалённый режим) ​

Способ 3: Завершить процесс, занимающий порт ​

Проблема 2: Браузер не открылся автоматически ​

Сценарий 1: Удалённая среда (SSH, Devcontainer, WSL) ​

Сценарий 2: Локальный режим, но браузер не открылся ​

Проблема 3: План или код-ревью не отображается ​

Случай 1: Ревью плана не отображается ​

Случай 2: Код-ревью не отображается ​

Проблема 4: Ошибка загрузки изображения ​

Проверьте загружаемый файл ​

Проверьте права на временную директорию ​

Просмотрите инструменты разработчика браузера ​

Проблема 5: Сбой интеграции с Obsidian/Bear ​

Проблемы интеграции с Obsidian ​

Проблемы интеграции с Bear ​

Проблема 6: Проблемы доступа в удалённой среде ​

Шаг 1: Настройте удалённый режим ​

Шаг 2: Настройте проброс портов ​

Шаг 3: Проверьте доступ ​

Проблема 7: План/аннотации не сохраняются корректно ​

Проверьте настройки сохранения плана ​

Проверьте путь сохранения ​

Просмотрите вывод терминала ​

Итоги урока ​

Следующие шаги ​

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

Частые проблемы

Что вы научитесь делать

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

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

Частые проблемы и решения

Проблема 1: Занятый порт

Способ 1: Дождаться автоматического повтора (только для локального режима)

Способ 2: Использовать фиксированный порт (удалённый режим)

Способ 3: Завершить процесс, занимающий порт

Проблема 2: Браузер не открылся автоматически

Сценарий 1: Удалённая среда (SSH, Devcontainer, WSL)

Сценарий 2: Локальный режим, но браузер не открылся

Проблема 3: План или код-ревью не отображается

Случай 1: Ревью плана не отображается

Случай 2: Код-ревью не отображается

Проблема 4: Ошибка загрузки изображения

Проверьте загружаемый файл

Проверьте права на временную директорию

Просмотрите инструменты разработчика браузера

Проблема 5: Сбой интеграции с Obsidian/Bear

Проблемы интеграции с Obsidian

Проблемы интеграции с Bear

Проблема 6: Проблемы доступа в удалённой среде

Шаг 1: Настройте удалённый режим

Шаг 2: Настройте проброс портов

Шаг 3: Проверьте доступ

Проблема 7: План/аннотации не сохраняются корректно

Проверьте настройки сохранения плана

Проверьте путь сохранения

Просмотрите вывод терминала

Итоги урока

Следующие шаги

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