t-invest-skill — когда твой ИИ-агент умеет смотреть на твой инвестиционный счёт

Представь: ты спрашиваешь своего ассистента «как мой портфель?» — и он отвечает не абстрактно, а по-настоящему, по живым данным твоего брокерского счёта. «Почём я брал Сбер?», «какая доходность у моих облигаций?», «сколько у меня свободных денег?» — агент сам лезет в API Т-Инвестиций, вытаскивает реальные цифры и даёт ответ за секунды. Именно это и делает t-invest-skill.

Это не инвестиционный советник и не робот-трейдер, который сам зарабатывает тебе деньги. Это инструмент доступа: он открывает агенту твои данные, аналитику и операции — но решения и сделки остаются за тобой. Проект прямо и честно об этом пишет в дисклеймере.

Что это вообще такое

По сути это папка-скилл для ИИ-агента: SKILL.md, папка scripts/ с CLI, написанным на Node.js, и references/ с правилами поведения. Агент читает SKILL.md, понимает, как отвечать и к каким командам обращаться, а сам CLI уже ходит в T-Invest API и возвращает данные.

Изюминка в том, что CLI — это один файл на Node.js, без npm-пакетов и без сборки. Внешняя зависимость одна-единственная: Node.js версии 20 и выше. Всё остальное вшито внутрь. Скачал, распаковал в каталог скиллов своего агента — и готово.

Что умеет CLI

Возможностей довольно много, и они логично разбиты на блоки.

Портфель. Позиции и прибыль/убыток, реальная доходность XIRR (это та, что учитывает пополнения и выводы, а не просто цену), структура портфеля по классам активов, секторам, валютам и странам, концентрация риска, календарь пассивного дохода (купоны плюс дивиденды), свободные деньги и операции с комиссиями.

Рынок и бумаги. Котировки, история цены с бенчмарком IMOEX, стакан, лента обезличенных сделок, технические индикаторы (RSI, SMA, MACD), расписание торгов. Можно открыть карточку любого актива. Для облигаций CLI сам считает доходность к погашению (YTM) и дюрацию. Для дивидендов, фундаментала и прогнозов аналитиков — тоже есть данные.

Надо понимать: YTM и дюрацию CLI считает сам, потому что T-Invest API готовых значений не отдаёт. А для сложных бумаг — флоатеров, амортизации, бессрочных выпусков — честно возвращается пустой результат с объяснением, почему.

Скринеры. Облигации по доходности, сроку и риску; акции по фундаменталу. Скринеры ходят по всему справочнику инструментов, и тут пригождается локальный кэш, чтобы потом работали за доли секунды.

Информация. Новости, сделки инсайдеров, календарь отчётностей, сигналы стратегий, вотчлист.

Торговля. Заявки и стоп-заявки. В песочнице — свободно, на боевом счёте — только с подтверждением каждой сделки. В режиме «только чтение» мутации вообще заблокированы на уровне кода.

Три режима и три токена

Ключевая идея безопасности — чёткое разделение режимов, у каждого свой токен доступа:

Токены выпускаются в личном кабинете Т-Инвестиций в разделе «Токены T-Invest API», у каждого свой уровень доступа. Хранятся они в единственном файле ~/.config/tinvest/.env. Важная деталь: CLI читает .env только из этого конкретного места, а не из текущей папки — чтобы запуски из любой директории вели себя одинаково. Переменные окружения имеют приоритет над файлом, что удобно для CI и контейнеров.

Без токена — ошибка APP_TINVEST_TOKEN_MISSING, никаких значений по умолчанию, твои данные просто не утекут.

Безопасность с реальными деньгами

Вот тут самое интересное. Сам факт наличия full-токена не разрешает торговать. Настоящие сделки открываются флагом в окружении, и каждая требует подтверждения. Гейты работают в коде, до обращения к API:

Флаг T_INVEST_STONKS_MODE включает торговлю без подтверждений — это автономный режим, осознанный opt-in для тех, кто действительно хочет отдать торговлю агенту. Автор прямо помечает его словом «ОПАСНО».

Что ещё защищает деньги:

• Подтверждение каждой сделки. Агент ставит флаг подтверждения только после того, как ты явно согласовал конкретную заявку.
• Гард ликвидности. Перед реальной рыночной заявкой CLI смотрит на стакан и спред. Если бумага неликвидная или спред широкий — заявка блокируется, и агент предлагает лимитную.
• Ключ идемпотентности (--order-id). Защита от дублирования заявки, если после сетевого сбоя команда повторится.
• Аудит-журнал. Каждая мутация, реальная или в песочнице, дописывается в ~/.config/tinvest/trades.log: время, режим, бумага, лоты, цена, номер заявки.

И ещё один важный нюанс: деньги нельзя вывести со счёта. Уровень токена «Торговля» и отсутствие в коде методов перевода/вывода означают, что возможны только операции с бумагами внутри счёта. Это сделано сознательно и честно.

Как установить

Требования скромные: Node.js ≥ 20 и агент, который умеет читать SKILL.md и запускать shell-команды.

Быстрый способ — одной командой в Linux / macOS / WSL:

curl -fsSL https://raw.githubusercontent.com/nyxandro/t-invest-skill/main/install.sh | bash

Скрипт скачает скилл и распакует в каталоги скиллов — ~/.agents/skills/ общий для агентов и ~/.claude/skills/ для Claude Code — а также создаст шаблон конфига .env без токенов. Повторный запуск обновит скилл, но не тронет уже вписанные токены. Скилл сам подскажет в статусе сессии, когда в репозитории появится новая версия.

Вручную скилл распаковывается так:

unzip t-invest.skill -d ~/.agents/skills/     # или -d ~/.claude/skills/ для Claude Code

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

Настройка токенов

Токены кладутся в единый файл ~/.config/tinvest/.env, права на файл — 600:

mkdir -p ~/.config/tinvest
cat > ~/.config/tinvest/.env <<'EOF'
T_INVEST_TOKEN_SANDBOX=      # песочница
T_INVEST_TOKEN_READONLY=     # боевой счёт, уровень «Только просмотр»
T_INVEST_TOKEN_FULL=         # боевой счёт, уровень «Торговля» (НЕ «Торговля и переводы»)
EOF
chmod 600 ~/.config/tinvest/.env

Заполняй только те режимы, что нужны. Уровень «Торговля и переводы» не нужен вовсе — CLI переводов и выводов не делает.

Как это работает внутри

У самого скилла продуманы детали, которые делают его приятным в реальной жизни.

Активный режим — персистентная памятка. В начале каждого диалога скилл спрашивает, в каком режиме работать, и перезаписывает выбор. По умолчанию — самый безопасный readonly. Это значит, что новая сессия не унаследует молча режим торговли. Пока режим не подтверждён, команды с данными не выполняются. Переключиться можно в любой момент через session start --mode <режим>.

Параллельные агенты. Если под одним пользователем работают несколько агентов одновременно, каждому можно задать свой TINVEST_SESSION_ID — тогда их активные режимы раздельны и не перезаписывают друг друга. Для одного агента это не нужно.

Кэш. Списки инструментов (на сутки) и графики купонов (на неделю) кэшируются в ~/.config/tinvest/cache. Скринеры и структура портфеля после первого прогона работают за доли секунды. Кэш безопасно удалить целиком.

Диагностика. Любая ошибка выводится по-русски со стабильным кодом типа APP_TINVEST_.... Технические детали — при запуске с TINVEST_DEBUG=1.

Правила поведения агента — дисциплина режимов, подтверждение каждой сделки, должная осмотрительность, правильная интерпретация полей JSON — описаны в SKILL.md и references/, и агент обязан им следовать.

Стоит ли пробовать

Это отличный пример того, как ИИ-агент становится не генератором текста, а рабочим инструментом, который аккуратно заходит в реальный сервис. И особенно приятно видеть, что про безопасность автор подумал не вскользь, а всерьёз: разделение режимов, трехуровневая защита торговли, аудит-журнал, невозможность вывести деньги.

Если хочешь попробовать аккуратно — заведи песочницу с виртуальными деньгами и погоняй агента там. Ничем не рискуешь, а зато сразу увидишь, насколько удобно спрашивать ассистента о портфеле обычным языком и получать живые ответы.