litellm-config/AGENTS.md

OpenCode Agent Protocol - LiteLLM VolcSync

此文件定义了在该代码库中工作的 AI Agent 的行为准则、代码风格和工作流。

1. 项目上下文

此仓库包含用于 LiteLLM 的自定义回调脚本，核心功能是限制模型用量（特别是火山引擎/VolcEngine）。

• 核心逻辑：通过 quota_interceptor 拦截请求，并通过 DailyLimitHandler 记录用量到 Redis。
• 关键文件：
  • volc_limit_sync.py: 主同步逻辑，从火山引擎 API 拉取配额并更新 Redis。
  • daily_limit.py: 轻量级回调，用于 LiteLLM 运行时检查。
  • config.yaml: 包含模型定义的 LiteLLM 配置文件。

2. 环境与运行 (Build & Run)

本项目主要由 Python 脚本组成，没有复杂的构建过程。

依赖安装

pip install litellm redis requests

运行与调试

由于是脚本项目，通常直接运行 Python 文件进行测试。

• 启动同步监控：

  # 必须配置必要的环境变量
  export VOLC_ACCESS_KEY="your_key"
  export VOLC_SECRET_KEY="your_secret"
  export REDIS_HOST="localhost"
  
  python volc_limit_sync.py
  

• 调试模式： 设置环境变量 DAILY_LIMIT_LOG_LEVEL=DEBUG 可启用详细日志。

3. 代码风格指南 (Code Style)

3.1 基础规范

• Python 版本：兼容 Python 3.8+。
• 命名规范：
  • 变量/函数：snake_case (e.g., clean_model_name, get_daily_limit)
  • 常量：UPPER_CASE (e.g., LOG_LEVEL, REDIS_HOST)
  • 类名：PascalCase (e.g., DailyLimitHandler)
• 类型提示 (Typing)：
  • 不要 强制添加类型提示（Type Hints），保持与现有代码一致的动态类型风格，除非涉及复杂的数据结构。
• 导入排序：标准库 -> 第三方库 (litellm, redis, requests) -> 本地模块。

3.2 日志与输出 (Logging)

重要：本项目使用自定义的日志风格，不要使用 Python 标准 logging 模块。

• 必须使用 log(msg, level="INFO") 或 dprint(msg) 函数。
• Emoji 前缀：日志消息通常以 Emoji 开头以增强可读性：
  • ℹ️ INFO: 一般信息
  • 🔍 DEBUG: 调试信息
  • ⚠️ WARNING: 警告/阻断
  • ❌ ERROR: 错误/异常
  • 📊 Usage: 用量统计
  • ♻️ RESTORE: 恢复模型
  • 🚫 BLOCK: 阻断模型

3.3 错误处理 (Error Handling)

由于这些脚本运行在 LiteLLM 主进程中，稳定性是第一优先级。

• 防御性编程：关键逻辑（特别是涉及 Redis 或外部 API 的部分）必须包裹在 try-except 块中。
• 禁止崩溃：回调函数内的异常不应导致 LiteLLM 崩溃。捕获异常并记录错误日志 (traceback.format_exc())，然后安全返回（pass 或返回默认值）。
• 示例：

  try:
      # 危险操作
      redis_client.incr(key)
  except Exception as e:
      # 记录但不抛出，以免影响主业务
      log(f"❌ Redis failed: {e}", level="ERROR")
  

3.4 特定模式

• LiteLLM 集成：
  • 检查 LITELLM_AVAILABLE 标志，确保脚本可以在没有 litellm 环境下独立运行（用于调试）。
  • 处理 litellm.exceptions 中的特定异常（如 ServiceUnavailableError）。
• 时间处理：
  • 明确处理时区问题。本项目强制使用 北京时间 (UTC+8) 进行每日限额重置（00:00 CST）。

4. 测试 (Testing)

目前没有集成的测试框架（如 pytest）。

• 验证方式：
  • 编写或运行 debug_*.py 脚本进行手动验证。
  • 使用 if __name__ == "__main__": 块在脚本底部包含自测逻辑。

5. Git 提交规范

• 使用约定式提交 (Conventional Commits)：
  • feat: 新功能 (e.g., feat: add support for deepseek-v3)
  • fix: 修复 (e.g., fix: resolve redis connection timeout)
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 重构

6. Cursor/Copilot 规则

• 优先保持现有文件的代码结构，不要为了"整洁"而破坏原有的 try-except 结构。
• 生成代码时，优先复用已有的 clean_model_name, generate_api_base_hash 等工具函数。