litellm-config/AGENTS.md

OpenCode Agent Protocol - LiteLLM VolcSync

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

1. 项目上下文

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

• 核心逻辑：通过 quota_interceptor 拦截请求，并通过 DailyLimitHandler 记录用量到 Redis。后台 active_monitor_loop 守护线程定期从火山引擎 API 同步配额到 Redis。
• 架构：主逻辑在 volc_limit_sync.py（限额 + 同步守护 + 每日消耗调度），消耗任务拆分在 volc_consume.py（每日北京时间 23:00 由守护线程延迟导入触发；见 merge-auto-consume.md）。LiteLLM 通过 config.yaml 中 callbacks: ["volc_limit_sync.proxy_handler_instance"] 加载回调，模块加载时自动启动后台同步线程。
• 关键文件：
  • volc_limit_sync.py: 核心文件，包含同步守护线程（active_monitor_loop）、LiteLLM 回调（DailyLimitHandler + quota_interceptor）、限额计算（v4 冻结快照：stable_limit = balance − BUFFER，effective_limit = min(2M 采集配额, stable_limit)；扣费红线 = 余额，与采集量/返还无关，见 docs/volc-quota-notes.md）、模型屏蔽/恢复、以及每日 23:00 消耗任务调度（_maybe_trigger_daily_consume，SETNX 去重）。
  • volc_consume.py: 消耗任务模块（每日 23:00 触发；手动 python volc_consume.py --dry-run / --force）。复用 volc_limit_sync 的拉包/归一化/用量记账设施，直连 Ark API 洗即将过期的免费资源包（防 30 天过期蒸发）。
  • config.yaml: LiteLLM 配置文件，包含模型定义和回调配置。
  • docker-compose.yml: 容器编排，仅挂载 config.yaml、volc_limit_sync.py、volc_consume.py。
  • docs/: 设计文档与额度机制速查（merge-auto-consume.md 消耗任务/限额设计、volc-quota-notes.md 火山额度机制事实基础、merge-volc-limit-into-newapi.md 未实施的迁移方案）。
  • debug/: 调试脚本（debug_volc_sync.py / debug_volc_sync_manual.py），手动验证 API 和 Redis 状态。
  • scripts/: 工具脚本（generate_keys.py 监控模型审计入口）。
  • archive/: 已废弃（daily_limit.py.deprecated 历史参考、recover.py 一次性恢复工具）。

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 可启用详细日志。

• 消耗任务（手动触发）：

  # 需要 HUOSHAN_API_KEY（Ark API Key）与 HUOSHAN_BASE_URL
  python volc_consume.py --dry-run   # 只计算每个模型的消耗计划，不发送请求
  python volc_consume.py --force     # 立即执行（绕过 23:00 时间限制）
  

  每日 23:00 由 volc_limit_sync.py 守护线程自动触发（consume:last_run:{日期} 去重）。

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

3.1 基础规范

• Python 版本：兼容 Python 3.8+。
• 命名规范：
  • 变量/函数：snake_case (e.g., clean_model_name, get_effective_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 等工具函数。