Развертывание и практика Dexter: пусть ИИ читает документы SEC и делает оценку DCF за вас

Введение

Dexter — это автономный агент для финансовых исследований, работающий в терминале. Вы задаете ему сложный вопрос, и он автоматически разбивает задачу, вызывает несколько инструментов данных и перепроверяет результаты, пока не выдаст подкрепленное данными заключение — словно у вас есть неутомимый старший аналитик.

Его основные возможности включают:

• Чтение документов SEC: автоматический сбор 10-K, 10-Q, 8-K и других отчетных документов.
• Запрос котировок в реальном времени: цены акций, финансовые показатели, денежные потоки, балансовые отчеты.
• Оценка внутренней стоимости по DCF: встроенный навык DCF на базе SKILL.md, самостоятельно выполняющий дисконтирование денежных потоков.
• Цикл самопроверки: проверка промежуточных результатов и итерации до тех пор, пока вывод не станет обоснованным.
• Защита от зацикливания: встроенный лимит шагов для предотвращения потери контроля над агентом.

Весь проект написан на TypeScript, ядром является LangChain + Ink (React для CLI), работает в среде Bun 1.0+. Если вы хотите использовать эти возможности с меньшими затратами, можно переключить провайдера LLM на Defapi, где цены на API в два раза ниже официальных.

---

Портрет целевой аудитории

• Разработчики с опытом 1–5 лет, имеющие базовое представление об архитектуре ИИ-агентов (вызов инструментов, Agentic Loop).
• Частные инвесторы или специалисты в сфере Fintech, желающие использовать инструменты ИИ для фундаментальных исследований.
• Инженеры, которые хотят узнать, как интегрировать несколько источников данных (SEC, Financial Datasets, Exa) в реальный проект.
• Пользователи, интересующиеся количественными финансовыми исследованиями и желающие настроить локальный конвейер обработки данных.

---

Основные зависимости и окружение

---

Структура проекта

dexter/
├── .dexter/
│   └── settings.json          # Конфигурация запуска агента (выбор модели/провайдера)
├── src/
│   ├── agent/                  # Ядро агента: логика циклов, промпты, scratchpad
│   │   ├── agent.ts           # Основной цикл Agentic Loop
│   │   ├── prompts.ts         # Системные промпты
│   │   └── scratchpad.ts      # История вызовов инструментов
│   ├── cli.tsx                # Входная точка рендеринга Ink/React CLI
│   ├── index.tsx              # Точка входа в программу
│   ├── components/            # Компоненты UI для CLI (Ink)
│   ├── hooks/                 # React-хуки (AgentRunner, ModelSelector)
│   ├── model/
│   │   └── llm.ts            # Слой абстракции LLM для разных провайдеров
│   ├── tools/
│   │   ├── registry.ts       # Реестр инструментов
│   │   ├── finance/          # Финансовые инструменты: котировки, финансы, отчеты, инсайдерские сделки
│   │   ├── search/           # Инструменты веб-поиска (Exa / Tavily)
│   │   ├── browser/          # Автоматизация браузера Playwright
│   │   └── descriptions/     # Описания инструментов (внедряются в системный промпт)
│   ├── skills/               # Каталог навыков SKILL.md
│   │   └── dcf/
│   │       └── SKILL.md     # Навык оценки внутренней стоимости по DCF
│   ├── evals/               # Фреймворк для оценки LangSmith
│   └── utils/               # Переменные окружения, конфиг, кэш
├── scripts/
│   └── release.sh
├── .env                     # API-ключи (в gitignore)
└── package.json

---

Пошаговое руководство

Шаг 1: Установка Bun и клонирование проекта

Если на вашем компьютере нет Bun, установите его. Поддерживается Windows/macOS/Linux:

# macOS / Linux
curl -fsSL https://bun.com/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"

Проверка установки:

bun --version
# Вывод примерно такой: Bun v1.2.x

Затем клонируйте репозиторий Dexter:

git clone https://github.com/virattt/dexter.git
cd dexter

Шаг 2: Настройка переменных окружения .env

Скопируйте шаблон файла переменных окружения:

cp env.example .env

Откройте .env в редакторе и введите свои ключи. Важное уточнение по подключению Defapi — если вы хотите использовать Defapi вместо OpenAI (экономия 50%), настройте следующим образом:

# .env

# ── Провайдеры LLM ──────────────────────────────────
# Вариант А: Прямое использование OpenAI (по умолчанию)
OPENAI_API_KEY=sk-your-openai-key

# Вариант Б: Доступ к OpenAI через Defapi (рекомендуется, экономия 50%)
# OPENAI_API_KEY=sk-your-defapi-key
# OPENAI_BASE_URL=https://api.defapi.com/v1

# Другие доступные провайдеры LLM
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
GOOGLE_API_KEY=your-google-key
XAI_API_KEY=your-xai-key
OPENROUTER_API_KEY=your-openrouter-key

# Локальные модели (OLLAMA)
OLLAMA_BASE_URL=http://127.0.0.1:11434

# ── Финансовые данные ───────────────────────────────
# Данные институционального уровня, AAPL/NVDA/MSFT бесплатно
FINANCIAL_DATASETS_API_KEY=your-financial-datasets-key

# ── Веб-поиск ───────────────────────────────────────
# Приоритет Exa, Tavily как резерв
EXASEARCH_API_KEY=your-exa-key
TAVILY_API_KEY=your-tavily-key

Установите зависимости:

bun install

Шаг 3: Запуск Dexter в интерактивном режиме

Запустите интерактивный CLI:

bun start

Вы увидите цветной интерфейс в терминале на базе Ink. Просто введите финансовый вопрос, например:

Какова динамика выручки AAPL за последние 5 лет? Какова текущая внутренняя стоимость по DCF?

Dexter начнет работу автоматически: разбивка задачи → поиск финансовых данных → чтение файлов SEC → запуск навыка DCF → обобщение выводов. Каждый этап вызова инструментов будет отображаться в интерфейсе в реальном времени.

Если вы хотите отлаживать код в процессе изменений, используйте режим watch:

bun dev

Шаг 4: Переключение моделей / провайдеров

Внутри CLI введите команду /model, чтобы переключить провайдера и модель. Dexter поддерживает автоматическое распознавание по префиксам:

Например, для переключения на Claude:

/model claude-sonnet-4-7

Шаг 5: Использование финансовых инструментов для запроса акций

Ядром Dexter является инструмент financial_search, который автоматически делегирует задачу наиболее подходящему под-инструменту. Примеры типичных запросов:

Запрос выручки и прибыли:

Найди выручку, чистую прибыль и свободный денежный поток TSLA за последние 3 года

Dexter вызовет get_income_statements (отчет о прибылях и убытках) и get_cash_flow_statements (отчет о движении денежных средств) и вернет данные в виде таблицы.

Запрос балансового отчета:

Каков текущий коэффициент задолженности (D/A) у NVDA? Сколько у них денежных средств и эквивалентов?

Чтение документов SEC:

Помоги мне прочитать раздел "Risk Factors" в последнем отчете 10-K компании AAPL

Dexter вызовет инструмент read_filings для захвата содержимого 10-K и перехода к нужному разделу.

Проверка инсайдерских сделок:

Какова ситуация с инсайдерскими сделками по акциям FAANG за последний квартал?

Все необработанные данные вызовов инструментов записываются в JSONL-файлы в директории .dexter/scratchpad/ для последующего аудита.

Шаг 6: Запуск навыка оценки DCF

Оценка DCF (дисконтирование денежных потоков) — один из встроенных навыков Dexter. Когда вопрос касается «внутренней стоимости» или «оценки», агент автоматически вызывает инструмент skill для загрузки src/skills/dcf/SKILL.md и выполняет шаги:

1. Получение исторического свободного денежного потока (FCF) компании.
2. Оценка темпов роста на ближайшие 5–10 лет.
3. Расчет средневзвешенной стоимости капитала (WACC).
4. Дисконтирование к текущему моменту.
5. Вывод финального диапазона оценки + анализ чувствительности.

Пример запроса:

Какова внутренняя стоимость MSFT по DCF? Укажи результаты для консервативного, базового и оптимистичного сценариев.

Шаг 7: Отладка и просмотр логов Scratchpad

Каждый запрос в Dexter генерирует JSONL-файл в папке .dexter/scratchpad/ с форматом имени:

ГГГГ-ММ-ДД-ЧЧММСС_<session_id>.jsonl

Каждая строка — это структурированная запись:

{"type":"init","timestamp":"2026-03-27T10:00:00.000Z","query":"Какова внутренняя стоимость AAPL по DCF?"}
{"type":"tool_start","timestamp":"2026-03-27T10:00:01.000Z","toolName":"get_cash_flow_statements","args":{"ticker":"AAPL","period":"annual","limit":5}}
{"type":"tool_result","timestamp":"2026-03-27T10:00:03.000Z","toolName":"get_cash_flow_statements","result":{"freeCashFlow":[67800000000, 73000000000, ...]},"llmSummary":"Свободный денежный поток AAPL стабильно рос последние 5 лет, совокупный темп роста около 9.2%"}
{"type":"thinking","timestamp":"2026-03-27T10:00:05.000Z","content":"Данные FCF получены, теперь нужно узнать ожидаемые темпы роста от аналитиков и параметры WACC..."}

Если вы заметили, что результат вызова инструмента неверен, откройте этот файл для локализации проблемы. Можно использовать jq для быстрой фильтрации:

# Посмотреть только результаты инструментов
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "tool_result")'

# Посмотреть процесс рассуждения агента
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "thinking")'

---

Устранение типичных проблем

1. Ошибка OPENAI_API_KEY not found

Самая частая ошибка. Проверьте наличие файла .env и правильность пути:

ls -la .env

Убедитесь, что внутри есть OPENAI_API_KEY=... или связка OPENAI_API_KEY + OPENAI_BASE_URL. При использовании Defapi должны присутствовать оба параметра.

2. Финансовые данные возвращают пустой результат

Бесплатные данные Financial Datasets ограничены AAPL, NVDA, MSFT. При запросе других акций вернется пустой результат. Вы можете:

• Проверить тарифный план на financialdatasets.ai.
• Убедиться, что FINANCIAL_DATASETS_API_KEY верно указан в .env.

3. Таймаут вызова модели

Таймаут API Anthropic и Google по умолчанию составляет 60 секунд. Если сетевое соединение нестабильно, можно настроить maxAttempts и время ожидания в src/model/llm.ts. Для постоянного использования рекомендуется подключаться через Defapi через оптимизированные каналы.

4. Агент попал в бесконечный цикл

В Dexter встроена защита maxIterations (по умолчанию 10 шагов). Если задача требует больше шагов, измените этот параметр в src/agent/agent.ts. При исчерпании шагов агент вернет текущие промежуточные выводы как финальный результат.

5. Неполные данные при вызове инструментов

Параметр limit в Financial Datasets управляет количеством возвращаемых лет (по умолчанию может быть 1 год). При запросе можно явно попросить Dexter указать limit=5 или limit=10.

6. Файлы Scratchpad пусты или не создаются

Scratchpad управляется в src/agent/scratchpad.ts. Если установлена переменная окружения SKIP_SCRATCHPAD=true, файлы не будут записываться. Проверьте .env. Также помните, что каждый новый запрос создает новый файл, а не дополняет старый.

---

Дополнительное чтение / Направления развития

Подключение WhatsApp для мобильного помощника

Dexter поддерживает получение сообщений через WhatsApp Gateway. Если ваш телефон и Dexter находятся в одной сети:

# Сканирование QR-кода для привязки WhatsApp
bun run gateway:login

# Запуск шлюза
bun run gateway

Отправьте сообщение самому себе в WhatsApp, и Dexter ответит. Это удобно для проверки финансовых данных компаний во время поездок.

Подробности в src/gateway/channels/whatsapp/README.md.

Запуск тестов для проверки точности агента

В Dexter встроена система оценки на базе LangSmith:

# Запуск оценки на всех тестовых вопросах
bun run src/evals/run.ts

# Случайная выборка из 10 вопросов
bun run src/evals/run.ts --sample 10

Оценка проводится методом LLM-as-Judge, результаты загружаются в дашборд LangSmith. Если вы изменили логику расчета финансовых показателей, используйте эти тесты для проверки качества.

Использование локальных моделей через Ollama

Если вы хотите полной независимости от внешних API:

# Запуск Ollama (должна быть установлена заранее)
ollama serve

# Настройка в .env
OLLAMA_BASE_URL=http://127.0.0.1:11434

Затем переключитесь на ollama:qwen2.5 в CLI. Примечание: способности локальных моделей к вызову инструментов могут быть слабее, чем у GPT-5.4 или Claude Sonnet.

Создание новых навыков в SKILL.md

Навыки в Dexter определяются через файлы SKILL.md. Каждый навык содержит YAML-заголовок (имя, описание) и инструкции в формате markdown. Чтобы создать новый навык:

1. Создайте новую папку в src/skills/, например src/skills/dupont/.
2. Напишите SKILL.md:

---
name: dupont-analysis
description: Анализ Дюпона - разложение ROE на рентабельность продаж, оборачиваемость активов и финансовый рычаг
---

# Навык анализа Дюпона

Ты финансовый аналитик. Выполни следующие шаги для указанного тикера:

1. Получи чистую прибыль, выручку, совокупные активы и акционерный капитал.
2. Рассчитай три показателя:
   - Рентабельность продаж = Чистая прибыль / Выручка
   - Оборачиваемость активов = Выручка / Совокупные активы
   - Финансовый рычаг = Совокупные активы / Акционерный капитал
3. Рассчитай ROE = Произведение этих трех показателей
4. Сравни со средними отраслевыми значениями и дай оценку (1-10)

1. Перезапустите Dexter, новый навык будет автоматически обнаружен и внедрен в системный промпт.

Снижение затрат на API через Defapi

Для сценариев с высокой частотой вызовов LLM (автоматический мониторинг рынка, генерация регулярных отчетов) затраты на API становятся значимыми. Подключение через Defapi позволяет сэкономить около 50%:

# .env
OPENAI_API_KEY=your-defapi-api-key
OPENAI_BASE_URL=https://api.defapi.com/v1

Defapi совместим со всеми моделями через интерфейс v1/chat/completions, Dexter не требует правок в коде, достаточно заменить ключ и базовый URL.