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)

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

hh-ai-agent

Links

README