Ferret
Русский
Discord (откроется в новой вкладке) X (откроется в новой вкладке) GitHub (откроется в новой вкладке) Скачать

Работа с Ferret

Отправка агентам

Запускайте агента для написания кода во встроенном терминале и передавайте ему ревью одним щелчком. Обычно это Claude Code и Codex, но подойдёт любой агент из списка ниже, а также CLI, добавленный вами. Можно также скопировать инструкцию для агента, работающего в другом месте, или опубликовать ревью на GitHub.

#Работа с замечаниями

Каждая карточка во вкладке Замечания поддерживает:

  • правку заголовка и запроса прямо на месте;
  • переключатель Отправить / Не отправлять;
  • Смотреть запись (переход к этому моменту) и Заменить изображение (выбор другого кадра);
  • Подтвердить / Отметить «Нужна проверка», Объединить со следующим, Удалить.

Фильтр по прогрессу показывает или скрывает замечания по статусу (например, Только те, что ждут вашей проверки); Показать все сбрасывает фильтр.

В заголовке есть кнопки Отменить, Открыть папку, Копировать для агента, В GitHub / GitLab, Обработать и Отправить агенту. Речь, которая не стала замечанием, перечислена в разделе Исключённая речь, где Вернуть как замечание возвращает её.

Вкладка «Замечания»

#Агенты во встроенном терминале

При открытии проекта Ferret запускает по одной вкладке терминала на каждого агента из Настройки → Агенты → Запуск при открытии проекта — в папке проекта и в обычном режиме агента. По умолчанию это Claude Code и Codex:

claude
codex

Вместо них можно выбрать любых агентов из списка поддерживаемых (они запускаются в порядке выбора) или ни одного.

Запросы разрешений остаются включёнными

Регистрация или клонирование проекта не означает, что Ferret ему доверяет. Агенты, такие как Claude Code и Codex, в первый раз спрашивают, доверяете ли вы папке, и продолжают спрашивать, прежде чем редактировать файлы или выполнять команды. Чтобы агенты пропускали запросы разрешений, подтверждения и песочницу в одном проекте, которому вы доверяете, включите это для проекта в Настройки → Агенты → Пропускать запросы разрешений и подтвердите. Ferret добавляет собственный флаг пропуска каждого агента, если он известен; агенты без известного флага сохраняют запросы. Это действует только для агентов, которых вы открываете сами в папке этого проекта; агенты, запущенные при открытии проекта, всегда сохраняют запросы. Флаги пропуска разрешений, введённые в аргументы, игнорируются.

Если ни один агент не выбран, открывается обычная оболочка. Меню + открывает Новый терминал, запускает любого из ваших агентов в новой вкладке или переходит в Настройки агентов…. Его поле поиска также находит вкладки, сохранённые URL и файлы.

Вкладки показывают состояние агента: Работает, Ожидает ввода, Готово (не прочитано), Простаивает. На боковой панели отмечается проект, в котором работает агент, так что это видно без переключения проектов.

Перетаскивание вкладок и панелей терминала: разделение, перемещение и возврат во вкладки.

Разделение перетаскиванием. Перетащите вкладку или панель за её ручку (она появляется, когда вкладка разделена) и отпустите:

  • на внешней четверти края панели: Разделить влево / Разделить вправо / Разделить вверх / Разделить вниз;
  • в центре панели: Открыть как вкладку (панель выходит из разделения и становится отдельной вкладкой);
  • на узкой полосе вокруг всей области терминала: Разделить всю область влево и т. д. (когда панелей 2 или больше);
  • на панели вкладок: Вкладкой сюда.

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

ДействиеmacOSWindows / Linux
Новый терминал⌘TCtrlT
Разделить вправо⌘DCtrlShiftD
Разделить вниз⌘⇧DAltShiftD
Закрыть панель / вкладку⌘WCtrlW

#Поддерживаемые агенты

Ferret не привязан к одному агенту. Он распознаёт перечисленных ниже агентов для написания кода: может запускать их, находить в терминале для Отправить агенту и показывать, установлены ли они. Настройки → Агенты перечисляют их с пометкой Установлен / Не найден, кнопкой Установить там, где разработчик агента публикует установщик в одну строку, а также с командой и аргументами для каждого.

Нужного нет в списке? Настройки → Агенты → Добавить своего агента регистрирует любой CLI или скрипт-обёртку (название, команда и, при желании, имя процесса, по которому его распознавать); можно также добавить его в agents.customAgents в settings.json. Агенты, работающие вне Ferret, могут использовать Копировать для агента.

Несколько функций зависят от агента и пока доступны только для Claude Code и Codex:

  • Аккаунты и использование: переключение между несколькими входами и индикатор лимитов в нижней панели.
  • Обработать: работает через ваш вход в Claude Code или Codex либо через настроенный вами LLM API.

#Отправить агенту / Копировать для агента

Из вкладки «Замечания» — агенту во встроенном терминале кнопкой «Отправить агенту».
  1. Нажмите Отправить агенту. По умолчанию (Авто (текущая вкладка или запущенный агент)) замечания уходят агенту в текущей вкладке терминала или запущенному агенту. Стрелка рядом с кнопкой (Выбрать агента для отправки) позволяет выбрать конкретного агента или вкладку.
  2. Ferret записывает инструкцию в поле ввода агента и отправляет её. Следите за ходом работы в терминале.

Если ни один агент не запущен, Ferret сначала запускает его и отправляет, как только он будет готов. Пока агент ждёт ответа на запрос разрешения, ничего не отправляется. Сначала ответьте в терминале.

Копировать для агента помещает ту же инструкцию в буфер обмена для агента, работающего в другом месте (в другом терминале, IDE или приложении). Учитываются только замечания, переключённые на Отправить. Видео никогда не включается.

#Проверка приёмки моделью решений

Агент исправляет замечания и проверяет каждое моделью решений, пока все не пройдут.

Включите эту функцию, и ваш агент для написания кода будет проверять свою работу по каждому замечанию, прежде чем сообщить «Готово». Сам Ferret ничего не оценивает: он даёт агенту модель решений (любой API, совместимый с System One) и в feedback.md поручает ему повторять цикл, пока все замечания не пройдут.

  1. Агент реализует замечания.
  2. Для каждого замечания он снимает скриншот ПОСЛЕ (с тем же viewport и состоянием страницы, что и кадр ДО) и отправляет модели решений один запрос с текстом замечания, его строкой «Готово, когда» и изображениями ДО/ПОСЛЕ.
  3. Замечание проходит, когда P(done) не ниже порога (по умолчанию 0.7) и выбран вариант done. Агент исправляет остальное и в каждом раунде заново оценивает все замечания; он останавливается, только когда все замечания проходят в одном раунде, либо по честной причине, которую обязан назвать: API недоступен, замечание вне рамок задачи или замечание застряло с неизменными оценками.
  4. Итоговый список «Готово / Не готово» включает оценки по каждому замечанию и число раундов.

Настройте это в Настройки → Модель решений и включите Добавить проверку моделью решений в инструкции агента. Пресеты лишь заполняют поля; все поля остаются редактируемыми, а Свой работает с любым совместимым API.

ПресетURL запросаМоделиКлюч
Ollama (по умолчанию)http://localhost:11434/v1/systemoneclef-flash, clef (читают изображения); nimble, tev1 (только текст)не нужен, бесплатно
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash, clef (читают изображения)CLOUDFLARE_API_TOKEN (разрешение Workers AI); ID аккаунта из поля или CLOUDFLARE_ACCOUNT_ID
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev, convaiinnovations/laya (только текст)AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest, jev-preview (только текст)TYPESAFE_API_KEY
Свойлюбой полный URLлюбыеBearer, свой заголовок или без ключа; допускаются дополнительные заголовки

Для Ollama установите его (0.35.1 или новее для Clef / Clef Flash) и скачайте модель в терминале. Ferret не запускает установщики:

ollama pull clef-flash

Ключи берутся из поля ключа (сохраняется вместе с другими вашими API-ключами), из указанной вами переменной окружения (окружение приложения, .env проекта или ~/.ferret/.env) или из apiKey в settings.json. Дополнительные заголовки могут брать значения из переменных окружения через ${VAR}.

Как ключ не попадает в промпты

Агенты никогда не видят ваш ключ. Ferret запускает локальный релей на 127.0.0.1 и передаёт каждому терминалу FERRET_DECISION_URL (релей с токеном для этого терминала), FERRET_DECISION_MODEL и FERRET_DECISION_IMAGES (в течение одного выпуска задаются также старые имена MOVIE_ADE_DECISION_*). Релей добавляет ключ и заголовки и пересылает запрос без изменений, поэтому промпты, feedback.md и расшифровки сессий агентов не содержат секретов. Терминалы, открытые после изменения настроек, получают новые значения.

Cloudflare отличается от документации System One в двух местах (проверено на работающем API): изображения должны быть data URI (data:image/jpeg;base64,…, иначе 422 "image must be an embedded base64 data URI"), а ответ обёрнут в { "result": { … }, "success": true } (ошибки возвращаются как { "success": false, "errors": [ … ] }). Пресет Cloudflare устанавливает Кодирование изображений в data URI, агенты получают это как FERRET_DECISION_IMAGE_FORMAT, а инструкции велят им читать .result, если он есть. Релей пропускает данные в обоих направлениях без изменений. Чтобы использовать Global API Key вместо API-токена, выберите в Аутентификация значение Без ключа и добавьте заголовки X-Auth-Email: ${CLOUDFLARE_EMAIL} и X-Auth-Key: ${CLOUDFLARE_API_KEY}.

Изображения читают только Clef и Clef Flash. С текстовой моделью отключите Отправлять изображения ДО/ПОСЛЕ; тогда агент оценивает только по тексту, что менее надёжно.

Ollama и большие изображения

Ollama 0.35.0 ограничивает запросы к /v1/systemone 64 KiB, поэтому запросы со скриншотами завершаются ошибкой HTTP 413. Инструкции велят агенту уменьшать оба изображения до ширины не более 1024px в формате JPEG (качество около 70). Если 413 всё равно возникает, обновите Ollama до 0.35.1 или новее либо перейдите на Cloudflare Workers AI.

#Использование API в нижней панели

Вызовы модели решений идут через релей, поэтому Ferret может их подсчитывать. Элемент нижней панели рядом с индикатором использования агентов показывает модель решений и сегодняшние вызовы, токены и стоимость (например, clef-flash · 42 calls · 18.3k tok). Щёлкните по нему, чтобы увидеть данные за сегодня, за этот месяц, по проектам, по моделям и по видам (модель решений / распознавание / обработка), а также последние 50 вызовов.

Стоимость показывается, только если API её сообщает (Vercel AI Gateway сообщает) или если вы задали цены за 1M токенов в Настройки → Модель решений; иначе отображается «—». В ~/.ferret/usage/decision-YYYY-MM.jsonl, по одному файлу в месяц, записываются только метаданные (время, проект, модель, статус, задержка, размер, число изображений, токены, стоимость) — никогда изображения, текст или ключи.

#Настройка инструкции

Отредактируйте Настройки → Агенты → Инструкции для агента. Подставляются две переменные:

ПеременнаяЗаменяется на
{{path}}Абсолютный путь к feedback.md
{{relpath}}Путь относительно проекта: .ferret/reviews/<id>/feedback.md

Оставьте поле пустым, чтобы использовать инструкцию по умолчанию. Максимальная длина — 2000 символов, а Сбросить инструкции восстанавливает значение по умолчанию. Пример:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

Параметр хранится как agentPrompt в settings.json.

#Отправка в GitHub или GitLab (Issue / комментарий к PR или MR)

Отправить в GitHub публикует ревью как новый issue или как комментарий к одному из ваших открытых pull request. Аутентификация делегируется GitHub CLI (откроется в новой вкладке). Ferret никогда не читает и не хранит токен.

  1. Установите gh: brew install gh (macOS), winget install --id GitHub.cli (Windows) или см. cli/cli (откроется в новой вкладке).
  2. Настройки → GitHub / GitLab → Войти через терминал запускает gh auth login --web -h github.com во встроенном терминале.
  3. Нажмите Отправить в GitHub, выберите Создать новый Issue или PR и проверьте Заголовок и Текст (их можно править).
  4. Поставьте флажок подтверждения, затем нажмите Создать Issue или Отправить комментарий.

Подробности:

  • Репозиторий берётся из git remote get-url origin.
  • Ferret выполняет gh issue create --repo … --title … --body-file - или gh pr comment <n> --repo … --body-file -.
  • Текст — это feedback.md без строк с изображениями (изображения не загружаются), не более 60 000 символов.
  • Кандидаты PR — ваши собственные открытые PR (до 30).

Если задан GH_TOKEN или GITHUB_TOKEN, gh использует его в первую очередь, и панель настроек предупреждает об этом.

GitLab. Когда origin — проект GitLab (gitlab.com или собственный экземпляр GitLab), та же кнопка отправляет в GitLab через GitLab CLI (откроется в новой вкладке) (glab): новый issue или комментарий к одному из ваших открытых merge request. Войдите через Настройки → GitHub / GitLab: это запускает glab auth login (с --hostname для собственного экземпляра GitLab) во встроенном терминале. Ferret никогда не читает и не хранит токен и предупреждает, если задан GITLAB_TOKEN.

Предложение поставить звезду. После первого Отправить агенту, а также при достижении 3, 10 и 30 завершённых ревью Ferret может предложить поставить ему звезду на GitHub. Он спрашивает не более 3 раз, с перерывом не менее 3 дней, и никогда во время записи. Поставить звезду ставит звезду через ваш собственный вход в gh (или открывает GitHub, если gh недоступен), а Больше не спрашивать отключает эти предложения. Поставить звезду можно также через Справка → Поставить звезду Ferret на GitHub.

#Установка CLI-инструментов и вход в них

Настройки → CLI-инструменты перечисляют инструменты командной строки, которые часто нужны вашим агентам, показывают, какие установлены и их версии, и запускают официальную команду установки или входа для вашей ОС в новой вкладке терминала:

  • Git-хостинг: gh, glab
  • ИИ и модели: Ollama, Cloudflare wrangler
  • Деплой: Vercel, Netlify, Fly.io, Railway, Heroku
  • Облака и сервисы: Supabase, Firebase, Stripe, Google Cloud (gcloud), AWS, Azure, Docker

Если у инструмента нет официального установщика в одну строку для вашей ОС, Документация открывает его страницу установки. Когда установка завершается, список сам проверяет всё заново.

Помочь с переводом этой страницы на GitHub (откроется в новой вкладке)