PM-pinou
12 KiB
12 KiB
天璇 (TianXuan) — Agent Knowledge Base
Project Identity
| Field | Value |
|---|---|
| 项目名称 | 天璇 (TianXuan) |
| 原始名称 | tls-analyzer |
| 核心功能 | TLS 流数据分析、实体画像、聚类、3D地球可视化、PCA散点图 |
| Python 版本 | 3.12 (embedded portable at runtime/python/python.exe) |
| Polars 版本 | 1.42.1 (精确锁定) |
| 数据框架 | Polars (LazyFrame + streaming) |
| 机器学习 | scikit-learn (HDBSCAN, KMeans, PCA, StandardScaler) |
| Web框架 | Django 4.2 + SQLite WAL |
| 前端3D | Three.js (603KB, 离线, 地球贴图1.4MB) |
| 前端图表 | 纯Canvas散点图 (无Chart.js) |
| LLM协议 | MCP (stdio transport) |
| 启动方式 | run.bat（双击即用）/ runtime\python\python.exe manage.py runserver（开发） |
Project Structure
tianxuan/
├── tianxuan/ # Django 项目配置
│ ├── settings.py # ALLOWED_HOSTS 自动检测, LOGGING 文件+stderr
│ ├── wsgi.py # SQLite 启动自修复
│ ├── urls.py
│ └── llm_orchestrator.py # LLM 编排器 (32B/284B 双兼容)
│
├── analysis/ # 核心分析模块 (Django app)
│ ├── data_loader.py # CSV 加载, BOM检测, schema_strict, 递归glob, 中文路径
│ ├── data_profiler.py # 列统计 + 相关性矩阵 (无pandas回退:numpy)
│ ├── entity_detector.py # 实体列自动检测 (tuple关键词 + unique_ratio + null惩罚)
│ ├── entity_aggregator.py # 实体聚合 (tuple关键词, lat/lon检测, 多列group_by, IP子网)
│ ├── session_store.py # 线程安全单例内存存储
│ ├── tool_registry.py # 12个MCP工具 + DB持久化 (sync_to_async)
│ ├── mcp_server.py # MCP stdio server
│ ├── views.py # 所有Django视图 (上传/手动/LLM/配置/LLM测试/日志/地球)
│ ├── urls.py # 16条路由
│ ├── models.py # ORM: AnalysisRun, ClusterResult, EntityProfile, ClusterFeature
│ ├── data_validator.py # 列校验 (缺失率/异常值/IP有效性)
│ ├── type_classifier.py # 值优先类型检测 (MAC/端口/IPv4/URL/HEX/ENUM/LAT_LON)
│ ├── geoip.py # GeoIP 经纬度查询 (data/geoip_data.txt)
│ ├── admin.py
│ └── management/commands/
│ ├── start_mcp.py # MCP服务器启动命令
│ └── run_pipeline.py # 一键CLI管道命令
│
├── config/
│ ├── config.yaml # 自动生成默认配置 (含entity.subnet_masks, columns覆盖)
│ ├── loader.py # Pydantic 配置加载 + 文件修改检测
│ └── __init__.py
│
├── templates/
│ ├── base.html # 导航: 首页/上传/手动/LLM/记录/地球/配置
│ └── analysis/ 或 tianxuan/ # 全部11个页面模板
│ ├── dashboard.html # 首页 - 最近运行
│ ├── upload.html # CSV上传 - 拖拽+多文件+删除+进度
│ ├── manual.html # 3步手动向导 - 选数据→设参数→运行
│ ├── auto.html # LLM自动分析 - 实时日志窗+取消
│ ├── config.html # 配置编辑 - LLM连通性测试
│ ├── run_list.html # 运行记录列表
│ ├── run_detail.html # 运行详情摘要
│ ├── cluster_overview.html # 聚类概览 - 纯Canvas散点图+PCA+地理
│ ├── cluster_detail.html # 簇详情 - 特征表+实体列表
│ ├── entity_profile.html # 实体画像 - 特征偏离+Canvas单点图
│ ├── globe.html # 3D地球可视化 - Three.js 流量弧线+经纬线+国境线
│ └── log_viewer.html # 日志查看
│
├── static/tianxuan/ # 离线静态资源
│ ├── three.min.js # Three.js 3D引擎 (603KB)
│ ├── earth_atmos_2048.jpg # 地球贴图 (1.4MB)
│ └── world_borders.js # 10国精简国境线轮廓
│
├── runtime/python/ # 便携Python 3.12运行时 (~593MB)
│
├── scripts/
│ ├── gen_test_data.py # 简单测试数据生成 (--globe模式使用真实GeoIP范围)
│ ├── gen_complex_test.py # 复杂数据生成 (5000行24列含55%缺失)
│ ├── column_survey.py # CSV列结构调查 (统计各CSV的列名/类型/分布)
│ ├── diagnose_compare.py # 跨机日志对比诊断
│ └── debug_db.py # DB持久化调试
│
├── tests/ # 121个测试
│ ├── test_data_loader.py # 26: BOM/schema/中文路径/递归glob
│ ├── test_entity.py # 17: 关键词/检测/聚合
│ ├── test_e2e.py # 6: 全端到端
│ └── test_clustering_edge.py # HDBSCAN零样本降级
│
├── docs/
│ ├── 工作流.md # 完整分析流水线文档
│ └── 故障诊断手册.md # 跨机问题诊断指南
│
├── run.bat # 用户启动 (含PYTHONUTF8=1)
├── shell.bat # Django shell
├── README.md
├── AGENTS.md
└── manage.py
12 MCP Tools
| # | 工具名 | 功能 | 必需参数 |
|---|---|---|---|
| 1 | load_data |
加载 CSV 文件（glob / 递归 / schema容错） | csv_glob |
| 2 | profile_data |
数据集概要统计 + 相关性矩阵 | dataset_id |
| 3 | filter_data |
按条件过滤（12操作符 + AND/OR） | dataset_id, filters |
| 4 | preprocess_data |
预处理（标准化/编码/填充） | dataset_id, columns |
| 5 | run_clustering |
执行聚类（HDBSCAN/KMeans + 质量评估） | dataset_id, cluster_columns |
| 6 | evaluate_clustering |
评估聚类质量（Silhouette/DB/CH） | cluster_result_id, dataset_id |
| 7 | extract_features |
提取各聚类区分特征（Z-Score/ANOVA） | dataset_id, cluster_result_id |
| 8 | export_results |
导出结果到磁盘（CSV/Parquet/JSON） | result_id, output_path |
| 9 | list_datasets |
列出所有活跃数据集 | 无 |
| 10 | drop_dataset |
删除数据集释放内存 | dataset_id |
| 11 | clone_dataset |
浅拷贝数据集（不复制数据） | dataset_id |
| 12 | build_entity_profiles |
自动检测实体列 + 聚合画像 | dataset_id |
所有工具通过 analysis/tool_registry.py 注册，analysis/mcp_server.py 暴露标准 MCP stdio 接口。
Config.Entity 类
config/loader.py 中的 Pydantic 模型：
class Entity(BaseModel):
subnet_masks: list[int] = [] # 子网掩码列表，如 [24, 28]
ip_columns: list[str] = ['src_ip', 'dst_ip'] # 需聚合的IP列
config.yaml 默认配置:
entity:
subnet_masks: [24, 28]
ip_columns: ["src_ip", "dst_ip"]
Architecture
- tuple 替代 frozenset: 避免跨机 PYTHONHASHSEED 差异
- PYTHONUTF8=1: 跨机编码一致性
- 类型安全聚合: 聚合前检查 dtype，非数值列先 cast
- sync_to_async ORM: 异步上下文中的 Django ORM
- 纯 Canvas 图表: 零外部 JS 依赖
- 上传目录隔离: %APPDATA%/TianXuan/data/uploads/，与项目路径无关
- 通用数值清洗 _coerce_to_float: 处理 + / - /空白/N/A 等伪影
- 值优先类型检测: config→值→名称→STRING
- 地球深度测试: depthTest: true, depthWrite: false，r=5.5
- 完整国境线: Natural Earth 110m, 177国, 286多边形, 269KB
Testing Protocol
运行全部测试
runtime\python\python.exe -m pytest tests -q
200 passed
跨机一致性测试
# 两台机器各自执行:
runtime\python\python.exe manage.py run_pipeline data\complex_test.csv
# 对比日志:
runtime\python\python.exe scripts\diagnose_compare.py log_a.txt log_b.txt
DB持久化测试
runtime\python\python.exe scripts\debug_db.py
# 期望: n_features=30 db_saved=True
# 验证: run_analysis 后 ClusterFeature 表有数据
LLM编排测试
runtime\python\python.exe scripts\test_llm_full.py
# 或
runtime\python\python.exe -c "from tianxuan.llm_orchestrator import run_llm_pipeline, LLMConfig; ..."
生成测试数据
# 简单数据
runtime\python\python.exe scripts\gen_test_data.py --rows 1000
# Globe模式 (IP在真实GeoIP范围内)
runtime\python\python.exe scripts\gen_test_data.py --globe
# 复杂数据 (5000行24列55%缺失)
runtime\python\python.exe scripts\gen_complex_test.py --rows 5000
列结构调查
runtime\python\python.exe scripts\column_survey.py --csv "data/*.csv"
Polars Version Compatibility
| API | 旧版(<1.0) | 新版(≥1.0) |
|---|---|---|
| mode | pl.mode() |
pl.col(col).mode() |
| encoding | encoding='utf-8' |
encoding='utf8' |
| value_counts col | 'index' |
原列名 |
| streaming | collect(streaming=True) |
collect(engine='streaming') |
| truth value | if series: |
if series.item(): |
32B LLM Optimization
- Step guidance: 每步告诉模型下一步做什么
- Truncation: 工具结果截断至 1200 chars
- Timeout: 90s (32B 推理更慢)
- Max steps: 15
- Tool description: 一行简洁描述
v6 (2026-07-16) — 基于真实TLS特征的恶意流量分析
| 模块 | 变动 |
|---|---|
| value_normalizer.py | 新增: 0ver/0cph/0crv/cipher-suite/ecdhe-named-curve hex→enum归一化, cnrs/isrs blank→no |
| data_loader.py | 集成normalize_lf到清洗流水线，输出_norm列 |
| entity_aggregator.py | 重构特征: 20+增强TLS特征(has_sni, aead_ratio, tls_modern_ratio, avg_bytes_per_packet, recoverable_ratio等) |
| gen_test_data.py | 3类真实流量画像: 正常浏览(60%)/代理VPN(20%)/恶意可疑(20%) |
| 特征维度 | 20→33维, 覆盖TLS指纹/连接行为/异常检测/时域特征 |
Completed (2026-07-16)
18个问题全部修复，3次端到端管道测试全部通过（简单CSV、用户自定义列名CSV、大规模CSV）。
| 工作流 | 问题 | 状态 |
|---|---|---|
| A1 | 重启后旧数据可分析 | ✅ 目录不存在时优雅降级，标记为failed |
| A2 | Web图标所有页面显示 | ✅ 创建favicon.svg + base.html添加link |
| A3 | 上传按钮在顶部 | ✅ 移至文件列表上方，sticky定位 |
| A10 | 文件上传限制 | ✅ 去除了Django字段限制，增大至256MB/50GB |
| A11 | 上传页删除功能 | ✅ 所有状态显示删除按钮，处理中弹出确认 |
| B7 | TLS 0ver hex格式 | ✅ 添加TLS_HEX_MAP，识别03 03/03 04 |
| B15 | "+"字符串识别为数字 | ✅ FLOAT检测添加+/前缀检查 |
| B18 | 列名映射 | ✅ 使用精确^exact_name$匹配，无模糊猜测 |
| C4 | Traceback截断 | ✅ tool_registry.py移除[:200] |
| D5 | 大数据量卡顿 | ✅ 添加head参数、50K降采样、MAX_ROWS=500 |
| D6 | 进度条 | ✅ 添加progress_pct/progress_msg字段 |
| D14 | 低内存崩溃 | ✅ MiniBatchKMeans、PCA降维、内存检查 |
| D16 | 空闲高IO | ✅ 日志级别已为INFO，无需修改 |
| E8 | Globe响应式缩放 | ✅ 动态H计算、vh单位、resize处理 |
| E9 | Globe ?data=参数 | ✅ 支持从SessionStore直接加载数据集 |
| F12 | LLM日志 | ✅ 添加callback机制、run_log字段 |
| G13 | 聚类图表 | ✅ 添加簇大小柱状图、Silhouette对比图 |
| H17 | 聚类质量 | ✅ 方差过滤、相关过滤、HDBSCAN自动调参 |