diff --git a/.kiro/hooks/code-quality-review.kiro.hook b/.kiro/hooks/code-quality-review.kiro.hook index 2dad4f5..62edc41 100644 --- a/.kiro/hooks/code-quality-review.kiro.hook +++ b/.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" } \ No newline at end of file diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 227ef56..0000000 --- a/IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -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) diff --git a/README.md b/README.md index 31e2e02..909b69b 100644 --- a/README.md +++ b/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 -cd -``` - -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 diff --git a/README_MAIN.md b/README_MAIN.md deleted file mode 100644 index 2deae7e..0000000 --- a/README_MAIN.md +++ /dev/null @@ -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。 diff --git a/analysis_output/analysis_report.md b/analysis_output/analysis_report.md deleted file mode 100644 index c3be4fb..0000000 --- a/analysis_output/analysis_report.md +++ /dev/null @@ -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重复率低,但存在个别车辆多次报修的情况。 diff --git a/bar_chart_responsible.png b/bar_chart_responsible.png deleted file mode 100644 index 7618d6d..0000000 Binary files a/bar_chart_responsible.png and /dev/null differ diff --git a/bar_chart_source.png b/bar_chart_source.png deleted file mode 100644 index a2d2814..0000000 Binary files a/bar_chart_source.png and /dev/null differ diff --git a/issue_type_bar_chart.png b/issue_type_bar_chart.png deleted file mode 100644 index 4877698..0000000 Binary files a/issue_type_bar_chart.png and /dev/null differ diff --git a/module_bar_chart.png b/module_bar_chart.png deleted file mode 100644 index 4e9f74b..0000000 Binary files a/module_bar_chart.png and /dev/null differ diff --git a/severity_pie_chart.png b/severity_pie_chart.png deleted file mode 100644 index 54b3881..0000000 Binary files a/severity_pie_chart.png and /dev/null differ diff --git a/status_pie_chart.png b/status_pie_chart.png deleted file mode 100644 index 218b3eb..0000000 Binary files a/status_pie_chart.png and /dev/null differ diff --git a/模块分布.png b/模块分布.png deleted file mode 100644 index 4e9f74b..0000000 Binary files a/模块分布.png and /dev/null differ diff --git a/车型工单数量柱状图.png b/车型工单数量柱状图.png deleted file mode 100644 index 29455b1..0000000 Binary files a/车型工单数量柱状图.png and /dev/null differ diff --git a/问题类型分布.png b/问题类型分布.png deleted file mode 100644 index 4877698..0000000 Binary files a/问题类型分布.png and /dev/null differ