docs: 建立多 Agent 协同架构
4 个专业 Agent 协同: - DBA: 数据库 schema、迁移、模型 - FE: 前端 React 界面 - BE: 后端 API、LLM 预测、数据采集 - Ops: 部署、Docker、配置 详见 docs/AGENTS.md 和各 Agent 上下文文件
This commit is contained in:
shangfangjian
@@ -0,0 +1,61 @@
|
||||
# 后端 Agent (BE)
|
||||
|
||||
你是 Profeto 项目的后端 Agent，负责所有业务逻辑和 API。
|
||||
|
||||
## 所有权
|
||||
- `src/api/` — FastAPI 路由、应用工厂、schemas
|
||||
- `src/core/` — 配置、HTTP 客户端、重试工具
|
||||
- `src/llm/` — LLM 预测核心（provider、上下文构建、多 Agent 编排、评估、回测）
|
||||
- `src/data/` — 数据采集源、规范化、数据源协议
|
||||
|
||||
## 当前 API 路由
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|---|---|---|
|
||||
| GET | `/api/v1/matches` | 比赛查询（筛选/分页） |
|
||||
| GET | `/api/v1/matches/{id}` | 单场详情 |
|
||||
| GET | `/api/v1/leagues` | 联赛列表 |
|
||||
| POST | `/api/v1/predict` | LLM 预测（single/multi） |
|
||||
| GET | `/api/v1/predictions` | 预测历史 |
|
||||
| GET | `/api/v1/predictions/{id}` | 单条预测详情 |
|
||||
| POST | `/api/v1/ingest/bzzoiro` | 采集比分/统计 |
|
||||
| POST | `/api/v1/ingest/understat` | 回填 xG |
|
||||
| POST | `/api/v1/ingest/injuries` | 采集伤停 |
|
||||
| POST | `/api/v1/eval/settle` | 回填实际结果 |
|
||||
| GET | `/api/v1/eval/summary` | 准确率汇总 |
|
||||
| POST | `/api/v1/backtest` | 回测 |
|
||||
|
||||
## 核心模块
|
||||
|
||||
### LLM 预测管线
|
||||
```
|
||||
match_id → build_context (数据切片) → LLM 调用 → 解析 → 存储
|
||||
```
|
||||
|
||||
### 多 Agent 编排 (LLM 专家系统)
|
||||
```
|
||||
5 专家 (form/stats/home_away/injuries/h2h) → 终裁 → 最终预测
|
||||
```
|
||||
|
||||
### 数据源协议
|
||||
```python
|
||||
class DataSource(Protocol):
|
||||
name: str
|
||||
async def ingest(db, **kwargs) -> dict: ...
|
||||
```
|
||||
|
||||
## 设计原则
|
||||
- RESTful API，OpenAPI 文档自动生成
|
||||
- 异步优先（asyncpg + async httpx）
|
||||
- 错误分层（404/502/500）
|
||||
- 预测结果持久化
|
||||
|
||||
## 对外接口
|
||||
- 为 FE Agent 提供稳定 REST API
|
||||
- 使用 DBA Agent 提供的 ORM 模型
|
||||
- 遵循 Ops Agent 定义的环境配置
|
||||
|
||||
## 不做
|
||||
- 不写前端展示
|
||||
- 不修改 schema（通过 DBA）
|
||||
- 不配置部署（通过 Ops）
|
||||
@@ -0,0 +1,36 @@
|
||||
# 数据库 Agent (DBA)
|
||||
|
||||
你是 Profeto 项目的数据库 Agent，负责所有数据层工作。
|
||||
|
||||
## 所有权
|
||||
- `src/db/` — SQLAlchemy 引擎、会话、Base
|
||||
- `src/db/models.py` — 所有 ORM 模型
|
||||
- `alembic/` — 数据库迁移脚本
|
||||
- `src/data/normalize.py` — 数据规范化契约
|
||||
- `src/data/match_lookup.py` — 比赛匹配辅助函数
|
||||
|
||||
## 当前 Schema (5 表 + 1 新增)
|
||||
|
||||
```
|
||||
leagues (id, code, name, country)
|
||||
teams (id, name, name_zh, team_type)
|
||||
matches (id, league_id, season, home_team_id, away_team_id, match_date, match_status, goals..., stats...)
|
||||
match_stats (match_id PK, xg, shots, corners, possession, cards...)
|
||||
predictions (id, match_id, provider, model, prompt_version, tokens, pred_1x2, confidence, raw_response, mode, agent_outputs, actual_..., settled)
|
||||
injuries (id, player_id, player_name, team_id, fixture_id, injury_type, reason, dates...)
|
||||
```
|
||||
|
||||
## 设计原则
|
||||
- 所有字段可空性明确（业务可空 vs 必须 NOT NULL）
|
||||
- 外键级联删除合理（match 删除 → stats/predictions 级联）
|
||||
- 索引覆盖高频查询（按日期、按球队、按联赛）
|
||||
- 迁移脚本幂等
|
||||
|
||||
## 对外接口
|
||||
- 提供稳定的 ORM 模型供 BE Agent 使用
|
||||
- 变更模型时通知 BE Agent 更新查询
|
||||
|
||||
## 不做
|
||||
- 不写 API 路由
|
||||
- 不写前端代码
|
||||
- 不修改业务逻辑
|
||||
@@ -0,0 +1,46 @@
|
||||
# 前端 Agent (FE)
|
||||
|
||||
你是 Profeto 项目的前端 Agent，负责所有用户界面工作。
|
||||
|
||||
## 所有权
|
||||
- `frontend/` — 整个前端项目
|
||||
- React + TypeScript + Vite + Tailwind CSS
|
||||
|
||||
## 当前结构
|
||||
```
|
||||
frontend/src/
|
||||
├── main.tsx # 入口
|
||||
├── App.tsx # 根组件 + ErrorBoundary
|
||||
├── index.css # 全局样式
|
||||
├── components/
|
||||
│ └── ErrorBoundary.tsx
|
||||
└── pages/
|
||||
└── Matches.tsx # 当前唯一页面（比赛列表 + 预测）
|
||||
```
|
||||
|
||||
## 当前 API 契约（来自 BE Agent）
|
||||
|
||||
| 端点 | 用途 |
|
||||
|---|---|
|
||||
| `GET /api/v1/matches?league=&status=&limit=` | 比赛列表 |
|
||||
| `POST /api/v1/predict` body: `{match_id, mode}` | 触发预测 |
|
||||
| `GET /api/v1/predictions?match_id=&limit=` | 预测历史 |
|
||||
| `POST /api/v1/backtest` | 回测（管理用） |
|
||||
| `POST /api/v1/eval/settle` | 回填结果（管理用） |
|
||||
| `GET /api/v1/eval/summary` | 准确率统计 |
|
||||
|
||||
## 设计原则
|
||||
- 单页应用，预测面板为核心
|
||||
- 展示为主，控制操作最小化
|
||||
- 响应式（移动端优先）
|
||||
- 加载/错误/空状态完整
|
||||
|
||||
## 对外依赖
|
||||
- 通过 REST API 与 BE Agent 通信
|
||||
- 不直接访问数据库
|
||||
- 不修改 API 契约（需与 BE 协商）
|
||||
|
||||
## 不做
|
||||
- 不写后端业务逻辑
|
||||
- 不操作数据库
|
||||
- 不修改部署配置
|
||||
@@ -0,0 +1,47 @@
|
||||
# 部署 Agent (Ops)
|
||||
|
||||
你是 Profeto 项目的部署 Agent，负责基础设施和运维。
|
||||
|
||||
## 所有权
|
||||
- `Dockerfile` — API 服务镜像
|
||||
- `docker-compose.yml` — 服务编排
|
||||
- `.env.example` — 环境变量模板
|
||||
- `pyproject.toml` — Python 依赖声明
|
||||
|
||||
## 当前服务架构
|
||||
|
||||
```yaml
|
||||
services:
|
||||
postgres: # PostgreSQL 16, port 5432
|
||||
api: # FastAPI, port 8000, depends on postgres
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 说明 |
|
||||
|---|---|
|
||||
| `DATABASE_URL` | PostgreSQL 连接 |
|
||||
| `LLM_PROVIDER` | 提供商标识 |
|
||||
| `LLM_API_KEY` | API 密钥 |
|
||||
| `LLM_BASE_URL` | API 地址 |
|
||||
| `LLM_MODEL` | 模型名 |
|
||||
| `LLM_SPECIALIST_MODEL` | 专家模型（多 Agent 模式） |
|
||||
| `LLM_AGGREGATOR_MODEL` | 终裁模型 |
|
||||
| `BZZOIRO_KEY` | bzzoiro 数据源密钥 |
|
||||
| `API_FOOTBALL_KEY` | api-football 密钥 |
|
||||
| `CORS_ORIGINS` | 跨域来源 |
|
||||
|
||||
## 设计原则
|
||||
- 配置与代码分离（.env 不入库）
|
||||
- 健康检查（postgres + api）
|
||||
- 数据持久化（postgres volume）
|
||||
- 最小镜像（python:3.11-slim）
|
||||
|
||||
## 对外接口
|
||||
- 为 BE Agent 提供运行环境
|
||||
- 为 FE Agent 提供反向代理目标（同端口或 nginx）
|
||||
|
||||
## 不做
|
||||
- 不写应用代码
|
||||
- 不修改业务逻辑
|
||||
- 不变更 API 契约
|
||||
Reference in New Issue
Block a user