# Debug 模式使用指南

## 📋 概述

Debug 模式提供了完整的 AI 对话日志输出功能，可以在终端中看到所有原始回答和输出结果。

## 🎯 功能特性

### 1. 用户消息显示
在 debug 模式下，所有用户发送的消息都会在终端中显示：
```
================================================================================
[DEBUG] 👤 用户消息:
帮我计算 1+1 等于多少
================================================================================
```

### 2. AI 推理过程显示
如果 AI 模型支持推理功能，会实时显示推理内容：
```
[DEBUG] 🧠 AI 推理：用户想要一个简单的数学计算...
```

### 3. AI 实时回答显示
AI 的回答会实时逐字显示在终端中：
```
[DEBUG] 🤖 AI: 1+1 等于 2
[DEBUG] 🤖 AI: 。
```

### 4. 对话循环信息
显示当前对话的轮次和循环状态：
```
[DEBUG] 🔄 开始对话循环，最大循环次数：5

[DEBUG] 📍 第 1 轮对话
```

### 5. 命令解析和执行
显示 AI 生成命令的解析和执行过程：
```
[DEBUG] 🔍 解析并执行命令...

[DEBUG] 📋 命令执行结果:
✓ 执行成功：execute_command
  结果：{"output": "2"}

执行了 1 个命令，成功 1 个，失败 0 个
```

### 6. 循环状态跟踪
显示对话循环的进行状态和结束原因：
```
[DEBUG] ✅ 对话循环结束
```
或
```
[DEBUG] ⚠️ 已达到最大循环次数 5，停止
```

## 🔧 启用方法

### 方法 1: 在 .env 文件中配置

编辑 `.env` 文件，添加或修改以下配置：
```ini
# 启用 Debug 模式
DEBUG_MODE=true
```

### 方法 2: 在命令行参数中指定

运行程序时添加 `--debug` 参数：
```bash
python src/main.py --debug
```

### 方法 3: 在 PowerShell 脚本中配置

编辑 `start_app.ps1` 文件，在运行参数中添加：
```powershell
$env:DEBUG_MODE = "true"
```

## 📊 输出示例

### 完整对话流程

```
[DEBUG] 🔄 开始对话循环，最大循环次数：5

[DEBUG] 📍 第 1 轮对话

================================================================================
[DEBUG] 👤 用户消息:
打开浏览器并访问百度
================================================================================

[DEBUG] 🧠 AI 推理：用户想要打开浏览器并访问百度，我需要先检查系统权限...
[DEBUG] 🤖 AI: 好的，我来帮你打开浏览器并访问百度。
[DEBUG] 🤖 AI: 首先让我检查一下系统权限。
[DEBUG] 🤖 AI: <control>{"type": "get_system_info"}</control>

[DEBUG] 🔍 解析并执行命令...

[DEBUG] 📋 命令执行结果:
✓ 执行成功：get_system_info
  结果：{"screen_width": 1920, "screen_height": 1080, "permission": "full"}

执行了 1 个命令，成功 1 个，失败 0 个

[DEBUG] 📍 第 2 轮对话

[DEBUG] 🧠 AI 推理：权限检查通过，现在执行打开浏览器的操作...
[DEBUG] 🤖 AI: 现在我来打开浏览器。
[DEBUG] 🤖 AI: <control>{"type": "execute_command", "command": "start msedge https://www.baidu.com"}</control>

[DEBUG] 🔍 解析并执行命令...

[DEBUG] 📋 命令执行结果:
✓ 执行成功：execute_command
  结果：{"output": ""}

执行了 1 个命令，成功 1 个，失败 0 个

[DEBUG] ✅ 对话循环结束
```

## 🎨 颜色说明

Debug 输出使用了不同的颜色来区分不同类型的信息：

| 颜色 | 说明 | 内容 |
|------|------|------|
| 🟢 绿色 | 用户消息 | 用户发送的原始消息 |
| ⚪ 灰色 | AI 推理 | AI 的思考过程（如果模型支持） |
| 🔵 蓝色 | AI 回答 | AI 的实时回答内容 |
| 🟡 黄色 | 系统信息 | 循环状态、命令执行结果等 |

## ⚙️ 配置选项

### DEBUG_MODE
- **类型**: Boolean
- **默认值**: false
- **说明**: 是否启用 debug 模式
- **可选值**: true, false

### 相关配置
- **NO_COLOR**: 设置为任何值将禁用颜色输出
- **LOG_LEVEL**: 日志级别（如果同时启用了日志功能）

## 📝 注意事项

1. **性能影响**: Debug 模式会增加终端输出，可能略微影响性能
2. **日志文件**: Debug 模式下建议同时启用日志保存功能（-nolog 参数会禁用）
3. **生产环境**: 生产环境中建议关闭 debug 模式以减少日志输出
4. **颜色支持**: 如果终端不支持颜色，输出会自动禁用颜色格式

## 🔍 故障排除

### 问题：看不到颜色输出
**解决方案**: 
- 检查终端是否支持 ANSI 颜色
- 确保没有设置 `NO_COLOR` 环境变量

### 问题：看不到 debug 输出
**解决方案**:
- 确认 `DEBUG_MODE=true` 已正确设置
- 检查 `.env` 文件是否被正确加载
- 确认程序启动时使用了 `--debug` 参数

### 问题：输出太多难以查看
**解决方案**:
- 使用终端的滚动功能查看历史输出
- 将输出重定向到文件：`python src/main.py --debug > debug.log 2>&1`
- 使用日志文件保存功能（debug 模式默认开启）

## 💡 最佳实践

1. **开发调试**: 开发时启用 debug 模式，便于查看 AI 行为
2. **问题诊断**: 遇到问题时启用 debug 模式，分析 AI 决策过程
3. **性能测试**: 性能测试时关闭 debug 模式，减少输出影响
4. **日志分析**: 结合日志文件分析，debug 输出 + 日志文件双重记录