Фикс состояния
This commit is contained in:
376
v1_plan.md
Normal file
376
v1_plan.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 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 отвечает строго на основе извлеченного контекста и прозрачной диагностики.
|
||||
|
||||
Reference in New Issue
Block a user