Profeto/docs/AGENTS.md

多 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 (独立)