# 天璇 TLS 流量分析工作流

## 工具总览（27 个 MCP 工具）

### ⚡ 核心工具（7个）— 执行实际分析，可修改数据

| 工具 | 输入 | 输出 | 何时调用 |
|------|------|------|---------|
| `profile_data` | dataset_id | 列类型/统计/空值率 | 第一步，了解数据 |
| `build_entity_profiles` | dataset_id, [entity_column] | 实体画像数据集 | 确定实体列后 |
| `compute_scores` | dataset_id | proxy_score/risk_level/threat_score | 实体画像完成后 |
| `run_clustering` | dataset_id, cluster_columns, algorithm | 聚类结果 | 需要行为分组时 |
| `extract_features` | dataset_id, cluster_result_id | 各组区分特征 | 聚类完成后 |
| `detect_anomalies` | dataset_id, [contamination] | 异常实体列表 | 评分完成后 |
| `visualize_anomalies` | dataset_id | PCA散点数据 | 评分/检测完成后 |

### 🔍 分析工具（5个）— 只读，安全可随时调用

| 工具 | 功能 | 典型场景 |
|------|------|---------|
| `analyze_patterns` | 热门IP/端口/TLS版本分布 | 快速了解流量结构 |
| `analyze_tls_health` | TLS安全评估（旧版比例/弱加密） | 安全审计 |
| `analyze_geo_distribution` | 地理分布/不可能旅行 | 检测跨国代理 |
| `analyze_entity_detail` | 单实体深度调查 | 可疑实体深入分析 |
| `analyze_temporal` | 时间维度流量模式 | 理解流量周期性 |

### 🩺 诊断工具（7个）— 排查问题

| 工具 | 解决什么问题 |
|------|-------------|
| `validate_data` | 数据质量：空列、常量列、schema不一致 |
| `explore_distributions` | 查看列分布统计，理解数据 |
| `find_outliers` | 发现极端值 |
| `diagnose_clustering` | 聚类效果差时诊断原因 |
| `compare_datasets` | 对比处理前后的数据差异 |
| `export_debug_sample` | 导出JSON供人工检查 |
| `repair_schema` | 修复列名不一致 |

### 其他（8个）

`load_data`, `filter_data`, `preprocess_data`, `evaluate_clustering`, `export_results`, `list_datasets`, `drop_dataset`, `clone_dataset`

---

## 标准分析流程

```
load_data → profile_data → build_entity_profiles → compute_scores → run_clustering → extract_features
```

### 完整步骤

#### 1. 加载数据
```
工具: load_data
参数: csv_glob="data/*.csv"
说明: 支持glob模式，自动合并同结构多文件
```

#### 2. 了解数据
```
工具: profile_data
参数: dataset_id="..."
说明: 查看列数、类型、空值率、统计摘要
```
> **可选**: 调用 `analyze_patterns` 查看更多流量结构信息

#### 3. 构建实体画像
```
工具: build_entity_profiles
参数: dataset_id="...", auto_detect=true
说明: 自动检测实体列(IP/SNI等)，聚合流数据为实体特征
```
> 如果自动检测失败 → 调用 `explore_distributions` 查看候选列

#### 4. 计算异常分数
```
工具: compute_scores
参数: dataset_id="<entity_dataset_id>"
说明: PCA自动学习权重，输出 proxy_score / risk_level / threat_score
```

#### 5. 检测异常（可选）
```
工具: detect_anomalies
参数: dataset_id="...", contamination=0.05
说明: Isolation Forest 找出异常实体
```

#### 6. 聚类分析
```
工具: run_clustering
参数: dataset_id="...", cluster_columns=[...], algorithm="hdbscan"
说明: 实体行为分组
```
> 如果聚类效果差 → 调用 `diagnose_clustering` 诊断

#### 7. 提取特征
```
工具: extract_features
参数: dataset_id="...", cluster_result_id="...", method="zscore"
说明: 找出每组区分特征
```

#### 8. 可视化
```
工具: visualize_anomalies
参数: dataset_id="..."
说明: PCA降维，散点图数据
```

---

## 异常排查流程

### 数据加载失败
```
load_data 报错
  → validate_data: 检查 schema 问题
  → repair_schema: 修复列名不一致
  → 重试 load_data
```

### 实体检测失败
```
build_entity_profiles 返回无实体列
  → explore_distributions: 检查各列unique值
  → 手动指定 entity_column 重试
```

### 聚类效果差
```
run_clustering 返回 1 个簇或全噪声
  → diagnose_clustering: 诊断原因
  → 根据诊断调整参数重试
  → 或用 analyze_tls_health 检查 TLS 质量
```

### 分数异常
```
compute_scores 后多数实体分数极高/低
  → explore_distributions: 检查各特征分布
  → find_outliers: 找出极端值
  → analyze_entity_detail: 深入调查可疑实体
```

---

## LLM自动模式

在配置页面设置 LLM 后，`LLM分析` 页面会自动编排工具链。LLM 的策略：

1. 先 `profile_data` 了解数据
2. 根据 profile 决定下一步
3. 失败时自动调用诊断工具
4. 分析过程中随时调用只读分析工具深入了解
5. 中文总结分析结果

> 可通过配置文件调整 LLM 参数 (config.yaml → llm)
