天璇 (TianXuan) — TLS 流数据分析平台

基于 Polars + scikit-learn + Three.js 的 TLS 流量分析工具。CSV 上传后支持手动分步分析（工作流构建器）、LLM 全自动分析（MCP 工具链）、聚类 3D 地球可视化。全离线运行，内嵌 Python 3.12 运行时。

功能概述

模块	说明
CSV 上传	多文件拖拽、BOM 自动检测、schema 容错、ZIP 自动解压
手动分析	工作流构建器：添加/排序/保存工具链，串行执行
LLM 自动分析	OpenAI 兼容 API，自动编排 filter→profile→entity→cluster→feature
聚类可视化	HDBSCAN/KMeans，Silhouette/DB 评估，Canvas 散点图 + 地理分布
3D 地球	Three.js 流量弧线，TLS 版本着色，经纬线+国境线
降维	UMAP + TruncatedSVD 用于高维数据降维与可视化
实体画像	聚合特征 + Z-Score 簇偏离量，自定义实体列/IP 子网掩码
MCP 协议	30 个 JSON-RPC 工具供外部 LLM 编排调用
增量更新	update.bat + rollback.bat，用户数据/代码分离

技术栈

组件	选型
后端	Django 4.2 + SQLite WAL
数据处理	Polars 1.42 (LazyFrame + streaming)
机器学习	scikit-learn (HDBSCAN, KMeans, MiniBatchKMeans, IsolationForest), UMAP, TruncatedSVD, StandardScaler
前端 3D	Three.js (603KB, 离线, 地球贴图 1.4MB)
前端图表	纯 Canvas 2D (散点图/地理分布/Silhouette)
配置管理	Pydantic + YAML
LLM 协议	MCP SDK (stdio) + OpenAI 兼容 API
运行时	内嵌 Python 3.12 (~593MB)

安装

项目自包含，无需预装 Python。解压后即可使用。

:: 首次部署 — 初始化数据库
runtime\python\python.exe manage.py migrate

使用方法

:: 双击启动 Web 界面 (http://127.0.0.1:8000/)
run.bat          :: 非阻塞启动，打印 PID 后退出，日志写入 logs/tianxuan.log

:: 命令行一键管道
runtime\python\python.exe manage.py run_pipeline "data/*.csv"

:: 开发模式启动
set PYTHONUTF8=1
runtime\python\python.exe manage.py runserver

Web 工作流: 上传 CSV → 手动分析（工作流构建器）或 LLM 自动分析 → 检视聚类概览/簇详情/实体画像/3D 地球

CLI 管道: 加载 CSV → 类型检测 → 实体聚合 → 聚类 → 特征提取 → 写入数据库

项目结构

天璇/
├── analysis/                    核心分析模块 (Django app)
│   ├── views/                   视图包 (12 模块)
│   │   ├── __init__.py          重导出所有视图函数
│   │   ├── helpers.py           辅助函数 (_extract_lat, _extract_lon)
│   │   ├── dashboard.py         首页 + 运行记录
│   │   ├── pipeline.py          管道执行器 (_run_pipeline_worker)
│   │   ├── clustering.py        聚类概览/详情/3D 地球数据
│   │   ├── entity.py            实体画像页
│   │   ├── upload.py            CSV 上传 (拖拽/多文件/进度)
│   │   ├── manual.py            手动分析工作流构建器
│   │   ├── auto.py              LLM 自动分析 (SSE 流式)
│   │   ├── globe.py             3D 地球数据接口
│   │   ├── config.py            配置编辑 + LLM 连通性测试
│   │   ├── log_viewer.py        日志查看器
│   │   └── tools.py             工具实验室
│   ├── tools/                   工具包 (17 模块, 30 个 MCP 工具实现)
│   │   ├── __init__.py          重导出所有 handler
│   │   ├── _registry.py         工具元数据定义 (Tool schema)
│   │   ├── _dispatch.py         工具调用分发器
│   │   ├── _helpers.py          共享辅助 (过滤/截断/数据集决议)
│   │   ├── load_data.py         CSV 加载 (glob/递归/ZIP/schema 容错)
│   │   ├── profile.py           数据概要统计 + 相关性矩阵
│   │   ├── filter.py            数据过滤 (12 操作符 + AND/OR)
│   │   ├── preprocess.py        预处理 (StandardScaler/OneHot/填充)
│   │   ├── clustering.py        聚类执行 (HDBSCAN/KMeans + 自动降维)
│   │   ├── evaluate.py          聚类质量评估 (Silhouette/DB/CH)
│   │   ├── features.py          特征提取 (Z-Score/ANOVA/UMAP)
│   │   ├── entities.py          实体画像 + 自适应评分 (SVD 权重)
│   │   ├── anomalies.py         异常检测 (IsolationForest) + UMAP 可视化
│   │   ├── export.py            结果导出 (CSV/Parquet/JSON)
│   │   ├── analysis.py          只读分析 (6 工具: 模式/时序/FFT/TLS/地理/实体)
│   │   ├── diagnostics.py       诊断 (7 工具: 校验/分布/异常值/聚类诊断/对比/导出/修复)
│   │   ├── data_mgmt.py         数据管理 (列表/删除/克隆)
│   │   └── distance_matrix.py   LLM 驱动距离计算
│   ├── tool_registry.py         旧编排层 (薄包装，重导出 tools/)
│   ├── mcp_server.py            MCP stdio 服务器
│   ├── data_loader.py           CSV 加载底层实现
│   ├── data_profiler.py         列统计 + 相关性矩阵
│   ├── data_validator.py        列校验 (缺失/异常值/IP 有效性)
│   ├── type_classifier.py       值优先类型检测 (MAC/端口/IPv4/URL/HEX/经纬度)
│   ├── geoip.py                 GeoIP 经纬度查询
│   ├── ip_clustering.py         IP 子网聚类与转换
│   ├── session_store.py         线程安全内存会话存储
│   ├── distance.py              距离计算 (IP 子网/地理/Levenshtein/Hamming/FFT)
│   ├── models.py                ORM: AnalysisRun, ClusterResult, EntityProfile, ClusterFeature
│   ├── urls.py                  路由注册
│   ├── nl_describe.py           自然语言数据描述
│   ├── profile_util.py          画像工具函数
│   ├── tls_ref.py               TLS 参考数据
│   ├── db_utils.py              SQLite 工具
│   ├── constants.py             全局常量
│   ├── appdata.py               应用数据路径管理
│   └── management/commands/     CLI 命令
│       ├── start_mcp.py         MCP 服务器启动
│       ├── run_pipeline.py      一键 CLI 管道
│       └── import_tlsdb.py      TLS 数据库导入
├── tianxuan/                    Django 项目配置
│   ├── settings.py              ALLOWED_HOSTS 自动检测, LOGGING 文件+stderr
│   ├── wsgi.py                  SQLite 启动自修复
│   ├── urls.py                  路由汇总
│   └── llm_orchestrator.py     LLM 编排 (策略式提示词, 自动错误恢复)
├── config/                      配置管理
│   ├── config.yaml              自动生成默认配置 (entity, server, data, clustering, llm)
│   ├── loader.py                Pydantic 配置加载 + 文件修改检测
│   └── __init__.py
├── templates/                   页面模板 (13 个 HTML)
│   ├── base.html                导航: 首页/上传/手动/LLM/记录/地球/配置
│   ├── analysis/                分析页面 (6 个)
│   │   ├── dashboard.html       首页
│   │   ├── run_list.html        运行记录列表
│   │   ├── run_detail.html      运行详情
│   │   ├── cluster_overview.html 聚类概览
│   │   ├── cluster_detail.html  簇详情
│   │   └── entity_profile.html  实体画像
│   └── tianxuan/                功能页面 (6 个)
│       ├── upload.html          CSV 上传
│       ├── manual.html          手动分析
│       ├── auto.html            LLM 自动分析
│       ├── globe.html           3D 地球
│       ├── config.html          配置编辑
│       └── log_viewer.html      日志查看
├── static/tianxuan/             离线静态资源
│   ├── three.min.js             Three.js 3D 引擎 (603KB)
│   ├── earth_atmos_2048.jpg     地球贴图 (1.4MB)
│   └── world_borders.js         177 国完整国境线 (269KB)
├── runtime/python/              便携 Python 3.12 运行时 (~593MB)
├── scripts/                     工具脚本
│   ├── gen_test_data.py         测试数据生成
│   ├── gen_complex_test.py      复杂数据生成
│   ├── column_survey.py         CSV 列结构调查
│   ├── diagnose_compare.py      跨机日志对比诊断
│   └── debug_db.py              DB 持久化调试
├── tests/                       端到端测试
│   ├── test_e2e_full.py
│   ├── test_e2e_batch.py
│   └── _test_hdbscan.py
├── docs/                        文档
│   ├── 工作流.md                 完整分析流水线
│   └── 故障诊断手册.md            问题排查指南
├── run.bat                      用户启动入口 (含 PYTHONUTF8=1)
├── shell.bat                    Django shell
├── update.bat                   增量更新
├── rollback.bat                 更新回滚
├── build.bat                    构建打包
└── manage.py                    Django 管理入口

架构要点

• views 包: 原单体 views.py (2000+ 行) 拆分为 12 个模块，按功能域分离 (dashboard, pipeline, clustering, entity, upload, manual, auto, globe, config, log_viewer, tools, helpers)
• tools 包: 原 tool_registry.py 拆分为 17 个模块 (14 个 handler 模块 + 3 个基础设施模块)，每个工具领域独立文件
• 30 个 MCP 工具 分四层: 核心 (14 个)、只读分析 (6 个)、诊断 (7 个)、数据管理 (3 个)
• 纯 Canvas 2D 图表: 零外部 JS 依赖，散点图/地理分布/Silhouette 均纯 Canvas 绘制
• tuple 替代 frozenset: 避免跨机 PYTHONHASHSEED 差异
• 值优先类型检测: config → 值采样 → 名称推断 → STRING 回退 (type_classifier.py)
• TruncatedSVD 降维: 特征 >50 维时自动降维至 50；compute_scores 中学习自适应评分权重
• UMAP 2D 嵌入: 训练 10K 样本 + 批量变换 1K 批次，存入 EntityProfile 表
• 上传目录隔离: %APPDATA%/TianXuan/data/uploads/，与项目路径无关

目标设备

条件	规格
操作系统	Windows 10 1909+
内存	8 GB
GPU	无独立显卡（核显可运行 Three.js）
磁盘	SSD 推荐（SQLite WAL 优化）
数据规模	支持 2500 个 CSV × 10000 行 × 50~58 列