sillytavern-runtime-debug

SillyTavern 运行时调试

共享沟通规范

遵循 TW plain-language and guidance rules：首次提及术语时加以解释，保持用户选择的新人／入门／熟练／老手级别，并在每个级别说明必要的更改和错误。灵魂模式和文风模式都不能取消这项基准要求。

插件运行时

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

使用 $consult-tavernweave-library 的 sillytavern-runtime-debug 路由，获取相关主机和部署指导。任何写入或主机变更之前都要添加 A0，并将回忆的指南建议与从具名的真实 SillyTavern 实例中收集的证据分开。

使用来自真实目标 SillyTavern 实例的证据，关闭运行时错误。离线 HTML 预览可用于辅助开发，但无法证明导入行为、消息渲染、扩展注入、iframe 访问、事件时序、持久化或 MVU 更新。

对于世界书选择以及状态到下一次请求的行为，请使用 E07 isolated checks and observation records。 从纯文本轮次开始，只添加选定的模板／MVU／UI 测试用例； 打包的静态夹具和回执验证器都无法证明真实主机上的成功。

负责运行时边界

负责实时复现、浏览器执行、直接运行时证据和验收闭环。不负责嵌入式 UI 设计或源代码实现。

如果实时测试发现 UI 源码缺陷，请向 sillytavern-embedded-ui 报告最简复现步骤、故障层级和所需验收标准。收到重新构建的产物后，验证其确切修订版本，并按需重新导入，然后继续执行同一套运行时测试矩阵。绝不能仅凭 UI 技能的离线或静态证据结束运行时验收。

使用驱动能力契约

使用任何能够安全提供所需能力的可用浏览器驱动：应用内浏览器、已连接的用户浏览器、Playwright、WebDriver 或 CDP。不要将工作流绑定到某个产品或工具前缀。

开始前，确认驱动能够执行测试所需的操作：

• 打开或连接到目标 SillyTavern 页面；
• 检查顶层文档并枚举框架；
• 收集带框架上下文的控制台错误和警告；
• 在顶层文档和选定的同源框架中执行只读 JavaScript；
• 检查属性、文本、几何信息和计算样式；
• 点击、输入、选择、滚动和按键；
• 更改视口大小或模拟窄屏布局；
• 在视觉证据有帮助时截取屏幕截图。

如果缺少某项能力，请调整测试或说明这一限制。绝不要假装屏幕截图能够证明控制台状态，也不要假装顶层框架的求值能够证明 iframe 状态。

验证实时开发链路

当项目使用源文件监视器和 Tavern Helper 实时编辑功能时，应分别验证每个环节：

source edit -> successful rebuild -> expected development output changed
            -> listener connected -> intended iframe reloaded -> new behavior observed

从 sillytavern-card-pipeline 获取监视器命令、输出路径和重新构建回执。根据已安装的 Tavern Helper 版本检测监听器控制项和连接状态；不要假定其他版本中的设置标签、URL 或端口适用。然后：

1. 捕获当前输出标识和目标 iframe 标识；
2. 等待源文件编辑后成功重新构建；
3. 观察监听器触发的重新加载，或执行已声明的手动刷新／重新绑定回退方案；
4. 使用制品标识、框架替换、项目提供的修订标记或其他直接信号，确认当前运行的就是重新构建后的输出；
5. 从重新加载后的运行环境收集控制台、DOM、交互和数据证据。

如果编译失败或监听器断开连接，页面可能仍在运行之前成功构建的制品。应报告这一过期制品边界，而不是将新源文件视为已测试。实时重新加载可以加快迭代，但不能替代发布验收：应针对确切的生产构建制品，使用新的导入、聊天或绑定（如果功能生命周期有此要求）重新执行所选矩阵。

确立测试边界

复现前记录：

• SillyTavern 版本和相关扩展版本；
• 目标角色／卡片标识和制品修订版本；
• 已声明的主卡片类型、能力标志、运行时依赖清单和所选区域加载器；
• 当前聊天标识、选定的开场轮次和消息数量；
• 浏览器、视口、缩放比例、配色方案和设备类别；
• 制品是刚导入的，还是已存在；
• 哪些操作可能会更改聊天、世界书、变量、设置或账户状态。

不要假定安装路径、端口、启动配置、账户状态、角色文件位置或 iframe ID。应从当前运行环境中查明。不要记录 API 密钥、Cookie、身份验证数据或扩展私有设置。

更改前先复现

1. 在需要保留状态时，从用户报告的状态开始。
2. 操作前捕获最简控制台基线。
3. 每次只执行一个可复现的操作。
4. 捕获可见结果、DOM 状态、计算样式、框架状态和新增的控制台输出。
5. 再重复一次，以区分确定性故障与时序或过期状态行为。

对于依赖导入的代码，应确认加载的是确切的构建制品。优先使用 SillyTavern 导入界面或其他经用户授权且可逆的途径。不要将覆盖安装数据目录中的文件作为默认调试方法。

当新制品或绑定脚本应生效时，除非该功能明确支持对现有聊天重新绑定，否则应使用新聊天进行测试。旧消息 DOM、缓存脚本、开场页面守卫和持久化设置都可能掩盖测试结果。

绘制运行时映射

建立简明的框架和所有权映射，而不是猜测选择器：

top SillyTavern document
  -> chat message container and rendered message body
  -> message-owned iframe, if present
  -> long-lived Tavern Helper script iframe, if present
  -> card-created nested iframe, if present
  -> host-mounted control panel or popup, if present

对每个框架，记录其稳定标识证据、来源、可访问性、所属消息或脚本，以及相关全局变量。优先使用语义化或 data-* 选择器。将生成的 ID、消息索引和框架顺序视为不稳定因素。

使用带保护的同源访问：

function readableFrame(frame) {
  try {
    return frame.contentWindow && frame.contentDocument
      ? frame.contentWindow
      : null;
  } catch {
    return null;
  }
}

如果是跨源访问，请在支持的情况下将驱动程序切换到该框架，或使用其文档说明的桥接方式。不要为了方便检查而削弱沙盒或安全控制。

分层诊断

沿着故障链，从最早可观测的输入一直追踪到最终 UI：

artifact/import
  -> card fields and regex
  -> message text and rendering
  -> Tavern Helper or extension frame
  -> optional global initialization
  -> variable/worldbook/message data
  -> DOM binding and event refresh
  -> layout, interaction, and persistence

导入与制品

• 确认导入的角色与预期名称、版本和载荷修订版一致。
• 重新盘点导入制品中的角色本地正则表达式和 Tavern Helper 脚本。确认所有必需的架构、加载器、绑定、世界书和宿主扩展都存在，并已根据声明的策略启用。
• 确认区域替代组中预期的成员已启用，且没有意外的双重激活。
• 测试首条消息、备用问候语或挂载行为时，请使用新聊天。
• 区分重建失败和导入制品过时。

运行时依赖与远程加载器

• 在正确的框架和作用域中探测每个 host_required 扩展或能力。打包的脚本并不能证明其宿主存在。
• 检查卡片承诺的每个已打包国内版／全球版 MVU Zod 脚本，并确认其启用状态与清单或打包基线一致。然后确认所选脚本的远程模块和架构注册辅助程序确实在 Tavern Helper 上下文中执行。不要擅自安装软件包或替换为其他提供方。
• 对于 remote_runtime，记录请求的 URL／ref、主要／备用尝试、网络故障、模块异常以及预期的就绪能力。
• 将 HTTP 成功仅视为传输证据。确认模块已执行，并发布了预期的全局变量、注册信息、DOM 标记、事件或其他就绪信号。
• 对于国内版／全球版或其他 regional_alternative 加载器，测试所选成员及其声明的备用项。不要仅为通过测试而同时启用两者。
• 不要在玩家设置和运行时故障报告中纳入 development_only 软件包。

控制台与异常

• 捕获顶层文档和相关框架中的错误与警告。
• 记录最先发生的根因错误，而不只是后续的空引用噪声。
• 按消息、堆栈、框架和时间去重重复的框架钩子输出。
• 保留被拒绝的 Promise、CSP 故障、网络错误和语法错误。

DOM 与样式

• 检查实际目标元素、其祖先元素及其所属框架。
• 比较原始 class 令牌、稳定属性、计算后的显示／位置／大小／溢出属性，以及边界矩形。
• 检查 SillyTavern 的消息净化或类名命名空间处理是否更改了静态内容。
• 请注意，在宿主净化流程之后注入的 DOM，可能不会像静态消息 HTML 那样进行相同的类转换。
• 测试长文本、空数据、隐藏状态、嵌套滚动和弹出层裁切。

运行时数据

• 按文档规定的初始化流程等待可选的全局变量。
• 读取精确的目标作用域：当前消息、最新消息、聊天、角色、脚本或全局作用域。
• 对于 MVU，检查目标消息层级上的 stat_data，并观察生命周期事件，而不是假定写入已经完成。
• 对于世界书，变更后重新读取目标世界书和绑定；不要仅凭提示消息推断操作成功。

交互

• 测试真实的指针／键盘操作，而不只是直接调用方法。
• 验证焦点移动、禁用状态、防重复提交机制、退出／关闭行为以及输入内容保留情况。
• 聊天切换、滑动、编辑或重新渲染后，验证监听器和单例挂载既不会消失，也不会重复。

使用可撤销的运行时原型

临时 DOM 或 JavaScript 原型有助于隔离问题原因。请明确将其限定为诊断用途：

• 确保变更幅度小且可撤销；
• 准确记录注入或更改的内容；
• 除非测试需要且用户已授权，否则不要写入持久化用户数据；
• 移除临时 ID、监听器、样式和值，或重新加载页面；
• 绝不要将原型视为最终交付的修复。

修复源代码后，重新构建并导入制品，然后在不含原型代码的干净运行时状态下重新复现问题。

处理长时间操作和超时

将长时间操作拆分为执行和观察阶段：

1. 发起一项操作；
2. 等待驱动调用返回或超时；
3. 轮询开销较低的只读标记，例如聊天身份、消息数、挂载状态或就绪状态；
4. 根据观察到的状态判断是否成功，而不是仅依据原始调用的返回状态。

驱动调用可能在副作用已成功后才超时。反之，调用已返回也不能证明渲染或持久化已经完成。

验收矩阵

选择与本次更改相关的行，并记录通过／失败的证据：

维度	所需证据
导入	已选中预期构件，且其脚本、正则表达式和绑定均存在
依赖项	主机能力、内嵌要求、远程执行和区域选择均符合清单
新建聊天	无需手动注入，首条消息或开场挂载内容即会出现
控制台	没有新增的因果错误或未处理的拒绝
DOM	元素数量、归属和属性正确，且没有重复挂载
样式	计算后的尺寸、显示方式、溢出和类名转换均正确
交互	点击、键盘、表单、关闭和重复操作均产生预期状态
数据	更改了正确的楼层／作用域；重新读取可确认持久化，且无关数据保持不变
生命周期	重新加载、滑动、编辑、切换聊天和重新渲染均不会导致行为泄漏或丢失
响应式	窄视口和宽视口均能正常工作；较长的中日韩文本和控件不会被裁切
安全	不可信文本保持惰性；不会暴露机密或私有配置

只有当源代码构建的构件通过所选的真实 SillyTavern 检查后，运行时工作才算完成。报告中可以将离线测试作为辅助证据，但不能用其替代真实检查。

消息内容页面和 MVU 显示

对于消息内容页面， 应沿着消息文本、挂载、解析和可见内容，追踪实际输出规则与接收对象。选择涵盖 周围文本、边界缺失或不完整、重复项目以及惰性模型文本的测试案例。检查按钮是本地 导航，还是经授权的发送操作。如果消息创建成功但生成失败，应验证重试不会重复发送玩家消息。

对于 MVU 状态栏， 应验证实际楼层／作用域、事件驱动的刷新和生命周期清理。根据字段语义比较显示的零、 false、空值和无效值。检查集合更改和已移除的选项，同时保留适当的视图状态。 只读刷新不得初始化、修复或写入游戏状态。请使用已声明的测试作用域和获准使用的数据； 不要为了构造测试案例而修改真实存档。

仅使用与已更改构件相关的测试案例。记录观察到的布局，并与共用的 前端质量标准 进行对照；不要将与参考站点的比较视为主机验收。协议或 UI 缺陷应交由其实现负责人处理； 不要用打补丁的控制台副本替代受维护的构件。

报告

请提供：

• 最小复现步骤；
• 出错层级和根本原因，并附直接证据；
• 版本、构件身份、浏览器和视口；
• 检测到的卡片类型／能力，以及内嵌、主机、远程、区域、可选和仅开发依赖项的状态；
• 如需更改 UI 源码，提供实现交接信息，以及重建／导入后的构件状态；
• 已通过的检查；
• 因设备、账号、扩展或驱动能力不可用而仍受阻的检查。