459 lines
15 KiB
Markdown
459 lines
15 KiB
Markdown
# 实施计划：真正的 AI 数据分析 Agent
|
||
|
||
## 概述
|
||
|
||
本实施计划将设计转化为具体的编码任务。系统采用五阶段流水线架构，每个阶段由 AI 驱动，具有自主决策能力。实施将按照从核心数据结构到各个引擎组件，最后到集成的顺序进行。
|
||
|
||
## 任务列表
|
||
|
||
- [x] 1. 搭建项目结构和核心数据模型
|
||
- 创建项目目录结构（src/models, src/engines, src/tools, tests）
|
||
- 定义核心数据类（DataProfile, ColumnInfo, RequirementSpec, AnalysisObjective, AnalysisPlan, AnalysisTask, AnalysisResult）
|
||
- 实现数据类的序列化和反序列化方法
|
||
- 设置测试框架（pytest, hypothesis）
|
||
- _需求：FR-1.1, FR-1.2_
|
||
|
||
- [x] 2. 实现数据访问层和隐私保护机制
|
||
- [x] 2.1 实现 DataAccessLayer 类
|
||
- 实现数据加载功能（支持多种编码）
|
||
- 实现数据画像生成（不暴露原始数据）
|
||
- 实现结果过滤机制（sanitize_result）
|
||
- _需求：约束条件5.3_
|
||
|
||
- [x] 2.2 编写属性测试：数据访问限制
|
||
- **属性 18：数据访问限制**
|
||
- **验证需求：约束条件5.3**
|
||
|
||
- [x] 2.3 编写单元测试
|
||
- 测试多种编码的数据加载
|
||
- 测试空文件和格式错误的处理
|
||
- 测试结果过滤功能
|
||
|
||
|
||
- [x] 3. 实现工具系统基础设施
|
||
- [x] 3.1 定义工具接口（AnalysisTool 抽象类）
|
||
- 定义标准接口（name, description, parameters, execute, is_applicable）
|
||
- 实现工具注册机制
|
||
- _需求：FR-4.1_
|
||
|
||
- [x] 3.2 实现基础数据查询工具
|
||
- 实现 get_column_distribution 工具
|
||
- 实现 get_value_counts 工具
|
||
- 实现 get_time_series 工具
|
||
- 实现 get_correlation 工具
|
||
- 确保所有工具返回聚合数据而非原始数据
|
||
- _需求：FR-4.1, 约束条件5.3_
|
||
|
||
- [x] 3.3 实现基础统计分析工具
|
||
- 实现 calculate_statistics 工具
|
||
- 实现 perform_groupby 工具
|
||
- 实现 detect_outliers 工具
|
||
- 实现 calculate_trend 工具
|
||
- _需求：FR-4.1_
|
||
|
||
- [x] 3.4 编写属性测试：工具接口一致性和输出过滤
|
||
- **属性 10：工具接口一致性**
|
||
- **属性 19：工具输出过滤**
|
||
- **验证需求：FR-4.1, 约束条件5.3**
|
||
|
||
- [x] 3.5 编写单元测试
|
||
- 测试每个工具的基本功能
|
||
- 测试工具参数验证
|
||
- 测试工具执行错误处理
|
||
|
||
- [x] 4. 实现可视化工具
|
||
- [x] 4.1 实现图表生成工具
|
||
- 实现 create_bar_chart 工具
|
||
- 实现 create_line_chart 工具
|
||
- 实现 create_pie_chart 工具
|
||
- 实现 create_heatmap 工具
|
||
- 实现 ai_picture 依据数据特性画图工具
|
||
|
||
- 使用 matplotlib 生成图表并保存为文件
|
||
- _需求：FR-4.1_
|
||
|
||
- [x] 4.2 编写单元测试
|
||
- 测试图表生成功能
|
||
- 测试图表文件保存
|
||
|
||
- [x] 5. 检查点 - 确保工具系统测试通过
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
|
||
- [x] 6. 实现工具管理器
|
||
- [x] 6.1 实现 ToolManager 类
|
||
- 实现工具选择逻辑（select_tools 方法）
|
||
- 根据数据特征启用/禁用工具
|
||
- 实现工具适用性判断
|
||
- _需求：FR-4.2, FR-4.3_
|
||
|
||
- [x] 6.2 实现动态工具调整策略
|
||
- 检查时间字段并启用时间序列工具
|
||
- 检查分类字段并启用分布分析工具
|
||
- 检查数值字段并启用统计工具
|
||
- 检查地理字段并启用地理工具
|
||
- _需求：FR-4.2, FR-4.3_
|
||
|
||
- [x] 6.3 编写属性测试：工具选择和适用性
|
||
- **属性 9：工具选择适配性**
|
||
- **属性 11：工具适用性判断**
|
||
- **属性 12：工具需求识别**
|
||
- **验证需求：FR-4.2, FR-4.3, 工具动态性验收.1, .2, .3**
|
||
|
||
- [x] 6.4 编写单元测试
|
||
- 测试不同数据特征的工具选择
|
||
- 测试工具适用性判断
|
||
|
||
- [x] 7. 实现数据理解引擎
|
||
- [x] 7.1 实现基础统计生成
|
||
- 实现 generate_basic_stats 函数
|
||
- 生成列信息（名称、类型、缺失率、唯一值数量）
|
||
- 生成示例值（每列最多5个）
|
||
- _需求：FR-1.2, FR-1.3_
|
||
|
||
- [x] 7.2 实现 AI 驱动的数据理解
|
||
- 实现 understand_data 函数
|
||
- 调用 LLM 推断数据类型
|
||
- 调用 LLM 识别关键字段和业务含义
|
||
- 调用 LLM 评估数据质量
|
||
- 生成 DataProfile 对象
|
||
- _需求：FR-1.2, FR-1.3, FR-1.4_
|
||
|
||
- [x] 7.3 编写属性测试：数据理解
|
||
- **属性 1：数据类型识别**
|
||
- **属性 2：数据画像完整性**
|
||
- **验证需求：场景1验收.1, FR-1.2, FR-1.3, FR-1.4**
|
||
|
||
- [x] 7.4 编写单元测试
|
||
- 测试工单数据识别
|
||
- 测试销售数据识别
|
||
- 测试数据质量评估
|
||
|
||
|
||
- [x] 8. 实现需求理解引擎
|
||
- [x] 8.1 实现用户需求解析
|
||
- 实现 understand_requirement 函数
|
||
- 调用 LLM 解析自然语言需求
|
||
- 将抽象概念转化为具体指标
|
||
- 生成 RequirementSpec 对象
|
||
- _需求：FR-2.1, FR-2.2_
|
||
|
||
- [x] 8.2 实现模板解析功能
|
||
- 实现 parse_template 函数
|
||
- 解析模板文件结构
|
||
- 提取模板要求的指标和图表
|
||
- _需求：FR-2.3_
|
||
|
||
- [x] 8.3 实现数据-需求匹配检查
|
||
- 实现 check_data_requirement_match 函数
|
||
- 检查数据是否满足需求
|
||
- 标记缺失的字段或能力
|
||
- _需求：FR-2.3_
|
||
|
||
- [x] 8.4 编写属性测试：需求理解
|
||
- **属性 3：抽象需求转化**
|
||
- **属性 4：模板解析**
|
||
- **属性 5：数据-需求匹配检查**
|
||
- **验证需求：场景2验收.1, .2, 场景3验收.1, .2, FR-2.1, FR-2.2, FR-2.3**
|
||
|
||
- [x] 8.5 编写单元测试
|
||
- 测试"健康度"需求的理解
|
||
- 测试模板解析
|
||
- 测试数据不满足需求的情况
|
||
|
||
- [x] 9. 检查点 - 确保数据和需求理解测试通过
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
- [x] 10. 实现分析规划引擎
|
||
- [x] 10.1 实现 AI 驱动的任务生成
|
||
- 实现 plan_analysis 函数
|
||
- 调用 LLM 根据数据特征和需求生成任务列表
|
||
- 为每个任务分配优先级
|
||
- 识别任务依赖关系
|
||
- 生成 AnalysisPlan 对象
|
||
- _需求：FR-3.1, FR-3.2_
|
||
|
||
- [x] 10.2 实现任务依赖验证
|
||
- 实现 validate_task_dependencies 函数
|
||
- 检查依赖关系是否形成 DAG
|
||
- 检查所有依赖的任务是否存在
|
||
- _需求：FR-3.1_
|
||
|
||
- [x] 10.3 编写属性测试：分析规划
|
||
- **属性 6：动态任务生成**
|
||
- **属性 7：任务依赖一致性**
|
||
- **验证需求：场景1验收.2, FR-3.1, FR-3.2**
|
||
|
||
- [x] 10.4 编写单元测试
|
||
- 测试任务生成
|
||
- 测试循环依赖检测
|
||
- 测试任务优先级排序
|
||
|
||
|
||
- [x] 11. 实现任务执行引擎（ReAct 模式）
|
||
- [x] 11.1 实现 ReAct 执行循环
|
||
- 实现 execute_task 函数
|
||
- 实现思考-行动-观察循环
|
||
- 调用 LLM 进行思考和决策
|
||
- 选择并调用工具
|
||
- 记录执行历史
|
||
- 实现循环终止条件（完成或达到最大迭代次数）
|
||
- _需求：FR-5.1_
|
||
|
||
- [x] 11.2 实现工具调用和结果处理
|
||
- 实现 call_tool 函数
|
||
- 根据 AI 决策选择工具
|
||
- 传递参数并执行工具
|
||
- 处理工具执行结果
|
||
- _需求：FR-5.2_
|
||
|
||
- [x] 11.3 实现洞察提炼
|
||
- 实现 extract_insights 函数
|
||
- 从执行历史中提炼关键发现
|
||
- 识别异常和趋势
|
||
- _需求：FR-5.4_
|
||
|
||
- [x] 11.4 编写属性测试：任务执行
|
||
- **属性 13：任务执行完整性**
|
||
- **属性 14：ReAct 循环终止**
|
||
- **属性 15：异常识别**
|
||
- **验证需求：场景1验收.3, 场景4验收.1, FR-5.1**
|
||
|
||
- [x] 11.5 编写单元测试
|
||
- 测试 ReAct 循环
|
||
- 测试工具选择和调用
|
||
- 测试异常数据的识别
|
||
|
||
- [x] 12. 实现动态计划调整
|
||
- [x] 12.1 实现计划调整逻辑
|
||
- 实现 adjust_plan 函数
|
||
- 分析已完成任务的结果
|
||
- 识别关键发现和异常
|
||
- 决定是否需要深入分析
|
||
- 生成新任务或调整优先级
|
||
- _需求：FR-3.3, FR-5.4_
|
||
|
||
- [x] 12.2 编写属性测试：计划调整
|
||
- **属性 8：计划动态调整**
|
||
- **验证需求：场景4验收.2, .3, FR-3.3**
|
||
|
||
- [x] 12.3 编写单元测试
|
||
- 测试发现异常后的计划调整
|
||
- 测试新任务的生成
|
||
- 测试任务跳过逻辑
|
||
|
||
- [ ] 13. 检查点 - 确保规划和执行引擎测试通过
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
|
||
- [x] 14. 实现报告生成引擎
|
||
- [x] 14.1 实现关键发现提炼
|
||
- 实现 extract_key_findings 函数
|
||
- 从所有分析结果中提炼关键发现
|
||
- 识别最重要的异常和趋势
|
||
- 排序和优先级排列
|
||
- _需求：FR-6.1_
|
||
|
||
- [x] 14.2 实现报告结构组织
|
||
- 实现 organize_report_structure 函数
|
||
- 根据分析内容组织报告结构
|
||
- 如果有模板，参考模板结构
|
||
- 如果没有模板，生成合理的结构
|
||
- _需求：FR-6.2_
|
||
|
||
- [x] 14.3 实现 AI 驱动的报告生成
|
||
- 实现 generate_report 函数
|
||
- 调用 LLM 生成报告内容
|
||
- 包含执行摘要、详细分析、结论和建议
|
||
- 嵌入图表和可视化
|
||
- 格式化为 Markdown
|
||
- _需求：FR-6.1, FR-6.2, FR-6.3_
|
||
|
||
- [x] 14.4 实现报告追溯性
|
||
- 确保报告中的所有发现都能追溯到分析结果
|
||
- 说明哪些分析被跳过及原因
|
||
- _需求：FR-6.1_
|
||
|
||
- [x] 14.5 编写属性测试：报告生成
|
||
- **属性 16：报告结构完整性**
|
||
- **属性 17：报告内容追溯性**
|
||
- **验证需求：场景3验收.3, .4, 场景4验收.4, FR-6.1, FR-6.2**
|
||
|
||
- [x] 14.6 编写单元测试
|
||
- 测试报告结构生成
|
||
- 测试模板结构遵循
|
||
- 测试跳过分析的说明
|
||
|
||
- [x] 15. 实现错误处理机制
|
||
- [x] 15.1 实现数据加载错误处理
|
||
- 实现 load_data_with_retry 函数
|
||
- 支持多种编码尝试
|
||
- 处理文件过大的情况（采样）
|
||
- 处理格式错误
|
||
- _需求：NFR-2.1_
|
||
|
||
- [x] 15.2 实现 AI 调用错误处理
|
||
- 实现 call_llm_with_fallback 函数
|
||
- 实现重试机制（指数退避）
|
||
- 实现降级策略（规则方法）
|
||
- _需求：NFR-2.1_
|
||
|
||
- [x] 15.3 实现工具执行错误处理
|
||
- 实现 execute_tool_safely 函数
|
||
- 验证工具参数
|
||
- 捕获执行异常
|
||
- 返回错误信息而不是崩溃
|
||
- _需求：NFR-2.1_
|
||
|
||
- [x] 15.4 实现任务执行错误处理
|
||
- 实现 execute_task_with_recovery 函数
|
||
- 检查依赖任务状态
|
||
- 处理依赖失败的情况
|
||
- 单个任务失败不影响整体流程
|
||
- _需求：NFR-2.1_
|
||
|
||
- [x] 15.5 编写单元测试
|
||
- 测试各种错误场景
|
||
- 测试重试机制
|
||
- 测试降级策略
|
||
- 测试错误恢复
|
||
|
||
|
||
- [x] 16. 实现主流程编排
|
||
- [x] 16.1 实现完整分析流程
|
||
- 实现 run_analysis 主函数
|
||
- 编排五个阶段的执行顺序
|
||
- 处理阶段之间的数据传递
|
||
- 实现进度显示
|
||
- _需求：所有功能需求_
|
||
|
||
- [x] 16.2 实现命令行接口
|
||
- 实现 CLI 参数解析
|
||
- 支持指定数据文件
|
||
- 支持指定用户需求
|
||
- 支持指定模板文件
|
||
- 支持指定输出目录
|
||
- _需求：NFR-3.1_
|
||
|
||
- [x] 16.3 实现日志和可观察性
|
||
- 配置日志系统
|
||
- 记录每个阶段的执行状态
|
||
- 显示 AI 的思考过程
|
||
- 记录错误和警告
|
||
- _需求：NFR-3.2_
|
||
|
||
- [x] 16.4 编写集成测试
|
||
- 测试端到端分析流程
|
||
- 测试基于模板的分析
|
||
- 测试错误恢复流程
|
||
|
||
- [x] 17. 实现配置和环境管理
|
||
- [x] 17.1 创建配置文件
|
||
- 定义 LLM API 配置
|
||
- 定义性能参数（超时、重试次数）
|
||
- 定义输出路径配置
|
||
- _需求：约束条件5.1_
|
||
|
||
- [x] 17.2 实现环境变量支持
|
||
- 支持从环境变量读取 API 密钥
|
||
- 支持配置文件覆盖
|
||
- _需求：约束条件5.1_
|
||
|
||
- [x] 17.3 编写单元测试
|
||
- 测试配置加载
|
||
- 测试环境变量读取
|
||
|
||
- [x] 18. 检查点 - 确保所有测试通过
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
|
||
- [x] 19. 创建测试数据和示例
|
||
- [x] 19.1 创建测试数据集
|
||
- 创建工单数据示例（ticket_sample.csv）
|
||
- 创建销售数据示例（sales_sample.csv）
|
||
- 创建用户数据示例（user_sample.csv）
|
||
- 创建包含异常的数据集
|
||
- _需求：验收标准_
|
||
|
||
- [x] 19.2 创建分析模板
|
||
- 创建工单分析模板（ticket_analysis.md）
|
||
- 创建问题分析模板（problem_analysis.md）
|
||
- 创建基于数据特征的分析模板（data_analysis.md）
|
||
- _需求：场景3验收_
|
||
|
||
- [x] 19.3 编写示例脚本
|
||
- 创建完全自主分析示例
|
||
- 创建指定需求分析示例
|
||
- 创建基于模板分析示例
|
||
|
||
- [x] 20. 编写文档
|
||
- [x] 20.1 编写 README
|
||
- 项目介绍
|
||
- 安装说明
|
||
- 使用示例
|
||
- 配置说明
|
||
- _需求：NFR-3.1_
|
||
|
||
- [x] 20.2 编写 API 文档
|
||
- 核心类和函数的文档字符串
|
||
- 工具接口文档
|
||
- 配置参数文档
|
||
- _需求：NFR-3.1_
|
||
|
||
- [x] 20.3 编写开发者指南
|
||
- 如何添加新工具
|
||
- 如何扩展功能
|
||
- 架构说明
|
||
- _需求：NFR-4.1_
|
||
|
||
- [x] 21. 性能优化和验证
|
||
- [x] 21.1 运行性能测试
|
||
- 测试数据理解阶段性能（< 30秒）
|
||
- 测试完整分析流程性能（< 30分钟）
|
||
- 测试大数据集处理（100万行）
|
||
- _需求：NFR-1.1, NFR-1.2_
|
||
|
||
- [x] 21.2 优化性能瓶颈
|
||
- 优化数据加载
|
||
- 优化 AI 调用（批处理、缓存）
|
||
- 优化工具执行
|
||
- _需求：NFR-1.1_
|
||
|
||
- [x] 21.3 编写性能测试
|
||
- 测试各阶段的性能指标
|
||
- 测试内存使用
|
||
|
||
- [x] 22. 最终检查点 - 完整系统验证
|
||
- 运行所有测试套件
|
||
- 验证所有验收标准
|
||
- 运行端到端示例
|
||
- 确保所有测试通过，如有问题请询问用户
|
||
|
||
|
||
## 注意事项
|
||
|
||
- 所有任务都是必需的，确保从一开始就有完整的测试覆盖
|
||
- 每个任务都引用了具体的需求以便追溯
|
||
- 检查点确保增量验证
|
||
- 属性测试验证通用正确性属性
|
||
- 单元测试验证特定示例和边缘情况
|
||
- 所有属性测试应使用 hypothesis 库，最少运行 100 次迭代
|
||
- 每个属性测试必须包含注释标签：`# Feature: true-ai-agent, Property {number}: {property_text}`
|
||
|
||
## 实施顺序说明
|
||
|
||
1. **阶段1（任务1-5）**：搭建基础设施，实现工具系统
|
||
2. **阶段2（任务6-9）**：实现数据理解和需求理解引擎
|
||
3. **阶段3（任务10-13）**：实现分析规划和任务执行引擎
|
||
4. **阶段4（任务14-15）**：实现报告生成和错误处理
|
||
5. **阶段5（任务16-18）**：集成和主流程编排
|
||
6. **阶段6（任务19-22）**：测试数据、文档和性能优化
|
||
|
||
每个阶段都有检查点，确保在继续之前验证功能正确性。
|
||
|
||
---
|
||
|
||
**版本**: v1.0.0
|
||
**日期**: 2026-03-06
|
||
**状态**: 任务计划完成
|