sillytavern-extension-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SillyTavern Extension Builder

SillyTavern 扩展构建器

Overview

概述

Create production-ready SillyTavern third-party extensions with the documented extension APIs and packaging rules.

通过文档化的扩展API和打包规则，创建可用于生产环境的SillyTavern第三方扩展。

Workflow

工作流

Define the extension contract.

Confirm extension slug, display name, minimum supported SillyTavern version, required modules, and whether the feature is UI-only, slash-command-only, or background worker based.
If the user does not provide a slug, generate a lowercase kebab-case slug.

Scaffold baseline files.

Prefer

scripts/scaffold_extension.sh

to generate

manifest.json

index.js

style.css

, and

settings.html

Choose template mode:
- ```
default
```
  for UI/event-focused extensions.
- ```
slash
```
  for slash-command-first extensions.
If the user already has files, perform minimal edits instead of full rewrites.

Wire extension lifecycle and settings.

Keep extension settings under
```
extension_settings[EXTENSION_NAME]
```
.
Call
```
loadExtensionSettings(EXTENSION_NAME)
```
before reading setting values.
Use
```
saveSettingsDebounced()
```
after setting changes.
Register startup/event handlers inside
```
jQuery(async () => { ... })
```
.

Implement user-facing behavior.

For DOM/UI integration, use documented APIs (context helpers, templates, settings rendering).
For command behavior, add slash commands and argument parsing with the slash-command APIs when needed.
For background logic, use a module worker class and gate execution by current chat context.

Validate compatibility and packaging.

Ensure manifest keys are correct and file names match actual files.
Ensure import paths are valid from the extension directory.
Keep third-party dependency usage explicit and minimal.
Package as a repo or zip with only required runtime files.

Return deliverables.

Provide final file set and a concise integration note.
Include install path expectations and any required module prerequisites.

定义扩展契约

确认扩展slug、展示名称、最低支持的SillyTavern版本、所需模块，以及功能类型为仅UI、仅斜杠命令还是基于后台worker。
如果用户未提供slug，生成一个小写kebab-case格式的slug。

搭建基础文件骨架

优先使用

scripts/scaffold_extension.sh

生成

manifest.json

、

index.js

、

style.css

和

settings.html

。

选择模板模式：
- ```
default
```
  适用于以UI/事件为核心的扩展
- ```
slash
```
  适用于优先实现斜杠命令的扩展
如果用户已经存在相关文件，仅做最小化修改，不要全量重写。

关联扩展生命周期与设置

将扩展设置存储在
```
extension_settings[EXTENSION_NAME]
```
下。
读取设置值前先调用
```
loadExtensionSettings(EXTENSION_NAME)
```
。
修改设置后使用
```
saveSettingsDebounced()
```
保存。
在
```
jQuery(async () => { ... })
```
内部注册启动/事件处理函数。

实现面向用户的功能

对于DOM/UI集成，使用文档提供的API（上下文助手、模板、设置渲染）。
对于命令功能，按需使用斜杠命令API添加斜杠命令和参数解析逻辑。
对于后台逻辑，使用模块worker类，根据当前聊天上下文控制执行。

验证兼容性与打包

确保manifest的键值正确，文件名与实际文件匹配。
确保从扩展目录出发的导入路径有效。
第三方依赖的使用要明确且最小化。
打包为仓库或zip包时仅包含必要的运行时文件。

返回交付物

提供最终文件集和简洁的集成说明。
包含预期安装路径和所有必要的前置模块要求。

Output Rules

输出规则

Prefer minimal-diff changes when editing an existing extension.
Keep settings schema stable; migrate old keys instead of silently breaking them.
Use deterministic IDs/command names (derive from extension slug).
If introducing a slash command, include help text and argument validation.
If introducing a module worker, include clear stop conditions for idle/no-chat states.

编辑现有扩展时优先选择差异最小的修改方案。
保持设置schema稳定，迁移旧键而不是静默破坏原有配置。
使用确定性的ID/命令名（从扩展slug派生）。
如果引入斜杠命令，必须包含帮助文本和参数验证逻辑。
如果引入模块worker，必须包含空闲/无聊天状态下的明确停止条件。

Resources

资源

```
references/writing-extensions-reference.md
```
- Condensed upstream authoring guidance, required file anatomy, APIs, and release rules.

references/st-extension-example-walkthrough.md

Practical breakdown of the
```
city-unit/st-extension-example
```
template and reuse patterns.

```
references/extension-quality-guidelines.md
```
- Research-backed recommendations for quality, maintainability, security, and release readiness.
```
references/template-selection-guide.md
```
- Decision guide for choosing
```
default
```
  vs
```
slash
```
  scaffold mode and migrating between them.

assets/templates/extension/manifest.json

Starter manifest with placeholders.

```
assets/templates/extension/index.js
```
- Starter extension entrypoint with settings and event wiring.
```
assets/templates/extension/style.css
```
- Starter CSS file referenced by manifest.

assets/templates/extension/settings.html

Starter settings template for
```
renderExtensionTemplateAsync
```
.

assets/templates/extension-slash/manifest.json

Slash-command-first starter manifest.

```
assets/templates/extension-slash/index.js
```
- Slash-command-first starter entrypoint with parser registration and validation.
```
assets/templates/extension-slash/style.css
```
- Minimal stylesheet for command help/settings rows.
```
assets/templates/extension-slash/settings.html
```
- Starter settings block for enabling/disabling command behavior.
```
scripts/scaffold_extension.sh
```
- Generator script for new extension skeletons.

```
references/writing-extensions-reference.md
```
- 精简的上游开发指南、必填文件结构、API说明和发布规则。

references/st-extension-example-walkthrough.md

对
```
city-unit/st-extension-example
```
模板和复用模式的实操拆解。

```
references/extension-quality-guidelines.md
```
- 基于研究的质量、可维护性、安全性和发布就绪建议。
```
references/template-selection-guide.md
```
- 选择
```
default
```
  和
```
slash
```
  脚手架模式以及模式迁移的决策指南。

assets/templates/extension/manifest.json

带占位符的初始manifest文件。

```
assets/templates/extension/index.js
```
- 预置设置和事件关联逻辑的扩展入口文件。
```
assets/templates/extension/style.css
```
- manifest引用的初始CSS文件。

assets/templates/extension/settings.html

用于
```
renderExtensionTemplateAsync
```
的初始设置模板。

assets/templates/extension-slash/manifest.json

优先斜杠命令的初始manifest文件。

```
assets/templates/extension-slash/index.js
```
- 预置解析器注册和验证逻辑的优先斜杠命令扩展入口文件。
```
assets/templates/extension-slash/style.css
```
- 用于命令帮助/设置行的极简样式表。
```
assets/templates/extension-slash/settings.html
```
- 用于启用/禁用命令功能的初始设置块。
```
scripts/scaffold_extension.sh
```
- 生成新扩展骨架的脚本工具。

Notes

注意事项

The docs and extension APIs evolve. If behavior is uncertain, prefer upstream docs over assumptions and keep code conservative.
Keep code style aligned with existing SillyTavern extension conventions (imports, settings handling, and event registration).

文档和扩展API会不断演进，如果对行为不确定，优先参考上游文档而非自行假设，保持代码实现保守。
代码风格要与现有SillyTavern扩展约定保持一致（导入、设置处理和事件注册方式）。