sillytavern-embedded-ui

SillyTavern 嵌入式 UI

共享沟通规范

遵循 TW 简明语言与指导规则：首次使用术语时加以说明，保持用户选择的新人/入门/熟练/老手级别，同时在每个级别都说明必要的改动和错误。灵魂模式和文风模式都不会停用这项基准要求。

插件运行时

如果此 Skill 通过插件、云主机或远程机器运行，请在入口处阅读插件执行契约，并在执行特定于主机的命令之前完成主机、工具和持久化检查。遵守此 Skill 的范围、授权和验收门槛。

设计或更改嵌入式界面前，请通过 $consult-tavernweave-library 使用 sillytavern-embedded-ui 路由。阅读 A0、最匹配的 UI/移动端指南，以及选定的设计/动效参考；在项目权威方采纳之前，每项参考均保持 proposed 状态。

将共享的前端设计质量标准作为默认设计要求。主动搜索并审视相关网页设计，根据作者意图制定独特方案，并通过视觉呈现布局。目标是达到 Awwwards 级别的质量；整洁的构图和实用的文案是必需项，而非可有可无的灵感。避免装饰性微文案和重复的英文说明，同时保留作者使用的语言及真实的功能标签。完整工作流和证据限制请参阅共享参考。

根据 rolecard 的实际生命周期，构建最精简且易于维护的界面。以语义化 HTML、CSS 和 JavaScript 作为可移植的基线。仅当现有项目已采用某个框架，或交互复杂度明显足以证明其合理性时，才使用该框架。

由你自行制定方案，不要要求作者填写技术问卷。一个连贯的设计就足够；不要凭空制造选项，也不要重新讨论已批准的决定。继续进行已获授权的工作，仅针对尚未解决且影响重大的选择提问。可选工作表用于记录 Agent 的工作，也可以用等效的项目记录替代。

自主管理实现边界

此技能涵盖嵌入式 UI 设计、源代码实现或审查、辅助验证，以及交由运行时测试的验收标准。不要操作实时 SillyTavern 会话，也不要声称已通过此技能完成运行时验收。

如果需要在目标运行时中复现或验收行为，请将确切的构建产物和相关检查清单交给 sillytavern-runtime-debug。如果运行时检查发现 UI 源码缺陷，请在此恢复实现工作，重新构建，并将新版本的产物交回，以完成运行时验收。

确定界面类型

设计组件前，先选择界面类型：

界面	主要用途	生命周期
消息内容页	呈现由消息生成的内容，例如信件、日记或论坛	遵循目标消息及其渲染生命周期
开场页	呈现问候语，或选择／设置开场内容	遵循问候语；设置向导在成功提交后结束
状态栏 / HUD	在消息附近显示常查看的游戏状态	随消息／运行时生命周期重新创建或刷新
控制中心	管理设置、数据包、世界数据和高级操作	通常长期存在且为单例
弹出窗口 / 抽屉 / 模态框	聚焦于某个细节或决策，同时保留周边状态	临时存在，并有明确的打开和关闭行为

不要把少量可选问候语做成应用，也不要让状态栏承载控制中心的工作流。

对于由消息生成的页面，请阅读消息内容页，并在有帮助时使用其可选工作表。对于 MVU 只读显示，请阅读MVU 状态栏设计及其可选工作表。这些分支遵循相同的质量标准，但各自的内容来源必须保持独立。混合界面必须声明每条显示信息的来源；这并不意味着一定要新增卡片类型或状态系统。

设计前先检查

阅读现有 HTML、CSS、JavaScript、数据架构、正则表达式／挂载路径以及运行时所有权。记录：

• UI 的渲染位置：消息正文、Tavern Helper 框架、嵌套框架或宿主文档；
• 可信代码边界，以及所有不可信的用户／模型／远程值；
• 状态来源和作用域：草稿、本地 UI 设置、聊天、消息楼层、世界书或 MVU stat_data；
• 会重新创建 DOM 的生命周期事件；
• 值得复用的现有设计令牌、选择器和组件模式；
• UI 必须支持的最小桌面端和移动端容器尺寸。

在润色颜色或装饰之前，先检查结构和状态流。

明确状态归属

分离以下关注点：

data state       persisted game or configuration data
draft state      reversible, unconfirmed user input
UI state         active tab, open panel, focus, scroll, and transient errors
derived view     formatted values, counts, progress, and summaries

不要将标签页、折叠面板或滚动位置持久化到世界书或 MVU 中，除非它们本就是游戏内容的一部分。不要在每次编辑草稿时写入正式游戏变量。条件允许时，在数据刷新时保留用户控制的视图状态。

预览、验证和最终提交中出现的任何内容，都应使用同一个构建器。避免使用可能逐渐不一致的并行模板。

结构与样式

• 使用语义化控件：在支持的情况下，使用真正的 button、input、select、textarea、标题、列表和对话框。
• 为每张卡片或每项功能的 ID、存储键、自定义事件、CSS 变量和类添加命名空间。
• 使用稳定的 data-* 属性进行 JavaScript 绑定。将装饰性类视为样式，而不是业务协议。
• 使用精简的令牌层定义背景、文本、边框、强调色、间距、圆角和字号比例。
• 使用 box-sizing: border-box，为会收缩的 flex/grid 子项设置 min-width: 0，并采用可预测的内部滚动区域。
• 使用 repeat(auto-fit, minmax(...)) 等流式网格、可换行控件，以及 min()／max()／clamp() 限制。
• 避免使用超出窄消息容器的固定宽度。移动端不要只依赖 100vh 作为高度策略。
• 在 iframe 中，应根据 iframe 或组件容器进行判断，而非宿主窗口。当实际宽度不明确时，使用容器尺寸测量。
• 操作界面应紧凑但有条理。仅在真正的开场场景中使用主视觉级字号和视觉效果。
• 避免嵌套的卡片边框和过度模糊。使用 backdrop-filter 时，提供非模糊的备用方案。

以防御方式渲染数据

将所有用户、模型、软件包和远程内容视为不可信。

• 对文本值，优先使用 textContent 和 DOM 构建方式。
• 如果确实需要 HTML，应在插入前使用可信的运行时清理器进行清理，之后不要再修改清理后的字符串。
• 对插入 HTML 属性的所有值进行转义。验证 URL 协议和来源。
• 不要使用 innerHTML 插入模型输出。
• 规范化意外的 null、数组、对象、长字符串、缺失字段和未知枚举值。
• 限制进度值和尺寸；提供备用标签和颜色。
• 让较长的 CJK 文本和不间断文本按预期换行、折叠或滚动。
• 将格式错误或不受支持的数据显示为诊断状态，而不是悄然隐藏。

对于远程 UI，优先使用声明式 HTML 加可信的本地绑定器。强制使用 HTTPS 或可信的本地来源、超时、大小限制、完整性校验或版本固定、协议版本、必需节点验证和清理。拒绝远程脚本、嵌套框架、基础 URL 更改和自动表单，除非另有经过审核的设计要求。

生命周期和集成

• 通过运行时实际的就绪路径进行初始化，而不只依赖 DOMContentLoaded。
• 使绑定操作具备幂等性。应复用兼容的现有实例；替换不兼容的实例前应先销毁它。
• 为事件清理函数、观察器、计时器、fetch 中止控制器、临时 DOM、body 滚动锁和共享全局变量设置统一的清理路径。
• 检查访问父文档的能力，并使用 try/catch 包装跨框架访问。
• 等待 MVU 等可选集成就绪后，再读取其事件或数据。
• 明确读取预期的消息起始位置或持久化范围。
• 对事件驱动的刷新进行防抖，并防止并发渲染。
• 对动态列表优先使用事件委托。避免使用依赖模块作用域函数的内联处理程序。
• 保留无关的用户数据，并在写入后重新读取。

SillyTavern 可能会在静态消息 HTML 中为类名添加命名空间。之后添加的动态 DOM 可能不会进行相同的转换。请在实际运行时中验证原始类名标记和计算样式；不要根据离线预览推断结果正确。

实现过程中使用实时编译

当用户要求实时编辑时，请将源代码实现在此处，并使用 sillytavern-card-pipeline 查找并运行目标项目现有的监视器。 不要臆造通用的 watch 命令、端口、本地服务器或输出映射。

编辑前，记录受维护的源代码、卡片使用的确切开发输出，以及当前成功构建标记。每次编辑后：

1. 等待成功重建；出现编译错误时停止；
2. 将新的输出标识交给 sillytavern-runtime-debug；
3. 验证 Tavern Helper 已重新加载预期的消息或脚本 iframe；如果无法实时监听，则使用项目声明的手动刷新／重新绑定备用方案；
4. 在继续之前，检查生成的 DOM、控制台、交互和数据状态。

监听器已连接并不能证明最新源代码已编译成功，监视构建成功也不能证明 SillyTavern 已加载它。请保留这两项凭证。使用实时循环缩短实现反馈时间，然后运行生产构建，并将其确切产物交给最终运行时验收流程。

打包前的可选前端沙盒

当作者希望打磨嵌入式 UI 时，可提供本地前端沙盒作为可选的工作循环，尤其是在打包前。趁修改成本还不高时，它可以暴露布局、交互、状态和跨模块问题。作者可以跳过；跳过不代表未通过门槛，也绝不会阻碍常规构建和真实运行时流程。节省的时间和发现的 Bug 因项目而异；不要承诺能固定减少运行时测试轮次。

TavernWeave 为此工作循环提供规范和工作方法。请在双方约定的测试工作区中，基于作者维护的源文件构建项目专属沙盒，并复用项目的预览服务和开发技术栈。不要引入通用 TW 工作台、演示应用或采用介绍页面。复用已有的采用／跳过决定；若有人要求构建沙盒，即表示已选择采用。若选择跳过，则不要创建沙盒，并继续现有工作流。

阅读沙盒工作流，了解范围、实施步骤和证据边界；阅读集成契约，了解状态、事件和 UI 参数；选择单模块或联合检查时，阅读场景配方。这些是实施要求，并非已发布运行时的 API。请根据项目调整名称和布局。用户指南提供了可直接使用的请求。

通过项目的最小化宿主适配器加载完整的维护中组件源代码，并列出每个选定模块的实际源路径、修订版本和 SHA-256。如果提供的哈希标记为 unverified，请报告为未验证，不要将其视为完整性检查。保留所需的 iframe/blob 层级和 API 窗口位置。完整模拟涵盖约定范围内的所有模块、入口和功能；并分别展示已加载、未连接、不支持和未测试的项目。单模块适用于专项测试；涉及共享状态或事件时，则应将相关模块一同挂载。替代模拟的截图无法证明源代码保真度。

将游戏数据与临时 UI 设置分开。展示数据来源、批次、目标聊天／楼层、修改前后的差异及预期事件；注入前，必须明确确认，并将确认绑定到该批次、范围和状态修订版本。初始预设和完整场景序列也需要确认；已获批准的序列无需为每个内部步骤重复确认。取消时不写入任何内容；目标或修订版本发生变化时，使批准失效。将实际提交的状态与每个模块观察到的字段进行比较。UI 滑块和精确输入应在已采用的范围内即时预览；提供基线对比、重置、预设和参数导出。手动调整时不要更改用户的视口大小。回写选定修改后，移除临时覆盖，并从维护中的源代码重新运行同一场景。导出场景记录和剩余宿主缺口，然后将确切的构建产物交给 sillytavern-runtime-debug。沙盒检查绝不设置 driverAccepted，也不能替代真实宿主、设备、模型和人工视觉证据。

公开文档中使用合成的机制示例。请将私有卡片源文件、原始聊天记录、玩家数据和本地证据保存在项目的测试工作区中，并确保其位于公共仓库和发布版本之外。

开场页面

将 first_mes 视为真实的助手消息，使其参与上下文、滑动、编辑、分支、导出、宏、正则表达式和渲染。

页面本身可以承担问候语的展示作用，符合构建器的 开场约定。 对于固定场景页或选择页，请检查其内容和进入游戏的流程。渲染页面本身并不授权写入状态或发送消息。保留可用的 first_mes 或所选 alternate_greetings 路径，并分别验证哪些内容会传给模型，哪些内容会呈现给玩家。

少量固定开场优先使用原生问候分支。实现自定义设置向导时，请遵循以下事务规则：

• 保持可见挂载内容精简，避免将大型 UI 标记放入模型上下文。
• 按稳定的聊天身份隔离草稿；验证并迁移已存储的草稿。
• 让预览保持只读。显示最终的玩家消息和所有持久化效果。
• 在确认时冻结聊天／草稿上下文，并在写入和发送前重新检查。
• 对可变目标创建快照，使重试具备幂等性，并将不可逆操作放在最后。
• 使用标准的 SillyTavern 发送路径，以便创建真实的用户消息和真实的助手回复。
• 保留现有输入文本；如果自动化失败，让消息仍可供手动发送。
• 仅在确认真实用户消息后，才标记开场已完成。
• 成功后退出开场工作流；后续游戏回到正常的多消息流程。

状态栏和 HUD

• 如果 MVU 提供状态，请使用 MVU 状态栏设计，将玩家的阅读任务转化为字段到显示内容的映射。复用当前架构，并在上游处理缺失结构；不要为了填充布局而创建变量。
• 优先考虑便于反复浏览，而不是追求炫目效果。
• 提供有用的加载中、空、不可用、数据格式错误和数据过期状态。
• 集中管理变量路径和格式化逻辑。切勿在组件代码中分散架构路径。
• 从预期楼层读取 stat_data，并根据有文档记录的事件刷新。
• 让筛选器、标签页和模式切换易于快速理解。
• 对长值采取明确的处理方式：折叠、换行、截断并提供可访问的完整值查看方式，或滚动显示。
• 数据刷新时保留当前标签页、滚动位置、展开的分区以及用户选择的地图／视图状态。
• 避免在滑动、编辑或重新渲染后创建重复的框架或挂载。
• 使用签名或定向更新，避免重新渲染未更改的分区；同时在用户操作后提供明确的强制刷新方式。
• 根据字段约定，区分有效的零值和 false 与缺失、空值或无效数据。只读刷新和本地视图控件不得初始化或修复游戏状态。

控制中心

• 让主要状态和主要操作保持可见；不要将它们藏在设置之下。
• 将入口控制、外壳几何结构、内容渲染和数据操作分开。
• 将面板设为单例，并在聊天或宿主 UI 重建后恢复其入口。
• 隔离各分区的渲染失败，避免单个字段格式错误导致整个面板空白。
• 说明离线、未通过身份验证、缺少依赖、部分成功和重试等状态。
• 在提交前预览世界书、程序包、身份或变量变更。
• 不要将控制中心用作开场页面事务中隐藏的第二个真实数据源。

弹出层、抽屉和模态框

• 将覆盖层挂载到不会被祖先的 overflow、transform 或滤镜裁剪的层中。在非框架代码中，位于可访问文档 body 下的专用覆盖层根节点相当于 portal。
• 如果无法访问宿主文档，请使用面板内的绝对定位覆盖层，并明确滚动策略。
• 将宽度和高度限制在实际容器范围内，并提供可在内部滚动的内容区域。
• 将焦点移入界面；在适当情况下，将焦点限制在真正的模态框内；按 Escape 关闭，并将焦点还给触发控件。
• 明确规定背景遮罩和关闭按钮的行为；不要让用户轻易误关具有破坏性的操作。
• 保留并恢复对 body 滚动或光标所做的任何更改。
• 测试嵌套确认流程、长内容、移动端键盘以及高度较小的视口。

无障碍门槛

• 保持标题顺序和 DOM 阅读顺序符合逻辑。
• 为每个控件提供无障碍名称，并为每个字段提供可见标签。
• 通过适当的 ARIA 状态公开当前选中的标签页、展开的分区、选中的值、忙碌状态和验证错误。
• 必要时，使用 aria-live 播报异步状态或错误。
• 确保键盘导航完整，并为焦点设置清晰可见的样式。
• 不要只通过颜色传达状态。
• 在空间允许时，将触控控件的目标尺寸设为约 44×44 CSS 像素。
• 遵循 prefers-reduced-motion；避免让重要信息只在动画期间显示。
• 检查文本对比度、200% 缩放/重排、较长的 CJK 文本，以及便于屏幕阅读器识别的错误关联。

准备运行时交接

静态 lint、单元测试和离线预览都是辅助检查。用它们准备候选实现，然后将构建产物交给 sillytavern-runtime-debug，以获取真实 SillyTavern 执行证据并完成验收。除非引用针对同一产物修订版本的独立 runtime-debug 报告，否则不要在此处将运行时用例标记为通过。

选择相关的运行时用例并将其纳入交接：

领域	所需的 runtime-debug 证据
渲染	新建聊天、每次开启滑动、消息编辑、重新渲染、重新加载和切换聊天
状态	加载中、空数据、长数据、格式错误的数据、依赖缺失、网络故障、重试和部分成功
交互	指针、键盘、焦点返回、重复点击、取消、关闭和输入保留
布局	宽屏桌面、窄消息容器、约 320px 宽度、较短视口、缩放和移动端键盘
样式	计算后的显示属性、尺寸、溢出、堆叠、转换后的类名、深色/浅色上下文和减少动态效果
数据	正确的作用域/楼层、事件刷新、重新读取后持久化、不产生无关更改，以及不重复提交
安全	用户/模型文本保持惰性；远程标记不会执行业务逻辑；DOM 或日志中不出现机密信息

对于消息内容页面，请从消息内容页面中选择协议用例，并在适用时涵盖周围文本保留和不完整内容。对于 MVU 显示，请从 MVU 状态栏设计中选择字段和集合用例，并涵盖只读刷新。仅有正则表达式测试样例不足以证明解析器或视觉行为。请在实际更改范围内完成这些检查，不要另建无关的演示应用。

对于前端问候语，请验证其实际的消息/分支载体、可见内容、进入 play 的流程以及模型可见的信息。针对其实际提供的控件选择交互用例。自定义设置向导还需测试草稿编辑、刷新/恢复、预览、确认、真实玩家消息和真实助手回复，且不得重复提交。如果采用的状态系统要求初始化变量，也请验证变量初始化。 对于 HUD 或控制中心，请要求检查滑动/编辑/切换聊天的生命周期，并实际检查计算后的样式。

交付内容

报告：

• 选定的界面和状态归属；
• 检查过的设计参考、视觉方案以及任何未经验证的质量证据；
• 最小实现或审查发现；
• 安全与无障碍设计决策；
• 支持性检查以及桌面或窄屏布局证据；
• 准确的构建产物标识和选定的运行时交接案例；
• sillytavern-runtime-debug 的已知设备、账户、扩展或驱动程序阻碍。