From 15f541e9e480410dc7ab599ee81d0facd9f01086 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 11 Nov 2026 06:22:39 +0000 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=BF=D0=B8=D1=81=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BF=D1=8F=D1=82=D1=8C=20=D0=B8=D0=BD=D0=B2=D0=B5=D1=81=D1=82?= =?UTF-8?q?=D0=B8=D1=86=D0=B8=D0=BE=D0=BD=D0=BD=D1=8B=D1=85=20=D1=81=D1=86?= =?UTF-8?q?=D0=B5=D0=BD=D0=B0=D1=80=D0=B8=D0=B5=D0=B2=20START,=20GUARD,=20?= =?UTF-8?q?GOAL,=20PULSE=20=D0=B8=20PRO?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 10 ++- designDocument/design.md | 6 ++ designDocument/scenarios.md | 148 ++++++++++++++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 designDocument/scenarios.md diff --git a/README.md b/README.md index 2209f29..78b478d 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,15 @@ ## Демонстрационные харнессы -- в процессе доработки... +Пять шаблонов агента на общей базе DSH: + +1. **START — Мой первый портфель:** объяснение инструментов и учебный портфель. +2. **GUARD — Сохранить деньги:** аудит портфеля, ликвидности и рисков к заданной дате. +3. **GOAL — Капитал под цель:** расчёт взносов и сравнение сценариев накопления. +4. **PULSE — Эксперты с доказательствами:** поиск мнений авторов с датами и источниками. +5. **PRO — Исследовательская панель:** анализ отчётности и проверяемые расчёты. + +[Подробные сценарии: настройки, шаги, результаты и критерии приёмки](designDocument/scenarios.md). - [Дизайн документ платформы](designDocument/design.md) - [Схемы работы харнессов](designDocument/design.md) \ No newline at end of file diff --git a/designDocument/design.md b/designDocument/design.md index 43b12c9..c704b3b 100644 --- a/designDocument/design.md +++ b/designDocument/design.md @@ -42,6 +42,12 @@ Invest Harness — платформа агентов для инвестиций 5. Если harness поддерживает запрос ввода и checkpoint, пользователь может ответить и продолжить выполнение отдельной попыткой. 6. Обновление шаблона создаёт новую ревизию агента после проверки настроек; текущие запуски не меняются. +### Пять инвестиционных сценариев + +На общем DSH harness создаются пять шаблонов: **START** объясняет инструменты начинающему, **GUARD** проверяет портфель к заданной дате, **GOAL** рассчитывает план накопления, **PULSE** сопоставляет подтверждённые мнения авторов, **PRO** анализирует отчётность. Пользователь настраивает шаблон через JSON Schema Driven UI и выбирает локальный либо удалённый Runner. Финансовые инструменты реализуются плагинами; методика задаётся скиллами. + +[Сценарии с настройками, шагами, обработкой ошибок и критериями приёмки](scenarios.md). Они описывают демонстрационные шаблоны с учебным или read-only доступом; конкретные внешние интеграции требуют проверки. Внутренняя логика агента остаётся за границей ответственности платформы. + ## Архитектура C4 Контейнер в C4 — отдельно запускаемое приложение или хранилище, не обязательно Docker-контейнер. Диаграммы используют нотацию Mermaid с явными типами элементов C4. C3 раскрывает логические модули, а не отдельные микросервисы. diff --git a/designDocument/scenarios.md b/designDocument/scenarios.md new file mode 100644 index 0000000..21637d8 --- /dev/null +++ b/designDocument/scenarios.md @@ -0,0 +1,148 @@ +# Пять демонстрационных сценариев + +Сценарии адаптированы из предоставленной аналитической работы «Finance Harness», версия 1.0 от 11.11.2026, раздел 3 (страницы 4–5), с учётом технической модели на странице 11. Это требования к демонстрации Invest Harness, а не описание готовых интеграций или подтверждённых продуктовых эффектов. + +В исследовании профили называются harness. В [терминах платформы](design.md) START, GUARD, GOAL, PULSE и PRO — пять **шаблонов агента** на общей DSH-базе: каждый закрепляет harness, плагины, скиллы, правила ответа и JSON Schema настроек. Отдельный движок для каждого сценария не нужен. Пользователь создаёт из шаблона свой экземпляр агента. + +| Шаблон | Запрос пользователя | Результат | Демонстрируемая возможность | +|---|---|---|---| +| START — Мой первый портфель | «Объясни, чем отличаются эти инструменты» | Понятное сравнение и учебный пример | Настройка глубины ответа через форму | +| GUARD — Сохранить деньги | «Деньги нужны через девять месяцев: где риски?» | Аудит портфеля и ликвидности | Read-only данные и регулярный обзор | +| GOAL — Капитал под цель | «Как накопить 3 млн рублей за семь лет?» | Несколько расчётных планов | Калькулятор, параметры и график | +| PULSE — Эксперты с доказательствами | «Как менялась позиция выбранного автора?» | Хронология с подтверждающими источниками | Поиск по публикациям и цитирование | +| PRO — Исследовательская панель | «Сравни банки по отчётности» | Проверяемые расчёты и аналитический отчёт | Инструменты, документы и свой Runner | + +## Общие условия демонстрации + +Пользователь выбирает шаблон в каталоге, настраивает форму, связывает разрешённые connections и выбирает локальное или удалённое исполнение. Провайдер модели выбирается независимо от сценария: API key либо доступный для этой среды account mode из [матрицы плагинов](plugins.md). Наличие подписки не гарантирует доступность интеграции. + +В каждом сценарии ниже названия инструментов и финансовых плагинов — проектируемые возможности. Плагины объявляют доступы, а шаблоны закрепляют версии и скиллы. Минимальная демонстрация работает с подготовленными документами и снимками данных; доступ к брокерскому аккаунту, Пульсу и платным источникам не считается уже полученным. + +Для этих пяти демонстрационных шаблонов используются учебные либо read-only подключения без отправки торговых поручений. Это граница конкретных шаблонов; платформа по-прежнему рассматривает внутреннюю логику Runner как чёрный ящик. Скилл описывает метод работы, но ограничения доступа обеспечивает runtime и политика инструментов. + +Настройки ниже — содержимое config schema шаблона; вопрос, документ и снимок портфеля — вход конкретного Run. Секреты хранятся в connections, а не в форме. Смена профиля не переносит контекст автоматически: пользователь явно передаёт выбранный снимок или параметры цели новому агенту; права проверяются повторно. Общая неограниченная память между агентами не требуется. + +## 1. START — «Мой первый портфель» + +**Пользователь и цель.** Начинающий инвестор хочет понять инструменты и смысл показателей до принятия собственного решения. Пример запроса: «Объясни разницу между вкладом и облигацией из этого примера простыми словами». + +**Состав.** DSH harness; плагины словаря, рыночных справочников и симулятора портфеля (`glossary`, `market_data`, `portfolio_simulator`); скилл объяснения финансовых понятий. Брокерское подключение не требуется. + +**Настройки формы.** `knowledgeLevel` — начальный/базовый; `explanationDepth` — кратко/подробно; `showGlossary` и `includeQuiz` — переключатели; `virtualCapital` — положительная сумма с валютой. Это параметры объяснения и симуляции, а не присвоение пользователю инвестиционной стратегии. + +**Ход сценария.** + +1. Пользователь выбирает START, задаёт уровень объяснения и виртуальный капитал, сохраняет ревизию. +2. Передаёт вопрос и выбирает инструменты из демонстрационного набора. +3. Агент получает определения и характеристики из разрешённых источников, отделяет известные условия от допущений. +4. Симулятор строит учебный пример; агент объясняет результаты и при включённой настройке добавляет вопрос для самопроверки. +5. Пользователь меняет глубину объяснения через форму и запускает новый Run с теми же входными данными. + +**Результат.** Сравнение инструментов, расшифровка терминов, учебный пример и ссылки на использованные материалы. Краткий и подробный режимы сохраняют одни и те же исходные факты. + +**Если данных не хватает.** Агент обозначает отсутствующие характеристики и предлагает дополнить вход. Недоступность источника не заменяется выдуманным значением. Учебная цена или доходность явно помечается как условная. + +**Критерий приёмки.** Форма меняет стиль и детализацию ответа без редактирования prompt пользователем; расчёты симулятора воспроизводимы; отсутствуют инструменты размещения поручений. Минимальный запуск — локально с кешированным учебным набором; модель может требовать сеть. + +## 2. GUARD — «Сохранить деньги» + +**Пользователь и цель.** Инвестору нужны деньги к определённой дате. Он хочет увидеть концентрацию, сроки и неопределённость ликвидности своего портфеля. Пример: «Мне нужны деньги через девять месяцев. Какие позиции требуют внимания?». + +**Состав.** DSH harness; плагины чтения портфеля, метаданных облигаций и сценарного расчёта (`portfolio_read`, `bond_metadata`, `rate_scenario`, `issuer_risk`), при регулярном запуске — `recurring-tasks`; скилл аудита портфеля. + +**Настройки формы.** `targetDate`, `requiredAmount`, `baseCurrency`, `maxDataAgeHours`, включение сценариев изменения ставки. Параметры стресс-сценария задаются явно. Расписание настраивается отдельной формой платформы с timezone, preview, overlap и misfire policy. + +**Ход сценария.** + +1. Пользователь выбирает GUARD и загружает снимок портфеля либо подключает доступный read-only источник. +2. Задаёт дату потребности в деньгах и сумму; платформа фиксирует конфигурацию агента. +3. Плагин нормализует позиции, валюты и дату оценки, объединяет экспозиции одного эмитента. +4. Инструменты рассчитывают концентрацию и заданные сценарии; агент объясняет результаты с указанием недостающих данных. +5. Пользователь сохраняет отчёт. При необходимости включает еженедельный запуск и просматривает следующие срабатывания перед сохранением. + +**Результат.** Сводка портфеля, концентрация по эмитентам и классам, сведения о сроках и ликвидности, сценарии и перечень пробелов. Для повторного обзора можно явно передать предыдущий результат; вывод об изменениях содержит обе даты оценки. + +**Если источник устарел или недоступен.** Отчёт обозначает возраст снимка; при превышении установленного порога задача не выдаёт его за актуальный обзор. Отзыв connection останавливает расписание с причиной. Низкая ликвидность не определяется только сроком погашения. + +**Критерий приёмки.** Итоги на подготовленном портфеле совпадают с эталонными расчётами, отсутствующие сведения видимы. Повторная доставка одного occurrence не создаёт второй Run. Локальное расписание работает только при запущенном daemon; удалённое выполняется на выбранном Runner. + +## 3. GOAL — «Капитал под цель» + +**Пользователь и цель.** Пользователь задаёт сумму и срок и хочет сравнить возможные планы накопления. Пример: «Какой ежемесячный взнос нужен для 3 млн рублей через семь лет?». + +**Состав.** DSH harness; плагины `goal_calculator`, `scenario_engine` и графиков; скилл объяснения сценарных расчётов. Брокерское подключение необязательно; доходность и инфляция могут быть заданными пользователем допущениями. + +**Настройки формы.** `targetAmount`, `targetDate`, `initialCapital`, `currency`, `contributionTiming`, массив сценариев с доходностью и инфляцией. Форма явно различает будущую номинальную сумму и сумму в сегодняшних ценах; не предлагает скрытого значения «ожидаемой доходности». + +**Ход сценария.** + +1. Пользователь создаёт GOAL, заполняет цель и исходные параметры. +2. Валидатор отклоняет прошедшую дату, несовместимые валюты и неполные сценарии. +3. Калькулятор определяет периодичность, преобразует ставки по зафиксированной методике и рассчитывает взносы для каждого сценария. +4. Агент объясняет различия; график строится из результата калькулятора, а не из чисел, придуманных моделью. +5. Пользователь меняет срок или взнос через форму и получает новый расчёт, сохраняя предыдущую ревизию для сравнения. + +**Результат.** Таблица сценариев, требуемый взнос, траектории накопления, исходные допущения и методика. До появления встроенного chart-компонента достаточно таблицы и файла с рядами данных; интерактивный график — отдельная возможность UI. + +**Если цель недостижима при заданном взносе.** Агент показывает расчётный разрыв и чувствительность к изменению параметров. Он не увеличивает допущение доходности молча и не представляет сценарии как прогноз рынка. + +**Критерий приёмки.** Калькулятор корректно обрабатывает нулевую ставку, уже достигнутую цель, момент внесения взноса и номинальные/реальные суммы. Ответ и график используют один набор данных. Сценарий доступен локально без подключения брокера. + +## 4. PULSE — «Эксперты с доказательствами» + +**Пользователь и цель.** Читатель хочет найти и сопоставить опубликованные взгляды автора. Пример: «Что автор писал о банках до отчётности и после неё?». + +**Состав.** DSH harness; плагины `pulse_search`, `transcript_search`, `stance_timeline`, `conflict_checker`; скилл анализа источников. Для первого демо используется разрешённый набор публикаций с метаданными либо явно синтетический корпус. Живая интеграция с Пульсом требует отдельной проверки доступа. + +**Настройки формы.** `authorIds`, временной интервал поиска, `answerDepth`, `includeContradictions`. Обязательность ссылок и запрет выдуманных цитат входят в политику шаблона и не выключаются пользовательской настройкой. + +**Ход сценария.** + +1. Пользователь выбирает автора и период, задаёт вопрос. +2. Поиск фильтрует разрешённый корпус по автору, датам и теме. +3. Инструменты возвращают фрагменты, идентификаторы публикаций, даты публикации/обновления и источник. +4. Агент разделяет факты и мнения, сопоставляет позиции во времени и показывает противоречия. +5. Пользователь открывает источник из ответа либо расширяет период и создаёт новый Run. + +**Результат.** Хронология тезисов с цитатами и источниками; отдельно — что найдено, что противоречит друг другу и чего подтвердить не удалось. Это поиск по высказываниям, а не выступление от имени живого автора. + +**Если подтверждения нет.** Агент сообщает, что позиция не найдена в выбранном корпусе и периоде. Старая публикация не превращается в утверждение о сегодняшней рекомендации. Команды внутри найденных текстов не получают полномочий управлять агентом. + +**Критерий приёмки.** Каждая цитата совпадает с фрагментом корпуса, автор и дата атрибутированы правильно. Тестовый конфликт показывает обе позиции; запрос без источника не порождает выдуманный ответ. Разрешения корпуса проверяются и в локальном, и в удалённом режиме. + +## 5. PRO — «Исследовательская панель» + +**Пользователь и цель.** Аналитик хочет сократить сбор отчётности и расчёт сопоставимых показателей. Пример: «Сравни выбранные банки по ROE, капиталу и динамике маржи за один период». + +**Состав.** DSH harness; плагины чтения документов, `statements_RAG`, `calculate_metrics`, графиков; опциональный read-only адаптер брокерских данных; скилл анализа отчётности. Идентификаторы инструментов — проектируемые контракты, а не утверждение о наличии готового MCP-сервера. + +**Настройки формы.** `entityIds`, отчётный период, стандарт отчётности, валюта представления, `metricIds`, `checklistVersionId`, `sourcePolicy`. В первой версии пользователь выбирает проверенные формулы и чек-листы. Загрузка произвольного исполняемого кода формулы требует отдельного пакета, проверки и разрешений. + +**Ход сценария.** + +1. Аналитик выбирает PRO, документы и набор показателей, сохраняет параметры через форму. +2. При конфиденциальных материалах выбирает локальный или on-prem Runner и модель, разрешённую политикой передачи данных. +3. Поиск находит строки документов с привязкой к страницам; нормализатор проверяет период, единицы, стандарт и периметр консолидации. +4. Калькулятор вычисляет показатели по выбранной версии методики. Агент формирует интерпретацию и перечисляет ограничения сравнения. +5. Результат сохраняется как отчёт, таблица расчётов и использованные ссылки. Повторное исследование закрепляет новый снимок входных данных. + +**Результат.** Сравнительная таблица, формулы и исходные числа со ссылками на страницы, графики при наличии UI capability, список несопоставимых или отсутствующих значений. + +**Если документы несопоставимы.** Показатель маркируется как несопоставимый или нерассчитанный; отсутствие данных не заменяется нулём. При недоступности своего Runner задача не переносится в облачный пул автоматически. Само размещение Runner on-prem не разрешает отправлять документы внешней модели. + +**Критерий приёмки.** На подготовленном наборе документов расчёты совпадают с эталоном в заранее заданной погрешности; каждое исходное число имеет источник. Переключение на совместимый свой Runner сохраняет контракт входа/выхода и не расширяет доступы. + +## Связь с реализацией платформы + +Финансовые инструменты перечисленных шаблонов расширяют [линейку плагинов](plugins.md), но не становятся частью диспетчера. Сначала можно реализовать один ручной запуск с подготовленными данными; расписания, графики и удалённое исполнение подключаются по мере готовности соответствующих компонентов. + +| Возможность | Где определён контракт | +|---|---| +| Форма, defaults и ревизии | [JSON Schema Driven UI](configuration-ui.md), [Agents API](api/agents-api.md) | +| Публикация пяти шаблонов и зависимостей | [Каталог](catalog.md), [Catalog API](api/catalog-api.md) | +| Подключение моделей и данных | [Provider API](api/provider-api.md), [безопасность](security.md) | +| Ручной запуск и расписание | [Runs API](api/runs-api.md) | +| Локальный и заменяемый Runner | [Исполнение](execution.md), [Runner Protocol](api/executor-api.md) | +| Этапы платформы | [Roadmap](roadmap.md) | + +Успешный Run означает, что результат принят по техническому контракту. Финансовая корректность, точность цитат и понятность объяснений проверяются отдельными эталонными задачами каждого шаблона. Числа из примеров — входы демонстрации, а не обещания доходности или измеренные результаты продукта.