# 实施计划：真正的 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 **状态**: 任务计划完成