tianxuan/AGENTS.md

# 天璇 (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/                         # 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
runtime\python\python.exe -m pytest tests -q
```
```
92 passed  (unit tests; Django tests need entity_detector update)
```

### 跨机一致性测试
```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行24列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) | 新版(≥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: 一行简洁描述

---

## 修复计划 (2026-07-16)

| # | 问题 | 状态 | 详情 |
|---|------|------|------|
| 1 | 重启后旧数据可分析 | ✅ | SessionStore 元数据持久化到 JSON 文件(`%APPDATA%/TianXuan/.session_store.json`)，wsgi.py 启动时自动恢复 |
| 2 | Web图标所有页面 | ✅ | `<link rel="icon">` 在 base.html 中，所有页面继承 |
| 3 | 上传按钮在顶部 | ✅ | `position: sticky` |
| 4 | Traceback完整 | ✅ | 移除 views.py 4处 + run_pipeline.py 1处 `[:200]` 截断 |
| 5 | 大数据不卡顿 | ✅ | 降采样 `head=` 参数支持，手动 POST 可传 head，LLM 自动决定，clamp ≥100行 |
| 6 | 进度条 | ✅ | progress_pct 在 10/30/50/70/90/100 各阶段更新 |
| 7 | TLS 0ver hex识别 | ✅ | TLS_HEX_MAP 移至 type_classifier.py 值优先检测链，0ver列自动 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** |

## MCP 工具系统 (2026-07-19)

系统现有 **27 个 MCP 工具**，分为三层：

### 工具架构

| 层 | 数量 | 标签 | 用途 |
|---|------|------|------|
| Core | 7 | ⚡ | 执行分析，可修改数据 |
| Analysis | 5 | 🔍 | 只读深潜，安全随时调用 |
| Diagnostic | 7 | 🩺 | 排查问题 |
| 其他 | 8 | — | 数据加载/过滤/导出等 |

### 手动分析工作台

手动分析页面已改为**工作流构建器**：
- 添加/移除/重排步骤
- 每步选择工具 + 填写参数
- **保存/加载/删除**方案（存为 `.omo/plans/<name>.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 |
| 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→33维 | 特征维度保留（33维），去掉_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，识别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自动调参 |