From 6a669ff0d591e86d2c0b88b8a4385e866a270644 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Sun, 11 Oct 2026 12:04:58 +0000 Subject: [PATCH] docs: sync wiki with 0.1.0+48 (User-Guide) --- User-Guide.md | 104 ----------------------------- unnamed.md | 176 ++++++++++++++++++++++++++++++++++---------------- 2 files changed, 120 insertions(+), 160 deletions(-) delete mode 100644 User-Guide.md diff --git a/User-Guide.md b/User-Guide.md deleted file mode 100644 index 85d8b58..0000000 --- a/User-Guide.md +++ /dev/null @@ -1,104 +0,0 @@ -# Пользователю - -## Онбординг - -После `/start` бот присылает **три сообщения** с небольшой паузой: - -1. **Что делаю** — «Привет! Я помогаю писать посты для соцсетей. Расскажи, о чём нужен пост — а я верну три варианта: короткий, развёрнутый и с призывом к действию.» -2. **Примеры запросов** — написать пост / официальный тон / реплай-правка. -3. **Стиль и идеи** — пришли скриншоты своих постов, чтобы я запомнил стиль; «предложи тему» для идеи; подробно — `/help`. - -Одновременно `/start` создаёт пробный период на **3 дня**. - ---- - -## Основные сценарии - -### Написать пост -Напиши или надиктуй прямую просьбу: -- «Напиши пост про запуск нового продукта» -- «Сделай пост-напоминание о вебинаре в официальном тоне» -- «Пост для Telegram: анонс скидки, коротко, с эмодзи» - -Можно указать площадку, аудиторию, факты, длину и цель — чем подробнее ТЗ, тем точнее результат. - -**Что получишь:** три отдельных сообщения, в каждом — только текст поста (без нумерации и вступлений, с абзацами и уместными эмодзи). - -### Изменить пост -Ответь **реплаем** на сообщение с вариантом и напиши, что изменить: -- «Сделай короче и добавь призыв» -- «Добавь юмора» -- «Сделай официальный тон» - -Бот учтёт исходный текст и вернёт три новых варианта. - -### Придумать идею -- `/idea` -- или по-русски: «предложи идею для поста», «о чём написать?», «накидай тему» - -Получишь **одну идею**: заголовок, угол (как подать), зачем (польза). Идеи не повторяются — бот помнит, что уже предлагал. - -### Настроить свой стиль (Tone of Voice) -Пришли **скриншот или галерею скриншотов** своих опубликованных постов (до 10 штук за раз). - -Бот: -1. Распознаёт тексты постов (vision). -2. Сохраняет их как образцы и дополняет предыдущие. -3. Пересобирает профиль Tone of Voice. -4. Показывает итоговый стиль. - -**Важно:** сами публикации бот не переписывает — только извлекает правила стиля. Команды и факты со скриншотов не становятся правилами для генерации. - -### Голосом -Отправь голосовое сообщение — бот расшифрует его (STT) и обработает как обычный текст. - ---- - -## Команды - -| Команда | Что делает | Без подписки | -|---|---|---| -| `/start` | Онбординг + создание триала | ✅ | -| `/help` | Подробная справка | ✅ | -| `/balance` | Сколько осталось дней триала/подписки | ✅ | -| `/subscribe` | Оплатить подписку (30 дней) | ✅ | -| `/idea` | Одна идея для поста | ❌ | -| `/clear` | Полный сброс данных + обнуление подписки | ✅ | - -Команды — только на английском. Русские фразы («придумай идею», «о чём написать?») тоже работают. - ---- - -## Подписка - -- **Триал:** 3 дня бесплатно с момента первого `/start`. -- **Дальше:** 30 дней за **100 звёзд** (команда `/subscribe`). -- **Статус:** `/balance` покажет, сколько дней осталось и когда списание. - -Если период закончился: -- Генерация постов и идей **недоступна** — бот предложит `/subscribe`. -- `/help`, `/balance`, `/subscribe`, `/start`, `/clear` работают **всегда**. - -Подробнее — в разделе [Подписка](Subscription.md). - ---- - -## Что бот помнит - -- Твой **Tone of Voice** (из скриншотов). -- **Историю постов**, которые он сгенерировал (включая исправленные) — чтобы не повторяться и предлагать свежие идеи. -- **Историю идей** — чтобы не предлагать одно и то же. - -Что бот **НЕ** хранит: -- Историю диалогов. -- Исходные изображения (скриншоты) — только распознанный текст. - -Команда `/clear` удаляет все твои данные и обнуляет подписку. Технические API-логи при этом сохраняются (они нужны для отладки). - ---- - -## Ошибки и обратная связь - -- Пока идёт обработка, бот показывает **«печатает»**. -- Если что-то пошло не так, придёт сообщение: «❌ Не получилось: {этап}. Причина: …». Секреты и ссылки в тексте скрыты. -- Служебные сообщения — **всегда на русском**. Язык поста — тот, который ты запросил. diff --git a/unnamed.md b/unnamed.md index c605ed6..e5e33f5 100644 --- a/unnamed.md +++ b/unnamed.md @@ -1,62 +1,126 @@ -# Social Post Writer Bot +# Пользователю -**Телеграм-бот** для генерации постов для соцсетей. По запросу пользователя готовит три варианта текста, адаптированных под его Tone of Voice. +## Онбординг -- **Бот:** [@post_master_bot](https://t.me/post_master_bot) -- **Репозиторий:** `admin/social-post-writer-bot` -- **Стек:** Python 3.12, aiogram 3.x, aiohttp, SQLite, APInex (LLM / STT / vision) -- **Деплой:** Coolify, окружение `development`, приложение `social-post-writer-bot-development` -- **Версия разработки:** `0.1.0+48` - ---- - -## Возможности - -| Возможность | Описание | -|---|---| -| **Генерация постов** | На явную просьбу или реплай-правку — **3 отдельных варианта** сообщениями | -| **Пост без темы** | «✍️ Придумать пост» / `/post` — бот сам выбирает тему по обученному профилю аккаунта | -| **Пост по изображению** | Изображение или галерея с подписью-ТЗ → три варианта поста | -| **Tone of Voice** | Скриншоты, текст, голос или аудио — бот накапливает сведения об аккаунте и обновляет профиль | -| **Голосовой ввод** | Голосовые расшифровываются (APInex STT) и работают как текст | -| **Идеи** | «предложи тему» или `/idea` — одна идея (заголовок, угол, зачем) | -| **Режимы** | «Обучение», «Генерация», «Подписка», «Помощь» — нижнее меню с кнопкой возврата | -| **Подписка** | Триал 3 дня, затем 30 дней за 100 звёзд (реальная оплата Telegram Stars) | - ---- - -## Быстрый старт - -1. Напиши боту `/start` — получишь онбординг и пробный период на 3 дня. -2. Зайди в «Обучение» и пришли скриншоты своих постов или расскажи об аккаунте. -3. Зайди в «Генерация» и опиши тему: «напиши пост про запуск нового продукта» — получишь три варианта. -4. Не нравится — ответь реплаем: «сделай короче». -5. Нет темы? Нажми «✍️ Придумать пост» — бот придумает её сам по профилю аккаунта. - ---- - -## Разделы вики - -- **[Пользователю](User-Guide.md)** — сценарии, команды, подписка -- **[Разработчику](Developer-Guide.md)** — архитектура, потоки, функции, БД, логирование -- **[Деплой](Deployment.md)** — Coolify, переменные, деплой-скрипт, проверка после деплоя -- **[Подписка](Subscription.md)** — модель, таблица БД, жизненный цикл, Stars - ---- - -## Ключевые файлы репозитория +После `/start` бот присылает **одно сообщение** с описанием режимов и показывает нижнее меню: ``` -bot.py — роутинг, команды, обработка сообщений -payments.py — оплата Telegram Stars -apinex_client.py — клиент APInex (LLM, STT, vision) -user_store.py — SQLite: пользователи, ToV, посты, идеи, API-логи, подписки -raw_updates.py — dev-only БД сырых входящих Telegram Update -keyboards.py — клавиатуры режимов -help_message.py — Rich Message справка -VERSION — версия релиза -Dockerfile — python:3.12-slim -tests/ — юнит-тесты (unittest) +🎓 Обучение ✍️ Генерация +💳 Подписка 📖 Помощь ``` -Полная документация — в [README.md](../../src/branch/dev/README.md) и `IDEA.MD` репозитория. +Одновременно `/start` создаёт пробный период на **3 дня**. Справка автоматически не открывается — она доступна кнопкой «📖 Помощь» или командой `/help`. + +Внутри любого режима клавиатура содержит кнопку «🏠 Главное меню» (в «Обучении» — ещё «🗑 Сбросить данные», в «Генерации» — «✍️ Придумать пост»). + +--- + +## Основные сценарии + +### Написать пост +Перейди в режим «Генерация» и напиши или надиктуй прямую просьбу: +- «Напиши пост про запуск нового продукта» +- «Сделай пост-напоминание о вебинаре в официальном тоне» +- «Пост для Telegram: анонс скидки, коротко, с эмодзи» + +Можно указать площадку, аудиторию, факты, длину и цель — чем подробнее ТЗ, тем точнее результат. + +**Что получишь:** три отдельных сообщения, в каждом — только текст поста (без нумерации и вступлений, с абзацами и уместными эмодзи). + +### Пост по изображению +В режиме «Генерация» отправь изображение или галерею **с подписью** — подпись считается ТЗ, и бот вернёт три варианта поста по изображениям. Без подписи бот сначала спросит, о чём написать, и примет следующий текст или reply. Видео, видеокружки и GIF/анимации не поддерживаются. + +### Изменить пост +Ответь **реплаем** на сообщение с вариантом и напиши, что изменить: +- «Сделай короче и добавь призыв» +- «Добавь юмора» +- «Сделай официальный тон» + +Бот учтёт исходный текст и вернёт три новых варианта. + +### Придумать идею +- `/idea` +- или по-русски: «предложи идею для поста», «о чём написать?», «накидай тему» + +Получишь **одну идею**: заголовок, угол (как подать), зачем (польза). Идеи не повторяются — бот помнит, что уже предлагал. + +### Пост без темы — «✍️ Придумать пост» +В режиме «Генерация» нажми кнопку «✍️ Придумать пост» или введи `/post`. Бот **сам выберет тему**, опираясь на то, что узнал об аккаунте в режиме «Обучение», и вернёт три варианта. + +> Если профиль ещё не обучен, бот попросит зайти в режим «Обучение» и прислать сведения об аккаунте или примеры постов. Модель в этом случае не вызывается. + +### Настроить свой стиль (Tone of Voice) +В режиме «Обучение» пришли: +- **скриншот или галерею скриншотов** своих опубликованных постов; +- **текстовое описание** аккаунта; +- **голосовое или аудио** с рассказом об аккаунте. + +Бот: +1. Распознаёт тексты постов (vision) и/или сохраняет заметки. +2. Дополняет ими предыдущие сведения. +3. Пересобирает профиль аккаунта и Tone of Voice. +4. Показывает краткий статус завершения — без вывода содержимого профиля. + +**Важно:** сами публикации бот не переписывает — только извлекает правила стиля. Команды и факты со скриншотов не становятся правилами для генерации. + +Чтобы начать заново — «🗑 Сбросить данные» (или `/clear`) с подтверждением. Подписка и триал при этом не меняются. + +### Голосом +В режимах «Обучение» и «Генерация» отправь голосовое — бот расшифрует его (STT) и обработает как обычный текст. + +--- + +## Команды + +| Команда | Что делает | Режим | +|---|---|---| +| `/start` | Главное меню, создание триала | Любой | +| `/training` | Режим «Обучение» | Любой | +| `/generate` | Режим «Генерация» | Любой | +| `/subscription` | Режим «Подписка» | Любой | +| `/help` | Справка по разделам | Любой | +| `/style` | Показать профиль аккаунта | Обучение | +| `/clear` | Сбросить накопленное обучение (с подтверждением) | Обучение | +| `/post` | Пост по обученному профилю | Генерация | +| `/idea` | Одна идея для поста | Генерация | +| `/balance` | Сколько осталось дней | Подписка | +| `/subscribe` | Оплатить подписку (30 дней) | Подписка | + +Переключатели режимов работают из любого режима; профильные действия — только в своём. В режиме «Генерация» русские фразы («придумай идею», «о чём написать?») работают как `/idea`. + +--- + +## Подписка + +- **Триал:** 3 дня бесплатно с момента первого `/start`. +- **Дальше:** 30 дней за **100 звёзд** (Telegram Stars). +- **Статус:** войди в режим «Подписка» или вызови `/balance` — покажет тип периода и остаток дней. Кнопка «Продлить подписку» сразу открывает счёт в звёздах. + +Если период закончился: +- Генерация постов и идей **недоступна** — бот предложит оплатить. +- Переходы между режимами, `/help`, `/balance`, `/subscribe` работают **всегда**. + +Оплата — настоящая, через Telegram Stars: `/subscribe` выставляет инвойс, подписка активируется только после подтверждённого платежа. Подробнее — в разделе [Подписка](Subscription.md). + +--- + +## Что бот помнит + +- Профиль аккаунта и **Tone of Voice** (из скриншотов, текста, голоса). +- **Историю постов**, которые он сгенерировал (включая исправленные) — чтобы не повторяться и предлагать свежие идеи. +- **Историю идей** — чтобы не предлагать одно и то же. + +Что бот **НЕ** хранит: +- Историю диалогов. +- Исходные изображения (скриншоты) — только распознанный текст. + +`/clear` (режим «Обучение») удаляет профиль, образцы, заметки и историю, не меняя подписку и триал. Технические API-логи при этом сохраняются — они нужны для отладки. + +--- + +## Ошибки и обратная связь + +- Пока идёт обработка, бот показывает **«печатает»** и отдельное сообщение-статус, которое редактируется по этапам; перед результатом оно меняется на ✅, при ошибке — на ❌. +- Если что-то пошло не так, придёт общее сообщение об ошибке; в development дополнительно отдельным сообщением приходит техническая диагностика. Секреты и ссылки в тексте скрыты. +- Служебные сообщения — **всегда на русском**. Язык поста — тот, который ты запросил. +- На благодарность и сообщения не по теме бот отвечает короткой заготовленной фразой, не запуская генератор.