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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проблема 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/Linux

export PLANNOTATOR_PORT=9999
plannotator start

Windows PowerShell

$env:PLANNOTATOR_PORT = "9999"
plannotator start

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

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

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

# Найти процесс, занимающий порт (замените 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)

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

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

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

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

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

2. Откройте браузер вручную и перейдите по отображаемому URL

3. Настройте проброс портов (если требуется доступ с локальной машины)

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

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

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

macOS/Linux

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

Windows PowerShell

echo $env:PLANNOTATOR_BROWSER

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

macOS/Linux

unset PLANNOTATOR_BROWSER
plannotator start

Windows PowerShell

$env:PLANNOTATOR_BROWSER = ""
plannotator start

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

# 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: Ревью плана не отображается

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

# Найти сообщения об ошибках
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: Код-ревью не отображается

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

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

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

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

fatal: not a git repository

Решение:

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

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

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

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

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

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

Решение:

# Проверить наличие незакоммиченных изменений
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

Решение:

# Проверить версию 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. Если загрузка всё равно не удаётся, проверьте права на системную временную директорию.

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

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

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

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

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

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

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

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

---

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

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

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

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

Решения:

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

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

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

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

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

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

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

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

macOS

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

Windows PowerShell

cat $env:APPDATA\obsidian\obsidian.json

Linux

cat ~/.config/obsidian/obsidian.json

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

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

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

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

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

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

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

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

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

[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:

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

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

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

[Bear] Saved plan to Bear

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

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

Решение:

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

---

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

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

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

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

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

Решения:

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

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

macOS/Linux/WSL

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

Windows

$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

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

ssh your-server

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

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

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

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

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

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

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

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

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

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

http://localhost:9999

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

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

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

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

---

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

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

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

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

Решения:

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

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

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

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

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

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

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

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

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

macOS/Linux

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

Windows PowerShell

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

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

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

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

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

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

---

Итоги урока

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

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

Запомните:

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

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

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

• Устранение неполадок - Углублённые методы отладки и анализа логов
• Справочник 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