SillyTavern_replica/WORLDBOOK_ACTIVATION_LOGIC.md

世界书激活业务逻辑说明

概述

世界书（WorldBook）系统允许用户创建动态的知识条目，这些条目可以根据特定条件自动激活并注入到对话上下文中。本文档详细说明世界书条目的筛选和分类逻辑。

核心流程

1. 数据收集阶段

后端从两个来源加载世界书条目：

1. 全局世界书 (globalBooks)

   • 来自前端传递的全局世界书列表
   • 所有对话都会检查这些世界书

2. 角色绑定世界书 (characterBookId)

   • 与当前角色卡绑定的世界书
   • 仅在该角色的对话中检查

2. 条目筛选阶段

对每个世界书条目进行以下检查：

2.1 禁用状态检查

if entry_data.get("disable", False):
    continue  # 跳过禁用的条目

2.2 触发条件检查

支持四种触发类型：

A. 常驻触发 (constant)

• 配置: trigger_config.triggers.constant[0] == true
• 行为: 总是激活，无需任何条件
• 适用场景: 角色基础设定、世界观背景等始终需要的信息

B. 关键词触发 (keyword)

• 配置:

  {
    "key": ["关键词1", "关键词2"],
    "caseSensitive": false,
    "matchWholeWords": false
  }
  

• 检查范围:
  • 用户当前输入 (user_message)
  • 聊天历史消息 (chat_history)
• 匹配模式:
  • 大小写敏感/不敏感
  • 全词匹配/部分匹配
• 适用场景: 当对话中提到特定概念时激活相关解释

C. 条件触发 (condition)

• 配置:

  {
    "conditions": [
      {"text": "tb.力量 > 10"},
      {"text": "tb.态度 包括 \"友好\""}
    ]
  }
  

• 支持的语法:
  • 数值比较: tb.字段名 >/</>=/<=/==/!= 数值
  • 字符串相等: tb.字段名 = "值"
  • 字符串包含: tb.字段名 包括 "子串"
• 逻辑: 所有条件必须同时满足 (AND)
• 适用场景: 基于动态表格状态的 conditional 内容

D. RAG触发 (暂未实现)

• 预留接口，未来可支持向量检索激活

3. 位置分类阶段

激活的条目按插入位置进行分类和排序：

位置编号及含义

位置	标签	权重	说明
0	角色定义之后	高	AI读完人设紧接着就读到这里，适合补充角色的详细设定
1	角色定义之前	中	在角色卡内容的最上方，用于定义角色的基础背景
2	示例对话之前	低	在对话示例的最上方
3	示例对话之后	低	用于在对话开始前提供最后的上下文补充
4	系统提示/作者注释	极高	AI对最近看到的信息记忆最清晰，适合动态信息
5	作为系统消息	最高	强制作为System Prompt插入，用于强制指令
6	深度插入	-	预留，待实现
7	宏替换	-	预留，待实现

排序规则

active_entries.sort(key=lambda x: (x.position or 0, x.order or 0))

1. 主排序: 按 position 升序（位置编号小的先插入）
2. 次排序: 同位置内按 order 升序（order值小的先插入）

4. 统计与日志

激活完成后，生成详细的统计信息：

[WorldBook] 📊 激活统计:
  - 总激活条目数: 5
  - 按位置分布:
    * 角色定义之后 (pos=0): 2 个
    * 系统提示/作者注释 (pos=4): 3 个
  - 按触发类型分布:
    * constant: 2 个
    * keyword: 2 个
    * condition: 1 个

数据结构

前端发送的数据格式

{
  worldBookData: {
    globalBooks: [
      { id: "...", name: "全局世界书1" },
      { id: "...", name: "全局世界书2" }
    ],
    characterBookId: "角色绑定的世界书ID"
  },
  mes: "用户输入的消息",
  chatHistory: ["历史消息1", "历史消息2"],
  dynamicTableData: {
    currentValues: {
      "力量": 15,
      "态度": "友好"
    }
  }
}

后端返回的激活条目格式

{
  "type": "worldbook_active",
  "entries": [
    {
      "uid": "uuid-string",
      "content": "条目内容",
      "position": 0,
      "order": 100,
      "trigger_config": {...},
      ...
    }
  ]
}

实现细节

关键方法

1. _collect_and_activate_worldbooks()

   • 主入口方法
   • 负责加载世界书、检查激活条件、排序和统计

2. _check_entry_activation()

   • 检查单个条目的激活条件
   • 支持 constant、keyword、condition 三种触发类型

3. _check_keyword_trigger_with_config()

   • 关键词匹配逻辑
   • 支持大小写敏感和全词匹配选项

4. _parse_table_condition()

   • 解析动态表格条件表达式
   • 支持数值比较和字符串操作

5. _get_trigger_type()

   • 识别条目的触发类型
   • 用于日志和统计

6. _get_position_label()

   • 将位置编号转换为中文标签
   • 用于日志和前端显示

数据类型标准化

在激活前，对所有条目数据进行标准化处理：

def _normalize_worldbook_entry(entry_data):
    # content 必须是字符串
    # uid 必须是字符串
    # position 必须是整数
    # group 必须是列表或None

前端集成

WebSocket 消息接收

前端通过 WebSocket 接收激活条目：

// ChatBoxSlice.jsx
else if (data.type === 'worldbook_active') {
  console.log('[WebSocket] 📚 收到世界书激活信息:', data.entries.length, '个条目');
  import('../../Store/SideBarRight/WorldBookActiveSlice').then(module => {
    module.default.getState().setActiveEntries(data.entries);
  });
}

显示组件

WorldBookActive 组件按位置分组显示激活的条目：

// 按位置分组
const groupedEntries = activeEntries.reduce((acc, entry) => {
  const pos = entry.position || 0;
  if (!acc[pos]) acc[pos] = [];
  acc[pos].push(entry);
  return acc;
}, {});

// 渲染每个位置组
{Object.keys(groupedEntries).map(pos => (
  <div key={pos} className="position-group">
    <div className="position-label">
      {positionLabels[pos]} ({pos})
    </div>
    {/* 渲染该位置的所有条目 */}
  </div>
))}

扩展方向

短期优化

1. 添加概率触发支持 (probability 字段)
2. 实现RAG检索触发
3. 支持逻辑表达式触发 (logicExpression)

长期规划

1. 实现深度插入 (position=6)
2. 实现宏替换 (position=7)
3. 添加条目冲突解决机制
4. 支持条目依赖关系

调试建议

查看激活日志

后端会输出详细的激活日志：

[WorldBook] 📖 加载全局世界书 '测试世界书'，共 10 个条目
[WorldBook-Check] 📌 常驻触发 | UID: xxx-xxx-xxx
[WorldBook] ✅ 全局世界书 '测试世界书' 条目激活 | UID: xxx | 触发: constant | 位置: 角色定义之后
[WorldBook-Check] 🔑 关键词触发(用户输入) | UID: yyy | 匹配关键词: ['魔法']

常见问题排查

1. 条目未激活

   • 检查 disable 字段是否为 true
   • 检查触发条件配置是否正确
   • 查看日志中的 [WorldBook-Check] 输出

2. 位置不正确

   • 确认 position 字段是整数类型
   • 检查 order 字段的排序是否符合预期

3. 关键词不匹配

   • 检查 caseSensitive 设置
   • 检查 matchWholeWords 设置
   • 确认关键词拼写正确

总结

世界书激活系统实现了：

• ✅ 多源数据加载（全局 + 角色绑定）
• ✅ 多种触发类型（常驻、关键词、条件）
• ✅ 智能位置分类（8个插入位置）
• ✅ 详细统计分析（按位置和触发类型）
• ✅ 完整日志记录（便于调试）

这为动态上下文管理提供了强大的基础，可以根据对话内容智能地注入相关知识。