Code Reader
首页
帮助
设计文档
首页
帮助
设计文档
  • SillyTavern World Info(世界信息)系统深度分析

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)结构

字段名类型默认值说明
uidnumber自动生成条目唯一标识符
keystring[][]主关键词数组
keysecondarystring[][]次关键词数组(用于 Selective 逻辑)
commentstring""条目标题/备注
contentstring""条目内容(插入 Prompt 的文本)
constantbooleanfalse是否始终激活
vectorizedbooleanfalse是否使用向量化匹配
selectivebooleantrue是否启用 Selective 逻辑
selectiveLogicnumber0Selective 逻辑类型
ordernumber100插入顺序权重(值越大越靠前)
positionnumber0插入位置
depthnumber4深度插入位置(atDepth 时有效)
rolenumber0角色类型(atDepth 时有效)
probabilitynumber100激活概率(%)
useProbabilitybooleantrue是否启用概率激活
disablebooleanfalse是否禁用条目
ignoreBudgetbooleanfalse是否忽略预算限制
excludeRecursionbooleanfalse是否排除递归匹配
preventRecursionbooleanfalse是否阻止递归扫描
delayUntilRecursionboolean/numberfalse延迟到指定递归层级激活
scanDepthnumber?null自定义扫描深度
caseSensitiveboolean?null是否区分大小写
matchWholeWordsboolean?null是否匹配整词
useGroupScoringboolean?null是否使用分组评分
stickynumber?nullSticky 持续时间(消息数)
cooldownnumber?nullCooldown 持续时间(消息数)
delaynumber?null延迟激活(消息数)
groupstring""包含组名称
groupOverridebooleanfalse组覆盖优先级
groupWeightnumber100组内权重
characterFilterobjectnull角色过滤器
triggersstring[][]生成类型触发器
automationIdstring""自动化 ID
matchPersonaDescriptionbooleanfalse匹配角色描述
matchCharacterDescriptionbooleanfalse匹配角色卡描述
matchCharacterPersonalitybooleanfalse匹配角色性格
matchCharacterDepthPromptbooleanfalse匹配深度 Prompt
matchScenariobooleanfalse匹配场景
matchCreatorNotesbooleanfalse匹配创作者备注
outletNamestring""Outlet 名称
decoratorsstring[][]内容装饰器
hashnumber自动生成条目哈希值

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 匹配流程

  1. 文本缓冲区构建:从聊天记录中提取文本,根据扫描深度确定范围
  2. 主关键词匹配:检查 key 数组中的任意关键词是否匹配
  3. 次关键词匹配(Selective 启用时):根据 selectiveLogic 检查 keysecondary
  4. 评分计算(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 递归扫描原理

递归扫描允许已激活条目的内容触发其他条目:

  1. 初始扫描找到 Entry A
  2. Entry A 的内容被添加到递归缓冲区
  3. 下一次递归扫描时,缓冲区内容也参与匹配
  4. 如果 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 组内竞争机制

同一组的条目互斥,只有一个能激活:

  1. Sticky 优先:组内有 Sticky 条目时,其他条目自动淘汰
  2. 优先级覆盖:groupOverride 为 true 的条目优先
  3. 加权随机:按 groupWeight 进行加权随机选择
  4. 评分最高(启用时):关键词匹配得分最高的条目胜出

7.2 组配置

{
  group: "weapons",        // 组名
  groupOverride: false,    // 优先级覆盖
  groupWeight: 100         // 组内权重
}

8. 管理功能

8.1 API Endpoints

Endpoint方法功能
/api/worldinfo/listPOST列出所有世界书
/api/worldinfo/getPOST获取指定世界书
/api/worldinfo/editPOST编辑/保存世界书
/api/worldinfo/deletePOST删除世界书
/api/worldinfo/importPOST导入世界书

8.2 世界书绑定层级

  1. Chat Lore:绑定到当前对话
  2. Persona Lore:绑定到用户人格
  3. Character Lore:绑定到角色卡(Primary + Additional)
  4. 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. 性能考虑

  1. 缓存机制:世界书数据使用 StructuredCloneMap 缓存
  2. 防抖保存:编辑操作使用防抖机制减少保存频率
  3. 分页加载:条目编辑器使用分页(默认 25 条/页)
  4. 扫描深度限制:MAX_SCAN_DEPTH = 1000
  5. 递归步数限制:world_info_max_recursion_steps

12. 代码文件结构

文件功能
src/endpoints/worldinfo.js后端 API 端点
public/scripts/world-info.js前端核心逻辑(6153 行)

文档生成时间:2026-01-31基于 SillyTavern 源代码分析