重构readme

.kiro/hooks/code-quality-review.kiro.hook

@@ -9,5 +9,7 @@
   "then": {
     "type": "askAgent",
     "prompt": "审核刚刚编辑的 Python 文件，检查以下代码质量问题并给出具体改进建议：\n1. 命名规范（变量、函数、类名是否符合 PEP8）\n2. 函数复杂度（是否过长或逻辑过于复杂）\n3. 错误处理（是否有适当的异常处理）\n4. 代码重复（是否有可以抽取的重复逻辑）\n5. 注释和文档字符串是否完整\n请直接指出问题所在的具体行，并给出修改建议。"
-  }
+  },
+  "workspaceFolderName": "iov_data_analysis_agent_old",
+  "shortName": "code-quality-review"
 }

IMPLEMENTATION_SUMMARY.md

@@ -1,293 +0,0 @@
-# 数据分析系统实施总结
-
-## 问题诊断与解决
-
-### 问题描述
-在运行完整数据分析时，`ToolManager.select_tools()` 返回 0 个工具，导致分析无法正常执行。
-
-### 根本原因
-```python
-# src/tools/tool_manager.py 第 18 行（修改前）
-self.registry = registry if registry else ToolRegistry()
-```
-
-`ToolManager` 在初始化时创建了一个新的空 `ToolRegistry` 实例，而工具实际上被注册到了全局注册表 `_global_registry` 中。这导致两个注册表互不相通：
-- 工具注册到 `_global_registry`
-- `ToolManager` 查询自己的空 `registry`
-- 结果：找不到任何工具
-
-### 解决方案
-```python
-# src/tools/tool_manager.py 第 18 行（修改后）
-from src.tools.base import AnalysisTool, ToolRegistry, _global_registry
-
-self.registry = registry if registry else _global_registry
-```
-
-修改 `ToolManager` 默认使用全局注册表，确保工具注册和查询使用同一个注册表实例。
-
-### 验证结果
-```
-✅ 全局注册表: 12 个工具
-✅ ToolManager 选择: 12 个工具
-✅ 工具可用性: 100%
-```
-
-## 系统架构
-
-### 核心组件
-
-#### 1. 数据访问层 (DataAccessLayer)
-- **职责**: 提供数据访问接口，隐藏原始数据
-- **隐私保护**: 只暴露元数据和聚合结果
-- **文件**: `src/data_access.py`
-
-#### 2. 工具系统 (Tool System)
-- **基础接口**: `AnalysisTool` (抽象基类)
-- **工具注册**: `ToolRegistry` (全局注册表)
-- **工具管理**: `ToolManager` (动态选择)
-- **工具类型**:
-  - 查询工具 (4个): 分布、计数、时间序列、相关性
-  - 统计工具 (4个): 统计量、分组、异常值、趋势
-  - 可视化工具 (4个): 柱状图、折线图、饼图、热力图
-
-#### 3. 分析引擎 (Analysis Engines)
-- **数据理解**: `ai_data_understanding.py` - AI 驱动的数据类型识别
-- **需求理解**: `requirement_understanding.py` - 将用户需求转换为分析目标
-- **分析规划**: `analysis_planning.py` - 生成分析任务计划
-- **任务执行**: `task_execution.py` - ReAct 模式执行任务
-- **报告生成**: `report_generation.py` - 生成分析报告
-
-#### 4. 数据模型 (Data Models)
-- **DataProfile**: 数据画像（元数据）
-- **RequirementSpec**: 需求规格
-- **AnalysisPlan**: 分析计划
-- **AnalysisResult**: 分析结果
-
-### 隐私保护机制
-
-```
-┌─────────────┐
-│   AI Agent  │ ← 只能看到元数据和聚合结果
-└──────┬──────┘
-       │
-       ↓
-┌─────────────┐
-│    Tools    │ ← 在原始数据上执行，返回聚合结果
-└──────┬──────┘
-       │
-       ↓
-┌─────────────┐
-│  Raw Data   │ ← AI 无法直接访问
-└─────────────┘
-```
-
-**保护措施**:
-1. AI 只能通过工具间接访问数据
-2. 工具只返回聚合结果，不返回原始行
-3. 结果数量限制（最多 100 个分组/数据点）
-4. 异常值最多返回 20 个样本
-
-## 配置管理
-
-### 环境变量 (.env)
-```env
-OPENAI_MODEL=mimo-v2-flash
-OPENAI_BASE_URL=https://api.xiaomimimo.com/v1
-OPENAI_API_KEY=[your-api-key]
-```
-
-### 配置读取
-所有 LLM API 调用统一从配置文件读取：
-- `src/config.py` - 配置管理
-- `src/env_loader.py` - 环境变量加载
-
-### 修改的文件
-1. `src/engines/task_execution.py`
-2. `src/engines/requirement_understanding.py`
-3. `src/engines/report_generation.py`
-4. `src/engines/plan_adjustment.py`
-5. `src/engines/analysis_planning.py`
-
-## 测试覆盖
-
-### 单元测试
-- **总数**: 328 个测试
-- **通过**: 314 个 (95.7%)
-- **失败**: 14 个 (环境问题，非功能缺陷)
-
-### 属性测试 (Property-Based Testing)
-- **框架**: Hypothesis
-- **覆盖模块**:
-  - 数据访问层
-  - 数据理解引擎
-  - 需求理解引擎
-  - 分析规划引擎
-  - 任务执行引擎
-  - 报告生成引擎
-  - 工具系统
-
-### 集成测试
-- ✅ 端到端分析流程
-- ✅ 工具注册和选择
-- ✅ 隐私保护验证
-- ✅ 配置管理验证
-
-## 性能指标
-
-### 测试数据
-- **文件**: cleaned_data.csv
-- **规模**: 84 行 × 21 列
-- **类型**: IT 服务工单
-
-### 执行时间
-| 阶段 | 耗时 | 说明 |
-|------|------|------|
-| 数据加载 | < 1s | 读取 CSV 文件 |
-| AI 数据理解 | ~5s | LLM 分析元数据 |
-| 需求理解 | ~3s | LLM 生成分析目标 |
-| 分析规划 | ~2s | LLM 生成任务计划 |
-| 任务执行 | ~51s | 执行 2 个分析任务 |
-| 报告生成 | ~2s | LLM 生成报告 |
-| **总计** | **~63s** | 完整分析流程 |
-
-### 资源使用
-- **内存**: < 500MB
-- **CPU**: 单核，低负载
-- **网络**: LLM API 调用
-
-## 工具清单
-
-### 查询工具 (Query Tools)
-1. **get_column_distribution** - 列分布统计
-2. **get_value_counts** - 值计数
-3. **get_time_series** - 时间序列数据
-4. **get_correlation** - 相关性分析
-
-### 统计工具 (Stats Tools)
-5. **calculate_statistics** - 描述性统计
-6. **perform_groupby** - 分组聚合
-7. **detect_outliers** - 异常值检测
-8. **calculate_trend** - 趋势计算
-
-### 可视化工具 (Visualization Tools)
-9. **create_bar_chart** - 柱状图
-10. **create_line_chart** - 折线图
-11. **create_pie_chart** - 饼图
-12. **create_heatmap** - 热力图
-
-## 使用指南
-
-### 运行完整分析
-```bash
-python run_analysis_en.py
-```
-
-### 验证工具注册
-```bash
-python verify_tools.py
-```
-
-### 运行测试套件
-```bash
-pytest tests/ -v
-```
-
-### 查看配置
-```bash
-python verify_config.py
-```
-
-## 输出文件
-
-### 分析报告
-```
-analysis_output/
-├── analysis_report.md    # Markdown 格式报告
-└── *.png                 # 图表文件（如有生成）
-```
-
-### 报告内容
-1. 执行摘要
-2. 数据概览
-3. 详细分析
-4. 结论与建议
-5. 任务执行附录
-
-## 系统状态
-
-### ✅ 已完成功能
-- [x] 工具注册系统
-- [x] 工具动态选择
-- [x] AI 数据理解
-- [x] 需求理解
-- [x] 分析规划
-- [x] 任务执行 (ReAct)
-- [x] 报告生成
-- [x] 隐私保护
-- [x] 配置管理
-- [x] 错误处理
-- [x] 日志记录
-- [x] 单元测试
-- [x] 属性测试
-- [x] 集成测试
-- [x] 端到端测试
-
-### 📊 质量指标
-- **测试覆盖率**: 95.7%
-- **代码质量**: 高
-- **文档完整性**: 完整
-- **隐私保护**: 有效
-- **性能**: 良好
-
-### 🚀 生产就绪
-系统已完全就绪，可以部署到生产环境：
-- ✅ 所有核心功能已实现
-- ✅ 测试覆盖率达标
-- ✅ 隐私保护机制有效
-- ✅ 配置管理规范
-- ✅ 错误处理完善
-- ✅ 文档齐全
-
-## 下一步计划
-
-### 功能增强
-1. 添加更多专业工具（地理分析、文本分析）
-2. 支持更多数据格式（Excel, JSON, SQL）
-3. 增强可视化能力（交互式图表）
-4. 支持多数据源联合分析
-
-### 性能优化
-1. 缓存机制（避免重复计算）
-2. 并行执行（多任务并行）
-3. 增量分析（只分析变化部分）
-4. 流式处理（大数据集）
-
-### 用户体验
-1. Web 界面
-2. 实时进度显示
-3. 交互式报告
-4. 自定义模板
-
-## 技术栈
-
-- **语言**: Python 3.x
-- **数据处理**: pandas, numpy
-- **统计分析**: scipy
-- **可视化**: matplotlib
-- **测试**: pytest, hypothesis
-- **LLM**: OpenAI API (mimo-v2-flash)
-- **配置**: python-dotenv
-
-## 联系信息
-
-- **项目**: AI Data Analysis Agent
-- **版本**: v1.0.0
-- **日期**: 2026-03-09
-- **状态**: 生产就绪
-
----
-
-**最后更新**: 2026-03-09 09:10:00  
-**测试环境**: Windows, Python 3.x  
-**测试数据**: cleaned_data.csv (84 rows × 21 columns)

README.md

@@ -1,436 +1,213 @@
-# AI 数据分析 Agent
+# AI-Driven Data Analysis Framework
 
-一个真正由 AI 驱动的数据分析系统，能够像人类分析师一样理解数据、自主规划分析、执行任务并生成洞察性报告。
+全自动 AI 数据分析框架。给一个 CSV 文件，AI 自主完成从数据理解到报告生成的全流程。
 
-## 特性
+## 核心理念
 
-- **AI 驱动决策**：让 AI 做决策，而不是执行预定义的规则
-- **动态适应**：根据数据特征和发现动态调整分析计划
-- **隐私保护**：AI 不读取原始数据，只通过工具获取摘要信息
-- **工具驱动**：通过动态工具集赋能 AI 的分析能力
-- **自然语言交互**：用自然语言描述需求，系统自动理解并执行
-- **模板支持**：支持使用模板作为参考框架，同时保持灵活性
+**框架只提供引擎和工具，AI 在运行时做所有决策。**
+
+- 没有硬编码的列名规则、数据类型判断或分析策略
+- AI 只能看到元数据（表头、统计摘要、样本值），永远不接触原始数据行
+- 对任意 CSV 文件自动适配，无需修改代码
+
+## 工作流程
+
+```
+CSV 文件
+  │
+  ▼
+[1] AI 数据理解 ─── AI 看元数据，推断数据类型、关键字段、质量评分
+  │
+  ▼
+[2] 需求理解 ─────── 解析自然语言需求 + 可选模板，生成分析目标
+  │
+  ▼
+[3] AI 分析规划 ──── AI 根据数据特征和工具库，生成具体任务列表
+  │
+  ▼
+[4] AI 任务执行 ──── ReAct 模式：AI 选工具 → 调用 → 观察结果 → 决定下一步
+  │
+  ▼
+[5] 报告生成 ─────── AI 生成图文结合的 Markdown 报告
+```
 
 ## 快速开始
 
-### 安装
+### 1. 安装依赖
 
-1. 克隆仓库：
-```bash
-git clone <repository-url>
-cd <repository-name>
-```
-
-2. 安装依赖：
 ```bash
 pip install -r requirements.txt
 ```
 
-3. 配置环境变量：
+### 2. 配置环境变量
 
-创建 `.env` 文件（参考 `.env.example`）：
-```bash
-cp .env.example .env
-```
+创建 `.env` 文件：
 
-编辑 `.env` 文件，设置 OpenAI API 密钥：
-```
-OPENAI_API_KEY=your_api_key_here
+```env
+OPENAI_API_KEY=your-api-key
 OPENAI_BASE_URL=https://api.openai.com/v1
 OPENAI_MODEL=gpt-4
 ```
 
-### 基本使用
+支持任何 OpenAI 兼容 API（如自定义 base_url）。
 
-#### 方式1：命令行接口
+### 3. 运行分析
 
 ```bash
-# 完全自主分析
-python -m src.cli data.csv
+# 最简用法 — AI 自动决定分析什么、怎么分析
+python run_analysis_en.py --data your_data.csv
 
 # 指定分析需求
-python -m src.cli data.csv -r "分析工单健康度"
+python run_analysis_en.py --data sales.csv --requirement "分析各产品线的销售趋势和异常"
 
-# 使用模板
-python -m src.cli data.csv -t templates/ticket_analysis.md
+# 使用报告模板
+python run_analysis_en.py --data tickets.csv --template templates/ticket_analysis.md
 
 # 指定输出目录
-python -m src.cli data.csv -o results/
-
-# 显示详细日志
-python -m src.cli data.csv -v
+python run_analysis_en.py --data data.csv --output my_output
 ```
 
-#### 方式2：Python API
+### 4. 查看结果
 
-```python
-from src.main import run_analysis
-
-# 运行分析
-result = run_analysis(
-    data_file="data.csv",
-    user_requirement="分析工单健康度",
-    output_dir="output"
-)
-
-# 检查结果
-if result['success']:
-    print(f"报告路径: {result['report_path']}")
-    print(f"执行时间: {result['elapsed_time']:.1f}秒")
-else:
-    print(f"分析失败: {result['error']}")
-```
-
-## 使用场景
-
-### 场景1：完全自主分析
-
-只需提供数据文件，AI 会自动：
-- 识别数据类型（工单、销售、用户等）
-- 推断关键字段的业务含义
-- 自主决定分析维度
-- 生成合理的分析计划
-- 执行分析并生成报告
-
-```bash
-python -m src.cli cleaned_data.csv
-```
-
-**输出示例**：
-```
-数据类型：工单数据
-关键发现：
-  * 待处理工单占比50%（异常高）
-  * 某车型问题占比80%
-  * 平均处理时长超过标准2倍
-建议：优先处理该车型的积压工单
-```
-
-### 场景2：指定分析方向
-
-用自然语言描述需求，AI 会：
-- 理解抽象概念的业务含义
-- 将其转化为具体指标
-- 根据数据特征选择合适的分析方法
-- 生成针对性的报告
-
-```bash
-python -m src.cli cleaned_data.csv -r "我想了解工单的健康度"
-```
-
-**AI 理解**：
-- 健康度 = 关闭率 + 处理效率 + 积压情况 + 响应及时性
-
-**AI 分析**：
-- 关闭率：75%（中等）
-- 平均处理时长：48小时（偏长）
-- 积压工单：50%（严重）
-- 健康度评分：60/100（需改进）
-
-### 场景3：使用模板
-
-使用模板作为参考框架，AI 会：
-- 理解模板的结构和要求
-- 检查数据是否满足模板要求
-- 如果数据缺少某些字段，灵活调整
-- 按模板结构组织报告
-
-```bash
-python -m src.cli cleaned_data.csv -t templates/ticket_analysis.md
-```
-
-### 场景4：迭代深入分析
-
-AI 能根据发现自主深入分析：
-- 识别异常或关键发现
-- 自主决定是否需要深入分析
-- 动态调整分析计划
-- 追踪问题的根因
-
-## 系统架构
-
-系统采用五阶段流水线架构，每个阶段都由 AI 驱动：
+每次运行会在输出目录下创建带时间戳的子目录：
 
 ```
-数据输入 → 数据理解 → 需求理解 → 分析规划 → 任务执行 → 报告生成
+analysis_output/
+  └── run_20260309_143025/
+        ├── analysis_report.md    ← 图文结合的分析报告
+        └── charts/
+              ├── bar_chart.png
+              ├── pie_chart.png
+              └── ...
 ```
 
-### 1. 数据理解（Data Understanding）
-- 加载和解析 CSV 文件
-- 推断数据类型和业务含义
-- 识别关键字段
-- 评估数据质量
-
-### 2. 需求理解（Requirement Understanding）
-- 解析用户的自然语言需求
-- 将抽象概念转化为具体指标
-- 解析和理解分析模板
-- 检查数据是否支持需求
-
-### 3. 分析规划（Analysis Planning）
-- 根据数据特征和需求生成任务列表
-- 确定任务优先级和依赖关系
-- 选择合适的分析方法
-- 生成初始工具配置
-
-### 4. 任务执行（Task Execution）
-- 使用 ReAct 模式（思考-行动-观察）执行任务
-- 动态选择和调用工具
-- 验证结果并处理错误
-- 根据发现动态调整计划
-
-### 5. 报告生成（Report Generation）
-- 提炼关键发现
-- 组织报告结构
-- 生成结论和建议
-- 嵌入图表和可视化
-
-## 命令行参数
+## 项目结构
 
 ```
-usage: python -m src.cli [-h] [-r REQUIREMENT] [-t TEMPLATE] [-o OUTPUT] 
-                          [-v] [--no-progress] [--version] 
-                          data_file
-
-positional arguments:
-  data_file             数据文件路径（CSV 格式）
-
-optional arguments:
-  -h, --help            显示帮助信息
-  -r, --requirement     用户需求（自然语言）
-  -t, --template        模板文件路径（Markdown 格式）
-  -o, --output          输出目录，默认为 "output"
-  -v, --verbose         显示详细日志
-  --no-progress         不显示进度条
-  --version             显示版本信息
+├── run_analysis_en.py          # 主入口（5 阶段 pipeline）
+├── src/
+│   ├── config.py               # 配置管理（环境变量 / JSON / .env）
+│   ├── data_access.py          # 数据访问层（隐私保护，AI 不可见原始数据）
+│   ├── engines/
+│   │   ├── ai_data_understanding.py   # [阶段1] AI 数据理解
+│   │   ├── requirement_understanding.py # [阶段2] 需求解析
+│   │   ├── analysis_planning.py       # [阶段3] AI 分析规划
+│   │   ├── task_execution.py          # [阶段4] ReAct 任务执行
+│   │   └── report_generation.py       # [阶段5] 报告生成
+│   ├── tools/
+│   │   ├── base.py             # 工具抽象基类 + 注册表
+│   │   ├── tool_manager.py     # 工具筛选（按数据特征过滤）
+│   │   ├── query_tools.py      # 查询工具（分布、计数、时间序列、相关性）
+│   │   ├── stats_tools.py      # 统计工具（描述统计、分组聚合、异常检测、趋势）
+│   │   └── viz_tools.py        # 可视化工具（柱状图、折线图、饼图、热力图）
+│   └── models/                 # 数据模型
+│       ├── data_profile.py     # DataProfile, ColumnInfo
+│       ├── requirement_spec.py # RequirementSpec, AnalysisObjective
+│       ├── analysis_plan.py    # AnalysisPlan, AnalysisTask
+│       └── analysis_result.py  # AnalysisResult
+├── templates/                  # 报告模板（可选）
+├── test_data/                  # 示例数据
+└── examples/                   # 使用示例
 ```
 
-## 配置说明
+## 内置工具
 
-### 环境变量配置
+框架提供 12 个分析工具，AI 在运行时自主选择和组合：
 
-在 `.env` 文件中配置以下参数：
-
-```bash
-# OpenAI API 配置
-OPENAI_API_KEY=your_api_key_here
-OPENAI_BASE_URL=https://api.openai.com/v1
-OPENAI_MODEL=gpt-4
-
-# 性能参数
-MAX_RETRIES=3
-TIMEOUT=120
-MAX_ITERATIONS=10
-
-# 输出配置
-OUTPUT_DIR=output
-LOG_LEVEL=INFO
-```
-
-### 配置文件
-
-可以创建 `config.json` 文件（参考 `config.example.json`）：
-
-```json
-{
-  "llm": {
-    "provider": "openai",
-    "model": "gpt-4",
-    "temperature": 0.7,
-    "max_tokens": 4000
-  },
-  "performance": {
-    "max_retries": 3,
-    "timeout": 120,
-    "max_iterations": 10
-  },
-  "output": {
-    "dir": "output",
-    "format": "markdown"
-  }
-}
-```
-
-## 输出文件
-
-分析完成后，输出目录包含：
-
-- `analysis_report.md` - 分析报告（Markdown 格式）
-- `analysis.log` - 执行日志
-- `*.png` - 生成的图表（如果有）
-- `data_profile.json` - 数据画像（可选）
-- `analysis_plan.json` - 分析计划（可选）
-
-## 工具系统
-
-系统提供丰富的分析工具，并根据数据特征动态调整：
-
-### 数据查询工具
-- `get_column_distribution` - 获取列的分布统计
-- `get_value_counts` - 获取值计数
-- `get_time_series` - 获取时间序列数据
-- `get_correlation` - 获取相关性分析
-
-### 统计分析工具
-- `calculate_statistics` - 计算描述性统计
-- `perform_groupby` - 执行分组聚合
-- `detect_outliers` - 检测异常值
-- `calculate_trend` - 计算趋势
-
-### 可视化工具
-- `create_bar_chart` - 创建柱状图
-- `create_line_chart` - 创建折线图
-- `create_pie_chart` - 创建饼图
-- `create_heatmap` - 创建热力图
-- `ai_picture` - AI 智能画图
+| 类别 | 工具 | 说明 |
+|------|------|------|
+| 查询 | `get_column_distribution` | 列分布统计（值计数、百分比） |
+| 查询 | `get_value_counts` | 唯一值计数 |
+| 查询 | `get_time_series` | 时间序列聚合 |
+| 查询 | `get_correlation` | 相关性矩阵 |
+| 统计 | `calculate_statistics` | 描述性统计（均值、中位数、偏度等） |
+| 统计 | `perform_groupby` | 分组聚合 |
+| 统计 | `detect_outliers` | 异常值检测（IQR / Z-score） |
+| 统计 | `calculate_trend` | 趋势分析（线性回归） |
+| 可视化 | `create_bar_chart` | 柱状图 |
+| 可视化 | `create_line_chart` | 折线图 |
+| 可视化 | `create_pie_chart` | 饼图 |
+| 可视化 | `create_heatmap` | 热力图 |
 
 ## 隐私保护
 
-系统遵循严格的隐私保护原则：
+数据访问层（`DataAccessLayer`）是核心安全边界：
 
-- **数据访问限制**：AI 不能直接访问原始数据
-- **工具驱动**：只能通过工具获取聚合结果
-- **元数据优先**：数据画像只包含元数据和统计摘要
-- **本地处理**：所有原始数据处理在本地完成，不上传到外部服务
+- AI **永远看不到**原始数据行
+- AI 只能通过工具获取**聚合结果**（统计值、分布、图表）
+- 数据画像只包含元数据：列名、数据类型、缺失率、唯一值数、样本值（最多 5 个）
+- 工具返回结果自动截断（最多 100 行），防止数据泄露
 
-## 性能指标
+## 配置
 
-- 数据理解阶段：< 30秒
-- 分析规划阶段：< 60秒
-- 单个任务执行：< 120秒
-- 完整分析流程：< 30分钟（取决于数据大小和任务数量）
-- 支持最大 100万行数据
+### 环境变量（推荐）
 
-## 故障排除
+通过 `.env` 文件或系统环境变量配置：
 
-### 问题1：找不到 OpenAI API 密钥
+```env
+# LLM 配置（必填）
+OPENAI_API_KEY=sk-xxx
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4
 
-**错误信息**：`OpenAI API key not found`
-
-**解决方案**：
-1. 确保 `.env` 文件存在
-2. 检查 `OPENAI_API_KEY` 是否正确设置
-3. 确保 `.env` 文件在项目根目录
-
-### 问题2：数据加载失败
-
-**错误信息**：`Failed to load data file`
-
-**解决方案**：
-1. 检查文件路径是否正确
-2. 确保文件是 CSV 格式
-3. 尝试使用 `-v` 参数查看详细错误信息
-4. 检查文件编码（系统会自动尝试多种编码）
-
-### 问题3：分析失败
-
-**错误信息**：`Analysis failed`
-
-**解决方案**：
-1. 检查日志文件 `output/analysis.log`
-2. 确保数据文件不为空
-3. 确保数据格式正确
-4. 检查 API 配额是否充足
-
-### 问题4：AI 调用超时
-
-**错误信息**：`LLM call timeout`
-
-**解决方案**：
-1. 增加 `TIMEOUT` 配置值
-2. 检查网络连接
-3. 尝试使用更快的模型
-
-## 开发和测试
-
-### 运行测试
-
-```bash
-# 运行所有测试
-pytest
-
-# 运行单元测试
-pytest tests/ -k "not properties"
-
-# 运行属性测试
-pytest tests/ -k "properties"
-
-# 运行集成测试
-pytest tests/test_integration.py -v
-
-# 运行特定测试
-pytest tests/test_integration.py::TestEndToEndAnalysis -v
-
-# 显示覆盖率
-pytest --cov=src --cov-report=html
+# 可选配置
+LLM_TEMPERATURE=0.7
+LLM_TIMEOUT=120
+AGENT_MAX_ROUNDS=20
+LOG_LEVEL=INFO
 ```
 
-### 项目结构
+### JSON 配置文件
 
-```
-.
-├── src/                    # 源代码
-│   ├── main.py            # 主流程编排
-│   ├── cli.py             # 命令行接口
-│   ├── config.py          # 配置管理
-│   ├── data_access.py     # 数据访问层
-│   ├── error_handling.py  # 错误处理
-│   ├── logging_config.py  # 日志配置
-│   ├── engines/           # 分析引擎
-│   │   ├── data_understanding.py
-│   │   ├── requirement_understanding.py
-│   │   ├── analysis_planning.py
-│   │   ├── task_execution.py
-│   │   ├── plan_adjustment.py
-│   │   └── report_generation.py
-│   ├── models/            # 数据模型
-│   │   ├── data_profile.py
-│   │   ├── requirement_spec.py
-│   │   ├── analysis_plan.py
-│   │   └── analysis_result.py
-│   └── tools/             # 分析工具
-│       ├── base.py
-│       ├── query_tools.py
-│       ├── stats_tools.py
-│       ├── viz_tools.py
-│       └── tool_manager.py
-├── tests/                 # 测试文件
-├── templates/             # 分析模板
-├── test_data/             # 测试数据
-├── examples/              # 示例脚本
-├── docs/                  # 文档
-├── .env.example           # 环境变量示例
-├── config.example.json    # 配置文件示例
-├── requirements.txt       # 依赖列表
-└── README.md             # 本文件
+也可以使用 `config.example.json` 作为模板创建配置文件。
+
+## 报告模板
+
+可以提供 Markdown 模板来控制报告结构。模板中的占位符会被 AI 用实际分析数据填充。
+
+参考 `templates/` 目录下的示例模板。
+
+## 扩展工具
+
+实现 `AnalysisTool` 抽象类并注册即可：
+
+```python
+from src.tools.base import AnalysisTool, register_tool
+
+class MyCustomTool(AnalysisTool):
+    @property
+    def name(self) -> str:
+        return "my_custom_tool"
+
+    @property
+    def description(self) -> str:
+        return "工具描述（AI 会看到这段文字来决定是否使用）"
+
+    @property
+    def parameters(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "column": {"type": "string", "description": "列名"}
+            },
+            "required": ["column"]
+        }
+
+    def execute(self, data, **kwargs) -> dict:
+        # 实现分析逻辑，返回聚合结果
+        return {"result": "..."}
+
+    def is_applicable(self, data_profile) -> bool:
+        return True
+
+register_tool(MyCustomTool())
 ```
 
-## 示例
+注册后，AI 会自动在规划和执行阶段发现并使用新工具。
 
-查看 `examples/` 目录获取更多示例：
+## 依赖
 
-- `autonomous_analysis.py` - 完全自主分析示例
-- `requirement_based_analysis.py` - 指定需求分析示例
-- `template_based_analysis.py` - 基于模板分析示例
-
-## 贡献
-
-欢迎贡献！请遵循以下步骤：
-
-1. Fork 项目
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 创建 Pull Request
-
-## 许可证
-
-MIT License
-
-## 联系方式
-
-如有问题或建议，请创建 Issue。
-
-## 致谢
-
-感谢所有贡献者和使用者的支持！
+- Python 3.10+
+- pandas, numpy, matplotlib, scipy, scikit-learn
+- openai（兼容任何 OpenAI API 格式的 LLM 服务）
+- python-dotenv

README_MAIN.md

@@ -1,274 +0,0 @@
-# AI 数据分析 Agent - 主流程使用指南
-
-## 概述
-
-这是一个真正由 AI 驱动的数据分析系统，能够自动理解数据、规划分析、执行任务并生成报告。
-
-## 快速开始
-
-### 1. 安装依赖
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. 配置环境变量
-
-创建 `.env` 文件并设置 OpenAI API 密钥：
-
-```
-OPENAI_API_KEY=your_api_key_here
-OPENAI_BASE_URL=https://api.openai.com/v1
-```
-
-### 3. 运行分析
-
-#### 方式1：使用命令行接口
-
-```bash
-# 完全自主分析
-python -m src.cli data.csv
-
-# 指定分析需求
-python -m src.cli data.csv -r "分析工单健康度"
-
-# 使用模板
-python -m src.cli data.csv -t template.md
-
-# 指定输出目录
-python -m src.cli data.csv -o results/
-
-# 显示详细日志
-python -m src.cli data.csv -v
-```
-
-#### 方式2：使用 Python API
-
-```python
-from src.main import run_analysis
-
-# 运行分析
-result = run_analysis(
-    data_file="data.csv",
-    user_requirement="分析工单健康度",
-    output_dir="output"
-)
-
-# 检查结果
-if result['success']:
-    print(f"报告路径: {result['report_path']}")
-    print(f"执行时间: {result['elapsed_time']:.1f}秒")
-else:
-    print(f"分析失败: {result['error']}")
-```
-
-## 系统架构
-
-系统采用五阶段流水线架构：
-
-1. **数据理解（Data Understanding）**
-   - 加载和解析 CSV 文件
-   - 推断数据类型和业务含义
-   - 评估数据质量
-
-2. **需求理解（Requirement Understanding）**
-   - 解析用户的自然语言需求
-   - 将抽象概念转化为具体指标
-   - 解析和理解分析模板
-
-3. **分析规划（Analysis Planning）**
-   - 根据数据特征和需求生成任务列表
-   - 确定任务优先级和依赖关系
-   - 选择合适的分析方法
-
-4. **任务执行（Task Execution）**
-   - 使用 ReAct 模式执行任务
-   - 动态选择和调用工具
-   - 根据发现调整分析计划
-
-5. **报告生成（Report Generation）**
-   - 提炼关键发现
-   - 组织报告结构
-   - 生成结论和建议
-
-## 命令行参数
-
-```
-usage: python -m src.cli [-h] [-r REQUIREMENT] [-t TEMPLATE] [-o OUTPUT] 
-                          [-v] [--no-progress] [--version] 
-                          data_file
-
-positional arguments:
-  data_file             数据文件路径（CSV 格式）
-
-optional arguments:
-  -h, --help            显示帮助信息
-  -r, --requirement     用户需求（自然语言）
-  -t, --template        模板文件路径（Markdown 格式）
-  -o, --output          输出目录，默认为 "output"
-  -v, --verbose         显示详细日志
-  --no-progress         不显示进度条
-  --version             显示版本信息
-```
-
-## 使用示例
-
-### 示例1：完全自主分析
-
-```bash
-python -m src.cli cleaned_data.csv
-```
-
-系统会自动：
-- 识别数据类型（工单、销售、用户等）
-- 推断关键字段的业务含义
-- 自主决定分析维度
-- 生成合理的分析计划
-- 执行分析并生成报告
-
-### 示例2：指定分析方向
-
-```bash
-python -m src.cli cleaned_data.csv -r "我想了解工单的健康度"
-```
-
-系统会：
-- 理解"健康度"的业务含义
-- 将抽象概念转化为具体指标（关闭率、处理效率、积压情况等）
-- 根据数据特征选择合适的分析方法
-- 生成针对性的报告
-
-### 示例3：使用模板
-
-```bash
-python -m src.cli cleaned_data.csv -t templates/ticket_analysis.md
-```
-
-系统会：
-- 理解模板的结构和要求
-- 检查数据是否满足模板要求
-- 如果数据缺少某些字段，灵活调整
-- 按模板结构组织报告
-
-## 输出文件
-
-分析完成后，输出目录包含：
-
-- `analysis_report.md` - 分析报告（Markdown 格式）
-- `analysis.log` - 执行日志
-- `*.png` - 生成的图表（如果有）
-
-## 日志和可观察性
-
-系统提供详细的日志记录：
-
-- **进度显示**：实时显示当前执行阶段和进度
-- **AI 思考过程**：显示 AI 的决策过程（使用 `-v` 参数）
-- **执行摘要**：显示各阶段的执行时间和状态
-- **错误追踪**：详细的错误信息和堆栈跟踪
-
-## 错误处理
-
-系统具有强大的错误处理能力：
-
-- **数据加载错误**：自动尝试多种编码和分隔符
-- **AI 调用错误**：重试机制和指数退避
-- **工具执行错误**：参数验证和异常捕获
-- **任务执行错误**：依赖检查和错误恢复
-
-## 性能指标
-
-- 数据理解阶段：< 30秒
-- 完整分析流程：< 30分钟（取决于数据大小和任务数量）
-- 支持最大 100万行数据
-
-## 隐私保护
-
-系统遵循严格的隐私保护原则：
-
-- AI 不能直接访问原始数据
-- 只能通过工具获取聚合结果
-- 数据画像只包含元数据和统计摘要
-- 所有原始数据处理在本地完成
-
-## 故障排除
-
-### 问题1：找不到 OpenAI API 密钥
-
-**解决方案**：确保 `.env` 文件存在并包含正确的 API 密钥。
-
-### 问题2：数据加载失败
-
-**解决方案**：
-- 检查文件路径是否正确
-- 确保文件是 CSV 格式
-- 尝试使用 `-v` 参数查看详细错误信息
-
-### 问题3：分析失败
-
-**解决方案**：
-- 检查日志文件 `output/analysis.log`
-- 确保数据文件不为空
-- 确保数据格式正确
-
-## 开发和测试
-
-### 运行测试
-
-```bash
-# 运行所有测试
-pytest
-
-# 运行集成测试
-pytest tests/test_integration.py -v
-
-# 运行特定测试
-pytest tests/test_integration.py::TestEndToEndAnalysis -v
-```
-
-### 代码结构
-
-```
-src/
-├── main.py              # 主流程编排
-├── cli.py               # 命令行接口
-├── logging_config.py    # 日志配置
-├── data_access.py       # 数据访问层
-├── error_handling.py    # 错误处理
-├── engines/             # 分析引擎
-│   ├── data_understanding.py
-│   ├── requirement_understanding.py
-│   ├── analysis_planning.py
-│   ├── task_execution.py
-│   ├── plan_adjustment.py
-│   └── report_generation.py
-├── models/              # 数据模型
-│   ├── data_profile.py
-│   ├── requirement_spec.py
-│   ├── analysis_plan.py
-│   └── analysis_result.py
-└── tools/               # 分析工具
-    ├── base.py
-    ├── query_tools.py
-    ├── stats_tools.py
-    ├── viz_tools.py
-    └── tool_manager.py
-```
-
-## 贡献
-
-欢迎贡献！请遵循以下步骤：
-
-1. Fork 项目
-2. 创建特性分支
-3. 提交更改
-4. 推送到分支
-5. 创建 Pull Request
-
-## 许可证
-
-MIT License
-
-## 联系方式
-
-如有问题或建议，请创建 Issue。

analysis_output/analysis_report.md

@@ -1,135 +0,0 @@
-# 工单分析报告
-
-生成时间：2026-03-09 10:10:08
-数据源：cleaned_data.csv
-
----
-
-# 工单数据分析报告
-
-## 1. 执行摘要
-
-基于对84条工单数据的全面分析，我们发现了以下关键洞察：
-
-1. **问题类型高度集中**：Remote control 问题占比高达 **66.67%**（56/84），是主要问题来源，建议优先优化相关系统。
-2. **处理效率差异显著**：平均关闭时长为 **54.77天**，但责任人间差异巨大，Vsevolod Tsoi 的平均处理时间为 **152天**，而刘康男仅为 **2天**。
-3. **车型问题聚焦**：EXEED RX（T22）以 **38个工单** 占据首位，JAECOO J7（T1EJ）以 **22个工单** 次之，这两款车型是问题高发区。
-4. **工单状态需关注**：临时关闭工单占比 **17.9%**（15/84），其平均关闭时长（**80.2天**）显著高于已关闭工单（**49.25天**）。
-5. **数据质量存在异常**：关闭时长列发现 **2个异常值**（277天和237天），占数据的 **2.38%**，表明存在极端处理时间。
-
-## 2. 数据概览
-
-- **数据类型**：Ticket（工单）
-- **数据规模**：84行 × 21列
-- **数据质量分数**：88.0/100
-- **关键字段**：工单号、来源、创建日期、问题类型、问题描述、处理过程、跟踪记录、严重程度、工单状态、模块、责任人、关闭日期、车型、VIN、关闭时长(天)等
-- **分析时间范围**：2025年1月2日至2025年2月（基于创建日期）
-
-## 3. 详细分析
-
-### 3.1 工单数量与趋势分析
-
-- **总体趋势**：2025年1月工单创建总数为 **62个**，平均每天约 **2个**；2025年2月工单创建总数为 **27个**，相比1月下降约 **56%**，表明工单创建活动减少。
-- **峰值日期**：1月13日创建数量最高（**8个**），1月上旬（1月2日至1月6日）共创建 **15个** 工单，为高峰期。
-- **分布特点**：2月工单创建量整体较低且分布分散，可能与业务活动或系统稳定性相关。
-
-### 3.2 问题类型与模块分布分析
-
-- **问题类型分布**：
-  - Remote control：**56个**（**66.67%**），为主要问题来源。
-  - Network：**6个**（**7.14%**），为第二常见问题类型。
-  - Navi：**5个**（**5.95%**）。
-  - Application：**4个**（**4.76%**）。
-- **模块分布**：
-  - local O&M：**45个**（**53.57%**），问题最集中的模块。
-  - TBOX：**16个**（**19.05%**），第二大问题模块。
-- **洞察**：Remote control 问题与 local O&M 模块高度相关，建议优先排查该模块的远程控制功能。
-
-### 3.3 严重程度与状态分析
-
-- **严重程度分布**：
-  - Low：**75个**（**89.3%**）。
-  - Medium：**9个**（**10.7%**），需重点关注这9个高影响问题。
-- **工单状态分布**：
-  - 已关闭（close）：**69个**（**82.1%**）。
-  - 临时关闭（temporary close）：**15个**（**17.9%**），需优先处理。
-- **关联分析**：临时关闭工单的平均关闭时长为 **80.2天**，显著高于已关闭工单的 **49.25天**，表明临时关闭状态可能延长处理时间。
-
-### 3.4 处理效率与责任人分析
-
-- **关闭时长统计**：
-  - 平均值：**54.77天**，中位数：**41天**。
-  - 分布右偏（偏度 **1.92**），标准差 **48.19天**，表明存在长尾效应。
-- **责任人效率差异**：
-  - Vsevolod Tsoi：平均 **152天**（最高）。
-  - 刘康男：平均 **2天**（最低）。
-  - 其他责任人：Evgeniy（**62.39天**）、Kostya（**26.6天**）、Vadim（**62.39天**）。
-- **来源渠道效率**：
-  - Mail：平均 **60.35天**（最长）。
-  - Telegram channel：平均 **16.5天**（最短）。
-- **洞察**：邮件处理流程可能存在瓶颈，建议优化；责任人效率差异需通过培训或资源调配改善。
-
-### 3.5 车辆特定问题分析
-
-- **车型分布**：
-  - EXEED RX（T22）：**38个**（占比最高）。
-  - JAECOO J7（T1EJ）：**22个**。
-  - EXEED VX FL（M36T）：**17个**。
-  - CHERRY TIGGO 9 (T28)：**7个**。
-- **VIN重复情况**：
-  - LVTDD24B1RG023450 和 LVTDD24B1RG021245 各出现 **2次**，其他VIN均出现1次，表明个别车辆多次报修。
-- **洞察**：EXEED RX（T22）和 JAECOO J7（T1EJ）是问题高发车型，建议针对这些车型开展专项排查。
-
-### 3.6 异常值检测与数据质量检查
-
-- **关闭时长异常值**：
-  - 发现 **2个异常值**：277天和237天，占数据的 **2.38%**。
-  - IQR上界为 **171.88天**，异常值远超此范围。
-- **数据分布特征**：
-  - 右偏明显（偏度 **1.92**），均值高于中位数，标准差较大。
-- **建议**：需核查异常工单的处理记录，避免极端值影响分析准确性。
-
-## 4. 结论与建议
-
-### 结论
-1. 工单问题高度集中于 Remote control 和 local O&M 模块，需优先优化。
-2. 处理效率差异显著，责任人与渠道间存在明显瓶颈。
-3. 车型问题聚焦于 EXEED RX（T22）和 JAECOO J7（T1EJ），建议专项治理。
-4. 临时关闭工单处理时间较长，需加强跟踪与重新评估。
-5. 数据质量存在异常值，需进一步核查。
-
-### 可操作建议
-1. **优化 Remote control 系统**：针对占比 **66.67%** 的 Remote control 问题，开展根因分析并优化相关功能，减少工单生成。
-2. **提升处理效率**：
-   - 针对责任人效率差异，组织培训或调整资源分配，重点关注 Vsevolod Tsoi 的处理流程。
-   - 优化邮件处理流程（平均 **60.35天**），引入自动化工具或增加人力。
-3. **聚焦高发车型**：针对 EXEED RX（T22）和 JAECOO J7（T1EJ）开展专项排查，制定预防性维护计划。
-4. **处理临时关闭工单**：优先重新评估 **15个** 临时关闭工单，目标将平均关闭时长从 **80.2天** 降低至接近已关闭工单水平（**49.25天**）。
-5. **数据质量改进**：核查 **2个异常值**（277天和237天）的工单记录，确保数据准确性，并建立异常值监控机制。
-
-通过执行这些建议，可显著提升工单处理效率、减少问题复发，并优化资源分配。
-
----
-
-## 分析追溯
-
-本报告基于以下分析任务：
-
-- ✓ 工单数量与趋势分析
-  - 2025年1月工单创建总数为62个，平均每天约2个，其中1月13日创建数量最高（8个）。
-  - 2025年2月工单创建总数为27个，相比1月下降约56%，表明工单创建活动减少。
-- ✓ 严重程度与状态分析
-  - 工单严重程度分布：Low 严重程度工单占比 89.3%（75/84），Medium 严重程度工单占比 10.7%（9/84），需关注 Medium 严重程度的 9 个高影响问题。
-  - 工单状态分布：已关闭（close）工单占比 82.1%（69/84），临时关闭（temporary close）工单占比 17.9%（15/84），需优先处理 15 个临时关闭工单。
-- ✓ 问题类型与模块分布分析
-  - 问题类型中，'Remote control'占比最高，达66.67%（56/84），是主要问题来源。
-  - 模块分布中，'local O&M'占比53.57%（45/84），是问题最集中的模块。
-- ✓ 处理效率与责任人分析
-  - 平均关闭时长为54.77天，中位数为41天，分布右偏（偏度1.92），表明部分工单处理时间较长，存在效率瓶颈。
-  - 按责任人分组，Vsevolod Tsoi的平均关闭时长最高（152天），而刘康男最低（2天），显示处理效率差异显著。
-- ✓ 异常值检测与数据质量检查
-  - 关闭时长(天)列存在2个异常值（277天和237天），占总数据的2.38%，远高于IQR上界171.88天，表明数据质量存在极端值问题。
-  - 数据右偏明显（偏度1.92），均值54.77天高于中位数41天，标准差48.19天，显示关闭时长分布不均匀，多数工单关闭较快但存在长尾。
-- ✓ 车辆特定问题分析
-  - 车型工单分布显示：EXEED RX（T22）以38个工单居首，占总工单的显著比例，JAECOO J7（T1EJ）以22个工单次之，表明这两款车型是问题高发区。
-  - VIN值计数中，LVTDD24B1RG023450和LVTDD24B1RG021245各出现2次，其他VIN均出现1次，说明VIN重复率低，但存在个别车辆多次报修的情况。