t-invest-skill — CLI + скилл для доступа к Т-Инвестициям

Даёт ИИ-агенту доступ к вашему брокерскому счёту Т-Инвестиций: данные, аналитику
и операции по вашей команде — через T-Invest API.
Вы спрашиваете обычным языком — «как мой портфель?», «почём я брал Сбер?», «какая
доходность у моих облигаций?» — а агент сам вызывает встроенный CLI и отвечает по
реальным данным счёта, а не по памяти. Вручную запускать CLI не нужно.

Это инструмент доступа к данным и операциям, а не инвестиционный советник: он
не оказывает инвестиционного консультирования и не даёт индивидуальных
инвестиционных рекомендаций (см. Дисклеймер).

Что умеет

• Портфель: позиции и P/L, реальная доходность (XIRR с учётом пополнений и
  выводов), структура (классы активов, секторы, валюты, страны, концентрация),
  календарь пассивного дохода (купоны + дивиденды), свободные деньги,
  операции с комиссиями.
• Рынок и бумаги: котировки, история цены с бенчмарком (IMOEX), стакан,
  лента обезличенных сделок, техиндикаторы (RSI/SMA/MACD), расписание торгов,
  карточки любых активов, облигации с расчётом YTM и дюрации, дивиденды,
  фундаментал, прогнозы аналитиков.
• Скринеры: облигации (по YTM / сроку / риску) и акции (по фундаменталу) по
  всему справочнику с локальным кэшем.
• Информация: новости, сделки инсайдеров, календарь отчётностей, сигналы
  стратегий, вотчлист.
• Торговля: заявки и стоп-заявки — в песочнице свободно, на боевом счёте с
  обязательным подтверждением каждой сделки; в режиме «только чтение» мутации
  заблокированы кодом.

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

Установка

Нужно: Node.js ≥ 20 (единственная внешняя зависимость — весь код вшит в один
файл, npm-пакеты и сборка не требуются) и агент, умеющий читать SKILL.md и
запускать shell-команды.

Быстро — одной командой (Linux / macOS / WSL). Скачает скилл и распакует его
в каталоги скиллов (~/.agents/skills/ — общий для агентов, ~/.claude/skills/ —
Claude Code), а также создаст шаблон ~/.config/tinvest/.env (без токенов):

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

Повторный запуск обновляет скилл и НЕ трогает уже вписанные токены. Скилл сам
подскажет (в session status), когда в репозитории появится новая версия.

Вручную. Скилл — это папка с SKILL.md, scripts/, references/. Скачай
.skill (кнопка в шапке или Releases) —
это ZIP-архив — и распакуй в каталог скиллов своего агента (~/.agents/skills/ у
большинства, ~/.claude/skills/ у Claude Code; сам файл-архив не подхватывается):

unzip t-invest.skill -d ~/.agents/skills/     # или -d ~/.claude/skills/ для Claude Code
# → <каталог>/t-invest/{SKILL.md, scripts/tinvest.cjs, references/}

После установки скилл подхватывается автоматически (перезапусти сессию агента).

Токены и режимы

CLI работает в трёх режимах, у каждого — собственный токен:

Токены выпускаются в личном кабинете Т-Инвестиций
→ «Токены T-Invest API» (уровень доступа под режим — по таблице выше; пошагово —
в инструкции по выпуску токена).
Кладутся в единственный файл ~/.config/tinvest/.env:

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 читает .env только из
~/.config/tinvest/.env (не из текущей папки) — детерминированно, из любой
директории запуска; реальные переменные окружения имеют приоритет (штатный
способ для CI/контейнеров). Без токена — ошибка APP_TINVEST_TOKEN_MISSING,
никаких значений по умолчанию. Уровень «Торговля и переводы» не нужен: CLI
переводов и выводов средств не делает.

Реальные деньги: гейт и безопасность

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

T_INVEST_ALLOW_TRADING=true   # разрешить реальные сделки (каждая — с подтверждением)
T_INVEST_STONKS_MODE=true     # ОПАСНО: сделки без подтверждений (осознанный opt-in)

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

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

Деньги нельзя вывести со счёта: токен уровня «Торговля» и отсутствие в коде
методов перевода/вывода означают, что возможны только операции с бумагами внутри
самого счёта. Честная оговорка: разделение режимов и гейт торговли — защита
штатных путей (флаг + подтверждение), а не криптография; владелец окружения может
включить флаг сам, но это осознанное явное действие.

Как это работает

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

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

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

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

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

Дисклеймер

Это инструмент доступа к данным и операциям T-Invest API. Он не является услугой
инвестиционного консультирования и не предоставляет индивидуальных инвестиционных
рекомендаций (ИИР). Данные и расчёты предоставляются «как есть», информационно;
все инвестиционные решения и сделки — на усмотрение и под ответственность
пользователя. Аналитика (доходности, скринеры, прогнозы аналитиков) — это данные и
вычисления, а не рекомендации к покупке/продаже.