sillytavern-card-pipeline

SillyTavern 卡片流水线

共享沟通规范

遵循 TW plain-language and guidance rules：首次使用术语时予以解释，遵循用户选择的新人/入门/熟练/老手级别，并在每个级别说明必要的更改和错误。灵魂模式和文案模式都不会禁用这套基准规范。

插件运行时

当此技能通过插件、云主机或远程计算机运行时，入口处应阅读插件执行约定，并在执行特定于主机的命令前进行主机、工具和持久化检查。遵守此技能的范围、授权和验收门槛。

此技能负责协调目标代码库的工作流；它不提供构建引擎。查找并验证项目自身的工具，将其映射到精简的适配器约定，并将配置、源文件和构建产物分开管理。

执行写入、构建或打包操作前，使用 $consult-tavernweave-library 的 sillytavern-card-pipeline 路由。阅读 A0 和返回的构建/部署指南，然后将路由回执与预检证据放在一起。

使用 acceptance-ledger.md 记录各项能力的证据。源代码、自动化、离线构建产物、浏览器、真实 SillyTavern、人工和发布门槛应分别记录；自动化绝不能写入 driver-accepted。

确认请求的门槛

运行任何会产生更改的命令前，先对请求分类：

• 实时迭代：运行项目中已验证的监视器，并在修改源文件后重新构建开发输出；
• 迭代：更改源文件并运行基于影响范围的检查；
• 检查点打包：生成下一阶段所需的 JSON 或 PNG；
• 候选发布版：组合、打包、嵌入，并运行完整的离线门槛；
• 已验收发布版：完成剩余的主机检查并批准交付。

只有当用户明确要求打包、重新打包、生成 PNG、最终构建产物、完整工作流、交付、发布，或要求生成必须包含打包产物的检查点时，才进行打包。不要在每次组件编辑后都打包。

探索项目适配器

调用项目工具前，先阅读 tool-adapter-contract.md。

1. 阅读代码库说明和当前构建文档。
2. 检测代码库根目录、当前生效的配置入口、可执行运行时和可用的工作流能力。
3. 通过帮助输出、模式、测试或源码检查验证每项能力；不要仅凭文件名推断其行为。
4. 记录命令、工作目录、明确的输入和输出、是否支持试运行、副作用和成功标准。
5. 先运行只读的信息查询或验证能力。

如果缺少所需能力，请在报告中明确指出。不要声称存在内置引擎或备用命令。

驱动实时开发循环

仅当用户要求实时编译、监视模式、热重载或等效开发循环时，才进行实时迭代。

1. 检查目标项目的包脚本、构建配置和开发文档。不要假设命令是 pnpm watch，也不要假设每个监视器都使用相同的输出布局。
2. 在适配器记录中记下监视器命令、工作目录、源目录、确切输出、初始构建就绪信号、重建成功和失败信号，以及停止流程。
3. 确认输出路径正是卡片、正则、本地服务器或 Tavern Helper 绑定所使用的路径。进程正在运行但初始构建未成功，则尚未就绪。
4. 启动一个监视器，并确保其输出可观察；每次修改源文件后，都要等待重建成功，然后再请 sillytavern-runtime-debug 验证监听器重载以及 SillyTavern 中的新行为。
5. 将监听器断开、编译器错误和输出过期视为迭代失败。不要把运行时行为归因于新源代码已加载，而实际上它仍在使用上一次成功生成的构件。

监视输出属于开发候选产物，即使项目将其写入 dist/ 也是如此。在进行检查点或发布打包前，运行已验证的生产构建并检查构件。如果两个命令可能写入相同目标，先停止或隔离监视器。

确定配置事实

创建、编辑或协调工作流数据时，请阅读 configuration-contracts.md。

一并确定当前生效的文件：

• profile：卡片系列身份、默认值、协议、变量根目录、配方和配置链接，包括声明的卡片类型／能力默认值；
• manifest：确切的版本路径、组件映射、打包策略、交付物、字段链、卡片绑定的世界书身份、运行时依赖清单以及特定版本的行为；
• plan：已知状态之间、可供审查的预期变更序列；
• contract：稳定的必需和禁止不变量。

重新探查确切的当前生效 profile 和 manifest，不要依赖记忆中的版本。将差异保留在数据中，而不是复制卡片名称或特定版本的工具。让生成的构件使用这些声明，而不是重复协议或版本规则。

从维护中的源代码检测主要卡片类型和能力标记，并将其与声明的 profile／manifest 对照协调。如果声明与打包后的扩展界面相矛盾，除非明确说明兼容性原因，否则不要接受。

准备变更

1. 清点当前源码和现有产物，不作修改。
2. 清点正则表达式、Tavern Helper 脚本、架构、宿主能力、远程导入和区域替代组。将它们归类为宿主必需、嵌入式必需、远程运行时、区域替代、可选或仅用于开发。
3. 提供预检说明，分别列出已嵌入内容、宿主设置、远程运行时加载、区域选择和仅用于开发的工具。对于 MVU Zod 卡片，列出已嵌入的打包架构以及国内版／全球版脚本，然后单独列出它们的 Git／CDN 目标。不要用本地 Zod 安装说明替换该加载路径。
4. 明确写入范围和新产物路径。保留早期版本；默认使用新版本或暂存目录。
5. 为范围内每个已正常工作的使用方创建回归检查清单。
6. 制定或审查计划，明确具体操作、带保护条件的替换、冲突策略，以及每一步对应的验证。
7. 验证配置档案、清单、计划、契约和运行时依赖结构。
8. 运行计划的试运行，并检查预测的写入内容，然后再应用计划。

如果只需从历史版本派生源组件，不要复制整个历史版本。不要将旧版 JSON 或 PNG 提取并覆盖正在编辑的组件。

按影响验证

使用 release-gate.md 中的影响矩阵。运行能够证明变更契约的最小检查集；只有当变更跨越边界时才扩大检查范围。

始终验证耦合变量字段在初始数据、架构、更新规则、输出格式、上下文、分组、运行时读取方和示例中的一致性。面向模型的文本不得包含开发者说明。分别验证各运行时层，不要假设世界书、正则表达式、辅助脚本或 iframe 共享其他层的 API。在 component_assembly 和 release 阶段，缺少 embedded_required 依赖或区域替代选择无效，都是阻断性缺陷，而不是提醒事项。

将错误的检查视为缺陷：契约必须锁定稳定行为并包含禁止出现的回归，而不能固化临时的实现偏好。

组合与打包

1. 确认源文件编辑和针对性检查均已完成。
2. 对维护中的源文件重新检测卡片类型和运行时依赖。 在写入暂存输出前，核对检测结果与声明清单。
3. 仅当活动配置文件选择了生成组件，且配方与当前目标相符时才进行组合。不要为了让构建通过而覆盖手动维护的组件快照。
4. 组合到暂存目录，并验证必需输出、依赖解析、语法和组件一致性。
5. 验证每个必需的内嵌正则表达式、架构、辅助脚本、加载器和绑定均存在于其声明的打包字段中，并具有预期的稳定标识和启用状态。对于区域组，要求包含卡片承诺的每个脚本，并执行清单的启用状态策略；通用的国内版／全球版组合应同时打包两个脚本，并仅启用其声明的默认项。
6. 根据活动清单中的稳定 ID 解析每个与卡片绑定或随卡片交付的世界书。验证其维护源和声明版本与卡片发行版一致；不要根据显示名称、时间戳或看起来最新的文件名来选择世界书。
7. 将组件源中的 JSON 打包到清单指定的暂存目标中。打包后绝不注入修复内容；应先更新维护中的源文件，再重新打包。
8. 重新打开打包后的 JSON，并验证运行时依赖清单、扩展接口、附加的世界书标识、版本信息和语义内容均与已解析的维护源一致。如果还会单独交付世界书，则要求其版本和内容与声明一致。
9. 在嵌入 JSON 前验证其有效性。
10. 根据清单策略，将 JSON 嵌入复制的或明确声明的 PNG 外壳中。保留无关数据块，并验证每个生成的卡片载荷都能解码为打包后的 JSON。
11. 默认禁用反向提取。仅在打包和嵌入完成后，将其用作沙盒化的往返检查。

如果明确要求重新打包现有目标，先对当前制品创建快照并计算哈希，然后报告替换情况。绝不要静默替换较早的发行版。

通过发行门禁

按照 release-gate.md 中的检查点、候选版本和验收标准执行。

至少要证明：

• 配置与版本一致；
• 卡片类型／能力证据，以及完整的运行时依赖分类；
• 必需的内嵌运行时资源和区域选择；
• 卡片与世界书的稳定 ID、版本、附加关系及源文件一致性；
• 合约检查和禁止回归检查；
• 完整的声明组件集和交付物集；
• 打包后 JSON 的有效性及其与源文件的一致性；
• PNG 结构、载荷数量，以及与 JSON 的语义等价性；
• 制品路径、大小和哈希；
• 声明范围之外没有意外写入。

仅在发行候选版本或收到明确请求时，才运行项目的发行审计。离线成功并不代表已完成依赖宿主的 UI、正则表达式、桥接、导入、新建聊天、远程加载器执行或交互检查；在真实 SillyTavern 验收完成前，应将这些项目记录为待处理。

报告交接情况

说明：

• 适配器能力及使用的确切命令；
• 对于实时迭代，监视器就绪信号、输出路径、最近一次成功重建，以及是否已验证真实 SillyTavern 重载；
• 活动配置文件、清单、计划和合约；
• 检测到的主要卡片类型和能力标志；
• 已内嵌的依赖、仍需宿主安装／启用的依赖、远程 Git/CDN 加载、选定的区域替代项、可选功能，以及仅用于开发的排除项；
• 已解析的卡片／世界书版本组合及附加验证结果；
• 写入的文件和保留的制品；
• 针对性、标准和发行检查的通过或失败结果；
• JSON 和 PNG 哈希，以及载荷一致性结果；
• 跳过的门禁及剩余的真实宿主验收事项。