vibe_data_ana/.kiro/specs/true-ai-agent/tasks.md

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