# kpl-anlayize **Repository Path**: beihaiRK07/kpl-analyse ## Basic Information - **Project Name**: kpl-anlayize - **Description**: kpl分析 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-27 - **Last Updated**: 2026-06-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # KPL AI 赛训数据引擎 - 详细项目结构说明文档 ## 项目简介 KPL AI 赛训数据引擎是一个基于 Python 的现代化数据分析平台，专注于王者荣耀职业联赛（KPL）的赛事数据处理和智能分析。该项目集成了数据爬取、数据净化、AI 智能体分析、Web API 服务和前端可视化等功能，为 KPL 战队和分析师提供全面的数据洞察服务。 项目采用模块化设计，使用 FastAPI 构建后端服务，集成 DeepSeek 大模型驱动五大 AI 代理（含赛训战略教练 Agent），支持实时数据采集和多维度数据可视化。 **核心特性：** - 自动化数据采集：基于 Playwright 的浏览器自动化爬虫 - 智能数据分析：五大 AI 代理（战队 / 赛事 / 选手 / 英雄 / 教练）协同分析 - 赛训战略决策：教练 Agent 统筹四领域 Agent，输出审视、追问与决策简报 - 实时 Web 服务：FastAPI + Vue.js 的前后端分离架构 - 多维度可视化：Matplotlib 和 ECharts 支持的图表展示 - 模块化设计：清晰的代码结构，便于维护和扩展 ## 整体架构 项目采用前后端分离架构： - **后端**：基于 FastAPI 的 Python 服务，提供 RESTful API - **前端**：基于 Vue.js + Vite 的现代化 Web 应用 - **数据层**：本地文件系统存储，包含原始数据和处理后的 Markdown 数据 - **AI 层**：领域 Agent 问答 + 教练 Agent 战略编排，基于 DeepSeek API（OpenAI 兼容） - **爬虫层**：基于 Playwright 的自动化数据采集系统 **架构优势：** - 微服务化设计，各模块职责清晰 - API 驱动的前后端分离，便于独立开发和部署 - 本地数据存储，减少外部依赖，提高响应速度 - AI 能力集成，提供智能化数据分析服务 ## 目录结构详解 ``` KPL/ ├── backend_api.py # FastAPI 后端主入口 ├── main.py # 数据采集和可视化主程序 ├── requirements.txt # Python 依赖包列表 ├── .env # 环境变量配置文件（API 密钥等） ├── pyrightconfig.json # Python 类型检查配置 ├── agent_test/ # AI 代理测试模块 │ ├── main.py │ ├── agent_model/ # 代理模型定义 │ ├── controller/ # 控制器层 │ ├── expert/ # 专家系统 │ ├── Markdown/ # Markdown 数据处理 │ ├── rules/ # 规则配置 │ └── tests/ # 测试用例 ├── agent_web/ # Web AI 代理服务 │ ├── __init__.py │ ├── agents/ # AI 代理实现（战队、赛事、选手、英雄、教练） │ ├── controllers/ # Web 控制器 │ ├── experts/ # 专家分析模块 │ ├── routers/ # API 路由定义 │ ├── rules/ # 业务规则 │ ├── schemas/ # Pydantic 数据模型 │ ├── services/ # 业务服务层 │ └── strategy/ # 赛训战略编排（教练 Agent 流水线） ├── core/ # 核心工具模块 │ ├── logger.py # 日志配置 ├── data/ # 数据存储目录 │ ├── charts/ # 图表数据 │ ├── heroes/ # 英雄数据 │ ├── markdown_table/ # Markdown 表格数据 │ ├── matches/ # 比赛数据 │ ├── players/ # 选手数据 │ ├── purified/ # 净化后的数据 │ └── teams/ # 战队数据 ├── fronted/ # 前端 Vue.js 项目 │ ├── index.html │ ├── package.json # Node.js 依赖 │ ├── vite.config.js # Vite 配置 │ └── src/ # 前端源码 ├── purification/ # 数据净化模块 │ ├── hero_purifier.py # 英雄数据净化 │ ├── match_purifier.py # 比赛数据净化 │ ├── player_purifier.py # 选手数据净化 │ └── team_purifier.py # 战队数据净化 ├── reports/ # 报告生成目录 ├── routers/ # 传统数据 API 路由 │ ├── heroes.py # 英雄数据路由 │ ├── matches.py # 比赛数据路由 │ ├── players.py # 选手数据路由 │ ├── system.py # 系统路由 │ └── teams.py # 战队数据路由 ├── spiders/ # 数据爬虫模块 │ ├── base.py # 爬虫基类 │ ├── hero_spider.py # 英雄数据爬虫 │ ├── match.py # 比赛数据爬虫 │ ├── player_spider.py # 选手数据爬虫 │ └── team_spider.py # 战队数据爬虫 ├── tests/ # 项目测试 ├── tools/ # 工具脚本 │ ├── hero_visualizer.py # 英雄可视化工具 │ ├── player_visualizer.py # 选手可视化工具 │ └── team_visualizer.py # 战队可视化工具 └── utils/ # 工具函数 ├── data_loader.py # 数据加载器 └── match_processor.py # 比赛数据处理器 ``` ## 主要功能模块详细说明 ### 1. 数据采集层 (Spiders) 数据采集层负责从腾讯游戏官网自动获取 KPL 相关数据，是整个系统的数据入口。 #### base.py - 爬虫基类 - 定义了所有爬虫的通用接口和方法 - 实现了浏览器初始化、页面加载、元素等待等基础功能 - 提供错误处理和重试机制 - 使用 Playwright 进行浏览器自动化 #### hero_spider.py - 英雄数据爬虫 - 爬取英雄胜率、登场率、ban率等统计数据 - 支持按赛季和版本筛选数据 - 生成英雄数据 JSON 文件 - 处理英雄图片和基本信息 #### player_spider.py - 选手数据爬虫 - 采集选手 KDA、输出伤害、承伤等个人数据 - 支持选手排名和统计分析 - 处理选手所属战队和位置信息 #### team_spider.py - 战队数据爬虫 - 获取战队胜率、排名、积分等数据 - 采集战队成员信息和战术统计 - 支持战队历史数据追踪 #### match.py - 比赛数据爬虫 - 详细采集每场比赛的对局数据 - 包括 BP（ban/pick）、选手表现、关键事件 - 生成比赛回放和统计数据 ### 2. 数据处理层 (Purification) 数据净化层对原始爬取数据进行清洗、标准化和结构化处理。 #### 数据净化流程 1. **数据验证**：检查数据完整性和格式正确性 2. **去重处理**：消除重复数据记录 3. **格式标准化**：统一数据格式和字段命名 4. **异常值处理**：识别和处理异常数据 5. **数据关联**：建立数据间的关联关系 #### 各净化器功能 - **hero_purifier.py**：英雄数据标准化，计算综合评分 - **player_purifier.py**：选手数据规范化，添加统计指标 - **team_purifier.py**：战队数据整合，计算团队统计 - **match_purifier.py**：比赛数据结构化，生成分析报告 ### 3. AI 智能体层 (Agent Web) AI 智能体层是项目的核心智能模块，集成大模型进行智能问答分析。 #### 代理架构 - **Agent**：直接与 AI 模型交互的核心类 - **Controller**：处理用户查询，管理对话流程 - **Expert**：领域知识专家，提供数据检索和预处理 - **Rule Engine**：规则引擎，根据查询类型应用不同分析规则 #### 五大智能体 前四个为**领域 Agent**，负责各自维度的量化分析；第五个为**教练 Agent**，负责统筹协作与战略决策。 ##### TeamAgent (战队分析师) - 分析战队整体实力和战术风格 - 提供战队对比分析 - 支持阵容搭配建议 - 基于战队数据进行战略分析 ##### MatchAgent (赛事复盘分析师) - 详细分析比赛过程和关键事件 - 提供 BP 分析和战术点评 - 支持比赛对比和趋势分析 - 生成专业的比赛报告 ##### PlayerAgent (选手分析师) - 分析选手个人表现数据 - 提供选手成长趋势分析 - 支持选手对比和定位分析 - 结合选手历史数据给出建议 ##### HeroAgent (英雄分析师) - 分析英雄胜率、ban率趋势 - 提供版本答案和英雄推荐 - 支持英雄对比分析 - 基于本地英雄数据进行推理 ##### CoachAgent (赛训战略教练) - 统筹四个领域 Agent 的协作结论，而非简单汇总 - **审视**：识别 Agent 之间的矛盾、盲区与冗余 - **追问**：向特定领域 Agent 发起针对性补充提问 - **决策**：输出《教练决策简报》，含 BP 建议、赛训要点与取舍说明 - 规则模式：`RuleComposer(mode="coach")`，自动组合 BP / 阵容 / 节奏等规则包 #### 赛训战略流水线 (Strategy Pipeline) 战略模式由 `agent_web/strategy/` 编排，流水线 ID 为 `kpl_strategy_v3_coach_managed`： ``` Team → Match → Player → Hero → Coach 审视 → Coach 追问 → Coach 决策 ``` | 阶段 | 说明 | |------|------| | 四领域串行协作 | 战队定盘 → 赛事举证 → 选手对位 → 英雄 BP，逐轮传递 peer 结论 | | 教练审视 | 识别矛盾 / 盲区 / 冗余，生成追问清单 | | 教练追问 | 按清单向特定 Agent 补充提问 | | 教练决策 | 综合初始结论 + 审视 + 追问回答，输出最终简报 | **数据要求**：选手、战队、英雄、赛事四类 Markdown 均需就绪（`strategy_ready: true`）。 **前端入口**：侧边栏「战略决策」→ `/agent-web/strategy` **主要 API**： - `POST /api/agent/strategy/chat` — 完整流水线，返回教练决策简报 - `GET /api/agent/strategy/pipeline/schema` — 流水线阶段说明 - `POST /api/agent/strategy/pipeline/run` — 运行完整流水线（含各阶段输出） - `POST /api/agent/strategy/pipeline/stage` — 运行至指定阶段 #### AI 模型配置 - **领域 / 教练 Agent**：DeepSeek API（`deepseek-chat`，OpenAI 兼容格式） - **参数设置**： - temperature: 0.3 (平衡准确性和多样性) - stream: 可选（战略模式支持 SSE 流式） - **提示工程**：针对每个领域及教练模式定制系统提示词与规则包 ### 4. API 服务层 (Routers) API 服务层提供 RESTful 接口，支持前端调用和外部集成。 #### 路由模块 - **heroes.py**：英雄数据查询接口 - **players.py**：选手数据查询接口 - **teams.py**：战队数据查询接口 - **matches.py**：比赛数据查询接口 - **system.py**：系统状态和配置接口 #### Agent Web 路由 - **hero.py**：英雄 AI 问答接口 - **player.py**：选手 AI 问答接口 - **team.py**：战队 AI 问答接口 - **match.py**：比赛 AI 问答接口 - **strategy.py**：赛训战略流水线（教练 Agent 统筹四领域 Agent） #### API 特性 - 标准的 RESTful 设计 - JSON 数据格式 - CORS 跨域支持 - 请求验证和错误处理 - 分页和过滤支持 ### 5. 可视化层 (Tools) 可视化层提供数据图表生成功能，支持多种图表类型。 #### 可视化工具 - **hero_visualizer.py**：英雄数据雷达图 - **player_visualizer.py**：选手表现雷达图 - **team_visualizer.py**：战队数据雷达图 #### 图表类型 - **雷达图**：多维度数据对比展示 - **柱状图**：数据量对比 - **线图**：趋势分析 - **饼图**：占比分析 #### 输出格式 - PNG 图片文件 - 支持自定义样式和颜色 - 高分辨率输出 - 自动布局优化 ### 6. 前端展示层 (Fronted) 前端采用现代 Web 技术栈，提供用户友好的界面。 #### 技术栈 - **Vue.js 3**：渐进式 JavaScript 框架 - **Vite**：快速构建工具 - **Element Plus**：Vue 3 UI 组件库 - **ECharts**：专业图表库 - **Axios**：HTTP 客户端 #### 主要功能 - 数据查询和展示 - AI 智能问答界面（战队 / 赛事 / 选手 / 英雄） - 赛训战略决策界面（教练 Agent 多阶段协作展示） - 图表可视化展示 - 响应式设计 - 实时数据更新 ## 运行指南 ### 环境要求 - Python 3.11+ - Node.js 16+ (前端开发) - Windows/Linux/macOS ### 后端启动 ```bash # 安装依赖 py -3.11 -m pip install -r requirements.txt # 启动后端服务 py -3.11 backend_api.py ``` 服务将在 http://127.0.0.1:8000 启动，API 文档访问 http://127.0.0.1:8000/docs ### 前端启动 ```bash cd fronted npm install npm run dev ``` 前端将在 http://localhost:5173 启动 ### 数据采集 运行主程序进行数据采集： ```bash py -3.11 main.py ``` 支持交互式菜单： 1. 采集概览数据 2. 生成可视化图表 3. 采集比赛详情 ## 配置说明 ### 环境变量 (.env) ```dotenv DEEPSEEK_API_KEY="your_deepseek_key_here" # Agent Web / 教练 Agent 使用 DEEPSEEK_BASE_URL="https://api.deepseek.com" # 可选，默认值如上 DEEPSEEK_MODEL="deepseek-chat" # 可选，默认值如上 ZHIPU_API_KEY="your_zhipu_key_here" # 其他模块如需智谱 AI 时使用 ``` ### AI 模型配置 - **Agent Web / 教练 Agent**: DeepSeek (`deepseek-chat`)，SDK 为 `openai` - **温度参数**: 0.3 (平衡创造性和准确性) ### 数据存储配置 - 数据文件存储在 `data/` 目录下 - 支持 JSON 和 Markdown 格式 - 按赛季 ID 组织数据结构 ## 依赖项说明 ### Python 主要依赖 - **fastapi**: Web 框架 - **uvicorn**: ASGI 服务器 - **playwright**: 浏览器自动化 - **openai**: DeepSeek API（OpenAI 兼容客户端） - **zai-sdk**: 智谱 AI SDK（可选） - **matplotlib**: 数据可视化 - **pandas**: 数据处理 - **beautifulsoup4**: HTML 解析 ### 前端主要依赖 - **vue**: 3.5.32 - **element-plus**: UI 组件库 - **echarts**: 图表库 - **axios**: HTTP 客户端 ## 开发和部署 ### 开发模式 - 后端支持热重载 (`reload=True`) - 前端使用 Vite 开发服务器 - 支持跨域调试 ### 生产部署 - 使用 uvicorn 生产服务器 - 前端构建静态文件 - 配置反向代理 (Nginx) ### 测试 - 单元测试在 `tests/` 目录 - AI 代理测试在 `agent_test/` - 支持 pytest 框架 ## 注意事项 1. **API 密钥**: 使用 Agent / 教练功能时需配置 `DEEPSEEK_API_KEY`；战略模式还需四类 Markdown 数据就绪 2. **数据采集**: 遵守腾讯游戏数据使用条款，避免过度请求 3. **性能优化**: 大数据集处理时注意内存使用 4. **版本兼容**: 确保 Python 版本为 3.11+ 以保证最佳兼容性 这个项目展示了现代数据工程的最佳实践，结合了爬虫技术、AI 智能和 Web 开发，为电竞数据分析提供了完整的解决方案。