From 829729943c43b746f964b7c392cfe47d6fdbcecf Mon Sep 17 00:00:00 2001 From: TianXuan Developer Date: Fri, 24 Jul 2026 13:06:14 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E7=A4=BE=E5=8C=BA=E4=BA=A4=E4=BA=92?= =?UTF-8?q?=E5=A2=9E=E5=BC=BA=20+=20=E5=8D=AB=E6=98=9F=E5=9C=B0=E5=9B=BE?= =?UTF-8?q?=20+=20=E8=8A=82=E7=82=B9/=E8=BE=B9=E6=95=B0=E6=8D=AE=E4=B8=B0?= =?UTF-8?q?=E5=AF=8C=20+=20=E9=A1=B9=E7=9B=AE=E6=B8=85=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 核心改进: - 节点数据丰富: TLS版本/加密套件/SNI/端口/流量统计/连接成功率 - 边数据丰富: 包数/持续时间/TLS/端口/SNI/分类标签 - 新增 edge_time_series 端点: 边流量时序图(北京时间) - 新增 cluster_nodes_edges 端点: 社区聚焦(zoom+高亮+专属边) - 社区点击: 自动缩放/高亮节点/显示社区边(可点击) - 边交互修复: 事件从layerGroup移至hitPoly,三处边渲染全修复 - 地图升级: ESRI卫星影像 + 255国矢量边界叠加 - 离线回退: 卫星→CartoDB→暗色矢量地图,完整可用 - 节点面板: 删除无意义社区标签,移至Host+组织同行 - sanitizeName: 清理5个非ASCII国家名避免乱码 - .gitignore: 补充geoip_chunks/和嵌套CSV规则 项目清理: - 删除 logs/ (20个调试文件,~2.5MB) - 删除 test_*.py (4个临时测试脚本) - 删除 _check_bool/_pipeline_test/_restart_server/start_server (硬编码路径) - 删除 node_modules/package.json/package-lock.json (18MB,不用Node) - 删除 tests/ 旧日志和调试脚本 - 删除 .pytest_cache/ .server_pid.txt RUNTIME_CHANGED.txt - AGENTS.md → CLAUDE.md Co-Authored-By: Claude --- .gitignore | 3 +- .server_pid.txt | 1 - AGENTS.md | 467 ------------ CLAUDE.md | 100 +++ _check_bool.py | 9 - _master_req.txt | Bin 2682 -> 0 bytes _pipeline_test.py | 73 -- _restart_server.py | 32 - .../simple_analysis/simple_analysis.html | 664 ++++++++++++++++-- simple_analysis/urls.py | 2 + simple_analysis/views.py | 561 +++++++++++++-- start_server.py | 16 - .../simple_analysis/maps/countries-10m.json | 1 + .../simple_analysis/maps/countries-110m.json | 1 + .../simple_analysis/maps/countries-50m.json | 1 + static/simple_analysis/maps/land-10m.json | 2 +- tests/_test_hdbscan.py | 77 -- tests/debug_playwright.mjs | 55 -- tests/debug_value_dropdown.mjs | 86 --- tests/quick_test.cjs | 166 ----- tests/start_srv.py | 9 - 21 files changed, 1219 insertions(+), 1107 deletions(-) delete mode 100644 .server_pid.txt delete mode 100644 AGENTS.md create mode 100644 CLAUDE.md delete mode 100644 _check_bool.py delete mode 100644 _master_req.txt delete mode 100644 _pipeline_test.py delete mode 100644 _restart_server.py delete mode 100644 start_server.py create mode 100644 static/simple_analysis/maps/countries-10m.json create mode 100644 static/simple_analysis/maps/countries-110m.json create mode 100644 static/simple_analysis/maps/countries-50m.json delete mode 100644 tests/_test_hdbscan.py delete mode 100644 tests/debug_playwright.mjs delete mode 100644 tests/debug_value_dropdown.mjs delete mode 100644 tests/quick_test.cjs delete mode 100644 tests/start_srv.py diff --git a/.gitignore b/.gitignore index 83e72d3..9750fcd 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ runtime/ # GeoIP MMDB (generated from geoip_chunks/) *.mmdb *.mmdb.gz +data/geoip_chunks/ # Logs logs/ @@ -42,7 +43,7 @@ Thumbs.db RUNTIME_CHANGED.txt # Test data (auto-generated CSV files) -data/*.csv +data/**/*.csv data/multi_upload/ node_modules/ package-lock.json diff --git a/.server_pid.txt b/.server_pid.txt deleted file mode 100644 index 05cf444..0000000 --- a/.server_pid.txt +++ /dev/null @@ -1 +0,0 @@ -16884 diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 309b33d..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,467 +0,0 @@ -# 天璇 (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, UMAP, TruncatedSVD, 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`（开发） | -| 目标设备 | Windows 10 1902, 4GB RAM, 无独立显卡（纯核显） | - -## 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行4列含55%缺失) -│ ├── column_survey.py # CSV列结构调查(统计各CSV的列类型/分布) -│ ├── diagnose_compare.py # 跨机日志对比诊断 -│ └── debug_db.py # DB持久化调试 ├── tests/ # 92个测试(unit) / 121个测试(all) -│ ├── 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 -├── TlsDB.csv # 参考表头名清单（非实际数据├── 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 模型 - -```python -class Entity(BaseModel): - subnet_masks: list[int] = [] # 子网掩码列表，如 [24, 28] - ip_columns: list[str] = ['src_ip', 'dst_ip'] # 需聚合的IP列``` - -config.yaml 默认配置: -```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 - -### 运行全部测试 - -```bash -# 单元测试（不需要Django)runtime\python\python.exe -m pytest tests/test_data_loader.py tests/test_type_classifier.py -q - -# 集成测试（自动启动后端、模拟前端行为、监控stderr报错)runtime\python\python.exe tests/test_integration.py -``` - -``` -92 passed (unit tests); ALL INTEGRATION TESTS PASSED -``` - -> ⚠️ **重要**: `tests/test_integration.py` 模拟前端HTML行为（上传CSV 轮询状态访问页面 删除）> **当前端HTML/API发生变化时，必须同步更新此脚*，否则集成测试将不再反映真实用户流程 -> -### 跨机一致性测```bash - -# 两台机器各自执行 - -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持久化测```bash -runtime\python\python.exe scripts\debug_db.py -# 期望: n_features=30 db_saved=True -# 验证: run_analysis ClusterFeature 表有数据 -``` - -### LLM编排测试 - -```bash -runtime\python\python.exe scripts\test_llm_full.py -# 或 runtime\python\python.exe -c "from tianxuan.llm_orchestrator import run_llm_pipeline, LLMConfig; ..." -``` - -### 生成测试数据 - -```bash -# 简单数据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 -``` - -### 列结构调查```bash - -runtime\python\python.exe scripts\column_survey.py --csv "data/*.csv" - -``` - ---- - -## Polars Version Compatibility - -| API | 旧版(<1.0) | 新版(.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: 一行简洁描述 ---- - -## v1.1.3 修复 (2026-07-21) - -13 issues fixed across build system, frontend, pipeline, and data handling. - -| # | 问题 | 状态| 详情 | -|---|------|------|------| -| 1 | 增量包构建修复| | update_info.json含SHA256、文件在files/子目录下、测试数据排除、__delete__支持 | -| 2 | 构建顺序+三段版本号| | 先commit后bump再tag、bump_version支持vX.Y.Z、update.bat加PYTHONUTF8 | -| 3 | 前端导航跳转 | | 上传后→手动分析页、LLM完成后→聚类概览| -| 4 | 聚类前手动筛选| | manual.html下filter_data工具UI | -| 5 | 地球→态势+拖拽修复 | | 导航改名、拖拽方向修正、惯性仅松开时施加| -| 6 | DB模型同步 | | 所有模型与SQLite表完全匹配| -| 7 | LLM后强制聚类| | LLM完成后自动运行clustering+PCA pipeline | -| 8 | 列名不一致处理| | 保留所有列(union)、不丢弃额外列、gen_test_data支持--missing-cols | -| 9 | FFT频谱分析 | | 新MCP工具analyze_fft(numpy.fft)、周期性特征提取| -| 10 | 异常处理修复 | | 24处裸except/except:pass全部修复为带日志处理 | -| 11 | LLM上下文增加| | 发送列类型+中文含义+空值率+众数给LLM | -| 12 | 工作流自动保存| | 最0条自动方案保存到手动分析页、支持固定防淘汰 | -| 13 | 列类型遵循TlsDB | | tls_ref_data作为权威类型源、未知列严格回退 | - -## 修复计划 (2026-07-16) - -| # | 问题 | 状态| 详情 | -|---|------|------|------| -| 1 | 重启后旧数据可分析| | SessionStore 元数据持久化为JSON 文件(`%APPDATA%/TianXuan/.session_store.json`)，wsgi.py 启动时自动恢复| -| 2 | Web图标所有页| | `` 在 base.html 中，所有页面继承| -| 3 | 上传按钮在顶部| | `position: sticky` | -| 4 | Traceback完整 | | 移除 views.py 4处 + run_pipeline.py 1处`[:200]` 截断 | -| 5 | 大数据不卡顿 | | 降采样`head=` 参数支持，手动POST 可传 head，LLM 自动决定，clamp 500| -| 6 | 进度条| | progress_pct → 10/30/50/70/90/100 各阶段更新| -| 7 | TLS 0ver hex识别 | | TLS_HEX_MAP 移至 type_classifier.py 值优先检测链ver列自动ENUM("TLSv1.2") | -| 8 | Globe响应式缩放| | Canvas resize 事件绑定，vh 单位动态计算| -| 9 | Globe ?data= | | 异常安全：try/except 包裹，空数据仍渲染页面| -| 10 | 文件上传无限| | DATA_UPLOAD_MAX_NUMBER_FIELDS=1000000, FILE_UPLOAD_MAX_MEMORY_SIZE=100MB | -| 11 | 上传页删除功能| | removeFile() + 按钮每文件| -| 12 | LLM日志 | | progress_callback 写入 run_run_log | -| 13 | 聚类图表 | | cluster_overview.html 含散点图/柱状态Silhouette |特征纯Canvas) | -| 14 | 低内存不崩溃 | | MiniBatchKMeans + PCA降维 + 降采样head 参数 | -| 15 | +号字符串识别为数| | type_classifier.py FLOAT检测前排除 `+` 前缀 | -| 16 | 空闲高IO | | 日志级别 INFO，无需修改 | -| 17 | 聚类效果 | ⚠️ | 预置了特征过滤降维，但具体效果需业务验证 | -| 18 | 列名精确匹配 | | `re.match` 精确匹配 + `_find_column` tuple 关键词| - -## v7 Final Verification (2026-07-20) - -All **19 issues** fixed and verified. 92/92 unit tests passing. Full regression run completed. - -| # | 问题 | 状态| 详情 | -|---|------|------|------| -| 1 | `handle_call` imported in llm_orchestrator.py | | `from analysis.tool_registry import handle_call` at line 7 | -| 2 | Retry button + run_type filter | | Retry form in `run_list.html` (line 51), run_type dropdown filter, URL route `retry_run` added | -| 3 | auto.html logs show tool+result | | `liveLog` polling every 3s from `/logs/?pos=` endpoint | -| 4 | Data saved to SQLite tables | | `sqlite_table` field on `AnalysisRun` model, `drop_sqlite_table` in data_loader | -| 5 | Error toast in base.html | | Complete toast system with error/success types, auto-dismiss, slide animations | -| 6 | display_id in all URLs | | All 6 URL patterns (`run_detail`, `run_status`, `cluster_overview`, `cluster_detail`, `retry_run`, `delete_upload`) use `display_id` | -| 7 | Delete buttons on dashboard+run_list | | Both pages have styled delete buttons with confirmation dialog | -| 8 | Progress bar 100% on completion | | `progress_pct` field updated through pipeline stages (10/30/50/70/90/100) | -| 9 | LLM thinking panel in auto.html | | `thinkingPanel` div with `llm_thinking` text area and step indicator | -| 10 | Tool call accordion in auto.html | | `renderToolCalls()` with toggle-able accordion sections per tool step | -| 11 | LazyFrame.sample() fixed | | Uses `lf.sample(n=...)` with explicit row count parameter (not deprecated `.sample()` API) | -| 12 | `filter_and_cluster` tool exists | | Registered at line 407 in `tool_registry.py` as tool #13 | -| 13 | Tool descriptions in Chinese | | All tool descriptions and parameter docs use Chinese | -| 14 | Globe: lines, timestamp, inertia, polar flip | | Flow arcs (Line geometry), timestamp-based dot animation, quaternion momentum decay, camera-relative rotation (no polar flip) | -| 15 | Config button in nav | | `{% url 'analysis:config' %}` link 配置 in base.html nav bar | -| 16 | config host:port affects broadcast | | `settings.py` reads `_cfg.server.host` - auto-adds to `ALLOWED_HOSTS` | -| 17 | SQLite timeout+retry mechanism | | `retry_on_lock` decorator in `db_utils.py`: 3 retries, exponential backoff, logs `[DB_LOCKED]` warning | -| 18 | Delete crash fixed (null csv_glob) | | `delete_upload` view checks `if run.csv_glob:` before accessing path (line 366) | -| 19 | No file count limit, streaming upload | | `DATA_UPLOAD_MAX_NUMBER_FIELDS=10000000`, `FILE_UPLOAD_MAX_MEMORY_SIZE=100MB` | - -### Remaining issues -- `test_e2e.py`, `test_entity.py`, `test_pipeline.py` still reference removed `entity_detector` module - need updating for new clustering pipeline -- `test_clustering_edge.py` does not exist on disk (only referenced in AGENTS.md) -- `retry_run` URL route was missing from `urls.py` - fixed during final verification - -### Test Results (2026-07-20) -| Test suite | Tests | Result | -|------------|-------|--------| -| `test_data_loader.py` | 28 | All passed | -| `test_type_classifier.py` | 64 | All passed | -| **Total** | **92** | ** All passed** | - -## v8 Fix (2026-07-20) - -| # | 问题 | 状态| -|---|------|------| -| 1 | 服务器启动config模块找不到| 修复 | -| 2 | 首次启动无数据库| 修复 | -| 3 | CSV中+'无法解析为f64 | 修复 | -| 4 | 上传分块处理+释放临时文件 | 修复 | -| 5 | 集成测试脚本 | 添加 | -| 6 | TlsDB.csv文档说明 | 更新 | -| 7 | load_from_db类型冲突 | 修复 | -| 8 | CSV未合并处理| 修复 | - -### Final Verification (2026-07-20) -| Check | Result | -|-------|--------| -| `manage.py check` (system) | 0 errors | -| Unit tests (data_loader + type_classifier) | 92 passed | -| Integration test (full upload→load→analyze) | ALL INTEGRATION TESTS PASSED | -| Git commit `v8` | `555ec29` | - -## MCP 工具系统 (2026-07-19) - -系统现有 **27 |MCP 工具**，分为三层： - -### 工具架构 - -| | 数量 | 标签 | 用| -|---|------|------|------| -| Core | 7 | | 执行分析，可修改数据 | -| Analysis | 5 | 🔍 | 只读深潜，安全随时调用| -| Diagnostic | 7 | 🩺 | 排查问题 | -| 其他 | 8 | | 数据加载/过滤/导出| - -### 手动分析工作流 -手动分析页面已改为 **工作流构建器**: -- 添加/移除/重排步骤 -- 每步选择工具 + 填写参数 -- **保存/加载/删除**方案（存储`.omo/plans/.json`)- 单步执行 |**▶▶ 全部执行**（自动串行） -- 执行结果显示在每一步下面 -### LLM 自动编排 - -LLM orchestrator 重写，支持： -- 策略式系统提示词（先 profile 根据数据决策 失败自动诊断- 重复调用检测+ 自动错误恢复 -- 27 个工具全部可用- 中文总结分析结果 - -### 全链路测试 -| 测试 | 用例 | 结果 | -|------|------|------| -| 单元测试 | 120 | | -| 管道测试 | 8 (3 datasets × 2 algos + edge) | | -| CLI pipeline | e2e 5 stages | | -| MCP 工具集成 | 10 (profile/patterns/validate/tls/geo/build/scores/detect/detail/visualize) | | - -## v3 修复 (2026-07-17) - -| # | 问题 | 状态| 详情 | -|---|------|------|------| -| 1 | 经纬度列名匹配`:ips.latd`) | | views.py直接字符串匹配+ entity_aggregator.py _LAT_KEYWORDS增加.latd后缀 | -| 2 | cnrs/isrs布尔类型 | | entity_aggregator.py聚合前将"+"→True/空白→False | -| 3 | 聚类图表（legend/柱状态负值） | | 纯Canvas：legend用HTML div+overflow、柱状图动态带宽、负值标签重新定义| -| 4 | 地球缩放改变数据流大小| | Three.js arc sphere尺寸与camera距离反比，zoom时视觉大小不变| -| 5 | 恶意/代理流量分析 | | entity_aggregator.py规则引擎：non_std_port_rate + modern_tls_rate + sni_missing_ratio + multi_country + proxy_score | -| 6 | EntityProfile批量IO | | views.py + tool_registry.py 改为 bulk_create(ignore_conflicts=True, batch_size=1000) | -| 7 | 重试分析 | 🗑| 已移除(v7 新架构不再需要entity_column 概念) | -| 8 | D5降采样导致特征提取行数不匹配 | | _handle_run_clustering存储_ds_idx抽样索引，_handle_extract_features按索引过滤数据| - -## v4 修复 (2026-07-17) - -| # | 问题 | 状态| 详情 | -|---|------|------|------| -| 1 | 进度条位置| | DOM重排: submitBar → progressArea → fileList progressArea → fileList | -| 2 | PCA sklearn RuntimeWarning | | `warnings.filterwarnings('ignore', category=RuntimeWarning, module='sklearn')` | -| 3 | cluster_overview N+1查询 | | `prefetch_related('features')` + `.only()`字段限制 | -| 4 | SQLite PRAGMA未优| | WAL + synchronous=NORMAL + cache_size=20MB + temp_store=MEMORY + mmap_size=3GB | -| 5 | 零方差过滤崩| | 全零方差时回退`np.arange(data.shape[1])`保留原始特征 | - -### 大规模测试结(2026-07-17) - -| 测试 | 规模 | 结果 | -|------|------|------| -| 单元测试 | 120 tests | 全部通过 | -| 管道测试 | 3 datasets × 2 algorithms | 8 tests OK | -| 中等规模 | **100文件 × 10000行= 1M行 825MB** | 全部完成: 加载→实体检测→聚合→聚2285个实体→特征提取| - -## Cleanup (2026-07-16) - -对 v6 迭代引入的垃圾文件和代码破坏进行全面清理 -| 操作 | 文件 | -|------|------| -| 🗑删除 | 15个垃圾脚(wnl_to_user_csv, eval_clustering, debug_db2/3, debug_persistence, test_orch/orch2, test_pca, test_profile, test_tool_loop/format, test_e2e_full, test_32b, test_chinese_path, verify_runtime) | -| 🗑删除 | data/wnl_converted.csv, data/globe_test.csv | -| 🗑删除 | analysis/value_normalizer.py + 关联测试 + data_loader/entity_aggregator中的_norm引用 | -| 🗑删除 | .omo/plans/ 旧计划文(tianxiu-v4/v5/v6, globe-v6) | -| 🔧 重构 | views.py: 统一 _run_analysis_worker → _run_llm_analysis → _run_pipeline_worker | -| 🔧 修复 | settings.py: FILE_UPLOAD_MAX_MEMORY_SIZE 10MB→100MB | -| 🔧 修复 | upload.html: 添加每文件删除按钮 + removeFile() | -| 🔧 修复 | tool_registry.py: async函数中的同步ORM调用加sync_to_async包装 | -| 🔧 修复 | run_pipeline.py: 改为调用 _run_pipeline_worker | -| 🔧 替换 | gen_test_data.py: 3画像版→简单随机生成版 | -| 验证 | 120/120 测试通过, 4次端到端管道测试全部成功 | - -### v6 (2026-07-16) 已清理（不再维护 -> ⚠️ v6 引入value_normalizer 模块已被删除，_norm 列全部移除> entity_aggregator 回退到使用原始列名（0ver/0cph/cipher-suite等） -| 模块 | 变动 | 当前状态| -|------|------|---------| -| value_normalizer.py | ~~新增: hex→enum归一化~~ | 🗑已删| -| data_loader.py | ~~集成normalize_lf~~ | 🔧 恢复原始 | -| entity_aggregator.py | ~~_norm列依赖~~ | 🔧 回退原始列名 | -| gen_test_data.py | ~~3类流量画像~~ | 🔧 简单随机生| -| 特征维度 | 20→3| 特征维度保留3维），去掉_norm列后的纯原始列特征| - -## 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，识别3 03/03 04 | -| B15 | "+"字符串识别为数字 | FLOAT检测添加/前缀检查| -| B18 | 列名映射 | 使用精确^exact_name$匹配，无模糊猜测 | -| C4 | Traceback截断 | tool_registry.py移除[:200] | -| D5 | 大数据量卡顿 | 添加head参数10K降采样、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自动调参 | - -## v1.1.6 (2026-07-22) - -Cleanup + minor fixes release. - -| # | 问题 | 状态 | 描述 | -|---|------|------|------| -| 1 | schema sort fix | 修复 | 排序逻辑修改，确保最后一行被包含 | -| 2 | batch upload | 修复 | 批量上传流程加固 | -| 3 | temp dir to D: | 修复 | 临时目录移到 D: 盘避免 C: 盘空间占用 | -| 4 | update.bat wildcard fix | 修复 | 通配符匹配优化使更新更可靠 | -| 5 | cleanup test artifacts | 修复 | 删除 test CSV data, temp scripts, gen_fast.py | -| 6 | VERSION sync | 修复 | VERSION 文件已更新为 v1.1.6 | - -### Pending -- tests/ 需要更新 entity_detector 相关 -- 大文件上传存在内存泄漏需要进一步排查 - ---- - -## Operating Procedures - -1. **不要阻塞式启动后端** — Start Django backend in background (use `start /B` or threading), never block the terminal. Use `start /B runtime\python\python.exe manage.py runserver` to avoid hanging the shell. - -2. **全量测试** — After all changes, run full E2E test: generate 2000 CSVs, upload through frontend, verify complete pipeline. This validates the entire system end-to-end before considering work complete. - -3. **更新文档和Git** — After tests pass: update AGENTS.md, commit all changes, push, clean up temp files and running processes. Do not leave dirty state (orphan processes, temp files, uncommitted changes). - -4. **同步依赖** — Use `git pull` to sync latest code, then `runtime\python\python.exe -m pip install -r requirements.txt` to install any new packages. Do this before starting any new work session. - -5. **编码前缀** — Prefix ALL terminal commands with `chcp 65001` to prevent Opencode encoding errors. PowerShell/CMD encoding issues are the #1 source of inexplicable command failures. - -6. **Python UTF-8** — When running Python, always add `set PYTHONUTF8=1` before the command. This ensures consistent Unicode handling across all machines and prevents cross-machine encoding drift. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0b93184 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,100 @@ +CLAUDE.md — 天璇 (TianXuan) 系统 + +项目概览 +天璇 是一个 TLS 加密流量数据分析与实体画像系统，基于 Django + Polars + scikit-learn + Three.js 构建，支持从 CSV 导入、实体检测、聚合、聚类、特征提取到 3D 可视化的全自动离线分析流水线。 + +- 版本: v2.0.0beta +- 运行方式: 离线桌面应用，内置 Python 3.12 运行时，双击 run.bat 即可启动，无需安装任何依赖。 +- 数据存储: SQLite (WAL 模式) + 内存缓存 +- 分支策略: 后续所有改动直接提交到 main 分支，并推送到远程仓库 https://gitea.cattysteve.top/HJQ/tianxuan。 + +核心模块 +| 模块 | 功能 | +|------|------| +| analysis/data_loader.py | CSV 加载、合并、列名规范化、GeoIP 解析 | +| analysis/entity_detector.py | 基于列名关键词和唯一值比率的实体列自动检测 | +| analysis/entity_aggregator.py | 按实体分组计算流量统计、TLS特征、时间模式等 | +| analysis/tool_registry.py | 12 个 MCP 工具注册（145KB） | +| simple_analysis/ | 新增的“简单分析”模块，独立 Django App，提供上传→筛选→聚类→地图可视化一站式工作流 | +| templates/ | 传统功能页面（仪表盘、上传、手动分析、LLM分析、3D地球等） | +| data/ | 离线 GeoIP 数据库 (GeoLite2-City.mmdb、GeoLite2-ASN.mmdb)、自定义 IP 数据 geoip_data.txt | + +项目结构要点 +天璇/ +├── analysis/ # 主分析 App +├── simple_analysis/ # 简单分析 App (新增) +│ ├── views.py # API 视图 (upload, filter, cluster, edges) +│ ├── urls.py # 路由 /simple/ +│ ├── templates/simple_analysis/ +│ │ └── simple_analysis.html # 单页应用 +│ └── static/ +├── config/ +│ ├── config.yaml # 全局配置（含 API Key、参数） +│ └── loader.py +├── data/ +│ ├── GeoLite2-City.mmdb # 130MB，城市级 GeoIP +│ ├── GeoLite2-ASN.mmdb # 9.5MB，ASN 数据库 +│ └── geoip_data.txt # 补充 IP 地理位置 +├── runtime/python/ # 嵌入式 Python 3.12 运行时 +├── db.sqlite3 # 主数据库 +├── main.py / manage.py +└── run.bat + +当前开发焦点：简单分析模块 (v3) +目标：构建一个完全离线、高性能的网络流量 IP 通信社区发现与可视化工具。 +工作流（4 步）： +1. 上传与预筛选：拖拽上传 CSV，支持高级筛选器（AND/OR/NOT 树状表达式），上传时立即过滤以减少内存占用。 +2. 高级手动筛选：可视化布尔表达式编辑器，对已加载数据进一步精筛。 +3. 网络聚类：基于 IP 通信图进行社区发现： + - 提取所有唯一 :ips / :ipd 作为节点。 + - 先按 /24 子网分组，子网内部使用 HDBSCAN (haversine 距离) 二次聚类。 + - 最终每个节点（IP）获得一个 cluster_id。 +4. 地图可视化与交互： + - 离线地图：使用 Leaflet + 离线瓦片缓存（leaflet-offline），无网络时回退到本地低级别瓦片。 + - 节点按簇着色，支持 Canvas 渲染器和聚类插件优化性能。 + - 点击节点展示：IP、运营商、组织、城市、关联对端IP、host/text 等。 + - 点击边（IP 间连线）展示：通信次数、总流量、首次/末次北京时间、时间规律。 + - 导出点表/边表 CSV。 + +重要技术约定 +- 列名规范化：所有 CSV 列名通过 normalize_columns() 处理成小写+下划线格式，内部使用标准列名（如 src_ip, dst_ip, cnam 等）。 +- GeoIP：完全抛弃 CSV 中自带经纬度（:ips.latd 等），所有坐标均使用离线 GeoLite2-City.mmdb 解析。 +- 时间处理：原始时间戳/时间列统一转为北京时间 (UTC+8) 展示。 +- 内存管理：上传后的数据保存在内存缓存（_cache dict），以 session_id（12位 hex）索引，无持久化。 +- 性能要求：i7-10700 + 8GB RAM，十万级 IP 节点需在 1 分钟内完成聚类，内存占用 <2GB。 + +前端注意事项 +- 所有静态资源（Leaflet, Chart.js, Three.js 等）必须本地托管，确保离线可用。 +- 地图瓦片离线方案必须实现：在线时缓存 OSM 瓦片到 IndexedDB，离线时使用缓存或内置低级别瓦片。 +- 按钮必须防重复点击，操作栏固定在顶部，调试信息面板实时显示。 +- 需修复 Cannot set properties of null 类 DOM 操作错误。 + +API 端点 (简单分析) +| 方法 | 路径 | 作用 | +|------|------|------| +| GET | /simple/ | 主页面 | +| POST | /simple/upload/ | 上传文件 + 预设筛选 + GeoIP 解析 | +| POST | /simple/filter/advanced/ | 树状高级筛选 | +| GET | /simple/column-values/ | 列 Top 50 唯一值（供下拉菜单） | +| POST | /simple/cluster/ | 执行网络聚类 | +| GET | /simple/cluster/