# 项目总览

## 项目结构

```
.
├── api.py                          # FastAPI主服务（搜索、创作指导、AI分析、Agent）
├── ai_analyzer.py                  # AI分析核心模块
├── ai_agent.py                     # AI Agent智能代理模块 ⭐
├── test_ai_analysis.py             # AI功能测试脚本
├── test_agent.py                   # Agent测试脚本 ⭐
├── requirements.txt                # Python依赖包
├── .env.example                    # 环境变量示例
├── .env                           # 环境变量配置（需自行创建）
├── .gitignore                     # Git忽略文件
├── QUICKSTART.md                  # 快速开始指南
├── README_AI.md                   # AI功能详细文档
├── README_AGENT.md                # Agent功能详细文档 ⭐
├── PROJECT_OVERVIEW.md            # 本文件
│
├── prompts/                       # 提示词目录
│   ├── analyze_prompt.md         # 数据分析提示词
│   └── agent_prompt.md           # Agent系统提示词 ⭐
│
├── douyin_data_soupce/           # 数据源模块
│   ├── douyin_search_crawler.py          # 搜索爬虫
│   ├── douyin_creative_guidance_playwright.py  # 创作指导爬虫
│   ├── douyin_cookie.json                # Cookie配置
│   └── douyin_data/                      # 数据存储目录
│       ├── douyin_creative_guidance_*.json
│       └── douyin_search_*.json
│
└── douyin_data/                  # 额外数据目录
    └── *.json
```

## 核心功能

### 1. 数据抓取
- **搜索爬虫**: 根据关键词搜索抖音视频
- **创作指导爬虫**: 抓取抖音创作指导页面的热门视频

### 2. API接口
- `POST /api/search` - 搜索抖音视频
- `POST /api/creative-guidance` - 获取创作指导数据
- `POST /api/analyze` - AI分析视频数据
- `POST /api/analyze-file` - AI分析JSON文件
- `POST /api/agent` - **AI智能代理（推荐）**

### 3. AI分析
- 使用阿里云百炼大模型
- 支持自定义提示词
- 多维度数据分析（内容趋势、互动数据、创作者分析等）

### 4. AI Agent（新功能）⭐
- **自主决策**: 理解用户意图，自动选择工具
- **函数调用**: 支持多轮工具调用
- **提示词驱动**: 通过修改提示词控制行为
- **工具扩展**: 轻松添加新工具

## 技术栈

- **Web框架**: FastAPI
- **爬虫**: Playwright
- **AI模型**: 阿里云百炼（DashScope）
- **数据格式**: JSON, CSV, TXT
- **环境管理**: python-dotenv

## 使用流程

### 推荐流程（使用AI Agent）⭐

```
1. 配置环境
   ├── 安装依赖: pip install -r requirements.txt
   ├── 配置Cookie: douyin_data_soupce/douyin_cookie.json
   └── 配置API Key: .env

2. 使用AI Agent（一步到位）
   ├── 方式1: API接口
   │   └── POST /api/agent
   │       └── {"query": "帮我分析一下游戏类视频的热门趋势"}
   ├── 方式2: 命令行
   │   └── python ai_agent.py --query "分析游戏类视频"
   └── 方式3: 测试脚本
       └── python test_agent.py

3. Agent自动完成
   ├── 理解用户意图
   ├── 选择工具获取数据
   ├── 分析数据
   └── 给出总结和建议
```

### 传统流程（手动控制）

```
1. 配置环境
   ├── 安装依赖: pip install -r requirements.txt
   ├── 配置Cookie: douyin_data_soupce/douyin_cookie.json
   └── 配置API Key: .env

2. 抓取数据
   ├── 方式1: API接口
   │   └── POST /api/creative-guidance
   └── 方式2: 命令行
       └── python douyin_data_soupce/douyin_creative_guidance_playwright.py

3. AI分析
   ├── 方式1: API接口
   │   ├── POST /api/analyze (直接传数据)
   │   └── POST /api/analyze-file (分析文件)
   ├── 方式2: 命令行
   │   └── python ai_analyzer.py --file xxx.json
   └── 方式3: Python代码
       └── from ai_analyzer import AIAnalyzer

4. 查看结果
   ├── API返回JSON
   ├── 命令行输出
   └── 保存到文件
```

## 配置说明

### 1. Cookie配置 (douyin_data_soupce/douyin_cookie.json)

用于抖音登录认证，格式：

```json
[
  {
    "name": "cookie_name",
    "value": "cookie_value",
    "domain": ".douyin.com",
    "path": "/"
  }
]
```

### 2. 环境变量 (.env)

```bash
# 阿里云百炼API Key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx

# 使用的模型（可选）
DASHSCOPE_MODEL=qwen-plus
```

### 3. 提示词 (prompts/analyze_prompt.md)

自定义AI分析的提示词，控制分析的维度和输出格式。

## API使用示例

### 1. 抓取游戏类创作指导

```bash
curl -X POST "http://localhost:8001/api/creative-guidance" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "游戏",
    "headless": true
  }'
```

### 2. AI分析数据

```bash
curl -X POST "http://localhost:8001/api/analyze-file" \
  -H "Content-Type: application/json" \
  -d '{
    "json_file": "douyin_data_soupce/douyin_data/douyin_creative_guidance_游戏_20260107_112545.json",
    "custom_instruction": "重点分析爆款视频特征"
  }'
```

## 命令行使用示例

### 1. 抓取数据

```bash
# 抓取游戏分类
python douyin_data_soupce/douyin_creative_guidance_playwright.py \
  --category 游戏 \
  --cookie douyin_data_soupce/douyin_cookie.json

# 手动模式（需要手动登录）
python douyin_data_soupce/douyin_creative_guidance_playwright.py \
  --category 游戏 \
  --manual
```

### 2. AI分析

```bash
# 分析JSON文件
python ai_analyzer.py \
  --file douyin_data_soupce/douyin_data/douyin_creative_guidance_游戏_20260107_112545.json

# 使用自定义提示词
python ai_analyzer.py \
  --file xxx.json \
  --prompt prompts/analyze_prompt.md \
  --instruction "重点分析互动率"

# 保存结果
python ai_analyzer.py \
  --file xxx.json \
  --output analysis_result.txt
```

## 数据格式

### 视频数据结构

```json
{
  "page_url": "https://...",
  "category": "游戏",
  "crawl_time": "2026-01-07T11:25:45",
  "total_videos": 50,
  "videos": [
    {
      "index": 1,
      "author": "作者名",
      "description": "视频描述",
      "authorLink": "作者链接",
      "duration": "03:25",
      "hot": "98.5万",
      "plays": "150万",
      "likes": "8.5万",
      "comments": "3200",
      "hotWords": ["热词1", "热词2"],
      "hashTags": ["#标签1", "#标签2"]
    }
  ]
}
```

### AI分析结果结构

```json
{
  "success": true,
  "analysis": "分析结果文本...",
  "model": "qwen-plus",
  "video_count": 50,
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 1500,
    "total_tokens": 6500
  }
}
```

## 支持的分类

- 全部
- 美食
- 旅行
- 泛生活
- 汽车
- 科技
- 游戏
- 二次元

## 支持的AI模型

- `qwen-turbo` - 快速响应
- `qwen-plus` - 平衡性能（推荐）
- `qwen-max` - 最强性能
- `qwen-long` - 超长文本

## 注意事项

1. **Cookie有效期**: Cookie会过期，需要定期更新
2. **API限流**: 注意抖音和阿里云的API调用频率限制
3. **Token消耗**: AI分析会消耗Token，注意成本控制
4. **数据隐私**: 敏感数据请谨慎使用云端API
5. **浏览器依赖**: 首次使用需要安装Playwright浏览器

## 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 安装Playwright浏览器
playwright install chromium

# 3. 配置环境
cp .env.example .env
# 编辑 .env 填入API Key

# 4. 测试AI功能
python test_ai_analysis.py

# 5. 启动API服务
python api.py
```

## 文档索引

- [快速开始](QUICKSTART.md) - 5分钟上手指南
- [AI功能详解](README_AI.md) - AI分析功能完整文档
- [AI Agent详解](README_AGENT.md) - AI智能代理完整文档 ⭐
- [API文档](http://localhost:8001/docs) - 启动服务后访问

## 获取帮助

- 查看命令行帮助: `python ai_analyzer.py --help`
- 查看API文档: 启动服务后访问 `/docs`
- 测试功能: `python test_ai_analysis.py`