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

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

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

cp .env.example .env

Заполнить как минимум GIGACHAT_TOKEN.
Запустить сервисы:

docker compose up -d --build

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

curl http://localhost:15000/health

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

{"status":"ok"}

Основные адреса

Backend API: http://localhost:15000
PostgreSQL + pgvector: localhost:5432
Webhook репозитория: POST /internal/rag-repo/webhook

Базовый сценарий проверки

Создать rag_session через POST /api/rag/sessions.
Дождаться завершения index-job через GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}.
Создать диалог через POST /api/chat/dialogs.
Отправить сообщение через POST /api/chat/messages.
Настроить webhook репозитория на POST /internal/rag-repo/webhook.
Сделать commit с story_id в сообщении, например FEAT-1 ....
Проверить заполнение таблиц:
- story_records, story_links, story_artifacts
- rag_blob_cache, rag_chunk_cache, rag_session_chunk_map
Во второй сессии индексации проверить поля job-статуса:
- indexed_files
- cache_hit_files
- cache_miss_files

Полезные замечания

Текущая chat-модель: GigaChat.
Основной retrieval всегда идет из rag_session.
rag_repo используется как фоновый источник кэша и контекста коммитов.
Если в webhook не найден story_id, commit-контекст Story не будет привязан, но cache-таблицы все равно должны наполняться.

8.2 KiB Raw Blame History Unescape Escape