HH AI Agent
Агент автоматически ищет вакансии на HH.ru, оценивает их через LLM, генерирует сопроводительные письма и присылает подходящие в Telegram.
Быстрый старт
Запусти мастер настройки — он проведёт тебя через все шаги:
python setup_wizard.py
Wizard спросит:
- Токен Telegram-бота и твой User ID
- Какой AI-провайдер использовать (Ollama локально, Mistral API или любой OpenAI-compatible)
- Данные твоего профиля для анализа вакансий
- Режим работы
После этого создаст .env и profile.yaml, проверит конфигурацию и покажет что делать дальше.
Изменить настройки позже:
python setup_wizard.py --edit
Требования
- Python 3.11+
- Telegram Bot (создаётся через @BotFather)
- Один из LLM-провайдеров (подробнее ниже)
- CloakBrowser (устанавливается автоматически через wizard)
Режимы работы
| Режим | Описание |
|---|---|
dry_run | Ищет и анализирует вакансии, присылает превью в Telegram — без реальных откликов |
approval | Присылает вакансию с кнопкой «Откликнуться» — отклик только после твоего нажатия |
Начинай с dry_run. Переходи на approval после того как убедишься что всё работает.
Карточка вакансии показывает краткое объяснение совпадения, рейтинг компании с HH и сворачиваемое сопроводительное письмо. Если rich messages недоступны, бот отправляет обычную HTML-карточку.
LLM-провайдеры
Ollama (рекомендуется — локально, бесплатно)
- Установи Ollama
- Загрузи модель:
ollama pull llama3 - В wizard выбери Ollama
Mistral API (облачный)
- Зарегистрируйся на console.mistral.ai
- Создай API ключ
- В 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 + ключ.
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 | Анализ вакансий, генерация писем |
database.py | SQLite-состояние, лимиты, переходы статусов |
approval.py | Единственный разрешённый инициатор реального отклика |
tg_bot.py | Telegram-команды, превью, inline-кнопки |
main.py | Основной цикл агента |
setup_wizard.py | Интерактивный мастер настройки |
Безопасность
- Реальный отклик требует трёх одновременных условий:
APP_MODE=approval+ENABLE_REAL_APPLY=true+ нажатие кнопки твоим Telegram ID; одноразовое разрешение действует 30 минут после нажатия - Массового автоматического режима нет
.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 — он реализовал базовые проверки и валидацию конфигурации, которые легли в основу надёжной работы агента.
Контакты
Вопросы и предложения: @fikstt3 (telegram)