agent/_process/03. RAG.md

RAG

Состояние as is

RAG сейчас используется как общее ядро индексации и retrieval по коду и документации. Основной storage - rag_session и многослойный индекс в БД.

Основные части

• RagService - фасад индексации и retrieval
• DocsIndexingPipeline - индексация документации
• CodeIndexingPipeline - индексация кода
• RagRepository - persistence и retrieval
• IntentRouterV2 - планирование retrieval: слои, фильтры, ограничения
• RuntimeRetrievalAdapter - выполнение retrieval в runtime

Индексация

Индексация идет по двум направлениям:

• DOCS
• CODE

На вход подается snapshot или changes. Для каждого файла выбирается подходящий pipeline. На выходе формируются документы по слоям и сохраняются в RAG-хранилище.

Структура БД

Все слои сохраняются в общую таблицу rag_chunks.

Общие поля по слоям

Поле БД	Назначение
rag_session_id	идентификатор сессии индексации
path	путь исходного файла
content	основной текст записи для retrieval
layer	идентификатор слоя
title	короткий заголовок записи
lang	язык исходного содержимого, в основном для code-слоев
repo_id	идентификатор репозитория или проекта
commit_sha	версия кода или документов на момент индексации
span_start, span_end	диапазон строк в исходном файле, если он есть
embedding	векторное представление записи
metadata_json	структурированные атрибуты конкретного слоя

Поля со смыслом слоя

Смысл конкретного слоя хранится в metadata_json. Именно эти атрибуты определяют, какой объект был извлечен и как его интерпретировать в retrieval. Домены и поддомены должны храниться в metadata_json явно.

Слои DOCS

D0_DOC_CHUNKS

Задача: Хранит текстовые фрагменты документации для retrieval по содержимому разделов.

Формирование: Документ сначала разбирается на frontmatter и body, затем body режется на секции через markdown chunker. Для каждой секции создается отдельная запись слоя. Нарезка идет по разделам документа. Только в fallback-сценарии, когда markdown-структура не найдена, используется нарезка по фиксированным текстовым чанкам.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
document_id	идентификатор документа-источника	frontmatter.id, иначе путь файла
type	тип документа из frontmatter	frontmatter.type
module	модуль документа	frontmatter.module
domain	домен документа	frontmatter.domain
subdomain	поддомен документа	frontmatter.subdomain
tags	теги документа	frontmatter.tags
section_path	полный путь секции в иерархии заголовков	результат MarkdownDocChunker
section_title	заголовок текущей секции	результат MarkdownDocChunker
order	порядок секции внутри документа	результат MarkdownDocChunker
doc_kind	классификация документа, например readme, spec, runbook	DocsClassifier.classify(path)
source_path	исходный путь документа	путь файла
artifact_type	тип артефакта, здесь DOCS	константа builder

Связанные классы: DocsIndexingPipeline, DocsContentParser, MarkdownDocChunker, DocsDocumentBuilder

D1_DOCUMENT_CATALOG

Задача: Хранит карточку документа как точку входа в документ и его краткое описание.

Формирование: Источник данных - frontmatter, fallback title, summary и doc kind, вычисленный классификатором документации. Данные извлекаются структурированно по атрибутам. В content попадает summary документа, а не склейка всех частей документа в сплошной текст.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
document_id	идентификатор документа	frontmatter.id, иначе путь файла
type	тип документа из frontmatter	frontmatter.type
name	системное имя документа	frontmatter.name
title	человекочитаемый заголовок документа	frontmatter.title, иначе fallback title
module	модуль документа	frontmatter.module
domain	домен документа	frontmatter.domain
subdomain	поддомен документа	frontmatter.subdomain
layer	логический слой, указанный в frontmatter документа	frontmatter.layer
status	статус документа	frontmatter.status
updated_at	дата или отметка последнего обновления	frontmatter.updated_at
tags	теги документа	frontmatter.tags
entities	сущности, связанные с документом	frontmatter.entities
parent	родительский документ	frontmatter.parent
children	дочерние документы	frontmatter.children
links	ссылки на связанные материалы	frontmatter.links
source_path	исходный путь документа	путь файла
summary_text	краткое содержание документа	секция # Summary
doc_kind	классификация документа, например readme, spec, runbook	DocsClassifier.classify(path)

Связанные классы: DocsIndexingPipeline, DocsFrontmatterParser, DocsClassifier, DocsContentParser, DocsDocumentBuilder

D2_FACT_INDEX

Задача: Хранит атомарные факты в форме subject-predicate-object для точного retrieval по утверждениям.

Формирование: Факты извлекаются из frontmatter и секций документа, после чего каждая найденная тройка превращается в отдельную запись.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
fact_id	идентификатор факта	вычисляется builder из содержимого факта и пути
subject_id	субъект факта	DocsFactExtractor
predicate	предикат или тип связи	DocsFactExtractor
object	значение или объект факта	DocsFactExtractor
object_ref	ссылка на объект, если она выделена отдельно	DocsFactExtractor
anchor	место в документе, откуда взят факт	DocsFactExtractor
tags	теги факта	DocsFactExtractor
source_path	исходный путь документа	путь файла

Связанные классы: DocsIndexingPipeline, DocsFactExtractor, DocsDocumentBuilder

D3_ENTITY_CATALOG

Задача: Хранит сущности, найденные в документации, чтобы искать документы и связи вокруг конкретной сущности.

Формирование: Сущности извлекаются из frontmatter документа, после чего каждая сущность сохраняется отдельной записью.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
entity_name	имя сущности	DocsEntityExtractor
document_id	идентификатор документа, где найдена сущность	frontmatter.id, иначе путь файла
document_type	тип документа-источника	frontmatter.type
module	модуль документа	frontmatter.module
domain	домен документа	frontmatter.domain
subdomain	поддомен документа	frontmatter.subdomain
tags	теги документа или сущности	frontmatter.tags
source_path	исходный путь документа	путь файла

Связанные классы: DocsIndexingPipeline, DocsEntityExtractor, DocsDocumentBuilder

D4_WORKFLOW_INDEX

Задача: Хранит workflow и сценарии из документации для ответов про flow, шаги и жизненный цикл процесса.

Формирование: Workflow извлекаются из detail sections документа и сохраняются как отдельные сценарии. Извлечение идет из структуры Details -> ## Сценарий.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
workflow_id	идентификатор сценария	вычисляется builder из названия, anchor и документа
document_id	идентификатор документа-источника	frontmatter.id, иначе путь файла
workflow_name	название сценария	блок Details -> ## Сценарий -> **Название**
preconditions	предусловия сценария	блок Details -> ## Сценарий -> **Предусловия**
trigger	триггер или событие запуска	блок Details -> ## Сценарий -> **Триггер**
main_flow	основной сценарий	блок Details -> ## Сценарий -> **Основной сценарий**
alternative_flow	альтернативные ветки	блок Details -> ## Сценарий -> **Альтернативный сценарий**
error_handling	обработка ошибок	блок Details -> ## Сценарий -> **Обработка ошибок**
postconditions	постусловия	блок Details -> ## Сценарий -> **Постусловие**
source_path	исходный путь документа	путь файла

Связанные классы: DocsIndexingPipeline, DocsWorkflowExtractor, DocsDocumentBuilder

D5_RELATION_GRAPH

Задача: Хранит связи между документами и сущностями документации для navigation и related docs retrieval.

Формирование: Связи извлекаются из frontmatter и сохраняются как отдельные relation edges.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
relation_id	идентификатор связи	вычисляется builder из source, target, relation type и anchor
source_id	источник связи	frontmatter.id или source документа в extractor
relation_type	тип связи	DocsRelationExtractor
target_id	целевой объект связи	DocsRelationExtractor
anchor	место в документе, где обнаружена связь	DocsRelationExtractor
source_path	исходный путь документа	путь файла

Связанные классы: DocsIndexingPipeline, DocsRelationExtractor, DocsDocumentBuilder

D6_INTEGRATION_INDEX

Задача: Хранит прикладные интеграции компонента, API, UI, сущности или внешней системы. Используется для ответов на вопросы вида "какие интеграции есть у компонента".

Формирование: Интеграции извлекаются из блока ## Integrations документа. Одна интеграция должна превращаться в отдельную запись слоя. Описание интеграции может быть развернутым, а структурированные атрибуты должны выделяться в словарь.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
integration_id	идентификатор интеграции	вычисляется builder из source, target и anchor
source_id	идентификатор объекта, для которого описана интеграция	frontmatter.id документа-источника
source_type	тип исходного объекта	frontmatter.doc_type
target	целевой объект интеграции	блок ## Integrations
target_type	тип целевого объекта, например api, ui, entity, service, external_system	блок ## Integrations
direction	направление интеграции	блок ## Integrations
interaction	тип взаимодействия	блок ## Integrations
via	технический канал интеграции	блок ## Integrations
purpose	назначение интеграции	блок ## Integrations
details	дополнительные атрибуты интеграции в виде словаря	блок ## Integrations
domain	домен документа	frontmatter.domain
subdomain	поддомен документа	frontmatter.subdomain
source_path	исходный путь документа	путь файла
anchor	место в документе, где описана интеграция	блок ## Integrations

Связанные классы: DocsIndexingPipeline, DocsIntegrationExtractor, DocsDocumentBuilder

Слои CODE

C0_SOURCE_CHUNKS

Задача: Хранит фрагменты исходного кода как базовый слой для цитирования, explain и точечной догрузки кода.

Формирование: Исходный файл режется на кодовые чанки, и для каждого чанка создается отдельная запись.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
chunk_index	порядковый номер чанка в файле	индекс чанка при нарезке
chunk_type	тип чанка, например функция, класс или текстовый блок	CodeTextChunker
module_or_unit	модуль, к которому относится chunk	вычисляется из пути файла
is_test	признак тестового файла	is_test_path(path)

Связанные классы: CodeIndexingPipeline, CodeTextChunker, CodeTextDocumentBuilder

C1_SYMBOL_CATALOG

Задача: Хранит символы кода: классы, функции и методы. Используется для поиска по именам и структуре кода.

Формирование: Символы извлекаются SymbolExtractor, и каждый символ сохраняется как отдельная запись.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
symbol_id	идентификатор символа	SymbolExtractor
qname	полное квалифицированное имя	SymbolExtractor
kind	тип символа: класс, функция, метод	SymbolExtractor
signature	сигнатура символа	SymbolExtractor
parent_symbol_id	родительский символ	SymbolExtractor
package_or_module	модуль или пакет символа	вычисляется из пути файла
is_test	признак тестового файла	is_test_path(path)

Связанные классы: CodeIndexingPipeline, PythonAstParser, SymbolExtractor, SymbolDocumentBuilder

C2_DEPENDENCY_GRAPH

Задача: Хранит связи между символами кода: вызовы, импорты, наследование. Используется для анализа зависимостей и flow.

Формирование: Связи строятся EdgeExtractor по AST и списку символов, после чего каждая связь сохраняется отдельной записью.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
edge_id	идентификатор связи	EdgeExtractor
edge_type	тип связи: вызов, импорт, наследование	EdgeExtractor
src_symbol_id	исходный символ	EdgeExtractor
src_qname	полное имя исходного символа	EdgeExtractor
dst_symbol_id	целевой символ, если он разрешен	EdgeExtractor
dst_ref	текстовая ссылка на целевой символ	EdgeExtractor
resolution	статус разрешения связи	EdgeExtractor
is_test	признак тестового файла	is_test_path(path)

Связанные классы: CodeIndexingPipeline, EdgeExtractor, EdgeDocumentBuilder

C3_ENTRYPOINTS

Задача: Хранит точки входа приложения: HTTP routes, CLI commands и другие entrypoints.

Формирование: Детекторы ищут HTTP и CLI точки входа по символам файла, после чего каждый найденный entrypoint сохраняется отдельной записью.

Фиксация в БД:

Атрибут в metadata_json	Описание	Источник
entry_id	идентификатор точки входа	detector entrypoint model
entry_type	тип точки входа	detector entrypoint model
framework	framework, в котором найдена точка входа	detector entrypoint model
route_or_command	route или команда	detector entrypoint model
handler_symbol_id	идентификатор обработчика	detector entrypoint model
handler_symbol	имя обработчика	detector entrypoint model
declaring_symbol	символ, в котором объявлен entrypoint	detector entrypoint model
entrypoint_kind	вид точки входа	detector entrypoint model
http_method	HTTP-метод	detector entrypoint model
route_path	путь маршрута	detector entrypoint model
decorator_text	текст декоратора или объявления	detector entrypoint model
summary_text	краткое описание точки входа	detector entrypoint model
is_test	признак тестового файла	is_test_path(path)
lang_payload	дополнительные данные детектора	detector metadata
artifact_type	тип артефакта, здесь CODE	константа builder

Связанные классы: CodeIndexingPipeline, EntrypointDetectorRegistry, FastApiEntrypointDetector, FlaskEntrypointDetector, TyperClickEntrypointDetector, EntrypointDocumentBuilder

C4_SEMANTIC_ROLES

Задача: Слой объявлен в enum и retrieval-планах как слой семантических ролей кода.

Формирование: Слой формируется на основе символов, связей, dataflow slices и execution traces. В текущем runtime этот слой не используется как активный маршрут, так как домен CODE отключен.

Фиксация в БД: Смысловые атрибуты слоя сохраняются в rag_chunks.metadata_json. Точное краткое описание состава этих атрибутов в текущем документе пока не зафиксировано.

Связанные классы: CodeIndexingPipeline, SemanticRoleBuilder, SemanticRoleDocumentBuilder