TT Agent Bridge

外部 CLI agent（ZCode / Claude Code など）が MCP 経由で TauriTavern を直接操作できるようにする: 実行時データ（チャット / 変数 / ワールドブック発動 / ログ / LLM リクエスト原文 / iframe ステータスバーの実行時）の読み取り、操作の実行（STScript / メッセージ送信 / 変数書き込み / キャラクター切替 / ワールドブック項目ジャンプ）、およびメインドキュメントまたはメッセージ iframe 内で任意の JS を実行して Tavern カードを診断する。

アーキテクチャ

外部 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 が直接 import する。コピーしないこと）。

• 拡張機能は公開された境界のみを使用する（TT ホスト ABI + 上流の getContext() 公開メンバー）。内部モジュールには触れない。

• bind-or-attach: MCP server 起動時にポート上に同一 token の生存 hub（daemon）が既にある場合、自動的に agent としてマウントする——複数 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 server を直接実行（daemon がない場合は自動的に bind、daemon がある場合は自動的に attach）:

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

token のペアリング

TT の右下隅にある Bridge バッジをクリック → token を貼り付ける（server 起動ログ内の token: ...）→「再接続」をクリック → バッジが緑色になれば接続成功。token が拒否された場合（4001）は、拡張機能が 30 秒の低速再試行を継続し、token を修正すれば自己回復する。

agent への接続（ZCode / Claude Code）

stdio MCP 方式で登録する（コマンド例。お使いのクライアントの構文に合わせて調整）:

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

MCP ツール一覧（21 個）

検出系（読み取り）

操作系（書き込み）

デバッグ系

bridge ローカル

典型的な debug シナリオ（Tavern カード）

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. 操作が反応しない（tab がクリックできない / ボタンが無反応）: tt_eval frame=... 内でスクリプトのソースコードを読み、Vue のマウント（el.__vue_app__）を確認し、dispatchEvent でクリックをシミュレートして対照実験を行う。

3. ワールドブックが反映されない: tt_worldinfo_last で発動バッチを確認 → tt_llm_logs の raw で prompt に実際に何が組み込まれたかを確認 → 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 が必須（--token / TTAB_TOKEN、デフォルトはランダム生成）。

• 任意のファイルシステム / コマンドのプロキシは行わない——ファイル操作は agent がローカルツールで行う。

• 書き込み系と tt_eval は destructive と明記され、agent 側の確認ポリシーに依存する。

• token は拡張機能の localStorage と bridge の .bridge-token に平文で保存される。いずれも本機のファイルである。

既知の制限

• /send のテキストはパイプ経由でエスケープして渡される。極端な文字を含む場合は tt_eval で context を直接操作してフォールバックする。

• set_variables scope=global は /setvar scope=global のオブジェクトシリアライズ動作に依存する。

• attached モードでは tt_poll_events は attach 以降のイベントのみを含む（履歴イベントは daemon の ring buffer にあり、MCP attach 経路では再生されない）。tt_bridge_status の extConnected は attach 時点のスナップショットである。

• TauriTavern の context.characterId は実測すると数字文字列（上流の ST は number）であり、bridge 内部では互換対応済み。

• daemon が死んだ場合、attached の MCP server 呼び出しは失敗する（エラーメッセージが 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 の拡張機能更新で取得できる。