intl_news/docs/usage.md

使用手册

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 服务	无

示例：

# 只抓取 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 全流程示例

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 客户端接入的研究工具层。

启动：

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 查看最新日报：

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
• 运行时也实时输出到终端。

快速查看最近日志：

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