AI-powered HH.ru job monitoring and Telegram application assistant
Личный Telegram-бот, который отслеживает новые вакансии на HH.ru, оценивает их соответствие профилю кандидата через LLM, генерирует сопроводительные письма и помогает отправлять отклики.
Проект работает на VPS в Docker, хранит состояние в SQLite и рассчитан на одного владельца Telegram ID.
- несколько редактируемых поисковых профилей;
- поиск вакансий;
- каталог за последние семь дней, свежие вакансии показываются первыми;
- LLM-оценка релевантности от
0до100; - отдельные пороги для уведомлений и автоматического скрытия;
- генерация нейтральных сопроводительных писем длиной
500–800символов; - проверка русского языка, заглушек, посторонних алфавитов и необычных символов;
- ручной отклик по кнопке Telegram через Playwright;
- поддержка обычной формы HH и добавления письма через чат после мгновенного отклика;
- точная привязка действий к
vacancyId, защита от клика по похожей вакансии; - остановка при CAPTCHA, истёкшей сессии, тесте или неизвестной разметке;
- доступ только для одного разрешённого Telegram-пользователя.
flowchart LR
HH["Публичные страницы HH.ru"] --> Search["Поиск и разбор вакансий"]
Search --> Score["LLM-оценка релевантности"]
Score --> DB[("SQLite")]
DB --> TG["Telegram-каталог и уведомления"]
TG --> Letter["Генерация и проверка письма"]
Letter --> Browser["Playwright: форма или чат HH"]
Browser --> HH
Основные компоненты:
HHWebClient— читает публичную выдачу и страницы вакансий;SearchService— синхронизирует вакансии и поисковые профили;ScoringService— ставит LLM-оценку и применяет автоскрытие;NotificationService— отправляет новые подходящие карточки;HHApplyService— контролирует идемпотентность отклика;PlaywrightHHBrowser— работает с формой и iframe чата HH;Repository— изолирует хранение данных в SQLite.
- Python 3.12
- aiogram 3
- Playwright
- HTTPX + BeautifulSoup
- SQLAlchemy Async + SQLite
- OpenRouter API
- APScheduler
- Docker Compose
- pytest + Ruff
git clone https://github.com/kavotavochavo1-ctrl/hh-ai-job-bot.git
cd hh-ai-job-bot
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .envНа Linux:
python3 -m venv .venv
./.venv/bin/python -m pip install -e ".[dev]"
cp .env.example .envМинимально необходимые переменные:
TELEGRAM_BOT_TOKEN=replace-with-rotated-token
TELEGRAM_USER_ID=123456789
OPENROUTER_API_KEY=replace-with-openrouter-key
OPENROUTER_MODEL=deepseek/deepseek-v4-flash
OPENROUTER_SCORING_MODEL=deepseek/deepseek-v4-flashОтредактируйте candidate_profile.md: этот текст используется при оценке
вакансий и создании сопроводительных писем.
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check src tests scriptsdocker compose up -d --build
docker compose ps
docker compose logs --tail=100 botБаза и HH-сессия хранятся в постоянном volume bot-data.
OAuth-приложение HH не требуется: поиск использует публичные страницы. Для откликов нужна локально созданная браузерная сессия без сохранения пароля:
.\.venv\Scripts\python.exe -m playwright install chromium
.\.venv\Scripts\python.exe scripts\capture_hh_session.pyПосле входа появится hh_storage_state.json. Это секрет уровня пароля:
никогда не публикуйте файл и передавайте его на сервер только защищённым
способом.
По умолчанию включён HH_APPLY_DRY_RUN=true. В этом режиме бот не нажимает
новый отклик, поскольку HH может создать его мгновенно. Для реальной отправки
используйте HH_APPLY_DRY_RUN=false только после проверки сессии.
| Команда | Назначение |
|---|---|
/start |
Краткая справка |
/help |
Все доступные команды |
/vacancies |
Свежий каталог |
/hidden |
Скрытые вакансии |
/profiles |
Управление поисковыми профилями |
/threshold |
Порог уведомлений |
/hide_threshold |
Порог автоматического скрытия |
/status |
Состояние мониторинга |
В карточках доступны переоценка, скрытие, ссылка на HH и генерация
сопроводительного. Отправка запускается только отдельной кнопкой
📨 Отправить на HH.
Тесты не обращаются к реальным Telegram, OpenRouter и HH:
.\.venv\Scripts\python.exe -m pytest -qПокрыты репозиторий, фильтры, каталог, генерация и валидация писем, идемпотентность, HTML-клиент, Telegram-handlers, обычная форма HH и iframe чата.
GitHub Actions запускает pytest и Ruff для каждого push в main и каждого
pull request.
.env, SQLite, browser storage state и локальные virtualenv исключены из Git;- токен Telegram, OpenRouter key и HH-сессия не выводятся в логи;
- опубликованный ключ необходимо немедленно отозвать, даже если commit удалён;
- успешный отклик блокирует повторную отправку;
- при неопределённом результате Playwright не повторяет финальный клик.
Дополнительные правила описаны в SECURITY.md.
- HH может менять HTML и
data-qa, поэтому browser flow требует поддержки; - CAPTCHA и антибот-защита намеренно не обходятся;
- проект рассчитан на одного пользователя;
- OpenRouter требует действующий ключ и положительный баланс;
- автоматизация откликов должна использоваться ответственно и в соответствии с правилами площадки;
- проект не является официальным продуктом HH.ru и не связан с компанией HH.
Проект распространяется по лицензии MIT.