refactor: 目录整理配套引用同步

README/AGENTS 文件清单与命令更新为新结构（generate_keys -> scripts/、
daily_limit -> archive/、文档 -> docs/）；config.yaml 与 volc_consume.py
注释中废弃脚本/文档路径同步；README 过期限额示例更新为 2M 配置。

AGENTS.md

@@ -7,12 +7,14 @@
 - **核心逻辑**：通过 `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`）、限额计算（v2 简化：`stable_limit = usage + balance − BUFFER`，dynamic 缺失时 fallback `FALLBACK_LIMIT` 90 万兜底）、模型屏蔽/恢复、以及每日 23:00 消耗任务调度（`_maybe_trigger_daily_consume`，SETNX 去重）。
+  - `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`。
+  - `docker-compose.yml`: 容器编排，仅挂载 `config.yaml`、`volc_limit_sync.py`、`volc_consume.py`。
-  - `debug_volc_sync.py` / `debug_volc_sync_manual.py`: 调试脚本，用于手动验证 API 和 Redis 状态。
+  - `docs/`: 设计文档与额度机制速查（`merge-auto-consume.md` 消耗任务/限额设计、`volc-quota-notes.md` 火山额度机制事实基础、`merge-volc-limit-into-newapi.md` 未实施的迁移方案）。
-  - `daily_limit.py.deprecated`: 已废弃，功能已全部合并到 `volc_limit_sync.py`，仅保留作历史参考。
+  - `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)
 

README.md

@@ -10,7 +10,7 @@ callbacks: ["volc_limit_sync.proxy_handler_instance"]
 
 这意味着当前 Docker 容器里真正生效的是 `volc_limit_sync.py`。
 
-`daily_limit.py` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回 `daily_limit.py`，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。
+旧脚本 `archive/daily_limit.py.deprecated` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回旧模块，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。
 
 ---
 
@@ -62,7 +62,7 @@ glm-4-7-251222 -> glm-4-7
 每次改完 `config.yaml` 后，执行：
 
 ```bash
-python generate_keys.py
+python scripts/generate_keys.py
 ```
 
 这个脚本现在不是单纯“生成 key”，而是正式的 **监控模型审计入口**。它会输出：
@@ -106,7 +106,7 @@ python generate_keys.py
 ### 新增监控模型
 
 1. 在 `config.yaml` 的 `model_list` 里加入新的火山模型条目。
-2. 运行 `python generate_keys.py`。
+2. 运行 `python scripts/generate_keys.py`。
 3. 先确认脚本输出中：
    - 该模型已经出现在“监控模型审计”里。
    - “监控别名”正确。
@@ -119,7 +119,7 @@ python generate_keys.py
 ### 删除监控模型
 
 1. 从 `config.yaml` 里删掉对应模型条目。
-2. 运行 `python generate_keys.py`，确认它已经不在“监控模型审计”里。
+2. 运行 `python scripts/generate_keys.py`，确认它已经不在“监控模型审计”里。
 3. 如果该模型曾有单独的 `HARD_DAILY_LIMITS` 项，可以按需清理。
 4. 如果该模型对应的是特殊手工别名，且已经没有任何上游模型再用它，可以再清理 `MANUAL_MONITORED_MODEL_ALIASES`。
 5. 重启 LiteLLM 容器。
@@ -160,14 +160,14 @@ python generate_keys.py
 3. 模糊规则
 4. `__DEFAULT__`
 
-例如：
+例如（当前值，2026-08）：
 
 ```python
 HARD_DAILY_LIMITS = {
-    "doubao-seed-code-preview-251028": 4_800_000,
+    # 火山免费额度规则：每模型每日采集上限 2M，次日按采集量发放资源包。
-    "doubao-seed-2-0-pro-260215:ba0383d3": 1_900_000,
+    # 采集上限封顶；真正决定今日可采的是 v4 动态层：
-    "doubao-seed-2-0-lite-260215:ba0383d3": 1_900_000,
+    # effective = min(2M, stable_limit)，stable_limit = 余额快照 − BUFFER（见 docs/volc-quota-notes.md）
-    "__DEFAULT__": 1_800_000,
+    "__DEFAULT__": 2_000_000,
 }
 ```
 
@@ -175,13 +175,13 @@ HARD_DAILY_LIMITS = {
 
 ## 常见坑
 
-### 1. 改了 `daily_limit.py` 但不生效
+### 1. 改了旧脚本（`archive/daily_limit.py.deprecated`）但不生效
 
 这是最容易踩的坑。
 
-当前 `config.yaml` 没有启用 `daily_limit.py`，所以：
+当前 `config.yaml` 没有启用旧模块 `daily_limit`，所以：
 
-- 改 `daily_limit.py`
+- 改 `archive/daily_limit.py.deprecated`
 - 改 `MODEL_QUOTAS`
 
 都不会影响当前 LiteLLM 容器的启动和监控行为。
@@ -204,7 +204,7 @@ xxx-251201 -> xxx
 xxx-260215 -> xxx
 ```
 
-所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python generate_keys.py` 审计确认。
+所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python scripts/generate_keys.py` 审计确认。
 
 ---
 
@@ -213,7 +213,7 @@ xxx-260215 -> xxx
 ### 审计当前纳入监控模型
 
 ```bash
-python generate_keys.py
+python scripts/generate_keys.py
 ```
 
 ### 直接运行同步监控
@@ -235,18 +235,30 @@ DAILY_LIMIT_LOG_LEVEL=DEBUG python volc_limit_sync.py
 ```text
 litellm-config/
 ├── config.yaml              # 纳入监控模型的主入口
-├── volc_limit_sync.py       # 当前生效的监控、同步、限额脚本
+├── docker-compose.yml       # 容器编排（挂载 config.yaml / volc_limit_sync.py / volc_consume.py）
-├── generate_keys.py         # 监控模型审计入口
+├── volc_limit_sync.py       # 当前生效的监控、同步、限额脚本（v4 冻结快照限额）
-├── daily_limit.py           # 旧脚本，当前 config 未启用
+├── volc_consume.py          # 每日 23:00 自动消耗任务（防免费资源包过期蒸发）
-├── debug_volc_sync.py       # 资源包调试脚本
+├── AGENTS.md                # 仓库 Agent 协议（代码风格/运行/提交规范）
-└── debug_volc_sync_manual.py # 手动调试脚本
+├── README.md
+├── docs/
+│   ├── merge-auto-consume.md       # 消耗任务 + 限额设计（v2 历史 / v4 修订）
+│   ├── volc-quota-notes.md         # 火山额度机制速查（扣费口径/方案演进/排障）
+│   └── merge-volc-limit-into-newapi.md  # 未实施的迁移方案（历史）
+├── scripts/
+│   └── generate_keys.py     # 监控模型审计入口
+├── debug/
+│   ├── debug_volc_sync.py   # 资源包调试脚本
+│   └── debug_volc_sync_manual.py  # 手动调试脚本
+└── archive/
+    ├── daily_limit.py.deprecated  # 旧脚本，当前 config 未启用（历史参考）
+    └── recover.py                 # 一次性恢复工具（历史）
 ```
 
 ---
 
 ## 维护原则
 
-- 先改 `config.yaml`，不要先改 `daily_limit.py`
+- 先改 `config.yaml`，不要先改旧脚本 `archive/daily_limit.py.deprecated`
-- 先跑 `python generate_keys.py` 审计，再决定要不要补 `HARD_DAILY_LIMITS`
+- 先跑 `python scripts/generate_keys.py` 审计，再决定要不要补 `HARD_DAILY_LIMITS`
 - 普通版本号模型优先依赖自动推导，不要手工补一堆重复映射
 - 只有特殊别名或一对多场景，才改 `MANUAL_MONITORED_MODEL_ALIASES`

config.yaml

@@ -473,7 +473,7 @@ litellm_settings:
   allowed_fails: 3 # cooldown model if it fails > 1 call in a minute.
   # 当前生效入口：volc_limit_sync.py
   # 监控模型发现、监控别名推导、资源包同步、HARD_DAILY_LIMITS 都在这个脚本里。
-  # daily_limit.py 当前未启用，仅保留作历史参考。
+  # 旧脚本 archive/daily_limit.py.deprecated 当前未启用，仅保留作历史参考。
   callbacks: ["volc_limit_sync.proxy_handler_instance"]
 
 router_settings: # router_settings are optional

volc_consume.py

@@ -1,7 +1,7 @@
 # ==========================================
 # 🚀 VolcConsume — 火山免费额度自动消耗任务
 # ==========================================
-# 与 volc_limit_sync.py 合并方案的一部分（见 merge-auto-consume.md）：
+# 与 volc_limit_sync.py 合并方案的一部分（见 docs/merge-auto-consume.md）：
 #   - 每日北京时间 23:00 由 volc_limit_sync 守护线程触发（可手动 --force）
 #   - 洗掉 CONSUME_MONITOR_DAYS 天内过期的资源包额度（FIFO 下即队列头部），
 #     防止 30 天过期蒸发导致"启动资金"缩水（免费额度规则：消耗 X → 次日返还 X）