vibe-code
d9c7b1406d
README/AGENTS 文件清单与命令更新为新结构（generate_keys -> scripts/、 daily_limit -> archive/、文档 -> docs/）；config.yaml 与 volc_consume.py 注释中废弃脚本/文档路径同步；README 过期限额示例更新为 2M 配置。
118 lines
6.2 KiB
Markdown
118 lines
6.2 KiB
Markdown
# 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 脚本组成，没有复杂的构建过程。
|
||
|
||
### 依赖安装
|
||
```bash
|
||
pip install litellm redis requests
|
||
```
|
||
|
||
### 运行与调试
|
||
由于是脚本项目，通常直接运行 Python 文件进行测试。
|
||
|
||
- **启动同步监控**：
|
||
```bash
|
||
# 必须配置必要的环境变量
|
||
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` 可启用详细日志。
|
||
|
||
- **消耗任务（手动触发）**：
|
||
```bash
|
||
# 需要 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` 或返回默认值）。
|
||
- **示例**：
|
||
```python
|
||
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` 等工具函数。
|