TavernHelper是 SillyTavern 第三方扩展JS-Slash-Runner（酒馆助手）提供的核心编程接口：通过一个全局window.TavernHelper对象，你的脚本就能自由读写角色卡、聊天记录与预设，还能监听酒馆事件、注入临时提示词、直接调用 AI 生成。本文是一份面向新手的完整使用手册，带你从安装到函数速查，逐步掌握它的全部能力。

⚠️ 执行自定义 JavaScript 代码可能带来安全风险（如窃取 API 密钥、破坏设置），请务必只运行来源可信、自己看得懂的脚本（详见 README.md 开头的警告）。

一、什么是 JS-Slash-Runner（酒馆助手）？

SillyTavern 默认不允许用户直接执行 JavaScript 代码。JS-Slash-Runner 的解决办法很巧妙：它在酒馆内嵌入了一个隔离的 iframe 沙箱，让外部脚本在里面运行，再通过一层封装把酒馆内部能力"安全地"暴露出来——这一层封装就叫TavernHelper🛠️。

几个关键事实（来自 manifest.json）：

换句话说：装上这个扩展后，你的脚本里所有TavernHelper.xxx()调用，都是对酒馆底层 API 的合法、受控访问。所有对外暴露的函数都在 src/function/index.ts 的getTavernHelper()中注册，这也是全文速查表的"总目录"。

二、TavernHelper 快速上手：3 步开始调用

1. 启用扩展并打开脚本面板

在 SillyTavern 设置中启用"酒馆助手"，打开它的扩展面板（入口在 src/Panel.vue），即可创建/管理脚本。脚本运行在一个独立 iframe 中，相关加载逻辑见 src/iframe/script_url.ts。

2. 在脚本里调用函数

脚本中直接使用TavernHelper即可，例如在控制台或脚本中读取当前角色：

// 获取当前角色卡名称与 id console.log(TavernHelper.getCurrentCharacterName()); console.log(TavernHelper.getCurrentCharacterId());

3. 在控制台自检接口

按F12打开浏览器控制台，输入window.TavernHelper，即可展开查看当前版本提供的所有接口——这是官方类型文件 @types/iframe/exported.tavernhelper.d.ts 里明确推荐的自查方式。

三、核心功能①：读写角色卡（Character）

角色卡管理函数位于 src/function/character.ts，全部异步（返回 Promise）。

查询类（读）

修改类（写）

示例：用updateCharacterWith给当前角色追加一条开场白：

await TavernHelper.updateCharacterWith('current', char => { char.first_messages.push('新的开场白……'); return char; });

角色卡的完整数据结构（description、first_messages、extensions 等）定义在 src/function/character.ts；如果你手里有原始 JSON 卡，还可以直接用importRawCharacter（见 src/function/import_raw.ts）批量导入。

四、核心功能②：读写聊天记录（Chat Messages）

聊天消息管理位于 src/function/chat_message.ts，是最常用的一组函数。

读：getChatMessages(range, options)

• range支持单个编号、区间字符串（如'0-9'），负数表示从末尾倒数；
• options可按role（system / assistant / user）、hide_state（是否隐藏消息）、include_swipes（是否带回滚页）过滤。

// 取最后 3 条普通（非隐藏）消息 const msgs = TavernHelper.getChatMessages('-3-1', { hide_state: 'unhidden' });

写：五个"增删改"函数

示例：把最后一条消息改写为新的内容：

await TavernHelper.setChatMessages([ { message_id: TavernHelper.getLastMessageId(), message: '改写后的内容……' }, ]);

写操作完成后，酒馆界面会自动刷新并保存，无需手动触发。

五、核心功能③：读写预设（Preset）

预设管理位于 src/function/preset.ts。预设包含三部分：settings（温度、top_p、最大上下文长度等采样参数）、prompts（提示词模板各段落）、extensions（扩展数据），完整类型见 src/function/preset.ts。

常用函数一览

示例：把"当前正在使用"的预设的温度调成 0.8：

await TavernHelper.updatePresetWith('in_use', p => { p.settings.temperature = 0.8; return p; });

注意：'in_use'是一个特殊名字，代表"正在使用的预设本身"，getPreset('in_use')、updatePresetWith('in_use', ...)都可以直接作用于它。

六、进阶能力：这些函数同样实用 🚀

除三大主角外，window.TavernHelper还暴露了以下能力（均在 src/function/index.ts 注册）：

1. 事件监听：让脚本"感知酒馆"

事件函数定义在 src/function/event.ts，类型声明在 @types/iframe/event.d.ts：

// 监听"收到消息"事件，弹出提示 TavernHelper.eventOn(TavernHelper.tavern_events.MESSAGE_RECEIVED, () => { console.log('收到新消息！'); });

• eventOn持续监听、eventOnce只触发一次、eventMakeFirst/Last调整执行顺序；
• 事件分两类：tavern_events（酒馆原生事件，如MESSAGE_UPDATED）与iframe_events（扩展内部事件），还支持自定义字符串事件+eventEmit广播，实现脚本间通信。

2. 注入临时提示词（injectPrompts）

inject.ts 提供injectPrompts(prompts)：往当前聊天里注入 system/user/assistant 提示，支持once: true让它在一次生成结束后自动移除——非常适合"只对本次回复生效"的临时指令场景。

3. 直接调用 AI 生成

src/function/generate/index.ts 暴露了generate（走酒馆完整流程）与generateRaw（裸调 OpenAI 兼容接口），以及getModelList（查询模型列表）、stopGenerationById/stopAllGeneration（停止生成）。

4. 其它值得了解的工具

七、新手避坑指南：5 个常见问题

1. 函数都是异步的：createCharacter、setChatMessages等返回 Promise，请记得await，否则数据可能还没写进酒馆。
2. 'current'是魔法值：角色卡、人格相关函数都支持传'current'表示"当前角色"，无需自己先查 id。
3. 优先用updateXxxWith系列：先读后写的原子操作，避免"读出来改到一半被覆盖"。
4. 不要直接改酒馆内部对象：一律走TavernHelper，它会自动处理保存与界面刷新；绕过它直接操作会导致状态不同步。
5. 旧版 API 已废弃：如setChatMessage（请用setChatMessages）、eventOnButton（请用eventOn(getButtonEvent(...))），编写新脚本时请使用新函数。

八、总结

TavernHelper 把 SillyTavern 最核心的三大对象——角色卡、聊天记录、预设——变成了几行 JavaScript 就能读写的标准 API，再配上事件系统、临时提示词注入与 AI 生成接口，足以支撑绝大多数"我想让酒馆自动做点什么"的需求。

建议的学习路径：先读本文第三、四、五节的三大主功能，再到控制台输入window.TavernHelper亲手试两个函数，最后以 src/function/index.ts 为索引深入各模块源码。祝你玩得开心！🎉