Агент для работы с проектной документацией

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. Архитектура

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. Типичный флоу

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. Инструкции к запуску

Локальный запуск

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 15000

Запуск через Docker Compose

1. Создать .env на основе примера:

cp .env.example .env

2. Заполнить как минимум GIGACHAT_TOKEN.

3. Запустить сервисы:

docker compose up -d --build

4. Проверить доступность backend:

curl http://localhost:15000/health

Ожидаемый ответ:

{"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-таблицы все равно должны наполняться.