SillyTavern_replica/WEBSOCKET_LOGS_EXAMPLE.md

# WebSocket 链路详细日志示例

本文档展示了添加详细日志后，WebSocket 链路的完整输出示例。

## 后端日志输出示例

### 1. 连接建立

```
================================================================================
[WebSocket] 📡 连接建立: 互动小说家/赛博朋克-数据幽灵
================================================================================

INFO:     connection open
```

### 2. 接收请求

```
--------------------------------------------------------------------------------
[WebSocket] 📨 收到请求:
  - Floor: 6
  - Role: 互动小说家
  - Chat: 赛博朋克-数据幽灵
  - Stream: True
  - Message Length: 45
--------------------------------------------------------------------------------

[WebSocket] 🌊 进入流式处理模式
[StreamChat] 🚀 开始流式处理
```

### 3. 工作流处理

```
################################################################################
[ChatWorkflow-Stream] 🚀 开始处理请求
  - Role: 互动小说家
  - Chat: 赛博朋克-数据幽灵
  - Message Length: 45
################################################################################

[ChatWorkflow-Stream] ✅ 已加载角色卡: 互动小说家

[ChatWorkflow-Stream] 📚 世界书激活结果: 0 个条目

[ChatWorkflow-Stream] 💬 聊天历史加载结果: 0 条消息

[ChatWorkflow-Stream] 📝 提示词组装结果: 3 条消息
    1. [system] 你是一个互动小说家，擅长创作赛博朋克风格的故...
    2. [user] 请描述一个数据幽灵在夜之城中的冒险...
    3. [assistant] ...

[ChatWorkflow-Stream] 🤖 开始流式调用 LLM
  - Model: gpt-4
  - Temperature: 1.0
  - Max Tokens: 30000
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```

### 4. LLM 客户端调用

```
[LLMClient] 🔧 创建 ChatOpenAI 实例
  - Model: gpt-4
  - API URL: https://api.openai.com/v1
  - Temperature: 1.0
  - Max Tokens: 30000

[LLMClient] 🚀 开始流式请求...
```

### 5. 流式输出进度

```
[ChatWorkflow-Stream] 📊 已接收 20 个 chunks, 当前长度: 156
[StreamChat] 📤 已发送 10 个 chunks

[ChatWorkflow-Stream] 📊 已接收 40 个 chunks, 当前长度: 312
[StreamChat] 📤 已发送 20 个 chunks

[ChatWorkflow-Stream] 📊 已接收 60 个 chunks, 当前长度: 478
[StreamChat] 📤 已发送 30 个 chunks
```

### 6. LLM 调用完成

```
[LLMClient] ✅ 流式请求完成
  - 总 Chunks: 85
  - 耗时: 3.45秒
  - Prompt Tokens: 256
  - Completion Tokens: 512
  - Total Tokens: 768

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[ChatWorkflow-Stream] ✅ LLM 流式调用完成
  - 总 Chunks: 85
  - 内容长度: 680
################################################################################

```

### 7. 发送响应

```
[StreamChat] ✨ 流式生成成功，总长度: 680

[StreamChat] 📚 发送世界书激活信息: 0 个条目

[StreamChat] ✅ 发送完成信号

[StreamChat] 💾 保存消息到文件...
[WebSocket] 消息已保存: 互动小说家/赛博朋克-数据幽灵
[StreamChat] ✅ 消息保存完成

```

### 8. 连接断开

```
================================================================================
[WebSocket] 🔌 连接断开: 互动小说家/赛博朋克-数据幽灵
================================================================================
```

## 前端日志输出示例

### 1. 建立连接

```javascript
================================================================================
[WebSocket] 📡 连接已建立
  - URL: ws://localhost:23337/api/chat/%E4%BA%92%E5%8A%A8%E5%B0%8F%E8%AF%B4%E5%AE%B6/%E8%B5%9B%E5%8D%9A%E6%9C%8B%E5%85%8B-%E6%95%B0%E6%8D%AE%E5%B9%BD%E7%81%B5/ws
  - Ready State: 1
================================================================================
```

### 2. 发送消息

```javascript
--------------------------------------------------------------------------------
[WebSocket] 📤 发送消息:
  - Floor: 6
  - Role: 互动小说家
  - Chat: 赛博朋克-数据幽灵
  - Stream: true
  - Message Length: 45
--------------------------------------------------------------------------------
```

### 3. 接收流式数据

```javascript
[WebSocket] 📊 已接收 10 个 chunks
[WebSocket] 📊 已接收 20 个 chunks
[WebSocket] 📊 已接收 30 个 chunks
```

### 4. 接收其他消息类型

```javascript
[WebSocket] 📚 收到世界书激活信息: 0 个条目
[WebSocket] 📋 收到任务ID信息: {imageWorkflow: "img_xxx", dynamicTable: "tbl_xxx"}
```

### 5. 完成信号

```javascript
[WebSocket] ✅ 收到完成信号
  - 总 Chunks: 85
  - 消息长度: 680
```

### 6. 连接关闭

```javascript
================================================================================
[WebSocket] 🔌 连接已关闭
  - Code: 1000
  - Reason: 
  - Was Clean: true
================================================================================
```

## 错误情况日志示例

### 1. LLM 调用失败

```
[LLMClient] ❌ 流式调用失败: API key is invalid
Traceback (most recent call last):
  File "backend/utils/llm_client.py", line 278, in stream_chat
    async for chunk in llm.astream(messages):
  ...
openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key'}}
```

### 2. 工作流处理失败

```
[ChatWorkflow-Stream] ⚠️ 错误: 角色 '不存在的角色' 不存在
Traceback (most recent call last):
  File "backend/services/chat_workflow_service.py", line 765, in process_chat_request_stream
    return {
  ...
```

### 3. WebSocket 错误

```
================================================================================
[WebSocket] ⚠️ 错误: Connection closed unexpectedly
================================================================================
```

## 日志级别说明

### 符号含义

- 📡 - 连接相关
- 📨 - 接收消息
- 📤 - 发送消息
- 🚀 - 开始处理
- ✅ - 成功完成
- ❌ - 错误/失败
- 📊 - 进度统计
- 📚 - 世界书相关
- 📋 - 任务相关
- 💬 - 聊天历史
- 📝 - 提示词
- 🤖 - LLM 调用
- 💾 - 文件保存
- 🔌 - 连接断开
- ⚠️ - 警告

### 分隔符

- `=` (80个) - 重要事件边界（连接建立/断开）
- `-` (80个) - 请求边界
- `#` (80个) - 工作流处理边界
- `~` (80个) - LLM 调用边界

## 日志配置建议

### 开发环境

在开发环境中，显示所有日志以便调试：

```python
# 保持当前的详细日志输出
```

### 生产环境

在生产环境中，可以简化日志：

```python
# 只记录关键事件
print(f"[WebSocket] 连接建立: {role_name}/{chat_name}")
print(f"[WebSocket] 收到请求: floor={request_data.get('floor')}")
print(f"[WebSocket] 生成完成，内容长度: {len(content)}")
```

## 日志分析工具

### 提取关键指标

```bash
# 统计平均响应时间
grep "耗时:" logs.txt | awk '{sum += $2; count++} END {print "平均耗时:", sum/count, "秒"}'

# 统计 Token 使用
grep "Total Tokens:" logs.txt | awk '{sum += $3; count++} END {print "平均 Token:", sum/count}'

# 统计错误率
grep "❌" logs.txt | wc -l
```

### 实时监控

```bash
# 实时查看 WebSocket 日志
tail -f logs.txt | grep --line-buffered "WebSocket\|StreamChat\|ChatWorkflow\|LLMClient"
```

## 性能优化建议

基于日志分析：

1. **如果 LLM 调用耗时过长** (>10秒)
   - 检查网络连接
   - 考虑使用更快的模型
   - 减少 max_tokens

2. **如果 Chunk 数量过多** (>200)
   - 检查是否启用了不必要的功能
   - 优化提示词长度

3. **如果世界书激活数量过多** (>10)
   - 检查触发条件是否过于宽松
   - 优化关键词匹配

4. **如果聊天历史加载失败**
   - 检查 CHATS_PATH 配置
   - 确认文件权限

## 总结

通过详细的日志记录，可以：

1. ✅ 清晰地追踪 WebSocket 的完整链路
2. ✅ 快速定位问题所在
3. ✅ 分析性能瓶颈
4. ✅ 监控系统运行状态
5. ✅ 优化用户体验

建议在开发和测试阶段使用详细日志，在生产环境中根据需要调整日志级别。