simon
3b44f64f66
- docs: 删除 CLAUDE.md / continuation.md / english-news-plan.md 及旧版 intlnews_usage.*，
统一迁移到 docs/{README,architecture,quickstart,usage,pipeline,configuration,deployment,development,faq}.md
- README: 精简为仓库入口，指向 docs/
- configs/sources.yaml: 更新注释指向新文档
- .env.example: 修正 DashScope Embedding 端点说明
Pipeline 修复：
- dedup/llm/embedding/vectorstore/reporter: 过滤 M2 no_content / 空正文，避免污染下游与 Qdrant
- dedup/pipeline: 改为先写唯一文件再写指纹，避免崩溃导致文章永久丢失
- crawler/orchestrator: sources_crawled 改为“尝试数”，成功数 = crawled - failed
- crawler/storage: write_index_jsonl 从文章路径推断日期，修复跨天/测试路径问题
- scheduler/pipeline: STEP_TIMEOUTS 实际生效（SIGALRM）
- scheduler/reporter: emb_count 排除 index.json；日报跳过无原文事件
- vectorstore/pipeline: payload 增加 source_ids；--recreate --all 时空日期也重建 collection
- app/cli: extract/dedup/translate/embed/index/pipeline 支持 --date；embed/index 支持 --all；crawl 全源失败返回非零
- scripts: domestic_full/crawl_8g/crawl_2g/pipeline 安全加载 .env；M1 全失败不标记且最终退出码=1
142 lines
4.4 KiB
Markdown
142 lines
4.4 KiB
Markdown
# 使用手册
|
||
|
||
## 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 生成日报并入库 | 无 |
|
||
| `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
|
||
```
|
||
|
||
## 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` |
|