From 2c84eaaa9abb2e36e47cbe66d72a7d3f02ee5b09 Mon Sep 17 00:00:00 2001 From: MpakobecEx Date: Sun, 18 Oct 2026 23:42:35 +0500 Subject: [PATCH] docs: record project context in AGENT.md --- AGENT.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 145 insertions(+), 19 deletions(-) diff --git a/AGENT.md b/AGENT.md index f47c0c2..540bf6d 100644 --- a/AGENT.md +++ b/AGENT.md @@ -1,4 +1,4 @@ -# AGENT.md — правила работы +# AGENT.md — правила и контекст проекта ## Ответы @@ -12,33 +12,159 @@ ## Проект - Корень: `D:\!Projects\MpakoImageAIbot`. -- Стек: Python 3.10+, python-telegram-bot 21+, httpx, aiosqlite, SQLite, Docker. -- Требования: `plan.md`. План работ: `checklist.md`; отмечать выполненные пункты. +- Стек: Python 3.10+, python-telegram-bot 21+, httpx, aiosqlite, SQLite, Docker, FastAPI/Jinja2. +- Требования: `plan.md`. План и статус: `checklist.md`. - Следовать структуре, именованию и стилю существующего кода. - Секреты — только в `.env`. Не логировать токены, не коммитить `.env`, `storage/`, `data/`. +## Текущее состояние (актуально на 18.10.2026) + +- Последний коммит локально и на сервере: `c633ab8` — «Ретраи Telegram». +- Бот: `@EroDrawAI_bot`. +- Сервер: `/home/mpakobecex/MpakoImageAIbot`, Docker Compose, контейнеры `mpakoimageaibot-bot-1` и `mpakoimageaibot-web-1` — `Up`. +- Веб: `http://192.168.31.158:8099`, доступ только из LAN, без авторизации. +- ComfyUI: `http://192.168.31.113:8188`, v0.40.0, RTX 4060 Ti 8 GB. +- Тесты: `54 passed`; `ruff` чистый. + +## Функционал + +- T2I: Z-Image Turbo (`workflows/txt2img.json`). +- I2I: Krea2 edit (`workflows/img2img.json`), вход через фото+подпись или reply на картинку. +- Улучшение промптов: ComfyUI `TextGenerate` + `qwen3vl_4b` (`workflows/prompt_enhance.json`), ChatML, `sampling_mode=off`. +- Очередь: + - обычная и премиум; + - строгое чередование: одна премиум, одна обычная; + - если одна пуста — берётся из другой; + - одна активная задача на пользователя. +- Оплата Telegram Stars (`XTR`): + - обычная очередь — 5 звёзд; + - премиум — 15 звёзд; + - админы бесплатно и в премиум-очередь; + - перед оплатой показываются счётчики обеих очередей и кнопки выбора; + - возврат звёзд при ошибке постановки/генерации. +- Баланс: + - новый пользователь — 3 генерации; + - +1 каждый день в 00:00 МСК, пропущенные дни добираются; + - обычная генерация списывает 1 генерацию или 5 звёзд; + - премиум не списывает баланс. +- Рефералы: + - `/invite` — ссылка `?start=ref_` и кнопка копирования; + - друг должен перейти по ссылке, запустить бота и впервые оплатить; + - реферер получает +3 генерации и уведомление. +- Возраст: обязательное подтверждение 18+ через кнопки в `/start`; без него запросы/оплата недоступны. Отказ сохраняется в БД. +- Модерация: CSAM, зоофилия, публичные люди, non-consensual, насилие+NSFW, экстремизм, обходные написания. Блокировки логируются в `blocked_requests`. +- OpenCV удалён из-за зависания CI; при i2i без детектора NSFW-промпты блокируются консервативно. +- Веб-история: фильтры по user_id/статусу/режиму, превью, карточка запроса; видны оригинальный и улучшенный промпты. +- Веб-пользователи `/users`: поиск, баланс, админ-флаг, блокировка, статус 18+. + +## Архитектура + +- `bot.py` — Telegram-хендлеры, оплата, возраст, баланс, рефералы, health-check. +- `queue_manager.py` — очередь, чередование premium/normal, воркер, прогресс, события. +- `db.py` — SQLite, миграции, users/requests/pending_payments/blocked_requests. +- `comfy_client.py` — HTTP + WebSocket ComfyUI, upload/history/view, текст. +- `prompt_enhancer.py` — улучшение/перевод промпта через ComfyUI. +- `moderation.py` — `is_prompt_allowed`, причины блокировок, `detect_person`. +- `workflows.py` — валидация подстановок в workflow. +- `web.py` + `web/templates` — FastAPI-история и управление пользователями. +- `config.py` — env и настройки. + +## База данных + +- `requests`: статусы `queued/running/done/failed`, mode, seed, username, enhanced_prompt, payment_charge_id, payment_refunded, is_premium. +- `users`: credits, last_daily_credit, referrer_id, first_paid_at, is_admin, is_blocked, age_confirmed, age_declined. +- `pending_payments`: payload, amount, status, charge_id, request_id, is_premium. +- `blocked_requests`: user_id, timestamp, prompt, reason, mode, has_person. +- `app_settings`: `admins_seeded`. +- SQLite WAL; файлы в `storage/`, БД в `data/`, оба volume в Docker. + +## Env (сервер) + +Не выводить `.env` в чат. Ключевые значения: + +```dotenv +COMFY_BASE_URL=http://192.168.31.113:8188 +TELEGRAM_PROXY=http://host.docker.internal:20171 +WEB_BIND_IP=192.168.31.158 +PROMPT_ENHANCE_ENABLED=true +MODERATION_ENABLED=true +PAYMENTS_ENABLED=true +STARS_PRICE=5 +PREMIUM_STARS_PRICE=15 +ADMIN_USER_IDS=7467236616,6532518406 +TELEGRAM_RETRY_ATTEMPTS=0 +TELEGRAM_RETRY_MAX_DELAY=30 +TELEGRAM_HEALTH_INTERVAL=60 +``` + +- `ADMIN_USER_IDS` — только первичный сид; далее админы в БД (`users.is_admin`), управляются через `/users`. +- `.env` на сервере имеет права `600`, не коммитится. + ## Git / Gitea - Remote: `ssh://git@home:2222/mpakobecex/MpakoImageAIbot.git` (алиас `home` → `192.168.31.158`). -- Основная ветка — `main`. -- Перед коммитом: `git diff`, тесты/линтер, если есть. +- Ветка `main`. +- Gitea Registry: `git.mpakosrv.ru/mpakobecex/mpakoimageaibot`. +- CI: `.gitea/workflows/docker-build.yml`, runner `ubuntu-latest`, Docker socket. + Собирает и пушит `latest` и `:`, а также локальный `mpakoimageaibot:latest`. +- Секреты CI: `REGISTRY_USER`, `REGISTRY_TOKEN`. +- Перед коммитом: `ruff check . --exclude .venv`, `pytest -q`, `git diff --check`. - Коммиты атомарные: `feat:`, `fix:`, `docs:`, `chore:`. -- Не делать force push и не переписывать историю. -- Push — после успешной проверки. +- Push после проверки. Force push — только по прямой команде пользователя. -## Работа с кодом +## Деплой -- Сначала прочитать существующий код, затем менять. -- Изменения минимальные и точечные; без попутного рефакторинга. -- Не удалять и не перезаписывать пользовательские файлы без подтверждения. -- Сетевые вызовы — async, event loop не блокировать. -- Ошибки обрабатывать явно: понятное сообщение пользователю + лог. -- После изменений проверять запуск/тесты и сообщать результат. -- Не оставлять проект в нерабочем состоянии. +```bash +ssh home +cd ~/MpakoImageAIbot +git fetch origin +git reset --hard origin/main +docker compose up -d --no-build +``` -## Безопасность +- После изменения `.env`: + ```bash + docker compose up -d --force-recreate --no-build bot + ``` + `docker compose restart` не перечитывает env. +- Перед деплоем проверить активную генерацию: + ```bash + curl -s http://192.168.31.113:8188/queue + ``` + Рестарт прерывает текущую задачу и помечает её `failed`. +- Логи: `docker compose logs --tail=50 bot`. -- Не выводить содержимое `.env` и приватные ключи. -- Не выполнять деструктивные команды без подтверждения. -- Не добавлять зависимости без необходимости. +## Telegram + +- Прокси V2RayA: `http://host.docker.internal:20171`. +- PTB использует proxy и get_updates_proxy. +- `TELEGRAM_RETRY_ATTEMPTS=0` — повторять операции до успеха; backoff до 30 с. +- Health-check `getMe` каждые 60 с; при сбое ретраи с backoff. +- Критичные отправки/счета/результаты ретраятся; статус-сообщения — до 3 попыток. +- Не логировать токен: httpx-логи приглушены. + +## Команды бота + +- `/start` — приветствие, баланс, цены, возрастной gate. +- `/help` — инструкция. +- `/balance` — баланс. +- `/invite` — реферальная ссылка + копирование. +- `/status` — статус задачи. + +## Веб + +- `/` — история запросов, превью, фильтры. +- `/users` — управление пользователями. +- `/request/{id}` — карточка запроса. +- `/media/{id}/input|output`, `/thumb/{id}`. +- Авторизации нет; порт слушает только `WEB_BIND_IP`. + +## Известные ограничения / не проверено + +- Реальная оплата Stars и реферальное начисление в Telegram не проверены. +- Нет сброса 18+ через веб; отказ сохраняется в БД. +- OpenCV отсутствует: i2i NSFW блокируется консервативно. +- Очередь 3+ пользователей, падение ComfyUI, рестарт с `running`-задачей не тестировались. +- При рестарте активная генерация прерывается. +- Веб без авторизации — не публиковать наружу.