Helpomatica/README.md

# Helpomatica

Локальная веб-панель в духе Claude Projects: проекты, инструкции, файлы,
общие чаты, пользователи с ролями и ответы **Cursor Agent**. Интерфейс
на русском. Это не SPA-фреймворк и не облачный продукт — один процесс
FastAPI раздаёт статику и JSON API, данные лежат на диске сервера.

Ответы агента **не полностью офлайн**: нужен `CURSOR_API_KEY` с
[Cursor Dashboard → Integrations](https://cursor.com/dashboard/integrations).
Веб-панель, логин, файлы и предразбор логов работают и без ключа.

---

## Как запустить локально

Скопируйте `.env.example` в `.env` и вставьте ключ:

```env
CURSOR_API_KEY=crsr_your_key_here
CURSOR_MODEL=auto
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
```

Затем:

```powershell
.\run.ps1
```

Скрипт ставит зависимости в `.deps` (`pip install --target .deps`),
выставляет `PYTHONPATH` и поднимает uvicorn с `--reload` на
**`0.0.0.0:8010`**.

- На этой машине: http://127.0.0.1:8010
- С других ПК в LAN: `http://<IP-этой-машины>:8010`
- Вход по умолчанию: **`admin` / `admin`**

Если PowerShell блокирует локальные сценарии:

```powershell
powershell -ExecutionPolicy Bypass -File .\run.ps1
```

Если страница не открывается с другого ПК, разрешите входящий TCP 8010
в брандмауэре Windows:

```powershell
netsh advfirewall firewall add rule name="Helpomatica 8010" dir=in action=allow protocol=TCP localport=8010
```

Загрузки и агент выполняются **на машине сервера**, не в браузере клиента.
Файлы копируются во временный workspace из `data/uploads/`.

---

## Docker

Нужен файл `.env` (из `.env.example`). Данные не кладутся в образ:
том `./data:/app/data` хранит `db.json` и загрузки.

```bash
docker compose up -d --build
```

Откройте http://localhost:8010 и войдите. После пересборки контейнера
проекты, чаты и файлы остаются в `./data`.

Healthcheck бьёт в `GET /` (страница логина, без авторизации).
`GET /api/auth/me` для проверки не подходит — без cookie он отдаёт 401.

Подробности про Cursor Agent в Linux-контейнере — в разделе
[Cursor SDK и Docker](#cursor-sdk-и-docker).

---

## Что это такое

Панель для команды на одной машине / в LAN:

- **Проекты** — название, описание, инструкции, модель, иконка.
- **Инструкции** — общий контекст для всех чатов проекта.
- **Файлы** — материалы проекта (видны во всех чатах) или только этого чата.
- **Чаты** — общие на проект: любой вошедший пользователь читает и пишет
  в тех же разговорах.
- **Пользователи** — роли `admin` и `user`. Админ видит имена авторов
  сообщений; обычный пользователь видит «Вы» / «Коллега».
- **Ответы** — локальный Cursor Agent (`AsyncAgent`) со стримингом,
  размышлениями, историей инструментов и кнопкой «Стоп».

Дополнительно в UI: поиск по чатам, экспорт чата в Markdown, чипы
контекстных файлов, копирование кода, цитаты строк лога, диаграммы
Mermaid, формулы KaTeX, светлая/тёмная тема, индикатор статуса агента.

---

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

```
Браузер (static/index.html + app.js + style.css)
        │  cookie helpomatica_session
        ▼
FastAPI (main.py)  ──►  data/db.json
        │               data/uploads/
        │               %TEMP%/helpomatica-agent/hlp-*   (в Docker: /tmp/...)
        ▼
cursor-sdk: AsyncClient.launch_bridge → AsyncAgent.send → SSE
        ▼
Cursor API (нужен CURSOR_API_KEY)
```

- **Бэкенд:** FastAPI, статика смонтирована на `/static`, корень `GET /`
  отдаёт `static/index.html`. Фронтенд — ванильный JS, без React/Vue.
- **Хранение:** JSON-файл `data/db.json` (атомарная запись через `.tmp`)
  и файловая система `data/uploads/`. Папка `data/` в Git не входит.
- **Сессии:** список в `db.json`, cookie HttpOnly `helpomatica_session`
  (`SameSite=Lax`, без `Secure` — HTTP по IP в LAN), срок 30 дней,
  не больше 200 сессий. Пароль: PBKDF2-HMAC-SHA256, 200 000 итераций.
- **Доступ:** все авторизованные видят все проекты и общие чаты.
  Отдельных ACL на проект нет. Файлы с `scope=chat` попадают в агент
  только этого чата; `scope=project` — во все чаты проекта.
- **Параллельность:** глобального single-flight нет. У каждого `chat_id`
  своя очередь: один активный запрос и максимум один в ожидании
  (второй лишний → HTTP 409). Разные чаты запускают отдельные local bridge.
- **Слушает** `0.0.0.0:8010`.

`SESSION_SECRET` в `.env` — заготовка, **main.py его не читает**.

---

## Стек

Версии из текущего `pip install` в `.deps` (в `requirements.txt`
пакеты **без пинов**):

| Слой | Что |
|------|-----|
| Язык | Python **3.12** (локально 3.12.10). `cursor-sdk` требует **≥ 3.10** |
| API | FastAPI **0.141.1**, Starlette, Pydantic v2 |
| Сервер | uvicorn[standard] **0.52.1** |
| Агент | cursor-sdk **1.0.27** (`AsyncAgent`, `AsyncClient.launch_bridge`, `LocalAgentOptions`) + httpx |
| Конфиг | python-dotenv **1.2.2** |
| Загрузки | python-multipart **0.0.32** |
| Предразбор логов | `log_preanalysis.py` (stdlib) |
| Фронтенд | `static/app.js`, `static/style.css` — без сборки |
| CDN | Mermaid 11, KaTeX 0.16.22, шрифты Google (Manrope, Playfair Display) |
| Данные | JSON + файлы на диске |

Локальный запуск (`run.ps1`) кладёт пакеты в `.deps` и добавляет каталог
в `sys.path`. Docker ставит те же пакеты в venv через `pip install -r requirements.txt`.

---

## Форма `data/db.json`

Корень — объект со списками. При пустом файле / первом старте создаётся
админ из `ADMIN_USERNAME` / `ADMIN_PASSWORD`.

```json
{
  "users": [
    {
      "id": "hex",
      "username": "admin",
      "display_name": "Admin",
      "password_hash": "salt$pbkdf2hex",
      "role": "admin",
      "created_at": "ISO-8601"
    }
  ],
  "sessions": [{ "id": "token", "user_id": "…", "created_at": "…" }],
  "projects": [{
    "id": "…", "name": "…", "description": "…", "instructions": "…",
    "icon": "✦", "model": "auto", "created_by": "…",
    "created_at": "…", "updated_at": "…"
  }],
  "chats": [{
    "id": "…", "project_id": "…", "title": "…", "sort_order": 0,
    "created_by": "…", "updated_by": "…",
    "created_at": "…", "updated_at": "…"
  }],
  "messages": [{
    "id": "…", "chat_id": "…", "role": "user|assistant", "content": "…",
    "attachments": [{ "id": "…", "name": "…" }],
    "user_id": "… или null", "author_name": "Admin|Помощник|…",
    "thinking": "…", "thinking_duration_ms": 17519,
    "activity": [{ "id": "a1", "type": "thinking|shell|…", "title": "…",
                   "detail": "…", "status": "running|completed" }],
    "created_at": "…"
  }],
  "files": [{
    "id": "…", "project_id": "…", "chat_id": "null или id чата",
    "scope": "project|chat", "name": "line_u_codes.log.1",
    "label": "", "stored_name": "<uuid>_оригинал",
    "content_type": "…", "size": 123, "created_at": "…"
  }],
  "analysis_cache": [{
    "key": "sha256", "file_sig": "sha256", "project_id": "…",
    "job_id": "", "question": "нормализованный текст",
    "answer": "…", "preanalysis": "markdown", "summary": "…",
    "created_at": "…"
  }]
}
```

Байты файлов лежат в `data/uploads/<stored_name>`, в UI показывается
оригинальное `name`.

---

## Как проходит запрос к агенту

1. Пользователь пишет сообщение. Фронт сохраняет его
   `POST /api/chats/{id}/messages` (роль `user`, вложения, автор).
2. Сразу же `POST /api/chats/{id}/respond` — SSE-поток
   (`text/event-stream`).
3. Сервер занимает слот чата (или ставит в очередь на один).
   Событие `status: queued` / `starting`.
4. Собирается workspace: `prepare_agent_workspace` создаёт
   `%TEMP%/helpomatica-agent/hlp-<project8>-*` (в Linux/Docker —
   `/tmp/helpomatica-agent/hlp-…`). Туда hardlink/копия загрузок
   (и в `./`, и в `./files/`), плюс подсказки `README.md`,
   `PROJECT_FILES.md`, `AGENTS.md`, `.cursorignore`.
5. Если вопрос похож на разбор логов (`log_preanalysis.looks_like_log_job`)
   и в скоупе есть `*.log*`:
   - ищется `analysis_cache`;
   - иначе поток-скан логов с SSE `progress` («Читаю лог… N%»);
   - результат пишется в `./PREANALYSIS.md`.
6. Промпт: инструкции проекта + выдержки файлов + последние 30 сообщений
   + правило «cwd уже workspace, читай PREANALYSIS.md первым».
7. В **отдельном потоке** (на Windows — `WindowsProactorEventLoopPolicy`)
   вызывается `AsyncClient.launch_bridge(workspace=cwd)` и
   `AsyncAgent.create` / `agent.send`. События моста читаются в этом
   потоке; основной event loop забирает их через `asyncio.to_thread(queue.get)`.
8. В браузер уходят SSE:
   - `thinking` — дельты `thinking-delta`;
   - `activity` — инструменты, shell, статус, шаги «Логи»;
   - `delta` — токены ответа (`text-delta`);
   - `thinking_done`, `done` / `cancelled` / `error`.
9. Готовый текст сохраняется как сообщение ассистента (`thinking`,
   `activity`, `thinking_duration_ms`). При успехе пишется кэш разбора
   (до 80 записей).

Кнопка «Стоп» — `POST /api/chats/{id}/cancel`.

---

## Workspace агента и файлы

- Каталог: `tempfile.gettempdir()/helpomatica-agent/hlp-…`.
- Копируются файлы **проекта** + файлы **этого чата** + вложения сообщений.
- Вложения, chat-scope и логи копируются всегда; остальные файлы проекта
  режутся лимитами 40 МБ / файл и 80 МБ суммарно.
- Если hardlink недоступен — `shutil.copy2`.
- Агент работает только с этим cwd; исходники панели и диск клиента
  ему не отдаются.

Цитаты в ответе вида `:15231:line_u_codes.log.1` или
`::log:line_u_codes.log.1:15231::` фронт превращает в ссылку на
`GET /api/files/{id}/excerpt?start=&end=` (фрагмент ±25 строк).

---

## Авторизация и API (кратко)

Публично: `GET /`, `/static/*`, `POST /api/auth/login`.
Остальные `/api/*` требуют cookie.

| Метод | Путь | Назначение |
|-------|------|------------|
| POST | `/api/auth/login` | вход, Set-Cookie |
| POST | `/api/auth/logout` | выход |
| GET | `/api/auth/me` | текущий пользователь |
| GET/POST | `/api/users` | список / создание (только admin) |
| GET | `/api/agent/status` | ключ, SDK, busy, очереди чатов |
| CRUD | `/api/projects`, `/api/chats` | проекты, чаты, порядок |
| GET | `/api/chats/{id}/export` | Markdown |
| POST | `/api/chats/{id}/messages` | сохранить сообщение |
| POST | `/api/chats/{id}/respond` | SSE-ответ агента |
| POST | `/api/chats/{id}/cancel` | остановить генерацию |
| GET | `/api/search?q=` | поиск по названиям и тексту (от 2 символов, до 30) |
| POST | `/api/projects/{id}/files` | загрузка (`scope` + `chat_id`) |
| POST | `/api/chats/{id}/files/bind` | привязать файлы к чату |
| GET | `/api/files/{id}` | скачать |
| GET | `/api/files/{id}/excerpt` | фрагмент лога по строкам |

Модель проекта выбирается в UI (`auto`, `composer-2.5`, `composer-2`,
`gpt-5.2`, `claude-4.6-sonnet`) и уходит в `AgentOptions.model`.
По умолчанию — `CURSOR_MODEL` из `.env`.

---

## Cursor SDK и Docker

На Windows wheel `cursor-sdk` кладёт в
`cursor_sdk/_vendor/bridge/bin/`:

- `cursor-sdk-bridge.cmd` → запускает **`node.exe`** (вендорный, ~89 МБ)
- `../dist/bin/cursor-sdk-bridge.js` — сам мост (Node, не отдельный .exe агента)

`resolve_bridge_path()` ищет: `CURSOR_SDK_BRIDGE_BIN`, затем bundled
`bin/cursor-sdk-bridge` (POSIX) / `cursor-sdk-bridge.cmd` (Windows),
затем PATH.

**Не копируйте `.deps` с Windows-хоста в Linux-образ** — там `node.exe`.
Dockerfile ставит пакет заново: Linux-wheel cursor-sdk (x64/arm64)
должен принести свой `node` + launcher `cursor-sdk-bridge`.

Если в контейнере мост не стартует (нет bundled node, ошибка glibc,
нет `cursor-sdk-bridge`):

- веб-UI, логин, файлы и **предразбор логов** всё равно работают;
- ответы Cursor Agent нужно снимать на Windows-хосте через `.\run.ps1`.

Образ не содержит `.env`. Ключ передаётся `env_file: .env`.

---

## Безопасность

- Сразу смените пароль админа (`admin`/`admin` только для первого старта).
- Не коммитьте `.env` (уже в `.gitignore`). Ключ Cursor — секрет.
- Панель слушает весь LAN: ограничьте доступ брандмауэром.
- Cookie без `Secure`: нормально для HTTP в LAN, не для публичного HTTPS
  без доработки.
- Это не multi-tenant isolation: любой `user` видит все проекты и чаты.
- Генерации картинок в панели нет; агенту это явно запрещено в промпте.

---

## Файлы репозитория

| Путь | Роль |
|------|------|
| `main.py` | FastAPI-приложение |
| `log_preanalysis.py` | потоковый скан логов → `PREANALYSIS.md` |
| `static/` | HTML/CSS/JS |
| `run.ps1` | локальный запуск на Windows |
| `requirements.txt` | зависимости |
| `.env.example` | шаблон переменных (без секретов) |
| `Dockerfile`, `docker-compose.yml`, `.dockerignore` | контейнер |
| `test_preanalysis.py` | короткий тест предразбора логов |
| `data/` | БД и загрузки на диске сервера — **не в Git** (только `data/.gitkeep`) |

---

## Выгрузка в Gitea

В репозиторий кладите только исходники продукта: `main.py`, `log_preanalysis.py`, `static/`, `requirements.txt`, `run.ps1`, Docker-файлы, `.env.example`, `.gitignore`, `README.md`.

**Не коммитьте и не копируйте в Gitea:**

- `.env` — там `CURSOR_API_KEY` и пароль админа
- `data/` — чаты, загрузки, `db.json` (том Docker `./data` тоже только локальный)
- `.deps/` — локальный `pip install --target` (ставится заново из `requirements.txt`)

После клона:

```powershell
copy .env.example .env
# вставьте CURSOR_API_KEY и смените ADMIN_PASSWORD
docker compose up -d --build
# или локально на Windows:
.\run.ps1
```