# 天璇 (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图标所有页| | `<link rel="icon">` 在 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/<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 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.