TT Agent Bridge

Позволяет внешним CLI-агентам (ZCode / Claude Code и т.п.) через MCP напрямую управлять TauriTavern: читать рантайм-данные (чат / переменные / активацию World Info / логи / исходные запросы к LLM / рантайм статус-бара iframe), выполнять действия (STScript / отправка сообщения / запись переменных / смена персонажа / переход к записи World Info), а также запускать произвольные JS-диагностики таверн-карточек в основном документе или внутри iframe сообщений.

Архитектура

外部 Agent（ZCode / Claude Code）           dev 脚本（tteval / ttdiag / regress）
      ↕  MCP over stdio                           ↕  agent 角色直连（ws + JSON）
bridge server（Node，仅监听 127.0.0.1，token 鉴权，支持常驻 daemon）
      ↕  WebSocket（扩展/agent 主动连出，多 agent 并存）
TauriTavern 扩展「TT Agent Bridge」
      ├─→ window.__TAURITAVERN__.api   检测：日志 / 世界书激活 / LLM 请求 / 聊天搜索 / console 捕获
      └─→ SillyTavern.getContext()     操作：STScript / 变量 / 消息 / 事件

• Единый источник истины контракта протокола: src/core/protocol.ts (bridge импортирует напрямую, не копировать).

• Расширение использует только публичные границы (ABI хоста TT + публичные члены вышестоящего getContext()), не касаясь внутренних модулей.

• bind-or-attach: при запуске MCP-сервера, если на порту уже есть живой hub (daemon) с тем же токеном, сервер автоматически монтируется как агент — множественные MCP-клиенты больше не конфликтуют за порт.

Related MCP server: macOS Companion MCP Server

Установка расширения (в TauriTavern)

1. Откройте TauriTavern → верхний抽屉 «Расширения» → Управление расширениями → Установить расширение

2. Введите Git-адрес этого репозитория (TauriTavern принимает только анонимные https Git-remote), например: https://github.com/<你的用户名>/tt-agent-bridge.git

3. После установки в правом нижнем углу появится статус-бейдж «Bridge» (зеленеет после принятия hello)

Ручное размещение каталога (data/extensions/third-party/tt-agent-bridge/) тоже возможно, но рекомендуется установка через Git для последующих обновлений. Внимание по обновлению: версия протокола развивается вместе с репозиторием (сейчас v2); расширение и bridge выпускаются из одного репозитория — после подтягивания нового репозитория нужно одновременно обновить расширение внутри TT (Git-обновление или синхронизация dist/ + manifest.json с последующей перезагрузкой страницы), иначе расширение будет отклонено с ошибкой 4003 (красный бейдж, периодические повторы).

Запуск

Рекомендуется: постоянный daemon (расширение держит длинное соединение, скрипты/MCP монтируются за секунды, больше не нужно ждать переподключения расширения каждый раз):

cd bridge
npm install
npm run daemon -- --port 18789 --token <你的token>   # 或 TTAB_PORT / TTAB_TOKEN 环境变量

Или запустить MCP-сервер напрямую (при отсутствии daemon — автоматический bind; при наличии daemon — автоматический attach):

npm run start                          # 随机 token，打印在 stderr，并写入 .bridge-token
# 或固定 token：
npm run start -- --port 18789 --token <你的token>

Парный токен

Нажмите на бейдж Bridge в правом нижнем углу TT → вставьте токен (token: ... из логов запуска сервера) → нажмите «Переподключить» → бейдж стал зелёным, значит соединение установлено. При отклонении токена (4001) расширение сохраняет медленный повтор в течение 30 секунд и самовосстанавливается после исправления токена.

Подключение к агенту (ZCode / Claude Code)

Регистрация через stdio MCP (примеры команд, адаптируйте под синтаксис вашего клиента):

zcode mcp add tt-agent-bridge -- npm run start --prefix <bridge目录绝对路径>

Обзор MCP-инструментов (21)

Диагностические (чтение)

Операционные (запись)

Отладочные

Локальные для bridge

Типичные сценарии отладки (таверн-карточки)

1. Пустой статус-бар / переменные не читаются: tt_mvu_stat — проверить, существует ли stat_data → tt_iframes — найти frame статус-бара → tt_eval frame=TH-message--0--2 — внутри iframe посмотреть getAllVariables() и DOM → tt_console_capture {enabled:true}, затем tt_logs kind=frontend — увидеть ошибки (SyntaxError чаще всего из-за двойного декодирования HTML-сущностей).

2. Интерактивность сломана (таб не нажимается / кнопки не реагируют): в tt_eval frame=... читать исходники скриптов, проверить монтирование Vue (el.__vue_app__), имитировать клики через dispatchEvent для контрольных экспериментов.

3. World Info не срабатывает: tt_worldinfo_last — посмотреть пачку активаций → tt_llm_logs raw — увидеть, что реально попало в промпт → tt_worldinfo_open — перейти сразу к нужной записи.

4. Проверка после редактирования карточки: tt_exec_stscript — запустить перезагрузку через /go → tt_read_messages — проверить отрисованный результат.

5. Аудит структуры карточки: tt_get_character section=regexes|scripts|character_book — читать встроенные компоненты по секциям, не заливая в контекст MB-размерный JSON всей карточки.

dev-скрипты (bridge/scripts/)

Границы безопасности

• WS слушает только 127.0.0.1; рукопожатие обязательно с токеном (--token / TTAB_TOKEN, по умолчанию генерируется случайно).

• Нет произвольного файлового/командного проксирования — файловые операции агент выполняет своими локальными инструментами.

• Операции записи и tt_eval помечены как destructive; решение подтверждает агент.

• Токен хранится в открытом виде в localStorage расширения и в .bridge-token bridge — оба файла локальные.

Известные ограничения

• Текст /send передаётся с экранированием через пайп; при экстремальных символах — fallback через tt_eval с прямым управлением контекстом.

• set_variables scope=global зависит от поведения сериализации объектов в /setvar scope=global.

• В режиме attached tt_poll_events содержит только события после attach (исторические события — в ring buffer daemon, через MCP attach-путь не воспроизводятся); extConnected в tt_bridge_status — снимок на момент attach.

• context.characterId в TauriTavern по факту — числовая строка (в вышестоящем ST — number), bridge внутренне это учитывает.

• При смерти daemon вызовы attached MCP-сервера завершаются ошибкой (сообщение явно указывает перезапустить daemon), автоматического отката к bind нет.

Разработка

npm install && npm run build     # 构建扩展（typecheck + vite -> dist/）
cd bridge && npm install         # bridge 依赖
cd bridge && npm run typecheck   # bridge 侧类型检查

Корень репозитория — это и есть расширение (manifest.json + dist/), артефакты сборки dist фиксируются в репозитории, TT после Git-установки загружает их напрямую; после изменения исходников выполните npm run build и закоммитьте — обновление расширения в TT сможет подтянуть изменения.