SillyTavern 项目深度分析文档

项目: SillyTavern
版本: 1.15.0
许可证: AGPL-3.0
分析日期: 2026-02-01

项目概述

SillyTavern 是一个功能丰富的 LLM (Large Language Model) 前端应用，为高级用户提供与各种 AI 模型交互的界面。它支持多种 AI 后端（OpenAI、Claude、NovelAI、Kobold 等），具有强大的角色扮演功能、复杂的脚本系统和丰富的扩展生态。

核心特性

多 AI 后端支持: 30+ 种 AI 服务集成
角色卡系统: V2/V3/CharX 多格式支持
高级脚本引擎: STscript 斜杠命令系统
扩展生态: 14+ 内置扩展 + 第三方扩展支持
多用户架构: 完整的数据隔离和权限管理
世界信息系统: 动态上下文管理
向量记忆: 长期语义记忆

文档导航

1. 架构设计

文档	描述	关键内容
服务端架构	Express 服务端核心架构	启动流程、中间件链、安全机制、多用户架构
前端架构	客户端 JavaScript 架构	模块系统、Prompt 构建、状态管理
AI 后端集成	AI 服务集成系统	30+ 后端支持、Prompt 转换、密钥管理

2. 核心系统

文档	描述	关键内容
角色卡系统	角色数据管理	V2/V3/CharX 格式、PNG 元数据、缓存机制
聊天系统	聊天数据管理	JSONL 格式、备份机制、导入导出
世界信息系统	动态上下文管理	关键词匹配、插入策略、递归激活
Slash 命令系统	STscript 脚本引擎	命令解析、闭包、管道、调试

3. 扩展生态

文档	描述	关键内容
Slash 命令系统	STscript 脚本引擎	命令解析、闭包、管道、调试

3. 扩展生态

文档	描述	关键内容
扩展系统	扩展架构详解	14 个内置扩展、第三方扩展、服务端插件

项目结构概览

SillyTavern/
├── server.js                 # 入口文件
├── src/                      # 服务端源码
│   ├── server-main.js        # Express 应用配置
│   ├── server-startup.js     # 服务器启动逻辑
│   ├── users.js              # 用户系统
│   ├── constants.js          # 常量定义
│   ├── express-common.js     # Express 工具函数
│   ├── prompt-converters.js  # Prompt 转换器
│   ├── character-card-parser.js  # 角色卡解析
│   ├── plugin-loader.js      # 服务端插件加载
│   ├── endpoints/            # API 端点
│   │   ├── backends/         # AI 后端接口
│   │   ├── characters.js     # 角色管理
│   │   ├── chats.js          # 聊天管理
│   │   ├── worldinfo.js      # 世界信息
│   │   └── ...
│   ├── middleware/           # Express 中间件
│   └── vectors/              # 向量数据库适配器
├── public/                   # 前端资源
│   ├── scripts/              # 客户端脚本
│   │   ├── slash-commands/   # STscript 系统
│   │   ├── extensions/       # 扩展系统
│   │   ├── chats.js          # 聊天界面
│   │   ├── char-data.js      # 角色数据
│   │   ├── PromptManager.js  # Prompt 管理
│   │   └── ...
│   └── index.html            # 主页面
└── plugins/                  # 服务端插件目录

技术栈

服务端

技术	用途
Node.js 18+	运行时
Express.js	Web 框架
node-persist	本地存储
multer	文件上传
helmet	安全中间件
csrf-sync	CSRF 防护
Jimp (WASM)	图像处理

客户端

技术	用途
原生 ES Modules	模块系统
jQuery + jQuery UI	DOM 操作
Webpack	构建工具
Handlebars	模板引擎
highlight.js	代码高亮

AI 集成

类型	支持的后端
Chat Completions	OpenAI, Claude, OpenRouter, Gemini, Mistral, Cohere, DeepSeek, xAI 等 22+
Text Completions	Kobold, Ollama, llama.cpp, Tabby, vLLM 等 14+
图像生成	Stable Diffusion, NovelAI, DALL-E, ComfyUI
语音合成	ElevenLabs, Azure, OpenAI, Edge TTS 等 37+

核心架构图

系统整体架构

数据流架构

安全架构

SillyTavern 实现了多层安全防护：

网络层: IP Whitelist (可选)
传输层: SSL/HTTPS 支持
Host 层: Host Whitelist (防 DNS Rebinding)
认证层: Basic Auth / 用户账号系统
会话层: Cookie Session + CSRF Token
应用层: 登录中间件、权限检查

扩展开发

客户端扩展

// 基本结构
import { eventSource, event_types } from '../../../script.js';
import { extension_settings, getContext } from '../../extensions.js';

const MODULE_NAME = 'my-extension';

// 初始化
async function init() {
    // 加载设置
    if (!extension_settings[MODULE_NAME]) {
        extension_settings[MODULE_NAME] = {};
    }
    
    // 订阅事件
    eventSource.on(event_types.CHAT_CHANGED, () => {
        // 处理聊天切换
    });
}

await init();

服务端插件

// 必需导出
export const info = {
    id: 'my-plugin',
    name: 'My Plugin',
    description: '插件描述'
};

export async function init(router) {
    // 注册路由
    router.get('/status', (req, res) => {
        res.json({ status: 'ok' });
    });
}

export async function exit() {
    // 清理资源
}

关键文件速查

服务端核心

文件	职责
`server.js`	应用入口
`src/server-main.js`	Express 配置
`src/server-startup.js`	启动逻辑
`src/users.js`	用户系统
`src/constants.js`	常量定义
`src/prompt-converters.js`	Prompt 转换

客户端核心

文件	职责
`public/scripts/chats.js`	聊天管理
`public/scripts/char-data.js`	角色数据
`public/scripts/PromptManager.js`	Prompt 构建
`public/scripts/slash-commands/SlashCommandParser.js`	命令解析
`public/scripts/extensions.js`	扩展系统

分析维度覆盖

本分析文档库涵盖以下维度：

✅ 运行机制: 启动流程、生命周期、事件循环
✅ 领域模型: 角色卡、聊天消息、世界信息条目
✅ 架构设计: 分层边界、依赖注入、模块通信
✅ 核心业务逻辑: Prompt 构建、消息生成、数据转换
✅ 数据流与状态: 数据流转、状态管理、缓存机制
✅ 扩展性: Hook 系统、插件机制、扩展 API
✅ 性能与容错: 缓存策略、备份机制、请求取消
✅ 安全机制: 多层认证、CSRF 防护、输入校验

贡献与反馈

本文档库由深度项目分析自动生成，旨在帮助开发者理解 SillyTavern 的架构设计和实现原理。

如需了解更多细节，请查阅具体文档文件或访问官方资源：

GitHub: https://github.com/SillyTavern/SillyTavern
文档: https://docs.sillytavern.app/
Discord: https://discord.gg/sillytavern

本文档使用中文编写，保留所有英文技术术语、类名、方法名和文件名。