clutch/docs/Clutch_Prediction_Implementation_Plan.md

Project Clutch-IQ: CS2 实时胜率预测系统实施方案

Version: 3.0 (Final Architecture) Date: 2026-01-31 Status: Ready for Implementation

---

1. 项目愿景 (Vision)

构建一个职业级、物理感知、战术驱动的 CS2 实时残局胜率预测引擎。 该系统不仅输出胜率数值（如 "CT Win 30%"），更能解析战术成因（如“因缺少拆弹钳且时间不足”），服务于赛后复盘、直播增强和战术分析。

---

2. 核心架构 (Architecture)

2.1 三层流水线设计

1. Phase 1: 数据快照引擎 (Snapshot Engine) - ETL 层
   • 负责从 Demo 解析高频、高精度的“战术切片”。
2. Phase 2: 特征工程工厂 (Feature Factory) - 逻辑层
   • 将原始数据转化为物理特征（路径距离）和博弈特征（交叉火力）。
3. Phase 3: 模型预测服务 (Inference Service) - 应用层
   • 基于 XGBoost/LightGBM 提供毫秒级实时预测。

---

3. 详细实施蓝图 (Implementation Roadmap)

Phase 1: 高精度数据快照 (The Snapshot Engine)

1.1 智能触发器 (Smart Triggers)

为了过滤冗余数据，系统仅在以下时刻捕获快照：

• 关键事件：Player_Death, Bomb_Plant, Bomb_Defuse_Start, Bomb_Defuse_End
• 状态剧变：任意玩家 HP 损失 > 20（捕捉对枪结果）
• 时间心跳：残局阶段 (≤3v3) 每 5 秒强制采样一次

1.2 标准化快照字段 (Snapshot Schema)

每个快照包含 4 类核心数据：

类别	字段名	说明	来源
元数据	match_id, round, tick	唯一索引	Demo
局势	bomb_state, bomb_timer	C4 状态 (0:未下, 1:已下, 2:被拆)	Demo
局势	seconds_remaining	回合/C4 倒计时	Demo
人员	ct_alive, t_alive	存活人数	Demo
人员	ct_hp_sum, t_hp_sum	团队总血量	Demo
装备	ct_has_kit, t_has_c4	关键道具 (钳子/C4)	Demo
空间	ct_positions, t_positions	原始坐标 (用于后续计算)	Demo

---

Phase 2: 特征工程与融合 (Feature Engineering)

2.1 物理感知特征 (Physics-Aware Features)

• F1: 路径距离 (NavMesh Distance)
  • 革新点：放弃欧氏距离，使用地图路网计算真实移动距离。
  • 实现：预计算 Map_Zone_Distance_Matrix，实时查询。
• F2: 时间压力指数 (Time Pressure Index - TPI)
  • 公式：TPI = \frac{\text{TravelTime} + \text{DefuseTime}}{\text{TimeRemaining}}
  • 判定：TPI > 1.0 \rightarrow 胜率强制归零。
• F3: 视线与掩体 (Line of Sight)
  • 特征：is_blind (致盲状态), is_in_smoke (烟雾状态)。

2.2 战术博弈特征 (Tactical Features)

• F4: 交叉火力系数 (Crossfire Coefficient)
  • 逻辑：计算多名 CT 与目标 T 的夹角。夹角接近 90° 时胜率加成最大。
• F5: 经济势能差 (Economy Momentum)
  • 公式：\Delta E = \text{CT\_Equip\_Value} - \text{T\_Equip\_Value}
  • 作用：量化“长枪打手枪”的装备压制力。

2.3 选手画像注入 (Player Profiling)

利用 L3 数据库增强模型对“人”的理解：

• F6: 明星光环：max_alive_rating (存活最强选手的 Rating)。
• F7: 残局专家：avg_clutch_win_rate (存活选手的历史残局胜率)。

---

Phase 3: 模型训练与策略 (Modeling Strategy)

3.1 训练配置

• 算法：XGBoost (分类器)
• 目标函数：LogLoss (优化概率准确性)
• 评估指标：AUC (排序能力), Brier Score (校准度)

3.2 样本清洗策略

• 剔除保枪局 (Filter Save Rounds)：
  • 若残局结束时：Damage_Dealt == 0 AND Dist_To_Enemy > 50m AND Weapon_Value > 2000
  • 判定为“主动放弃”，剔除样本，防止污染胜率模型。

---

4. 交付物清单 (Deliverables)

1. extract_snapshots.py
   • 基于 demoparser2 的 Python 脚本，批量处理 Demo 生成 CSV 训练集。
2. map_nav_graph.json
   • 核心地图 (Mirage, Inferno 等) 的区域距离查找表。
3. Clutch_Predictor_Model.pkl
   • 训练好的 XGBoost 模型文件。
4. Win_Prob_Service.py
   • 简单的 Flask 接口：输入当前状态 JSON \rightarrow 输出 { "ct_win_prob": 0.35, "key_factor": "time_pressure" }。

---

5. 下一步行动 (Action Items)

1. [High Priority] 开发 extract_snapshots.py 原型，跑通基础数据流。
2. [Medium Priority] 构建 Mirage 地图的简单网格距离表。
3. [Medium Priority] 整合 L3 数据库，生成选手能力特征表。