# 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 数据库，生成选手能力特征表。