HHostingByteSoftware
Ctrl K
ComunidadGuías…

README.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
<div align="center">
  <img src="public/icons/branding/logo-192.png" alt="ReMind logo" width="104" />

  <h1>ReMind</h1>

  <p>
    <strong>ReMind — для всех. Даже для тех, кто ещё не понял зачем.</strong>
  </p>

  <p>
    <a href="https://github.com/ReNothingg/ReMind/actions/workflows/ci.yml"><img src="https://github.com/ReNothingg/ReMind/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPLv3-0f766e.svg" alt="License: AGPLv3" /></a>
    <a href="https://github.com/ReNothingg/ReMind/stargazers"><img src="https://img.shields.io/github/stars/ReNothingg/ReMind?style=flat&color=111827" alt="GitHub stars" /></a>
    <a href="https://github.com/ReNothingg/ReMind/issues"><img src="https://img.shields.io/github/issues/ReNothingg/ReMind?color=2563eb" alt="Open issues" /></a>
  </p>

  <p>
    <img src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white" alt="Python 3.11" />
    <img src="https://img.shields.io/badge/React-19-20232A?logo=react&logoColor=61DAFB" alt="React 19" />
    <img src="https://img.shields.io/badge/Vite-7-646CFF?logo=vite&logoColor=white" alt="Vite 7" />
    <img src="https://img.shields.io/badge/Flask-API-111827?logo=flask&logoColor=white" alt="Flask API" />
    <img src="https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white" alt="Docker Compose" />
  </p>

  <p>
    <a href="#overview">Обзор</a>
    · <a href="#features">Возможности</a>
    · <a href="#quick-start">Быстрый старт</a>
    · <a href="#docker">Docker</a>
    · <a href="#architecture">Архитектура</a>
    · <a href="#quality">Качество</a>
    · <a href="#license">Лицензия</a>
  </p>

  <img src="public/images/banners/main-banner.png" alt="ReMind interface preview" width="100%" />
</div>

<a id="stars"></a>


## Обзор

**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 |

<a id="features"></a>

## Возможности

- Streaming AI chat через `POST /chat` с server-sent events.
- История диалогов, список сессий, удаление и восстановление контекста.
- Public read-only share links через `/sessions/<id>/share` и `/c/<public_id>`.
- 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.

<a id="tech-stack"></a>

## Технологический стек

| Слой | Стек |
|---|---|
| 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 |

<a id="quick-start"></a>

## Быстрый старт

### Требования

- 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
```

<a id="docker"></a>

## 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).

<a id="architecture"></a>

## Архитектура

```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 — существующие границы доступа.

<a id="api-contract"></a>

## API-контракт

Полезные endpoints:

| Endpoint | Назначение |
|---|---|
| `POST /chat` | Streaming chat response |
| `GET /sessions` | Список сессий |
| `GET /sessions/<id>/history` | История выбранной сессии |
| `POST /sessions/<id>/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
```

<a id="quality"></a>

## Качество

### 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`.

<a id="repository-map"></a>

<a id="contributing"></a>

## Участие в разработке

Вклад приветствуется, если он помогает держать проект надежным, безопасным и поддерживаемым.

Перед открытием 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)

<a id="license"></a>

## Лицензия

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.