Workzilla Parser

Личный сервис для мониторинга новых задач на Workzilla, их автоматической оценки на релевантность и отправки подходящих задач в Telegram.

Проект уже умеет:

• читать ленту задач из авторизованного JSON endpoint Workzilla;
• сохранять задачи в локальную БД;
• не переобрабатывать уже известные задачи;
• прогонять новые задачи через rule-based prefilter;
• передавать прошедшие задачи в LLM-классификатор;
• отправлять релевантные задачи в Telegram;
• работать в разовом режиме и в постоянном polling loop.

Возможности

• Авторизация через браузерный login flow и сохранение session state.
• Сбор задач без HTML-парсинга страницы, через внутренний API.
• Дедупликация по external_id.
• Единый профиль интересов в interest_profile.json.
• Тестирование фильтров без отправки уведомлений.
• Поддержка OpenAI-compatible LLM API, включая OpenRouter.
• Безопасный polling с настраиваемым интервалом и jitter.

Техническая Идея

Текущая архитектура:

1. Playwright используется для ручного логина и сохранения сессии.
2. httpx использует сохраненную сессию и получает список открытых задач через Workzilla endpoint.
3. Rule-based prefilter отсеивает очевидно неподходящие задачи.
4. LLM оценивает только те задачи, которые прошли prefilter.
5. Релевантные задачи уходят в Telegram.
6. Все задачи и результаты проверок сохраняются в SQLite.

Практически это выглядит так:

Workzilla -> HTTP collector -> prefilter -> LLM -> Telegram

Требования

• Windows PowerShell
• Python 3.12+ по pyproject.toml
• доступ к аккаунту Workzilla
• Telegram bot token и chat id
• API ключ для LLM, если нужен LLM-слой

Основные зависимости:

• httpx
• playwright
• sqlalchemy
• pydantic-settings
• aiogram

Структура Проекта

WorkzillaParser/
  app/
    classifiers/
    collectors/
    config/
    notifiers/
    schemas/
    services/
    storage/
  data/
  logs/
  tests/
  .env.example
  interest_profile.json
  PLAN.md
  README.md
  STAGE0_FINDINGS.md
  STAGE0_RESEARCH.md
  pyproject.toml

Основные папки:

• app/collectors - сбор задач и работа с авторизацией.
• app/classifiers - prefilter и LLM-классификация.
• app/notifiers - Telegram-уведомления.
• app/storage - SQLite и репозиторий.
• app/services - pipeline и polling.

Установка

1. Установить зависимости

Из корня проекта:

python -m pip install --upgrade pip
python -m pip install -e .
python -m playwright install chromium

2. Подготовить .env

Скопируй значения из .env.example в .env и заполни нужные параметры.

Минимально важные секции:

• Workzilla session/config
• Telegram
• LLM

3. Создать БД

python -m app.main init-db

Настройка

.env

Основные переменные:

APP_ENV=development
LOG_LEVEL=INFO
DATABASE_URL=sqlite:///./data/workzilla.db
INTEREST_PROFILE_PATH=./interest_profile.json

WORKZILLA_BASE_URL=https://client.work-zilla.com
WORKZILLA_FREELANCER_URL=https://client.work-zilla.com/freelancer
WORKZILLA_OPEN_ORDERS_PATH=/api/order/v6/list/open
WORKZILLA_SESSION_STATE_PATH=./data/private/storage_state.json
WORKZILLA_AUTH_METADATA_PATH=./data/private/auth_metadata.json
WORKZILLA_AGENT_ID=
WORKZILLA_POLL_INTERVAL_SECONDS=45
WORKZILLA_POLL_JITTER_SECONDS=15

TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

LLM_ENABLED=true
LLM_PROVIDER=openrouter
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=openrouter/free
LLM_API_KEY=

interest_profile.json

Главное место для настройки интересов.

В файле можно менять:

• summary - краткое описание твоего профиля;
• min_price - минимальная цена задачи;
• include_keywords - что prefilter чаще всего должен пропускать;
• exclude_keywords - что нужно отсекать сразу;
• interests - список интересов для LLM prompt;
• anti_interests - что LLM должна считать нежелательным.

Пример текущего тестового профиля лежит в interest_profile.json.

Авторизация Workzilla

Для сбора задач нужен сохраненный session state.

Запуск:

python -m app.main login

Что происходит:

1. Открывается браузер через Playwright.
2. Ты вручную входишь в аккаунт Workzilla.
3. После загрузки кабинета возвращаешься в терминал.
4. Нажимаешь Enter.
5. Проект сохраняет:
   • storage_state.json
   • auth_metadata.json

Эти файлы используются далее для HTTP-сбора задач.

Команды CLI

Основные команды:

python -m app.main doctor
python -m app.main init-db
python -m app.main login
python -m app.main show-profile
python -m app.main preview-filter
python -m app.main preview-llm
python -m app.main collect-once
python -m app.main watch
python -m app.main notify-test

Кратко по командам:

• doctor Показывает активную конфигурацию без секретов.
• init-db Создает таблицы SQLite.
• login Открывает браузер и сохраняет Workzilla session state.
• show-profile Показывает активный профиль интересов.
• preview-filter Показывает решения только rule-based prefilter.
• preview-llm Показывает задачи, дошедшие до LLM, и финальные решения классификатора.
• collect-once Выполняет один цикл сбора, классификации и отправки уведомлений.
• watch Запускает постоянный polling loop.
• notify-test Отправляет тестовое сообщение в Telegram.

Типовой Сценарий Первого Запуска

1. Установить зависимости.
2. Заполнить .env.
3. Настроить interest_profile.json.
4. Выполнить:

python -m app.main init-db
python -m app.main login

5. Проверить профиль:

python -m app.main show-profile

6. Проверить prefilter:

python -m app.main preview-filter

7. Проверить LLM:

python -m app.main preview-llm

8. Проверить Telegram:

python -m app.main notify-test

9. Выполнить один реальный проход:

python -m app.main collect-once

10. Переключиться в постоянный режим:

python -m app.main watch

Как Работают Фильтры

Система использует 2 уровня фильтрации.

1. Rule-Based Prefilter

Фильтрует по:

• минимальному бюджету;
• include keywords;
• exclude keywords.

Зачем:

• отсечь очевидный мусор;
• сократить число запросов в LLM;
• снизить стоимость;
• ускорить обработку.

2. LLM-Классификатор

Видит только те задачи, которые прошли prefilter.

LLM возвращает:

• is_relevant
• score
• reason
• category
• confidence

Telegram Уведомления

Когда задача признана релевантной, бот отправляет:

• заголовок;
• Task ID;
• цену задачи;
• сумму исполнителю;
• score;
• категорию;
• confidence;
• причину решения;
• сокращенное описание;
• ссылку на кабинет Workzilla.

Для включения укажи в .env:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Проверка:

python -m app.main notify-test

Автоматический Режим

Для постоянной работы:

python -m app.main watch

Что делает watch:

• запускает collect-once в цикле;
• ждет безопасный интервал между циклами;
• добавляет случайный jitter;
• корректно останавливается по Ctrl+C.

Рекомендуемый безопасный polling:

WORKZILLA_POLL_INTERVAL_SECONDS=45
WORKZILLA_POLL_JITTER_SECONDS=15

Это дает реальный интервал примерно 45-60 секунд между циклами.

Дедупликация

Проект не переобрабатывает уже известные задачи.

Как это работает:

• каждая задача сохраняется по external_id;
• если задача уже есть в БД, она пропускается;
• повторно не запускаются:
  • prefilter
  • LLM
  • Telegram-уведомления

Это защищает от дублей и повторного спама.

Текущая версия не переобрабатывает задачи, если они изменились, но сохранили тот же external_id. Это можно добавить позже как улучшение.

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

Что важно:

• не хранить пароль Workzilla в коде;
• не коммитить .env;
• не коммитить storage_state.json;
• не коммитить auth_metadata.json;
• не публиковать HAR-файлы;
• не делать слишком агрессивный polling.

Проект уже игнорирует чувствительные артефакты через .gitignore.

Хранилище

Сейчас используется SQLite.

Основные данные:

• задачи;
• результаты классификации;
• статус уведомлений.

Файл БД по умолчанию:

• data/workzilla.db

Известные Ограничения

• авторизация пока завязана на ручной login flow;
• сессия Workzilla может протухать и требовать повторного login;
• часть free-моделей OpenRouter может вести себя нестабильно;
• LLM prompt пока общий и требует дальнейшей настройки под твои реальные интересы;
• обновления уже известных задач пока не переоцениваются.

Диагностика

Полезные команды:

python -m app.main doctor
python -m app.main show-profile
python -m app.main preview-filter
python -m app.main preview-llm

Если что-то идет не так:

• проверь .env;
• проверь, сохранена ли Workzilla session;
• проверь Telegram через notify-test;
• проверь LLM через preview-llm;
• проверь профиль интересов через show-profile.

Документы

• PLAN.md - общий план проекта.
• STAGE0_RESEARCH.md - исследование этапа 0.
• STAGE0_FINDINGS.md - найденные технические детали по Workzilla API.

Ближайшие Улучшения

• более точный личный профиль интересов;
• обработка обновленных задач по modified;
• запуск как системный сервис;
• расширенный лог ошибок и метрик;
• управление через Telegram-команды;
• история и статистика уведомлений.