work/agent

Files

2026-03-12 16:55:23 +03:00

12 KiB

Raw Permalink Blame History

v1.plan.md

1. Цель ближайшего этапа

На ближайшем этапе цель — не достраивать полного агента и не интегрировать решение в UI, а довести до зрелого состояния изолированный code-first test pipeline:

user query -> IntentRouterV2 -> retrieval plan -> layered retrieval -> evidence gate -> LLM answer -> diagnostics

Именно этот контур должен стать будущим ядром агента, которое позже заменит legacy RouterService.

2. Что считается результатом этапа

Этап можно считать успешным, когда:

IntentRouterV2 стабильно определяет intent, sub_intent, keyword_hints, path_scope, layers, conversation_mode и retrieval constraints;
retrieval реально следует плану, заданному роутером;
LLM получает контекст, собранный из retrieval, а не из побочных обходных механизмов;
ответ не строится без достаточного evidence;
диагностика тестов позволяет понять:
- что выбрал router;
- что извлек retrieval;
- чего не хватило;
- почему ответ хороший или плохой.

3. Что сейчас не делать

На текущем этапе не стоит:

встраивать это сразу в UI;
подключать docs retrieval как обязательную часть MVP;
строить полный cross-domain runtime;
пытаться довести сразу весь orchestration runtime;
инвестировать много времени в C6, D5, D6;
лечить legacy RouterService, кроме минимально необходимого для совместимости.

4. Приоритетный план работ

4.1. Итерация 1 — зафиксировать канонический test-first контур

4.1.1. Принять `IntentRouterV2` как единственную точку истины для тестового MVP

Именно IntentRouterV2 должен определять:

domain
intent
sub_intent
keyword_hints
path_scope
layers
conversation_mode
retrieval constraints

4.1.2. Зафиксировать минимальный набор сценариев MVP-now

Для текущего этапа в качестве канонического набора сценариев следует оставить:

OPEN_FILE
EXPLAIN
FIND_TESTS
FIND_ENTRYPOINTS
GENERAL_QA как fallback

4.1.3. Зафиксировать контракт тестового пайплайна

Нужно явно определить структуру следующих объектов:

RouterResult
RetrievalRequest
RetrievalResult
EvidenceBundle
AnswerSynthesisInput
DiagnosticsReport

Это нужно, чтобы тесты настраивали устойчивый контракт, а не размытый процесс.

4.2. Итерация 2 — связать router и retrieval

4.2.1. Сделать retrieval adapter под контракт роутера

Output IntentRouterV2 должен напрямую превращаться в retrieval plan.

Примеры:

OPEN_FILE
- path-priority retrieval
- C0_SOURCE_CHUNKS
EXPLAIN
- symbol-first retrieval
- C1 + C0 + C2, optionally C3
FIND_TESTS
- target symbol / path
- lightweight C5-lite
FIND_ENTRYPOINTS
- C3_ENTRYPOINTS
GENERAL_QA
- ограниченный broad retrieval без агрессивных допущений

4.2.2. Убрать разрыв между индексатором и retrieval runtime

Нужна надежная связка:

index data -> retrieval gateway -> normalized retrieval output

Retrieval должен стать нормальной runtime-функцией, а не только наличием индексов и отдельных explain-механизмов.

4.2.3. Ввести единый формат retrieval output

Нужен единый формат, в который складываются найденные артефакты:

symbols
chunks
relations
entrypoints
tests
diagnostics per layer

Это станет основой для EvidenceBundle.

4.3. Итерация 3 — перенести evidence-first логику в общий test pipeline

4.3.1. Сделать общий evidence gate

Для каждого sub-intent нужно определить minimum evidence.

`OPEN_FILE`

найден path или очень сильный lexical hit;
есть хотя бы 1–2 relevant chunks.

`EXPLAIN`

найден целевой symbol или уверенный target fragment;
есть минимальное число code chunks;
есть хотя бы базовые relations или surrounding context.

`FIND_TESTS`

найден target symbol/file;
найден хотя бы один reliable candidate test.

`FIND_ENTRYPOINTS`

найден хотя бы один candidate entrypoint.

`GENERAL_QA`

найден хоть какой-то устойчивый контекст;
иначе ответ должен честно говорить о слабом evidence.

4.3.2. Запретить уверенный ответ без опоры

Если minimum evidence не выполнен, система должна:

либо честно деградировать;
либо выдать частичный ответ;
либо явно сообщить, каких данных не хватает.

4.4. Итерация 4 — унифицировать сборку контекста для LLM

4.4.1. Ввести единый `EvidenceBundle`

LLM должна получать структурированный пакет:

target intent / sub-intent
target symbol / path
relevant code chunks
retrieved relations
entrypoints if any
test evidence if any
retrieval diagnostics summary
evidence sufficiency flags

4.4.2. Разделить fast context и deep context

Fast context

Короткая выжимка:

target symbol
file
short relations summary
top evidence

Deep context

Полные chunks, расширенные relations и supporting fragments.

4.4.3. Стандартизировать prompt contract

Для каждого sub-intent нужен понятный режим ответа:

открыть;
объяснить;
найти тесты;
найти точки входа;
общий fallback.

LLM должна понимать:

какой тип ответа нужен;
насколько evidence полон;
можно ли делать выводы;
где надо явно отметить неопределенность.

4.5. Итерация 5 — довести диагностику до рабочего инструмента настройки

4.5.1. Разделить диагностику на 2 уровня

Уровень 1 — Human-readable summary

Коротко:

intent выбран правильно / нет;
target найден / нет;
retrieval успешен / нет;
evidence достаточен / нет;
ответ надежный / частичный / слабый.

Уровень 2 — Detailed diagnostics

Подробно:

router fields;
layer-by-layer retrieval;
empty / failed layers;
ranking decisions;
evidence gate results;
context assembly details.

4.5.2. Добавить явные failure reasons

Рекомендуемый минимальный набор:

router_low_confidence
target_symbol_not_found
path_scope_empty
layer_c1_empty
layer_c2_empty
test_mapping_not_found
insufficient_code_evidence

5. Как трактовать RAG-план на текущем этапе

5.1. Что оставить как целевой план

Целевую карту слоев оставляем без изменений:

C0–C6
D0–D6

Она остается правильной как target architecture.

5.2. Что считать MVP-now

Для текущего этапа обязательны:

C0_SOURCE_CHUNKS
C1_SYMBOL_CATALOG
C2_SYMBOL_RELATIONS
C3_ENTRYPOINTS

И в облегченном виде:

C5_TEST_MAPPINGS_LITE

Пока не делать блокирующими:

C4_EXECUTION_PATHS
C6_CODE_FACTS
весь docs runtime

5.3. Что считать следующим этапом

После стабилизации code-first MVP:

подключение docs retrieval;
использование D-layers в runtime;
docs-from-code generation;
cross-domain linking.

6. Как строить тестовый контур

6.1. Router tests

Проверяют только:

intent
sub_intent
layers
keyword_hints
path_scope
confidence / fallback behavior

6.2. Retrieval tests

Проверяют:

что retrieval реально использует router output;
какие слои сработали;
что извлечено;
нет ли шума от тестов;
не пропал ли основной код.

6.3. Evidence gate tests

Проверяют:

достаточен ли evidence;
правильно ли система деградирует;
не отвечает ли уверенно при слабой опоре.

6.4. Answer quality tests

Проверяют финальный ответ LLM:

есть ли опора в коде;
нет ли лишних догадок;
хватает ли связности;
соответствует ли ответ типу вопроса.

7. Что скорректировать в README / архитектурном плане

В README нужно явно разделить:

7.1. Target Architecture

Полная целевая система.

7.2. MVP-now

Изолированный test-first контур для CODE_QA, который:

не зависит от UI;
не зависит от full runtime orchestration;
нацелен на доводку IntentRouterV2 + retrieval + evidence + LLM answers.

8. Самые важные изменения в реализации прямо сейчас

Приоритет:

P1

Сделать IntentRouterV2 центром тестового MVP.

P2

Связать router output с реальным layered retrieval.

P3

Ввести единый EvidenceBundle.

P4

Сделать общий evidence gate для всего test pipeline.

P5

Привести диагностику к форме, удобной для настройки через тесты.

P6

Добавить C5-lite для FIND_TESTS.

9. Итоговая формулировка ближайшей цели

Довести до зрелости изолированный code-first test pipeline на базе IntentRouterV2, в котором роутер управляет retrieval, retrieval формирует evidence bundle, evidence gate контролирует достаточность опоры, а LLM отвечает строго на основе извлеченного контекста и прозрачной диагностики.

12 KiB Raw Permalink Blame History Unescape Escape