# 使用手册

## 1. CLI 命令（`uv run en-news`）

| 命令 | 功能 | 常用参数 |
|------|------|----------|
| `crawl` | M1 抓取新闻 | `--source/-s <id>` 只抓单源；`--profile/-p` 指定 Profile |
| `extract` | M2 正文提取 | `--source/-s <id>` 只处理单源；`--date/-d` 指定日期 |
| `dedup` | M3 三层去重 | `--date/-d` 指定日期 |
| `translate` | M4 翻译+事件抽取 | `--date/-d` 指定日期 |
| `embed` | M5 向量生成 | `--date/-d` 指定日期；`--all` 处理全部日期 |
| `index` | M6 写入 Qdrant | `--recreate` 重建；`--date/-d` 指定日期；`--all` 全量回灌 |
| `search` | M6 语义检索 | 必需 query；`--top-k` 返回条数 |
| `report` | M9 生成日报并入库 | 无 |
| `sync-sources` | 把 deduped 已合并的多来源同步到 events/Qdrant/MySQL | 无 |
| `pipeline` | M2→M6（+日报） | `--skip-report` 跳过日报；`--date/-d` 指定日期 |
| `mcp-server` | M8 启动 MCP 服务 | 无 |

示例：

```bash
# 只抓取 CNBC
uv run en-news crawl --source cnbc

# 单步正文提取
uv run en-news extract

# 搜索
uv run en-news search "美联储" --top-k 5

# 重建 Qdrant collection（慎用！会清空现有向量）
uv run en-news index --recreate

# 指定历史日期处理
uv run en-news translate --date 20260801
uv run en-news embed --date 20260801
uv run en-news index --date 20260801

# 全量回灌历史向量（--recreate 搭配 --all 时只会在首个日期重建 collection）
uv run en-news index --all
uv run en-news embed --all

# 修复历史多来源：把 deduped 中已合并的 source_ids 同步到 events/Qdrant/MySQL
uv run en-news sync-sources
```

## 2. Shell 脚本

| 脚本 | 用途 |
|------|------|
| `scripts/domestic_full.sh` | 国内服务器全流程：M1 抓取 + M2→M6 管道 + 日报 |
| `scripts/domestic_full.sh --resume` | 同上，但跳过当天已完成步骤 |
| `scripts/pipeline.sh` | 仅 M2→M6 管道 + 日报 |
| `scripts/pipeline.sh --resume` | 同上，支持步骤级断点续跑 |
| `scripts/domestic_crawl_8g.sh [source]` | 8G headful + HTTP 代理抓取 M1 |
| `scripts/domestic_crawl_2g.sh [source]` | 2G headless stealth 轻量抓取 M1 |
| `scripts/cleanup_logs.sh` | 清理 14 天前日志 |
| `scripts/domestic_sync.sh [date]` | 从海外服务器同步 raw 数据（海外已停用，保留兼容） |

### 2.1 全流程示例

```bash
cd /home/pi/intlnews

# 每天定时任务可执行
bash scripts/domestic_full.sh

# 手动中断后继续
bash scripts/domestic_full.sh --resume
```

### 2.2 步骤级断点说明

步骤状态记录在 `data/run_state/{YYYYMMDD}.state`：

- 每成功一个步骤追加一行，如 `M1_crawl`、`M2_extract`、`M3_dedup`、`M4_translate`、`M5_embed`、`M6_index`、`report`。
- `--resume` 只跳过已标记步骤；失败步骤不会标记，所以会从失败处重试。
- 跨天自动失效，状态文件按天隔离。

## 3. MCP 服务（M8）

MCP 是给 Cherry Studio / Claude Code 等 Agent 客户端接入的研究工具层。

启动：

```bash
uv run en-news mcp-server
```

提供工具：

| 工具 | 功能 |
|------|------|
| `search_news` | 语义检索新闻 |
| `search_by_stock` | 按美股代码检索相关事件 |
| `search_by_sentiment` | 按情绪倾向（利好/利空/中性）过滤检索 |
| `get_today_events` | 获取当日重要投资事件 |
| `get_stats` | 获取系统统计概览 |

具体接入方式由客户端决定，通常是在 MCP 配置中指向 `uv run --directory /path/to/intlnews en-news mcp-server`。

## 4. 日报查看

日报已结构化写入 MySQL：

- 主表：`news_report`
  - `report_type = 'intl'`
  - `ai_summary` 为 AI 日报摘要
  - `stats` 为 JSON 统计快照
- 明细表：`news_event`
  - `section = 'intl'`
  - 包含标题、摘要、来源、情绪、重要度、URL

可通过 SQL 查看最新日报：

```sql
SELECT id, report_date, generated_at, ai_summary
FROM news_report
WHERE report_type = 'intl'
ORDER BY report_date DESC, generated_at DESC
LIMIT 5;
```

## 5. 日志

- 全流程日志：`logs/domestic_full_{YYYYMMDD_HHMMSS}.log`
- 管道日志：`logs/pipeline_{YYYYMMDD_HHMMSS}.log`
- 运行时也实时输出到终端。

快速查看最近日志：

```bash
tail -100 logs/pipeline_$(ls -t logs/pipeline_*.log | head -1 | sed 's#logs/##')
```

## 6. 常见操作组合

| 目标 | 命令 |
|------|------|
| 只抓取新闻 | `bash scripts/domestic_crawl_8g.sh` |
| 从已有 raw 跑全管道 | `uv run en-news pipeline --skip-report` |
| 增量补齐翻译 | `uv run en-news translate`（自动跳过已有） |
| 只生成日报 | `uv run en-news report` |
| 搜索知识库 | `uv run en-news search "关键词"` |
| 启动 MCP | `uv run en-news mcp-server` |