# VS Code 调试配置指南

本文档说明如何在 VS Code 中运行和调试 Agentic RAG 服务。

## 🚀 快速开始

### 1. 打开VS Code
```bash
cd /home/fl/code/ai-solution/agentic-rag-4
code .
```

### 2. 选择Python解释器
- 按 `Ctrl+Shift+P` 打开命令面板
- 输入 "Python: Select Interpreter"
- 选择 `.venv/bin/python` (项目虚拟环境)

## 🐛 调试配置

已配置了以下调试选项，可在"运行和调试"面板中使用：

### 1. Debug Agentic RAG Service
- **用途**: 直接调试服务主程序
- **端口**: 8000
- **特点**: 支持断点调试，实时代码重载

### 2. Debug Service with uvicorn
- **用途**: 使用uvicorn调试服务（推荐）
- **端口**: 8000
- **特点**: 更接近生产环境，支持热重载

### 3. Run Tests
- **用途**: 运行所有测试用例
- **特点**: 支持测试断点调试

### 4. Run Streaming Test
- **用途**: 运行流式API测试
- **特点**: 测试实际的流式响应

## 📋 如何使用

### 方法1: 使用VS Code调试面板
1. 点击左侧活动栏的"运行和调试"图标 (Ctrl+Shift+D)
2. 选择调试配置（推荐 "Debug Service with uvicorn"）
3. 点击绿色的"开始调试"按钮或按 F5

### 方法2: 使用调试启动器
```bash
python debug_service.py
```

### 方法3: 使用任务
1. 按 `Ctrl+Shift+P` 打开命令面板
2. 输入 "Tasks: Run Task"
3. 选择相应的任务（如 "Start Service"）

## 🔧 断点调试

### 设置断点
- 在代码行号左侧点击设置断点
- 红色圆点表示断点已设置

### 常用调试点
- `service/main.py:app` - 应用入口
- `service/graph/graph.py` - 核心逻辑
- `service/llm_client.py:astream` - LLM流式调用（你选中的代码）
- `service/config.py` - 配置加载

### 调试控制
- **F5**: 继续执行
- **F10**: 单步跳过
- **F11**: 单步进入
- **Shift+F11**: 单步跳出
- **Ctrl+Shift+F5**: 重启调试

## 🌐 服务端点

调试时服务运行在:
- **主页**: http://localhost:8000
- **健康检查**: http://localhost:8000/health
- **API文档**: http://localhost:8000/docs
- **聊天API**: http://localhost:8000/api/chat

## 📊 调试技巧

### 1. 查看变量
- 鼠标悬停在变量上查看值
- 使用"变量"面板查看作用域内的所有变量
- 使用"监视"面板添加表达式监视

### 2. 控制台调试
- 在"调试控制台"中执行Python表达式
- 例如: `config.get_llm_config()`

### 3. 异步调试
- 对于 `async` 函数，断点会在 `await` 处暂停
- 可以查看异步调用栈

### 4. 流式调试
- 在 `llm_client.py` 的 `astream` 方法设置断点
- 观察流式数据的生成过程

## 🛠️ 故障排除

### 问题1: 端口已占用
```bash
./stop_service.sh  # 停止现有服务
```

### 问题2: 模块导入错误
确保环境变量正确设置:
- `PYTHONPATH`: 项目根目录
- `CONFIG_FILE`: config.yaml路径

### 问题3: 配置文件找不到
确保 `config.yaml` 在项目根目录

### 问题4: 虚拟环境问题
```bash
uv sync  # 重新同步依赖
```

## 🔄 开发工作流

### 标准调试流程
1. 设置断点
2. 启动调试 (F5)
3. 发送测试请求
4. 在断点处检查状态
5. 修改代码
6. 热重载自动生效

### 测试流程
1. 运行 "Run Tests" 配置
2. 或使用任务 "Run Tests"
3. 查看测试结果

### 流式测试
1. 运行 "Run Streaming Test" 配置
2. 观察流式输出
3. 检查事件序列

## 📝 日志查看

### 调试模式日志
- 在VS Code终端中查看详细日志
- 日志级别: DEBUG

### 服务日志
```bash
tail -f server.log  # 查看服务日志
```

## 🎯 最佳实践

1. **使用条件断点**: 右键断点设置条件
2. **异常断点**: 设置在异常处暂停
3. **日志断点**: 不停止执行，只记录日志
4. **热重载**: 保存文件自动重启服务
5. **环境隔离**: 使用项目专用虚拟环境

---

现在你可以愉快地在VS Code中调试你的Agentic RAG服务了！🎉