995 lines
40 KiB
Markdown
995 lines
40 KiB
Markdown
# Архитектура текущего агентного контура NDC_1C
|
||
|
||
Дата среза: 2026-05-23
|
||
Статус документа: рабочая карта текущей реализации, собрана по коду, конфигам и orchestration-файлам репозитория.
|
||
|
||
## 1. Коротко
|
||
|
||
В проекте сейчас есть не один агент, а связка из двух больших контуров:
|
||
|
||
1. Продуктовый 1С-ассистент.
|
||
Это backend/runtime, который принимает вопрос пользователя, нормализует смысл, выбирает маршрут, ходит в 1С/MCP, строит ответ и пишет debug/technical payload.
|
||
|
||
2. Агентный контур разработки и контроля качества.
|
||
Это repo-native система прогонов, аудита, verdict/handoff и сохранения проверенных сценариев в autoruns. Его цель - снять с человека ручной разбор прогонов: запускать реальные сценарии, читать ответы как бизнес-пользователь, находить P0/P1/P2, формировать ремонтный handoff и не давать сохранять плохие сценарии как "успешные".
|
||
|
||
Текущая важная мысль: **по умолчанию контур уже не является полностью авто-ремонтником**. Он автономно запускает, анализирует и формирует handoff, но код обычно чинит Lead Codex в основном контексте. Полностью автономный coder-режим есть, но он выключен по умолчанию и включается только явно через `repair_mode=auto-coder`.
|
||
|
||
## 2. Сколько моделей участвует
|
||
|
||
Ниже - фактическая карта ролей и моделей.
|
||
|
||
| Слой | Роль | Модель/провайдер по текущим файлам | Температура | Лимит | Где задано |
|
||
|---|---|---|---:|---:|---|
|
||
| Product runtime LLM | LLM-нормализация / pre-decompose пользовательского вопроса | `local`, `unsloth/qwen3-30b-a3b-instruct-2507` | `0.8` | `900` | `llm_normalizer/data/shared_llm_connection.json` |
|
||
| Domain case loop live runner | Запуск live case/scenario/pack против backend | по умолчанию берет shared config: `local`, `unsloth/qwen3-30b-a3b-instruct-2507` | `0.8` | `900` | `scripts/domain_case_loop.py` + `shared_llm_connection.json` |
|
||
| Stage wrapper | Обертка stage-loop, если запускать без override | `local`, `qwen2.5-14b-instruct-1m` | `0.0` | `2048` | `scripts/stage_agent_loop.py` |
|
||
| Codex analyst | Строгий read-only бизнес/технический аналитик | `gpt-5.4` | не через temperature, через reasoning effort | n/a | `.codex/agents/domain_analyst.toml`, `scripts/domain_case_loop.py` |
|
||
| Codex coder | Implementation agent для минимального патча | `gpt-5.4` | reasoning effort | n/a | `.codex/agents/domain_coder.toml`, `scripts/domain_case_loop.py` |
|
||
| Codex orchestrator | Координатор доменного цикла | `gpt-5.4` | reasoning effort | n/a | `.codex/agents/orchestrator.toml` |
|
||
| Lead Codex | Основной интерактивный разработчик в текущем чате | модель текущей Codex-сессии, вне repo-конфига | n/a | n/a | не хранится в репозитории |
|
||
|
||
Итого в текущей практической схеме участвуют минимум **4 модельные роли**:
|
||
|
||
- локальная LLM для runtime-нормализации ассистента;
|
||
- Codex analyst;
|
||
- Codex coder;
|
||
- Lead Codex.
|
||
|
||
Если считать orchestrator как отдельную роль, получается **5 агентных ролей**, но orchestrator сейчас в основном описан как агентная маска/роль для внешнего Codex orchestration, а не как обязательный шаг каждого ручного цикла.
|
||
|
||
## 3. Важное расхождение конфигов
|
||
|
||
Есть два разных default-профиля локальной LLM:
|
||
|
||
1. `scripts/domain_case_loop.py` читает `llm_normalizer/data/shared_llm_connection.json`.
|
||
Текущий shared config:
|
||
|
||
```json
|
||
{
|
||
"llmProvider": "local",
|
||
"model": "unsloth/qwen3-30b-a3b-instruct-2507",
|
||
"baseUrl": "http://127.0.0.1:1234/v1",
|
||
"temperature": 0.8,
|
||
"maxOutputTokens": 900
|
||
}
|
||
```
|
||
|
||
2. `scripts/stage_agent_loop.py` имеет свои CLI defaults:
|
||
|
||
```text
|
||
--llm-provider local
|
||
--llm-model qwen2.5-14b-instruct-1m
|
||
--llm-base-url http://127.0.0.1:1234/v1
|
||
--temperature 0.0
|
||
--max-output-tokens 2048
|
||
```
|
||
|
||
Практический вывод: если запускать `domain_case_loop.py` напрямую, он сейчас ориентируется на Qwen3 shared config. Если запускать через `stage_agent_loop.py` без override, stage wrapper передаст Qwen2.5 defaults. Это нужно помнить при сравнении прогонов.
|
||
|
||
## 4. Основные порты и runtime-адреса
|
||
|
||
| Компонент | Адрес/порт | Где задано |
|
||
|---|---|---|
|
||
| Backend 1С-ассистента | `http://127.0.0.1:8787` | `scripts/domain_case_loop.py`, `llm_normalizer/backend/src/config.ts` |
|
||
| Local OpenAI-compatible LLM endpoint | `http://127.0.0.1:1234/v1` | `shared_llm_connection.json`, CLI defaults |
|
||
| MCP proxy к 1С | `http://127.0.0.1:6003` | `llm_normalizer/backend/src/config.ts`, `ASSISTANT_MCP_PROXY_URL` |
|
||
| MCP channel | `default` | `llm_normalizer/backend/src/config.ts`, `ASSISTANT_MCP_CHANNEL` |
|
||
| MCP timeout | `6000 ms` | `ASSISTANT_MCP_TIMEOUT_MS` |
|
||
| MCP live limit | `128` | `ASSISTANT_MCP_LIVE_LIMIT` |
|
||
|
||
## 5. Product runtime: как отвечает 1С-ассистент
|
||
|
||
Продуктовый runtime живет в `llm_normalizer/backend`.
|
||
|
||
Грубый путь одного вопроса:
|
||
|
||
1. Пользователь отправляет сообщение в backend.
|
||
2. Backend собирает prompt bundle / normalizer prompt.
|
||
3. LLM-нормализация или deterministic resolver определяют intent, filters, date scope, domain family.
|
||
4. Orchestration решает lane:
|
||
- address lane;
|
||
- living chat;
|
||
- MCP discovery;
|
||
- exact capability route;
|
||
- bounded/limited answer.
|
||
5. Address/MCP слой получает данные из 1С через proxy.
|
||
6. Compose/answer policy строит human-facing answer.
|
||
7. Параллельно пишется technical debug payload.
|
||
8. Сессия сохраняется в `llm_normalizer/data/assistant_sessions`.
|
||
|
||
Ключевые runtime-файлы:
|
||
|
||
- `llm_normalizer/backend/src/services/assistantService.ts` - верхний слой ассистента.
|
||
- `llm_normalizer/backend/src/services/addressQueryService.ts` - address query / exact route execution.
|
||
- `llm_normalizer/backend/src/services/addressIntentResolver.ts` - распознавание address intent.
|
||
- `llm_normalizer/backend/src/services/addressFilterExtractor.ts` - извлечение фильтров.
|
||
- `llm_normalizer/backend/src/services/addressCapabilityPolicy.ts` - capability policy / feature gates.
|
||
- `llm_normalizer/backend/src/services/addressNavigationState.ts` - состояние диалога, selected object, carryover.
|
||
- `llm_normalizer/backend/src/services/assistantMcpDiscovery*` - discovery/bridge/handoff вокруг MCP.
|
||
- `llm_normalizer/backend/src/services/address_runtime/*` - staged runtime для address lane.
|
||
- `llm_normalizer/backend/src/config.ts` - флаги, порты, MCP settings.
|
||
|
||
## 6. Prompt runtime продукта
|
||
|
||
Главный backend prompt builder:
|
||
|
||
- `llm_normalizer/backend/src/services/promptBuilder.ts`
|
||
|
||
Он знает версии:
|
||
|
||
- `normalizer_v1`
|
||
- `normalizer_v1_1`
|
||
- `normalizer_v1_1_1`
|
||
- `normalizer_v1_1_2`
|
||
- `normalizer_v1_1_2_1`
|
||
- `normalizer_v2`
|
||
- `normalizer_v2_0_1`
|
||
- `normalizer_v2_0_2`
|
||
|
||
Backend default:
|
||
|
||
```text
|
||
DEFAULT_PROMPT_VERSION = normalizer_v2_0_2
|
||
```
|
||
|
||
Текущий системный prompt-файл:
|
||
|
||
- `llm_normalizer/backend/src/prompts/system/default.txt`
|
||
|
||
Суть системной роли:
|
||
|
||
```text
|
||
Ты semantic-normalizer для бухгалтерского ассистента NDC.
|
||
Твоя роль: только нормализация запроса пользователя в строгий JSON-контракт.
|
||
Не давай бухгалтерский ответ по сути вопроса.
|
||
Возвращай только JSON.
|
||
```
|
||
|
||
Фактическое дерево `llm_normalizer/backend/src/prompts` сейчас содержит только `default.txt` в подпапках:
|
||
|
||
- `system/default.txt`
|
||
- `developer/default.txt`
|
||
- `domain/default.txt`
|
||
- `fewshot/default.txt`
|
||
|
||
При этом `promptBuilder.ts` декларирует version-specific файлы вроде `developer/normalizer_v2_0_2.txt`, `domain/normalizer_domain_v1_1.txt`, `fewshot/normalizer_v2_0_2.txt`. В текущем дереве этих файлов нет. Это отдельная зона аудита: либо runtime использует сохраненные presets из `llm_normalizer/data/presets`, либо часть built-in preset loader может быть недособрана для прямой загрузки `normalizer_v2_0_2`.
|
||
|
||
Сохраненные preset-файлы:
|
||
|
||
- `llm_normalizer/data/presets/preset-splJ9OGZ.json`
|
||
- `llm_normalizer/data/presets/preset-rk8wKqPt.json`
|
||
- `llm_normalizer/data/presets/preset-it0w_T10.json`
|
||
|
||
Все найденные preset-файлы относятся к `normalizer_v1`, а не к `normalizer_v2_0_2`.
|
||
|
||
## 7. Agentic semantic development loop: зачем он нужен
|
||
|
||
Агентный контур нужен не для того, чтобы "модель сама по себе стала умнее", а чтобы построить повторяемую систему:
|
||
|
||
1. Собрать реалистичный пакет вопросов.
|
||
2. Прогнать его live против настоящего backend.
|
||
3. Прочитать user-facing ответы как человек.
|
||
4. Сравнить с business intent.
|
||
5. Поставить P0/P1/P2.
|
||
6. Объяснить root cause layer.
|
||
7. Сформировать ремонтный handoff.
|
||
8. После фикса прогнать тот же сценарий.
|
||
9. Только после принятого live replay сохранить пакет в autoruns.
|
||
|
||
Главный принцип из `AGENTS.md`: **семантический анализ важнее зеленых unit-тестов и route ids**. Route matched не считается успехом, если пользовательский ответ бизнесово неправильный.
|
||
|
||
## 8. Главные файлы агентного контура
|
||
|
||
| Файл | Роль |
|
||
|---|---|
|
||
| `scripts/domain_case_loop.py` | Основной движок case/scenario/pack/pack-loop. Запускает backend, пишет artifacts, строит business-first review, repair targets, analyst/coder prompts. |
|
||
| `scripts/domain_truth_harness.py` | Live strict replay по JSON spec. Дает `truth_review`, `business_review`, `semantic_audit`, final status. |
|
||
| `scripts/review_assistant_stage1_run.py` | Анализ уже сохраненных GUI/autorun прогонов. Строит business review, findings, repair targets. |
|
||
| `scripts/stage_agent_loop.py` | Stage-level wrapper над `domain_case_loop.py`; умеет запускать stage loop, summarise, status, save autorun. |
|
||
| `scripts/agent_semantic_pack_builder.py` | Сборщик целевых AGENT-паков из recipes/source catalog. |
|
||
| `scripts/save_agent_semantic_run.py` | Сохраняет только уже validated replay в UI autoruns. Проверяет accepted artifacts. |
|
||
| `.codex/skills/domain-case-loop/SKILL.md` | Правила работы доменного loop как навыка Codex. |
|
||
| `.codex/agents/domain_analyst.toml` | Ролевая маска строгого аналитика. |
|
||
| `.codex/agents/domain_coder.toml` | Ролевая маска кодера. |
|
||
| `.codex/agents/orchestrator.toml` | Ролевая маска координатора. |
|
||
| `docs/orchestration/active_domain_contract.json` | Текущий mutable domain contract. |
|
||
| `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json` | Stage manifest для dogfood gate агентного loop. |
|
||
|
||
## 9. Роли агентного контура
|
||
|
||
### 9.1 Lead Codex
|
||
|
||
Это основной разработчик в текущем чате. Он:
|
||
|
||
- читает репозиторий;
|
||
- запускает harness;
|
||
- делает patch через `apply_patch`;
|
||
- запускает тесты;
|
||
- коммитит;
|
||
- обновляет Tasker;
|
||
- принимает handoff от agent loop.
|
||
|
||
Важно: Lead Codex не является repo-configured моделью. Его модель/лимиты задаются внешней средой Codex и в этом репозитории не фиксируются.
|
||
|
||
### 9.2 Orchestrator
|
||
|
||
Файл:
|
||
|
||
- `.codex/agents/orchestrator.toml`
|
||
|
||
Модель:
|
||
|
||
```text
|
||
gpt-5.4
|
||
model_reasoning_effort = high
|
||
sandbox_mode = workspace-write
|
||
```
|
||
|
||
Задача:
|
||
|
||
- принять case/scenario;
|
||
- создать artifact folder;
|
||
- захватить baseline;
|
||
- вызвать analyst;
|
||
- передать coder минимальную задачу;
|
||
- rerun;
|
||
- запросить before/after verdict;
|
||
- завершить статусом `accepted | partial | blocked | needs_exact_capability`.
|
||
|
||
Жесткие ограничения:
|
||
|
||
- не менять архитектуру;
|
||
- не принимать heuristic output как confirmed answer;
|
||
- не маскировать fallback;
|
||
- принимать scenario tree, а не плоский список вопросов;
|
||
- selected-object, pronoun follow-up, date carryover, field truth, answer layering являются обязательными acceptance target.
|
||
|
||
### 9.3 Domain analyst
|
||
|
||
Файл:
|
||
|
||
- `.codex/agents/domain_analyst.toml`
|
||
|
||
Модель:
|
||
|
||
```text
|
||
gpt-5.4
|
||
model_reasoning_effort = high
|
||
sandbox_mode = read-only
|
||
```
|
||
|
||
Задача:
|
||
|
||
- читать artifacts, а не гадать по краткому пересказу;
|
||
- судить бизнес-смысл ответа;
|
||
- выделять P0/P1/P2;
|
||
- отличать route gap, capability gap, business utility gap, field mapping gap, object memory gap, temporal honesty gap;
|
||
- давать quality score 0-100;
|
||
- запрещать acceptance ниже 80 или при unresolved P0.
|
||
|
||
Ожидаемая структура prose verdict:
|
||
|
||
1. Question meaning
|
||
2. Primary user path and scenario tree
|
||
3. Expected direct answer
|
||
4. What the system actually computed
|
||
5. Business mismatch
|
||
6. Route / capability mismatch
|
||
7. State continuity and selected-object memory
|
||
8. Field truth and evidence quality
|
||
9. P0 defects
|
||
10. P1 defects
|
||
11. P2 defects
|
||
12. Minimal patch directions
|
||
13. Acceptance matrix for rerun
|
||
14. Acceptance criteria for rerun
|
||
15. Quality score
|
||
16. Loop decision
|
||
|
||
### 9.4 Domain coder
|
||
|
||
Файл:
|
||
|
||
- `.codex/agents/domain_coder.toml`
|
||
|
||
Модель:
|
||
|
||
```text
|
||
gpt-5.4
|
||
model_reasoning_effort = high
|
||
sandbox_mode = workspace-write
|
||
```
|
||
|
||
Задача:
|
||
|
||
- читать verdict/handoff;
|
||
- делать минимальный domain-only patch;
|
||
- не менять широкую архитектуру;
|
||
- не подменять exact data эвристикой;
|
||
- сохранять successful baseline flows.
|
||
|
||
Разрешенные зоны:
|
||
|
||
- intents;
|
||
- domain-specific routing;
|
||
- recipes;
|
||
- capability mapping;
|
||
- exact/confirmed route handling;
|
||
- domain validators;
|
||
- evidence/source-ref modeling;
|
||
- role modeling;
|
||
- follow-up resolution;
|
||
- business-readable presentation.
|
||
|
||
Запрещено:
|
||
|
||
- broad architecture changes;
|
||
- fake data;
|
||
- silent heuristic masking;
|
||
- large unrelated refactors.
|
||
|
||
### 9.5 Deterministic reviewer
|
||
|
||
Это не LLM-модель, а код.
|
||
|
||
Главные места:
|
||
|
||
- `scripts/domain_case_loop.py::build_business_first_review`
|
||
- `scripts/domain_truth_harness.py::build_business_review_summary`
|
||
- `scripts/review_assistant_stage1_run.py::augment_gui_business_review`
|
||
|
||
Что он умеет проверять:
|
||
|
||
- direct answer first;
|
||
- technical garbage;
|
||
- top-level scaffolding;
|
||
- overly verbose direct answer;
|
||
- counterparty net-flow vs company profit misroute;
|
||
- bank role misclassification;
|
||
- domain leak for nomenclature margin questions;
|
||
- missing accounting contract;
|
||
- missing next action for limited margin answer.
|
||
|
||
Последние добавленные issue-коды:
|
||
|
||
- `domain_leak_accounting_route` - P0;
|
||
- `accounting_contract_missing` - P1;
|
||
- `business_next_step_missing` - P2.
|
||
|
||
## 10. Режимы запуска agent loop
|
||
|
||
### 10.1 Case mode
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/domain_case_loop.py run-case --domain <domain> --question "<question>"
|
||
```
|
||
|
||
Используется для одного конкретного вопроса.
|
||
|
||
Артефакты:
|
||
|
||
- `baseline_output.md`
|
||
- `baseline_debug.json`
|
||
- `baseline_turn.json`
|
||
- `baseline_session.json`
|
||
- `baseline_job.json`
|
||
|
||
### 10.2 Scenario mode
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/domain_case_loop.py run-scenario --manifest <manifest.json>
|
||
```
|
||
|
||
Используется для одной цепочки вопросов в одной assistant session.
|
||
|
||
Артефакты:
|
||
|
||
- `scenario_manifest.json`
|
||
- `scenario_state.json`
|
||
- `scenario_summary.md`
|
||
- `steps/<step_id>/turn.json`
|
||
- `steps/<step_id>/debug.json`
|
||
- `steps/<step_id>/output.md`
|
||
- `steps/<step_id>/step_state.json`
|
||
|
||
### 10.3 Pack mode
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/domain_case_loop.py run-pack --manifest <pack.json>
|
||
```
|
||
|
||
Используется для нескольких сценариев внутри одного доменного пакета.
|
||
|
||
Артефакты:
|
||
|
||
- `pack_state.json`
|
||
- `pack_summary.md`
|
||
- `repair_targets.json`
|
||
- `scenario_acceptance_matrix.md`
|
||
- `scenarios/<scenario_id>/...`
|
||
|
||
### 10.4 Autonomous pack-loop mode
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/domain_case_loop.py run-pack-loop --manifest <pack.json>
|
||
```
|
||
|
||
Что делает:
|
||
|
||
1. Запускает `run-pack`.
|
||
2. Собирает evidence bundle.
|
||
3. Строит deterministic repair targets.
|
||
4. Вызывает Codex analyst.
|
||
5. Пишет `business_audit.md`.
|
||
6. Если не accepted:
|
||
- при `lead-handoff` пишет `lead_coder_handoff.md` и останавливается;
|
||
- при `auto-coder` вызывает Codex coder.
|
||
7. После coder-патча должен быть rerun.
|
||
|
||
Текущий default repair mode:
|
||
|
||
```text
|
||
lead-handoff
|
||
```
|
||
|
||
Это принципиально: агент не должен сам бесконтрольно править runtime, пока не доказано, что auto-coder достаточно надежен.
|
||
|
||
### 10.5 Truth harness live replay
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/domain_truth_harness.py run-live --spec <spec.json> --output-dir artifacts/domain_runs/<run_id>
|
||
```
|
||
|
||
Артефакты:
|
||
|
||
- `final_status.md`
|
||
- `truth_review.md/json`
|
||
- `business_review.md/json`
|
||
- `semantic_audit.md/json`
|
||
- `pack_state.json`
|
||
- `steps/<step_id>/turn.json`
|
||
- `steps/<step_id>/output.md`
|
||
|
||
Это сейчас самый удобный механизм для целевых AGENT-прогонов.
|
||
|
||
### 10.6 Save validated AGENT run to autoruns
|
||
|
||
Команда:
|
||
|
||
```powershell
|
||
python scripts/save_agent_semantic_run.py --spec <spec.json> --validated-run-dir <accepted_artifact_dir>
|
||
```
|
||
|
||
Ограничение:
|
||
|
||
- нельзя сохранять pack в autoruns до live replay;
|
||
- save-script проверяет `truth_review.json`, `business_review.json`, accepted/pass status;
|
||
- unvalidated save возможен только через явный `--allow-unvalidated`, но по правилам проекта это invalid intermediate artifact для боевых паков.
|
||
|
||
## 11. Stage-level AGENT loop
|
||
|
||
Stage manifest:
|
||
|
||
- `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`
|
||
|
||
Ключевые параметры:
|
||
|
||
```json
|
||
{
|
||
"stage_id": "agentic_semantic_development_loop",
|
||
"module_name": "Agentic Semantic Development Loop",
|
||
"target_score": 88,
|
||
"max_iterations": 6,
|
||
"repair_mode": "lead-handoff",
|
||
"save_autorun_on_accept": true,
|
||
"manual_confirmation_required_after_accept": true
|
||
}
|
||
```
|
||
|
||
Acceptance invariants:
|
||
|
||
- status command exposes next action / repair state / validation state;
|
||
- run-pack-loop defaults to Lead Codex handoff;
|
||
- continue command never runs real coder pass without `--execute-repair`;
|
||
- `business_audit.md` and `lead_coder_handoff.md` are produced before code repair when semantic replay is not accepted;
|
||
- patched repair cannot close stage without rerun validation;
|
||
- business answers remain direct/context-aware/free of debug IDs;
|
||
- manual GUI confirmation remains required after accepted semantic replay.
|
||
|
||
Stage wrapper:
|
||
|
||
- `scripts/stage_agent_loop.py`
|
||
|
||
Основные команды:
|
||
|
||
```powershell
|
||
python scripts/stage_agent_loop.py plan --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
|
||
python scripts/stage_agent_loop.py run --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
|
||
python scripts/stage_agent_loop.py status --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
|
||
python scripts/stage_agent_loop.py summarize --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
|
||
```
|
||
|
||
## 12. Current active domain contract
|
||
|
||
Файл:
|
||
|
||
- `docs/orchestration/active_domain_contract.json`
|
||
|
||
Текущий domain:
|
||
|
||
```text
|
||
inventory_stock_supplier_provenance
|
||
```
|
||
|
||
Смысл:
|
||
|
||
- складские остатки на дату;
|
||
- выбранная номенклатура;
|
||
- поставщик;
|
||
- закупочные документы;
|
||
- возраст закупки;
|
||
- дальнейшая продажа;
|
||
- selected-object continuity;
|
||
- pronoun follow-up;
|
||
- temporal carryover.
|
||
|
||
Правило из контракта:
|
||
|
||
- стабильные слои: `AGENTS.md`, `.codex/skills/domain-case-loop`, `.codex/agents/*.toml`;
|
||
- mutable слой: `docs/orchestration/active_domain_contract.json`;
|
||
- при смене домена надо менять active contract, а не переписывать agent canon.
|
||
|
||
## 13. Как агент оценивает качество
|
||
|
||
### 13.1 Основной порядок анализа
|
||
|
||
Проектное правило:
|
||
|
||
1. Читать цепочку пользовательских вопросов как человеческий разговор.
|
||
2. Читать ответы ассистента как их видит пользователь.
|
||
3. Оценить semantic correctness, context awareness, directness, usefulness.
|
||
4. Только потом смотреть debug payload, route ids, capability ids, filters.
|
||
5. Только после этого смотреть unit tests / narrow regressions.
|
||
|
||
Это зашито в `AGENTS.md` и поддерживается `business_first_review`.
|
||
|
||
### 13.2 Виды итогового статуса
|
||
|
||
Используются статусы:
|
||
|
||
- `accepted` - можно считать сценарий принятым;
|
||
- `partial` - есть рабочая часть, но качество/coverage недостаточно;
|
||
- `blocked` - инфраструктурный или реальный hard blocker;
|
||
- `needs_exact_capability` - запрос валиден для проекта, но не хватает capability/route/контракта.
|
||
|
||
### 13.3 Severity
|
||
|
||
Практическая шкала:
|
||
|
||
- P0 - смысловая или архитектурная поломка, нельзя принимать;
|
||
- P1 - важная проблема качества/контракта, обычно блокирует "хорошую базу";
|
||
- P2 - полезная доработка, не всегда blocker;
|
||
- warning/info - поддерживающие сигналы.
|
||
|
||
Примеры P0:
|
||
|
||
- wrong intent;
|
||
- wrong capability;
|
||
- wrong recipe;
|
||
- wrong date/period;
|
||
- missing required filter;
|
||
- focus object missing;
|
||
- business direct answer missing;
|
||
- technical garbage in answer;
|
||
- counterparty net-flow misrouted to company profit;
|
||
- domain leak accounting route.
|
||
|
||
Примеры P1:
|
||
|
||
- answer layering noise;
|
||
- business answer too verbose;
|
||
- accounting contract missing.
|
||
|
||
Пример P2:
|
||
|
||
- limited margin answer without next action.
|
||
|
||
## 14. Что считается хорошим ответом
|
||
|
||
Общие правила:
|
||
|
||
- direct answer first;
|
||
- business meaning first, proof second, service notes last;
|
||
- no route/debug/internal ids in user-facing answer;
|
||
- no row counts before business answer;
|
||
- no `status`, `what was considered`, `exact contour`, `coverage`, `truth gate` above the answer;
|
||
- selected-object follow-up must be action-first, not trace-first;
|
||
- if exact fact unavailable, answer must say what is confirmed, what is inferred, what remains unknown;
|
||
- limited answer must still give useful next action when domain expects it.
|
||
|
||
Для маржинальности номенклатуры агент теперь ожидает:
|
||
|
||
- период;
|
||
- выручку;
|
||
- себестоимость;
|
||
- валовую прибыль;
|
||
- маржу;
|
||
- если данных не хватает - честный отказ плюс следующий шаг.
|
||
|
||
Запрещенная доменная протечка для маржинальности:
|
||
|
||
- ОС;
|
||
- амортизация;
|
||
- банковские списания;
|
||
- payment_document;
|
||
- unresolved settlement;
|
||
- зависшие оплаты;
|
||
- закрытие расчетов вместо реализации/себестоимости.
|
||
|
||
## 15. Artifact topology
|
||
|
||
Главные каталоги:
|
||
|
||
```text
|
||
artifacts/domain_runs/
|
||
llm_normalizer/data/assistant_sessions/
|
||
llm_normalizer/reports/
|
||
llm_normalizer/data/autorun_generators/
|
||
llm_normalizer/data/eval_cases/
|
||
docs/orchestration/
|
||
```
|
||
|
||
Что где лежит:
|
||
|
||
- live run artifacts: `artifacts/domain_runs/<run_id>/`;
|
||
- session JSON: `llm_normalizer/data/assistant_sessions/<session_id>.json`;
|
||
- saved autorun sessions: `llm_normalizer/data/autorun_generators/saved_sessions/`;
|
||
- generated eval cases: `llm_normalizer/data/eval_cases/`;
|
||
- autorun history: `llm_normalizer/data/autorun_generators/history.json`;
|
||
- specs/manifests: `docs/orchestration/*.json`;
|
||
- stage loop artifacts: `artifacts/domain_runs/stage_agent_loops/`.
|
||
|
||
## 16. Как pack попадает в UI autoruns
|
||
|
||
Правильный порядок:
|
||
|
||
1. Создать или обновить spec.
|
||
2. Выполнить live replay:
|
||
|
||
```powershell
|
||
python scripts/domain_truth_harness.py run-live --spec docs/orchestration/<spec>.json --output-dir artifacts/domain_runs/<run_id>
|
||
```
|
||
|
||
3. Проверить:
|
||
- `final_status.md`;
|
||
- `semantic_audit.md/json`;
|
||
- `truth_review.md/json`;
|
||
- step-level `output.md` / `turn.json`.
|
||
4. Если статус accepted и semantic gate pass, сохранить:
|
||
|
||
```powershell
|
||
python scripts/save_agent_semantic_run.py --spec docs/orchestration/<spec>.json --validated-run-dir artifacts/domain_runs/<run_id>
|
||
```
|
||
|
||
5. В UI pack появится как `AGENT | ...`.
|
||
|
||
Если pack сохранен раньше live replay, по правилам проекта это мусорный intermediate artifact, его надо удалить и пересоздать.
|
||
|
||
## 17. Текущие сохраненные AGENT-паки
|
||
|
||
Недавние важные specs:
|
||
|
||
- `docs/orchestration/agent_autonomy_business_quality_20260523.json`
|
||
- `docs/orchestration/agent_autonomy_selected_object_mix_20260523.json`
|
||
- `docs/orchestration/agent_inventory_margin_ranking_20260523.json`
|
||
- `docs/orchestration/agent_profit_direct_answer_20260523.json`
|
||
- `docs/orchestration/agent_cashflow_profit_directness_20260523.json`
|
||
- `docs/orchestration/agent_cashflow_no_tops_20260523.json`
|
||
- `docs/orchestration/inventory_margin_ranking_agent_loop_20260522.json`
|
||
|
||
Пример принятого pack:
|
||
|
||
- `agent_autonomy_selected_object_mix_20260523`
|
||
- live replay: 15/15;
|
||
- status: `accepted`;
|
||
- сохранен в autoruns как `AGENT | selected-object + multi-org context mix`.
|
||
|
||
## 18. Как анализируется GUI/autorun прогон
|
||
|
||
Файл:
|
||
|
||
- `scripts/review_assistant_stage1_run.py`
|
||
|
||
Назначение:
|
||
|
||
- взять сохраненные assistant sessions;
|
||
- собрать пары user/assistant;
|
||
- извлечь user-facing ответ;
|
||
- дополнить business review;
|
||
- найти issue codes;
|
||
- сгруппировать repair targets;
|
||
- записать markdown/json отчет.
|
||
|
||
Особые детекторы:
|
||
|
||
- technical leaks;
|
||
- bank role misclassification;
|
||
- counterparty value-flow -> company profit slip;
|
||
- margin domain leak;
|
||
- direct answer missing;
|
||
- top-line scaffolding;
|
||
- verbosity.
|
||
|
||
## 19. Где находятся ролевые маски и ограничения
|
||
|
||
### Agent masks
|
||
|
||
- `.codex/agents/orchestrator.toml`
|
||
- `.codex/agents/domain_analyst.toml`
|
||
- `.codex/agents/domain_coder.toml`
|
||
|
||
### Skill rules
|
||
|
||
- `.codex/skills/domain-case-loop/SKILL.md`
|
||
- `.codex/skills/domain-case-loop/references/business_first_analyst_rubric.md`
|
||
- `.codex/skills/domain-case-loop/references/scenario_tree_acceptance_canon.md`
|
||
- `.codex/skills/domain-case-loop/references/verdict_template.md`
|
||
- `.codex/skills/domain-case-loop/references/repo_runtime_map.md`
|
||
|
||
### Project rules
|
||
|
||
- `AGENTS.md`
|
||
|
||
Ключевые ограничения из `AGENTS.md`:
|
||
|
||
- UTF-8 without BOM;
|
||
- после code changes обновлять graphify;
|
||
- acceptance через semantic answer, не только tests;
|
||
- valid multi-org clarification не считать bug;
|
||
- если multi-company contour требует уточнения, replay должен продолжить с выбором компании;
|
||
- не сохранять AGENT pack в autoruns до accepted live replay;
|
||
- не принимать domain, если root работает, а selected-object/drilldown edges ломаются;
|
||
- no silent heuristic masking.
|
||
|
||
### Runtime feature flags
|
||
|
||
- `llm_normalizer/backend/src/config.ts`
|
||
|
||
Примеры включенных флагов:
|
||
|
||
- `FEATURE_ASSISTANT_ADDRESS_QUERY_V1 = true`
|
||
- `FEATURE_ASSISTANT_ADDRESS_QUERY_LLM_PREDECOMPOSE_V1 = true`
|
||
- `FEATURE_ASSISTANT_ADDRESS_QUERY_LIVE_V1 = true`
|
||
- `FEATURE_ASSISTANT_ADDRESS_NAVIGATION_STATE_V1 = true`
|
||
- `FEATURE_ASSISTANT_CAPABILITY_ROUTE_GUARD_V1 = true`
|
||
- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_AUDIT_V1 = true`
|
||
- `FEATURE_ASSISTANT_LIVING_CHAT_ROUTER_V1 = true`
|
||
|
||
Примеры выключенных/опасных:
|
||
|
||
- `FEATURE_ASSISTANT_MCP_RUNTIME_V1 = false`
|
||
- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_HARD_GUARD_V1 = false`
|
||
- `FEATURE_ASSISTANT_STAGE2_EVAL_V1 = false`
|
||
|
||
## 20. Что автоматизировано, а что нет
|
||
|
||
Автоматизировано:
|
||
|
||
- capture baseline/rerun;
|
||
- live scenario replay;
|
||
- semantic audit artifact generation;
|
||
- deterministic issue detection;
|
||
- repair target grouping;
|
||
- Codex analyst verdict;
|
||
- Lead Codex handoff;
|
||
- validated autorun save;
|
||
- stage status/summary.
|
||
|
||
Частично автоматизировано:
|
||
|
||
- code repair через Codex coder.
|
||
|
||
Почему частично:
|
||
|
||
- `auto-coder` существует, но выключен по умолчанию;
|
||
- default `repair_mode = lead-handoff`;
|
||
- агент пишет handoff, а Lead Codex применяет патч в основном контексте;
|
||
- это сделано осознанно, чтобы не получить слабый авто-патч с architecture drift.
|
||
|
||
Не автоматизировано полностью:
|
||
|
||
- финальное продуктово-бухгалтерское решение спорных бизнес-рамок;
|
||
- опасные architecture forks;
|
||
- выбор между разными учетными моделями, если данных/политики не хватает;
|
||
- гарантированная 100% оценка всех доменов без целевых packs.
|
||
|
||
## 21. Текущий уровень зрелости агента
|
||
|
||
Что уже хорошо:
|
||
|
||
- умеет запускать real backend replay;
|
||
- умеет сохранять step-level artifacts;
|
||
- умеет semantic gate;
|
||
- умеет selected-object continuity checks;
|
||
- умеет multi-org clarification continuation;
|
||
- умеет сохранять validated packs в UI autoruns;
|
||
- умеет ловить техмусор и несколько бизнесовых P0;
|
||
- умеет формировать repair handoff.
|
||
|
||
Что еще надо качать:
|
||
|
||
- сильный analyst verdict уровня ручного аудита на каждый новый домен;
|
||
- больше domain-specific semantic detectors;
|
||
- auto-coder пока не default;
|
||
- prompt/preset registry требует отдельной ревизии;
|
||
- stage wrapper defaults и shared LLM defaults надо унифицировать или явно документировать в CLI;
|
||
- больше целевых packs по бухгалтерским доменам: маржинальность, себестоимость, прибыль, НДС, долги, склад, взаиморасчеты.
|
||
|
||
## 22. Текущие риски
|
||
|
||
### 22.1 Разные defaults моделей
|
||
|
||
`domain_case_loop.py` и `stage_agent_loop.py` могут запускать разные local LLM defaults.
|
||
|
||
Риск:
|
||
|
||
- один и тот же pack может вести себя по-разному при прямом и stage-запуске.
|
||
|
||
Что сделать:
|
||
|
||
- унифицировать stage wrapper с shared LLM config или явно писать effective model в каждый artifact.
|
||
|
||
### 22.2 Prompt preset registry не полностью прозрачен
|
||
|
||
`promptBuilder.ts` декларирует version-specific files, но в prompt-директории сейчас видны только default files.
|
||
|
||
Риск:
|
||
|
||
- прямой built-in load для `normalizer_v2_0_2` может зависеть от отсутствующих файлов или от сохраненных presets неочевидным образом.
|
||
|
||
Что сделать:
|
||
|
||
- отдельный audit prompt registry;
|
||
- документировать active prompt source in runtime;
|
||
- добавить health check на prompt file presence.
|
||
|
||
### 22.3 Semantic gate еще не равен бухгалтеру
|
||
|
||
Deterministic review уже ловит часть P0/P1, но не все.
|
||
|
||
Риск:
|
||
|
||
- новый домен может пройти route-level checks, но быть бизнесово слабым.
|
||
|
||
Что сделать:
|
||
|
||
- добавлять domain-specific detectors по мере появления ручных аудитов;
|
||
- сохранять плохие и хорошие примеры как unit tests review layer.
|
||
|
||
### 22.4 Auto-coder выключен
|
||
|
||
Это скорее плюс по безопасности, но минус по автономности.
|
||
|
||
Риск:
|
||
|
||
- агент не закрывает цикл полностью сам.
|
||
|
||
Что сделать:
|
||
|
||
- сначала довести analyst/handoff до стабильно высокого качества;
|
||
- затем включать auto-coder только на низкорисковых scoped domains.
|
||
|
||
## 23. Быстрая карта "кто за что отвечает"
|
||
|
||
| Вопрос | Ответ |
|
||
|---|---|
|
||
| Кто отвечает пользователю в UI? | Product runtime в `llm_normalizer/backend`. |
|
||
| Кто нормализует вопрос? | Local LLM + deterministic resolvers. |
|
||
| Какая локальная модель сейчас в shared config? | `unsloth/qwen3-30b-a3b-instruct-2507`. |
|
||
| Кто запускает live replay? | `domain_truth_harness.py` или `domain_case_loop.py`. |
|
||
| Кто пишет semantic audit? | `domain_truth_harness.py` + `domain_case_loop.py::business_first_review`. |
|
||
| Кто анализирует GUI-прогоны? | `review_assistant_stage1_run.py`. |
|
||
| Кто делает строгий LLM-verdict? | `domain_analyst` на `gpt-5.4`. |
|
||
| Кто должен чинить код в auto режиме? | `domain_coder` на `gpt-5.4`, но auto-coder не default. |
|
||
| Кто чинит код сейчас обычно? | Lead Codex по handoff. |
|
||
| Где текущий активный домен? | `docs/orchestration/active_domain_contract.json`. |
|
||
| Где сохраненные AGENT autoruns? | `llm_normalizer/data/autorun_generators/saved_sessions/`. |
|
||
| Где история autorun генерации? | `llm_normalizer/data/autorun_generators/history.json`. |
|
||
| Где stage manifest агентного loop? | `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`. |
|
||
|
||
## 24. Минимальная команда для текущего целевого AGENT-прогона
|
||
|
||
Пример live replay:
|
||
|
||
```powershell
|
||
python scripts/domain_truth_harness.py run-live `
|
||
--spec docs/orchestration/agent_autonomy_selected_object_mix_20260523.json `
|
||
--output-dir artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual
|
||
```
|
||
|
||
Проверить:
|
||
|
||
```powershell
|
||
Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/final_status.md
|
||
Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/semantic_audit.md
|
||
Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/truth_review.md
|
||
```
|
||
|
||
Сохранить в autoruns только если accepted:
|
||
|
||
```powershell
|
||
python scripts/save_agent_semantic_run.py `
|
||
--spec docs/orchestration/agent_autonomy_selected_object_mix_20260523.json `
|
||
--validated-run-dir artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual
|
||
```
|
||
|
||
## 25. Как читать результаты агента
|
||
|
||
Правильный порядок:
|
||
|
||
1. `final_status.md`
|
||
2. `semantic_audit.md`
|
||
3. `truth_review.md`
|
||
4. `pack_state.json`
|
||
5. `steps/<step_id>/output.md`
|
||
6. `steps/<step_id>/turn.json`
|
||
|
||
Не надо начинать с route ids. Сначала читается human-facing answer.
|
||
|
||
## 26. Что значит "качать агента дальше"
|
||
|
||
В текущей архитектуре "качать агента" означает:
|
||
|
||
1. Улучшать business-first review.
|
||
2. Добавлять domain-specific semantic detectors.
|
||
3. Строить целевые AGENT packs по свежим больным темам.
|
||
4. Требовать live replay до autorun save.
|
||
5. Делать accepted gate не по route/pass, а по human answer quality.
|
||
6. Расширять analyst verdict/handoff так, чтобы Lead Codex получал почти готовый repair plan.
|
||
7. Постепенно приближать auto-coder к безопасному default, но не раньше, чем analyst gate станет надежным.
|
||
|
||
Ближайший правильный домен для прокачки:
|
||
|
||
- маржинальность / прибыльность номенклатуры;
|
||
- выручка без НДС;
|
||
- себестоимость реализации;
|
||
- валовая прибыль;
|
||
- маржа;
|
||
- честный отказ, если данных мало;
|
||
- next action, если рейтинг нельзя построить.
|
||
|
||
## 27. Источники для этого документа
|
||
|
||
Ключевые источники:
|
||
|
||
- `AGENTS.md`
|
||
- `graphify-out/GRAPH_REPORT.md`
|
||
- `.codex/skills/domain-case-loop/SKILL.md`
|
||
- `.codex/skills/domain-case-loop/references/repo_runtime_map.md`
|
||
- `.codex/skills/domain-case-loop/references/business_first_analyst_rubric.md`
|
||
- `.codex/agents/orchestrator.toml`
|
||
- `.codex/agents/domain_analyst.toml`
|
||
- `.codex/agents/domain_coder.toml`
|
||
- `scripts/domain_case_loop.py`
|
||
- `scripts/domain_truth_harness.py`
|
||
- `scripts/review_assistant_stage1_run.py`
|
||
- `scripts/stage_agent_loop.py`
|
||
- `scripts/save_agent_semantic_run.py`
|
||
- `scripts/agent_semantic_pack_builder.py`
|
||
- `llm_normalizer/data/shared_llm_connection.json`
|
||
- `llm_normalizer/backend/src/config.ts`
|
||
- `llm_normalizer/backend/src/services/promptBuilder.ts`
|
||
- `docs/orchestration/active_domain_contract.json`
|
||
- `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`
|