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

#Не удаётся записать экран или окно (macOS)

Сообщение: Для записи всего экрана или другого окна нужно разрешение macOS на запись экрана.

1. В диалоге Объект записи нажмите Открыть Системные настройки.
2. В разделе Конфиденциальность и безопасность → Запись экрана и системного звука включите Ferret.
3. Перезапустите приложение и нажмите Проверить снова.

Для записи Встроенный браузер разрешения не нужны.

При запуске из исходного кода на macOS pnpm dev запускает переименованную копию Electron с ad-hoc-подписью, которая тоже называется Ferret (scripts/prepare-dev-electron.mjs), поэтому в этих списках она отображается отдельной записью Ferret. При первом запуске macOS снова запросит доступ к записи экрана и микрофону. После этого запросов больше не будет. Сборки для разработки используют фиктивную связку ключей (--use-mock-keychain), поэтому запроса Связки ключей не появляется: cookie и ключи, сохранённые в dev-сборке, шифруются фиксированным ключом, а не настоящей Связкой ключей. Чтобы использовать настоящую Связку ключей, задайте ADE_DEV_REAL_KEYCHAIN=1.

#Микрофон не открывается

Сообщение: Не удалось открыть микрофон. Проверьте разрешение в настройках ОС.

• macOS: Системные настройки → Конфиденциальность и безопасность → Микрофон, затем включите Ferret.
• Windows: Параметры → Конфиденциальность и защита → Микрофон, затем разрешите доступ классическим приложениям.

Без микрофона обведённые пером места всё равно становятся замечаниями, но без произнесённого запроса.

#Нет модели на устройстве / whisper-cli не найден

Сообщение: Модель распознавания на устройстве не найдена. Аудио будет сохранено, обработаются только замечания пером.

Скачайте модель в настройках или выберите имеющийся ggml-*.bin. Если в настройках написано whisper.cpp (whisper-cli) не найден, установите его (инструкция), убедитесь, что он есть в PATH, и откройте настройки заново. Собранное приложение, запущенное из Finder или Проводника, может не видеть PATH вашей оболочки, поэтому устанавливайте в стандартное место, например в каталог Homebrew.

Скачанная модель, не прошедшая проверку sha256, удаляется. Повторите загрузку.

#Терминал: не удалось загрузить node-pty

Так бывает при запуске из исходного кода, если node-pty был собран под другой ABI Node или Electron.

pnpm rebuild:native

#Агент не найден / «Отправить агенту» не отправляет

• command not found: claude (или codex, gemini либо команда другого агента) в терминале: CLI не установлен или его нет в PATH. Ferret показывает собственную ошибку оболочки и не добавляет подсказок. Проверьте, что команда работает в вашем обычном терминале, воспользуйтесь кнопкой Установить в Настройки → Агенты или укажите абсолютный путь в поле Команда этого агента.
• Агент ждёт подтверждения. Ответьте в терминале, затем отправьте. Сначала ответьте на запрос агента.
• Ввод агента ещё не готов. Дождитесь, пока агент закончит запуск.
• Текст введён, но не отправлен. Нажмите Enter в терминале.
• Сначала откройте терминал.
• Не удалось разобрать аргументы запуска: Незакрытая кавычка. Исправьте кавычки в аргументах агента.

#Запись не начинается

• Сначала откройте папку проекта.
• Сначала откройте URL для ревью.
• Страница не загрузилась. Откройте отображающийся URL, затем начните запись. Проверьте, что dev-сервер запущен. Не удаётся подключиться к серверу означает, что на этом порту ничего не слушает.

#Не задан ключ OpenAI или эндпоинт

API-ключ OpenAI не задан… или Эндпоинт распознавания (Base URL / модель) не задан…: добавьте его в настройках или переключитесь на На устройстве (бесплатно). Аудио этой записи уже сохранено.

#Ошибки GitHub

• GitHub CLI (gh) не найден. Установите gh.
• Вход в GitHub не выполнен. Настройки → GitHub / GitLab → Войти через терминал.
• Нет remote origin. или origin — не репозиторий GitHub. Проверьте git remote -v.
• Репозиторий не найден или нет доступа. Проверьте gh auth status и GH_TOKEN.

#Сообщить об ошибке

Создайте issue на github.com/JapanMarketing-Dev/ferret/issues (откроется в новой вкладке), указав ОС, версию приложения (нижняя панель → Обновления) и шаги для воспроизведения. Не прикладывайте содержимое .ferret/, если в нём есть приватные экраны.