准备开始重构日志模块。

docs/3.日志规范化改造建议.md

@@ -0,0 +1,473 @@
+Read file: docs/日志服务使用清单.md
+Read file: docs/全局log服务改造方案_优化版.md
+现在我来为您创建一份完整的日志规范化改造文档：
+
+Read file: docs/日志服务改造检查报告.md
+现在我来创建一份完整的日志规范化改造文档：
+
+# 日志规范化改造实施方案
+
+## 1. 项目概述
+
+### 1.1 改造目标
+将项目从分散的日志管理方式统一为中央化的日志管理系统，实现：
+- 统一的日志服务架构
+- 模块独立的日志配置
+- 支持API和命令行两种运行模式
+- 自动日志轮转和清理
+- 灵活的上下文管理
+
+### 1.2 当前问题分析
+经过代码分析，发现以下主要问题：
+
+1. **日志体系分散**：存在3套独立的日志管理器
+   - `core/logging/log_manager.py` - 中央日志管理器
+   - `data_pipeline/dp_logging/manager.py` - 数据管道独立日志
+   - `react_agent/logger.py` - React Agent独立日志
+
+2. **print语句残留**：多个模块仍使用print输出
+3. **配置不统一**：各模块使用不同的日志配置方式
+4. **文件管理混乱**：日志文件分散在不同目录
+
+## 2. 改造方案设计
+
+### 2.1 统一日志架构
+
+项目根目录/
+├── core/logging/                    # 中央日志服务
+│   ├── __init__.py                 # 统一入口
+│   └── log_manager.py              # 核心管理器
+├── config/
+│   └── logging_config.yaml         # 统一配置文件
+├── logs/                           # 统一日志目录
+│   ├── app.log                     # 主应用日志
+│   ├── agent.log                   # Agent模块日志
+│   ├── vanna.log                   # Vanna相关日志
+│   ├── data_pipeline.log           # 数据管道日志
+│   └── react_agent.log             # React Agent日志
+└── 各业务模块/                      # 使用统一日志API
+
+### 2.2 模块日志分配
+
+| 模块              | 日志文件            | 主要组件                                                 | 说明             |
+| ----------------- | ------------------- | -------------------------------------------------------- | ---------------- |
+| **App**           | `app.log`           | unified_api.py, citu_app.py, common/*                    | 主应用和通用功能 |
+| **Agent**         | `agent.log`         | agent/*, agent/tools/*                                   | 智能代理相关     |
+| **Vanna**         | `vanna.log`         | core/*, customllm/*, customembedding/*, custompgvector/* | Vanna框架相关    |
+| **Data Pipeline** | `data_pipeline.log` | data_pipeline/*                                          | 数据处理管道     |
+| **React Agent**   | `react_agent.log`   | react_agent/*                                            | React Agent模块  |
+
+## 3. 具体实施步骤
+
+### 3.1 第一步：完善配置文件
+
+#### 3.1.1 更新config/logging_config.yaml
+
+```yaml
+version: 1
+
+# 全局配置
+global:
+  base_level: INFO
+  
+# 默认配置（用于app.log）
+default:
+  level: INFO
+  console:
+    enabled: true
+    level: INFO
+    format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  file:
+    enabled: true
+    level: DEBUG
+    filename: "app.log"
+    format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
+    rotation:
+      enabled: true
+      max_size: "50MB"
+      backup_count: 10
+
+# 模块特定配置
+modules:
+  app:
+    level: INFO
+    console:
+      enabled: true
+      level: INFO
+      format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    file:
+      enabled: true
+      level: DEBUG
+      filename: "app.log"
+      format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
+      rotation:
+        enabled: true
+        max_size: "50MB"
+        backup_count: 10
+  
+  agent:
+    level: DEBUG
+    console:
+      enabled: true
+      level: INFO
+      format: "%(asctime)s [%(levelname)s] Agent: %(message)s"
+    file:
+      enabled: true
+      level: DEBUG
+      filename: "agent.log"
+      format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
+      rotation:
+        enabled: true
+        max_size: "30MB"
+        backup_count: 8
+  
+  vanna:
+    level: DEBUG
+    console:
+      enabled: true
+      level: INFO
+      format: "%(asctime)s [%(levelname)s] Vanna: %(message)s"
+    file:
+      enabled: true
+      level: DEBUG
+      filename: "vanna.log"
+      format: "%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s"
+      rotation:
+        enabled: true
+        max_size: "20MB"
+        backup_count: 5
+  
+  data_pipeline:
+    level: DEBUG
+    console:
+      enabled: true
+      level: INFO
+      format: "%(asctime)s [%(levelname)s] Pipeline: %(message)s"
+    file:
+      enabled: true
+      level: DEBUG
+      filename: "data_pipeline.log"
+      format: "%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s"
+      rotation:
+        enabled: true
+        max_size: "20MB"
+        backup_count: 5
+  
+  react_agent:
+    level: DEBUG
+    console:
+      enabled: true
+      level: INFO
+      format: "%(asctime)s [%(levelname)s] ReactAgent: %(message)s"
+    file:
+      enabled: true
+      level: DEBUG
+      filename: "react_agent.log"
+      format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
+      rotation:
+        enabled: true
+        max_size: "30MB"
+        backup_count: 8
+```
+
+### 3.2 第二步：改造React Agent模块
+
+#### 3.2.1 删除独立日志管理器
+```bash
+# 删除独立日志文件
+rm react_agent/logger.py
+```
+
+#### 3.2.2 修改React Agent模块代码
+
+**react_agent/api.py**
+```python
+# 替换现有的日志导入
+from core.logging import get_app_logger
+
+# 初始化日志
+logger = get_app_logger("ReactAgentAPI")
+```
+
+**react_agent/agent.py**
+```python
+# 替换现有的日志导入
+from core.logging import get_app_logger
+
+# 初始化日志
+logger = get_app_logger("CustomReactAgent")
+```
+
+**react_agent/sql_tools.py**
+```python
+# 替换现有的日志导入
+from core.logging import get_app_logger
+
+# 初始化日志
+logger = get_app_logger("SQLTools")
+```
+
+### 3.3 第三步：改造Data Pipeline模块
+
+#### 3.3.1 创建统一日志接口
+
+**data_pipeline/dp_logging/__init__.py**
+```python
+"""
+Data Pipeline 统一日志管理
+支持API和命令行两种模式
+"""
+
+from core.logging import get_data_pipeline_logger, initialize_logging
+import os
+
+def init_data_pipeline_logging():
+    """初始化data_pipeline日志系统"""
+    # 确保日志系统已初始化
+    initialize_logging()
+
+def get_logger(name: str, task_id: str = None):
+    """
+    获取data_pipeline专用logger
+    
+    Args:
+        name: logger名称
+        task_id: 任务ID（可选，用于任务特定日志）
+    
+    Returns:
+        配置好的logger实例
+    """
+    logger = get_data_pipeline_logger(name)
+    
+    # 如果提供了task_id，添加任务特定的文件处理器
+    if task_id:
+        import logging
+        from pathlib import Path
+        
+        # 创建任务特定的日志文件
+        task_log_file = Path(f"data_pipeline/training_data/{task_id}/data_pipeline.log")
+        task_log_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        # 创建任务特定的文件处理器
+        task_handler = logging.FileHandler(task_log_file, encoding='utf-8')
+        task_handler.setLevel(logging.DEBUG)
+        
+        formatter = logging.Formatter(
+            '%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        task_handler.setFormatter(formatter)
+        
+        # 添加到logger
+        logger.addHandler(task_handler)
+    
+    return logger
+```
+
+#### 3.3.2 修改Data Pipeline主要文件
+
+**data_pipeline/schema_workflow.py**
+```python
+# 替换现有的日志导入
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
+
+# 在类初始化时调用
+init_data_pipeline_logging()
+logger = get_logger("SchemaWorkflow", task_id)
+```
+
+**data_pipeline/trainer/run_training.py**
+```python
+# 在文件开头添加
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
+
+# 初始化日志
+init_data_pipeline_logging()
+logger = get_logger("RunTraining")
+
+# 替换所有print语句
+# 原代码：print("正在检查嵌入模型连接...")
+# 新代码：logger.info("正在检查嵌入模型连接...")
+```
+
+### 3.4 第四步：清理print语句
+
+#### 3.4.1 需要改造的文件清单
+
+| 文件路径 | 当前状态 | 改造方式 | 优先级 |
+|----------|----------|----------|--------|
+| `data_pipeline/task_executor.py` | print语句 | 替换为logger | 高 |
+| `data_pipeline/config.py` | print语句 | 替换为logger | 高 |
+| `data_pipeline/trainer/run_training.py` | print语句 | 替换为logger | 高 |
+| `data_pipeline/validators/sql_validate_cli.py` | print语句 | 保留（CLI工具） | 中 |
+| `data_pipeline/validators/sql_validation_example.py` | print语句 | 保留（示例程序） | 低 |
+
+#### 3.4.2 print语句替换规则
+
+```python
+# 错误信息 -> logger.error()
+print(f"错误: {error_message}") 
+# 改为：
+logger.error(f"错误: {error_message}")
+
+# 警告信息 -> logger.warning()
+print(f"警告: {warning_message}")
+# 改为：
+logger.warning(f"警告: {warning_message}")
+
+# 调试信息 -> logger.debug()
+print(f"调试: {debug_info}")
+# 改为：
+logger.debug(f"调试: {debug_info}")
+
+# 一般信息 -> logger.info()
+print(f"信息: {info_message}")
+# 改为：
+logger.info(f"信息: {info_message}")
+```
+
+【补充】
+#### 3.4.3 批量扫描print语句建议
+建议使用正则表达式（如`print\(`）或脚本工具，批量扫描全项目（排除./test、./doc和test_*.py文件）中的print语句，形成详细的待改造文件清单，确保无遗漏。
+
+### 3.5 第五步：验证和测试
+
+#### 3.5.1 API模式测试
+```bash
+# 启动API服务
+python unified_api.py
+
+# 检查日志文件生成
+ls -la logs/
+# 应该看到：app.log, agent.log, vanna.log, data_pipeline.log, react_agent.log
+
+# 调用API测试日志
+curl -X POST http://localhost:5000/api/v0/ask_agent \
+  -H "Content-Type: application/json" \
+  -d '{"question": "test question", "user_id": "test_user"}'
+
+# 检查agent.log
+tail -f logs/agent.log
+```
+
+#### 3.5.2 命令行模式测试
+```bash
+# 测试data_pipeline命令行
+python data_pipeline/trainer/run_training.py
+
+# 检查data_pipeline.log
+tail -f logs/data_pipeline.log
+```
+
+【补充】
+### 3.6 API入口日志初始化与写入
+
+#### 3.6.1 unified_api.py日志初始化
+- 在unified_api.py文件开头，务必添加日志系统初始化代码：
+  ```python
+  from core.logging import initialize_logging, get_app_logger
+  initialize_logging()
+  logger = get_app_logger("App")
+  ```
+- 替换所有print和异常输出为logger调用。
+- 确保API处理函数（如ask_agent）有logger.info/debug/error等调用。
+- 启动unified_api.py后，logs/app.log应由该文件负责写入。
+
+#### 3.6.2 agent.log日志写入排查建议
+- 检查agent相关模块是否用统一日志服务（如get_app_logger("Agent")）。
+- 检查unified_api.py是否初始化了日志系统。
+- 检查日志配置文件中agent部分是否正确。
+- 若调用ask_agent API未见agent.log写入，需重点排查上述环节。
+
+## 4. 改造完成标准
+
+### 4.1 功能验证清单
+
+- [ ] 启动unified_api.py时自动初始化日志系统
+- [ ] 各模块日志正确写入对应的日志文件
+- [ ] 日志文件自动轮转功能正常
+- [ ] 控制台和文件输出格式正确
+- [ ] 上下文信息（user_id, session_id）正确显示
+- [ ] 错误降级到控制台功能正常
+
+### 4.2 文件验证清单
+
+- [ ] 删除react_agent/logger.py
+- [ ] 删除data_pipeline/dp_logging/manager.py
+- [ ] 更新所有模块的日志导入
+- [ ] 替换所有print语句
+- [ ] 配置文件正确更新
+
+### 4.3 日志文件验证
+
+启动服务后，logs/目录下应该包含：
+- `app.log` - 主应用日志
+- `agent.log` - Agent模块日志  
+- `vanna.log` - Vanna相关日志
+- `data_pipeline.log` - 数据管道日志
+- `react_agent.log` - React Agent日志
+
+【补充】
+### 4.4 logger命名规范建议
+- 建议所有logger实例命名时，使用模块名或功能名作为参数，如：
+  ```python
+  logger = get_app_logger("Agent")
+  logger = get_app_logger("Vanna")
+  logger = get_app_logger("DataPipeline")
+  logger = get_app_logger("ReactAgent")
+  logger = get_app_logger("App")
+  ```
+- 便于日志聚合和后续分析。
+
+## 5. 注意事项和风险控制
+
+### 5.1 兼容性考虑
+- 保留CLI工具的print输出，确保用户体验
+- 示例程序可以保留print，便于演示
+- 确保API和命令行两种模式都能正常工作
+
+### 5.2 性能考虑
+- 日志文件轮转避免单个文件过大
+- 合理设置日志级别，避免过多DEBUG输出
+- 考虑异步日志写入（如需要）
+
+### 5.3 错误处理
+- 日志目录创建失败时降级到控制台
+- 配置文件加载失败时使用默认配置
+- 文件写入失败时不影响主程序运行
+
+【补充】
+### 5.4 日志异常处理与降级机制
+- 日志系统初始化失败时，自动降级为控制台输出，保证主程序不因日志异常而中断。
+- 日志目录创建失败时，自动切换为当前目录或控制台输出。
+- 配置文件加载失败时，自动使用默认配置。
+- 文件写入失败时，日志输出降级为console，主程序继续运行。
+
+## 6. 后续优化建议
+
+### 6.1 短期优化（1-2周）
+1. 根据实际使用情况调整日志级别
+2. 优化日志格式，提高可读性
+3. 添加日志文件大小监控
+
+### 6.2 中期优化（1-3个月）
+1. 实现结构化日志（JSON格式）
+2. 添加日志分析和统计功能
+3. 集成日志管理系统（如ELK）
+
+### 6.3 长期优化（3-6个月）
+1. 实现异步日志写入
+2. 添加日志压缩和归档
+3. 实现分布式日志收集
+
+## 7. 总结
+
+通过本次改造，项目将实现：
+- **统一管理**：所有模块使用同一套日志系统
+- **模块独立**：不同模块的日志分离存储
+- **配置灵活**：通过YAML文件统一配置
+- **易于维护**：标准化的日志格式和API
+- **高可用性**：完善的错误处理和降级机制
+
+改造完成后，项目的日志管理将更加规范、高效和易于维护。
+