12 KiB
12 KiB
真正的 AI 数据分析 Agent - 需求文档
1. 项目背景
1.1 当前问题
现有系统是"四不像"：
- 任务规划：基于模板的规则生成（固定90个任务）
- 任务执行：AI 驱动的 ReAct 模式
- 结果：规则 + AI = 不协调、不灵活
1.2 核心问题
用户的真实需求：
"我有数据，帮我分析一下" "我想了解工单的健康度" "按照这个模板分析，但要灵活调整"
系统应该做什么：
- 像人类分析师一样理解数据
- 自主决定分析什么
- 根据发现调整分析计划
- 生成有洞察力的报告
而不是：
- 机械地执行固定任务
- 死板地按模板填空
2. 用户故事
2.1 场景1：完全自主分析
作为 数据分析师
我想要 上传数据文件，让 AI 自动分析
以便 快速了解数据的关键信息
验收标准：
- AI 能识别数据类型（工单、销售、用户等）
- AI 能推断关键字段的业务含义
- AI 能自主决定分析维度
- AI 能生成合理的分析计划
- AI 能执行分析并生成报告
- 报告包含关键发现和洞察
示例：
输入：cleaned_data.csv
输出：
- 数据类型：工单数据
- 关键发现：
* 待处理工单占比50%（异常高）
* 某车型问题占比80%
* 平均处理时长超过标准2倍
- 建议：优先处理该车型的积压工单
2.2 场景2：指定分析方向
作为 业务负责人
我想要 指定分析方向（如"健康度"）
以便 获得针对性的分析结果
验收标准：
- AI 能理解"健康度"的业务含义
- AI 能将抽象概念转化为具体指标
- AI 能根据数据特征选择合适的分析方法
- AI 能生成针对性的报告
示例：
输入：
- 数据：cleaned_data.csv
- 需求："我想了解工单的健康度"
AI 理解：
- 健康度 = 关闭率 + 处理效率 + 积压情况 + 响应及时性
AI 分析：
- 关闭率：75%（中等）
- 平均处理时长：48小时（偏长）
- 积压工单：50%（严重）
- 健康度评分：60/100（需改进）
2.3 场景3：参考模板分析
作为 数据分析师
我想要 使用模板作为参考框架
以便 保持报告结构的一致性，同时保持灵活性
验收标准：
- AI 能理解模板的结构和要求
- AI 能检查数据是否满足模板要求
- 如果数据缺少某些字段，AI 能灵活调整
- AI 能按模板结构组织报告
- AI 不会因为数据不完全匹配而失败
示例：
输入：
- 数据：cleaned_data.csv
- 模板：issue_analysis.md（要求14个图表）
AI 检查：
- 模板要求"严重程度分布"，但数据中没有"严重程度"字段
- 决策：跳过该分析，在报告中说明
AI 调整：
- 执行其他13个分析
- 报告中注明："数据缺少严重程度字段，无法分析该维度"
2.4 场景4：迭代深入分析
作为 数据分析师
我想要 AI 能根据发现深入分析
以便 找到问题的根因
验收标准：
- AI 能识别异常或关键发现
- AI 能自主决定是否需要深入分析
- AI 能动态调整分析计划
- AI 能追踪问题的根因
示例：
初步分析：
- 发现：待处理工单占比50%（异常高）
AI 决策：需要深入分析
深入分析1：
- 分析待处理工单的特征
- 发现：某车型占80%
AI 决策：继续深入
深入分析2：
- 分析该车型的问题类型
- 发现：都是"远程控制"问题
AI 决策：继续深入
深入分析3：
- 分析"远程控制"问题的模块分布
- 发现：90%是"车门模块"
结论：车门模块的远程控制功能存在系统性问题
3. 功能需求
3.1 数据理解（Data Understanding）
FR-1.1 数据加载
- 系统应支持 CSV 格式数据
- 系统应自动检测编码（UTF-8, GBK等）
- 系统应处理常见的数据格式问题
FR-1.2 数据类型识别
- AI 应分析列名、数据类型、值分布
- AI 应推断数据的业务类型（工单、销售、用户等）
- AI 应识别关键字段（时间、状态、分类、数值）
FR-1.3 字段含义理解
- AI 应推断每个字段的业务含义
- AI 应识别字段之间的关系
- AI 应识别可能的分析维度
FR-1.4 数据质量评估
- AI 应检查缺失值
- AI 应检查异常值
- AI 应评估数据质量分数
3.2 需求理解（Requirement Understanding）
FR-2.1 自主需求推断
- 当用户未指定需求时，AI 应根据数据类型推断常见分析需求
- AI 应生成默认的分析目标
FR-2.2 用户需求理解
- AI 应理解用户的自然语言需求
- AI 应将抽象概念转化为具体指标
- AI 应判断数据是否支持用户需求
FR-2.3 模板理解
- AI 应解析模板结构
- AI 应理解模板要求的指标和图表
- AI 应检查数据是否满足模板要求
- AI 应在数据不满足时灵活调整
3.3 分析规划（Analysis Planning）
FR-3.1 动态任务生成
- AI 应根据数据特征和需求生成分析任务
- 任务应是动态的，不是固定的
- 任务应包含优先级和依赖关系
FR-3.2 任务优先级
- AI 应根据重要性排序任务
- 必需的分析应优先执行
- 可选的分析应后执行
FR-3.3 计划调整
- AI 应能根据中间结果调整计划
- AI 应能增加新的深入分析任务
- AI 应能跳过不适用的任务
3.4 工具集管理（Tool Management）
FR-4.1 预设工具集
- 系统应提供基础数据分析工具集
- 基础工具包括：数据查询、统计分析、可视化、数据清洗
- 工具应有标准的接口和描述
FR-4.2 动态工具调整
- AI 应根据数据特征决定需要哪些工具
- AI 应根据分析需求动态启用/禁用工具
- AI 应能识别缺少的工具并请求添加
FR-4.3 工具适配
- AI 应根据数据类型调整工具参数
- 例如：时间序列数据 → 启用趋势分析工具
- 例如：分类数据 → 启用分布分析工具
- 例如：地理数据 → 启用地图可视化工具
FR-4.4 自定义工具生成
- AI 应能根据特定需求生成临时工具
- AI 应能组合现有工具创建新功能
- 自定义工具应在分析结束后可选保留
示例：
数据特征：
- 包含时间字段（created_at, closed_at）
- 包含分类字段（status, type, model）
- 包含数值字段（duration）
AI 决策：
- 启用工具：时间序列分析、分类分布、数值统计
- 禁用工具：地理分析（无地理字段）
- 生成工具：计算处理时长（closed_at - created_at）
3.5 分析执行（Analysis Execution）
FR-5.1 ReAct 执行模式
- 每个任务应使用 ReAct 模式执行
- AI 应思考 → 行动 → 观察 → 判断
- AI 应能从错误中学习
FR-5.2 工具调用
- AI 应从可用工具集中选择合适的工具
- AI 应能组合多个工具完成复杂任务
- AI 应能处理工具调用失败的情况
FR-5.3 结果验证
- AI 应验证每个任务的结果
- AI 应识别异常结果
- AI 应决定是否需要重试或调整
FR-5.4 迭代深入
- AI 应识别关键发现
- AI 应决定是否需要深入分析
- AI 应动态增加深入分析任务
3.6 报告生成（Report Generation）
FR-6.1 关键发现提炼
- AI 应从所有结果中提炼关键发现
- AI 应识别异常和趋势
- AI 应提供洞察而不是简单罗列数据
FR-6.2 报告结构组织
- AI 应根据分析内容组织报告结构
- 如果有模板，应参考模板结构
- 如果没有模板，应生成合理的结构
FR-6.3 结论和建议
- AI 应基于分析结果得出结论
- AI 应提供可操作的建议
- AI 应说明建议的依据
FR-6.4 多格式输出
- 系统应生成 Markdown 格式报告
- 系统应支持导出为 Word 文档（可选）
- 报告应包含所有生成的图表
4. 非功能需求
4.1 性能需求
NFR-1.1 响应时间
- 数据理解阶段：< 30秒
- 分析规划阶段：< 60秒
- 单个任务执行：< 120秒
- 完整分析流程：< 30分钟（取决于数据大小和任务数量）
NFR-1.2 数据规模
- 支持最大 100MB 的 CSV 文件
- 支持最大 100万行数据
- 支持最大 100列
4.2 可靠性需求
NFR-2.1 错误处理
- AI 调用失败时应有降级策略
- 单个任务失败不应影响整体流程
- 系统应记录详细的错误日志
NFR-2.2 数据安全
- 数据应在本地处理，不上传到外部服务
- 生成的报告应保存在用户指定的目录
- 敏感信息应脱敏处理
4.3 可用性需求
NFR-3.1 易用性
- 用户只需提供数据文件即可开始分析
- 分析过程应显示进度和状态
- 错误信息应清晰易懂
NFR-3.2 可观察性
- 系统应显示 AI 的思考过程
- 系统应显示每个阶段的进度
- 系统应记录完整的执行日志
4.4 可扩展性需求
NFR-4.1 工具扩展
- 应易于添加新的分析工具
- 工具应有标准接口
- AI 应能自动发现和使用新工具
- 工具应支持热加载，无需重启系统
NFR-4.2 工具动态性
- 工具集应根据数据特征动态调整
- 工具参数应根据数据类型自适应
- 系统应支持运行时生成临时工具
NFR-4.3 模型扩展
- 应支持不同的 LLM 提供商
- 应支持本地模型和云端模型
- 应支持模型切换
5. 约束条件
5.1 技术约束
- 使用 Python 3.8+
- 使用 OpenAI 兼容的 LLM API
- 使用 pandas 进行数据处理
- 使用 matplotlib 进行可视化
5.2 业务约束
- 系统应在离线环境下工作（除 LLM 调用外）
- 系统不应依赖特定的数据格式或业务领域
- 系统应保持通用性，适用于各种数据分析场景
5.3 隐私和安全约束
数据隐私保护：
- AI 不能访问完整的原始数据内容
- AI 只能读取：
- 表头（列名）
- 数据类型信息
- 基本统计摘要（行数、列数、缺失值比例、数据类型分布）
- 工具执行后的聚合结果（如分组统计结果、图表数据）
- 所有原始数据处理必须在本地完成，不发送给 LLM
- AI 通过调用本地工具来分析数据，工具返回摘要结果而非原始数据
5.3 隐私和安全约束
数据隐私保护：
- AI 不能访问完整的原始数据内容
- AI 只能读取：
- 表头（列名）
- 数据类型信息
- 基本统计摘要（行数、列数、缺失值比例、数据类型分布）
- 工具执行后的聚合结果（如分组统计结果、图表数据）
- 所有原始数据处理必须在本地完成，不发送给 LLM
- AI 通过调用本地工具来分析数据，工具返回摘要结果而非原始数据
6. 验收标准
6.1 场景1验收
- 上传任意 CSV 文件，AI 能识别数据类型
- AI 能自主生成分析计划
- AI 能执行分析并生成报告
- 报告包含关键发现和洞察
6.2 场景2验收
- 指定"健康度"等抽象需求，AI 能理解
- AI 能生成相关指标
- AI 能执行针对性分析
- 报告聚焦于用户需求
6.3 场景3验收
- 提供模板，AI 能理解模板要求
- 数据缺少字段时，AI 能灵活调整
- 报告按模板结构组织
- 报告说明哪些分析被跳过及原因
6.4 场景4验收
- AI 能识别异常发现
- AI 能自主决定深入分析
- AI 能动态调整分析计划
- 报告包含深入分析的结果
6.5 工具动态性验收
- 系统根据数据特征自动启用相关工具
- 系统根据数据特征自动禁用无关工具
- AI 能识别需要但缺失的工具
- AI 能生成临时工具满足特定需求
- 工具参数根据数据类型自动调整
7. 成功指标
7.1 功能指标
- 数据类型识别准确率 > 90%
- 字段含义推断准确率 > 80%
- 分析计划合理性（人工评估）> 85%
- 报告质量（人工评估）> 80%
7.2 性能指标
- 完整分析流程完成率 > 95%
- AI 调用成功率 > 90%
7.3 用户满意度
- 用户认为分析结果有价值 > 80%
- 用户愿意再次使用 > 85%
- 用户推荐给他人 > 75%
版本: v3.0.0
日期: 2026-03-06
状态: 需求定义完成