vibe_data_ana/examples/README.md

# 示例脚本说明

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

## 示例列表

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

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

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

**使用方法**：
```bash
# 方法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 将需求转化为具体指标
- 生成针对性的分析报告

**使用方法**：
```bash
# 方法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 理解模板结构和要求
- 数据不满足时灵活调整
- 说明跳过的分析及原因

**使用方法**：
```bash
# 方法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` - 通用数据分析模板

**适用场景**：
- 需要标准化报告格式
- 定期生成相同结构的报告
- 团队协作需要统一格式

## 组合使用

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

```bash
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/
```

## 运行所有示例

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

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

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

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

## 自定义示例

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

```python
# 修改数据文件
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`