PM-pinou
20 KiB
20 KiB
天璇 (TianXuan) — Agent Knowledge Base
Project Identity
| Field | Value |
|---|---|
| 项目名称 | 天璇 (TianXuan) |
| 原始名称 | tls-analyzer |
| 核心功能 | TLS 流数据分析、实体画像、聚类 3D 地球可视化、UMAP/SVD 降维散点图 |
| Python 版本 | 3.12 (embedded portable at runtime/python/python.exe) |
| Polars 版本 | 1.42.1 (精确锁定) |
| 数据框架 | Polars (LazyFrame + streaming) |
| 机器学习 | scikit-learn (HDBSCAN, KMeans, MiniBatchKMeans, IsolationForest), UMAP, TruncatedSVD, StandardScaler |
| Web 框架 | Django 4.2 + SQLite WAL |
| 前端 3D | Three.js (603KB, 离线, 地球贴图 1.4MB) |
| 前端图表 | 纯 Canvas 2D 散点图 / Canvas 地理分布 |
| LLM 协议 | MCP (stdio transport) + OpenAI 兼容 API |
| 启动方式 | run.bat (双击即用, 非阻塞, 打印 PID 后退出) / runtime\python\python.exe manage.py runserver (开发) |
| 目标设备 | Windows 10 1909+, 8GB RAM, 无独立显卡 (核显), 支持 2500 CSV × 10000 行 × 50~58 列 |
Project Structure
天璇/
├── tianxuan/ Django 项目配置
│ ├── settings.py ALLOWED_HOSTS 自动检测, LOGGING 文件+stderr
│ ├── wsgi.py SQLite 启动自修复
│ ├── urls.py 路由汇总
│ └── llm_orchestrator.py LLM 编排 (策略式提示词, 自动错误恢复)
├── analysis/ 核心分析模块 (Django app)
│ ├── views/ 视图包 (12 模块, 原 views.py 拆分)
│ │ ├── __init__.py 重导出所有视图函数
│ │ ├── helpers.py 辅助函数
│ │ ├── dashboard.py 首页 + 运行记录
│ │ ├── pipeline.py 管道执行器
│ │ ├── clustering.py 聚类概览/详情/地球数据
│ │ ├── entity.py 实体画像页
│ │ ├── upload.py CSV 上传
│ │ ├── manual.py 手动分析工作流构建器
│ │ ├── auto.py LLM 自动分析
│ │ ├── globe.py 3D 地球数据接口
│ │ ├── config.py 配置编辑 + LLM 测试
│ │ ├── log_viewer.py 日志查看器
│ │ └── tools.py 工具实验室
│ ├── tools/ 工具包 (17 模块, 30 个 MCP 工具实现)
│ │ ├── __init__.py 重导出所有 handler
│ │ ├── _registry.py 工具元数据 (Tool descriptor + get_tools_meta)
│ │ ├── _dispatch.py 工具调用分发 (handle_call)
│ │ ├── _helpers.py 共享辅助 (过滤表达式构建/响应截断/数据集决议/数值列检测)
│ │ ├── load_data.py 工具 1: load_data
│ │ ├── profile.py 工具 2: profile_data
│ │ ├── filter.py 工具 3: filter_data
│ │ ├── preprocess.py 工具 4: preprocess_data
│ │ ├── clustering.py 工具 5+8: run_clustering, filter_and_cluster
│ │ ├── evaluate.py 工具 6: evaluate_clustering
│ │ ├── features.py 工具 7: extract_features (+ UMAP 嵌入)
│ │ ├── entities.py 工具 9+10: build_entity_profiles, compute_scores
│ │ ├── anomalies.py 工具 11+12: detect_anomalies, visualize_anomalies
│ │ ├── export.py 工具 13: export_results
│ │ ├── analysis.py 工具 14-19: analyze_patterns/temporal/fft/tls_health/geo_distribution/entity_detail
│ │ ├── diagnostics.py 工具 20-26: validate_data/explore_distributions/find_outliers/diagnose_clustering/compare_datasets/export_debug_sample/repair_schema
│ │ ├── data_mgmt.py 工具 27-29: list_datasets/drop_dataset/clone_dataset
│ │ └── distance_matrix.py 工具 30: compute_distance_matrix
│ ├── tool_registry.py 旧编排层 (薄包装, 重导出 tools/)
│ ├── mcp_server.py MCP stdio server
│ ├── data_loader.py CSV 加载底层 (BOM/编码/schema 容错/递归 glob/ZIP 解压)
│ ├── data_profiler.py 列统计 + 相关性矩阵
│ ├── data_validator.py 列校验 (缺失/异常值/IP 有效性)
│ ├── type_classifier.py 值优先类型检测 (MAC/端口/IPv4/URL/HEX/ENUM/LAT_LON/BOOL_ENUM/TIMESTAMP)
│ ├── 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 WAL 工具 + 锁重试
│ ├── constants.py 全局常量
│ ├── appdata.py 应用数据路径 (%APPDATA%/TianXuan)
│ └── management/commands/
│ ├── start_mcp.py MCP 服务器启动命令
│ ├── run_pipeline.py 一键 CLI 管道命令
│ └── import_tlsdb.py TLS 数据库导入
├── 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 聚类概览 — Canvas 散点图 (PC1/PC2) + 地理分布 + Silhouette
│ │ ├── cluster_detail.html 簇详情 — 特征实体列表
│ │ └── entity_profile.html 实体画像 — 特征偏离 + Canvas 单点
│ └── tianxuan/ 功能页面 (6 个)
│ ├── upload.html CSV 上传 — 拖拽+多文件删除+进度
│ ├── manual.html 手动分析 — 工作流构建器 (添加/排序/保存/执行)
│ ├── auto.html LLM 自动分析 — 实时日志, thinking panel, 工具调用折叠
│ ├── globe.html 3D 地球 — Three.js 流量弧线 + 经纬线 + 国境线
│ ├── config.html 配置编辑 — LLM 连通性测试
│ └── 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 复杂数据生成 (5000 行 含 55% 缺失)
│ ├── column_survey.py CSV 列结构调查
│ ├── diagnose_compare.py 跨机日志对比诊断
│ └── debug_db.py DB 持久化调试
├── tests/ 测试
│ ├── test_e2e_full.py 全端到端测试
│ ├── test_e2e_batch.py 批量端到端测试
│ ├── start_srv.py 测试服务器启动辅助
│ └── _test_hdbscan.py HDBSCAN 零样本降级测试
├── data/ 数据目录
│ └── geoip_data.txt GeoIP 离线数据库
├── logs/ 日志输出
│ └── tianxuan.log 主日志文件
├── docs/
│ ├── 工作流.md 完整分析流水线文档
│ └── 故障诊断手册.md 跨机问题诊断指南
├── run.bat 用户启动入口 (含 PYTHONUTF8=1)
├── shell.bat Django shell
├── update.bat 增量更新
├── rollback.bat 更新回滚
├── build.bat 构建打包
├── TlsDB.csv 参考表头名清单
├── README.md
├── AGENTS.md
└── manage.py
30 MCP Tools
系统现有 30 个 MCP 工具, 分四层, 实现于 analysis/tools/ 包的 14 个 handler 模块:
⚡ 核心工具 (14 个) — 执行分析, 可修改数据
| # | 工具 | 实现模块 | 功能 | 必需参数 |
|---|---|---|---|---|
| 1 | load_data |
tools/load_data.py | 加载 CSV 文件 (glob/递归/ZIP 解压/schema 容错) | csv_glob |
| 2 | profile_data |
tools/profile.py | 数据集概要统计 + 相关性矩阵 | dataset_id |
| 3 | filter_data |
tools/filter.py | 按条件过滤 (12 操作符 + AND/OR 逻辑) | dataset_id, filters |
| 4 | preprocess_data |
tools/preprocess.py | 预处理 (StandardScaler/OneHot/填充/列删除) | dataset_id, columns |
| 5 | run_clustering |
tools/clustering.py | 执行聚类 (HDBSCAN/KMeans + 自动特征过滤 + 质量评估) | dataset_id, cluster_columns |
| 6 | evaluate_clustering |
tools/evaluate.py | 评估聚类质量 (Silhouette/DB/CH/噪声比/簇大小) | cluster_result_id, dataset_id |
| 7 | extract_features |
tools/features.py | 提取各聚类区分特征 (Z-Score/ANOVA) + UMAP-2D 嵌入 | dataset_id, cluster_result_id |
| 8 | filter_and_cluster |
tools/clustering.py | 一步完成: 过滤 + 自动选数值列 + 聚类 | dataset_id, filters |
| 9 | build_entity_profiles |
tools/entities.py | 自动检测实体列 + 聚合特征 (多列复合键支持) | dataset_id |
| 10 | compute_scores |
tools/entities.py | 自适应代理/异常/威胁评分 (SVD 权重 + IQR 阈值) | dataset_id |
| 11 | detect_anomalies |
tools/anomalies.py | Isolation Forest 异常检测 (分块处理大数据集) | dataset_id |
| 12 | visualize_anomalies |
tools/anomalies.py | UMAP-2D 嵌入 + 聚类可视化 (按风险等级/聚类着色) | dataset_id |
| 13 | export_results |
tools/export.py | 导出结果到磁盘 (CSV/Parquet/JSON) | result_id, output_path |
| - | export_entities_json |
tools/export.py | 导出实体画像为 JSON (附加工具) | dataset_id, output_path |
🔍 分析工具 (6 个) — 只读深潜, 安全随时调用
| # | 工具 | 实现模块 | 功能 |
|---|---|---|---|
| 14 | analyze_patterns |
tools/analysis.py | 流量模式: top 源/目标 IP、端口/TLS 版本/协议分布 |
| 15 | analyze_temporal |
tools/analysis.py | 时间维度流量分析: 小时/日流量计数、繁忙/空闲时段 |
| 16 | analyze_fft |
tools/analysis.py | FFT 频谱分析: 周期模式、频率特征、周期性评分 |
| 17 | analyze_tls_health |
tools/analysis.py | TLS 安全态势: 旧版比例、弱加密、证书问题、SNI 异常 |
| 18 | analyze_geo_distribution |
tools/analysis.py | 地理分布: top 来源国家、不可能旅行、ISP 多样性 |
| 19 | analyze_entity_detail |
tools/analysis.py | 单实体深度调查: 流/版本/目标/时间模式/异常评分 |
🩺 诊断工具 (7 个) — 排查问题
| # | 工具 | 实现模块 | 功能 |
|---|---|---|---|
| 20 | validate_data |
tools/diagnostics.py | 数据质量: schema 一致性、缺失率、列类型冲突 |
| 21 | explore_distributions |
tools/diagnostics.py | 列分布统计: 唯一值、空值率、min/max/mean/std、直方图 |
| 22 | find_outliers |
tools/diagnostics.py | IQR 方法检测数值列统计异常值 |
| 23 | diagnose_clustering |
tools/diagnostics.py | 聚类效果差时诊断: 方差/相关分析 + 参数建议 |
| 24 | compare_datasets |
tools/diagnostics.py | 对比两数据集: schema 差异、行数变化、值分布偏移 |
| 25 | export_debug_sample |
tools/diagnostics.py | 导出原始数据样本 JSON 供外部调试 |
| 26 | repair_schema |
tools/diagnostics.py | 修复 schema 不匹配: 列名对齐、大小写合并、填充缺失 |
📦 数据管理 (3 个)
| # | 工具 | 实现模块 | 功能 |
|---|---|---|---|
| 27 | list_datasets |
tools/data_mgmt.py | 列出所有活跃数据集和结果 |
| 28 | drop_dataset |
tools/data_mgmt.py | 删除数据集释放内存 (支持 dataset/cluster/feature 三种类型) |
| 29 | clone_dataset |
tools/data_mgmt.py | 浅拷贝数据集 (LazyFrame 查询计划, 不复制数据) |
🧠 LLM 驱动 (1 个)
| # | 工具 | 实现模块 | 功能 |
|---|---|---|---|
| 30 | compute_distance_matrix |
tools/distance_matrix.py | LLM 编写 Python 距离函数, 逐行执行并返回评分摘要 |
工具注册流程: tools/_registry.py (Tool 元数据) → tools/_dispatch.py (分发到对应 handler) → analysis/mcp_server.py (暴露 MCP stdio 接口)
手动分析工作流
手动分析页面 (manual.html) 为工作流构建器:
- 添加/移除/重排步骤
- 每步选择工具 + 填写参数
- 保存/加载/删除方案 (存储于
.omo/plans/<name>.json) - 单步执行 / 全部执行 (自动串行)
- 执行结果显示在每一步下面
标准分析流程
load_data → filter_data → profile_data → build_entity_profiles → compute_scores → run_clustering → extract_features
LLM 自动模式由 tianxuan/llm_orchestrator.py 驱动, 策略式提示词: 先 profile 了解数据 → 根据数据决策 → 失败自动诊断 → 重复调用检测 + 自动错误恢复。
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"]
IP 子网聚合逻辑位于 analysis/ip_clustering.py, tools/entities.py::_handle_build_entity_profiles 在 group_by 前对 IP 列自动应用子网掩码。
Architecture
- 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 个基础设施: _registry/_dispatch/_helpers) - tuple 替代 frozenset: 避免跨机 PYTHONHASHSEED 差异
- PYTHONUTF8=1: 跨机编码一致性 (run.bat 内置)
- 类型安全聚合: 聚合前检查 dtype, 非数值列 cast
- sync_to_async ORM: 异步上下文中 Django ORM 安全调用
- 纯 Canvas 图表: 零外部 JS 依赖 (散点图/地理分布/Silhouette 柱状图)
- 上传目录隔离:
%APPDATA%/TianXuan/data/uploads/, 与项目路径无关 - 通用数值清理 _coerce_to_float: 处理
+/-/ 空白 / N/A 等伪值 - 值优先类型检测: config → 值 → 名称 → STRING (type_classifier.py)
- 地球深度测试: depthTest: true, depthWrite: false, r=5.5
- 完整国境线: Natural Earth 110m, 177 国 286 多边形 269KB
- UMAP 降维: extract_features 中为实体数据计算 UMAP-2D 嵌入, 存储到 EntityProfile 表 (embedding_x/embedding_y), 训练 10K 样本 + 批量变换 1K 批次
- TruncatedSVD: 聚类时特征 > 50 维自动降维; compute_scores 中学习自适应评分权重
- LLM 驱动距离计算: compute_distance_matrix 工具允许 LLM 编写 Python 函数在受限命名空间 (math, numpy) 中逐行执行
- 距离计算多策略: tools/distance_matrix.py 中的 compute_distance_matrix 和 analysis/distance.py 中的 IP 子网/地理/Levenshtein/Hamming/FFT 相位距离
Testing Protocol
运行测试
# 端到端测试 (自动启动后端、模拟前端行为、监控 stderr)
runtime\python\python.exe tests\test_e2e_full.py
runtime\python\python.exe tests\test_e2e_batch.py
# HDBSCAN 零样本降级测试
runtime\python\python.exe tests\_test_hdbscan.py
跨机一致性测试
# 两台机器各自执行
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
# 验证: AnalysisRun, ClusterFeature 表有数据
LLM 编排测试
runtime\python\python.exe scripts\test_llm_full.py
生成测试数据
# 简单数据
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 行 4 列含 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: 每步告诉模型下一步做什么, 减少 32B 模型推理发散
- Truncation: 工具结果截断 1200 chars (避免上下文窗口溢出)
- Timeout: 90s (32B 推理更慢)
- Max steps: 15
- Tool description: 一行简洁描述 (中文)
- 策略式提示词: 先 profile → 根据数据决策 → 失败自动诊断 → 重复调用检测 + 自动错误恢复
- 工具结果自动截断:
_truncate_response()确保单次返回不超过 64 KB, 长列表/矩阵自动压缩
Operating Procedures
-
非阻塞启动后端 —
run.bat使用start /B启动 Django, 打印 PID 后退出, 不阻塞终端。日志写入logs/tianxuan.log。 -
全量测试 — 所有改动完成后, 运行完整 E2E 测试: 生成测试 CSV, 上传前端, 验证全流水线。
-
更新文档和 Git — 测试通过后: 更新 AGENTS.md, 提交所有更改, 清理临时文件和残留进程。不留脏状态 (孤儿进程、临时文件、未提交更改)。
-
同步依赖 — 使用
git pull同步最新代码, 然后runtime\python\python.exe -m pip install -r requirements.txt安装新依赖。每次新工作会话前执行。 -
编码前缀 — 所有终端命令加
chcp 65001避免 Opencode 编码错误。PowerShell/CMD 编码问题是命令失败的首要原因。 -
Python UTF-8 — 运行 Python 时始终加
set PYTHONUTF8=1。确保跨机 Unicode 处理一致, 防止编码漂移。
近期变更 (beta-clean 分支)
- views.py (2000+ 行单体) →
analysis/views/包 (13 模块) - tool_registry.py (3000+ 行) →
analysis/tools/包 (18 模块) - 默认聚类算法改为 AgglomerativeClustering
- 移除实体概念，直接对原始行聚类 (entity_value = row_N)
- cluster_detail 显示原始数据行而非实体画像
- run_detail 新增全域 SVD 特征分析 + LLM 工作流时间线
- 3D 地球侧栏复用
/globe/?embed=1（iframe + postMessage 联动） - UI 全面中文化
- 非阻塞启动 (run.bat 打印 PID 后退出)
待办
- 前端 UI 验证: 打开
prototype_cluster_ui.html查看交互设计是否符合要求 - 更新前端原型后，将验证通过的交互逻辑合并到正式模板