---
outline: deep
---

# 故障排查指南

本文档帮助用户和开发者排查 ChatLab 使用中遇到的问题。

## 日志文件

**获取日志文件**：软件左下角的 **「设置」 > 「存储管理」 > 「日志文件」 > 打开目录**

日志存储在 `文档/ChatLab/logs/` 目录下：

```
ChatLab/logs/
├── app.log                              # 主程序日志
├── ai/                                  # AI 相关日志
│   └── ai_YYYY-MM-DD_HH-mm.log
└── import/                              # 导入日志
    └── import_{sessionId}_{timestamp}.log
```

### 日志文件说明

| 目录/文件      | 内容                                             |
| -------------- | ------------------------------------------------ |
| `app.log`      | 主程序日志，包含文件解析、数据库操作、IPC 通信等 |
| `ai/*.log`     | AI 日志，包含 LLM 调用、Agent 执行、工具调用等   |
| `import/*.log` | 导入性能日志，包含导入速度、内存使用、各阶段耗时 |

## 常见问题

### 1. 导入失败

**症状**：拖入文件后提示解析失败

**排查步骤**：

1. 确认文件格式是否支持（.json / .jsonl / .txt）
2. 检查文件是否损坏（用文本编辑器打开查看）
3. 查看日志文件中的 `[Parser]` 相关错误

### 2. AI 功能无响应

**症状**：AI 实验室发送消息后无回复

**排查步骤**：

1. 检查是否已配置 API Key（设置 > AI 设置）
2. 点击「验证」，确认 API 连接正常
3. 查看日志文件中的 `[LLM]` 或 `[Agent]` 相关错误

**常见原因**：

- API Key 无效或余额不足
- API 服务商限流

### 3. 数据库错误

**症状**：打开会话时提示错误

**排查步骤**：

1. 查看日志文件中的 `[Database]` 相关错误
2. 检查数据库文件是否存在

## 反馈问题

如果以上方法无法解决问题，请：

1. 收集日志文件
2. 描述问题复现步骤
3. 提交 Issue 到 GitHub

**提交 Issue 时请包含**：

- 操作系统及版本
- ChatLab 版本
- 问题描述及复现步骤
- 相关日志片段（注意脱敏）