From f50784f9dc07e22d1fa34fb1461569ddce47370b Mon Sep 17 00:00:00 2001
From: shangfangjian <shangfangjian@bilidili.cn>
Date: Mon, 14 Sep 2026 21:59:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E5=A4=9A=20Agent=20?=
 =?UTF-8?q?=E5=8D=8F=E5=90=8C=E6=9E=B6=E6=9E=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

4 个专业 Agent 协同:
- DBA: 数据库 schema、迁移、模型
- FE: 前端 React 界面
- BE: 后端 API、LLM 预测、数据采集
- Ops: 部署、Docker、配置

详见 docs/AGENTS.md 和各 Agent 上下文文件
---
 CLAUDE.md          |  43 +++++++++++++++
 docs/AGENTS.md     | 128 +++++++++++++++++++++++++++++++++++++++++++++
 docs/agents/be.md  |  61 +++++++++++++++++++++
 docs/agents/dba.md |  36 +++++++++++++
 docs/agents/fe.md  |  46 ++++++++++++++++
 docs/agents/ops.md |  47 +++++++++++++++++
 6 files changed, 361 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 docs/AGENTS.md
 create mode 100644 docs/agents/be.md
 create mode 100644 docs/agents/dba.md
 create mode 100644 docs/agents/fe.md
 create mode 100644 docs/agents/ops.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..958c76f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,43 @@
+# Profeto — 先知
+
+足球 LLM 预测服务。
+
+## 多 Agent 协同
+
+本项目采用 4 Agent 协同模式。详见 `docs/AGENTS.md`。
+
+| Agent | 所有权 | 上下文文件 |
+|---|---|---|
+| 🗄️ DBA (数据库) | `src/db/`, `alembic/`, 数据模型 | `docs/agents/dba.md` |
+| 🖥️ FE (前端) | `frontend/` | `docs/agents/fe.md` |
+| ⚙️ BE (后端) | `src/api/`, `src/core/`, `src/llm/`, `src/data/` | `docs/agents/be.md` |
+| 🚀 Ops (部署) | `Dockerfile`, `docker-compose.yml`, 配置 | `docs/agents/ops.md` |
+
+## 技术栈
+
+- **后端**: Python 3.11+, FastAPI, SQLAlchemy async, PostgreSQL
+- **前端**: React, TypeScript, Vite, Tailwind CSS
+- **LLM**: OpenAI-compatible (OpenAI / Deepseek / Ollama)
+- **数据源**: bzzoiro, understat, api-football
+
+## 常用命令
+
+```bash
+# 后端
+uvicorn src.api.app:app --reload        # 启动 API
+pytest                                   # 测试
+alembic upgrade head                     # 数据库迁移
+
+# 前端
+cd frontend && npm run dev               # 开发
+cd frontend && npm run build             # 构建
+
+# 部署
+docker compose up -d                     # 启动全部服务
+```
+
+## 协作原则
+
+- 每个 Agent 在自己的所有权范围内工作
+- 跨 Agent 变更通过接口契约协调（REST API / ORM 模型 / docker-compose）
+- 修改接口前通知相关 Agent
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
new file mode 100644
index 0000000..684b84a
--- /dev/null
+++ b/docs/AGENTS.md
@@ -0,0 +1,128 @@
+# 多 Agent 协同架构
+
+本项目采用 4 个专业 Agent 协同工作,各司其职。
+
+## Agent 职责
+
+### 🗄️ 数据库 Agent (DBA)
+**所有权:** `src/db/`, `alembic/`, 数据模型
+
+职责:
+- 数据库 schema 设计与迁移 (Alembic)
+- ORM 模型定义与关系
+- 查询性能优化与索引
+- 数据完整性约束
+- 数据源入库逻辑
+
+边界:
+- 不写业务路由
+- 不写前端代码
+- 对外暴露稳定的模型接口
+
+---
+
+### 🖥️ 前端 Agent (FE)
+**所有权:** `frontend/`
+
+职责:
+- React 组件与页面
+- 用户界面与交互
+- 状态管理
+- API 调用与数据展示
+- 样式 (Tailwind)
+
+边界:
+- 不直接操作数据库
+- 不写后端业务逻辑
+- 通过 REST API 与后端通信
+
+---
+
+### ⚙️ 后端 Agent (BE)
+**所有权:** `src/api/`, `src/core/`, `src/llm/`, `src/data/`
+
+职责:
+- API 路由与业务逻辑
+- LLM 预测管线 (上下文构建 → 调用 → 存储)
+- 数据采集与清洗
+- 定时任务调度
+- 多 Agent 编排 (LLM 专家系统)
+
+边界:
+- 不写前端展示
+- 不直接配置部署环境
+- 对外暴露 REST API
+
+---
+
+### 🚀 部署 Agent (Ops)
+**所有权:** `Dockerfile`, `docker-compose.yml`, `.env.example`, 配置
+
+职责:
+- 容器化与编排
+- 环境变量与配置管理
+- 服务健康检查
+- 日志与监控
+- 备份策略
+
+边界:
+- 不写应用代码
+- 不修改业务逻辑
+- 通过配置文件影响行为
+
+---
+
+## 协作接口
+
+### FE ↔ BE
+```
+REST API (OpenAPI 契约)
+- GET  /api/v1/matches
+- POST /api/v1/predict
+- GET  /api/v1/predictions
+- POST /api/v1/eval/settle
+- GET  /api/v1/backtest
+```
+
+### BE ↔ DBA
+```
+SQLAlchemy 模型接口
+- Match, Team, League, MatchStats, Prediction, Injury
+- AsyncSession 依赖注入
+```
+
+### BE ↔ LLM
+```
+LLMProvider 抽象
+- OpenAI / Deepseek / Ollama / 任意兼容网关
+- JSON mode 结构化输出
+```
+
+### Ops ↔ 所有
+```
+环境变量 + docker-compose
+- .env 配置注入
+- 服务发现 (localhost:8000 / 5432)
+```
+
+---
+
+## 工作流程
+
+```
+1. 用户/编排者 发起任务
+2. 拆解任务分配给对应 Agent
+3. Agent 在各自所有权范围内工作
+4. 跨 Agent 变更通过接口契约协调
+5. 集成测试验证协作
+```
+
+## 变更协调规则
+
+| 变更类型 | 需要协调 |
+|---|---|
+| 新增 API 字段 | BE + FE |
+| 修改数据模型 | DBA + BE + FE |
+| 新增数据源 | DBA + BE |
+| 修改部署配置 | Ops + 所有 |
+| 修改 LLM Prompt | BE (独立) |
diff --git a/docs/agents/be.md b/docs/agents/be.md
new file mode 100644
index 0000000..e5a6637
--- /dev/null
+++ b/docs/agents/be.md
@@ -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）
diff --git a/docs/agents/dba.md b/docs/agents/dba.md
new file mode 100644
index 0000000..47e4e5c
--- /dev/null
+++ b/docs/agents/dba.md
@@ -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 路由
+- 不写前端代码
+- 不修改业务逻辑
diff --git a/docs/agents/fe.md b/docs/agents/fe.md
new file mode 100644
index 0000000..1079ef6
--- /dev/null
+++ b/docs/agents/fe.md
@@ -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 协商）
+
+## 不做
+- 不写后端业务逻辑
+- 不操作数据库
+- 不修改部署配置
diff --git a/docs/agents/ops.md b/docs/agents/ops.md
new file mode 100644
index 0000000..d5c6833
--- /dev/null
+++ b/docs/agents/ops.md
@@ -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 契约