# 世界书激活业务逻辑说明

## 概述

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

## 核心流程

### 1. 数据收集阶段

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

1. **全局世界书** (`globalBooks`)
   - 来自前端传递的全局世界书列表
   - 所有对话都会检查这些世界书

2. **角色绑定世界书** (`characterBookId`)
   - 与当前角色卡绑定的世界书
   - 仅在该角色的对话中检查

### 2. 条目筛选阶段

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

#### 2.1 禁用状态检查
```python
if entry_data.get("disable", False):
    continue  # 跳过禁用的条目
```

#### 2.2 触发条件检查

支持四种触发类型：

##### A. 常驻触发 (constant)
- **配置**: `trigger_config.triggers.constant[0] == true`
- **行为**: 总是激活，无需任何条件
- **适用场景**: 角色基础设定、世界观背景等始终需要的信息

##### B. 关键词触发 (keyword)
- **配置**: 
  ```json
  {
    "key": ["关键词1", "关键词2"],
    "caseSensitive": false,
    "matchWholeWords": false
  }
  ```
- **检查范围**:
  - 用户当前输入 (`user_message`)
  - 聊天历史消息 (`chat_history`)
- **匹配模式**:
  - 大小写敏感/不敏感
  - 全词匹配/部分匹配
- **适用场景**: 当对话中提到特定概念时激活相关解释

##### C. 条件触发 (condition)
- **配置**:
  ```json
  {
    "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 | 宏替换 | - | 预留，待实现 |

#### 排序规则

```python
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 个
```

## 数据结构

### 前端发送的数据格式

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

### 后端返回的激活条目格式

```python
{
  "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()`**
   - 将位置编号转换为中文标签
   - 用于日志和前端显示

### 数据类型标准化

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

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

## 前端集成

### WebSocket 消息接收

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

```javascript
// 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` 组件按位置分组显示激活的条目：

```jsx
// 按位置分组
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个插入位置）
- ✅ 详细统计分析（按位置和触发类型）
- ✅ 完整日志记录（便于调试）

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