SillyTavern World Info(世界信息)系统深度分析
概述
World Info(WI,又称 Lorebook)是 SillyTavern 角色扮演场景管理的核心功能。它允许用户创建可动态激活的文本条目,根据对话内容自动插入相关信息到 Prompt 中,从而丰富角色扮演的世界观和上下文。
1. World Info 数据结构
1.1 世界书(World Book)结构
// 世界书根结构
{
entries: {
[uid: number]: WIEntry // 以 UID 为键的条目映射
},
originalData?: { // 原始数据(用于兼容性)
entries: Array<WIEntry>
}
}
世界书存储在用户目录下的 worlds/ 文件夹中,每个世界书是一个独立的 JSON 文件(.json)。
1.2 条目(Entry)结构
| 字段名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
uid | number | 自动生成 | 条目唯一标识符 |
key | string[] | [] | 主关键词数组 |
keysecondary | string[] | [] | 次关键词数组(用于 Selective 逻辑) |
comment | string | "" | 条目标题/备注 |
content | string | "" | 条目内容(插入 Prompt 的文本) |
constant | boolean | false | 是否始终激活 |
vectorized | boolean | false | 是否使用向量化匹配 |
selective | boolean | true | 是否启用 Selective 逻辑 |
selectiveLogic | number | 0 | Selective 逻辑类型 |
order | number | 100 | 插入顺序权重(值越大越靠前) |
position | number | 0 | 插入位置 |
depth | number | 4 | 深度插入位置(atDepth 时有效) |
role | number | 0 | 角色类型(atDepth 时有效) |
probability | number | 100 | 激活概率(%) |
useProbability | boolean | true | 是否启用概率激活 |
disable | boolean | false | 是否禁用条目 |
ignoreBudget | boolean | false | 是否忽略预算限制 |
excludeRecursion | boolean | false | 是否排除递归匹配 |
preventRecursion | boolean | false | 是否阻止递归扫描 |
delayUntilRecursion | boolean/number | false | 延迟到指定递归层级激活 |
scanDepth | number? | null | 自定义扫描深度 |
caseSensitive | boolean? | null | 是否区分大小写 |
matchWholeWords | boolean? | null | 是否匹配整词 |
useGroupScoring | boolean? | null | 是否使用分组评分 |
sticky | number? | null | Sticky 持续时间(消息数) |
cooldown | number? | null | Cooldown 持续时间(消息数) |
delay | number? | null | 延迟激活(消息数) |
group | string | "" | 包含组名称 |
groupOverride | boolean | false | 组覆盖优先级 |
groupWeight | number | 100 | 组内权重 |
characterFilter | object | null | 角色过滤器 |
triggers | string[] | [] | 生成类型触发器 |
automationId | string | "" | 自动化 ID |
matchPersonaDescription | boolean | false | 匹配角色描述 |
matchCharacterDescription | boolean | false | 匹配角色卡描述 |
matchCharacterPersonality | boolean | false | 匹配角色性格 |
matchCharacterDepthPrompt | boolean | false | 匹配深度 Prompt |
matchScenario | boolean | false | 匹配场景 |
matchCreatorNotes | boolean | false | 匹配创作者备注 |
outletName | string | "" | Outlet 名称 |
decorators | string[] | [] | 内容装饰器 |
hash | number | 自动生成 | 条目哈希值 |
1.3 插入位置(Position)枚举
export const world_info_position = {
before: 0, // 角色卡描述之前
after: 1, // 角色卡描述之后
ANTop: 2, // Author's Note 顶部
ANBottom: 3, // Author's Note 底部
atDepth: 4, // 指定深度位置
EMTop: 5, // Example Messages 顶部
EMBottom: 6, // Example Messages 底部
outlet: 7, // 自定义 Outlet
};
1.4 Selective 逻辑类型
export const world_info_logic = {
AND_ANY: 0, // 主关键词 AND 任意次关键词
NOT_ALL: 1, // 主关键词 AND NOT 所有次关键词
NOT_ANY: 2, // 主关键词 AND NOT 任意次关键词
AND_ALL: 3, // 主关键词 AND 所有次关键词
};
2. World Info 激活流程
2.1 激活流程图
2.2 扫描状态机
export const scan_state = {
NONE: 0, // 停止扫描
INITIAL: 1, // 初始状态
RECURSION: 2, // 递归扫描
MIN_ACTIVATIONS: 3 // 最小激活扫描
};
3. 关键词匹配机制
3.1 匹配流程
- 文本缓冲区构建:从聊天记录中提取文本,根据扫描深度确定范围
- 主关键词匹配:检查
key数组中的任意关键词是否匹配 - 次关键词匹配(Selective 启用时):根据
selectiveLogic检查keysecondary - 评分计算(Group Scoring 启用时):计算匹配得分
3.2 匹配选项
| 选项 | 说明 |
|---|---|
caseSensitive | 区分大小写匹配 |
matchWholeWords | 整词匹配(使用正则边界) |
useGroupScoring | 使用分组评分 |
3.3 正则表达式支持
关键词支持正则表达式格式:/pattern/flags
// 示例
/key\d+/i // 匹配 key 后跟数字,不区分大小写
/\bfire\b/g // 匹配完整的单词 fire
3.4 Selective 逻辑详解
// AND_ANY:任意次关键词匹配即激活
if (selectiveLogic === world_info_logic.AND_ANY && hasSecondaryMatch) {
return true;
}
// NOT_ALL:所有次关键词都不匹配才激活
if (selectiveLogic === world_info_logic.NOT_ALL && !hasSecondaryMatch) {
return true;
}
// NOT_ANY:任意次关键词不匹配才激活
if (selectiveLogic === world_info_logic.NOT_ANY && !hasAnyMatch) {
return true;
}
// AND_ALL:所有次关键词都匹配才激活
if (selectiveLogic === world_info_logic.AND_ALL && hasAllMatch) {
return true;
}
4. 递归激活机制
4.1 递归扫描原理
递归扫描允许已激活条目的内容触发其他条目:
- 初始扫描找到 Entry A
- Entry A 的内容被添加到递归缓冲区
- 下一次递归扫描时,缓冲区内容也参与匹配
- 如果 Entry B 的关键词匹配 Entry A 的内容,Entry B 也被激活
4.2 递归控制选项
| 选项 | 说明 |
|---|---|
world_info_recursive | 全局启用递归扫描 |
world_info_max_recursion_steps | 最大递归步数 |
excludeRecursion | 条目不参与递归匹配 |
preventRecursion | 条目内容不进入递归缓冲区 |
delayUntilRecursion | 延迟到指定递归层级才激活 |
4.3 延迟递归层级
// 设置延迟到第 N 层递归
delayUntilRecursion: 2 // 条目仅在第 2 层递归时激活
delayUntilRecursion: true // 等同于 1
5. 时序效果(Timed Effects)
5.1 Sticky(粘性)
- 条目激活后在指定消息数内保持激活
- 不受关键词匹配状态影响
- 结束时可自动触发 Cooldown
5.2 Cooldown(冷却)
- 条目在指定消息数内无法再次激活
- 用于防止频繁触发
5.3 Delay(延迟)
- 条目在对话开始后 N 条消息内不激活
- 用于控制条目出现时机
6. Prompt 集成
6.1 插入位置详解
| Position | 位置 | 用途 |
|---|---|---|
before (0) | 角色卡描述之前 | 世界背景设定 |
after (1) | 角色卡描述之后 | 补充角色信息 |
ANTop (2) | Author's Note 顶部 | 高优先级提示 |
ANBottom (3) | Author's Note 底部 | 低优先级提示 |
atDepth (4) | 指定深度 | 动态插入到对话历史中 |
EMTop (5) | Example Messages 顶部 | 影响示例消息 |
EMBottom (6) | Example Messages 底部 | 影响示例消息 |
outlet (7) | 自定义 Outlet | 扩展使用 |
6.2 深度插入(Depth)
// 在对话历史的指定深度插入
{
position: world_info_position.atDepth,
depth: 4, // 插入到最近 4 条消息之前
role: extension_prompt_roles.SYSTEM // 系统角色
}
6.3 预算控制
world_info_budget:WI 占 Prompt 的最大比例(%)world_info_budget_cap:WI 最大 token 数上限ignoreBudget:条目忽略预算限制
7. 包含组(Inclusion Groups)
7.1 组内竞争机制
同一组的条目互斥,只有一个能激活:
- Sticky 优先:组内有 Sticky 条目时,其他条目自动淘汰
- 优先级覆盖:
groupOverride为 true 的条目优先 - 加权随机:按
groupWeight进行加权随机选择 - 评分最高(启用时):关键词匹配得分最高的条目胜出
7.2 组配置
{
group: "weapons", // 组名
groupOverride: false, // 优先级覆盖
groupWeight: 100 // 组内权重
}
8. 管理功能
8.1 API Endpoints
| Endpoint | 方法 | 功能 |
|---|---|---|
/api/worldinfo/list | POST | 列出所有世界书 |
/api/worldinfo/get | POST | 获取指定世界书 |
/api/worldinfo/edit | POST | 编辑/保存世界书 |
/api/worldinfo/delete | POST | 删除世界书 |
/api/worldinfo/import | POST | 导入世界书 |
8.2 世界书绑定层级
- Chat Lore:绑定到当前对话
- Persona Lore:绑定到用户人格
- Character Lore:绑定到角色卡(Primary + Additional)
- Global Lore:全局选择的世界书
绑定优先级(从高到低):Chat > Persona > Character > Global
8.3 导入导出
支持格式:
- SillyTavern JSON 格式
- NovelAI Lorebook 格式(自动转换)
- Agnai Memory Book 格式(自动转换)
- Risu Lorebook 格式(自动转换)
- 角色卡内嵌 Lorebook(PNG 格式)
9. 高级功能
9.1 角色过滤
characterFilter: {
isExclude: false, // true = 排除模式,false = 包含模式
names: [], // 角色名称列表
tags: [] // 标签 ID 列表
}
9.2 生成类型触发器
triggers: ["normal", "continue", "impersonate", "quiet"]
控制条目在何种生成类型下激活。
9.3 内容装饰器
// 在条目内容开头使用
@@activate // 强制激活(忽略关键词)
@@dont_activate // 强制不激活
9.4 自动化 ID
用于外部扩展(如 Quick Reply)控制条目。
10. 关键算法总结
10.1 扫描算法
1. 合并所有来源的条目(Chat/Persona/Character/Global)
2. 按 Order 降序排序
3. 初始化扫描缓冲区
4. 进入扫描循环:
- 检查每个条目的激活条件
- 执行概率检查
- 执行预算检查
- 确认激活并注入内容
- 决定下一扫描状态
5. 按 Position 分组构建 Prompt
10.2 关键词匹配算法
1. 构建扫描文本(聊天记录 + 全局数据)
2. 遍历主关键词:
- 支持正则表达式
- 支持整词匹配
- 支持大小写敏感/忽略
3. 如有次关键词,按 SelectiveLogic 检查
4. 返回匹配结果
11. 性能考虑
- 缓存机制:世界书数据使用
StructuredCloneMap缓存 - 防抖保存:编辑操作使用防抖机制减少保存频率
- 分页加载:条目编辑器使用分页(默认 25 条/页)
- 扫描深度限制:
MAX_SCAN_DEPTH = 1000 - 递归步数限制:
world_info_max_recursion_steps
12. 代码文件结构
| 文件 | 功能 |
|---|---|
src/endpoints/worldinfo.js | 后端 API 端点 |
public/scripts/world-info.js | 前端核心逻辑(6153 行) |
文档生成时间:2026-01-31基于 SillyTavern 源代码分析