vibe_data_ana/examples/README.md

示例脚本说明

本目录包含三种分析模式的示例脚本，展示了如何使用真正的 AI 数据分析 Agent。

示例列表

1. 完全自主分析 (autonomous_analysis.py)

场景：让 AI 完全自主地分析数据，无需任何人工指导。

特点：

• 无需指定分析需求
• 无需提供分析模板
• AI 自动识别数据类型
• AI 自主决定分析维度
• AI 动态生成分析计划

使用方法：

# 方法1：直接运行脚本
python examples/autonomous_analysis.py

# 方法2：使用命令行
python -m src.main --data test_data/ticket_sample.csv --output output/autonomous

适用场景：

• 快速了解新数据集
• 探索性数据分析
• 不确定分析方向时

2. 指定需求分析 (requirement_based_analysis.py)

场景：指定分析需求，让 AI 进行针对性分析。

特点：

• 支持自然语言需求描述
• AI 理解抽象概念（如"健康度"）
• AI 将需求转化为具体指标
• 生成针对性的分析报告

使用方法：

# 方法1：直接运行脚本
python examples/requirement_based_analysis.py

# 方法2：使用命令行
python -m src.main \
  --data test_data/ticket_sample.csv \
  --requirement "分析工单健康度" \
  --output output/requirement

示例需求：

• "我想了解工单的健康度"
• "分析销售趋势和区域表现"
• "识别流失风险用户"
• "找出系统性能瓶颈"

适用场景：

• 有明确分析目标
• 需要针对性洞察
• 业务问题导向的分析

3. 基于模板分析 (template_based_analysis.py)

场景：使用分析模板作为参考框架，保持报告结构一致性。

特点：

• 使用预定义的报告模板
• AI 理解模板结构和要求
• 数据不满足时灵活调整
• 说明跳过的分析及原因

使用方法：

# 方法1：直接运行脚本
python examples/template_based_analysis.py

# 方法2：使用命令行
python -m src.main \
  --data test_data/ticket_sample.csv \
  --template templates/ticket_analysis.md \
  --output output/template

可用模板：

• templates/ticket_analysis.md - 工单分析模板
• templates/problem_analysis.md - 问题分析模板
• templates/data_analysis.md - 通用数据分析模板

适用场景：

• 需要标准化报告格式
• 定期生成相同结构的报告
• 团队协作需要统一格式

组合使用

你也可以同时使用模板和需求：

python -m src.main \
  --data test_data/ticket_sample.csv \
  --template templates/ticket_analysis.md \
  --requirement "重点关注车门模块的远程控制问题" \
  --output output/combined

这样可以：

• 使用模板提供报告结构
• 使用需求指定分析重点
• AI 在模板框架下进行深入分析

测试数据

示例脚本使用 test_data/ 目录下的测试数据：

• ticket_sample.csv - 工单数据（20条记录）
• sales_sample.csv - 销售数据（25条记录）
• user_sample.csv - 用户数据（20条记录）
• anomaly_sample.csv - 包含异常的数据（25条记录）

输出结果

分析结果会保存在指定的输出目录中：

output/
├── autonomous/          # 自主分析结果
│   ├── report.md       # 分析报告
│   └── charts/         # 生成的图表
├── requirement/        # 需求分析结果
│   ├── report.md
│   └── charts/
└── template/           # 模板分析结果
    ├── report.md
    └── charts/

运行所有示例

如果你想运行所有示例，可以使用以下命令：

# 完全自主分析
python examples/autonomous_analysis.py

# 指定需求分析
python examples/requirement_based_analysis.py

# 基于模板分析
python examples/template_based_analysis.py

自定义示例

你可以修改示例脚本中的参数来测试不同的场景：

# 修改数据文件
data_file = "your_data.csv"

# 修改需求
user_requirement = "你的分析需求"

# 修改模板
template_file = "your_template.md"

# 修改输出目录
output_dir = "your_output_dir"

注意事项

1. 环境配置：确保已配置 .env 文件中的 LLM API 密钥
2. 数据格式：数据文件应为 CSV 格式，支持 UTF-8 和 GBK 编码
3. 输出目录：输出目录会自动创建，无需手动创建
4. 日志查看：运行时会显示详细的分析过程日志

故障排除

如果遇到问题，请检查：

1. Python 版本是否为 3.8+
2. 是否安装了所有依赖：pip install -r requirements.txt
3. 是否配置了 .env 文件
4. 数据文件路径是否正确
5. 是否有足够的磁盘空间保存输出

更多信息

• 查看主 README：README_MAIN.md
• 查看配置指南：docs/configuration_guide.md
• 查看需求文档：.kiro/specs/true-ai-agent/requirements.md
• 查看设计文档：.kiro/specs/true-ai-agent/design.md