sillytavern-api-reference

SillyTavern API 参考

通用沟通规范

遵循 TW plain-language and guidance rules：首次使用术语时解释其含义，采用用户选择的「新人／入门／熟练／老手」级别，并在每个级别说明必要的更改和错误。灵魂模式和文风模式都不能禁用这项基准规范。

插件运行时

当此 Skill 通过插件、云主机或远程机器运行时，进入时阅读 the plugin execution contract，并在执行特定主机的命令前应用其中关于主机、工具和持久化的检查。遵守此 Skill 的范围、授权和验收门槛。

使用 $consult-tavernweave-library 的 sillytavern-api-reference 路由，查找最精简且相关的 ST 指南集，然后针对已确认的目标版本核实确切符号。指南路由仅作为导航依据，不能替代已安装的运行时或固定版本的源代码。只有当任务具备写入能力时，才添加 A0。

使用此 skill 查找目标运行时的权威 API 来源。不要将其视为不断演进的 API 的固定规范。references/core-facts.md 中的公开基准是带日期的导航快照，并不声称描述最新版本。目标运行时始终具有权威性。

对于世界书／模板入口、明确的读取、消息窗口或状态到提示词的契约，请使用 E03 version verification。 该文档将固定版本源代码的发现与尚未验证的目标主机分开记录；只加载所选机制所需的检查项。

确定运行时接口

在选择 API 之前，对每项请求的操作进行分类：

接口	用途	主要权威来源
SillyTavern 核心	主机上下文、原生事件、渲染和扩展 API	与已安装 SillyTavern 版本对应的源代码和文档
Tavern Helper / JS-Slash-Runner	消息、变量、生成、注入、世界书和 iframe 助手	与已安装扩展对应的声明和文档
STScript	斜杠命令管线、闭包、Quick Replies 和作用域变量	正在运行的 SillyTavern 实例提供的命令帮助，或对应的命令参考
宏	提示词阶段的替换和简单变量访问	正在运行的 SillyTavern 实例提供的宏帮助，或对应的宏参考
ST-Prompt-Template	EJS 求值和提示词模板功能	已安装的扩展版本及其上游文档
MVU / MagVarUpdate	结构化的 stat_data、更新解析、替换和生命周期事件	已安装的 MVU 全局对象、对应的声明和上游源代码

不要仅仅因为存在名称相似的全局对象，就将某个接口的符号用于其他接口。

验证工作流

1. 记录目标版本和功能。在 Tavern Helper 上下文中，优先使用 getTavernVersion() 和 getTavernHelperVersion()。使用 typeof、Object.keys 或有文档说明的初始化辅助函数探测可选集成。

2. 确认每个依赖由宿主提供、嵌入卡片中，还是从远程加载。不要根据导入的辅助函数或全局符号推断安装要求。

3. 根据这些版本查找权威来源。优先查阅运行时源码或官方版本化文档，其次是匹配的声明，最后是 references/core-facts.md 中的公开互操作性索引。

4. 照录确切的符号拼写、参数形式、返回类型、事件常量或命令语法。切勿凭记忆还原。如果请求未提供具体符号或已安装版本，请在给出确切值或签名之前停止。询问钩子和运行时身份；不要主动提供来自持续变动分支的示例，并将其当作对目标运行时问题的回答。

5. 在版本敏感的工作旁按以下简洁格式记录来源：

   symbol: updateWorldbookWith
   surface: Tavern Helper
   applies_to: detected extension version or declaration snapshot
   provenance: public upstream URL plus commit/path, or identified runtime source
   confidence: high | medium | low
   runtime_check: performed check, or reason it remains pending
   

6. 实现支持范围最窄的 API，并添加功能不可用时的处理。不要悄然回退到宿主私有 DOM、已弃用 API 或不同的持久化作用域。

7. 在预期上下文中验证调用。在浏览器控制台中探测，并不能证明同一个全局变量也存在于消息 iframe、脚本 iframe、提示词模板或 STScript 流程中。

置信度规则

• 高：从匹配的运行时源码、官方版本化文档或声明中读取到的确切事实，并已在目标运行时中交叉验证。
• 中：仅有声明、仅有变更日志、仅有单一来源或与目标版本相邻的事实。添加功能探测或真实运行时测试。
• 低：推断得出、存在冲突或未经版本确认的事实。不要据此实现；应先解决冲突。

main、release 或 beta 等持续变动的分支名称不能作为版本标识。如果仅用于导航，应明确标注。任何包含确切事件值或回调签名的示例，都必须引用不可变提交或匹配的已安装源码，且不得作为对不同运行时或身份不明的运行时问题的回答。

区分声明所能证实的内容与运行时实际观察到的内容。声明可以确定拼写和名义类型，但无法验证回调时机、生命周期、副作用或实际可用性。

实现规则

• 如果 Tavern Helper 封装能提供所需操作，优先使用它。只有在核心状态或 API 未被封装覆盖时，才使用 window.SillyTavern.getContext()。
• 只有在确认已安装版本后，才能将注入的全局函数和 window.TavernHelper 属性视为同一辅助接口的两种访问方式。
• 优先使用当前的 WorldbookEntry API 系列：getWorldbook、replaceWorldbook、updateWorldbookWith、createWorldbookEntries 和 deleteWorldbookEntries。不要在新代码中引入已弃用的 lorebook 条目 API。
• 优先使用更新函数或条目级辅助函数，而非替换整个对象。保留未知字段、条目标识、无关的用户内容，以及预期的聊天／角色／全局作用域。
• 区分 generate 和 generateRaw：后者会提供自己的有序提示词。不能假定两者会创建常规聊天轮次，也不能假定会自动运行 MVU 解析。
• 明确处理消息楼层和 swipe。需要考虑备用页面时，使用 include_swipes: true 读取，并在写入后选择范围最小的 refresh。
• 使用前等待可选的全局对象（如 Mvu）。订阅时使用导出的事件常量，尤其是在上游字符串值存在历史拼写错误的情况下。
• 不要仅凭 API 标识符推断提供方、安装状态或交付类别。追踪实际的卡片脚本、导入、清单声明和运行时注册路径。
• 将打包的国内版／全球版 MVU Zod 脚本视为卡片资源，其存在状态和启用状态必须符合卡片约定。将这些脚本导入的 Git/CDN 模块视为远程交付。不要用独立的 Zod 安装说明替代这条打包加载路径。
• 将远程导入视为运行时交付，而非安装或执行的证明。记录其 URL/ref、回退方案和就绪状态探测。
• 保留宏用于替换。会写入变量的宏可能在预览、切换 swipe 或重新渲染时运行；时序重要时请使用显式事务。
• 严格按照文档保留 STScript 管道值、命名参数语法、引号和闭合分隔符。/send 会添加消息，但本身不会触发生成。
• 当监听器、提示词注入、计时器和共享接口的生命周期可能超出当前操作时，添加清理逻辑。
• 切勿在日志或示例中暴露 API 密钥、身份验证数据、扩展设置或私密聊天内容。

解决分歧

来源不一致时：

1. 确认它们描述的是同一接口和版本。
2. 优先采用目标运行时实现，而非指南或声明。
3. 对于精确拼写，优先采用原始声明或命令／宏参考，而非叙述性摘要。
4. 如果行为仍不明确，应降低置信度，并提供最小化的运行时探测方案。
5. 说明尚未解决的事实，不要把猜测的代码片段说成可直接运行。

输出约定

对于依赖 API 的回答或补丁：

• 列出所有运行时或扩展依赖项；
• 说明每项依赖由宿主提供、嵌入卡片、远程加载、可选、区域限定，还是仅供开发使用；
• 说明检测到或假定的版本；
• 指明每个敏感符号所依据的确切权威来源；
• 提供适用于正确执行上下文的代码；
• 标注仍需进行的能力探测或真实运行时检查；
• 不要声称静态检查能证明消息创建、事件时序、iframe 访问或 MVU 持久化。

如果用户未提供足够的身份信息，无法确定具体的 API 问题，正确的输出应是简短的证据请求和安全的运行时探测方案。不要用未注明版本的精确签名来充篇幅。