docs: record project context in AGENT.md
Build and push Docker image / docker (push) Has been cancelled
Details
Build and push Docker image / docker (push) Has been cancelled
Details
This commit is contained in:
parent
c633ab834a
commit
2c84eaaa9a
164
AGENT.md
164
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_<user_id>` и кнопка копирования;
|
||||
- друг должен перейти по ссылке, запустить бота и впервые оплатить;
|
||||
- реферер получает +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` и `:<sha>`, а также локальный `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`-задачей не тестировались.
|
||||
- При рестарте активная генерация прерывается.
|
||||
- Веб без авторизации — не публиковать наружу.
|
||||
|
|
|
|||
Loading…
Reference in New Issue