sillytavern-card-components

SillyTavern 卡片组件

共享沟通规范

遵循 TW plain-language and guidance rules：首次使用术语时进行解释，保持用户选择的新人/入门/熟练/老手级别，并在每个级别说明必要的变更和错误。Soul 和 prose 模式绝不会停用这项基准要求。

插件运行时

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

在分解或写入注册表之前，通过 $consult-tavernweave-library 使用 sillytavern-card-components 路由，阅读 A0 和返回的卡片格式/正则表达式指南，并在往返计划中记录回执。

将可复用组件源与打包后的卡片制品分开存放。探索性工作应保持为一次性内容，以确保共享库稳定。只有在证据充分时才晋升变更。

确定边界

1. 检查或更改卡片文件前，先阅读仓库说明。
2. 将任务归类为以下其中一项：
   • 将输入卡片拆解到新的沙盒中；
   • 编辑版本本地组件快照；
   • 组合现有配方；
   • 明确将成熟工作晋升到共享库中。
3. 确定当前的事实来源。除非仓库明确另有说明，否则将版本本地的 components/ 树、打包后的 JSON 和打包后的 PNG 视为制品。
4. 保留先前的发布版本。绝不要因组件工作而迁移、重写或规范化归档制品。
5. 优先采用能复用现有注册表、配方和构建约定的最小变更。

安全拆解卡片

提取 JSON 或 PNG 输入前，请阅读 safe-disassembly.md。

• 绝不要提取到输入目录、活动版本树或共享组件库中。
• 将输入复制到一个全新的沙盒中，记录其哈希值和大小，并将该快照视为只读证据。
• 要求提取工具接受明确指定的输入和输出位置。如果工具通过隐式清单路径写入，则只能针对沙盒内该配置的一次性副本运行，或改用其他方法。
• 将 PNG 载荷解码为规范化的卡片 JSON，然后再拆分逻辑组件。
• 记录每个提取文件的来源，使用稳定的逻辑标识符、卡片 JSON 指针或选择器、源哈希值和输出哈希值。
• 除非明确的契约授权进行转换，否则保留未知字段、条目标识符、数组顺序和扩展元数据。

提取成功不代表获准更新共享库。

对组件库建模

创建或更改注册表、模块声明、输出声明、配方、依赖、变量根目录或替换关系时，请阅读 component-model.md。

将注册表作为机器可读的事实来源。根据它生成面向用户的目录；切勿将 CSV 或电子表格导出文件用作构建输入。

每个模块至少声明：

• 稳定 ID 和类别；
• 源文件和生成的输出；
• 明确的依赖项和冲突项；
• 运行时依赖声明和交付类别；
• 内容是否对模型可见；
• 构建或合并行为；
• 受影响的运行时层或变量层；
• 库支持时的适用性和成熟度元数据。

如果存在缺失依赖项、循环依赖、冲突、未声明的输出冲突、缺失源文件，或路径逃逸出预期根目录，则组合必须失败。在 component_assembly 和 release 阶段，如果存在尚未解决的必需嵌入式运行时资源，或区域替代项选择无效，也必须失败。将 worldbook、MVU、regex、helper-script 和 embedded-UI API 隔离；声明依赖项并不会使其他运行时层全局可用。

将配方定义为选择项

将组件内容保留在模块中。让配方选择模块并声明输出边界；不要将构建逻辑或内容复制到配方中。

使用仓库定义的阶段。如果仓库中有等效阶段，请保持以下语义：

• variable_core：仅生成完整的变量链；
• component_assembly：添加卡片专用适配器和展示组件；
• release：要求完整的已声明输出集，并执行发布检查。

配方的默认输出位置应为沙盒。只有在明确执行已获准写入范围的重建或晋级操作时，才指向版本快照。仅当注册表指定了延后适配器的归属方和必需阶段时，variable_core 配方才可延后生成后续的嵌入式适配器。不得将此延后操作带入 component_assembly 或 release。

保持耦合字段同步

将变量字段视为跨文件契约。按以下顺序追踪并更新所有适用的使用方：

initial data -> schema -> update rules -> output format -> context -> variable groups -> runtime readers -> rendered examples

记录有意缺失的层。不要因为一个写入方或一个界面成功更改，就认定字段迁移已完成。

验证源文件与产物的一致性

1. 验证注册表和配方结构。
2. 解析依赖关系图和输出归属。
3. 解析运行时依赖类别、自有嵌入式输出和区域替代组。
4. 在干净的沙盒中进行组合。
5. 验证语法、编码、必需内容和禁止内容，以及运行时层契约。
6. 构建沙盒 JSON，并在适用范围内构建沙盒 PNG。
7. 将构建好的产物重新提取到第二个干净的沙盒中。
8. 比较规范化的卡片语义和组件映射。仅在契约要求时使用字节相等性；JSON 格式和 PNG 容器字节可能不同。
9. 对更改涉及的每个先前正常运行的使用方执行回归检查。
10. 对依赖宿主环境的 UI、regex、bridge、remote-loader 执行和交互检查，保持待处理状态，直到它们通过真实的 SillyTavern 验收测试。

仅提升成熟组件

必须明确请求更新共享库，并预先声明成熟度门槛。每次只提升一个可独立测试的功能，并且仅在通过组合、往返、回归和适用的运行时检查后才进行提升。

替换共享模块时，登记关系的两个方向，保留旧版本工件，并根据注册表重新生成派生目录。将实验性模块或仅用于验证的模块标记为生产配方之外的内容。如果经过反复调试后功能仍不稳定，请停止并重新评估核心设计，而不是在库中叠加兼容性补丁。

报告结果

说明：

• 输入快照哈希和沙盒位置；
• 创建或更改的文件；
• 注册表、配方和依赖项的处理决定；
• 检测到的卡片功能，以及运行时依赖项清单，包括嵌入式资源、主机要求、远程加载器和区域选择；
• 往返和回归检查及其结果；
• 是否进行了共享库提升；
• 仍需执行的任何真实 SillyTavern 检查。