主题 SDK 概述

主题 SDK 是替换 NeoTavern 整个视觉外壳的版本化契约 —— 而不仅仅是换色。

主题 SDK 是什么

主题是一个控制应用外观以及主要区域如何组成的软件包（.sttheme）。与插件不同，主题没有 JavaScript：它是 CSS、语义令牌和清单中的声明式外壳布局。由于 SDK 是声明式的，主题无法破坏应用的行为或到达其数据。

@neotavern/theme-sdk 包提供契约本身：规范令牌名、清单校验、继承解析和 CSS 变量生成。宿主的参考实现通过把 --st-* 自定义属性写到文档根上，并按定义好的顺序加载主题的样式表来应用主题。

主题化分为三个层级，主题可以使用其中任何一个：

设计令牌 —— 颜色、字体、间距、圆角、阴影、z-index 层、动效和控件大小的语义变量。组件只引用这些令牌，因此覆盖一个令牌会一致地重新样式化整个界面。
组件皮肤 —— 通过稳定的 data-component、data-part、data-role 和 data-state 钩子重新样式化组件的 CSS。
外壳布局 —— 主要区域的声明式组合：导航栏、管理面板和聊天工作区。

由于聊天逻辑、数据模型和行为不受影响，主题可以模仿操作系统、游戏主机、视觉小说界面或移动应用布局，而不会破坏任何功能。详情请参阅层级。

主题是一个包含 theme.json、components.css 和 shell.css 的 ZIP。你可以手工构建一个：

第一个主题不需要 Node.js、npm、JavaScript 或主题 SDK CLI。

安装软件包并不会激活它。激活会校验整个 extends 链是否存在缺失的父主题和循环，然后在一次事务中更新启用的主题和保存的主题选择。用相同 id 更新软件包会原子地替换其目录并保持当前的激活状态；注册表错误时恢复之前的目录。

发行版附带一组内置主题，例如 AMOLED、GitHub Dark、Matrix、Nord、Gruvbox、 Dracula、Tokyo Night、Catppuccin Mocha、Solarized Dark 和 One Dark，因此主题管理器永远不会空着打开。

主题无法读取聊天记录、API 密钥或文件系统，并且不包含可执行代码。每个样式表都会扫描禁止的构造，安全模式完全禁用第三方主题。保证请参阅安全模式，完整 API 请参阅生成的主题 SDK 参考。