实施计划：真正的 AI 数据分析 Agent

概述

本实施计划将设计转化为具体的编码任务。系统采用五阶段流水线架构，每个阶段由 AI 驱动，具有自主决策能力。实施将按照从核心数据结构到各个引擎组件，最后到集成的顺序进行。

任务列表

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

注意事项

所有任务都是必需的，确保从一开始就有完整的测试覆盖
每个任务都引用了具体的需求以便追溯
检查点确保增量验证
属性测试验证通用正确性属性
单元测试验证特定示例和边缘情况
所有属性测试应使用 hypothesis 库，最少运行 100 次迭代
每个属性测试必须包含注释标签：# Feature: true-ai-agent, Property {number}: {property_text}

实施顺序说明

阶段1（任务1-5）：搭建基础设施，实现工具系统
阶段2（任务6-9）：实现数据理解和需求理解引擎
阶段3（任务10-13）：实现分析规划和任务执行引擎
阶段4（任务14-15）：实现报告生成和错误处理
阶段5（任务16-18）：集成和主流程编排
阶段6（任务19-22）：测试数据、文档和性能优化

每个阶段都有检查点，确保在继续之前验证功能正确性。

版本: v1.0.0
日期: 2026-03-06
状态: 任务计划完成

15 KiB Raw Blame History Unescape Escape

实施计划：真正的 AI 数据分析 Agent

概述

任务列表

注意事项

实施顺序说明

15 KiB

Raw Blame History