newsreport_agent_for_traffic/MAIN_USAGE_GUIDE.md

# main.py 使用指南

## 概述

`main.py` 是当前项目的主入口，负责把多个数据源的抓取、向量入库和报告生成串成统一流程。

支持数据源：

- `traffic`：赛文交通网
- `wechat`：微信公众号（高德地图）
- `baidu`：微信公众号（百度地图）
- `ccgp`：中国政府采购网
- `all`：全部数据源

支持模式：

- `crawl`
- `report`
- `topic`
- `full`

## 常用命令

### 完整流程

```bash
python main.py --mode full --sources all
```

### 仅抓取并写入向量库

```bash
python main.py --mode crawl --sources all
```

### 仅生成综合报告

```bash
python main.py --mode report
```

### 生成主题报告

```bash
python main.py --mode topic --topic "信控"
```

## 参数说明

### 通用参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--mode` | 运行模式 | `full` |
| `--sources` | 数据源选择 | `all` |
| `--topic` | 主题分析关键词，仅 `topic` 模式使用 | 空 |

### 赛文交通网参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--max-news` | 最大抓取条数 | `20` |

### 高德公众号参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--wechat-count` | 最大抓取篇数 | `30` |
| `--wechat-keyword` | 关键词过滤 | `交通` |

### 百度地图公众号参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--baidu-count` | 最大抓取篇数 | `30` |
| `--baidu-keyword` | 关键词过滤 | `交通` |

### 政府采购网参数

| 参数 | 含义 | 默认值 |
|------|------|--------|
| `--ccgp-keywords` | 关键词列表，逗号分隔 | `信控,绿波` |
| `--ccgp-count` | 每个关键词最大抓取条数 | `30` |

## 典型用法

### 只抓赛文交通网

```bash
python main.py --mode crawl --sources traffic --max-news 50
```

### 只抓高德和百度公众号

```bash
python main.py --mode crawl --sources wechat,baidu --wechat-count 20 --baidu-count 20
```

### 只抓政府采购网

```bash
python main.py --mode crawl --sources ccgp --ccgp-keywords "信控,绿波,交通管理" --ccgp-count 20
```

### 分步执行

```bash
python main.py --mode crawl --sources all
python main.py --mode report
python main.py --mode topic --topic "绿波"
```

## 实际执行逻辑

### `crawl`

1. 按所选数据源抓取原始数据
2. 原始数据保存到 `data/*.json`
3. 统一转换为 RAG 输入格式
4. 写入 `vector_db/`

### `report`

1. 从 `vector_db/` 按 `std_timestamp` 读取最近 15 天新闻元数据
2. 综合报告会按来源均衡取样，尽量确保每个来源至少纳入 5 条新闻（若该来源在时间窗口内不足 5 条，则取其全部）
3. 调用千问模型生成综合报告
4. 保存为 `data/report_summary_*.txt`

### `topic`

1. 从向量库检索主题相关片段
2. 生成专题报告
3. 保存为 `data/report_topic_*.txt`

### `full`

1. 抓取所选数据源
2. 写入向量库
3. 基于新数据生成最近 15 天综合报告

## 配置要求

### 必需

```env
QWEN_API_KEY=你的API密钥
QWEN_MODEL=qwen-max
DATA_DIR=./data
VECTOR_DB_DIR=./vector_db
```

### 可选

```env
TARGET_URL=https://www.7its.com/
WECHAT_APPID=...
WECHAT_APPSECRET=...
BAIDU_MAP_APPID=...
BAIDU_MAP_APPSECRET=...
```

说明：

- 当前公众号后台模式依赖 `WECHAT_MP_COOKIE`
- 如果未配置 `WECHAT_MP_COOKIE`，高德和百度两个公众号源都会被跳过

## 输出文件

### 原始抓取数据

- `news_*.json`
- `wechat_articles_*.json`
- `baidu_map_articles_*.json`
- `ccgp_results_*.json`
- `ccgp_probe_*.json`

### 报告文件

- `report_summary_*.txt`
- `report_topic_*.txt`

## 已更新的行为说明

以下旧说法不再准确：

- 报表输出为 `.md`
- 政府采购网只依赖搜索接口稳定返回
- 公众号数据源未配置时仍会继续请求接口