SillyTavern 前端架构分析

// lib.js 中整合的核心库
import {
    showdown,        // Markdown 渲染
    moment,          // 日期时间处理
    DOMPurify,       // HTML 净化
    hljs,            // 代码高亮
    Handlebars,      // 模板引擎
    SVGInject,       // SVG 注入
    Popper,          // 浮动元素定位
    Fuse,            // 模糊搜索
    Readability,     // 网页内容提取
    lodash,          // 工具函数库
    localforage,     // 本地存储
} from './lib.js';

export {
    characters,          // 角色列表
    chat,                // 当前聊天记录
    this_chid,           // 当前角色ID
    eventSource,         // 事件发射器
    event_types,         // 事件类型枚举
    main_api,            // 当前使用的API类型
    getContext,          // 获取上下文
    substituteParams,    // 参数替换
    // ... 更多
}

// 消息附件处理
export async function populateFileAttachment(message, inputId)
export async function uploadFileAttachment(fileName, base64Data)
export async function getFileAttachment(url)

// 消息可见性控制
export async function hideChatMessageRange(start, end, unhide, nameFilter)

// 样式处理
export function encodeStyleTags(text)
export function decodeStyleTags(text, options)
export function formatCreatorNotes(text, avatarId)

/**
 * @typedef {object} v2CharData
 * @property {string} name - 角色名称
 * @property {string} description - 角色描述
 * @property {string} personality - 性格特征
 * @property {string} scenario - 场景设定
 * @property {string} first_mes - 开场消息
 * @property {string} mes_example - 对话示例
 * @property {v2WorldInfoBook} character_book - 世界信息书
 * @property {v2CharDataExtensionInfos} extensions - 扩展数据
 */

/**
 * @typedef {object} v1CharData
 * @property {string} name
 * @property {string} description
 * @property {string} personality
 * @property {string} avatar - 头像文件名（唯一标识）
 * @property {v2CharData} data - v2 数据扩展
 */

export {
    selected_group,           // 当前选中的群组ID
    is_group_generating,      // 群组生成状态
    groups,                   // 群组列表
    generateGroupWrapper,     // 群组消息生成
    saveGroupChat,            // 保存群组聊天
    // ...
}

export const group_generation_mode = {
    SWAP: 0,           // 切换角色回复
    APPEND: 1,         // 追加角色回复
    APPEND_DISABLED: 2 // 禁用追加
};

export const group_activation_strategy = {
    NATURAL: 0,        // 自然模式
    LIST: 1,           // 列表模式
    MANUAL: 2,         // 手动模式
    POOLED: 3,         // 池化模式
};

export const chat_completion_sources = {
    OPENAI: 'openai',
    CLAUDE: 'claude',
    OPENROUTER: 'openrouter',
    AI21: 'ai21',
    MAKERSUITE: 'makersuite',
    VERTEXAI: 'vertexai',
    MISTRALAI: 'mistralai',
    CUSTOM: 'custom',
    COHERE: 'cohere',
    // ... 更多
};

// 消息类
class Message {
    constructor(role, content, name = '')
}

// 消息集合类
class MessageCollection {
    constructor()
    add(message)
    hasItemWithIdentifier(identifier)
    getItemByIdentifier(identifier)
}

// Token 处理器
class TokenHandler {
    constructor(getTokenCountCallback)
    count(text, padding = 0)
    getCounts()
}

// Prompt 类
class Prompt {
    constructor({
        identifier,      // 唯一标识
        role,            // 角色（system/user/assistant）
        content,         // 内容
        name,            // 显示名称
        system_prompt,   // 是否为系统 Prompt
        position,        // 位置
        injection_depth, // 注入深度
        injection_position, // 注入位置（0=相对, 1=绝对）
        injection_order, // 注入顺序
        injection_trigger, // 触发条件
        forbid_overrides, // 禁止覆盖
    })
}

// Prompt 集合类
export class PromptCollection {
    collection = []
    overriddenPrompts = []
    
    add(...prompts)
    set(prompt, position)
    get(identifier)
    override(prompt, position)
}

// Prompt 管理器
class PromptManager {
    constructor()
    init(moduleConfiguration, serviceSettings)
    render(afterTryGenerate = true)
    
    // Prompt 操作
    getPromptById(identifier)
    addPrompt(prompt, identifier)
    updatePromptByIdentifier(identifier, updatePrompt)
    
    // 角色相关
    getPromptsForCharacter(character, onlyEnabled = false)
    getPromptOrderForCharacter(character)
    appendPrompt(prompt, character)
    detachPrompt(prompt, character)
}

get promptSources() {
    return {
        charDescription: 'Character Description',
        charPersonality: 'Character Personality',
        scenario: 'Character Scenario',
        personaDescription: 'Persona Description',
        worldInfoBefore: 'World Info (↑Char)',
        worldInfoAfter: 'World Info (↓Char)',
    };
}

export function escapeHtml(str)
export function sanitizeSelector(str, replacement = '_')
export function isValidUrl(value)
export function isUuid(value)
export function convertValueType(value, type)
export function extractAllWords(value)
export function escapeRegex(string)

export function download(content, fileName, contentType)
export function getFileText(file)
export function getFileBuffer(file)
export function getBase64Async(file)
export function parseJsonFile(file)

export function debounce(func, timeout)
export function throttle(func, limit)
export function debouncedThrottle(func, limit)
export function delay(ms)

export function deepMerge(target, source)
export function shuffle(array)
export function splitRecursive(input, length, delimiters)
export function humanFileSize(bytes, si = false, dp = 1)

// PromptManager.js 中的处理流程
class PromptManager {
    render(afterTryGenerate = true) {
        // 1. 等待当前生成完成
        waitUntilCondition(() => !is_send_press && !is_group_generating)
            .then(async () => {
                // 2. 执行干运行（dry-run）以确定上下文组成
                this.tryGenerate().finally(async () => {
                    // 3. 渲染 Prompt 管理器 UI
                    await this.renderPromptManager();
                    await this.renderPromptManagerListItems();
                });
            });
    }
}

// openai.js 中的消息准备
function prepareOpenAIMessages({
    promptManager,       // Prompt 管理器实例
    mesExamples,         // 对话示例
    chatHistory,         // 聊天历史
    systemPrompt,        // 系统 Prompt
    userPrompt,          // 用户 Prompt
    contextSize,         // 上下文大小限制
}) {
    // 1. 创建消息集合
    const messageCollection = new MessageCollection();
    
    // 2. 添加系统级 Prompt
    const systemPrompts = promptManager.getPromptsForCharacter(character, true);
    for (const prompt of systemPrompts) {
        if (prompt.injection_position === INJECTION_POSITION.RELATIVE) {
            // 相对位置：添加到消息流中
            messageCollection.add(new Message(prompt.role, content, prompt.name));
        }
    }
    
    // 3. 添加对话示例
    if (mesExamples && mesExamples.length > 0) {
        for (const example of mesExamples) {
            messageCollection.add(example);
        }
    }
    
    // 4. 添加聊天历史（带 Token 截断）
    const tokenHandler = new TokenHandler(getTokenCountCallback);
    for (const message of chatHistory) {
        // Token 检查与截断逻辑
        if (tokenHandler.count(message.content) > contextSize) {
            break;
        }
        messageCollection.add(message);
    }
    
    // 5. 处理绝对位置注入
    for (const prompt of systemPrompts) {
        if (prompt.injection_position === INJECTION_POSITION.ABSOLUTE) {
            // 绝对位置：在指定深度插入
            messageCollection.insertAtDepth(prompt.injection_depth, 
                new Message(prompt.role, content, prompt.name));
        }
    }
    
    return messageCollection;
}

// TokenHandler 类
class TokenHandler {
    constructor(getTokenCountCallback) {
        this.getTokenCount = getTokenCountCallback;
        this.counts = {};
    }
    
    count(text, padding = 0) {
        const tokens = this.getTokenCount(text) + padding;
        return tokens;
    }
    
    // 上下文填充策略
    fillContext(messages, maxTokens) {
        let totalTokens = 0;
        const result = [];
        
        // 从最新消息开始反向遍历
        for (let i = messages.length - 1; i >= 0; i--) {
            const message = messages[i];
            const tokens = this.count(message.content);
            
            if (totalTokens + tokens <= maxTokens) {
                result.unshift(message);
                totalTokens += tokens;
            } else {
                // 超出限制，停止添加
                break;
            }
        }
        
        return result;
    }
}

// 全局策略（默认）
configuration.promptOrder.strategy = 'global';
// 所有角色共享相同的 Prompt 顺序

// 角色特定策略
configuration.promptOrder.strategy = 'character';
// 每个角色有独立的 Prompt 顺序配置

// prompt_order 存储结构
this.serviceSettings.prompt_order = [
    {
        character_id: 'character-uuid',
        order: [
            { identifier: 'main', enabled: true },
            { identifier: 'nsfw', enabled: false },
            { identifier: 'jailbreak', enabled: true },
            { identifier: 'charDescription', enabled: true },
            // ...
        ]
    }
];

export const POPUP_TYPE = {
    TEXT: 1,        // 文本弹窗
    CONFIRM: 2,     // 确认弹窗
    INPUT: 3,       // 输入弹窗
    DISPLAY: 4,     // 展示弹窗
    CROP: 5,        // 图片裁剪弹窗
};

export const POPUP_RESULT = {
    AFFIRMATIVE: 1, // 确认
    NEGATIVE: 0,    // 否定
    CANCELLED: null,// 取消
    CUSTOM1: 1001,  // 自定义 1
    // ...
};

export class Popup {
    constructor(content, type, inputValue, options)
    async show()
    completeAffirmative()
    completeNegative()
    completeCancelled()
}

// 便捷函数
export async function callGenericPopup(content, type, inputValue, options)

export function renderTemplate(templateId, data)
export async function renderTemplateAsync(templateId, data)

export class DragAndDropHandler {
    constructor(options)
    init()
    handleDrop(event)
}

// 核心全局状态
let characters = [];           // 所有角色数据
let chat = [];                 // 当前聊天记录
let this_chid = null;          // 当前选中角色ID
let selected_group = null;     // 当前选中群组ID
let main_api = 'openai';       // 当前使用的API
let is_send_press = false;     // 是否正在发送

export const power_user = {
    tokenizer: tokenizers.BEST_MATCH,    // 分词器选择
    token_padding: 64,                   // Token 填充
    collapse_newlines: false,            // 折叠换行
    pin_examples: false,                 // 固定示例
    chat_truncation: 100,                // 聊天截断
    streaming_fps: 30,                   // 流式 FPS
    // ... 更多设置
};

// 与特定聊天绑定的变量
chat_metadata.variables = {
    key: value
}

// 1. accountStorage - 用户账户相关
// 2. localStorage - 浏览器本地存储
// 3. localforage - IndexedDB 大容量存储

export const tokenizers = {
    NONE: 'none',
    GPT3: 'gpt3',
    GPT4: 'gpt4',
    CLAUDE: 'claude',
    LLAMA: 'llama',
    BEST_MATCH: 'best_match',
    // ...
};

export function getTokenCount(str, padding = undefined)
export async function getTokenCountAsync(str, padding = undefined)
export function getFriendlyTokenizerName(forApi)

// extensions.js
export async function initExtensions()
export function loadExtensionSettings()
export function runGenerationInterceptors(promptData)

globalThis.SillyTavern = {
    libs,           // 第三方库
    getContext,     // 获取应用上下文
};

// events.js
export const event_types = {
    // 消息事件
    MESSAGE_RECEIVED: 'message_received',
    MESSAGE_EDITED: 'message_edited',
    MESSAGE_DELETED: 'message_deleted',
    MESSAGE_SWIPED: 'message_swiped',
    
    // 角色事件
    CHARACTER_SELECTED: 'character_selected',
    CHARACTER_EDITED: 'character_edited',
    CHARACTER_DELETED: 'character_deleted',
    
    // 聊天事件
    CHAT_CHANGED: 'chat_changed',
    CHAT_CREATED: 'chat_created',
    CHAT_DELETED: 'chat_deleted',
    
    // 设置事件
    SETTINGS_LOADED: 'settings_loaded',
    OAI_PRESET_CHANGED: 'oai_preset_changed',
    
    // 生成事件
    GENERATION_STARTED: 'generation_started',
    GENERATION_ENDED: 'generation_ended',
    GENERATION_STOPPED: 'generation_stopped',
};

export const eventSource = new EventEmitter();