From c2b8a37bdd2262e4d4c9ef26a63ad320d03e39be Mon Sep 17 00:00:00 2001 From: shangfangjian Date: Mon, 14 Sep 2026 22:09:28 +0800 Subject: [PATCH] =?UTF-8?q?Revert=20"docs:=20=E5=BB=BA=E7=AB=8B=E5=A4=9A?= =?UTF-8?q?=20Agent=20=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 This reverts commit f50784f9dc07e22d1fa34fb1461569ddce47370b. --- 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 deletions(-) delete mode 100644 CLAUDE.md delete mode 100644 docs/AGENTS.md delete mode 100644 docs/agents/be.md delete mode 100644 docs/agents/dba.md delete mode 100644 docs/agents/fe.md delete mode 100644 docs/agents/ops.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 958c76f..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 deleted file mode 100644 index 684b84a..0000000 --- a/docs/AGENTS.md +++ /dev/null @@ -1,128 +0,0 @@ -# 多 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 deleted file mode 100644 index e5a6637..0000000 --- a/docs/agents/be.md +++ /dev/null @@ -1,61 +0,0 @@ -# 后端 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 deleted file mode 100644 index 47e4e5c..0000000 --- a/docs/agents/dba.md +++ /dev/null @@ -1,36 +0,0 @@ -# 数据库 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 deleted file mode 100644 index 1079ef6..0000000 --- a/docs/agents/fe.md +++ /dev/null @@ -1,46 +0,0 @@ -# 前端 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 deleted file mode 100644 index d5c6833..0000000 --- a/docs/agents/ops.md +++ /dev/null @@ -1,47 +0,0 @@ -# 部署 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 契约