102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
|
# CLAUDE.md
|
|||
|
|
|
|||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|||
|
|
|
|||
|
|
## 项目概述
|
|||
|
|
|
|||
|
|
多平台 AI Coding Plan 统一管理系统，支持 MiniMax、OpenAI、Google Gemini、智谱、Kimi 等多个 AI 平台的订阅计划管理。提供额度查询、刷新倒计时、API 代理转发、多媒体任务队列和 Web 仪表盘。
|
|||
|
|
|
|||
|
|
## 启动命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Docker 部署（推荐）
|
|||
|
|
docker compose up -d
|
|||
|
|
|
|||
|
|
# 本地开发
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload
|
|||
|
|
|
|||
|
|
# 访问 API 文档
|
|||
|
|
# http://localhost:8080/docs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心架构
|
|||
|
|
|
|||
|
|
### 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
app/
|
|||
|
|
├── main.py # FastAPI 入口，管理 lifespan
|
|||
|
|
├── config.py # config.yaml 配置加载
|
|||
|
|
├── database.py # aiosqlite 数据库层（所有 CRUD 操作）
|
|||
|
|
├── models.py # Pydantic 数据模型
|
|||
|
|
├── providers/ # Provider 插件系统（自动发现）
|
|||
|
|
├── routers/ # API 路由
|
|||
|
|
└── services/ # 后台服务（调度器、额度、队列）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Provider 插件系统
|
|||
|
|
|
|||
|
|
新增平台无需修改核心代码，在 `app/providers/` 下创建文件即可：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from app.providers.base import BaseProvider, Capability
|
|||
|
|
|
|||
|
|
class NewPlatformProvider(BaseProvider):
|
|||
|
|
name = "new_platform"
|
|||
|
|
display_name = "New Platform"
|
|||
|
|
capabilities = [Capability.CHAT]
|
|||
|
|
|
|||
|
|
async def chat(self, messages, model, plan, stream=True, **kwargs):
|
|||
|
|
yield "data: ..."
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`ProviderRegistry` 会在启动时自动扫描并注册所有 `BaseProvider` 子类实例。
|
|||
|
|
|
|||
|
|
### 数据库设计
|
|||
|
|
|
|||
|
|
使用 SQLite + aiosqlite，所有 CRUD 操作集中在 `database.py` 中：
|
|||
|
|
|
|||
|
|
- **plans** - 订阅计划
|
|||
|
|
- **quota_rules** - 额度规则（一个 Plan 可有多条规则）
|
|||
|
|
- **model_routes** - 模型路由表（支持 priority fallback）
|
|||
|
|
- **tasks** - 异步任务队列
|
|||
|
|
- **quota_snapshots** - 额度历史快照
|
|||
|
|
|
|||
|
|
首次启动时，`seed_from_config()` 会从 `config.yaml` 导入种子数据。
|
|||
|
|
|
|||
|
|
### 四种刷新策略
|
|||
|
|
|
|||
|
|
`QuotaRule.refresh_type` 决定额度刷新方式：
|
|||
|
|
|
|||
|
|
| 类型 | 说明 | 关键参数 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `fixed_interval` | 固定间隔刷新 | `interval_hours` |
|
|||
|
|
| `calendar_cycle` | 自然周期（日/周/月） | `calendar_unit` + `calendar_anchor` |
|
|||
|
|
| `api_sync` | 调用平台 API 查询真实余额 | 无 |
|
|||
|
|
| `manual` | 手动重置 | 无 |
|
|||
|
|
|
|||
|
|
刷新逻辑在 `app/services/scheduler.py:_refresh_quota_rules()` 中，每 30 秒执行一次。
|
|||
|
|
|
|||
|
|
### API 代理路由
|
|||
|
|
|
|||
|
|
- `/v1/chat/completions` - OpenAI 兼容格式
|
|||
|
|
- `/v1/messages` - Anthropic 兼容格式（自动转换请求/响应格式）
|
|||
|
|
|
|||
|
|
支持两种路由方式：
|
|||
|
|
1. 通过 `X-Plan-Id` header 直接指定 Plan
|
|||
|
|
2. 通过 `model` 参数自动查找 `model_routes` 表（支持 priority fallback）
|
|||
|
|
|
|||
|
|
### 任务队列
|
|||
|
|
|
|||
|
|
异步任务支持图片、语音、视频生成，由 `scheduler.py:_process_task_queue()` 消费。
|
|||
|
|
|
|||
|
|
## 配置
|
|||
|
|
|
|||
|
|
主配置文件为 `config.yaml`，包含：
|
|||
|
|
- `server.proxy_api_key` - API 代理鉴权 Key
|
|||
|
|
- `database.path` - SQLite 数据库路径
|
|||
|
|
- `plans` - 订阅计划种子数据
|
|||
|
|
|
|||
|
|
配置通过 `app/config.py` 的 Pydantic 模型加载。
|