## Обзор
**ReMind** это AI-приложение на React/Vite и Flask, собранное как продуктовая база: streaming chat, сохранение сессий, share-ссылки, авторизация, безопасные загрузки, privacy endpoints, OpenAPI-контракт, Celery worker и Docker Compose-инфраструктура лежат в одном репозитории.
| Что важно | Как это устроено |
|---|---|
| AI chat workspace | SSE-стриминг, история сообщений, session management, guest/auth режимы |
| Мультимодальность | File upload pipeline, image flow, voice synthesis, translate endpoint |
| Приватность | Экспорт данных, удаление аккаунта/данных, secure session handling |
| Production base | Nginx, PostgreSQL, Redis, Celery, health checks, metrics, CI/security gate |
| Extensibility | OpenAPI и shared services поверх общего backend layer |
## Возможности
- Streaming AI chat через `POST /chat` с server-sent events.
- История диалогов, список сессий, удаление и восстановление контекста.
- Public read-only share links через `/sessions//share` и `/c/`.
- Guest mode и auth mode в одном интерфейсе.
- Регистрация, логин, профиль, настройки, избранное, Google OAuth и Telegram Login OIDC.
- Telegram-бот как синхронизированный канал ReMind: личные и групповые чаты, Guest Mode, inline-ответы, rich Markdown, streaming drafts и нативный Thinking-блок.
- Безопасная загрузка файлов с проверкой имени, MIME-типа и содержимого.
- Перевод текста и text-to-speech через отдельные API endpoints.
- При запросе озвучивания выбранный текст передаётся внешнему Google Translate TTS endpoint; не используйте озвучивание для секретных данных.
- Privacy flows: export/delete пользовательских данных.
- HTML/JSON health check, Prometheus-style `/metrics` и audit logging.
## Технологический стек
| Слой | Стек |
|---|---|
| Frontend | React 19, TypeScript, Vite 7, i18next, Chart.js, D3, Mermaid, Nomnoml |
| Backend | Python 3.11, Flask, Flask-SQLAlchemy, Flask-Session, Authlib, Waitress, Gunicorn |
| AI / Media | AI provider adapter, local `echo`, `demo_image`, Pillow, server-side speech synthesis |
| Storage / Queue | SQLite for local development, PostgreSQL for deployment, Redis, Celery |
| Infra | Docker, Docker Compose, Nginx |
| Quality | Ruff, Black, MyPy, ESLint, TypeScript, GitHub Actions |
## Быстрый старт
### Требования
- Python `3.11`
- Node.js `20+`
- Redis `7+`
- Git
- `AI_PROVIDER_API_KEY` для основного AI-сценария
### 1. Клонирование
```bash
git clone https://github.com/ReNothingg/ReMind.git
cd ReMind
```
### 2. Установка зависимостей
PowerShell:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
npm ci
Copy-Item .env.example .env
```
Bash:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm ci
cp .env.example .env
```
### 3. Настройка `.env`
Минимальная полезная локальная конфигурация:
```env
SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=sqlite:///database/users.db
REDIS_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/1
AI_PROVIDER_API_KEY=
AI_PROVIDER_MODEL_NAME=
```
`AI_PROVIDER_API_KEY` нужен для основного AI provider. Для локальных smoke-тестов UI, SSE и истории можно использовать встроенные `echo` и `demo_image`.
### 4. Запуск frontend + backend
```bash
npm run dev
```
Команда запускает:
| Сервис | URL |
|---|---|
| Flask API | `http://127.0.0.1:5000` |
| Vite dev server | `http://127.0.0.1:5173` |
Vite проксирует API-запросы на backend.
Если нужно запустить части отдельно:
```bash
npm run dev:backend
npm run dev:frontend
```
### 5. Дополнительные процессы
Celery worker:
```bash
celery -A celery_worker.celery worker --loglevel=info --concurrency=2
```
## Docker
В репозитории есть отдельные Compose-конфигурации для разработки и production-проверки.
| Режим | Команда | Назначение |
|---|---|---|
| Dev | `docker compose -f docker-compose.dev.yml up --build` | Hot reload frontend, backend and worker |
| Dev shortcut | `npm run docker:dev` | Запуск dev Compose stack |
| Production | `npm run docker:prod` | HTTPS Nginx + Flask app + worker + PostgreSQL + Redis |
Dev URLs:
- Frontend: `http://127.0.0.1:5173`
- Backend: `http://127.0.0.1:5000`
Подробности по Docker: [docs/docker.md](docs/docker.md).
## Архитектура
```mermaid
graph TD
UI[React + Vite SPA] -->|HTTP / SSE| API[Flask API]
API --> SERVICES
API --> AUTH[Auth + Session Layer]
API --> FILES[Secure Upload Pipeline]
SERVICES --> AI[AI Provider / Echo / Demo Image]
SERVICES --> DB[(SQLite / PostgreSQL)]
API --> REDIS[(Redis)]
REDIS --> CELERY[Celery Worker]
NGINX[Nginx] --> API
```
Ключевые точки входа:
| Путь | Ответственность |
|---|---|
| `app_factory.py` | Flask app assembly, middleware, security, sessions and routes |
| `routes/features/` | Feature-oriented API modules |
| `services/` | Chat history, files, model access, voice and shared business logic |
| `ai_engine/` | AI provider adapters and local smoke-test providers |
| `src/` | React SPA |
| `openapi/openapi.json` | API contract used to generate `src/generated/openapi.ts` |
### Инструменты чата
Встроенный Python/React-рантайм выполняет инструменты только в рамках текущего ответа.
Код независим от внешних агентных платформ; shell-доступа к серверу, субагентов и фонового цикла нет.
| Возможность | Реализация ReMind |
|---|---|
| Типизированные инструменты и проверки | `ai_engine/tool_schemas.json`, `services/tool_validation.py`, существующие правила доступа |
| Связанные вызовы и результаты | `services/tool_execution.py`: каждый вызов получает результат, включая ошибки и лимиты; успешные повторы возвращают прежний результат без повторной публикации |
| Файлы и версии | Чтение с пагинацией, поиск по маске и содержимому, сравнение, создание и точечные правки с проверкой версии; оригиналы сохраняются |
| Точечные правки | `canvas_read`, `canvas_edit`: версия документа, точное единственное совпадение, сохранение ID Canvas |
| Веб-исследование | До трёх запросов одновременно, фильтры доменов и свежести, чтение страниц по частям, поиск по тексту и переходы по реальным ссылкам |
| Табличные данные | CSV и плоские JSON-массивы: схема, пропуски, фильтры, сортировка, группировка, агрегаты и CSV-экспорт |
| GitHub | Чтение нескольких разрешённых файлов и поиск текста в явно выбранных путях подключённого репозитория |
| План и уточнения | Карточка шагов и вопросы с выбором либо свободным ответом; ответ пользователя отправляется обычным сообщением |
| Журнал выполнения | Состояния инструментов, время, ошибки и прогресс в существующем мобильном блоке; старые сохранённые блоки поддерживаются |
Google SDK сохраняет исходные части ответа и thought signatures внутри одного запроса;
ID функции возвращается в соответствующем результате. В интерфейс попадают сводки,
которые отдаёт Gemini, и реальные события выполнения. Скрытые рассуждения не восстанавливаются
и не имитируются. Журнал сохраняется и при прерывании SSE. Следующее сообщение использует
обычную историю ReMind; подписанный контекст провайдера между отдельными запросами не хранится.
Лимиты: 16 раундов инструментов, до 4 вызовов за раунд и 32 операции за ответ. Пакетные запросы учитывают вложенные операции; после 180 секунд новые инструменты не запускаются. После исчерпания
бюджета модель получает возможность завершить ответ без инструментов. Финальный текст
проверяется перед выдачей; сводки и статусы передаются по мере поступления. Долгий синхронный
инструмент завершается по собственному таймауту; закрытие браузера не отменяет уже начатую
операцию внутри её обработчика.
Проверки безопасности охватывают схему аргументов, доступ к возможностям, выход за границы
файлов запроса, неоднозначные и устаревшие правки, повторы вызовов, лимиты и DNS rebinding.
HTTP-соединение идёт к проверенному публичному IP с TLS-проверкой исходного hostname;
прокси из окружения, cookies и автоматические перенаправления не используются. Порты — 80/443.
Приватные адреса, учётные данные в URL и неожиданные сжатые ответы отклоняются.
Правка Canvas защищает снимок текущего запроса, но не объединяет параллельные изменения браузера.
Python сохраняет существующий изолированный runner; GitHub — существующие границы доступа.
## API-контракт
Полезные endpoints:
| Endpoint | Назначение |
|---|---|
| `POST /chat` | Streaming chat response |
| `GET /sessions` | Список сессий |
| `GET /sessions//history` | История выбранной сессии |
| `POST /sessions//share` | Создание public read-only share link |
| `POST /translate` | Translate text |
| `POST /synthesize` | Text-to-speech synthesis |
| `GET /api/privacy/export` | Экспорт пользовательских данных |
| `POST /api/privacy/delete` | Удаление пользовательских данных |
| `GET /health` | Health check |
| `GET /metrics` | Runtime metrics |
| `GET /openapi.json` | OpenAPI schema |
Проверить generated TypeScript client:
```bash
npm run openapi:check
```
## Качество
### Backend
```bash
pip install -r requirements/dev.txt -c requirements/constraints.txt
ruff check .
black --check .
mypy app_factory.py routes utils services
```
### Frontend
```bash
npm run typecheck
npm run openapi:check
npm run lint
npm run build
```
CI покрывает secret scanning, backend checks, frontend checks и security pipeline через `pip-audit`, `npm audit`, `bandit` и `semgrep`.
## Участие в разработке
Вклад приветствуется, если он помогает держать проект надежным, безопасным и поддерживаемым.
Перед открытием PR:
1. Прочитайте [CONTRIBUTING.md](CONTRIBUTING.md).
2. Не добавляйте secrets и персональные данные в commits.
3. Добавьте или обновите тесты для пользовательского поведения.
4. Запустите релевантные проверки качества из README.
5. Используйте pull request template и приложите подтверждение проверки.
Документы проекта:
- [Security Policy](SECURITY.md)
- [Support Guide](SUPPORT.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Governance](GOVERNANCE.md)
- [Pull Request Template](.github/pull_request_template.md)
- [Issue Templates](.github/ISSUE_TEMPLATE/)
- [CODEOWNERS](.github/CODEOWNERS)
## Лицензия
ReMind распространяется под лицензией **GNU AGPL-3.0-only**. Подробности в [LICENSE](LICENSE).
Коммерческое использование разрешено только при соблюдении условий AGPL-3.0-only. В частности, если вы модифицируете ReMind и предоставляете к нему доступ по сети, пользователи такого сервиса должны получить доступ к Corresponding Source вашей версии на условиях AGPL.
Если вы хотите использовать ReMind или его части в proprietary-продукте, closed-source сервисе, hosted commercial platform, или без AGPL source-disclosure obligations, нужна отдельная коммерческая лицензия от ReNothingg (меня).
Название **ReMind**, логотип ReMind, визуальная идентичность, домены, официальные аккаунты и иное официальное оформление проекта не лицензируются по AGPL-3.0-only.
Вы не можете использовать название ReMind, логотип, брендинг или официальную идентичность для продвижения измененных версий, форков, коммерческих сервисов или производных продуктов без явного письменного разрешение ReNothingg.
Дополнительные уведомления: [NOTICE.md](NOTICE.md).
Contact: [renothingg.github.io](https://renothingg.github.io/?contact)
### Работа с файлами и данными
Доступны 33 функции инструментов, включая загрузку инструкций. Файлы и артефакты берутся из текущего запроса и доступной серверной истории этого чата. История и пути, присланные клиентом, не открывают доступ к чужим вложениям. Создание и экспорт файлов разрешены только авторизованным пользователям в сохраняемых чатах. За ответ можно создать до 8 файлов, каждый до 512 КБ, суммарно до 2 МБ. Исходники скачиваются как вложения; HTML-предпросмотр не выполняет сценарии, не отправляет формы и ограничивает внешние ресурсы политикой CSP. Python по-прежнему выполняется в отдельном runner с прежними ограничениями процесса и сети.
CSV/JSON обрабатываются без `eval`, SQL или исполнения содержимого. Ограничения: 20 000 строк, 128 входных колонок, до 32 выбранных колонок в одном запросе. CSV-экспорт включает все отфильтрованные строки выбранных колонок; опасные формулы экранируются с явным признаком в результате. Временные чаты позволяют анализ, но не сохраняемый экспорт.
Поиск сначала получает фрагменты результатов, а затем модель открывает нужные источники. Фрагмент поиска явно отличается от текста прочитанной страницы. `source_id` стабилен внутри ответа. Полные сохранённые тексты ограничены 100 000 символов на страницу и доступны по частям; кэш действует только внутри запроса. Открываются точные URL из сообщений пользователя, источников поиска или прочитанных ссылок. Изменённая строка запроса URL не наследует разрешение исходного адреса.
`ask_user` завершает текущий ответ и выводит карточку уточнения. Ответ из карточки — следующее сообщение пользователя, а не автоматическое подтверждение действий. План отражает текущий ответ; фоновых заданий он не создаёт. Сохраняемые карточки, скачиваемые файлы и статусы используют существующие историю, SSE и мобильный интерфейс ReMind.
