Фикс состояния
This commit is contained in:
161
README_old.md
Normal file
161
README_old.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Агент для работы с проектной документацией
|
||||
|
||||
## 1. Общее описание
|
||||
Приложение представляет собой backend агентного режима для работы с документацией и кодом проекта.
|
||||
|
||||
Система решает следующие задачи:
|
||||
- индексирует локальную копию проекта в `rag_session` и использует ее как основной рабочий контекст пользователя;
|
||||
- принимает webhook коммитов репозитория в `rag_repo` и фиксирует контекст изменений по `story_id`;
|
||||
- ускоряет построение `rag_session` за счет переиспользования кэша чанков и эмбеддингов из `rag_repo`;
|
||||
- обрабатывает пользовательские запросы через `chat`, `agent`, оркестратор и специализированные графы;
|
||||
- сохраняет quality-метрики, Story-контекст и артефакты сессии в PostgreSQL.
|
||||
|
||||
Ключевая идея архитектуры:
|
||||
- `rag_session` отвечает за пользовательскую рабочую сессию и всегда остается основным источником retrieval;
|
||||
- `rag_repo` не участвует напрямую в пользовательском ответе, а служит фоновым источником кэша и контекста коммитов;
|
||||
- `story_id` связывает изменения аналитика, документацию и последующую работу тестировщика.
|
||||
|
||||
## 2. Архитектура
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User["Пользователь"]
|
||||
Git["Git репозиторий\n(Gitea / Bitbucket)"]
|
||||
Chat["Модуль chat"]
|
||||
Agent["Модуль agent"]
|
||||
RagSession["Модуль rag_session"]
|
||||
RagRepo["Модуль rag_repo"]
|
||||
Shared["Модуль shared"]
|
||||
DB["PostgreSQL + pgvector"]
|
||||
Giga["GigaChat API"]
|
||||
|
||||
User --> Chat
|
||||
Chat --> Agent
|
||||
Agent --> RagSession
|
||||
Agent --> Shared
|
||||
RagSession --> Shared
|
||||
RagRepo --> Shared
|
||||
Chat --> DB
|
||||
Agent --> DB
|
||||
RagSession --> DB
|
||||
RagRepo --> DB
|
||||
RagSession --> Giga
|
||||
Agent --> Giga
|
||||
Git --> RagRepo
|
||||
RagRepo -.кэш и контекст коммитов.-> RagSession
|
||||
```
|
||||
|
||||
Кратко по ролям модулей:
|
||||
- `chat` — внешний API чата, фоновые задачи, SSE события, диалоги.
|
||||
- `agent` — роутер интентов, оркестратор, графы, tools, генерация ответа и changeset.
|
||||
- `rag_session` — создание и сопровождение пользовательского RAG индекса по локальным файлам.
|
||||
- `rag_repo` — прием webhook коммитов, определение `story_id`, фиксация контекста коммита и заполнение repo-cache.
|
||||
- `shared` — инфраструктурный слой: БД, retry, event bus, GigaChat client, настройки.
|
||||
|
||||
## 3. Типичный флоу
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User as Пользователь
|
||||
participant Git as Git репозиторий
|
||||
participant RagRepo as Модуль rag_repo
|
||||
participant DB as PostgreSQL
|
||||
participant RagSession as Модуль rag_session
|
||||
participant Chat as Модуль chat
|
||||
participant Agent as Модуль agent
|
||||
|
||||
Note over User,RagSession: Первая рабочая сессия: кэша репозитория еще нет
|
||||
User->>RagSession: Создание rag_session и загрузка файлов проекта
|
||||
RagSession->>DB: Проверка cache hit/miss
|
||||
DB-->>RagSession: Кэш пуст
|
||||
RagSession->>RagSession: Чанкинг и расчет embeddings без repo-cache
|
||||
RagSession->>DB: Сохранение rag_chunks и rag_index_jobs
|
||||
User->>Chat: Отправка запроса в чат
|
||||
Chat->>Agent: Передача задачи
|
||||
Agent->>RagSession: Retrieval контекста
|
||||
RagSession->>DB: Чтение rag_chunks
|
||||
DB-->>RagSession: Релевантные чанки
|
||||
RagSession-->>Agent: Контекст
|
||||
Agent-->>Chat: Ответ / changeset
|
||||
|
||||
Note over User,Git: Пользователь вручную делает commit и push
|
||||
Git->>RagRepo: Webhook push
|
||||
RagRepo->>RagRepo: Определение provider, commit_sha, changed_files, story_id
|
||||
RagRepo->>DB: Запись story_records/story_links/story_artifacts
|
||||
RagRepo->>DB: Запись rag_blob_cache/rag_chunk_cache/rag_session_chunk_map
|
||||
|
||||
Note over User,RagSession: Вторая рабочая сессия: repo-cache уже существует
|
||||
User->>RagSession: Создание новой rag_session и загрузка файлов проекта
|
||||
RagSession->>DB: Проверка cache hit/miss
|
||||
DB-->>RagSession: Найдены cache hit по части файлов
|
||||
RagSession->>RagSession: Переиспользование чанков из rag_repo cache
|
||||
RagSession->>RagSession: Пересчет embeddings только для cache miss файлов
|
||||
RagSession->>DB: Сохранение rag_chunks, rag_session_chunk_map, rag_index_jobs
|
||||
User->>Chat: Новый запрос
|
||||
Chat->>Agent: Передача задачи
|
||||
Agent->>RagSession: Retrieval по новой сессии
|
||||
RagSession-->>Agent: Контекст из session-RAG
|
||||
Agent-->>Chat: Ответ / changeset
|
||||
```
|
||||
|
||||
Что важно в этом сценарии:
|
||||
- первый запуск индексации может быть полностью без кэша;
|
||||
- после коммита `rag_repo` фиксирует контекст изменений и наполняет cache-таблицы;
|
||||
- во второй и последующих сессиях `rag_session` использует `cache_hit_files`, чтобы уменьшить объем новых embeddings.
|
||||
|
||||
## 4. Инструкции к запуску
|
||||
|
||||
### Локальный запуск
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --reload --port 15000
|
||||
```
|
||||
|
||||
### Запуск через Docker Compose
|
||||
1. Создать `.env` на основе примера:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Заполнить как минимум `GIGACHAT_TOKEN`.
|
||||
|
||||
3. Запустить сервисы:
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
4. Проверить доступность backend:
|
||||
```bash
|
||||
curl http://localhost:15000/health
|
||||
```
|
||||
|
||||
Ожидаемый ответ:
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
### Основные адреса
|
||||
- Backend API: `http://localhost:15000`
|
||||
- PostgreSQL + pgvector: `localhost:5432`
|
||||
- Webhook репозитория: `POST /internal/rag-repo/webhook`
|
||||
|
||||
### Базовый сценарий проверки
|
||||
1. Создать `rag_session` через `POST /api/rag/sessions`.
|
||||
2. Дождаться завершения index-job через `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`.
|
||||
3. Создать диалог через `POST /api/chat/dialogs`.
|
||||
4. Отправить сообщение через `POST /api/chat/messages`.
|
||||
5. Настроить webhook репозитория на `POST /internal/rag-repo/webhook`.
|
||||
6. Сделать commit с `story_id` в сообщении, например `FEAT-1 ...`.
|
||||
7. Проверить заполнение таблиц:
|
||||
- `story_records`, `story_links`, `story_artifacts`
|
||||
- `rag_blob_cache`, `rag_chunk_cache`, `rag_session_chunk_map`
|
||||
8. Во второй сессии индексации проверить поля job-статуса:
|
||||
- `indexed_files`
|
||||
- `cache_hit_files`
|
||||
- `cache_miss_files`
|
||||
|
||||
### Полезные замечания
|
||||
- Текущая chat-модель: `GigaChat`.
|
||||
- Основной retrieval всегда идет из `rag_session`.
|
||||
- `rag_repo` используется как фоновый источник кэша и контекста коммитов.
|
||||
- Если в webhook не найден `story_id`, commit-контекст Story не будет привязан, но cache-таблицы все равно должны наполняться.
|
||||
Reference in New Issue
Block a user