invest-harness/designDocument/scenarios.md

# Пять демонстрационных сценариев

Четыре сценария адаптированы из предоставленной аналитической работы «Finance Harness», версия 1.0 от 11.11.2026, раздел 3 (страницы 4–5), с учётом технической модели на странице 11. Третий сценарий заменён на поиск сигналов в волатильных акциях по продуктовому запросу. Это требования к демонстрации Invest Harness, а не описание готовых интеграций или подтверждённых продуктовых эффектов

В исследовании профили называются harness. В [терминах платформы](design.md) «Мой первый портфель», «Эксперты из Пульс», «Поиск сигналов в волатильных акциях», «Капитал под цель» и «Исследовательская панель» — пять **шаблонов агента** на общей DSH-базе: каждый закрепляет harness, плагины, скиллы, правила ответа и JSON Schema настроек. Отдельный движок для каждого сценария не нужен. Пользователь создаёт из шаблона свой экземпляр агента

| Шаблон | Запрос пользователя | Результат | Демонстрируемая возможность |
|---|---|---|---|
| Мой первый портфель | «Объясни, чем отличаются эти инструменты» | Понятное сравнение и учебный пример | Настройка глубины ответа через форму |
| Эксперты из Пульс | «Как менялась позиция выбранного автора?» | Хронология с подтверждающими источниками | Поиск по публикациям и цитирование |
| Поиск сигналов в волатильных акциях | «Сообщи о необычном движении выбранных акций» | Сигнал с графиком и объяснением | Частый мониторинг и уведомления |
| Капитал под цель | «Как накопить 3 млн рублей за семь лет?» | Несколько расчётных планов | Калькулятор, параметры и график |
| Исследовательская панель | «Сравни банки по отчётности» | Проверяемые расчёты и аналитический отчёт | Инструменты, документы и свой Runner |

## Общие условия демонстрации

Пользователь выбирает шаблон в каталоге, настраивает форму, связывает разрешённые connections и выбирает локальное или удалённое исполнение. Провайдер модели выбирается независимо от сценария: API key либо доступный для этой среды account mode из [матрицы плагинов](plugins.md). Наличие подписки не гарантирует доступность интеграции

В каждом сценарии ниже названия инструментов и финансовых плагинов — проектируемые возможности. Плагины объявляют доступы, а шаблоны закрепляют версии и скиллы. Минимальная демонстрация работает с подготовленными документами и снимками данных; доступ к брокерскому аккаунту, Пульсу и платным источникам не считается уже полученным

Для этих пяти демонстрационных шаблонов используются учебные либо read-only подключения без отправки торговых поручений. Это граница конкретных шаблонов; платформа по-прежнему рассматривает внутреннюю логику Runner как чёрный ящик. Скилл описывает метод работы, но ограничения доступа обеспечивает runtime и политика инструментов

Настройки ниже — содержимое config schema шаблона; вопрос, документ и снимок портфеля — вход конкретного Run. Секреты хранятся в connections, а не в форме. Смена профиля не переносит контекст автоматически: пользователь явно передаёт выбранный снимок или параметры цели новому агенту; права проверяются повторно. Общая неограниченная память между агентами не требуется

## 1. «Мой первый портфель»

**Пользователь и цель.** Начинающий инвестор хочет понять инструменты и смысл показателей до принятия собственного решения. Пример запроса: «Объясни разницу между вкладом и облигацией из этого примера простыми словами»

**Состав.** DSH harness; плагины словаря, рыночных справочников и симулятора портфеля (`glossary`, `market_data`, `portfolio_simulator`); скилл объяснения финансовых понятий. Брокерское подключение не требуется

**Настройки формы.** `knowledgeLevel` — начальный/базовый; `explanationDepth` — кратко/подробно; `showGlossary` и `includeQuiz` — переключатели; `virtualCapital` — положительная сумма с валютой. Это параметры объяснения и симуляции, а не присвоение пользователю инвестиционной стратегии

**Ход сценария.**

1. Пользователь выбирает «Мой первый портфель», задаёт уровень объяснения и виртуальный капитал, сохраняет ревизию
2. Передаёт вопрос и выбирает инструменты из демонстрационного набора
3. Агент получает определения и характеристики из разрешённых источников, отделяет известные условия от допущений
4. Симулятор строит учебный пример; агент объясняет результаты и при включённой настройке добавляет вопрос для самопроверки
5. Пользователь меняет глубину объяснения через форму и запускает новый Run с теми же входными данными

**Результат.** Сравнение инструментов, расшифровка терминов, учебный пример и ссылки на использованные материалы. Краткий и подробный режимы сохраняют одни и те же исходные факты

**Если данных не хватает.** Агент обозначает отсутствующие характеристики и предлагает дополнить вход. Недоступность источника не заменяется выдуманным значением. Учебная цена или доходность явно помечается как условная

**Регулярная работа.** Раз в неделю агент готовит урок по выбранным темам, обновляет учебный пример и добавляет вопрос для самопроверки. План тем задаётся в настройках; предыдущий результат передаётся явно, если нужно избежать повторения урока. Ответ пользователя не предполагается автоматически: он может запустить отдельный разбор ответа вручную. Реальные сделки и брокерский аккаунт для такого расписания не нужны

**Критерий приёмки.** Форма меняет стиль и детализацию ответа без редактирования prompt пользователем; расчёты симулятора воспроизводимы; отсутствуют инструменты размещения поручений. Минимальный запуск — локально с кешированным учебным набором; модель может требовать сеть

## 2. «Эксперты из Пульс»

**Пользователь и цель.** Читатель хочет найти и сопоставить опубликованные взгляды автора. Пример: «Что автор писал о банках до отчётности и после неё?»

**Состав.** DSH harness; плагины `pulse_search`, `transcript_search`, `stance_timeline`, `conflict_checker`; скилл анализа источников. Для первого демо используется разрешённый набор публикаций с метаданными либо явно синтетический корпус. Живая интеграция с Пульсом требует отдельной проверки доступа

**Настройки формы.** `authorIds`, временной интервал поиска, `answerDepth`, `includeContradictions`. Обязательность ссылок и запрет выдуманных цитат входят в политику шаблона и не выключаются пользовательской настройкой

**Ход сценария.**

1. Пользователь выбирает автора и период, задаёт вопрос
2. Поиск фильтрует разрешённый корпус по автору, датам и теме
3. Инструменты возвращают фрагменты, идентификаторы публикаций, даты публикации/обновления и источник
4. Агент разделяет факты и мнения, сопоставляет позиции во времени и показывает противоречия
5. Пользователь открывает источник из ответа либо расширяет период и создаёт новый Run

**Результат.** Хронология тезисов с цитатами и источниками; отдельно — что найдено, что противоречит друг другу и чего подтвердить не удалось. Это поиск по высказываниям, а не выступление от имени живого автора

**Если подтверждения нет.** Агент сообщает, что позиция не найдена в выбранном корпусе и периоде. Старая публикация не превращается в утверждение о сегодняшней рекомендации. Команды внутри найденных текстов не получают полномочий управлять агентом

**Регулярная работа.** Ежедневный запуск проверяет новые и обновлённые публикации выбранных авторов, формирует дайджест и сопоставляет их с ранее найденными позициями. Источник должен поддерживать разрешённое чтение; для демо достаточно последовательных снимков корпуса. Плагин сохраняет идентификаторы и даты обновления обработанных публикаций отдельно от ExecutionSpec; отметка обработки продвигается только после сохранения результата. Повторная проверка с перекрытием интервалов не дублирует публикации. Если материалов нет, отчёт сообщает об отсутствии обновлений; ошибка доступа не трактуется как отсутствие публикаций

**Критерий приёмки.** Каждая цитата совпадает с фрагментом корпуса, автор и дата атрибутированы правильно. Тестовый конфликт показывает обе позиции; запрос без источника не порождает выдуманный ответ. Разрешения корпуса проверяются и в локальном, и в удалённом режиме

## 3. «Поиск сигналов в волатильных акциях»

**Пользователь и цель.** Инвестор выбирает набор волатильных акций и хочет получать сообщения о необычном ускорении роста, замедлении роста или падении цены. Пример: «Проверяй эти акции каждые две минуты и сообщай о резких изменениях, для которых не нашлось объяснения в доступных источниках»

**Состав.** DSH harness; плагины рыночных данных, расчёта сигналов, новостного поиска, графиков, `recurring-tasks` и доставки уведомлений; скилл объяснения рыночных отклонений. Расчёт выполняет детерминированный инструмент, а агент проверяет контекст и формулирует сообщение. Торговые поручения не отправляются

**Настройки формы.** Список идентификаторов инструментов и бирж, интервал проверки (в первой версии 1–5 минут), размер свечи, окно сглаживания, окно оценки обычной волатильности, пороги скорости и ускорения, минимальная ликвидность/объём, максимальный возраст данных, время подавления повторов и выбранные типы сигналов. Пользователь задаёт режим уведомлений: обо всех обнаруженных отклонениях либо только об отклонениях без найденного объяснения. Источники новостей и канал доставки подключаются с отдельными разрешениями; секреты в форму не попадают

**Как определяется сигнал.** Используются завершённые свечи одинаковой длительности. Расчётный плагин получает сглаженный логарифм цены x(t), оценивает скорость v(t) = [x(t) − x(t−Δt)] / Δt и ускорение a(t) = [v(t) − v(t−Δt)] / Δt. Метод сглаживания, единицы времени, пороги и версия алгоритма закреплены в конфигурации. Сглаживание и сравнение используют только данные, доступные к моменту оценки, без будущих свечей

- Ускорение роста: скорость положительна, ускорение положительно и превышает выбранный порог необычности
- Замедление роста: скорость ещё положительна, ускорение отрицательно и по модулю превышает порог; это не утверждение, что цена уже падает
- Падение: скорость отрицательна и её модуль превышает порог; отрицательное ускорение дополнительно отмечает усиление падения

Пороги сравниваются с прошлым поведением той же бумаги на сопоставимом интервале, а не с одним абсолютным значением для всех акций. Алгоритм и значения порогов проверяются на историческом воспроизведении до включения уведомлений; документ не задаёт универсально прибыльную торговую стратегию

**Ход сценария.**

1. Пользователь выбирает акции, периодичность, параметры чувствительности и канал уведомлений, сохраняет ревизию и включает расписание
2. Запуск проверяет торговую сессию, свежесть и полноту свечей, достаточность истории и ликвидность, затем рассчитывает скорость, ускорение и отклонения
3. Для кандидатов плагин проверяет корпоративные события, доступные новости, движение рынка и сектора; сплит или изменение базы цены не выдаются за обычный рыночный скачок
4. Агент формирует объяснение со ссылками либо помечает, что объяснение не найдено в проверенных источниках. Недоступный источник обозначается отдельно: он не подтверждает отсутствие новостей
5. Сигнал сохраняется, проверяется подавление повторов и создаётся задание доставки в разрешённый канал. Пользователь получает время, бумагу, тип отклонения, значения показателей, график или ссылку на него и статус проверки объяснения

**Результат.** Карточка сигнала с датой и часовым поясом, временем последней свечи, источником котировок, интервалом расчёта, порогом и измеренным отклонением. При найденной новости показывается возможная связь, а не доказанная причина. Слова «объяснение не найдено» не означают, что движение объективно необоснованно, и не являются командой купить или продать

**Если данные непригодны.** При пропусках, устаревших котировках, недостаточной истории, остановке торгов или неподтверждённой корректировке цены расчёт по бумаге пропускается с причиной. Недоступность новостей даёт статус «объяснение не проверено»; в режиме «только без найденного объяснения» такой сигнал не отправляется как необъяснённый. Техническая ошибка видна в истории запусков

**Регулярная работа.** Расписание запускает проверку каждые 1–5 минут; плагин учитывает календарь и сессию конкретной биржи, вне сессии возвращает статус без сигнала. Для этого сценария overlapPolicy=skip и misfirePolicy=skip: после простоя проверяется ближайшее новое срабатывание, просроченные торговые сигналы не рассылаются. Субминутный мониторинг потребует отдельного потокового режима и не обещается текущим cron API

Состояние мониторинга хранит последнюю обработанную свечу и активное отклонение отдельно для tenant, агента, инструмента и версии алгоритма. Пока одно отклонение продолжается, новые проверки не создают одинаковые уведомления. Повтор разрешён после возврата показателя в норму и нового пересечения порога либо при явно настроенном усилении сигнала; cooldown ограничивает частоту. Перезапуск Runner не сбрасывает это состояние

Сигнал и запись на доставку фиксируются атомарно в хранилище плагина. Доставка повторяется отдельно от расчёта с тем же notificationId и ограниченным сроком актуальности; статус доставки виден пользователю. Если канал не поддерживает идемпотентность, неоднозначный ответ отмечается как неизвестный результат доставки, без обещания отсутствия дублей. Перед отправкой повторно проверяются разрешение канала и возраст сигнала

**Критерий приёмки.** Историческое воспроизведение проверяет раздельное обнаружение трёх типов движения, отсутствие использования будущих данных и подавление повторов. Пропуск свечи, сплит, закрытая сессия и устаревшие котировки не создают ложный сигнал в подготовленных тестах. Повтор одного запуска не создаёт второе задание доставки, а сбой доставки не запускает повторный анализ. Качество сигналов и частота ложных срабатываний измеряются отдельно; успешный Run не доказывает полезность сигнала для торговли

## 4. «Капитал под цель»

**Пользователь и цель.** Пользователь задаёт сумму и срок и хочет сравнить возможные планы накопления. Пример: «Какой ежемесячный взнос нужен для 3 млн рублей через семь лет?»

**Состав.** DSH harness; плагины `goal_calculator`, `scenario_engine` и графиков; скилл объяснения сценарных расчётов. Брокерское подключение необязательно; доходность и инфляция могут быть заданными пользователем допущениями

**Настройки формы.** `targetAmount`, `targetDate`, `initialCapital`, `currency`, `contributionTiming`, массив сценариев с доходностью и инфляцией. Форма явно различает будущую номинальную сумму и сумму в сегодняшних ценах; не предлагает скрытого значения «ожидаемой доходности»

**Ход сценария.**

1. Пользователь создаёт «Капитал под цель», заполняет цель и исходные параметры
2. Валидатор отклоняет прошедшую дату, несовместимые валюты и неполные сценарии
3. Калькулятор определяет периодичность, преобразует ставки по зафиксированной методике и рассчитывает взносы для каждого сценария
4. Агент объясняет различия; график строится из результата калькулятора, а не из чисел, придуманных моделью
5. Пользователь меняет срок или взнос через форму и получает новый расчёт, сохраняя предыдущую ревизию для сравнения

**Результат.** Таблица сценариев, требуемый взнос, траектории накопления, исходные допущения и методика. До появления встроенного chart-компонента достаточно таблицы и файла с рядами данных; интерактивный график — отдельная возможность UI

**Если цель недостижима при заданном взносе.** Агент показывает расчётный разрыв и чувствительность к изменению параметров. Он не увеличивает допущение доходности молча и не представляет сценарии как прогноз рынка

**Регулярная работа.** Раз в месяц агент получает актуальный капитал и фактические взносы из разрешённого источника либо явно обновлённого пользователем снимка, сравнивает их с планом и рассчитывает оставшийся взнос. Допущения доходности и инфляции остаются закреплёнными настройками, пока пользователь их не изменит. Без свежих фактических данных создаётся только плановый пересчёт с явной отметкой, что выполнение плана не проверено. Агент предлагает изменения параметров, но не сохраняет новую ревизию цели без действия пользователя

**Критерий приёмки.** Калькулятор корректно обрабатывает нулевую ставку, уже достигнутую цель, момент внесения взноса и номинальные/реальные суммы. Ответ и график используют один набор данных. Сценарий доступен локально без подключения брокера

## 5. «Исследовательская панель»

**Пользователь и цель.** Аналитик хочет сократить сбор отчётности и расчёт сопоставимых показателей. Пример: «Сравни выбранные банки по ROE, капиталу и динамике маржи за один период»

**Состав.** DSH harness; плагины чтения документов, `statements_RAG`, `calculate_metrics`, графиков; опциональный read-only адаптер брокерских данных; скилл анализа отчётности. Идентификаторы инструментов — проектируемые контракты, а не утверждение о наличии готового MCP-сервера

**Настройки формы.** `entityIds`, отчётный период, стандарт отчётности, валюта представления, `metricIds`, `checklistVersionId`, `sourcePolicy`. В первой версии пользователь выбирает проверенные формулы и чек-листы. Загрузка произвольного исполняемого кода формулы требует отдельного пакета, проверки и разрешений

**Ход сценария.**

1. Аналитик выбирает «Исследовательская панель», документы и набор показателей, сохраняет параметры через форму
2. При конфиденциальных материалах выбирает локальный или on-prem Runner и модель, разрешённую политикой передачи данных
3. Поиск находит строки документов с привязкой к страницам; нормализатор проверяет период, единицы, стандарт и периметр консолидации
4. Калькулятор вычисляет показатели по выбранной версии методики. Агент формирует интерпретацию и перечисляет ограничения сравнения
5. Результат сохраняется как отчёт, таблица расчётов и использованные ссылки. Повторное исследование закрепляет новый снимок входных данных

**Результат.** Сравнительная таблица, формулы и исходные числа со ссылками на страницы, графики при наличии UI capability, список несопоставимых или отсутствующих значений

**Если документы несопоставимы.** Показатель маркируется как несопоставимый или нерассчитанный; отсутствие данных не заменяется нулём. При недоступности своего Runner задача не переносится в облачный пул автоматически. Само размещение Runner on-prem не разрешает отправлять документы внешней модели

**Регулярная работа.** Раз в неделю агент проверяет разрешённые источники на новые или исправленные отчёты выбранных компаний. При появлении документов пересчитывает сопоставимые показатели и показывает различия с предыдущим успешным исследованием, сохраняя версии документов и методики. Если новых документов нет, возвращает краткий статус без нового вывода о компании. Исправленный отчёт обрабатывается как новая версия источника, а не незаметная замена прежнего результата

**Критерий приёмки.** На подготовленном наборе документов расчёты совпадают с эталоном в заранее заданной погрешности; каждое исходное число имеет источник. Переключение на совместимый свой Runner сохраняет контракт входа/выхода и не расширяет доступы

## Общие правила регулярного запуска

Пользователь выбирает расписание, IANA timezone, закреплённую ревизию агента и место исполнения, проверяет ближайшие срабатывания и включает задачу. Настройки расписания хранятся в Schedule, а не внутри каждого DSH-плагина. Выключение расписания прекращает будущие запуски; текущий Run отменяется отдельно

Каждое срабатывание создаёт отдельный Run с новым входным снимком либо явно указанным режимом получения свежих данных. После создания ExecutionSpec не меняется. Данные, полученные внутри Run, сохраняются как артефакты с датами и источниками. Сравнение с историей использует явно разрешённую ссылку на предыдущий успешный результат, а не неограниченную общую память агентов

Для периодических обзоров исходный вариант — overlapPolicy=skip и misfirePolicy=coalesce: занятое расписание пропускает срабатывание, после простоя выполняется максимум один пропущенный запуск. Точная семантика задана в [API расписаний](api/runs-api.md). Поиск краткоживущих сигналов использует misfirePolicy=skip, как указано в третьем сценарии. Плагин хранит состояние мониторинга в пределах tenant и экземпляра агента; повтор не должен дважды продвигать отметку обработки. Это требование к реализации финансовых плагинов, а не новая гарантия диспетчера

Результат доступен в истории запусков. Для третьего сценария плагин уведомлений и разрешение канала обязательны до включения доставки; для остальных уведомления опциональны. Наличие расписания само по себе не означает отправку сообщений. Если данные недоступны, отчёт показывает проблему, а отзыв connection приостанавливает расписание согласно общему контракту

## Связь с реализацией платформы

Финансовые инструменты перечисленных шаблонов расширяют [линейку плагинов](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 означает, что результат принят по техническому контракту. Финансовая корректность, точность цитат и понятность объяснений проверяются отдельными эталонными задачами каждого шаблона. Числа из примеров — входы демонстрации, а не обещания доходности или измеренные результаты продукта