OpenCode Agent Protocol - LiteLLM VolcSync

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

1. 项目上下文

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

核心逻辑：通过 quota_interceptor 拦截请求，并通过 DailyLimitHandler 记录用量到 Redis。后台 active_monitor_loop 守护线程定期从火山引擎 API 同步配额到 Redis。
架构：所有逻辑统一在 volc_limit_sync.py 单文件中。LiteLLM 通过 config.yaml 中 callbacks: ["volc_limit_sync.proxy_handler_instance"] 加载回调，模块加载时自动启动后台同步线程。
关键文件：
- volc_limit_sync.py: 唯一核心文件，包含同步守护线程（active_monitor_loop）、LiteLLM 回调（DailyLimitHandler + quota_interceptor）、限额计算、模型屏蔽/恢复等全部逻辑。
- config.yaml: LiteLLM 配置文件，包含模型定义和回调配置。
- docker-compose.yml: 容器编排，仅挂载 config.yaml 和 volc_limit_sync.py。
- debug_volc_sync.py / debug_volc_sync_manual.py: 调试脚本，用于手动验证 API 和 Redis 状态。
- daily_limit.py.deprecated: 已废弃，功能已全部合并到 volc_limit_sync.py，仅保留作历史参考。

本项目主要由 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

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) -> 本地模块。

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

由于这些脚本运行在 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")

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

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

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