TT Agent Bridge

让外部 CLI agent（ZCode / Claude Code 等）通过 MCP 直接操作 TauriTavern：读取运行时数据（聊天 / 变量 / 世界书激活 / 日志 / LLM 请求原文 / iframe 状态栏运行时），执行操作（STScript / 发消息 / 写变量 / 切角色 / 跳世界书条目），以及在主文档或消息 iframe 内跑任意 JS 诊断酒馆卡。

架构

外部 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 场景（酒馆卡）

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 的扩展更新拉取。