ailine/LOGGING.md

📝 日志使用规范

统一日志系统

本项目采用统一的日志系统，确保后端和前端的日志输出格式一致，便于调试和监控。

---

📁 日志模块位置

后端日志

• 模块路径：app/logger.py
• 日志器名称：ai_agent
• 使用方式：

  from app.logger import debug, info, warning, error
  

前端日志

• 模块路径：frontend/logger.py
• 日志器名称：ai_agent_frontend
• 使用方式：

  from frontend.logger import debug, info, warning, error
  # 或
  from .logger import debug, info, warning, error  # 在 frontend 包内
  

---

🎯 日志级别

级别	函数	使用场景	环境变量控制
DEBUG	debug()	详细调试信息（变量值、中间状态）	DEBUG=true 时输出
INFO	info()	关键流程节点（服务启动、API 请求）	始终输出
WARNING	warning()	警告信息（配置缺失、降级处理）	始终输出
ERROR	error()	错误信息（异常、失败）	始终输出

---

📝 使用示例

后端使用（app/ 目录下）

from app.logger import debug, info, warning, error

async def process_message(self, message: str, ...):
    info(f"收到用户消息: {message[:50]}...")
    
    try:
        result = await graph.ainvoke(...)
        debug(f"Graph 执行结果: {result}")
        return result
    except Exception as e:
        error(f"消息处理失败: {e}")
        raise

前端使用（frontend/ 目录下）

from .logger import error, warning

class APIClient:
    def get_user_threads(self, user_id: str):
        try:
            resp = requests.get(...)
            if resp.status_code != 200:
                error(f"获取历史列表失败: HTTP {resp.status_code}")
                return []
        except Exception as e:
            error(f"获取历史列表异常: {e}")
            return []

---

⚙️ 配置说明

环境变量

变量	说明	默认值	示例
LOG_LEVEL	日志级别	INFO	DEBUG, INFO, WARNING, ERROR
DEBUG	调试模式	false	true, false

本地开发配置（.env）

# 输出详细调试信息
LOG_LEVEL=DEBUG
DEBUG=true

Docker 部署配置（.env.docker）

# 仅输出关键信息，减少日志量
LOG_LEVEL=WARNING
DEBUG=false

---

🚫 禁止事项

❌ 不要使用 print()

# ❌ 错误
print("处理消息...")
print(f"错误: {e}")

# ✅ 正确
info("处理消息...")
error(f"错误: {e}")

❌ 不要使用 loguru

# ❌ 错误
from loguru import logger
logger.info("消息")

# ✅ 正确
from app.logger import info  # 后端
from frontend.logger import info  # 前端
info("消息")

❌ 不要在工具函数中使用日志

工具函数应保持纯粹，避免副作用：

# ❌ 错误
@tool
def read_file(filename: str):
    info(f"读取文件: {filename}")  # 工具函数不应有日志
    return content

# ✅ 正确（日志在调用工具的地方）
async def tool_call_node(state):
    info(f"调用工具: read_file")
    result = await read_file.ainvoke(...)
    return result

---

📊 日志格式

输出格式

2026-04-16 10:30:45 | INFO     | ai_agent | 收到用户消息: 你好...
2026-04-16 10:30:45 | DEBUG    | ai_agent | Graph 执行结果: {...}
2026-04-16 10:30:46 | WARNING  | ai_agent_frontend | JSON 解析失败: ...
2026-04-16 10:30:46 | ERROR    | ai_agent | 消息处理失败: ConnectionError

字段说明

字段	说明
时间	YYYY-MM-DD HH:MM:SS
级别	DEBUG, INFO, WARNING, ERROR（8 字符宽度，左对齐）
日志器	ai_agent（后端）或 ai_agent_frontend（前端）
消息	日志内容

---

🔧 最佳实践

1. 使用结构化日志

# ✅ 推荐：包含关键信息
info(f"用户 {user_id} 调用模型 {model_name}")

# ❌ 不推荐：信息不完整
info("调用模型")

2. 异常日志包含堆栈

# ✅ 推荐：记录完整异常信息
try:
    result = await api_call()
except Exception as e:
    error(f"API 调用失败: {e}", exc_info=True)

3. 敏感信息脱敏

# ✅ 推荐：隐藏敏感信息
debug(f"API Key: {api_key[:4]}...{api_key[-4:]}")

# ❌ 错误：泄露完整密钥
debug(f"API Key: {api_key}")

4. 日志级别合理使用

# ✅ 推荐：根据重要性选择级别
info("服务启动成功")           # 关键流程
debug(f"配置参数: {config}")   # 调试信息
warning("配置缺失，使用默认值")  # 警告但不影响运行
error("数据库连接失败")         # 严重错误

---

📋 文件清单

文件	日志导入	说明
app/agent.py	from app.logger import debug, info, warning, error	✅ 正确
app/backend.py	from app.logger import debug, info, warning, error	✅ 正确
app/history.py	from app.logger import error	✅ 已修复
app/nodes/*.py	from app.logger import ...	✅ 正确
app/tools.py	无日志	✅ 正确（工具函数不使用日志）
frontend/api_client.py	from .logger import error, warning	✅ 已修复
frontend/logger.py	自身定义	✅ 前端日志模块

---

🎯 总结

核心原则

1. 统一模块：后端使用 app.logger，前端使用 frontend.logger
2. 禁止 print：所有输出必须通过日志模块
3. 禁止 loguru：不使用第三方日志库
4. 环境控制：通过 LOG_LEVEL 和 DEBUG 控制输出
5. 工具纯粹：工具函数不使用日志，日志在调用方

优势

• ✅ 格式统一：所有日志输出格式一致
• ✅ 易于调试：支持分级输出，开发时查看详细信息
• ✅ 性能优化：生产环境可减少日志量
• ✅ 便于监控：日志格式标准化，便于日志收集和分析

---

📝 所有文件已按照日志规范统一！