SillyTavern扩展开发：打造自定义AI功能模块

【免费下载链接】SillyTavern LLM Frontend for Power Users. 项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern

SillyTavern作为一款强大的LLM前端工具，其扩展系统为开发者提供了无限的可能性。本文将深入探讨如何开发自定义扩展，从基础概念到高级功能实现，帮助您打造专属的AI功能模块。

扩展系统架构解析

SillyTavern的扩展系统采用模块化设计，每个扩展都是一个独立的文件夹，包含必要的配置文件、JavaScript代码和样式文件。

扩展目录结构

public/scripts/extensions/
├── your-extension/
│   ├── manifest.json      # 扩展元数据
│   ├── index.js          # 主逻辑文件
│   ├── style.css         # 样式文件
│   ├── settings.html     # 设置界面
│   └── window.html       # 弹窗界面

核心文件详解

manifest.json - 扩展配置文件

{
    "display_name": "你的扩展名称",
    "loading_order": 15,
    "requires": ["module1", "module2"],
    "optional": ["optional_module"],
    "js": "index.js",
    "css": "style.css",
    "author": "开发者名称",
    "version": "1.0.0",
    "minimum_client_version": "1.10.0",
    "dependencies": ["required-extension"],
    "homePage": "https://your-repo.com"
}

字段说明：

• display_name: 扩展显示名称
• loading_order: 加载顺序（数值越小越先加载）
• requires: 必需的Extras API模块
• optional: 可选的Extras API模块
• dependencies: 依赖的其他扩展
• minimum_client_version: 最低客户端版本要求

index.js - 扩展主逻辑

import { main_api } from '../../../script.js';
import { getContext } from '../../extensions.js';
import { SlashCommand } from '../../slash-commands/SlashCommand.js';
import { SlashCommandParser } from '../../slash-commands/SlashCommandParser.js';
import { renderExtensionTemplateAsync } from '../../extensions.js';
import { POPUP_TYPE, callGenericPopup } from '../../popup.js';
import { t } from '../../i18n.js';

// 扩展初始化函数
jQuery(() => {
    // 添加扩展按钮到界面
    const buttonHtml = `
        <div id="your_extension" class="list-group-item flex-container flexGap5">
            <div class="fa-solid fa-icon extensionsMenuExtensionButton" /></div>
            ${t`你的扩展`}
        </div>`;
    $('#extensions_menu_container').append(buttonHtml);
    
    // 绑定点击事件
    $('#your_extension').on('click', async () => {
        await showExtensionWindow();
    });

    // 注册斜杠命令
    SlashCommandParser.addCommandObject(SlashCommand.fromProps({
        name: 'yourcommand',
        callback: async (args) => {
            return await executeYourCommand(args);
        },
        returns: '执行结果描述',
        helpString: '命令帮助说明'
    }));
});

async function showExtensionWindow() {
    const html = await renderExtensionTemplateAsync('your-extension', 'window', {
        param1: 'value1',
        param2: 'value2'
    });

    const dialog = $(html);
    callGenericPopup(dialog, POPUP_TYPE.TEXT, '', { 
        wide: true, 
        large: true, 
        allowVerticalScrolling: true 
    });
}

async function executeYourCommand(args) {
    // 命令执行逻辑
    const context = getContext();
    // 访问聊天上下文
    const messages = context.chat.filter(x => x.mes && !x.is_system);
    
    // 调用API或其他处理
    try {
        const result = await fetch('/api/your-endpoint', {
            method: 'POST',
            headers: getRequestHeaders(),
            body: JSON.stringify({ data: args })
        });
        
        return result.ok ? '成功' : '失败';
    } catch (error) {
        console.error('命令执行错误:', error);
        return '执行出错';
    }
}

扩展开发实战指南

1. 环境准备与项目设置

首先确保您的开发环境配置正确：

# 克隆SillyTavern仓库
git clone https://gitcode.com/GitHub_Trending/si/SillyTavern
cd SillyTavern

# 安装依赖
npm install

# 启动开发服务器
npm start

2. 创建基础扩展结构

# 在extensions目录下创建新扩展
mkdir public/scripts/extensions/your-extension
cd public/scripts/extensions/your-extension

# 创建必要文件
touch manifest.json index.js style.css settings.html window.html

3. 实现核心功能模块

3.1 用户界面集成

// 在index.js中添加UI元素
function addUIElements() {
    // 添加到工具栏
    const toolbarButton = `
        <div id="your_toolbar_button" class="toolbar-button" title="你的功能">
            <i class="fa-solid fa-star"></i>
        </div>`;
    $('#toolbar').append(toolbarButton);
    
    // 添加到设置面板
    const settingsSection = `
        <div class="settings-section">
            <h3>你的扩展设置</h3>
            <label>
                <input type="checkbox" id="your_setting_toggle">
                启用功能
            </label>
        </div>`;
    $('#settings_container').append(settingsSection);
}

3.2 数据处理与API交互

class YourDataProcessor {
    constructor() {
        this.cache = new Map();
    }
    
    async processChatData(messages) {
        // 处理聊天数据
        const processed = messages.map(msg => ({
            role: msg.role,
            content: this.enhanceContent(msg.mes),
            timestamp: new Date().toISOString()
        }));
        
        return processed;
    }
    
    enhanceContent(content) {
        // 内容增强逻辑
        return content.replace(/\b(\w+)\b/g, '**$1**');
    }
    
    async callExternalAPI(data) {
        const response = await fetch('/api/your-service', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.getApiKey()}`
            },
            body: JSON.stringify(data)
        });
        
        if (!response.ok) {
            throw new Error(`API调用失败: ${response.status}`);
        }
        
        return await response.json();
    }
}

3.3 事件处理与消息系统

// 事件监听器设置
function setupEventListeners() {
    const context = getContext();
    
    // 监听消息发送事件
    context.eventSource.on(context.eventTypes.MESSAGE_SENT, (message) => {
        if (extension_settings.yourExtension.enabled) {
            this.onMessageSent(message);
        }
    });
    
    // 监听设置变化
    $('#your_setting_toggle').on('change', (e) => {
        extension_settings.yourExtension.enabled = e.target.checked;
        saveSettingsDebounced();
    });
}

// 消息处理
async function onMessageSent(message) {
    try {
        const enhancedMessage = await this.dataProcessor.processChatData([message]);
        this.displayProcessingResult(enhancedMessage);
    } catch (error) {
        console.error('消息处理错误:', error);
        toastr.error('处理消息时出错');
    }
}

4. 样式与界面设计

/* style.css - 扩展样式 */
.your-extension-container {
    padding: 15px;
    background: var(--SmartThemeBlurTintColor);
    border-radius: 8px;
    margin: 10px 0;
}

.your-extension-button {
    background: var(--SmartThemeQuoteColor);
    border: none;
    padding: 8px 16px;
    border-radius: 4px;
    cursor: pointer;
    transition: background 0.2s;
}

.your-extension-button:hover {
    background: var(--SmartThemeEmColor);
}

.your-extension-result {
    margin-top: 10px;
    padding: 10px;
    border: 1px solid var(--SmartThemeBorderColor);
    border-radius: 4px;
    background: var(--SmartThemeBodyColor);
}

5. 高级功能实现

5.1 实时数据处理

class RealTimeProcessor {
    constructor() {
        this.observers = new Set();
        this.isProcessing = false;
    }
    
    subscribe(observer) {
        this.observers.add(observer);
    }
    
    unsubscribe(observer) {
        this.observers.delete(observer);
    }
    
    async processInRealTime(data) {
        if (this.isProcessing) return;
        
        this.isProcessing = true;
        try {
            const result = await this.analyzeData(data);
            this.notifyObservers(result);
        } finally {
            this.isProcessing = false;
        }
    }
    
    notifyObservers(result) {
        for (const observer of this.observers) {
            try {
                observer(result);
            } catch (error) {
                console.error('Observer error:', error);
            }
        }
    }
}

5.2 缓存与性能优化

class SmartCache {
    constructor(maxSize = 100, ttl = 300000) {
        this.cache = new Map();
        this.maxSize = maxSize;
        this.ttl = ttl;
    }
    
    get(key) {
        const item = this.cache.get(key);
        if (!item) return null;
        
        if (Date.now() > item.expiry) {
            this.cache.delete(key);
            return null;
        }
        
        return item.value;
    }
    
    set(key, value) {
        if (this.cache.size >= this.maxSize) {
            const firstKey = this.cache.keys().next().value;
            this.cache.delete(firstKey);
        }
        
        this.cache.set(key, {
            value,
            expiry: Date.now() + this.ttl
        });
    }
    
    clear() {
        this.cache.clear();
    }
}

调试与测试策略

1. 开发调试技巧

// 调试工具函数
class DebugHelper {
    static enableDebugMode() {
        window.yourExtensionDebug = true;
        console.log('扩展调试模式已启用');
    }
    
    static log(message, data = null) {
        if (window.yourExtensionDebug) {
            console.log(`[你的扩展] ${message}`, data);
        }
    }
    
    static error(message, error) {
        console.error(`[你的扩展错误] ${message}`, error);
        toastr.error(`${message}: ${error.message}`);
    }
    
    static measurePerformance(name, callback) {
        const start = performance.now();
        const result = callback();
        const end = performance.now();
        console.log(`[性能] ${name}: ${(end - start).toFixed(2)}ms`);
        return result;
    }
}

2. 单元测试示例

// 测试工具函数
function testYourFunctions() {
    // 测试数据处理
    const testData = [{ role: 'user', mes: 'Hello' }];
    const result = yourDataProcessor.processChatData(testData);
    
    console.assert(result.length === 1, '数据处理长度错误');
    console.assert(result[0].content.includes('**'), '内容增强失败');
    
    // 测试缓存功能
    const cache = new SmartCache();
    cache.set('test', 'value');
    console.assert(cache.get('test') === 'value', '缓存获取失败');
    
    console.log('所有测试通过');
}

最佳实践与注意事项

1. 代码组织规范

// 良好的代码组织结构
class YourExtension {
    // 静态属性
    static VERSION = '1.0.0';
    static DEFAULT_SETTINGS = {
        enabled: true,
        threshold: 0.5,
        mode: 'auto'
    };
    
    // 实例属性
    constructor() {
        this.initialized = false;
        this.processor = new DataProcessor();
        this.cache = new SmartCache();
    }
    
    // 初始化方法
    async initialize() {
        if (this.initialized) return;
        
        try {
            await this.loadSettings();
            this.setupEventListeners();
            this.initialized = true;
            DebugHelper.log('扩展初始化完成');
        } catch (error) {
            DebugHelper.error('初始化失败', error);
        }
    }
    
    // 设置管理
    async loadSettings() {
        this.settings = { 
            ...YourExtension.DEFAULT_SETTINGS, 
            ...extension_settings.yourExtension 
        };
    }
    
    async saveSettings() {
        extension_settings.yourExtension = this.settings;
        await saveSettingsDebounced();
    }
}

2. 错误处理与恢复

// 健壮的错误处理
class ErrorHandler {
    static async withRetry(operation, maxRetries = 3, delay = 1000) {
        let lastError;
        
        for (let attempt = 1; attempt <= maxRetries; attempt++) {
            try {
                return await operation();
            } catch (error) {
                lastError = error;
                DebugHelper.log(`尝试 ${attempt}/${maxRetries} 失败`, error);
                
                if (attempt < maxRetries) {
                    await new Promise(resolve => setTimeout(resolve, delay * attempt));
                }
            }
        }
        
        throw lastError;
    }
    
    static handleCriticalError(error) {
        console.error('严重错误:', error);
        toastr.error('扩展遇到严重错误，请检查控制台');
        
        // 禁用扩展以防止进一步错误
        extension_settings.yourExtension.enabled = false;
        saveSettingsDebounced();
    }
}

发布与维护指南

1. 版本管理与更新

{
    "version": "1.0.0",
    "changelog": {
        "1.0.0": "初始版本发布",
        "1.1.0": "新增高级功能",
        "1.2.0": "性能优化和bug修复"
    },
    "compatibility": {
        "min_st_version": "1.10.0",
        "max_st_version": "2.0.0"
    }
}

2. 用户文档编写

# 你的扩展使用指南

## 功能特性
- 实时消息处理
- 智能内容增强
- 可自定义设置

## 安装方法
1. 将扩展文件夹复制到 `public/scripts/extensions/`
2. 重启SillyTavern
3. 在扩展菜单中启用

## 配置说明
- **启用功能**: 控制扩展是否激活
- **处理阈值**: 设置处理敏感度
- **运行模式**: 选择自动或手动模式

通过本文的详细指导，您已经掌握了SillyTavern扩展开发的核心技术。从基础结构到高级功能，从调试技巧到发布维护，每个环节都为您提供了实用的代码示例和最佳实践。现在就开始打造您自己的AI功能模块，为SillyTavern生态贡献独特价值！

记住，优秀的扩展不仅需要强大的功能，更需要良好的用户体验和稳定的性能。在开发过程中始终以用户需求为中心，不断测试优化，您的扩展定能成为SillyTavern社区中的明星产品。

【免费下载链接】SillyTavern LLM Frontend for Power Users. 项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern