# 快速开始

## 1. 环境要求

- Python 3.11（项目支持 `>=3.11,<3.13`）
- [uv](https://docs.astral.sh/uv/) 包管理器
- Linux（推荐 Pi 4 / 8GB 内存或更高）
- 可选但推荐：Playwright 浏览器依赖、Xvfb、Privoxy/Shadowsocks（用于海外访问）

## 2. 安装依赖

```bash
# 在项目根目录执行
uv sync

# 如需开发依赖（pytest、ruff）
uv sync --extra dev
```

## 3. 配置环境变量

```bash
cp .env.example .env
```

然后编辑 `.env`，至少配置以下密钥：

| 变量 | 用途 |
|------|------|
| `DEEPSEEK_API_KEY` | M4 翻译+事件抽取、M7 日报摘要（DeepSeek） |
| `QWEN_API_KEY` 或 `DASHSCOPE_API_KEY` | Qwen LLM、M5 向量化（Embedding 复用兼容端点） |
| `DASHSCOPE_API_KEY` | M5 `text-embedding-v3` 向量化 |
| `QDRANT_URL` / `QDRANT_API_KEY` | 远程 Qdrant（可选；默认本地文件模式可留空） |
| `NEWS_DB_*` | M9 日报入库 MySQL（`NEWS_DB_PASSWORD` 必填） |

完整变量说明见 [配置说明](configuration.md)。

## 4. 验证安装

```bash
uv run en-news --help
```

能看到 `crawl / extract / dedup / translate / embed / index / search / report / pipeline / mcp-server` 即安装成功。

## 5. 首次运行

### 5.1 抓取（M1）

```bash
# 抓取全部源（8G headful + HTTP 代理，适合国内 Pi）
bash scripts/domestic_crawl_8g.sh

# 只抓取某个源
bash scripts/domestic_crawl_8g.sh reuters
```

> 如果不需要真实抓取，可先用测试数据或已有 `data/raw/` 数据跳过此步。

### 5.2 全链路管道（M2→M6 + 日报）

```bash
bash scripts/pipeline.sh
```

或使用命令行入口：

```bash
uv run en-news pipeline --skip-report   # 只跑 M2→M6，不生成日报
uv run en-news pipeline                 # M2→M6 + 日报
```

### 5.3 语义搜索

```bash
uv run en-news search "美联储 利率 决议"
```

## 6. 日常全流程

```bash
# 全流程：M1 抓取 + 管道 + 日报
bash scripts/domestic_full.sh

# 中断后继续（跳过当天已完成步骤）
bash scripts/domestic_full.sh --resume
```

## 7. 常见首个坑

- 如果没有配置 `NEWS_DB_PASSWORD`，日报（`report`）步骤会失败。`scripts/pipeline.sh` 会包含日报；若暂时不配 MySQL，请使用 `uv run en-news pipeline --skip-report` 跳过日报。
- 抓取海外站点需要代理和 Xvfb，详见 [部署与运维](deployment.md)。
- 运行前请确保已在项目根目录（所有路径都相对项目根目录）。