HH AI Agent

Агент автоматически ищет вакансии на HH.ru, оценивает их через LLM, генерирует сопроводительные письма и присылает подходящие в Telegram.

Быстрый старт

Запусти мастер настройки — он проведёт тебя через все шаги:

python setup_wizard.py

Wizard спросит:

1. Токен Telegram-бота и твой User ID
2. Какой AI-провайдер использовать (Ollama локально, Mistral API или любой OpenAI-compatible)
3. Данные твоего профиля для анализа вакансий
4. Режим работы (dry_run, approval или auto)

После этого создаст .env и profile.yaml, проверит конфигурацию и покажет что делать дальше.

Изменить настройки позже:

python setup_wizard.py --edit

---

Требования

• Python 3.11+
• Telegram Bot (создаётся через @BotFather)
• Один из LLM-провайдеров (подробнее ниже)
• CloakBrowser (устанавливается автоматически через wizard)

---

Режимы работы

Режим	Описание
dry_run	Ищет и анализирует вакансии, присылает превью в Telegram — без реальных откликов
approval	Присылает вакансию в Telegram с кнопкой «Откликнуться» для ручного подтверждения
auto (автоподача)	Автоматически откликается на вакансии с высоким совпадением (по умолчанию ≥ 85%) безопасными пачками по расписанию; остальные отправляет на ручной аппрув

Начинай с dry_run. Переходи на approval или auto после того как убедишься что всё работает.

Карточка вакансии показывает краткое объяснение совпадения, рейтинг компании с HH и сворачиваемое сопроводительное письмо. Если rich messages недоступны, бот отправляет обычную HTML-карточку.

Опциональная автоподача

Автоподача выключена по умолчанию. Для её включения нужны все три настройки:

APP_MODE=approval
ENABLE_REAL_APPLY=true
AUTO_APPLY_ENABLED=true

Порог совпадения, размер пачки, интервалы и рабочее окно задаются через AUTO_APPLY_* в .env. Агент соблюдает MAX_APPLICATIONS_PER_DAY, продолжает поиск до достижения фактического размера пачки и отправляет итог каждого запуска в Telegram. Вакансии ниже порога остаются на ручной проверке. Если состояние отправки нельзя подтвердить, circuit breaker приостанавливает следующие отклики.

---

LLM-провайдеры

Ollama (рекомендуется — локально, бесплатно)

1. Установи Ollama
2. Загрузи модель:

   ollama pull llama3

3. В wizard выбери Ollama

Mistral API (облачный)

1. Зарегистрируйся на console.mistral.ai
2. Создай API ключ
3. В wizard выбери Mistral API и введи ключ

Wizard создаёт отдельный MISTRAL_KEYS_MASTER_KEY для локального шифрования ключей. Сохрани резервную копию этого значения: без него уже сохранённые ключи расшифровать нельзя. После запуска ключами можно управлять командой /mistral_keys; в Telegram и логах показываются только последние четыре символа.

⚠️ При Mistral текст вакансий и твой профиль уходят во внешний API.

OpenAI-compatible (любой совместимый)

Поддерживается любой сервис с эндпоинтом /chat/completions (LocalAI, LM Studio, Groq и т.п.). В wizard выбери OpenAI-compatible и укажи URL + ключ.

При использовании облачного OpenAI-compatible провайдера текст вакансии и данные профиля передаются этому провайдеру.

---

Telegram-команды

Команда	Описание
/start	Краткая справка
/status	Режим, состояние, статистика
/pause	Приостановить поиск
/resume	Возобновить поиск
/pending	Вакансии, ожидающие решения
/stats	Статистика по статусам
/diagnostics	Результат последнего цикла и состояние circuit breaker
/mistral_keys	Список, проверка, добавление и удаление Mistral-ключей
/cancel	Отменить ввод CAPTCHA

---

Архитектура

Файл	Ответственность
config.py	Валидация .env и profile.yaml
browser_backend.py	CloakBrowser / Playwright адаптер
hh_client.py	Поиск, чтение страниц, отправка откликов
llm/	Ollama / Mistral / OpenAI-compatible адаптеры, retry, квота
ai_analyzer.py	Анализ вакансий, генерация писем
cover_letter.py	Нормализация и обязательные проверки сопроводительного письма
database.py	SQLite-состояние, лимиты, переходы статусов
approval.py	Единственный разрешённый инициатор реального отклика
tg_bot.py	Telegram-команды, превью, inline-кнопки
main.py	Основной цикл агента
instance_lock.py	Защита от одновременного запуска двух процессов
setup_wizard.py	Интерактивный мастер настройки

---

Безопасность

• Реальный отклик требует APP_MODE=approval + ENABLE_REAL_APPLY=true и либо нажатия кнопки твоим Telegram ID, либо отдельно включённой автоподачи с достаточным confidence
• Автоподача выключена по умолчанию и ограничивается размером пачки, рабочим окном и дневным лимитом
• Ссылка на портфолио может быть объявлена обязательной; без неё письмо не будет отправлено
• После начала отправки неопределённый результат резервирует дневной слот и останавливает автоматическую серию, чтобы не создавать дубли
• .env, profile.yaml и .browser-profile/ исключены из Git
• Токены, cookies и полный .env не записываются в логи

---

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

Ошибка	Решение
Configuration error	Заполни все обязательные поля через python setup_wizard.py --edit
CloakBrowser failed to start	Проверь python -m cloakbrowser info, при необходимости смени на BROWSER_BACKEND=playwright
HH.ru login is required	Запусти с BROWSER_HEADLESS=false и войди вручную
LLM check failed	Проверь endpoint, ключ и дневную квоту через python main.py --check-llm
Invalid model response	Проверь провайдер и модель — вакансия безопасно пропускается

---

Разработка

Тесты не обращаются к HH.ru, Telegram или внешним LLM:

python -m compileall .
pytest -q

---

Ограничения

• Автоматизация может нарушать правила HH.ru — ответственность за аккаунт несёт пользователь
• CloakBrowser не гарантирует отсутствие детектирования или CAPTCHA
• Нет proxy, GeoIP-ротации и внешних CAPTCHA-сервисов
• Рассчитано на одного владельца и одну SQLite-базу
• В ручном режиме письмо можно проверить и отредактировать в Telegram; автоподача отправляет его без предварительного просмотра

---

Благодарности

Огромное спасибо kkonstantin08 за разработку этой архитектуры — именно он спроектировал весь безопасный конвейер от поиска вакансий до approval-механизма с permit-токенами.

Также благодарность danscMax — он реализовал базовые проверки и валидацию конфигурации, которые легли в основу надёжной работы агента.

Искренняя благодарность vadzhipov (Azat Vadzhipov) — за проектирование и реализацию надёжного механизма автоподачи откликов (guarded auto-apply) с пакетированием, контролем порога совпадения, рабочим окном и защитой circuit breaker.

---

Контакты

Вопросы и предложения: @fikstt3 (telegram)

Disclamer: автоматизация HH.ru нарушает пользовательское соглашение, использовать на свой страх и риск. Автор не несет ответственность за возможные ограничения аккаунта.